RPL fields set by VTAM

All of the RPL operands described in the preceding section can be supplied by the application program and cause the RPL fields to be set when the RPL macroinstruction is assembled or when the RPL-based macroinstruction is executed. Some of the fields described in the preceding section that are initially set by the application program can be (for certain macroinstructions) reset by VTAM® before the macroinstruction is completed. Additional RPL fields cannot be set by the application program but can be examined by it during program execution. VTAM uses both types of fields to return information to the application program upon completion of RPL-based macroinstruction processing. See Figure 1 and Figure 2 for a description of these fields.

In some cases, fields set by VTAM upon the completion of one macroinstruction cause erroneous results if the application program reuses the same RPL for another macroinstruction without again initializing the field. (Only the SSENSEI, SSENSMI, USENSEI, SSENSEO, SSENSMO, USENSEO, FDBK, FDB2, and RTNCD fields are cleared by VTAM, and no fields are reset to their original values by VTAM.)

For example, before a RECEIVE is issued, the RTYPE field is set by the application program to indicate the types of input (DFSYN, DFASY, RESP) that are eligible to satisfy the RECEIVE. The application program might indicate all three. When the RECEIVE is completed, VTAM uses the same field to indicate the type of input that actually satisfied the RECEIVE; if a RESP response was received, for instance, VTAM would reset the RTYPE field to RTYPE=(NDFSYN, NDFASY, RESP). Should the application program issue another RECEIVE with the same RPL and fail to reset the RTYPE field to its intended setting, the second RECEIVE could receive only responses.

VTAM can alter the following RPL fields prior to posting an RPL-based macroinstruction complete. These RPL fields are listed in alphabetical order. Additional information about the particular operation to which the field modifications apply is found in the following tables:

See individual macroinstruction descriptions in this chapter for details. Figure 4 and Figure 5 show which fields are set up by VTAM in the read-only RPL supplied in various exits. Further information can be found under the exit routine descriptions given in Using exit routines. The read-only RPL information is similar to that which would have been placed into the RPL of a RECEIVE that had just received the RU that caused the exit routine to be scheduled.

Field name

Contents

AREA

When an OPNDST or OPNSEC macroinstruction completes, AREA is set to the address of an NIB or a list of NIBs. (The NIB field is replaced by the CID). If the RPL for the OPNDST or OPNSEC is to be reused for subsequent RPL-based operations, the AREA field must be reset to indicate the data area to be used for the operation.

ARECLEN

The number of bytes of data returned by OPNDST with a NIB specifying PROC=(NEGBIND) or by INTRPRET.

ARG

The communication identifier (CID) for the session is provided by the OPNDST or OPNSEC macroinstruction that establishes the session. The CID, a 32-bit value, is generated by VTAM when the session is established and is used by the application program to indicate the identity of the session for subsequent requests. It is also returned by VTAM when a RECEIVE OPTCD=ANY completes successfully. The ARG field is also used to return the CID of the session determined by INQUIRE OPTCD=TOPLOGON.

BRACKET

When a request is received, the BRACKET field indicates the status of bracket indicators.

CHAIN

When a RECEIVE RTYPE=DFSYN macroinstruction has received a request, the CHAIN field indicates the request's relative position within the chain.

CHNGDIR

When a request or response is received, the CHNGDIR field indicates the status of a change-direction indicator (CMD).

CODESEL

When a RECEIVE macroinstruction is completed, the CODESEL field indicates whether the data received is in standard or alternate code.

CONTROL

After a RECEIVE macroinstruction has completed, CONTROL is set to indicate which data or data-flow-control RU was received. The CONTROL field is also set after a SEND POST=RESP or SESSIONC STYPE=REQ completes. If the logical unit obeys SNA protocols, the CONTROL field is the same as in the original SEND or SESSIONC.

CRYPT

When a RECEIVE macroinstruction for a data request is completed, this indicates whether the RH enciphered data indicator was present for the request.

ECB/EXIT

This field has been used as an internal ECB if ECB=INTERNAL was specified, or if OPTCD=SYN was specified.

FDBK

Status information for INQUIRE OPTCD=APPSTAT. This field is cleared by VTAM when the processing of the macroinstruction begins.

FDB2

A specific error return code returned by all RPL-based macroinstructions. This is one of the feedback fields described in Handling errors and special conditions, and in Return codes and sense fields for RPL-based macroinstructions. A DSECT containing labeled EQU instructions for each FDB2 return code is described in Control block formats and DSECTs (ISTUSFBC). These DSECT labels can be used instead of the numerical values that are cited for FDB2 throughout this book.

IBSQAC

When a SESSIONC STYPE=REQ,CONTROL=STSN is completed, the IBSQAC field contains the logical unit's response regarding the inbound sequence number for this session.

IBSQVAL

When a SESSIONC STYPE=REQ,CONTROL=STSN is completed and IBSQAC is set to TESTPOS or TESTNEG, the IBSQVAL field contains the logical unit's version of the inbound sequence number for this session.

OBSQAC

When a SESSIONC STYPE=REQ,CONTROL=STSN is completed, the OBSQAC field contains the logical unit's response regarding the outbound sequence number for this session.

OBSQVAL

When a SESSIONC STYPE=REQ,CONTROL=STSN is completed and OBSQAC is set TESTPOS or TESTNEG, the OBSQVAL field contains the logical unit's version of the outbound sequence number for the session. When SEND is used with OPTCD=LMPEO, the OBSQVAL field is set by VTAM with the sequence number of the first RU generated.

OPTCD

When a RECEIVE macroinstruction for data is completed and a function management header is present, the OPTCD field is set to indicate FMHDR. The OPTCD field is also set when data-flow-control requests or their responses are received. Therefore, the field corresponds to the format indicator in the request header of the received request or response.

RECLEN

After an INQUIRE macroinstruction has completed, RECLEN contains the length of the requested information (such as the session parameters). After a SETLOGON OPTCD=QUIESCE macroinstruction has completed, RECLEN contains the number of CINIT requests queued for the application program. After a RCVCMD macroinstruction has completed, RECLEN contains the amount of input data. After a RECEIVE macroinstruction has completed, RECLEN contains the total length of data in VTAM's buffers (prior to the discarding of the data if TRUNC is in effect) plus the length of data already moved by that RECEIVE macroinstruction. This value might be greater than AREALEN, indicating the presence of excess data (the value in RECLEN represents the total length of excess data plus the data in AREA).

REQ

A value returned by all RPL-based macroinstructions (except EXECRPL and CHECK) that identifies the type of macroinstruction. This field shows which type of macroinstruction last used the RPL. These are the values that are set:

Value: Macroinstruction
21 (X'15'): SETLOGON
22 (X'16'): SIMLOGON
23 (X'17'): OPNDST
25 (X'19'): CHANGE
26 (X'1A'): INQUIRE
27 (X'1B'): INTRPRET
31 (X'1F'): CLSDST
34 (X'22'): SEND
35 (X'23'): RECEIVE
36 (X'24'): RESETSR
37 (X'25'): SESSIONC
39 (X'27'): SENDCMD
40 (X'28'): RCVCMD
41 (X'29'): REQSESS
42 (X'2A'): OPNSEC
44 (X'2C'): TERMSESS

RESPOND

When a SESSIONC STYPE=REQ, a SEND POST=RESP, or a RECEIVE macroinstruction has received a response, the RESPOND field indicates the characteristics of the response. When a RECEIVE macroinstruction has received a request, the RESPOND field indicates the characteristics of the expected response.

RPLURH

¹ When a RECEIVE macroinstruction is completed, the 3-byte RPLURH field is set with the contents of the RH used for the input operation.

RTNCD

A general return code returned by all of the RPL-based macroinstructions. This is one of the feedback fields described in Return codes and sense fields for RPL-based macroinstructions, and in Handling errors and special conditions.

RTYPE

When a RECEIVE macroinstruction is completed, the RTYPE field indicates the type of input that caused the completion.

SEQNO

When a RECEIVE macroinstruction has received a request or a response, the SEQNO field contains the sequence number of that RU. When a SEND or SESSIONC macroinstruction is used to send a request (STYPE=REQ), the SEQNO field contains the VTAM-supplied sequence number of the request. When using SEND OPTCD=LMPEO, SEQNO is set by VTAM with the sequence number of the last RU sent.

SIGDATA

When a Signal request is received, the SIGDATA field contains the signal information sent on the session.

SSENSEI

When a SEND POST=RESP, RECEIVE, or SESSIONC STYPE=REQ macroinstruction receives a negative response, or when a RECEIVE receives an exception request or an LUSTAT data-flow-control request, the SSENSEI, SSENSMI, and USENSEI fields are set with sense information. Similarly, under some circumstances, the INQUIRE, INTRPRET, CLSDST, OPNDST, OPNSEC, REQSESS, SIMLOGON, SETLOGON, and TERMSESS macroinstructions can be posted complete with sense information. For further details about these fields, refer to Return codes and sense fields for RPL-based macroinstructions. VTAM clears these fields when the processing of the macroinstruction begins.

SSENSEO

This field is always set to 0 when an RPL-based macroinstruction is completed.

SSENSMI

SSENSMO

This field is always set to 0 when an RPL-based macroinstruction is completed.

USENSEI

When a SEND POST=RESP, RECEIVE, or SESSIONC STYPE=REQ macroinstruction receives a negative response, or when a RECEIVE receives an exception request or an LUSTAT data-flow-control request, the SSENSEI, SSENSMI, and USENSEI fields are set with sense information. Similarly, under some circumstances, the INQUIRE, INTRPRET, CLSDST, OPNDST, OPNSEC, REQSESS, SIMLOGON, SETLOGON, and TERMSESS macroinstructions can be posted complete with sense information. For further details about these fields, refer to Return codes and sense fields for RPL-based macroinstructions. These fields are cleared by VTAM when the processing of the macroinstruction begins.

USENSEO

This field is always set to 0 when an RPL-based macroinstruction is completed.

USER

Upon the completion of a SEND, RECEIVE, RESETSR, or SESSIONC macroinstruction, this field contains whatever value you previously placed in the USERFLD field of the NIB used to establish the session. See the description of the USERFLD operand of the NIB macroinstruction for more information.