220 Flexible Decision Automation for Your zEnterprise with Business Rules and Events
database that is hosted locally to the decision execution on IBM AIX® server1 but is not
accessible to z/OS server2 due to the firewall configuration.
7.6 Coding the COBOL client application
To access the zRule Execution Server, the COBOL application must use the supplied client
API. This API consists of the following API calls:
HBRCONN To connect to the server
HBRRULE To execute a decision
HBRDISC To disconnect from the server
Each call takes the HBRWS copybook-defined structure as a parameter.
7.6.1 HBRWS header structure
The HBRWS header structure is required for all zRule Execution Server for z/OS client API
calls. It is in the <INSTALL-ROOT>.SHBRCOBS data set. It must be included in any client programs
that call zRule Execution Server for z/OS. Example 7-11 shows the layout of the structure.
Example 7-11 Layout of the structure
01 HBRA-CONN-AREA.
10 HBRA-CONN-EYE PIC X(4) VALUE 'HBRC'.
10 HBRA-CONN-LENTH PIC S9(8) COMP VALUE +3536.
10 HBRA-CONN-VERSION PIC S9(8) COMP VALUE +2.
10 HBRA-CONN-RETURN-CODES.
15 HBRA-CONN-COMPLETION-CODE PIC S9(8) COMP VALUE -1.
15 HBRA-CONN-REASON-CODE PIC S9(8) COMP VALUE -1.
10 HBRA-CONN-FLAGS PIC S9(8) COMP VALUE +1.
10 HBRA-CONN-INSTANCE.
15 HBRA-CONN-PRODCODE PIC X(4) VALUE SPACES.
15 HBRA-CONN-INSTCODE PIC X(12) VALUE SPACES.
15 HBRA-CONN-SSID PIC X(4) VALUE SPACES.
15 HBRA-CONN-GRPID PIC X(4) VALUE SPACES.
10 HBRA-RESERVED01 PIC S9(8) COMP VALUE 0.
10 HBRA-RESERVED02 PIC S9(8) COMP VALUE 0.
10 HBRA-RESERVED03 PIC S9(8) COMP VALUE 0.
10 HBRA-CONN-RULE-CCSID PIC S9(8) COMP VALUE 0.
10 HBRA-CONN-RULEAPP-PATH PIC X(256) VALUE SPACES.
10 HBRA-RESPONSE-AREA VALUE SPACES.
15 HBRA-RESPONSE-MESSAGE PIC X(1024).
10 HBRA-RA-INIT VALUE LOW-VALUES.
15 HBRA-RESERVED04 PIC X(1792).
10 HBRA-RA-PARMETERS
REDEFINES HBRA-RA-INIT.
15 HBRA-RA-PARMS OCCURS 32.
20 HBRA-RA-PARAMETER-NAME PIC X(48).
20 HBRA-RA-DATA-ADDRESS USAGE POINTER.
20 HBRA-RA-DATA-LENGTH PIC 9(8) BINARY.
10 HBRA-RESERVED.
15 HBRA-RESERVED05 PIC X(12).
15 HBRA-RESERVED06 PIC X(64).
15 HBRA-RESERVED07 PIC X(64).
Chapter 7. Advanced topics for decision authoring 221
15 HBRA-RESERVED08 PIC X(128).
15 HBRA-RESERVED09 PIC X(132).
The entire HBRA-CONN-AREA must be passed on each of the three API calls to zRule
Execution Server for z/OS. We describe the important elements of this structure in the
following sections.
HBRA-CONN-RETURN-CODES
This element provides response and reason codes to the requested API call. If these
responses do not have a zero value on their return from an API, the user documentation
provides more details about the error that occurred.
HBRA-CONN-RULEAPP-PATH
This element is important for the data structure. This value is used by zRule Execution Server
for z/OS to identify which decision to execute on the specific data. After a decision is deployed
to zRule Execution Server for z/OS, the value for the RULEAPP-PATH can be identified by
logging on to the administrator console and viewing the deployed decision.
The RULEAPP-PATH uses this structure:
/<RULEAPP-NAME>/<RULEAPP-VER>/<RULESET-NAME>/<RULESET-VER>
The RULE-APP-VER and RULESET-VER are generally required only if the client wants to
execute a particular version of a decision that is deployed to zRule Execution Server for z/OS.
In most cases, the client wants to execute the latest version of the decision. In this case, the
path is simplified to this structure:
/<RULEAPP-NAME>/<RULESET-NAME>
The Miniloan sample that is supplied with the product uses this structure:
/zRulesMiniLoanDemoRuleApp/zRulesMiniLoanDemo
HBRA-RESPONSE-AREA
If any text messages or warnings are returned by the Java portion of the server, they are
returned in this data area to help you diagnose any problems. A preferred practice is to write
this area out to an application log, if a nonzero return code is received.
HBRA-RA-PARAMETERS
This section is required only on the HBRRULE API call and provides the user data that is
used to evaluate the decision. The structure is a list of triplets to pass the parameter name, a
pointer to the data in working storage, and the length of the data.
HBRA-PARAMETER-NAME
This name is the name of the parameter as it is known to the decision. This parameter name
is defined as part of the rule-authoring process. The parameter name is case-sensitive and
must be added as a character string, exactly as it is defined in the ruleset.
HBRA-DATA-ADDRESS
This element is a pointer to the location of the parameter in your working storage. Normally,
this element points to the address of the 01-level element in your copybook that you imported
to define this parameter to the decision. It is normally set like the following example:
set HBRA-DATA-ADDRESS(1) to address of Borrower

Get Flexible Decision Automation for Your zEnterprise with Business Rules and Events now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.