Invoking API Requests

Once the CLIENT process is configured and running, any NonStop application can access the associated Web service by sending the process a predefined IPM request and waiting for the response. Each IPM request contains a LightWave header which contains a 2 byte method code. The method code indicates which Web service method should be invoked by this IPM request. The remainder of the IPM consists of fields that correspond to the parameters of the selected web service method.

For example, using the following fragment from the generated DDL for the sample Employees service API, to invoke a "Get Employees" request:

Initialize the get-employees-rq structure to 0 values.
Set the GET-EMPLOYEES-RQ.LIGHTWAVE-RQ-HEADER.RQ-CODE value to RQ-GET-EMPLOYEES.
Optionally set the GET-EMPLOYEES-RQ.LIGHTWAVE-RQ-HEADER.RQ-TIMEOUT value to the number of milliseconds to wait for the request to complete.
Set any remaining application element values.
Send the IPM to the CLIENT process using the appropriate Guardian system procedure call.

To ensure compatibility with future versions of LightWave Client, the LIGHTWAVE-RQ-HEADER structure must be initialized to binary 0 before populating other values.

TEXT

DEF EMPLOYEE-API-VAL.
  02 RQ-GET-EMPLOYEES                      PIC S9(4) COMP VALUE 1.
  02 RQ-ADD-EMPLOYEE                       PIC S9(4) COMP VALUE 3.
  02 RQ-ADD-EMPLOYEE-BLOB                  PIC S9(4) COMP VALUE 6.
  02 RQ-ADD-EMP-BLOB-FILE                  PIC S9(4) COMP VALUE 7.
  02 RQ-DELETE-EMPLOYEE                    PIC S9(4) COMP VALUE 4.
  02 RQ-GET-EMPLOYEE                       PIC S9(4) COMP VALUE 2.
  02 RQ-UPDATE-EMPLOYEE                    PIC S9(4) COMP VALUE 5.
END.
 
DEF LIGHTWAVE-RQ-HEADER.
  02 RQ-CODE                             TYPE BINARY 16.
  02 RQ-VERSION                          TYPE BINARY 16 UNSIGNED.
  02 RQ-TIMEOUT                          TYPE BINARY 32 UNSIGNED.
  02 RESERVED                            PIC X(24).
END.
 
!
! Operation:    GET /employees
! Description:  Get a list of employees
! Request Code: RQ-GET-EMPLOYEES
!
DEF GET-EMPLOYEES-RQ.
  02 LIGHTWAVE-RQ-HEADER                 TYPE LIGHTWAVE-RQ-HEADER.
  02 BEGIN-AFTER                         PIC X(20).
END.

Once the CLIENT process invokes the Web service method it returns the response in an IPM. This response IPM also contains a standard CLIENT header which contains a 2 byte response code. If the response code is zero, the remainder of the IPM consists of fields that correspond to the output parameters of the Web service method. If the response code is non-zero then the application should treat the response as an error.

TEXT

DEF LIGHTWAVE-RP-HEADER.
  02 RP-CODE                             TYPE BINARY 16.
  02 HTTP-STATUS                         TYPE BINARY 16.
  02 INFO-CODE                           TYPE BINARY 16.
  02 INFO-DETAIL                         TYPE BINARY 16.
  02 RESERVED                            PIC X(24).
END.
 
DEF GET-EMPLOYEES-200-RP.
  02 LIGHTWAVE-RP-HEADER                 TYPE LIGHTWAVE-RP-HEADER.
  02 GET-EMPLOYEES-RESPONSE              TYPE GET-EMPLOYEES-RESPONSE.
END.