|
|
|
The &CNMREAD verb makes the next CNM record available to an NCL procedure.
This verb has the following format:
&CNMREAD [ WAIT={ nnnn | 0 } ]
[ TYPE={ SEGMENT | VECTOR | BOTH | RESP } ]
[ { ARGS [ RANGE=(start,end) ] |
VARS=prefix* [ RANGE=(start,end) ] |
VARS={ name | (name,name,...,name) } |
MDO=mdoname [ MAP=mapname ] } ]
The &CNMREAD verb is used within the CNMPROC procedure to request delivery of the next CNM record. Such a record can arrive unsolicited, or a user procedure can have solicited the record. If no CNM record is immediately available, processing of the procedure is suspended and resumes when the next CNM record arrives, unless the WAIT operand is used. Multiple &CNMREAD statements are present within CNMPROC.
&CNMREAD can also be used from standard NCL user procedures that, having sent CNM data, process any results returned. Having issued the &CNMSEND, &CNMREAD is used to read back any records that were solicited or, particularly if no data is returned, merely the response to the sent CNM request.
&CNMREAD processing always sets the &RETCODE system variable and can set the &SYSMSG variable as described in later notes. If variables are created, &ZVARCNT is set.
Operands:
Specifies a time-out value of nnnn seconds. If this time interval expires before data satisfying the &CNMREAD request arrives, control is returned to the NCL procedure at the next statement and the &RETCODE system variable is set to 12. If a value of 0 is specified, control is returned immediately even if no data is available.
The WAIT operand is invalid when the MDO operand is specified.
Limits: 0 through 9999
Specifies that the record is delivered in character format hexadecimal, with each two characters representing one byte and is divided into 256-character sections. Each of these sections is placed into the next variable specified on the &CNMREAD statement. The first 256 characters (128 bytes) are placed into the first variable, the next 256 characters into the second variable, and so on.
Specifies that vectorization is used to divide the CNM RU at strategic boundaries and place each section into a user variable. All user variable names commence with the prefix $CNM. When this option is used all existing variables with names &$CNMxxxx are deleted. The CNM RU is then examined and new variables created depending upon the RU type and contents as follows:
Contains the 8-byte Deliver RU, or is null if no Deliver RU is present.
Contains the embedded Network Services RU (NSRU). For an NMVT RU, it contains only the first 12 bytes, while for a RECFMS Type 0 it contains only the first 20 bytes of the RU. The remainder of these RUs consists of various CNM subvectors which are available in separate variables. For all other RU types, this variable contains the entire NSRU. However, if the NSRU exceeds 128 bytes in actual length, the variable contains only the first 128 bytes expanded, or 256 hexadecimal characters.
Contains the portion (if any) of the NSRU which exceeds 128 bytes (the first 128 bytes being found in character-format hexadecimal in &$CNMNSRU).
Contain the CNM subvector information for the NMVT and RECFMS Type 0 RUs. Each CNM subvector in the RU is placed in a user variable where the name reflects the contents. Variable names are of the form &$CNMSVxxnn, where xx is the hexadecimal subvector type, and nn is the occurrence number of the vector type in the RU. If a subvector length exceeds 128 bytes then the portion which exceeds 128 bytes is placed in a variable named &$CNMSVxxnnX.
Consider the subvector X'07040000000001'. The length is X'07', the subvector type is X'04', and the character string '07040000000001' would be placed in the variable &$CNMSV0401. If the subvector X'030400' followed, it would be placed in &$CNMSV0402. When all the subvector information has been formatted, the variable &$CNMSVLIST contains a list of the subvector types found and their order. For example, if it contained 040491 this means that 2 type 04 subvectors were found followed by a type 91.
Contain hierarchy information concerning the originating device. Each variable that is set contains the eight-character name of the resource and one of the following four-character type codes:
If the NSRU originated from an LU, then &$CNMHLU is set; otherwise, &$CNMHTPU contains the target PU information. &$CNMHPU contains the name and type of the controlling PU (which may be the same as &$CNMHTPU), &$CNMHLNK contains the PU's link information, and &$CNMHSPU contains the PU's boundary function PU information. These variables are only set where information is available.
Contain externally sourced data pertinent to the NSRU. Your products set these variables under certain conditions. &$CNMNV01 is set if the Network Tracking System (NTS) feature is installed. This vector contains the LU name and session partner (if known) for NSRUs associated with logical units (for example, 3274 alerts and RTM data). &$CNMNV02 can also be set when NTS is installed and contains NTS RTM objective response time information.
Contains the major vector type (that is, X'0080', X'0025') of the MV currently vectored.
Contain the major vector type of the nth MV. nn is the number of the MV.
Contains the hexadecimal length of the MV currently vectored.
Segments the CNM data into the variables nominated on the &CNMREAD statement and sets the user variables as described for a TYPE=VECTOR read.
Specifies that only the response to the CNM data sent using a &CNMSEND statement is returned. Any outstanding CNM RU data is still available to be read with a subsequent &CNMREAD statement.
Nominates the user-specified variables to hold the tokenized CNM record if segmentation is requested. The ARGS operand indicates that the system generates the token names automatically as &1, &2 through to &n, according to the range specified by the RANGE operand.
Tokenization is performed from left to right of the record. If more variables are specified than are required, the excess variables are set to null. If too few variables are specified to contain the data, some information is lost.
Nominates the user-specified variables to hold the tokenized CNM record if segmentation is requested. The VARS=prefix* operand specifies that the system generates the token names automatically as &prefix1, &prefix2 through to &prefixn, according to the range specified by the RANGE operand. The prefix is one to four characters in length and must adhere to the standard NCL variable naming conventions. Tokenization then proceeds as described for the ARGS operand.
Nominates the user-specified variables to hold the tokenized CNM record if segmentation is requested. The VARS=name operand indicates a single specific token name only. Alternatively, a list of specific token names is provided, each name separated by a comma and the entire list enclosed in parentheses. Tokenization then proceeds as described for the ARGS operand.
Formats that the incoming data into an MDO with the name mdoname. If the incoming data is mapped, then the received map name is used to connect to Mapping Services Mapping Support. If the incoming data is not mapped, then the requester is responsible to connect to Mapping Services Mapping Support if necessary. MAP=mapname nominates the map name which defines the mapping of the data object.
The distributed $CNM map defines the MDO received on an &CNMREAD verb.
Examples: &CNMREAD
&CNMREAD TYPE=BOTH VARS=(A,B,C,D,E,F,G,H,I,J)
&CNMREAD ARGS RANGE=(1,12)
&CNMREAD TYPE=VECTOR
&CNMREAD TYPE=RESP
Notes:
When control is returned to the NCL procedure following an &CNMREAD statement the &RETCODE (return code) variable is set to one of the following:
For an &CNMREAD request other than TYPE=RESP, this return code indicates that data has arrived and is now placed in the variables as described for the &CNMREAD statement.
For an &CNMREAD TYPE=RESP request, this return code indicates a positive response was received following an &CNMSEND request.
Indicates that no data is outstanding. This return code is expected when an &CNMREAD request is issued in the following circumstances:
Indicates that some error, such as a negative response, has been encountered. The &SYSMSG variable is set and contains text explaining the actual error. An &CNMCLEAR is not required following such an error as an implicit clear is performed when the &CNMREAD completes.
Is set when the WAIT=nnnn option is used to indicate that the time interval specified expired before any data satisfying the particular request arrived.
An &CNMREAD request issued from CNMPROC always returns with the &RETCODE value set to 0 unless the WAIT=nnnn option was also specified. In this case an &RETCODE value of 12 is possible. The use of an &CNMREAD TYPE=RESP request from CNMPROC serves no useful purpose, as control is returned immediately with &RETCODE set to 0. While you are testing and developing a CNMPROC procedure, you can terminate the current version and invoke a new copy. Use the SYSPARMS CNMPROC=FLUSH command, which is designed to force termination of CNMPROC, followed by a SYSPARMS CNMPROC=procname command to restart CNMPROC.
For a user procedure, a reply to a &CNMSEND satisfies the &CNMREAD request for data. If multiple RUs are returned from a single solicitation, then each can be read in sequence by subsequent &CNMREAD statements. After the last reply RU is read a subsequent &CNMREAD returns with &RETCODE set to 4 (unless further &CNMSEND statements have been issued). Similarly, if multiple &CNMSEND solicitations are performed before issuing any &CNMREAD statements, each &CNMREAD request for data is satisfied by a reply RU until all RUs from all solicitations have been processed. All reply RUs are presented, in the order of their arrival from VTAM, for the first such request before any are returned for the next request. After all RUs from all requests have been processed in this manner a subsequent &CNMREAD completes with &RETCODE set to 4.
While reply RUs for a particular solicitation are available (that is, have not yet been processed by an &CNMREAD request), an &CNMREAD TYPE=RESP returns the response for that solicitation, even when subsequent &CNMSENDs are issued (that is, further requests have queued response information). After all reply RUs are processed for a solicitation, or where the &CNMSEND request did not solicit and an &CNMREAD TYPE=RESP has processed the response, a subsequent &CNMREAD TYPE=RESP returns the response from the next &CNMSEND statement.
Where an &CNMREAD request for data follows a single &CNMSEND request that does not solicit data, the &CNMREAD completes with an &RETCODE value of 4. However, if any subsequent &CNMSEND statement that did solicit data was issued before the &CNMREAD statement, data from the first such request would satisfy the &CNMREAD. In either case, the response information to those intervening requests which did not satisfy a &CNMREAD is lost, unless an error is detected in any such request. Detection of an error condition always results in &RETCODE being set to 8 and the &SYSMSG variable set, regardless of the type of &CNMREAD issued.
You are responsible to maintain synchronization between data sent and received across the CNM interface. The &CNMCLEAR NCL statement can assist in this respect.
If the TYPE=VECTOR or TYPE=BOTH operands are specified, the &$CNMSV* variables created (except for &$CNMSVLIST) have the Modified Data tag set. This setting allows the CNM information in them to be processed using the &ASSIGN verb or the &ZMODFLD system variable. For more information, see the descriptions of &ASSIGN and &ZMODFLD in this reference.
See also the distributed CNMPROC, $NWCNMPR.
| Copyright © 2009 CA. All rights reserved. |
|