Difference between revisions of "I2Rest PCML syntax"

From i2Rest
Jump to: navigation, search
Line 1: Line 1:
 
{{DISPLAYTITLE:I2Rest PCML syntax}}
 
{{DISPLAYTITLE:I2Rest PCML syntax}}
 +
<span style="color:red">i2Rest Server использует формат PCML как основу для описания параметров вызова программ IBM i и expose them as OpenAPI services. Формат PCML подробно описан [https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_73/rzahh/pcml.htm on IBM site]. PCML описание ваших RPGLE программ может быть создано вручную в любом текстовом редакторе, или сгенерировано автоматически как результат выполнения команды CRTRPGMOD (параметры PGMINFO и INFOSTMF). i2Rest Server понимает все параметры PCML синтаксиса. В дополнении к стандартным, в i2Rest Server можно применять несколько расширенных атрибутов и тегов, направленных на улучшение взаимодействия клиента с вашими API</span>
  
−
== Additional PCML data tags ==
+
__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>
 
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 - specifies the path to program, that should handle array been passed in current <data> element.
+
===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/jpcmlt_bl.pgm"/></pre>
 
<pre> <data name="CCY"    type="char"  length="3" trimarray="/qsys.lib/%libl%.lib/jpcmlt_bl.pgm"/></pre>
−
jpcmlt_bl -
+
Parameters passed to trimarray exit program as follows:
−
jpcmlt_bl  parameters
+
{| class="wikitable" style="width: 70%"
−
  input:
+
! style="width: 10%"| Parameter!! style="width: 10%"| Type !! style="width: 10%"| !! Description
−
      pointer on record to be processed
+
|-
−
      record length
+
|Data|| CHAR(*) || INPUT || Pointer to output data in current array row
−
  output:
+
|-
−
      error code? 
+
|Length || BINARY(4) || INPUT || Length of output data (comes from "length" attribute)
−
 
+
|-
−
assert - specifies the path to program, that should handle some way data passed in current <data> element.
+
|Trim? || CHAR(1) || OUTPUT || trimarray user exit should return Y in this field in order to stop sending array in API response
−
<code><pre> <data name="ERMSG"       type="struct" usage="output"     struct="KSM" assert="/qsys.lib/%libl%.lib/jpcmla_eq.pgm" exclude="true"/> </pre></code>
+
|}
−
In the example above program jpcmla_eq is used to process in ERMSG element. jpcmla_eq comes in the package with i2Rest Server.
 
−
jpcmla_eq parameters
 
−
  input:
 
−
      pointer on record to be processed
 
−
      record length
 
−
  output:
 
−
      error code 
 
−
 
 
−
jpcmla_eq examines record pointer to which was passed with dirst input. If KSM or errormessage is found, jpcmla_eq returns error code and stops handling PCML tags. That prevents possible failures, which could occur if incorrect data was returned by the colled API.
 
  
−
exclude - attribute applicable for <code>usage="output"</code> or <code>usage="inputoutput"</code> elements. Elements with exclude attribute will be not included into server response.
+
===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/jpcmla_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
 +
|}
  
−
== Open Api 3.0 tag ==
+
===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.
  
−
This tag is not about processing of remote program call like native PCML tags. It contains 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.
+
== 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.
  
 
{| class="wikitable"
 
{| class="wikitable"

Revision as of 12:27, 22 May 2020

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/jpcmlt_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

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/jpcmla_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

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.

Field Name Type Description
title string The title of the application.
description string A short description of the application.
termsOfService string A URL to the Terms of Service for the API. MUST be in the format of a URL.
contact Contact Object The contact information for the exposed API.
license License Object The license information for the exposed API.
version string The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).
responseDescription string

Contact Object

Field Name Type Description
name string
url string
e-mail string

Error Response Object

Field Name Type Description
status string
code string
details string
reason string
Retrieved from "https://www.i2rest.com/index.php?title=I2Rest_PCML_syntax&oldid=804"