APIs

Use the zRule Execution Server for z/OS APIs to connect your z/OS® application (COBOL or PL/I application) to a server, execute one or more rulesets, and disconnect from the server.

The following table explains how the APIs work in zRule Execution Server for z/OS:

Table 1.
API zRule Execution Server for z/OS
HBRCONN Connects to the server group specified in the dataset listed in the HBRENVPR DD statement. For example:

//HBRENVPR DD DISP=SHR,DSN=++HBRWORKDS++.SHBRPARM(HBRBATCH)

++HBRWORKDS++ variable represents the high-level qualifier of the working datasets for the server instance.
HBRRULE Executes the ruleset that is specified in the HBRA-CONN-RULEAPP-PATH field of the HBRA-CONN-AREA data area, which the z/OS application uses to communicate with the server group.

The HBRA-CONN-SSID field returns the subsystem ID of the server that completed the execution of the ruleset. If ruleset execution does not complete successfully, this field is set to blanks.
HBRDISC Disconnects from the server group that is specified in the dataset listed in the HBRENVPR DD statement. For example:

//HBRENVPR DD DISP=SHR,DSN=++HBRWORKDS++.SHBRPARM(HBRBATCH)

++HBRWORKDS++ variable represents the high-level qualifier of the working datasets for the server instance.
Note: After each API call completes, your z/OS application check the HBRA-CONN-COMPLETION-CODE and HBRA-CONN-REASON-CODE fields in the HBRA-CONN-AREA data area. For more information, see Completion codes and reason codes.
The following dataset 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 following table describes the fields that are passed in the HBRA-CONN-AREA data area:

Table 2.
Field name Data type User read/write Description
Length Format
HBRA-CONN-EYE 4 EBCDIC No Eyecatcher HBRC
HBRA-CONN-LENGTH 4 binary No Length of this structure
HBRA-CONN-VERSION 4 binary No Version of this structure
HBRA-CONN-COMPLETION_CODE 4 binary Read The API call completion code
HBRA-CONN-REASON_CODE 4 binary Read The API call reason code
HBRA-CONN-FLAGS 4 binary No Not used.
HBRA-CONN-PRODCODE 4 EBCDIC No Set to HBR_.
HBRA-CONN-INSTCODE 12 EBCDIC No Set to RULESFORZOS.
HBRA-CONN-SSID 4 EBCDIC Read The SSID the rule execution occurred in for zRule Execution Server for z/OS, JVMS for CICS® JVM, or EMBD for embedded zRule Execution Server for z/OS
HBRA-CONN-RULE-CCSID 4 binary Write The CCSID used when translating the strings in HBRA-CONN-RULEAPP-PATH, HBRA-RA-PARAMETER-NAME, and HBRA-RESPONSE-MESSAGE to and from Java™ Unicode.

If it is not set, the default value of 1047 is used.
HBRA-CONN-RULEAPP-PATH 256 EBCDIC Write The path of the RuleApp to be executed
HBRA-EXECUTION-ID 43 EBCDIC Read The execution ID is returned as part of running a rule. When the run finishes, you can access the value from COBOL or PL/I by using the variable HBRA-EXECUTION-ID.
HBRA-RESPONSE-MESSAGE 1024 EBCDIC Read The Java error message in the event of a failure in rule execution
HBRA-RA-PARMS 32 See below. Write This field is an array of up to 32 parameters whose structure is defined by the following three members.

It is expected that the user has initialized the HBRA-CONN-AREA to zero so that the number of parameters is defined by the number of consecutive entries with nonzero HBRA-RA-DATA-LENGTH.
HBRA-RA-PARAMETER-NAME 48 EBCDIC Write The name of this rule parameter
HBRA-RA-DATA-ADDRESS 4 pointer Write Pointer to the data for this rule parameter
HBRA-RA-DATA-LENGTH 4 binary Write Length of the data in this rule parameter