&MSGREAD

Requests that the next message be made available to MSGPROC.

&MSGREAD { SET |  VARS=prefix* [ RANGE=(start,end) ] |
           VARS={ var | ( var1, var2, ..., varn ) } |
           STRING= ( name, name, ..., name) |
           ARGS  [ RANGE=(start,end) ] |
           MDO=mdoname }
         [ WAIT={ YES | NO | nnnn.nn } ]
         [ TYPE={ ALL  | SOLICIT | UNSOLICIT } ]
         [ DOM={ YES | NO } ]

Used within a MSGPROC procedure to request delivery of the next message. If no message is available immediately, procedure processing is suspended at this point and resumes when the next message to be sent to the user's terminal arrives.

Multiple &MSGREAD statements is present within a MSGPROC, to make the processing of group messages easier.

On completing &MSGREAD, system variable &ZVARCNT is set to the number of variables created or modified by the operation.

The profile of the message received by &MSGREAD is set in a suite of reserved system variables. The message profile (which includes attributes such as color, highlighting, and source information) provides a complete description of all the message attributes in addition to the message text.

When &MSGREAD completes, the system variable &ZFDBK is set as follows:

0: Message has been received.
4: Wait time has expired.

Operands:

SET

Specifies that no message tokenization is performed; the &MSGREAD statement returns only the message profile of the next message.

If SET is not specified, operands must be coded on the &MSGREAD statement specifying the tokenization requirements for the message text by using other &MSGREAD operands.

VARS=prefix* [ RANGE=(start,end) ] | VARS={ var | ( var1, var2, ..., varn ) }

Specifies the message is to be tokenized into variables from left to right before control is returned to the procedure. If insufficient variables are nominated, some data is lost. Excess variables are set to null. The formats of the operands that is coded with VARS= are described below:

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

STRING=

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

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

ARGS [ RANGE=(start, end) ]

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 option is coded to designate a start and an end value to delimit the number of variables generated.

MDO=mdoname

Specifies that, if an embedded MDO is present in the message received by &MSGREAD, it will be assigned to an object with the name specified in mdoname.

WAIT={ YES | NO | nnnn.nn }

Specifies the action &MSGREAD processing takes if no message is available for processing immediately. Code WAIT=NO if you want control returned immediately to the statement after &MSGREAD when no incoming message is available. Code WAIT=nnnn.nn to specify the number of seconds up to which &MSGREAD waits for a message, before returning control to the procedure (maximum is 9999.99 seconds). Code WAIT=YES or omit the operand (it will default to YES), if &MSGREAD is to wait indefinitely for a message to arrive. Coding WAIT=0 has the same effect as WAIT=NO.

TYPE={ ALL | SOLICIT | UNSOLICIT }

Indicates whether &MSGREAD filters solicited or unsolicited messages. Default is ALL, which means that all messages satisfy &MSGREAD. Code SOLICIT if you want to receive solicited messages only.

DOM={ YES | NO }

Specifies whether receipt of a delete operator message (DOM) instruction can complete an &MSGREAD operation. If MSGPROC wants to know about the flow of DOMs to the user's window, code DOM=YES. When a DOM completes &MSGREAD, message profile system variables will indicate that a DOM (and not a real message) has been received.

Examples: &MSGREAD

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

This requests the first message from the message queue, specifying that it is to be 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.

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

This example reads the next message from the message queue and tokenizes it into individual words. *(3) indicates that the first 3 words are ignored, 2 characters of the next word are placed in the variable &A, three characters of the next word are placed in the variable &B and the next 4 words are placed in variables &C, &D, &E and &F respectively.

&MSGREAD STRING=(A,B(2),*(5),C(3))

Reads the next message from the message queue as a single string of text. The first 256 bytes are placed in &A, the next 2 characters are placed in &B, the next 5 characters are ignored and the next 3 characters are placed in &C.

&MSGREAD MDO=BRUCE

Reads the next message from the message queue and, if the message contains a user MDO, assigns the embedded MDO into an object called BRUCE and mapped by &ZMAPNAME.

Notes:

After a successful &MSGREAD, a $MSG MDO will always be available to the MSGPROC. $MSG is mapped my $MSG, and contains all attributes of the message. If the message is an envelope for a user MDO, the user MDO will be automatically assigned the name specified on the MDO= operand. It is also available directly from the $MSG.USERMDO component and its map name is in $MSG.MAPNAME or &ZMAPNAME.

After an &MSGREAD a useful technique is to use an &GOTO statement for the routine that will process the message, using the first token of the message (normally the message number).

&CONTROL NOLABEL
.READ
&MSGREAD ARGS
GOTO .&1
&MSGCONT     -* Unexpected messages will be
&GOTO .READ  -* caught and returned for normal processing

.msg1
.msg2
-*
-* Processing
-*...
&GOTO .READ

While testing and developing a MSGPROC procedure you might need to terminate the current version and invoke an updated copy. MSGPROC is invoked on entering OCS Mode. Exiting OCS flushes the current MSGPROC. Subsequent re-entry to OCS loads the latest copy of the procedure (unless it was preloaded, when the preloaded copy is used).

The PROFILE MSGPROC=FLUSH command is used to terminate an active MSGPROC process. PROFILE MSGPROC=name can then be used to initiate a new MSGPROC process.

If MSGPROC terminates for any reason, standard message processing resumes.

MDO assignment which occurs during &MSGREAD processing results in the setting of &ZMDORC and &ZMDOFDBK system variables.

More information:

&MSGCONT

&MSGDEL

&MSGREPL