Copyright © Cloud Software Group, Inc. All Rights Reserved

Calling a Rule – CALLRULE

Syntax

For the syntax of all Call Level Interface functions, see Call Level Interface Specification and HRNHLLTM Module Parameters.

Calling Parameters

Your client program calls a rule by specifying CALLRULE as the OPERATION parameter and a string consisting of the rule name as the PARM parameter. If the rule takes arguments, the rule name is followed by the values for the arguments in parentheses. The DATA-IN (the fifth) and the DATA-OUT (the sixth) parameter are specified as described below. The RETURN-DATA (the seventh) parameter is set to any message that is returned by ENDMSG when the RETURN-CODE parameter is 0.

• When your client program has started a transaction, it can call an entry rule and pass values for its arguments. The rule has no real restrictions and can use all TIBCO Object Service Broker facilities, that is, it can call other rules and use the EXECUTE, DISPLAY, TRANSFERCALL, COMMIT, and ROLLBACK statements. • When the called rule completes, control is returned to the client program. The transaction, however, ends only with a STOPTR call.

DATA-IN and DATA-OUT Areas

The client program can pass DATA-IN and DATA-OUT areas to the session:

The rule can read the DATA-IN areas using MAP tables or tools such as $GETENVCOMMAREA.

The rule can write to the DATA-OUT areas using MAP tables or the $SETENVCOMMAREA tool.

The DATA-IN and the DATA-OUT areas can have one of two formats and describe one or more blocks of storage. In all cases, the client program is responsible for allocating storage, and for storage blocks pointed to by their structure.

The DATA-IN and the DATA-OUT areas are mapped by the same structure. The structure is used to represent a list of blocks (or COMMAREAs). The structure contains a count of the number of blocks, location and size.

Format Types

Each block is in one of the following formats:

•	Format 1: Represented by a pointer to the storage block

Format 1 works well in an assembler environment and permits segmentation of the storage for each separate block. It requires pointer manipulation.

•	Format 2: Implicitly follows the structure

Format 2 is suited to COBOL applications, as the structure describing the blocks and the blocks themselves are passed as one large contiguous storage area. It does not require pointer manipulation.

Format 1

The storage blocks are in separate locations, and are pointed to by addresses. This technique is not well-supported by the COBOL language, but works well in assembler.

Element	Length (bytes)	Description
Count	4	Number of blocks of storage in this group.
Address1	4	Pointer to block #1.
Length1	4	Length of block #1.
...
AddressN	4	Pointer to block #N.
LengthN	4	Length of block #N.

Format 2

The storage blocks are part of the area being passed. Use this implementation for COBOL.

Element	Length (bytes)	Description
Count	4	Number of blocks in this group.
0	4	Storage blocks are always defined in pairs, consisting of a full word of binary zeroes followed by a full word containing the length of the block. This is the first field of binary zero for the first storage block.
Length1	4	This is the second field containing the length of the first storage block.
...		Repeat the pair of binary zero and length for the 2nd through N-1th storage block.
0	4	This is the first field of binary zero for the N-th storage block.
LengthN	4	This is the second field containing the length of the N-th storage block.
Commarea1	length 1	First block
...		2nd through N-1th storage blocks
CommareaN	length N	Nth storage block

Accessing the Storage Areas

From your rules code, you can obtain the address of the DATA-IN block list by using the value of the field APIINHANDLE of the System Interpreted Table @SESSION(0). Similarly, you can obtain the address of the DATA-OUT block list using the value of the field APIOUTHANDLE of @SESSION(0). Access to the storage referenced by MAP tables is always granted and there is no need to register these addresses in the @MAP table. APIINHANDLE memory is accessible for reading and APIOUTHANDLE for reading and writing.

You can also use the $GETENVCOMMAREA and $SETENVCOMMAREA tools to access the blocks of storage in the DATA-IN and DATA-OUT areas.

Since the user client is responsible for allocating storage for the DATA-IN and DATA-OUT block lists, changing the value for APIINHANDLE and APIOUTHANDLE is not supported. The contents of the block lists can, however, be modified by rules code using MAP tables.

Sample Rule Code

The following rule fragment assigns the address of the DATA-OUT block list to local variable OUT, and the address of the DATA-IN block list to local variable IN:

---

 

GET @SESSION(0);

IN=@SESSION.APIINHANDLE;

OUT=@SESSION.APIOUTHANDLE;

---

 

Sample Calls

These examples call the ABC rule with the two arguments: 1 and SCR. They pass in one commarea via DATA-IN and expect up to 80 bytes of data to be returned in DATA-OUT.

COBOL Call

---

 

01 HRN-CALLABC.

05 RULEPARMLEN PIC 9(4) USAGE COMP-4 VALUE 12.

05 RULEPARMDAT PIC X(12) VALUE 'ABC(1,''SCR'')'.

01 HRN-DATA-IN.

05 IN-NO-COMMAREA PIC 9(9) USAGE COMP-4 VALUE 1.

05 IN-ZEROES PIC 9(9) USAGE COMP-4 VALUE 0.

05 DATAINPARMLEN PIC 9(9) USAGE COMP-4 VALUE 27.

05 DATAINPARMDAT PIC X(49)

VALUE 'CALLING OSB FROM COBOL II'.

 

01 HRN-DATA-OUT.

05 OUT-NO-COMMAREA PIC 9(9) USAGE COMP-4 VALUE 1.

05 OUT-ZEROES PIC 9(9) USAGE COMP-4 VALUE 0.

05 DATAOUTPARMLEN PIC 9(9) USAGE COMP-4 VALUE 80.

05 DATAOUTPARMDAT PIC X(80) VALUE SPACES.

 

.

.

CALL 'HRNHLLTM' USING HRNHLLWA 'CALLRULE'

HRN-NULL_DATA HRN-CALLABC HRN-DATA-IN HRN-DATA-OUT

HRN-RETURN-DATA HRN-RETURN-CODE.

---

 

Non Re-entrant Assembler Call

---

 

CALL HRNHLLTM,(HRNHLLWA,C'CALLRULE', X

0,CALLABC,DATAIN,DATAOUT,DATA,CODE),VL

.

.

CALLABC DC AL2(12),C'ABC(1,''SCR'')'

DATAIN DC F(1),A(DATAINC),F(50)

DATAINC DC CL28'CALLING OSB FROM ASSEMBLER'

DATAOUT DC F(1),A(DATAOUTC),F(80)

DATAOUTC DS CL80

DATA DS CL159 REASON CODE FROM HRNHLLTM

CODE DS F RETURN CODE FROM HRNHLLTM

---

 

Return Values

 

Return Codes	Description
0	CALLRULE request succeeded.
11	CALLRULE request failed. The first four bytes of the RETURN-DATA parameter are set to the reason code. Refer to Call Level Interface Reason Codes.

Non-Zero Value Returned

Whenever a non-zero value is returned in RETURN-CODE, RETURN-DATA contains either a reason code or an error message. The reason code is indicated by binary zeros in the first byte of RETURN-DATA; otherwise, RETURN-DATA contains a short error message similar to the ENDMSG that is returned to the workbench.

See Also

TIBCO Object Service Broker Managing Data about MAP tables.

TIBCO Object Service Broker Programming in Rules about writing rules.

TIBCO Object Service Broker Shareable Tools about the tools and System Interpreted Tables.

Copyright © Cloud Software Group, Inc. All Rights Reserved