Adding API calls to a z/OS client application

To enable a z/OS® application (COBOL or PL/I application) to execute rulesets on IBM® Decision Server for z/OS, you must include calls to the necessary APIs.

About this task

Use the HBRA-CONN-AREA data area to pass the RuleApp path and the input parameters and to receive the outputs of the ruleset execution.

The following data set members contain the information that you need to code the API calls:

For COBOL applications:
- ++HBRHLQ++.SHBRCOBC(HBRWS) contains the HBRA-CONN-AREA data area.
- ++HBRHLQ++.SHBRCOBC(HBRC) contains the copybook for the completion codes and the reason codes.
For PL/I applications:
- ++HBRHLQ++.SHBRPLIC(HBRWSP) contains the HBRA-CONN-AREA data area.
- ++HBRHLQ++.SHBRPLIC(HBRCP) contains the include file for the completion codes and the reason codes.

The steps in the procedure include examples that are taken from the source code for the Miniloan sample application. The Miniloan application executes a set of loan eligibility rules against financial data for two borrowers. A message then states whether their loans are approved or disapproved. To view the COBOL source code for the entire application, refer to the following ++HBRHLQ++.SHBRCOBS data set members:

HBRMINB for batch applications.
HBRMINC for CICS® applications.
HBRMINI for IMS applications that run in a batch processing region or that use DL/I calls.
HBRMINIT for IMS applications that run in a message processing region.

To view the PL/I source code for the entire application, refer to the following ++HBRHLQ++.SHBRPLIS data set members: HBRMINBP for batch applications.

Procedure

Include the required z/OS data models. For example, the following code includes the reason codes from the HBRC data set member and the working storage variables from the HBRWS data set member.
- Example for COBOL:
```
01 WS-REASON-CODES.
  COPY HBRC.
  COPY HBRWS.
```
- Example for PL/I:
```
%INCLUDE HBRCP;
%INCLUDE HBRWSP;
```

Initialize the values to be passed to the IBM Decision Server for z/OS instance. For example, the following code sets the RuleApp path and the ruleset parameters for the Borrower and the Loan:

Example for COBOL:

MOVE "/MiniLoanDemoRuleApp/MiniLoanDemo" TO
    HBRA-CONN-RULEAPP-PATH
  move LENGTH OF Borrower to HBRA-RA-DATA-LENGTH(1)
  move "borrower"             to  HBRA-RA-PARAMETER-NAME(1)
  set HBRA-RA-DATA-ADDRESS(1) to address of Borrower
  move LENGTH OF Loan         to HBRA-RA-DATA-LENGTH(2)
  move "loan"                 to HBRA-RA-PARAMETER-NAME(2)
  set HBRA-RA-DATA-ADDRESS(2) to address of Loan
  move 683                    to HBRA-RA-DATA-LENGTH(2)

Note: Because Loan is a data structure of variable length, you must set its length manually.

Example for PL/I:

HBRA_CONN_RULEAPP_PATH = "/MiniLoanDemoPLIRuleApp/MiniLoanDemoPLI";
HBRA_RA_PARAMETER_NAME(1) = 'borrower';
HBRA_RA_DATA_LENGTH(1) = size(Borrower);
HBRA_RA_DATA_ADDRESS(1) = addr(Borrower);
HBRA_RA_PARAMETER_NAME(2) = 'loan';
HBRA_RA_DATA_LENGTH(2) = size(Loan);
HBRA_RA_DATA_ADDRESS(2) = addr(Loan);

Connect to an instance of IBM Decision Server for z/OS:
- Example for COBOL:
```
  call 'HBRCONN' using
    HBRA-CONN-AREA.
```
- Example for PL/I:
```
CALL HBRCONN(addr(HBRA_CONN_AREA));
```
Execute the ruleset by using the HBRA-CONN-AREA data area to specify inputs.
- Example for COBOL:
```
  call 'HBRRULE' using
    HBRA-CONN-AREA.
```
- Example for PL/I:
```
call HBRRULE(addr(HBRA_CONN_AREA));
```
If you are using a zRule Execution Server for z/OS server group member, the HBRA-CONN-SSID field returns the subsystem ID of the server that completed the execution of the ruleset. If ruleset execution cannot complete, this field is set to blanks.
If an API call executes successfully, IBM Decision Server for z/OS returns the following outputs:
- Execution results
- A completion code of HBR-CC-OK in HBRA-CONN-COMPLETION-CODE
- A reason code of HBR-RC-NONE in HBRA-CONN-REASON-CODE.
For example, in the following code zRule Execution Server for z/OS returns the status of the Loan request along with the name of the Borrower.
- Example for COBOL:
```
IF HBRA-CONN-COMPLETION-CODE = HBR-CC-OK THEN
  DISPLAY WS-PROGRAM  '-'
    '-name->' name
    ' -loan amount->' amount
    ' -approved->' approved
ELSE          
  DISPLAY WS-PROGRAM  '-'
    '-CC->' HBRA-CONN-COMPLETION-CODE
    '-RC->' HBRA-CONN-REASON-CODE
    '-MSG->' HBRA-RESPONSE-MESSAGE.
```
- Example for PL/I:
```
IF HBRA-CONN-COMPLETION-CODE = HBR-CC-OK 
THEN
  DO;
  DISPLAY(WS-PROGRAM || '-');
  DISPLAY('-name->' || name);
  DISPLAY('-loan amount->' || amount);
  DISPLAY('-approved->' || approved);
END;
ELSE
  DO;
  DISPLAY(WS-PROGRAM || '-');
  DISPLAY('-CC->' || HBRA-CONN-COMPLETION-CODE);
  DISPLAY('-RC->' || HBRA-CONN-REASON-CODE);
  DISPLAY('-MSG->' || HBRA-RESPONSE-MESSAGE);
END;
```
If an API call does not execute successfully, IBM Decision Server for z/OS returns a non-zero completion code and response code. If additional diagnostic information is available, IBM Decision Server for z/OS also returns a response message in HBRA-RESPONSE-MESSAGE.

Note: To execute the ruleset multiple times with different inputs, include both the HBRRULE API call and the completion code check in a loop.
Disconnect from the IBM Decision Server for z/OS instance:
- Example for COBOL:
```
  call 'HBRDISC' using
    HBRA-CONN-AREA.
```
- Example for PL/I:
```
call HBRDISC(addr(HBRA_CONN_AREA)); 
```