RPL—Create a request parameter list

Purpose

Every request that an application program makes for session establishment or communication must refer to a request parameter list (RPL). See Figure 1 for the list of macroinstruction categories.

Usage

The application program uses the RPL to describe most of the requests that it makes to VTAM®. The application program can, for example, issue a RECEIVE and indicate an RPL. The RPL shows VTAM which session to obtain input from, where to place the input data, how to notify the application program once the operation is completed, and other options to be followed during processing of the request. If the RPL contains a request code in its REQ field, an EXECRPL macroinstruction can be used in place of the RPL-based macroinstruction indicated in REQ.

An application program can create many RPLs; a separate RPL can, in fact, be created for every RPL-based request in the application program. At the other extreme, one RPL can serve for all RPL-based requests in the program (assuming that all the requests are synchronous—that is, issued with OPTCD=SYN set). This multiple use is possible because each RPL-based request can itself modify fields of the RPL to which it points. You can think of the RPL as a list form of all RPL-based macroinstructions.

If the same RPL is used for multiple requests, it is good programming practice to reset the RPL control block fields after the request has completed. All ACB, NIB, and RPL fields that are not used by a particular macroinstruction should be set to 0 unless otherwise indicated.

The RPL macroinstruction builds an RPL during assembly. The RPL is built on a fullword boundary. Also, the GENCB macroinstruction can generate an RPL during program execution. Requests for RPL modification can be made as part of an RPL-based request or by the MODCB macroinstruction. Either way involves naming an RPL field and specifying its new value. Also, the IFGRPL DSECT can alter RPL field values. Be aware that every operand of the RPL macroinstruction represents a field in the RPL it generates. Subsequent requests to modify any RPL field use the keyword of the operand corresponding to the field being modified.

VTAM sets default values for most of the RPL fields when the RPL is initially assembled or generated. These values are underlined in the operand descriptions. After an RPL-based macroinstruction uses an RPL, VTAM might modify some of the RPL's fields. These fields are listed at the end of each macroinstruction description in this chapter and are summarized in Figure 1.

Although all of the RPL operands are optional (with the exception of AM=VTAM) and can be specified with any of the RPL-based macroinstructions, each of the RPL-based macroinstructions requires that certain RPL fields be set when the macroinstruction is executed. These fields are identified in Figure 1 at the end of this macroinstruction description.

Input parameters

 

Format: Expressions involving registers cannot be used with the RPL macroinstruction.

ACB=acb_address

Associates the request that uses this RPL with an ACB. If you omit this operand, the ACB field is set to 0.

AM=VTAM

Indicates that a VTAM RPL is built. This operand is required.

AAREA=alternate_data_area_address

When used by a CLSDST OPTCD=PASS macroinstruction, AAREA indicates the location of an 8-byte area containing the symbolic name of the target PLU. When used by an INTRPRET macroinstruction, AAREA indicates a work area where VTAM places the interpreted data sequence. When used by a REQSESS macroinstruction, AAREA must be set to 0. When used by an OPNDST macroinstruction, AAREA indicates a work area where VTAM places a negotiable BIND response if the NIB specified PROC=NEGBIND.

When used by OPNDST OPTCD=RESTORE, AAREA points to the area allocated by the application to hold the recovery data that is used during session recovery.

If you omit this operand, the AAREA field is set to 0.

For XRF, the AAREA field in the RPL is initialized by the application program to provide the address of the input area where the SWITCH response information should be placed.

AAREALN=alternate_data_area_length

Indicates the length (in bytes) of the data area identified by the AAREA operand. When AAREA is used as an input area for an INTRPRET or OPNDST (for a negotiable BIND response) macroinstruction, VTAM uses this length to determine whether the data to be placed there is too long to fit.

When used by OPNDST OPTCD=RESTORE, the area obtained must be large enough to hold all the recovery data.

If you omit this operand, the AAREALN field is set to 0.

For XRF, the AAREALN field in the RPL is initialized by the application program to contain the length of the input area pointed to by AAREA. The AAREA field is ignored if AAREALN=0 (no switch response information is returned).

AREA=data_area_address

When used by a SIMLOGON, REQSESS, or a CLSDST OPTCD=PASS macroinstruction, AREA indicates the address of an area containing user data that is to be sent to the PLU (through the SSCP) in the user data field of the CINIT request.

When used by a RECEIVE macroinstruction, AREA indicates the address of the area into which data is to be read. When used by a SEND OPTCD=NBUFFLST macroinstruction, AREA indicates the address of the area from which data is to be written. When used by a SEND OPTCD=BUFFLST macroinstruction, AREA indicates the address of a buffer list which further indicates the data to be sent.

When used by an INQUIRE macroinstruction, AREA indicates where the data obtained by INQUIRE is to be placed.

When used by an INTRPRET macroinstruction, AREA indicates the address of an area containing data to be interpreted by VTAM.

When used by an RCVCMD macroinstruction, AREA contains the address of an area into which a header and a VTAM operator message is placed.

When used by a SENDCMD macroinstruction, AREA contains the address of an area containing a header and a VTAM operator command.

If you omit this operand, the AREA field is set to 0.

AREALEN=data_area_length

Indicates the length (in bytes) of the data area identified by the AREA operand. The AREALEN operand is meaningful only for RECEIVE, RCVCMD, and INQUIRE macroinstructions; VTAM uses this length to determine whether the data it is placing in the area is too long to fit. AREALEN=0 means that no input data area is available. If you omit this operand, the AREALEN field is set to 0.

ARECLEN=data_length

Indicates the length (in bytes) of the data area identified by the AAREA parameter, provided by a CLSDST OPTCD=PASS macroinstruction.

BRACKET

This operand is used when a normal-flow request is sent by SEND on a session.

BRACKET=(BB)

The begin-bracket indicator is set in the request.

BRACKET=(NBB)

The begin-bracket indicator is not set in the request.

BRACKET=(EB)

The end-bracket indicator is set in the request.

BRACKET=(NEB)

The end-bracket indicator is not set in the request.

BRACKET=(CEB)

The conditional-end-bracket indicator is set in the request.

BRACKET=(NCEB)

The conditional-end-bracket indicator is not set in the request. For details, see Bracket protocols.

When the session is the SSCP-LU session for a CNM application program, BRACKET=(NBB,NEB) must be specified, explicitly or by default.

BRANCH

For application programs running in supervisor state under a TCB, BRANCH indicates whether authorized path processing is to be used. See Authorized path.

BRANCH=YES

When the macroinstruction is issued, VTAM processes the macroinstruction using authorized path. For programs running under an SRB rather than under a TCB, the macroinstruction is processed in this manner automatically, regardless of the actual setting of the BRANCH field.

BRANCH=NO

When the macroinstruction is issued, VTAM does not process the macroinstruction using authorized path.

CHAIN

This field is set when a request is sent by SEND on a session. It denotes the request's relative position within the chain currently being sent.

CHAIN=FIRST

The request is first within the current chain.

CHAIN=MIDDLE

The request is in the middle of the current chain.

CHAIN=LAST

The request is last within the current chain.

CHAIN=ONLY

The request is the only request of the chain.

When the session is the SSCP-LU session for a CNM application program, CHAIN=ONLY must be specified, explicitly or by default.

CHNGDIR

This field is set when a normal-flow request is sent by SEND on a session.

CHNGDIR=CMD

A change-direction indicator is set in the request. For details, see Half-duplex protocols.

CHNGDIR=NCMD

When the session is the SSCP-LU session for a CNM application program, CHNGDIR=(NCMD) must be specified, explicitly or by default.

CODESEL

Indicates which data code is used in data requests being sent by SEND.

CODESEL=ALT

The alternate data code is used.

CODESEL=STANDARD

The standard data code is used.

When the session is the SSCP-LU session for a CNM application program, CODESEL=STANDARD must be specified explicitly, or by default.

CONTROL

Indicates whether data, data-flow-control, or session-control requests and responses are to be sent on a session. Data and data-flow-control requests (BID, BIS, CANCEL, CHASE, LUSTAT, QC, RTR, QEC, RELQ, RSHUTD, SBI, SHUTC, SHUTD, SIGNAL) are sent with the SEND macroinstruction. The session-control requests (CLEAR, RQR, SDT, STSN) are issued by the SESSIONC macroinstruction. Session-control responses (BIND, SDT, and STSN) are also sent using the SESSIONC macroinstruction. CONTROL=UNBIND is specified in a read-only RPL when the SCIP exit routine is scheduled with CONTROL=UNBIND. See Communicating with logical units, and the SEND and SESSIONC macroinstructions for an explanation of the requests designated by CONTROL.

CONTROL=DATA is the default.

When the session is the SSCP-LU session for a CNM application program, CONTROL=DATA must be specified, explicitly or by default.

CONTROL=SWITCH causes the backup XRF session to become the primary XRF session. The former primary XRF session, if it is still active, is terminated with an UNBIND(CLEANUP). This command can be issued only on a backup XRF session. If issued on a primary XRF session, it is rejected.

CRYPT

Indicates whether data is to be enciphered before it is sent by SEND on a session.

CRYPT=YES

Data is to be enciphered.

CRYPT=NO

Data is not to be enciphered.

When the session is an SSCP-LU session for a CNM application program, CRYPT=NO must be specified or defaulted.

For details about the use of this operand, see "Redbooks®".

ECB

ECB=event_control_block_address

Indicates the location of an event control block (ECB) to be posted by VTAM when the request associated with this RPL is completed. The ECB can be any fullword of storage aligned on a fullword boundary.

The ECB field and the EXIT field share the same RPL field. If asynchronous handling of the request has been specified (ASY option code in the RPL), the ECB-EXIT field is used in this manner:

• If you specify ECB=address, VTAM uses the field as the address of an external ECB; you check and clear this ECB yourself (for example, with CHECK for the RPL).
• If you specify EXIT=address, VTAM uses the field as the address of the RPL exit routine, and schedules the routine as indicated under the EXIT operand description.

ECB=INTERNAL

If you specify ECB=INTERNAL, VTAM uses the ECB-EXIT field as an internal ECB; you must issue CHECK for the RPL to check and clear this ECB.

If synchronous handling has been specified (SYN option code in the RPL), VTAM flags the RPL to be processed as if ECB=INTERNAL were specified. VTAM uses the ECB-EXIT field as an ECB which is cleared and checked automatically.

VTAM clears internal ECBs when:

• It begins processing any RPL-based macroinstruction
• The RPL is checked.

However, VTAM clears external ECBs only when the RPL is checked. (RPL checking is done at request completion by VTAM for synchronous request handling, and is done by the user issuing CHECK for asynchronous request handling.) Users of external ECBs must, therefore, be sure that the external ECB is cleared (with CHECK for the RPL or with assembler instructions) before the next RPL-based macroinstruction is issued.

For further information about asynchronous processing, refer to Handling errors and special conditions.

EXIT=rpl_exit_routine_address

Indicates the address of a routine to be scheduled when the request represented by this RPL is completed.

If the SYN option code has been specified, the exit routine is not used; should you specify an address anyway, the address is overwritten before the synchronous request completes. (VTAM uses the ECB-EXIT field as an internal ECB in this situation—see the ECB operand discussion on page in this topic.) The RPL exit routine is scheduled only if asynchronous handling of the request has been specified.

If the EXIT operand is specified, the ECB operand must not be specified. (The EXIT field and the ECB field occupy the same field in the RPL.)

For further information about asynchronous processing, refer to Handling errors and special conditions.

IBSQAC=SET

IBSQAC=TESTSET

IBSQAC=INVALID

IBSQAC=IGNORE

IBSQAC=TESTPOS

IBSQAC=TESTNEG

IBSQAC=RESET

OBSQAC=SET

OBSQAC=TESTSET

OBSQAC=INVALID

OBSQAC=IGNORE

OBSQAC=TESTPOS

OBSQAC=TESTNEG

OBSQAC=RESET

These fields are used by a SESSIONC macroinstruction to designate which type of Set and Test Sequence Numbers (STSN) request or response is being sent on a session. The setting of the IBSQAC field relates to the inbound sequence number. The setting of the OBSQAC field relates to the outbound sequence number. SET is the default.

IBSQVAL=inbound_sequence_number

OBSQVAL=outbound_sequence_number

When SESSIONC is used to send certain STSN requests or responses, the inbound and outbound sequence numbers can be specified by these fields. Specify any decimal integer 0 - 65535 inclusive, or any hexadecimal value that does not exceed X'FFFF'.

If either of these operands is omitted, the associated field is set to 0.

NIB=nib_address

Identifies the NIB whose NAME or CID field indicates the resource that is to be the object of an RPL-based macroinstruction. It is used with the CLSDST, INQUIRE, INTRPRET, OPNDST, OPNSEC, REQSESS, SESSIONC, SIMLOGON, and TERMSESS macroinstructions.

The CID and the NIB address occupy the same physical field (RPLARG) in the RPL control block. VTAM can distinguish between an NIB address and a CID only through a particular bit (RPLNIB). For this reason, this book calls the field the NIB field when an NIB address is being inserted into it and the ARG field when a CID is being inserted into it. When NIB=address appears on a SIMLOGON macroinstruction, for example, the bit is set to indicate that the field contains an NIB address. When ARG=(register) is coded on a SEND macroinstruction, for example, the bit is cleared to indicate that the field contains a CID. (Register notation must be used with ARG, because CIDs are not available until program execution.)

When dealing with the NIB and ARG operands, remember if only one physical field is involved, always use the NIB keyword to insert an NIB address and always use the ARG keyword to insert a CID. This rule also applies to the GENCB and MODCB macroinstructions.

Note: If your application uses the RPL DSECT, IFGRPL, you must set the RPLNIB bit if an NIB address is being inserted into the RPLARG field, and clear RPLNIB if a CID is being inserted into RPLARG.

If you omit this operand, the NIB field is set to 0.

OPTCD=option code or (option code, . . . )

Indicates options that are to affect the requests made using this RPL.

Code as indicated in the assembler format table. If only one option code is specified, the parentheses can be omitted.

RPL   ACB=ACB1,OPTCD=(SPEC,SYN,CS),AM=VTAM
RPL   ACB=ACB1,OPTCD=SPEC,AM=VTAM

Note: The MODCB macroinstruction can be used to change some option codes set in the RPL after it has been built.

OPTCD=ACCEPT

OPTCD=ACQUIRE

Indicates whether OPNDST is being issued to accept a session-establishment request or to acquire a session by issuing a session-initiation request.

For XRF requests, the NIB BNDAREA field must point to a BIND specifying a control vector or vectors included with the XRF-session-activation control vector (including correlation ID) initialized appropriately. OPTCD=BACKUP must be specified on the OPNDST OPTCD=ACQUIRE if the session establishment request is for a backup XRF session. The request fails if the secondary logical unit cannot support XRF. OPTCD=BACKUP or OPTCD=NBACKUP does not apply for OPNDST OPTCD=ACCEPT and is ignored. However, if a SIMLOGON OPTCD=BACKUP is issued, it drives a LOGON exit routine that contains OPNDST OPTCD=ACCEPT.

OPTCD=CA

OPTCD=CS

The CA (continue-any) and CS (continue-specific) option codes determine which type of RECEIVE is required to obtain input from the session. This operand is used with the RTYPE operand for SEND, RECEIVE, and RESETSR. It is also used with OPNDST and OPNSEC. For further information, refer to Continue-any mode versus continue-specific mode.

CA places the session in a mode for a particular type of input wherein that input is subject to a RECEIVE OPTCD=ANY as well as a RECEIVE OPTCD=SPEC macroinstruction. This mode is called continue-any mode.

CS places the session into a mode for a particular type of input wherein only RECEIVEs for that type of input that are directed specifically to the session can be used to obtain input from it. This mode is called continue-specific mode.

OPTCD=CONALL

OPTCD=CONANY

Used with SIMLOGON and with OPNDST OPTCD=ACQUIRE to control the number of sessions established by these macroinstructions when an NIB is used. When CONANY is set, a session is initiated for the first available logical unit in the NIB list. Control is passed to the application program's LOGON exit routine, if one exists, when the resulting CINIT has been generated. When CONALL is set, a session is initiated for each available logical unit in the NIB list.

OPTCD=COND

OPTCD=UNCOND

OPTCD=UNBIND

Indicates the action to be taken when a TERMSESS macroinstruction is issued. If OPTCD=COND, the application program acting as the primary end of the session determines if and when to terminate the session. If OPTCD=UNCOND, VTAM terminates the session. If OPTCD=UNBIND, an UNBIND request is sent from the SLU to the PLU to terminate the session; control returns to the application program when the response to the UNBIND request is received.

OPTCD=APPSTAT

OPTCD=CIDXLATE

OPTCD=COUNTS

OPTCD=DEVCHAR

OPTCD=LOGONMSG

OPTCD=SESSKEY

OPTCD=STATUS

OPTCD=TERMS

OPTCD=TOPLOGON

OPTCD=USERVAR

Indicates the action that VTAM is to take when an INQUIRE macroinstruction is issued.

OPTCD=MTS

OPTCD=NMTS

The MTS option code only applies to the REQSESS and CLSDST OPTCD=PASS macroinstructions. If you code OPTCD=MTS, VTAM expects valid MTS override data in an area pointed to by NIBMTSAR and formatted to match the ISTMTS DSECT. The NMTS option code tells VTAM not to expect any MTS override data.

OPTCD=NBACKUP

OPTCD=BACKUP

This parameter applies only when trying to initiate an XRF backup session. NBACKUP means that the session establishment request is for a primary XRF session or a non-XRF session. BACKUP indicates that the OPNDST request is to initiate a backup XRF session.

A backup XRF session must not be requested by the application until the OPNDST for the primary XRF session has been posted complete.

OPTCD=NBUFFLST

OPTCD=BUFFLST

Indicates, when a SEND macroinstruction is issued, whether FM data is sent by VTAM from a number of discontiguous buffers. See The buffer-list (BUFFLST) option for more information.

OPTCD=NCONTCHN

OPTCD=CONTCHN

Indicates, when a SEND macroinstruction is issued with OPTCD=LMPEO, whether VTAM continues to send a chain upon receipt of a negative response.

OPTCD=NFMHDR

OPTCD=FMHDR

Indicates to VTAM how the format bit in the request header (RH) is to be set. This option applies only to SEND for data requests and data responses, and should be used to notify the logical unit that the request or response contains or does not contain (FMHDR and NFMHDR, respectively) a function management header. If FMHDR is set, the format bit is set on in the request header and is delivered to the receiver.

When the session is the SSCP-LU session for a CNM application program, FMHDR must be specified.

Note: VTAM does not prevent setting FMHDR for sending responses on LU-LU sessions; however, because this is not an SNA protocol, it should not be used. Because the format indicator is on in all data-flow-control requests and responses, the application program must ensure that the desired value is in the RPL used for SEND. (It might have been set by a previously received data-flow-control request or response.)

OPTCD=NIBTK

OPTCD=TRUNC

OPTCD=KEEP

Indicates the action to be taken when a RECEIVE macroinstruction is completed with input that is too large to fit in the input data area. TRUNC causes the excess data to be discarded. KEEP causes the excess data to be saved for subsequent RECEIVE macroinstructions. NIBTK causes the PROC=TRUNC or PROC=KEEP setting in the NIB to be used either to truncate or keep the data. RCVCMD must specify TRUNC.

OPTCD=NKEEPSRB

OPTCD=KEEPSRB

Indicates whether VTAM should return to the application under the same SRB in which VTAM was invoked. This parameter is meaningful only for synchronous SRB (non cross-memory) invocations. Asynchronous SRB and synchronous cross-memory SRB invocations return under the same SRB. Preserving the SRB provides the following environmental advantages to the invoker:

• The FRR stack is maintained if KEEPFRR=YES is specified on the ACB.
• The linkage stack is maintained, thus preserving any existing linkage stack entries. Refer to the z/OS MVS Programming: Extended Addressability Guide for additional details regarding linkage stack considerations.

Note: To provide this function, VTAM utilizes SUSPEND and RESUME. Suspending the SRB (as opposed to exiting and returning under a different SRB) allows the environment to be preserved. However, SUSPEND and RESUME may impact performance. Take this into account when making use of this parameter for performance sensitive API invocations (such as SEND or RECEIVE).

OPTCD=NLMPEO

OPTCD=LMPEO

Indicates, when a SEND macroinstruction is issued, whether the large message performance enhancement outbound option is to be used. The effect of this option is to allow VTAM to split the FM data being sent into a chain of RUs. See Large message performance enhancement outbound (LMPEO) option for more information.

OPTCD=NRSPQUED

OPTCD=RSPQUED

Indicates, when a SEND macroinstruction is issued, whether VTAM searches for any queued responses. When a SEND OPTCD=RSPQUED macroinstruction is posted complete, the RPL flag RPLRSPNM is set if there are any responses on the normal flow inbound response queue and the RPL flag RPLRSPQR is set if there are any responses on the normal flow inbound data queue. When the SEND is posted complete, the application program must test these RPL flags explicitly to see whether there are any queued responses.

OPTCD=NSENSE

OPTCD=SENSE

When a CLSDST macroinstruction is issued with OPTCD=RELEASE to reject a CINIT request, OPTCD=NSENSE or SENSE indicates whether sense values were specified with the SSENSEO, SSENSMO, and SSENSEO operands. If OPTCD=NSENSE is specified, VTAM rejects the CINIT with a sense value of X'08010000'. If OPTCD=SENSE is specified, VTAM rejects the CINIT with the application-specified sense values in the SSENSEO, SSENSMO, and SSENSEO fields of the RPL.

Note: Only a nonzero sense code is allowed for OPTCD=SENSE. If you specify OPTCD=SENSE, and a sense code of X'00000000', VTAM rejects the CLSDST with RTNCD/FDB2=X'14',X'50'. (This return code indicates that the RPL field is not valid).

OPTCD=NSONCODE

OPTCD=SONCODE

In the following cases, indicates whether an UNBIND type code is specified in the RPL with the PARMS=(SONCODE=code) operand:

• When a TERMSESS macroinstruction is issued with OPTCD=UNBIND
• When a CLSDST macroinstruction is issued with OPTCD=RELEASE.

If OPTCD=NSONCODE, VTAM uses a SON code of hex 01. If OPTCD=SONCODE, VTAM uses the SON code specified in the RPL with the PARMS=(SONCODE=code) operand.

OPTCD=NUSERRH

OPTCD=USERRH

Indicates, when a SEND macroinstruction is issued, whether the application program specifies the RH when sending FM data or data-flow-control requests and responses. See The user RH (USERRH) option for more information.

Note: The RH field can be set up by using the RPLURH DSECT label.

OPTCD=Q

OPTCD=NQ

Indicates the action VTAM is to take when the application program issues RECEIVE, RCVCMD, SIMLOGON, REQSESS, or OPNDST OPTCD=ACCEPT and the operation cannot be completed immediately.

OPTCD=QALL

OPTCD=QSESSLIM

OPTCD=QNOTENAB

Indicates the action to be taken when a SIMLOGON OPTCD=Q is issued and the logical unit that is the object of this simulated logon request is at its session limit or not enabled for sessions. This option determines whether the SIMLOGON is queued for both or just one of these conditions.

OPTCD=QUIESCE

OPTCD=STOP

OPTCD=START

OPTCD=HOLD

Indicates the action VTAM takes when a SETLOGON macroinstruction is issued. QUIESCE causes VTAM to indicate that the application program is inhibited for any new sessions. The STOP version of SETLOGON causes any application program issuing INQUIRE OPTCD=APPSTAT to be told that new sessions should not be initiated with the application program that issued SETLOGON STOP. The START version of SETLOGON causes any application program issuing INQUIRE OPTCD=APPSTAT to be told that your application program is active. START can also be used in conjunction with SETLOGON=HOLD to pace session requests. HOLD causes CINIT and BIND requests to be queued, and the LOGON and SCIP exits not to be driven for session requests until a subsequent SETLOGON OPTCD=START is issued. SETLOGON OPTCD=STOP does not stop the scheduling of the LOGON or SCIP exit routines. STOP can be used only for private application program protocols and is not enforced by VTAM.

OPTCD=RELEASE

OPTCD=PASS

Indicates whether a session-initiation request is generated when a CLSDST macroinstruction is issued to terminate a session.

OPTCD=RELRQ

OPTCD=NRELRQ

Indicates the action to be taken when a SIMLOGON macroinstruction is issued and the logical unit that is the object of this simulated logon request has an established session or pending active session with another PLU, and is at its session limit. The effect of this option is to determine whether the application program that is in session with the logical unit is to be notified of your request.

Note the difference in spelling between the RELRQ-NRELRQ RPL option, and the related exit routine. The latter is coded in the EXLST macroinstruction as RELREQ.

OPTCD=SPEC

OPTCD=ANY

When the RPL is used by an OPNDST OPTCD=ACCEPT macroinstruction, this option code indicates whether any session or a specific session can be accepted.

When the RPL is used by a RECEIVE macroinstruction, this option code indicates whether input from any session or a specific session can complete the RECEIVE.

OPTCD=SYN

OPTCD=ASY

Indicates whether VTAM should synchronously or asynchronously handle any request made using this RPL. For further information, refer to:

• How a synchronous operation works
• How an asynchronous operation works
• Advantages and disadvantages of different forms of operation
• Cautions, restrictions and techniques
• Synchronous versus asynchronous operations.

SYN

Synchronous handling means that when a request is made, control is not returned to the application program until the requested operation has completed (successfully or otherwise). The application program should not use the CHECK macroinstruction for synchronous requests: VTAM automatically performs this checking (which includes clearing the internal ECB; the ECB-EXIT field in the RPL is used as an internal ECB) as discussed in the RPL ECB and EXIT operand descriptions. When control is returned to the application program, registers 0 and 15 contain completion codes. See Handling errors and special conditions, for further information.

Some macroinstructions can take a relatively long time to complete. Because the SRB or task issuing the macroinstruction with the SYN option code is suspended until processing completes, use the ASY option code if the SRB or task cannot be allowed to be suspended for that long. Also use the ASY option when the macroinstruction is issued within an exit identified in an ACB exit list.

ASY

Asynchronous handling means that after VTAM schedules the requested operation, control is immediately passed back to the application program. When the event has completed, VTAM does one of the following:

• If an ECB address is specified for the RPL, VTAM posts a completion indicator in the event control block. The application program must issue a CHECK or a system WAIT macroinstruction to determine whether the ECB has been posted. If a system WAIT or similar technique is used, the application program must still issue a CHECK on the RPL to mark the RPL inactive so that it can be reused and to cause entry to the SYNAD or LERAD exit routine if the requested operation ends with a logic or other error.
• If the EXIT operand is in effect for the RPL, VTAM schedules the exit routine indicated by this operand. This exit routine should issue the CHECK macroinstruction so that the RPL can be reused, and also to cause automatic entry into a LERAD or SYNAD exit routine if the requested operation ends with a logic or other error. CHECK should be issued in the exit routine even if the application program has no LERAD or SYNAD routine, because CHECK returns a code indicating whether an error occurred. See Handling errors and special conditions, for further information.

Note: After an asynchronous request is accepted and before it is completed, do not modify the RPL used by the request. A modification during this interval could cause VTAM to be unable to complete the request in a normal manner, which in turn causes VTAM to terminate the application program.

ASY is recommended for CONTROL=SWITCH.

PARMS=(SONCODE=code)

The application program can set the UNBIND SON code by specifying OPTCD=SONCODE and PARMS=(SONCODE=code), where code is the 1-byte UNBIND type code to be used by VTAM on an UNBIND RU. See the description of the UNBIND RU in SNA Formats for definitions of those SON codes. VTAM does not validate the code specified in this parameter.

If PARMS=(SONCODE=X'FE') is specified, system and user sense codes are set with the existing SSENSEO, SSENSMO, and USENSEO RPL fields.

PARMS=(THRDPTY=NONOTIFY)

PARMS=(THRDPTY=NOTIFY)

Indicates for CLSDST OPTCD=PASS whether the application program receives notification when the new session is established between the target PLU and the SLU.

POST

This field is used with the SEND macroinstruction to determine when the SEND of a request is to be posted as being complete.

POST=RESP

Post the SEND as being complete when a response is received for the request.

POST=SCHED

Post the SEND as being complete as soon as the RPL and buffer area are available for reuse.

RECLEN=data_length

When used by a REQSESS, SIMLOGON, INTRPRET, or CLSDST OPTCD=PASS macroinstruction, RECLEN indicates the length (in bytes) of the user data or sequence contained in the area indicated by the AREA operand.

When used by a SEND OPTCD=NBUFFLST or SENDCMD macroinstruction, RECLEN indicates the length (in bytes) of the data that begins at the address indicated by AREA. RECLEN tells VTAM how much data to transfer. When used by a SEND OPTCD=BUFFLST macroinstruction, RECLEN indicates the length of the buffer list.

If you omit this operand, the RECLEN field is set to 0.

RESPOND

When a response is sent by SEND or SESSIONC, the RESPOND field indicates the characteristics of the response. When a request is sent by SEND or SESSIONC, the RESPOND field indicates characteristics of the expected response to that request.

For details about the RESPOND field, refer to What a response contains.

When the session is the SSCP-LU session for a CNM application program, FME and NRRN are required.

RTYPE

When a RECEIVE macroinstruction is issued, the RTYPE field designates the type or types of input eligible to satisfy the macroinstruction (only one type can actually satisfy the RECEIVE). When a SEND or RESETSR macroinstruction is issued, the RTYPE field indicates the type or types of input for which the session's CA-CS mode is to be switched.

DFSYN, NDFASY, and NRESP are the defaults.

For further information about these input types, see DFSYN, DFASY, and RESP types of RUs.

SEQNO=sequence_number

Indicates the 2-byte sequence number of a response or of an expedited-flow DFC request.

If an application program responds to a request, it must set the SEQNO field for the SEND STYPE=RESP or SESSIONC STYPE=RESP with the appropriate sequence number to identify the request it is responding to.

The SEQNO field can be set to any value by the application program for the sending of an expedited data-flow-control request. VTAM uses the contents of this field for the TH sequence number of the request. Specify any decimal integer 0 - 65535 inclusive. If you omit this operand, the SEQNO field is set to 0.

For certain non-SNA 3270 logical units, the sequence number field wraps to 0 after it reaches 255. The high-order byte of the field is always set to 0. The application program should always set both bytes in the SEQNO field for all sessions, including sessions with those non-SNA 3270 logical units.

SIGDATA=signal_data

When the SEND macroinstruction is used to send a SIGNAL request to a logical unit, this field contains the signal data to be sent.

Specify a decimal, hexadecimal, or character constant of 1-4 bytes. If fewer than 4 bytes are specified, the value is padded to 4 bytes as if the constant were an assembler language DC statement with a length attribute of 4.

SSENSEO

This field is set by VTAM for a Logical Unit Status (LUSTAT) request and informs the logical unit of the type of error that caused the exception condition. These error types are described in Return codes and sense fields for RPL-based macroinstructions. SSENSEO=0 is the default.

This field can also be used to provide application-specified sense values for negative responses to CINIT or for UNBIND.

SSENSMO=system-sense_modifier_value

This field is set by VTAM for a Logical Unit Status (LUSTAT) request. The value set in this field is used in conjunction with the SSENSEO setting to describe the specific type of error that caused the exception condition. The meanings assigned to the SSENSMO values are described in detail in SNA Formats If this operand is omitted, the SSENSMO field is set to 0.

This field can also be used to provide application-specified sense values for negative responses to CINIT or for UNBIND. Refer to the TERMSESS macroinstructions in this chapter.

Specify any decimal integer 0–255 inclusive, or specify a 1-byte hexadecimal constant.

STYPE=REQ

STYPE=RESPONSE

This field designates the type of output to be sent on a session by SEND or SESSIONC. The application program uses STYPE=REQ to send a request. STYPE=RESP is used when a response is to be sent. Only REQ applies to CONTROL=SWITCH.

USENSEO=user-sense_value

This field is set by VTAM for a Logical Unit Status (LUSTAT) request. In most instances the user-sense field is user-defined and can be used to inform the logical unit that an exception condition is being indicated for an application-program-related error that is not an SNA-defined error, or it can be used to further modify the SNA-defined system-sense and system-sense modifier values. See Return codes and sense fields for RPL-based macroinstructions, for more information. If this operand is omitted, the USENSEO field is set to 0.

This field can also be used to provide application specified sense values for negative responses to CINIT or for UNBIND. Refer to the TERMSESS macroinstructions in this chapter.

Specify any decimal integer 0 - 65535 inclusive, or specify a 2-byte hexadecimal or character constant.