I2Rest PCML syntax

i2Rest Server использует формат PCML как основу для описания параметров вызова программ IBM i и expose them as OpenAPI services. Формат PCML подробно описан on IBM site. PCML описание ваших RPGLE программ может быть создано вручную в любом текстовом редакторе, или сгенерировано автоматически как результат выполнения команды CRTRPGMOD (параметры PGMINFO и INFOSTMF). i2Rest Server понимает все параметры PCML синтаксиса. В дополнении к стандартным, в i2Rest Server можно применять несколько расширенных атрибутов и тегов, направленных на улучшение взаимодействия клиента с вашими API

Attributes extending PCML Data tag

Three more attributes in PCML data tag were added in order to improve response processing on server side.

trimarray

This attribute specifies the path to program, that can be used to handle array been returned in current output-capable element. It allows to exclude rows which does not contain significant information, usually these are empty lines. i2Rest Server will pass output data row to defined trimarray user exit program, which will decide wither to stop sending this array in API reply.
Example:

 <data name="CCY"    type="char"  length="3" trimarray="/qsys.lib/%libl%.lib/I2RESTT_BL.PGM"/>

Parameters passed to trimarray exit program as follows:

Parameter	Type		Description
Data	CHAR(*)	INPUT	Pointer to output data in current array row
Length	BINARY(4)	INPUT	Length of output data (comes from "length" attribute)
Trim?	CHAR(1)	OUTPUT	trimarray user exit should return Y in this field in order to stop sending array in API response

i2Rest Server installation includes sample trimarray user exit program I2RESTT_BL which can be used to trim empty array rows (field value is *blanks or *zeroes)

assert

This attribute specifies the path to program, that should be used as error checking procedure for current output-capable element. i2Rest Server will process data fields with assert exit program first, to ensure that returned data is consistent. Assert user exit can inform i2Rest Server about error in data field, in this case i2Rest Server will stop further processing of output parameters and will return error message to the client of API.
Example:

 <data name="ERMSG"       type="struct" usage="output"      struct="KSM" assert="/QSYS.LIB/%LIBL%.LIB/I2RESTA_EQ.PGM" exclude="true"/> 

Parameters passed to trimarray exit program as follows:

Parameter	Type		Description
Data	CHAR(*)	INPUT	Pointer to output data
Length	BINARY(4)	INPUT	Length of output data (comes from "length" attribute)
Error message	CHAR(1024)	OUTPUT	Text of error message. Blank value means no error in current field, in other case i2Rest Server will stop processing of output parameters and will return this error message to the client

i2Rest Server installation includes assert user exit I2RESTA_EC, which can be used to check error code fields in ERRC0100 error code format (see description)

exclude

This attribute applicable for output-capable data elements (usage="output" or usage="inputoutput"). Elements with exclude attribute will be not included into server response. Exclude attribute can be useful in processing fields with the assert attribute defined. You can omit sending error code field in API response in case of there is no error.

openapi30 tag

This tag is not about processing of remote program call like native PCML tags. It enhanced API description according to OpenAPI Specification (OAS), which allows both humans and computers to discover and understand the capabilities of the service without access to source code or documentation. An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

Tag openapi30 can be presented in different places in PCML. The structure of openapi30 tag will depend on its place and will be used to enhance different parts of resulted OpenAPI specification.

Root level openapi30 tag

At this level you can define some parts of info object and tags array

Example:

<pcml version="1.0">

   <openapi30>
      <title>My PCML based API title</title>
      <description>My PCML based API - Description</description>
      <termsOfService>http://terms.of.service</termsOfService>
      <version>1.0.0</version>
      <contact>
         <name>Name</name>
         <url>http://Name</url>
         <email>Name@name.com</email>
      </contact>
      <license>
         <name>Name</name>
         <url>http://Name</url>
      </license>
      <tags>
         <tag name="itag1">Tag1</tag>
         <tag name="itag2">Tag2</tag>
      </tags>
   </openapi30>

   <program name=...
   ...

Program level openapi30 tag

At this it is possible to enhance contents of Operation object, Request Body Object and example(s) object.

Example:

   ...
   <program name=...>
      <openapi30>
         <tags>
            <!-- This will come to paths/<your API>/post/tags array -->
            <tag>Tag1</tag>
            <tag>Tag2</tag>
         </tags>
         <operationDescription>This text will come to paths/<your API>/post/description field</operationDescription>
         <requestDescription>This text will come to paths/<your API>/post/requestBody/description field</requestDescription>
         <responseDescription>This text will come to paths/<your API>/post/responses/200/description field</responseDescription>
         <requestExamples>
            <!-- This will come to paths/<your API>/post/requestBody/content/"application/json"/examples -->
            <example name="exmalpe1" summary="Summary of example 1" description="Description of example 1">
               <![CDATA[{
                  "input": {"echo": 0},
                  "tracein": false,
                  "joblog": false,
                  "traceout": false
               }]]>
            </example>
            <example name="exmalpe2" summary="Summary of example 2" description="Description of example 2">Second Example</example>
         </requestExamples>
      </openapi30>

      <data name=  ...
      ...