I2Rest PCML syntax

i2Rest Server uses the PCML format as the basis for describing call parameters for IBM i programs to expose them as OpenAPI services. PCML format described in details on IBM site. PCML description of your RPGLE programs can be created manually in any text editor, or generated automatically as a result of the CRTRPGMOD command (PGMINFO and INFOSTMF parameters). i2Rest Server has full support of the PCML syntax, and also can use several advanced attributes and tags to improve interaction between API and a client.

You have to deploy PCML description file to i2Rest Server in order to be able to call programs as an OpenAPIs

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.

Extended behavior of standard PCML Data attributes

Referenced numbers

In accordance with the PCML documentation, in the attributes "ccsid", "count", "length", "offset", "outputsize", you can specify a variable name that contains the corresponding numeric value. In a standard PCML, this variable must be of type int. In i2rest, the variable specified in the reference can be defined with any numeric type.

Date and time with no delimiters

Starting from version 6.0, new data types was implemented in PCML - date, time and timestamp. "dateseparator" and "timeseparator" attributes allow you to specify the separators used in date and time fields. i2Rest implements additional value that can be used as separators - empty string (""). With empty separators, date and time fields will be represented in parameter lists as follows:

date:

• MDY     mmddyy
• DMY     ddmmyy
• YMD     yymmdd
• JUL     yyddd
• ISO     yyyymmdd
• USA     mmddyyyy
• EUR     ddmmyyyy
• JIS     yyyymmdd
• CYMD    cyymmdd
• CMDY    cmmddyy
• CDMY    cddmmyy
• LONGJUL yyyyddd
• MY      mmyy
• YM      yymm
• MYY     mmyyyy
• YMM     yyyymm

time:

• HMS     hhmmss
• ISO     hhmmss
• USA     hhmmAM
• EUR     hhmmss
• JIS     hhmmss

openapi30 tag

This tag is not about processing of remote program call like native PCML tags. It can enhance 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.

i2Rest Server generates OpenAPI specification automatically for each deployed PCML API service. OpenAPI specification in format 3.0 is available for each PCML API at address (main and management gates):

http[s]://<your_i2rest_server_instance>/openapi30/<API_mount_point>

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="example1" summary="Summary of example 1" description="Description of example 1">
               <![CDATA[{
                  "input": {"echo": 0},
                  "tracein": false,
                  "joblog": false,
                  "traceout": false
               }]]>
            </example>
            <example name="example2" summary="Summary of example 2" description="Description of example 2">Second Example</example>
         </requestExamples>
      </openapi30>

      <data name=  ...
      ...