&INTREAD

The &INTREAD verb retrieves the next message queued from the dependent processing environment of the issuing process.

This verb has the following format:

&INTREAD { VARS=prefix* [ RANGE=( start, end ) ] |
           VARS={ name | ( name, name, ..., name ) } |
           ARGS [ RANGE=(start, end) ] |
           STRING=( name, name, ..., name ) |
           SET  MDO=mdoname | SET } 
         [ WAIT={ YES | NO | nnnn.nn } ] 
         [ TYPE={ ANY | REQ | RESP } ] 
         [ PRIORITY={ REQ | RESP } ] 
         [ INPUT={ CHAR | HEX | HEXEXP } ]

The verb returns the next result line from a command executed by a previous &INTCMD statement, a message delivered by INTQ command, unsolicited messages, or event notifications.

Commands issued by an &INTCMD statement execute in the dependent processing environment of the issuing process, and results return to the dependent response queue for that dependent environment. The originating NCL process then uses the &INTREAD statement to retrieve command results line-by-line, from the response queue.

Other processes can send messages to your procedure using the &WRITE verb or INTQ commands.

This verb lets you write powerful logical procedures which correlate command results and react intelligently. On completing &INTREAD:

System variable &ZVARCNT totals the variables created or modified by the operation.
System variable &ZINTYPE indicates the dependent queue type where the message was obtained.
The &INTREAD Message Profile is set and the $INT mapped object is available.
Note: For more information about the message profile variables set for &INTREAD, see the Network Control Language Programming Guide.
System variable &ZFDBK is set as follows on &INTREAD completion:

0

Message has been received.

4

Wait time has expired.

8

Response queue limit reached, messages discarded (the default is 32 K).
&ZMDORC and &ZMDOFDBK are also set to indicate the result of MDO assignment that took place in making the $INT MDO available or in assigning the mdoname specified on the MDO operand.

Operands:

VARS=

Tokenizes the message into the nominated variables before control is returned to the procedure. Each word of the command output line is tokenized into the nominated variables from left to right. If insufficient variables are provided, data is lost. Excess variables are set to null. Formats for the operands associated with VARS= are:

prefix*: Generates the variables automatically during the tokenization process with variable names of 'prefix1 … prefix2', and so on. The RANGE= operand is specified to indicate a starting and ending suffix number. prefix* cannot be used with other variable names.
name: The name for a variable, excluding the ampersand (&).
name(n): As name, but n denotes the length of the data that is put into the variable.
*(n): Denotes a skip operation, where n represents the number of units to skip during the tokenization process. On VARS= statements, n denotes 'skip this number of words'. An asterisk (*) by itself is the same as *(1).

ARGS

Denotes that the line of text retrieved is tokenized and placed word-by-word into automatically generated variables with the form &1 through &n, depending on how many are required to hold the text. The RANGE= operand is coded to designate a start number and an end number to delimit the number of variables generated.

STRING=

Specifies that no tokenization is to be performed. The entire text of the command line is treated as a single string and returned to the procedure in the nominated variables. Formats for the operands associated with STRING are:

name: Specifies the name of a user-specified variable, excluding the leading &, in which to put the string text. Text is put into each variable up to the maximum length of each variable.
name(n): Specifies the name of a user-specified variable, excluding the leading &, in which to put the string text. Text is put into each variable for the length specified by n.
*(n): Denotes a skip operation, where n represents the number of units to skip during the tokenization process. On STRING statements, n denotes 'skip this number of characters'. An asterisk (*) by itself is the same as *(1).

SET

Specifies that no tokenization of the message is to be performed, but that the &INTREAD statement is to return only the message profile of the next message.

If SET is not specified, instructions must be coded on the &INTREAD statement specifying the tokenization requirements for the message text by using the other &INTREAD operands. SET is mutually exclusive with the INPUT operand.

MDO=mdoname

Specifies that, if a user MDO is embedded in the message, it is assigned to a local MDO with the name specified. An MDO might be present if the message was generated by an &EVENT MDO= or &WRITE MDO= statement. If no MDO is available, &ZVARCNT is set to zero, otherwise it is set to 1. All message profile variables are still set.

WAIT={ YES | NO | nnnn.nn }

WAIT=YES (the default) specifies that if no message is immediately available on the dependent response queue when &INTREAD is issued, the procedure waits until the next message arrives.

WAIT=NO specifies that control returns to the procedure immediately. If no message is available, all specified variables are set to null.

WAIT=nnnn.nn specifies the procedure can wait up to nnnn.nn seconds for a message to arrive. If no message is immediately available when the &INTREAD is issued (maximum is 9999.99 seconds). After nnnn.nn seconds without a message, control returns to the procedure with all specified variables set to null and &ZFDBK set to 4. If WAIT=0 is coded, control returns immediately. If WAIT=nnnn.nn is not used, it is your responsibility to ensure that the procedure is structured so that an &INTREAD is not issued in the case where messages cannot arrive. Otherwise, the NCL process waits indefinitely.

TYPE={ ANY | REQ | RESP }

TYPE=ANY returns the next message of any type, either from the dependent response queue or the dependent request queue. If messages are available on both queues, the first message from the dependent response queue is returned in preference.

TYPE=REQ indicates that &INTREAD is to return the first message from the dependent request queue of the issuing process.

TYPE=RESP (the default) indicates that &INTREAD is to return the first message from the dependent response queue of the issuing process.

PRIORITY={ REQ | RESP }

This operand is used with TYPE=ANY, to return the message if data is available on both the response and request queues. The default is PRIORITY=RESP. PRIORITY=REQ is used to select request messages in preference to responses.

INPUT={ CHAR | HEX | HEXEXP }

Specifies the format for the data returned in the variables created by the &INTREAD operation. The default is standard character data.

INPUT=HEX indicates that data in the variables is pure hexadecimal (and therefore not directly processable by NCL).

INPUT=HEXEXP indicates that data in the variables is hexadecimal data represented as expanded hexadecimal. For example, a hexadecimal byte with a value of 0A appears in a variable as two characters 0A.

HEX and HEXEXP support provide data transparency across &INTREAD operations.

Examples: &INTREAD

&INTREAD WAIT=5 ARGS RANGE=(20,80)

This requests the first message from the dependent response queue. The message is tokenized into variables &20 up to a maximum of &80 (&ZVARCNT is set to total how many variables were created). If no message is immediately available, control returns after 5 seconds.

&INTREAD VARS=(*(3),A(2),B(3),C,D,E,F)

This example reads the next message from the dependent response queue and tokenizes it into individual words:

*(3) indicates that the first three words are ignored
Two characters of the next word are placed in the variable &A.
Three characters of the next word are placed in the variable &B
The next four words are placed in variables &C, &D, &E and &F respectively.

Notes:

If a procedure is suspended waiting for an &INTREAD, use END or FLUSH commands to force termination.

When a message is received as a result of &INTREAD processing, a mapped data object, containing all attributes associated with the message, is made available to the NCL procedure in an object named $INT. The $INT object is an envelope for a user-defined, mapped data object, which is reassigned from the $INT.USERMDO component or assigned automatically if the MDO= operand was specified. The map name for the user MDO is available in the $INT.MAPNAME component or the &ZMAPNAME profile variable. If no user MDO is present when the MDO= operand is specified, a null unmapped MDO is assigned. Message profile variables and the $INT MDO will always be available after a successful &INTREAD, whether an embedded MDO is available or not. The $INT MDO is mapped by $MSG.

&INTCLEAR is used to clear outstanding messages queued to the dependent processing environment.

If &ZFDBK is set to 8 on &INTREAD completion, it means that the response queue was congested at some time with unprocessed messages that exceeded 32 KB. One or more messages might have been lost. This condition is unlikely to occur and represents a surge of messages being queued by dependent processing region activity faster than the &INTREAD process can process them. If this condition occurs, establish the cause of the large number of messages.

&INTREAD is sensitive to the current setting of the &CONTROL VARSEG option at the time the &INTREAD statement is issued. This option determines the processing method for the data delivered to the &INTREAD through INTQ commands.

For example (where a procedure using INTQ passes data to another procedure):

&A = &STR SHOW SESSINTQ ID=&NCLID &A
&INTREAD TYPE=REQ ARGS

If &CONTROL VARSEG (default) is in effect when the second procedure issues the &INTREAD, it receives two variables. &1 contains the word SHOW, and &2 the word SESS, even though the words were originally contained within one variable. However, if &CONTROL NOVARSEG is in effect, the second procedure receives a single variable containing SHOW SESS.

A response message is propagated to the current processes owning environment, using either the &INTCONT or &INTREPL statement.

Note: For more information about NCL processing environments and dependent processing environments, see the Network Control Language Programming Guide. See also the INTQ command description in the Online Help.

More information: