Adding API calls to your COBOL client application

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

About this task

As described in APIs, 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 you need to code the API calls:

++HBRHLQ++.SHBRCOBC(HBRWS) contains the HBRA-CONN-AREA data area.
++HBRHLQ++.SHBRCOBC(HBRC) contains the copybook for the completion codes and the reason codes.

The steps in the procedure include examples 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 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.
HBRMINW for applications that run on Rule Execution Server on WebSphere® Application Server for z/OS through WOLA as batch jobs.

Procedure

To add the API calls to your COBOL application:

Include the required copybooks. 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:
```
01 WS-REASON-CODES.
    COPY HBRC.
  COPY HBRWS.
```

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:

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.

Connect to an instance of IBM Decision Server for z/OS:
```
  call 'HBRCONN' using
    HBRA-CONN-AREA.
```
Execute the ruleset by using the HBRA-CONN-AREA data area to specify inputs:
```
  call 'HBRRULE' using
    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 more information, see Completion codes and reason codes.
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:
```
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.
```
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:
```
  call 'HBRDISC' using
    HBRA-CONN-AREA.
```