SEND—Send output on a session

Purpose

The SEND macroinstruction transmits a request or a response for data or data-flow-control on a session with a logical unit. SEND can also be used by a CNM application program to send a request or a response to the SSCP on the SSCP-LU session. The major options for a SEND macroinstruction are illustrated in Figure 1.

Usage

Before issuing the SEND macroinstruction the application program must set register 13 to the address of an 18-word save area. Refer to Summary of register usage, for information pertaining to the register contents upon return of control.

For further information about the SEND macroinstruction, refer to Using VTAM to communicate with LUs.

VTAM® receives control from the SEND macroinstruction in the addressing mode of the application program that issued the macroinstruction and returns control to the application program in that same mode.

Syntax

Notes:

¹ Operand value can be placed in its RPL field either by specification on an RPL macroinstruction operand or by explicitly setting the field using the IFGRPL DSECT.
² You can code more than one suboperand on BRACKET, but code no more than one from each group.
³ You can code more than one suboperand on OPTCD, but code no more than one from each group.
⁴ You can code more than one suboperand on RESPOND, but code no more than one from each group.
⁵ You can code more than one suboperand on RTYPE, but code no more than one from each group.

The diagram shows the major options for a SEND macroinstruction. — Figure 1. Major SEND options

Input parameters

RPL=rpl_address: Indicates the RPL that specifies which kind of processing SEND is to perform.

The following RPL operands apply to the SEND macroinstruction:

ACB=acb_address

Indicates the ACB that identifies the application program issuing SEND.

AREA=output_data_address

If OPTCD=NBUFFLST, CONTROL=DATA, and STYPE=REQ, AREA specifies the address of the data to be sent. If OPTCD=BUFFLST, CONTROL=DATA, and STYPE=REQ, AREA specifies the address of a buffer list which in turn specifies the data to be sent. This storage can be reused as soon as VTAM has transferred the data to its own buffers (see the following POST=SCHED discussion).

ARG=(register)

The SEND macroinstruction is always directed to one session. The ARG operand specifies the register containing the CID of the session being transmitted to. If the ARG operand is not specified, the CID that is already in the RPLARG field is used.

Note: If your application uses the RPL DSECT, IFGRPL, you must clear the RPLNIB bit if a CID is being inserted into the RPLARG field. For application programs running in supervisor state under a TCB, BRANCH indicates whether authorized path processing is to be used. See Authorized path.

BRANCH

If the macroinstruction is issued in an application program that is running in supervisor state under a TCB, set BRANCH to YES to specify that you should use authorized path processing.

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.

BRACKET

This field indicates whether a chain is the beginning, middle, end, or the only chain in a bracket. This operand is meaningful only when bracket protocols are being used on the session. Refer to Bracket protocols.

BRACKET=(BB,NEB) This chain is the beginning of a bracket.
BRACKET=(NBB,NEB) This chain is the middle of a bracket.
BRACKET=(NBB,EB) This chain is the end of a bracket.
BRACKET=(BB,EB) This chain is the only chain of a bracket.

For all requests in a chain except the first and last requests, (NBB,NEB) is set.

BRACKET=CEB is used to set the conditional end bracket indicator. This can be used only for the last or for the only request in a chain.

CHAIN

Indicates the position of the request within the chain of requests currently being transmitted. For additional information, see Chaining.

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. Also, see Large message performance enhancement outbound (LMPEO) option to understand how VTAM splits a message sent with SEND OPTCD=LMPEO into chained request units.

CHNGDIR

Indicates whether the change-direction indicator is set on in the request sent. Refer to Half-duplex protocols for an explanation of the change-direction indicator.

CHNGDIR=(CMD): Turn on the change-direction indicator in the request to be sent (valid only for a last-of-chain DFSYN request). This corresponds to the SNA-defined change-direction indicator.
CHNGDIR=(NCMD): Turn off the change-direction indicator in the request to be sent. This is the setting for all requests of the chain except the last of chain.

CODESEL

Indicates whether the request being sent on the session is encoded in the standard code (STANDARD) or in some other code (ALT). The application program and the logical unit must have previously agreed what type of code is recognized as the standard code (such as EBCDIC) and what code is recognized as the alternate code (such as ASCII). This operand is meaningful only for CONTROL=DATA,STYPE=REQ.

CODESEL=STANDARD: Indicates that the request being sent on the session is encoded in the standard code (STANDARD).
CODESEL=ALT: Indicates that the request being sent on the session is encoded in some other code (ALT).

CRYPT

This operand applies only if CONTROL=DATA and STYPE=REQ.

CRYPT=YES: Indicates that the data at the location specified by AREA is to be enciphered before it is sent on the session.
CRYPT=NO: Indicates that the data at the location specified by AREA is not to be enciphered before it is sent on the session.

See "Redbooks®" for details and a warning about the use of this operand.

ECB

Indicates that an ECB is posted when an asynchronous (OPTCD=ASY) SEND operation is posted as being complete. You cannot specify both ECB and EXIT on a single macroinstruction.

ECB=event_control_block_address: Specifies that VTAM is to post an event control block (ECB). Event_control_block_address is the location of the ECB to be posted. The ECB can be any fullword of storage aligned on a fullword boundary.
ECB=INTERNAL: Specifies that VTAM is to post an internal ECB.

EXIT=exit_routine_address

Indicates the address of an RPL exit routine that is scheduled when an asynchronous (OPTCD=ASY) SEND operation is posted as being complete. You cannot specify both ECB and EXIT on a single macroinstruction. For details about the EXIT operand, refer to the RPL macroinstruction description in this chapter.

OPTCD=BUFFLST

OPTCD=NBUFFLST

Specifies whether the buffer list option is used. OPTCD=BUFFLST allows FM data to be sent from a number of discontiguous buffers. The RPL AREA field points to a buffer list which is a contiguous set of 16-byte control blocks, called buffer list entries. The RPL RECLEN field must specify a buffer list length that is a nonzero multiple of 16 bytes. For a detailed description of the use of the BUFFLST option, refer to The buffer-list (BUFFLST) option.

OPTCD=CA

OPTCD=CS

When the SEND operation is completed successfully, (RTNCD,FDB2)=(X'00',X'00') or (X'04',X'04'), the session is placed in continue-any mode (OPTCD=CA) or continue-specific mode (OPTCD=CS) for the types of input specified by the RTYPE field. More than one type of input can be specified. VTAM switches the modes for all specified types of input. No switching occurs if RTYPE=(NDFSYN,NDFASY,NRESP) is in effect for the SEND. The SEND is posted complete when the last request unit associated with the SEND is handled by VTAM; for OPTCD=LMPEO and OPTCD=BUFFLST, more than one request unit can be sent by SEND.

OPTCD=CONTCHN

OPTCD=NCONTCHN

Specifies the action VTAM should take on receipt of a negative response to a chain being sent with OPTCD=LMPEO. VTAM either continues to send the chain (OPTCD=CONTCHN) or aborts the chain, (OPTCD=NCONTCHN) possibly by sending a zero-length LIC request unit. (Refer to Exception conditions for details.)

OPTCD=FMHDR

OPTCD=NFMHDR

When OPTCD=FMHDR is used, the receiver is notified that the data contains a function management header.

OPTCD=LMPEO

OPTCD=NLMPEO

Specifies whether the large message performance enhancement outbound option is to be used. OPTCD=LMPEO allows VTAM to reformat FM data into one or more request units to form a chain or partial chain of RUs. (A detailed description of LMPEO is contained in Large message performance enhancement outbound (LMPEO) option.) When OPTCD=(LMPEO,BUFFLST) is specified, the FM data to be sent is pointed to indirectly by the RPL AREA field which points to a buffer list. If OPTCD=(LMPEO,NBUFFLST) is specified, the RPL AREA field points directly to the FM data to be sent. (See The buffer-list (BUFFLST) option for a detailed description of buffer list operation.) POST=SCHED or POST=RESP can be used with OPTCD=LMPEO. If a negative response is received before a SEND is posted complete, the POST=SCHED or POST=RESP and OPTCD=CONTCHN or OPTCD=NCONTCHN operands determine what action is to be taken. For a detailed description, refer to Exception conditions.

OPTCD=RSPQUED

OPTCD=NRSPQUED

Specifies whether VTAM should search for any queued responses. When the SEND is posted complete, if OPTCD=RSPQUED is specified, the RPL flag RPLRSPNM is set if there are any responses on the normal-flow inbound response queue. The RPL flag RPLRSPQR is set if there are any responses on the normal-flow inbound data queue.

The application program can test these RPL flags when the SEND is posted complete to see if there are any queued responses.

OPTCD=SYN

OPTCD=ASY

If the SYN option code is set, control is returned to the application program when the SEND operation has completed. If the ASY option code is set, control is returned as soon as VTAM has accepted the request. After the SEND operation has completed, the ECB is posted or the RPL exit routine is scheduled, depending on the setting of the ECB-EXIT field. The SEND is posted complete when the last request unit associated with the SEND is handled by VTAM; for OPTCD=LMPEO and OPTCD=BUFFLST, more than one request unit can be sent by SEND. Refer to the RPL macroinstruction description in this chapter for details about OPTCD=SYN or OPTCD=ASY.

It might take VTAM a relatively long time to complete the SEND operation. Because the SEND-issuing task or SRB issuing the macroinstruction with the SYN option code is suspended until processing completes, use the ASY option code if the SEND-issuing task or SRB cannot be allowed to be suspended for that long.

OPTCD=USERRH

OPTCD=NUSERRH

Specifies whether the user RH option is used. If OPTCD=USERRH is specified, VTAM includes a 3-byte user RH header from the RPL (RPLURH) or from a buffer list entry for each RU sent. FM data and data-flow-control requests and responses can be sent using OPTCD=USERRH. The RPL CONTROL operand must be set to the type of request or response unit being sent. The RUCAT field in the user RH must be set to FMD or DFC. If OPTCD=(USERRH,BUFFLST), the initial RH is specified in the RH field of certain buffer list entries. For a detailed description of the user RH option, refer to The user RH (USERRH) option.

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

POST

Defines at what point in the output operation the SEND macroinstruction is to be completed. The OPTCD=SYN or OPTCD=ASY, ECB, and EXIT operands govern the action to be taken when the macroinstruction completes. Figure 2 summarizes the use of the POST operand, including defaults assumed. See also Scheduled versus responded output operations.

For OPTCD=LMPEO, the POST operand applies to the last generated request unit for the SEND. For OPTCD=BUFFLST, this operand applies to the last request unit associated with the buffer list.

POST=RESP

Indicates that the macroinstruction generally completes only when VTAM returns a response for the request on the session. (The macroinstruction is posted complete under certain exception conditions, such as the processing of a Clear, or the receipt of a negative response to an earlier request in the chain, or session termination. A RECEIVE does not obtain the response; the response information posts in the SEND RPL. The RESPLIM field of the NIB, used to establish the session, limits the number of SEND POST=RESP macroinstructions for normal-flow requests that can be outstanding at one time on the session. If the limit is exceeded, VTAM posts the SEND complete with (RTNCD,FDB2)=(X'14',X'44'). When you specify asynchronous handling (ASY option code in effect) you must use a CHECK macroinstruction before you can reuse the output data area (pointed to by the AREA field).

POST=SCHED

Indicates that the macroinstruction completes as soon as the output data area (pointed to by the AREA field) and the RPL are available for reuse. This occurs prior to the actual transmission of the data. A RECEIVE macroinstruction (or an RESP exit routine) is required to obtain the response. Only one SEND POST=SCHED macroinstruction can be outstanding for a given session at one time. A second SEND POST=SCHED macroinstruction issued before the first has been completed is rejected by VTAM with (RTNCD,FDB2)= (X'14',X'3C'). The limit of one SEND POST=SCHED macroinstruction outstanding at a time for a session does not apply to the sending of responses.

RECLEN=output_data_length

If OPTCD=NBUFFLST, CONTROL=DATA, and STYPE=REQ, RECLEN specifies the number of bytes of data to be sent from the field pointed to by AREA. The maximum number that can be set is decimal 65532, unless OPTCD=LMPEO is specified. If OPTCD=LMPEO and the maximum RU size specified in BIND is not 0 (that is, VTAM splits the message if required), then a larger amount of data can be sent. If the RECLEN field is set to 0, the AREA field is not examined.

If OPTCD=BUFFLST, CONTROL=DATA, and STYPE=REQ, RECLEN specifies the length of the buffer list whose address is in AREA; this must be a nonzero multiple of 16.

RECLEN must be set to 0 for sending exception requests. Refer to Exception conditions.

RESPOND

Details about the RESPOND operand are given in What a response contains. When a request is sent (STYPE=REQ), this field indicates the desired response:

RESPOND=(x,x,x,QRESP) and the NIB used to establish the session specified PROC=ORDRESP: The response is sent in order with respect to normal-flow (DFSYN) requests.
RESPOND=(x,x,x,NQRESP) or the NIB used to establish the session specified PROC=NORDRESP: The response is sent in order with respect to other responses and not necessarily in order with respect to normal-flow (DFSYN) requests.
RESPOND=(EX,FME,RRN,x): Only negative responses type 1 and 2 are expected (see the following note).
RESPOND=(EX,FME,NRRN,x): Only a negative response type 1 is expected.
RESPOND=(EX,NFME,RRN,x): Only a negative response type 2 is expected.
RESPOND=(EX,NFME,NRRN,x): Invalid. Should not be specified. VTAM assumes (NEX,NFME,NRRN,x).
RESPOND=(NEX,FME,RRN,x): Definite response type 1 or 2 is expected (see the following note).
RESPOND=(NEX,FME,NRRN,x): Definite response type 1 is expected.
RESPOND=(NEX,NFME,RRN,x): Definite response type 2 is expected.
RESPOND=(NEX,NFME,NRRN,x): No response expected.

If a normal-flow data-flow-control request is sent, RESPOND=(NEX,FME,NRRN,NQRESP) is assumed unless NIB PROC=ORDRESP is specified in the NIB used to establish the session. In that case, the value in RESPOND is used.

Note: Although VTAM and certain logical units permit response types 1 and 2 to be sent separately, sending multiple responses per chain is not allowed by SNA protocols and should not be used.

If response types 1 and 2 are returned and POST=RESP for the SEND RPL, the first response completes the SEND operation. If the two responses are returned together, both are received as one response; that is, the second response is also reflected in the completed RPL. If the second response does not accompany the first, however, the second response must be received by a separate RECEIVE macroinstruction or by an RESP exit routine.

When a response is sent (STYPE=RESP), this field indicates the response type:

RESPOND=(x,x,x,QRESP or NQRESP): The queued response indicator must be set to the same value as received in the request.
RESPOND=(EX,FME,RRN,x): This is a negative response type 1 or 2.
RESPOND=(EX,FME,NRRN,x): This is a negative response type 1.
RESPOND=(EX,NFME,RRN,x): This is a negative response type 2.
RESPOND=(EX,NFME,NRRN,x): Invalid. Rejected with (RTNCD,FDB2)=(X'14',X'3B').
RESPOND=(NEX,FME,RRN,x): This is a positive response type 1 or 2.
RESPOND=(NEX,FME,NRRN,x): This is a positive response type 1.
RESPOND=(NEX,NFME,RRN,x): This is a positive response type 2.
RESPOND=(NEX,NFME,NRRN,x): Invalid. Rejected with (RTNCD,FDB2)=(X'14',X'3B').

RTYPE

When a SEND is issued, the RTYPE field indicates the type or types of input for which the session's CA-CS mode is to be switched. For a description of input types, see DFSYN, DFASY, and RESP types of RUs.

SEQNO=sequence_number

Specifies the sequence number sent with a request or response. The number specified by this operand is used when sending a normal-flow response or when sending an expedited DFC request or response. The number is not used when sending a normal-flow request; VTAM generates the sequence number in that case.

Usually the sequence number received for a request (and placed into the SEQNO field of the RPL used to receive the request) is the sequence number that should be sent with any response to that request. The correct sequence number to use is dictated by SNA protocols.

SIGDATA=signal_data

Contains the signal data that is to be sent when CONTROL=SIGNAL, STYPE=REQ is specified. The signal data can be a decimal, hexadecimal, or character constant of 1–4 bytes or a register (the value in the register is used). 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. If you omit this operand, the SSENSEO field defaults to 0.

This field can also provide application-specified sense values for negative responses to CINIT or for UNBIND. Refer to the sections on the CLSDST or TERMSESS macroinstructions in this chapter for additional information.

SSENSMO=system-sense_modifier_value

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

Designates whether a request (STYPE=REQ) or a response (STYPE=RESP) is to be sent. The CONTROL field governs the request code if a data-flow-control request or response is sent. Some of these requests are described in more detail in Communicating with logical units.

STYPE=REQ: Must be specified if OPTCD=LMPEO or OPTCD=BUFFLST.
If OPTCD=USERRH is specified, the RPL flag set by the STYPE operand is ignored. However, the user RH must specify that the RU is a request unit for OPTCD=LMPEO or OPTCD=BUFFLST.
STYPE=RESP: Sends a response indicating whether a normal or expedited flow has been processed successfully. The response can be either positive or negative.

STYPE=REQ,CONTROL

The following operands show the types of control data requests:

CONTROL=BID: Sends a Bid request. The receiver interprets this as a request on the part of the sender for permission to begin a new bracket on the session.
CONTROL=BIS: Sends a Bracket Initiation Stopped request to indicate that the sender stops initiating any new brackets on the session.
CONTROL=CANCEL: Sends a Cancel request. The receiver might interpret this request as an indication that the receiver should discard the chain that it is receiving on the session. A Cancel request is sent instead of a request indicating CHAIN=LAST when a chain is canceled.
CONTROL=CHASE: Sends a Chase request. When the sender receives a response to this request, it can be certain that no normal-flow requests were previously sent on the session (before CHASE) for which the session partner later returns a response.
CONTROL=DATA: Sends a Data request. This must be specified if OPTCD=LMPEO or OPTCD=BUFFLST is coded.
CONTROL=LUS: Sends a Logical Unit Status (LUSTAT) request. An LUSTAT request can convey the same type of information as does a negative response. It can also convey information about the availability of the sender or its components on this session. An LUSTAT is sent when the sender wants to indicate an exception or a change-of-status condition, but cannot do so with a negative response (for example, the session-partner is sending requests and asking for no responses). The SSENSEO, SSENSMO, and USENSEO fields are used for LUSTAT indicators.
CONTROL=QC: Sends a Quiesce Complete request. This informs the receiver that the sender no longer transmits normal-flow requests on the session. Once this request is sent, no other normal-flow requests can be transmitted to the session partner until the session partner returns a Release Quiesce (RELQ) request.
CONTROL=QEC: Sends a Quiesce at End-of-Chain request. This informs the receiver that when it is through transmitting the current chain, it is to stop transmitting further normal-flow requests on the session and return a Quiesce Complete (QC) request.
CONTROL=RELQ: Sends a Release Quiesce request. This informs the receiver that it can begin transmitting normal-flow requests on the session.
CONTROL=RSHUTD: Sends a Request Shutdown request to the primary end of the session. This requests the primary logical unit to terminate the session (for example, issue a CLSDST macroinstruction).
CONTROL=RTR: Sends a Ready to Receive request. This indicates that the sender is now willing to receive a new bracket on the session.
CONTROL=SBI: Sends a Stop Bracket Initiation request to request that the receiver not begin any new brackets on the session.
CONTROL=SHUTC: Sends a Shutdown Complete request to the primary end of the session. This acknowledges the receipt of a SHUTD request and indicates the secondary logical unit is ready to accept session termination.
CONTROL=SHUTD: Sends a Shutdown request to the secondary end of the session. The secondary logical unit interprets this as an indication that the primary logical unit is about to terminate the session. When a secondary logical unit is ready to accept session termination, it returns a Shutdown (SHUTC) request.
CONTROL=SIGNAL: Sends a Signal request containing the 4 bytes of signal data in the SIGDATA field of the RPL.

STYPE=RESP,CONTROL

Sends a response indicating whether a previously received normal-flow request has been processed successfully. A positive or negative response of any type (definite response 1, 2, or both) can be sent; however, only certain combinations are valid within SNA protocols. The CONTROL field operands, DATA, BID, BIS, CANCEL, CHASE, LUS, QC, and RTR, are explained in the preceding section.

STYPE=RESP,CONTROL

Sends a response indicating whether a previously received expedited-flow data-flow-control request has been processed successfully. Only a positive or negative definite response 1 is allowed. The CONTROL field operands, QEC, RELQ, RSHUTD, SBI, SHUTC, SHUTD, and SIGNAL, are explained in the preceding section.

Note: A response to an expedited-flow data-flow-control request on a session can be sent only if the NIB used to establish the session specified PROC=APPLRESP; otherwise, VTAM sends the response on behalf of the application program. Sending or receiving a Clear request eliminates the requirement to send a response to a previously received expedited-flow data-flow-control request.

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.

Examples

SEND1    SEND   RPL=RPL1,STYPE=REQ,CONTROL=DATA,                       C
               AREA=OUTBUF,RECLEN=60,CHAIN=ONLY,                       C
               RESPOND=(EX,FME,NRRN,NQRESP),POST=SCHED

SEND1 sends a 60-byte data request on the session identified in RPL1's ARG field. SEND1 is completed as soon as VTAM has scheduled the output operation and OUTBUF and RPL1 are available for reuse. The RESPOND field indicates that only negative response type 1 should be returned; that is, if the request is processed normally, no response is returned. A RECEIVE RTYPE=RESP macroinstruction (or RESP exit routine) is required to obtain the negative response, if one is returned.

Completion information

The actual or implied setting of the POST field governs what constitutes the “completion” of the SEND operation. Refer to the description of the POST operand in the preceding section for details.

After the SEND operation is completed, the following RPL fields are set:

The value 34 (decimal) is set in the REQ field, indicating a SEND request.
The sequence number is placed in the SEQNO field except when OPTCD=LMPEO. For OPTCD=LMPEO, SEQNO is set by VTAM with the sequence number of the last RU generated from the message, and OBSQVAL is set by VTAM with the sequence number of the first RU generated from the message.
The USER field contains the value that was set in the USERFLD field of the NIB when the session was established.
The RTNCD and FDB2 fields are set as indicated in Return codes and sense fields for RPL-based macroinstructions.

The following fields can also be set when a response has been received (POST=RESP):

The RESPOND field indicates the type of response that has been returned. This field is set in exactly the same manner as indicated in the preceding discussion for sending a response.
The control field is set to the request code value received in the response. However, this should be the same value as was in the original SEND if the logical unit obeys SNA protocols.
If a negative response has been returned, the SSENSEI, SSENSMI, and USENSEI fields are set indicating system-sense information, system-sense modifier, and user-sense information. For additional information about these fields, refer to Return codes and sense fields for RPL-based macroinstructions.

Registers 0 and 15 are also set as indicated in Handling errors and special conditions.