APIDOC - Aperio documentation tags

The Aperio reads RPG source code and tries to determine the interface to program. What are the input parameters, what is the output data etc… Most of the work is done automatically but sometimes it is needed to put some documentation tags to preciselly tell the framework how the program interface looks like. This chapter describes how Aperio reads RPG source.

Aperio tries to determine program interface mainly based on original source code. For example: respAddElement('data');tells Aperio framework that output JSON will contain “data” field. Command reqExist('params':'warehouse'); tells that program has input parameter warehouse. Similar for reqGetValue('params':'warehouse'); command. Based on commands (procedure calls) Aperio can only determine the names of input and output parameters. The second step of analysing source is the analyse of parameter and data names. Based on parameter name Aperio can look into DC1 fref files and retrieve more descriptive attributes like “length”, “label”, “scale”, “type”. Aperio uses parameter name and searches it inside fref files using alias field. In case field name do not exists in any fref alias programmer has two options.

He can provide reference field as an attribute inside source code (see bellow). By providing referenceField attribute, Aperio now can retrieve more atributes from fref (length, type, label, description).

      respAddStringField('data':'warehouseIn');
      //APIDOC_ATTR referenceField : SROM

The second solution is to manually provide all required attributes insde source code.

      respAddStringField('data':'warehouseIn');
      //APIDOC_ATTR label       : Warehouse
      //APIDOC_ATTR description : Inbound Warehouse
      //APIDOC_ATTR length      : 3
      //APIDOC_ATTR type        : text

There are some attibutes which do not exist in DC1 fref but they are related either to user interface or to interface of program. For example “mandatory” attribute it is something which is specific for this particular program. The there is only one option. Put attribute value inside source code using APIDOC tags. There are several documentation tags which can be added to the RPG source file to detail describe API.

Documentation tags can be used either in free format rpg sources

//APIDOC_ATTR label : warehouse

or positional RPG source

C* APIDOC_ATTR label : warehouse

Sometimes there is need to remove part of code together with documentation tags but because ot coding rules the old lines must remain in source. They must be marked as deleted. In this case You have to remove part of documentation tag name. See proposal bellow

////IDOC_ATTR label : warehouse

or positional RPG source

C****IDOC_ATTR label : warehouse

Tag	Purpose
APIDOC_TXT	Method text. Text which follows this tag will be added to metadata. If there are several lines of text, then all lines should start with APIDOC_TXT
APIDOC_PARM	Definition of parameter. It consists of two values divided by colon. First value it is parent parameter name.The second is the parameter name. NOTE: attributes described right after this tag will belong to parameter
APIDOC_METH	Indicates that definition of attributes which is placed right after this tag will belong to method definition.
APIDOC_ATTR	Define attributes. It consists of two values divided by colon. First value it is atribute name.The second is the attribute value. NOTE: Attribute always belong to either method definition or to parameter. If attribute is defined after parameter definitin then it belongs to parameter. If the attribute is defined after APIDOC_METH tag then it belongs to method definition

See example of ussage documentation tags.

* APIDOC_TXT   This method retrieves general metadata info.
*                                                           
* APIDOC_METH                                              
* APIDOC_ATTR    openCrossRef    : false                  
* APIDOC_ATTR    tags            : API, METADATA          
*                                                           
* APIDOC_PARM data:id                                 
* APIDOC_ATTR    description     : Metadata id  
* APIDOC_ATTR    label           : Metadata id  
* APIDOC_ATTR    length          : 10           
* APIDOC_ATTR    referenceField  : *NONE        
* APIDOC_ATTR    type            : text

This source written in positional RPG source. All the parameters and attributes is defined in the beggining of source. First line represents description of API. Then openCrossRef and tags attributes are defined on method definition level. Then one output parameter which belongd to parent data and it named id. Then all attributes (description, label, length, referenceField, type) belongs to parameter id.

// APIDOC_TXT   This method retrieves general metadata info.
//                                                           
// APIDOC_METH                                              
// APIDOC_ATTR    openCrossRef    : false                  
// APIDOC_ATTR    tags            : API, METADATA          
//                                                           
// APIDOC_PARM data:id                                 
// APIDOC_ATTR    description     : Metadata id  
// APIDOC_ATTR    label           : Metadata id  
// APIDOC_ATTR    length          : 10           
// APIDOC_ATTR    referenceField  : *NONE        
// APIDOC_ATTR    type            : text

    if reqExist('params':'picklist');                            
       R345PLNO = %DEC(reqGetVALUE('params':'picklist'):12: 0);  
 // APIDOC_ATTR    mandatory : true

This source written in free RPG source. Commands reqExist…. or reqGetValue…. determines the parameter and parent name. The attribute added by APIDOC_ATTR belongs to parameter picklist. The source code above means, the input parameter picklist is mandatory.

C       if      reqExist('params':'warehouse')                            
        EVAL    R345PLNO = reqGetVALUE('params':'warehouse)
C* APIDOC_ATTR    mandatory : true                      
C* APIDOC_ATTR    label : Shipping warehouse

This source written in positional RPG source. Commands reqExist…. or reqGetValue…. determines the parameter and parent name. The attribute added by APIDOC_ATTR belongs to parameter warehouse. The source code above means, the input parameter warehouse is mandatory and label is “Shipping warehouse”.

C       if      reqExist('params':'warehouse')                            
        EVAL    R345PLNO = reqGetVALUE('params':'warehouse)
C* APIDOC_ATTR    mandatory : true                      
C****IDOC_ATTR    label : Shipping warehouse                      
C* APIDOC_ATTR    label : Transit warehouse

The source code shows how to change APIDOC values but still keep in source the old value (track changes). Label was changed from “Shipping warehouse” to “Transit warehouse”.

    if reqExist('params':'picklist');                            
       R345PLNO = %DEC(reqGetVALUE('params':'picklist'):12: 0);  
 /////IDOC_ATTR    mandatory : true              
 // APIDOC_ATTR    mandatory : false

The source code shows how to change APIDOC values but still keep in source the old value (track changes). Mandatory was changed from true to false.

Note: In older verson of aperio (before 2.200) the documentation tags started with “@” (example @APIDOC_ATTR). Since Aperio backend version 2.200 the “@” caracter is not mandatory.

Note: Since Aperio version 2.202 it is not required to put single quotes in the beggining and end of documentation text inside documentation lines.