|
|
|
Requests the next VTAM PPO message be made available to PPOPROC.
&PPOREAD { SET |
VARS=prefix* [ RANGE=(start,end) ] |
VARS={ name | (name,name, ..., name) } |
STRING=( name, name, ..., name ) |
ARGS [ RANGE=(start,end) ] |
[ WAIT={ YES | NO | nnnn.nn } ]
The PPOPROC system level procedure uses &PPOREAD to receive the next VTAM message.
If no VTAM PPO message is immediately available, processing of the procedure will be suspended at this point and will resume when the next VTAM PPO message arrives.
If DEFMSG has been used to limit the messages that are to be intercepted, only those messages will satisfy an &PPOREAD.
Multiple &PPOREAD statements is present within PPOPROC, thus making the processing of group messages easier. Delivery of all unsolicited VTAM messages to the one NCL process allows PPOPROC to correlate and react intelligently to VTAM's notification of network events.
On completion of &PPOREAD the system variable &ZVARCNT is set to the number of variables created or modified by the operation.
The profile of the message received by &PPOREAD 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 PPO message attributes in addition to the message text.
Operands:
Specifies that no tokenization of the PPO message is to be performed, but that the &PPOREAD statement is to return only the message profile of the next PPO message.
If SET is not specified, instructions must be coded on the &PPOREAD statement specifying the tokenization requirements for the message text by using the other &PPOREAD operands.
Specifies that the message is to be tokenized into the nominated variables before control is returned to the procedure. Each word of the command output line will be tokenized into the nominated variables from left to right. If insufficient variables are provided, some data will not be available to the procedure. Excess variables will be set to a null value. The formats of the operands that may be coded with VARS= are described below. The format of the operands associated with VARS= are:
Variables will be generated automatically during the tokenization process, and that the variable names will be prefix1 .. prefix2, and so on. The RANGE= operand may be specified to indicate a starting and ending suffix number. prefix* cannot be used in conjunction with other variable names.
The name of a variable, excluding the ampersand (&).
As name, but n denotes the length of the data that is to be placed in the variable.
Denotes a skip operation, where n represents the number of units to be skipped during the tokenization process. On VARS= statements n denotes 'skip this number of words'. An asterisk (*) by itself is the same as *(1).
Specifies that no tokenization is to be performed. The entire text of the command line is to be treated as a single string and returned to the procedure in the nominated variables. The formats of the operands associated with STRING are:
User-specified variables (excluding the leading &) into which the string text is to be placed. Text will be placed into each variable for the maximum length of a variable.
User-specified variables (excluding the leading &) into which the string text is to be placed. Text will be placed into each variable for specified length 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 this number of characters'. An asterisk (*) by itself is the same as *(1).
Denotes that the line of text retrieved will be tokenized and placed word by word into automatically generated variables of the form &1 through &n, depending on how many are required to hold the text. The RANGE= operand may be coded to designate a start number and optionally an end number, which delimits the number of variables that will be generated.
YES signifies that if no message is immediately available, the PPOPROC procedure is suspended until a message arrives. NO indicates that if no message is available control is to be returned to the procedure immediately. nnnn.nn signifies the number of seconds, and 1/100th seconds the procedure is suspended for, awaiting a message to arrive, before control will be returned to the procedure (maximum is 9999.99 seconds). WAIT=0 has the same effect as WAIT=NO.
Examples:
&PPOREAD ARGS RANGE=(20,80)
Reads or waits for the next unsolicited VTAM message specifying that it is tokenized into variables &20 to a maximum of &80. &ZVARCNT will be set to indicate how many variables were created.
&PPOREAD VARS=(*(3),A(2),B(3),C,D,E,F)
Reads or waits for the next unsolicited VTAM message, and tokenizes the message 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.
&PPOREAD VARS=ABC* RANGE=(1,50)
Reads or waits for the next unsolicited VTAM message, tokenizes it and places the text word by word into a series of automatically generated variables of the form ABC1 ABC2 ... ABC50 and so on. As many variables as required are generated, to the limit specified by the RANGE operand.
&PPOREAD STRING=(A(3),B(2),*(5),C(3))
Reads the next unsolicited VTAM message as a single string of text. The first 3 characters 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.
Notes:
Following an &PPOREAD a useful technique is the use of an &GOTO statement, using the VTAM message number, to go to the routine that will process the message.
&CONTROL NOLABEL
.READ
&PPOREAD VARS=(A,B,C,D,E,F,G,H)
&GOTO .&A
-* Unexpected messages will be caught here,
-* and returned for normal processing.
&WRITE MON=YES DATA=UNEXPECTED MESSAGE NO: &A
&GOTO .READ
.ISTnnnI
.ISTnnnI
:
: process ...
While testing and developing a PPOPROC procedure, you may need to terminate the current version and invoke a new updated copy. This is achieved using the SYSPARMS PPOPROC=FLUSH command, which is specifically designed to force termination of PPOPROC, followed by a SYSPARMS PPOPROC=member command to reinstate PPOPROC.
The &RETCODE system variable is set to zero (0) by &PPOREAD, except when WAIT=NO or WAIT=n was coded and no message arrived. In this case, &RETCODE is set to 12.
When PPOPROC terminates for any reason, standard PPO processing is resumed, and no PPO messages will be lost.
Preloading of PPOPROC using the LOAD command offers no performance advantage as the procedure remains loaded for the duration of processing.
| Copyright © 2009 CA. All rights reserved. |
|