How to create CRUD 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.

DSRE01 - black box program for validation incoming data and maintaining the file.
EXAMPLE025 getting a list of records
EXAMPLE026 getting one record
EXAMPLE027 adding new record
EXAMPLE028 record update
EXAMPLE029 record deletion

Message handling is performed according to : How to handle messages in Aperio (Standard DC1 method )

Black box program

Data structure for the parameter list for DSRE01 is based on file DSLE01. Database fields in DSLE01 (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(FRF)         
A          R DSE01                                      
* Calling mode                                         
A            CAMD      R               REFFLD(CAMD)     
* 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 DSRE01 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 DSRE01 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

API programs

Aperio documentation tags should be added at the beginning of the program:

      * @APIDOC_ATTR    'openCrossRef : true         '
      * @APIDOC_ATTR    'httpMethod : GET            '
      * @APIDOC_ATTR    'keyParams  : field1         '

First call DSRE01 with mode CLRNULLON to clear data structure and set null indicators.

         // Set fields
         gPrE01.CAMD = MODE_CLRNULLON;
         DSRE01(gPrE01);

Then get the parameters and set off corresponding null indicators. If a parameter is absent in the API call, its null indicator remains on.

        if reqExist('params':'field1');
          gPrE01.FLD01 = reqGetValue('params':'field1');
          %nullind(gPrE01.FLD01) = *off;
          .... ;    
        endif;

Then set mode and call DSRE01 again. If any error appears, gather error messages, else prepare response data.

        gPrE01.CAMD = MODE_GET;
        DSRE01 (gPrE01);

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

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