|
|
|
Receives data from PPI.
&PPI RECEIVE [ WAIT={ YES | NO | n | NOTIFY } ]
[ OPT={ NONE | ASIS | HEXEXP } ]
{ VARS=(list) |
VARS=prefix*[ RANGE=(start,end) ] |
ARGS [ RANGE=(start,end) ] | STRING=(list) |
MDO=stem [ MAP=map ] }
Operands:
The RECEIVE option of the &PPI verb allows a PPI-defined NCL process to receive the next available data buffer queued to that receiver ID. The data may be parsed into NCL variables in a variety of ways.
The NCL process need not be concerned with the length of the incoming data; this is handled automatically.
An optional parameter, that indicates what action to take if there is no data buffer immediately available to process.
WAIT=YES (the default) indicates that the process is to wait indefinitely for a buffer to arrive. The process may be flushed while waiting.
WAIT=NO indicates that the process is to immediately continue execution. In this case, &RETCODE will be 4, and &ZFDBK will be 30 (the PPI return code for no data).
WAIT=n indicates that the process is to wait the indicated number of seconds (from 0.01 to 9999.99). If no buffer arrives in that time, action is as for WAIT=NO. The process may be flushed while waiting.
WAIT=NOTIFY indicates that the process is to continue execution, and that a message is to be queued to the dependent processing environment, informing it when a data buffer arrives. This as akin to the way that &PANEL TYPE=ASYNC works. The message may be seen using &INTREAD. This allows the process to wait for several events simultaneously. If a new &PPI RECEIVE (of any type) is issued before the message has been queued, the notification is canceled (a message may already be queued, but not yet received using &INTREAD, so be careful). The notification message (N00101) has a type of PPI, and an event class of RECEIVE. If the receiver ECB is posted with a shutdown code (99), the event class will be SHUTDOWN.
If no data is immediately available, &RETCODE will be set to 20. indicating that a message will be queued to &INTREAD.
The process simply reissues &PPI RECEIVE after reading the notification message.
An optional parameter that controls how the incoming data is parsed.
NONE (the default) means that any unprintable data is translated to blanks when placing it into the nominated NCL tokens.
ASIS means that unprintable characters will be left alone when placing it into NCL tokens. This is typically useful only when using the STRING parse option, as the other options delimit on blanks (x'40'), which may actually be part of the hexadecimal data.
HEXEXP means that each string being placed into an NCL token is hexadecimal-expanded to character-format hexadecimal. This limits the amount of data that maybe placed into a token to 128 source bytes (for a maximum of 256 hexadecimal-expanded characters). Typically useful only with the STRING parse option.
One of these options is required, and sets the parsing option for the received data.
The input data is parsed using blanks as the separator, or broken up into string segments.
VARS=(list) parses the data on blanks into a list of variables. Each entry in the list must be a valid variable name, without the & (unless you wish to substitute the variable name itself). Each variable in turn receives the next blank-delimited piece of source data, truncated to 256 characters if required (128 before hexadecimal-expansion of using OPT=HEXEXP). A piece of source data may be skipped by specifying * as the variable name. Several may be skipped by specifying *(n). A variable may have the amount of data placed in it truncated by specifying name(n) for that entry.
VARS=prefix* and ARGS (which is the same as VARS=*) parse as for VARS=(list) with the variable names being formed from the prefix, suffixed by the numbers specified in the RANGE= operand. All the target variables in the range are cleared before this parsing is performed.
STRING=(list) indicates that the data is to be placed into the nominated variables in order, delimiting only be length. If no subscripts are specified on the variables in the list, 256 is used. Part of the data may be skipped by using *(n) and each variable may have an explicit length specified after it.
Note: If you are using OPT=HEXEXP, these lengths refer to the length before hexadecimal-expansion, and in this case the maximum length allowed is 128.
Following a successful RECEIVE, &RETCODE will be 0. &ZVARCNT contains the count of the number of variables updated.
The sender ID of the data is stored in the NCL user variable &PPISENDERID. The actual byte length of the received data is stored in the user variable &PPIDATALEN.
The received data is assigned into the MDO. If MAP=map is specified, then the specified map is attached to the MDO.
| Copyright © 2009 CA. All rights reserved. |
|