Application programs can perform STOQ communications by invoking three procedures in the EVASUPPORT system library: STOQ_SEND, STOQ_RECV, and STOQ_POLL. Before invoking these procedures, each application program must declare and initialize a STOQ parameter block.
Declaring a STOQ Parameter Block
A STOQ parameter block stores the following information, in the following order:
-
The name of the STOQ. The STOQ name is always six characters long, and should be left-justified and blank filled if necessary to attain the six-character length. The STOQ name can contain any EBCDIC characters, including embedded blanks and nonprinting values. The name cannot consist entirely of null characters.
-
The length of the subqueue name, in characters. This value must be in the range 0 to 99. A length of 0 indicates that there is no subqueue name.
-
The subqueue name, if any. The subqueue name can contain any EBCDIC characters, including embedded blanks and nonprinting values. The name cannot consist entirely of null characters.
-
The length of the message data, in characters. This value must be in the range 0 to 9999. A length of 0 indicates that there is no message data.
-
For send operations, this value must be stored in advance by the application program.
-
For receive operations, the caller stores a value that determines the maximum message size to be received. After a receive, the system sets the value to the actual size of the message received. If this actual message size value is larger than the maximum message size value stored by the caller, the message will be truncated to the caller’s maximum message size. The caller should restore the maximum message size value prior to each receive.
-
For poll operations, this value is returned by the system and reflects the number of messages in the specified STOQ or subqueue.
-
-
The message data. The maximum length for message data is 9999 bytes. The message data can contain any EBCDIC characters, including embedded blanks and nonprinting values.
-
For send operations, this value must be stored in advance by the application program.
-
For receive operations, this value is returned by the system.
-
For poll operations, this field is not used.
-
Send, Receive, and Poll Operations
The three EVASUPPORT procedures STOQ_SEND, STOQ_RECV, and STOQ_POLL each receive two parameters: a STOQ parameter block and a flag variable. The STOQ parameter block was described in the previous subsection.
The flag variable is a real variable with the following significant fields:
|
Field |
Value and Meaning |
|---|---|
|
[01:01] |
Indicates whether the top or bottom of the STOQ is used for the operation. |
The bottom of the STOQ or subqueue is used.
The top of the STOQ or subqueue is used. |
|
|
[00:01] |
The No Wait flag. Indicates whether to wait or to abandon the STOQ operation if a delay is encountered. A delay occurs for a STOQ_SEND if the specified STOQ is full. A delay occurs for a STOQ_RECV if there are no messages in the specified STOQ or subqueue. |
The process waits until the send or receive operation can be completed.
The process abandons the operation and proceeds to the next statement. |
Additionally, the STOQ_SEND, STOQ_RECV, and STOQ_POLL procedures each return a real value. The application program can inspect this result to determine whether errors occurred in the operation. Refer to Handling the CRCR or STOQ Result later in this section.
Using STOQ in ALGOL
For ALGOL programs, the STOQ parameter block can be declared as an EBCDIC array. In this array,
-
The first six bytes store the STOQ name.
-
The next byte stores the two-digit subqueue name length in packed decimal form.
-
The next 0 to 99 bytes store the subqueue name (depending on the value of the subqueue name length specified in the previous byte).
-
The next two bytes store the four-digit message data length in packed decimal form.
-
The next 0 to 9999 bytes store the message data.
The following ALGOL program includes statements to define a STOQ parameter block and invokes the STOQ_SEND, STOQ_RECV, and STOQ_POLL procedures.
BEGIN
EBCDIC ARRAY STOQ_BLOCK [0:9999];
REAL STOQ_FLAGS, RESULT_STATUS;
LIBRARY EVASUPPORT (LIBACCESS = BYFUNCTION,
FUNCTIONNAME = “EVASUPPORT.”);
REAL PROCEDURE STOQ_RECV (STOQ_BLOCK, STOQ_FLAGS);
EBCDIC ARRAY STOQ_BLOCK [0];
REAL STOQ_FLAGS;
LIBRARY EVASUPPORT;
REAL PROCEDURE STOQ_SEND (STOQ_BLOCK, STOQ_FLAGS);
EBCDIC ARRAY STOQ_BLOCK [0];
REAL STOQ_FLAGS;
LIBRARY EVASUPPORT;
REAL PROCEDURE STOQ_POLL (STOQ_BLOCK, STOQ_FLAGS);
EBCDIC ARRAY STOQ_BLOCK [0];
REAL STOQ_FLAGS;
LIBRARY EVASUPPORT;
REPLACE STOQ_BLOCK[0] BY “QUEUE1”, % QUEUE NAME
48”09”, % SUB QUEUE NAME LEN
“SUBQUEUE1”, % SUB QUEUE NAME
48”0012”, % DATA LENGTH
“DATA MESSAGE”; % DATA
STOQ_FLAGS.[1:1]:= 0; % INSERT AT BOTTOM OF STOQ
STOQ_FLAGS.[0:1]:= 0; % WAIT FOR SPACE
STOQ_SEND(STOQ_BLOCK, STOQ_FLAGS);
REPLACE STOQ_BLOCK[0] BY 48”00” FOR 10000;
REPLACE STOQ_BLOCK[0] BY “QUEUE1”, % QUEUE NAME
48”09”, % SUB QUEUE NAME LEN
“SUBQUEUE1”, % SUB QUEUE NAME
48”0000”; % CLEAR FOR RECV
STOQ_FLAGS.[1:1]:= 1; % RECEIVE FROM TOP OF STOQ
STOQ_FLAGS.[0:1]:= 0; % WAIT FOR MESSAGE
STOQ_RECV(STOQ_BLOCK, STOQ_FLAGS);
REPLACE STOQ_BLOCK[0] BY 48”00” FOR 10000;
REPLACE STOQ_BLOCK[0] BY “QUEUE1”, % QUEUE NAME
48”00”, % SUB QUEUE NAME LEN
48”0000”; % CLEAR FOR POLL
STOQ_FLAGS:= 0; % CLEAR - NOT USED FOR POLL
STOQ_POLL(STOQ_BLOCK, STOQ_FLAGS);
END.Using STOQ in COBOL74
For COBOL74 programs, the STOQ parameter block must be a group item. All subordinate items are passed to STOQ.
All subqueue names used with that STOQ parameter block must be the same length as the subordinate item declared to store the subqueue name. One simple way to handle this requirement is by padding all subqueue names with blanks to bring them to the same length. An alternative would be to declare a different STOQ parameter block for use with each subqueue name of a given length.
The subqueue name item should be declared with the number of digits specified by the subqueue name length item. Thus in the following example, STOQ-SUBQ-LENGTH is declared with a value of 6, and STOQ-SUBQ is declared as PIC X(6).
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 RESULT-STATUS REAL.
77 STOQ-STATUS REAL.
01 STOQ-BLOCK.
03 STOQ-QUEUE PIC X(6).
03 STOQ-SUBQ-LENGTH PIC 9(2) COMP VALUE 6.
03 STOQ-SUBQ PIC X(6).
03 STOQ-DATA-LENGTH PIC 9(4) COMP.
03 STOQ-DATA PIC X(9999).
PROCEDURE DIVISION.
BEGIN-PARA.
MOVE “QUEUE1” TO STOQ-QUEUE.
MOVE “SUBQ01” TO STOQ-SUBQ.
MOVE “HELLO THERE” TO STOQ-DATA.
MOVE 11 TO STOQ-DATA-LENGTH.
CHANGE ATTRIBUTE LIBACCESS OF “EVASUPPORT”
TO BYFUNCTION.
CALL “STOQ_SEND OF EVASUPPORT”
USING STOQ-BLOCK, STOQ-STATUS
GIVING RESULT-STATUS.
CALL “STOQ_RECV OF EVASUPPORT”
USING STOQ-BLOCK, STOQ-STATUS
GIVING RESULT-STATUS.
CALL “STOQ_POLL OF EVASUPPORT”
USING STOQ-BLOCK, STOQ-STATUS
GIVING RESULT-STATUS.
STOP RUN.