How to create CRUD non DC1 API?

The example programs can be found in the QSAMPLES source file and they are delivered together with Aperio. CRUD operations are performed over file FILE01.

  • DSRE02 - black box program for validation incoming data and maintaining the file.

  • EXAMPLE030 getting a list of records

  • EXAMPLE031 getting one record

  • EXAMPLE032 adding new record

  • EXAMPLE033 record update

  • EXAMPLE034 record deletion

Black box program

Data structure for the parameter list for DSRE02 is based on file DSLE02. Database fields in DSLE02 (ones that correspond to fields from FILE01) should be defined with ALWNULL keyword, so the program can check if the value is passed (null indicator off).

A                                      REF(IAFFRF)       
A          R DSE02                                       
* Calling mode                                          
A            CAMD      R               REFFLD(CAMD)      
* Cal stack entry                                      
A            CSE       R               REFFLD(CSE)       
* Return info                                           
A            RETC      R               REFFLD(RETC)      
****************************************************    
*  FILE001                                              
****************************************************    
A            FLD01         10A         ALWNULL           
A            FLD02         10A         ALWNULL           
A            FLD03         10P 0       ALWNULL

*ALWNULL(USRCTL) must be specified on the H-Spec of all programs, to process or define null capable fields.

H ALWNULL(*USRCTL)
Modes to call DSRE02 program:
  • ADD
  • UPDATE
  • GET
  • DELETE
  • CLRNULLOFF Clear parameters, set null indicators for null capable fields to off
  • CLRNULLON Clear parameters, set null indicators for null capable fields to on

Depending on modes DSRE02 program returns record’s data and proper return code. Return codes:

  • ’ ’ - no errors
  • ‘NF’ - no record was found
  • ‘ER’ - errors appeared
  • ‘EV’ - errors during validation

Call stack entry parameter is used for message handling and is set in the calling program. Description of procedures used for message handling can be found here:

How to set message file in Aperio

Example:

     D messageFile     c                   'IAFMSGF'
      * Send error message
      /COPY QASWCPYPRC,IAFS0001                  Aperio
      ...
       // Initiation
       setDftMsgFile(messageFile);

How to send messages in Aperio

Example:

         monitor;
           update F01;
         on-error;
           unlock FILE01;
           sendPgmMsg(gPrE02.CSE:'M000044':'field1');
         endmon;

API programs

  1. Aperio documentation tags should be added at the beginning of the program:
      * @APIDOC_ATTR    'openCrossRef : false                       '
      * @APIDOC_ATTR    'httpMethod : GET                           '
      * @APIDOC_ATTR    'keyParams  : field1                        '
  1. First call DSRE02 with mode CLRNULLON to clear data structure and set null indicators.
         // Set fields
         gPrE02.CAMD = MODE_CLRNULLON;
         DSRE02(gPrE02);
  1. Then get the parameters and set off corresponding null indicators. If a parameter is absent in the AIP call, its null indicator remains on.
        if reqExist('params':'field1');
          gPrE02.FLD01 = reqGetValue('params':'field1');
          %nullind(gPrE02.FLD01) = *off;
          //.... ;    
        endif;
  1. Then set mode and call DSRE02 again. If any error appears, gather error messages using Aperio procedure respAddPgmMessages, else prepare response data.
        gPrE02.CAMD = MODE_GET;
        DSRE02 (gPrE02);

        if gPrE02.RETC = *blanks;  
          //Add data into response
        elseif gPrE02.RETC = 'NF';
          XPERRC = API_NOT_FOUND_ERR;
        else;
          //Add data messages into response
          XPERRC = lcl_addMessages();
        endif;

How to receive messages in Aperio

     P lcl_addMessages...
     P                 B
     D                 PI             9B 0

       monitor;

         XPERRC = respAddPgmMessages(Z1PGMN);

       on-error;
         return API_INTERNAL_ERR;
       endmon;

       return XPERRC;
  1. To implement sorting of the list of records (EXAMPLE025) add “order by” fields to the compile-time array.
     *
     * Global work fields
     *
    D apiNameToField  S             70A   DIM(999) CTDATA PERRCD(1)  

** Parameter name in API method                             Field name in file
field1                                                      FLD01
field2                                                      FLD02
field3                                                      FLD03

The details about procedures used for implementing sorting are describe in FAQ: How to implement sorting