View source for I2Rest PCML syntax

{{DISPLAYTITLE: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 [https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_73/rzahh/pcml.htm 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.

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

__TOC__

== Attributes extending PCML Data tag ==
Three more attributes in [Https://www.ibm.com/support/knowledgecenter/en/ssw_ibm_i_74/rzahh/pcmldttg.htm PCML data tag] were added in order to improve response processing on server side.<br>
===trimarray===
This attribute specifies the path to program, that can be used to handle array been returned in current <data> 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. <br/>
Example:
<pre> <data name="CCY"    type="char"  length="3" trimarray="/qsys.lib/%libl%.lib/I2RESTT_BL.PGM"/></pre>
Parameters passed to trimarray exit program as follows:
{| class="wikitable" style="width: 70%"
! style="width: 10%"| Parameter!! style="width: 10%"| Type !! style="width: 10%"| !! 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 <data> 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.<br/>
Example: 
<pre> <data name="ERMSG"       type="struct" usage="output"      struct="KSM" assert="/QSYS.LIB/%LIBL%.LIB/I2RESTA_EQ.PGM" exclude="true"/> </pre>
Parameters passed to trimarray exit program as follows:
{| class="wikitable" style="width: 70%"
! style="width: 10%"| Parameter!! style="width: 10%"| Type !! style="width: 10%"| !! 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 [https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_71/apiref/errorcodeformat.htm description])

===exclude===
This attribute applicable for output-capable data elements (<code>usage="output"</code> or <code>usage="inputoutput"</code>). 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 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):
<pre>http[s]://<your_i2rest_server_instance>/openapi30/<API_mount_point></pre>

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 [https://swagger.io/specification/#info-object info object] and [https://swagger.io/specification/#tagObject tags array]

Example:
<pre>
<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=...
   ...
</pre>

===Program level openapi30 tag===
At this it is possible to enhance contents of [https://swagger.io/specification/#operation-object Operation object], [https://swagger.io/specification/#request-body-object Request Body Object] and [https://swagger.io/specification/#exampleObject example(s) object].

Example:
<pre>
   ...
   <program name=...>
      <openapi30>
         <tags>
            <nowiki><!-- This will come to paths/<your API>/post/tags array --></nowiki>
            <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>
            <nowiki><!-- This will come to paths/<your API>/post/requestBody/content/"application/json"/examples --></nowiki>
            <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=  ...
      ...