SLI_RECEIVE

This verb transfers data or a status code to the application program. SLI_RECEIVE also provides the current status of the session to the Windows® LUA application.

An SLI_RECEIVE verb for an LU-LU session flow can only be issued on an opened session. If the SLI_OPEN initiation type is primary with SSCP access, the application program can issue an SLI_RECEIVE verb for SSCP-LU normal flow data even when an SLI_OPEN verb is pending.

Supplied Parameters

The application supplies the following parameters:
lua_verb
LUA_VERB_SLI

The verb-code indicator for the LUA verbs.

lua_verb_length
The length of the verb control block. This number must equal the length expected by the SLI for the SLI_RECEIVE verb.
lua_opcode
LUA_OPCODE_SLI_RECEIVE
lua_correlator
A value that an LUA application program can supply to help correlate this verb with other information that the program supplies. This parameter is ignored by the LUA interface.
lua_luname
The local LU name in ASCII. If the name contains fewer than 8 characters, you must pad it with blanks. LUA examines this parameter only if lua_sid is 0. Using the lua_luname parameter on all verbs helps make debugging easier, especially when multiple LUs are configured.
lua_sid
The session ID returned by SLI_OPEN that identifies the session to be used. If this parameter is 0, the lua_luname parameter is used for identification.
lua_max_length
The length of the buffer used to receive data.
lua_data_ptr
A pointer to the buffer where the SLI places data received from the host application. Because this buffer is used for data and SNA commands, the contents of the buffer are usually in EBCDIC.
lua_post_handle
If asynchronous notification is to be accomplished by events, lua_post_handle contains the handle of the vent to be signaled.
lua_flag1.bid_enable
A flag that specifies whether the LUA should reuse the SLI_BID verb control block on behalf of the LUA application program.
lua_flag1.nowait
A flag that tells the SLI to post the SLI_RECEIVE verb with the return code NO_DATA when there is no data to be read. If the first RU of a multiple-RU chain arrives and the lua_flag1.nowait option has been selected, the lua_flag1.nowait option is ignored. The SLI_RECEIVE verb returns IN_PROGRESS and completes asynchronously after all RUs of the chain arrive. If chaining is allowed, the lua_flag1.nowait option should not be used.
The lower-order half-byte of lua_flag1 contains flags that describe the message session and flow. The flow flags describe the flow or flows on which the LUA application program can accept a message. At least one of the following flags must be set, but the set flags must not overlap flags that are set in another active SLI_RECEIVE verb.
lua_flag1.sscp_exp
A flag that specifies SSCP-expedited flow.
lua_flag1.sscp_norm
A flag that specifies SSCP-normal flow.
lua_flag1.lu_exp
A flag that specifies LU-expedited flow
lua_flag1.lu_norm
A flag that specifies LU-normal flow.

Returned Parameters

If the verb completed successfully, the following parameters are returned:
lua_data_length
The length of the data being received.
lua_th
A 6-byte parameter that contains the SNA transmission header (TH) for the message.
lua_rh
A 3–byte parameter that contains the SNA request/response header (RH) for the message.
lua_message_type
The type of SNA data and commands. When the SLI application program wants to send data, the application program must set this parameter. The valid message types follow:
  • LUA_MESSAGE_TYPE_LU_DATA
  • LUA_MESSAGE_TYPE_SSCP_DATA
  • LUA_MESSAGE_TYPE_RSP
  • LUA_MESSAGE_TYPE_BID
  • LUA_MESSAGE_TYPE_BIS
  • LUA_MESSAGE_TYPE_CANCEL
  • LUA_MESSAGE_TYPE_CHASE
  • LUA_MESSAGE_TYPE_LUSTAT_LU
  • LUA_MESSAGE_TYPE_LUSTAT_SSCP
  • LUA_MESSAGE_TYPE_QC
  • LUA_MESSAGE_TYPE_QEC
  • LUA_MESSAGE_TYPE_RELQ
  • LUA_MESSAGE_TYPE_RTR
  • LUA_MESSAGE_TYPE_SBI
  • LUA_MESSAGE_TYPE_SIGNAL

LU_DATA, LUSTAT_LU, LUSTAT_SSCP, and SSCP_DATA are not SNA commands.

lua_flag2.async
A flag that specifies that this verb completes asynchronously.
lua_flag2.sscp_exp
A flat that specifies SSCP-expedited flow.
lua_flag2.sscp_norm
A flag that specifies SSCP-normal flow.
lua_flag2.lu_exp
A flag that specifies LU-expedited flow.
lua_flag2.lu_norm
A flag that specifies LU-normal flow.
lua_prim_rc
The primary return code, set by the verb function. For details, see LUA Verb Return Codes.
lua_sec_rc
The secondary return code, set by the verb function. For details, see LUA Verb Return Codes.

Usage Notes

SLI_RECEIVE receives responses, SNA commands, and request unit data from the host. SLI_RECEIVE also provides the status of the session to the Windows® LUA application. An SLI_OPEN request must complete before SLI_RECEIVE can be issued. However, if SLI_OPEN is issued with lua_init_type set to LUA_INIT_TYPE_PRIM_SSCP, an SLI_RECEIVE over the SSCP normal flow may be issued as soon as SLI_OPEN returns an IN_PROGRESS.

Data is received by the application in one of four session flows. The four session flows, from highest to lowest priority are:
  • SSCP expedited
  • LU expedited
  • SSCP normal
  • LU normal

The data flow type that SLI_RECEIVE verb will process is specified in lua_flag1. The application can also specify whether it wants to look at more than one type of data flow. When multiple flow bits are set, the highest priority is received first. When SLI_RECEIVE completes processing, lua_flag2 indicates the specific type of flow for which data has been received by the Windows® LUA application.

If SLI_BID successfully completes before SLI_RECEIVE is issued, the Windows® LUA interface can be instructed to reuse the last SLI_BID’s verb control block. To do this, issue SLI_RECEIVE with the lua_flag1.bid_enable parameter set to 1.

When using lua_flag1.bid_enable parameter, the SLI_BID storage must not be freed because the last SLI_BID verb’s verb control block is used. Also, when using the lua_flag1.bid_enable parameter, the successful completion of SLI_BID will be posted.

If SLI_RECEIVE is issued with lua_flag1.nowait when no data is available to receive, LUA_NO_DATA will be the secondary return code set by the Windows® LUA interface.

If status is available, the application must read it. Until the application reads the status by issuing an SLI_BID or SLI_RECEIVE, all other operations are rejected, except for:
  • SLI_SEND verbs on the SSCP flow
  • SLI_CLOSE

When the primary return code is STATUS, the only SLI_RECEIVE parameters returned are lua_prim_rc, lua_sec_rc, and lua_sid. An active SLI_RECEIVE verb can be posted with the STATUS return code only when there is no active SLI_BID verb.

When the value of the primary return code is STATUS, the possible values for the secondary return code are:
  • READY

    Indicates the SLI session is now ready for processing all additional commands. The READY status is issued after a prior NOT_READY status was received.

  • NOT_READY
    Indicates that a CLEAR command or an UNBIND command with a type value of X'02' or X'01' was received from the host. The SLI session is suspended.
    • When a CLEAR arrives, the session is suspended until an SDT command is received.
    • When an UNBIND type X'02' (UNBIND with BIND forthcoming) arrives, the session is suspended until BIND, optional CRV and STSN, and SDT commands are received. Any user extension routines must be reentrant.
    • When an UNBIND type X'01' (UNBIND normal) arrives and the SLI_OPEN verb for this session specified an lua_session_type of LUA_SESSION_TYPE_DEDICATED, the session is suspended until BIND, optional CRV and STSN, and SDT commands are received. User extension routines provided to process these commands must be reentrant.

      After the CLEAR, UNBIND type X'02', or UNBIND type X'01' arrives, the application can send SSCP data before reading the NOT_READY status, and can both send and receive SSCP data after reading the NOT_READY status.

  • SESSION_END_REQUESTED

    Indicates that a SHUTD command was received from the host. The host is requesting that the SLI application end the session as soon as convenient.

    When the application is ready to end the session, it should issue an SLI_CLOSE or an SLI_CLOSE Normal.

  • INIT_COMPLETE

    Indicates that an RUI_INIT verb completed during SLI_OPEN processing. This status is returned only when the SLI_OPEN lua_init_type parameter is LUA_INIT_TYPE_PRIM_SSCP.

    After this status is received, the application can send and receive data on the SSCP-normal flow.

In addition to the return codes, additional SNA sense data can be returned if a request unit sent by the host application has been converted into an exception request (EXR). An EXR is indicated by having the SLI_RECEIVE complete with the following returned verb parameters values:
Parameters
lua_prim_rc
OK (X'0000')
lua_sec_rc
OK (X'00000000')
lua_rh.rri
bit off (request unit)
lua_rh.sdi
bit on (sense data included)
Under these conditions, the request has been converted into an EXR and up to 7 bytes of information is returned in the application buffer. The format of the information in the data buffer is:
  • Bytes 0—3 contain sense data defining the error detected. If LUA converted the request into an EXR, the sense data is one of the following values:
    Sense Data Value of byes 0 - 3
    LUA_MODE_INCONSISTENCY X'08090000'
    LUA_BRACKET_RACE_ERROR X'080B0000'
    LUA_BB_REJECT_NO_RTR X'08130000'
    LUA_RECEIVER_IN_TRANSMIT_MODE X'081B0000'
    LUA_CRYPTOGRAPHY_FUNCTION_INOP X'08480000'
    LUA_SYNC_EVENT_RESPONSE X'10010000'
    LUA_RU_DATA_ERROR X'10020000'
    LUA_RU_LENGTH_ERROR X'10020000'
    LUA_INCORRECT_SEQUENCE_NUMBER X'20010000'
    LUA_LCC_NOT_SUPPORTED X'20010000'
The information returned to bytes 4 through 6 in lua_peek_data contain up to the first 3 bytes of the original request unit.

OLD USAGE NOTE INFO

If LUA_STATUS is the primary return code, the secondary return code can be one of the following: LUA_READY, LUA_NOT_READY, LUA_SESSION_END_REQUESTED or LUA_INIT_COMPLETE. In addition, if LUA_STATUS is the primary return code, the following parameters are used:
  • lua_sec_rc
  • lua_sid

LUA_READY is returned after an LUA_NOT_READY status and indicates that the SLI is again ready to perform all commands.

LUA_NOT_READY indicates that the SLI session is suspended because the SLI has received either an SNA CLEAR command or an SNA UNBIND command with an X'02' UNBIND type (UNBIND with BIND forthcoming). Depending on what caused the suspension, the session can be reactivated as follows:
  • When the suspension is caused by an SNA CLEAR, receiving an SNA SDT reactivates the session.
  • When an SNA UNBIND type BIND forthcoming causes suspension of the session and the SLI_OPEN that opened the session is completed, the session is suspended until the SLI receives a BIND and SDT command. The session can also optionally receive an STSN command. As a result, user-supplied routines issued with the initial SLI_OPEN must be re-entered because they will be recalled.

The application can send SSCP data after a CLEAR or UNBIND type BIND forthcoming arrives and before the NOT_READY status is read. The application can send and receive SSCP data after reading a NOT_READY.

When an SNA UNBIND type BIND forthcoming arrives before completion of the SLI_OPEN that opened the session, LUA_SESSION_FAILURE (not LUA_STATUS) is the primary return code.

LUA_SESSION_END_REQUESTED indicates that the application received an SNA SHUTD from the host. The Windows® LUA application should issue SLI_CLOSE to close the session when convenient.

LUA_INIT_COMPLETE is returned only when lua_init_type for SLI_OPEN is LUA_INIT_TYPE_PRIM_SSCP. The status means that the SLI_OPEN has been processed sufficiently to allow SSCP data to now be sent or received.

Of the seven bytes of data in lua_peek_data, bytes 0 through 3 contain sense data defining the error detected. The following table indicates the possible values of bytes 0 through 3.

Sense Data Value of byes 0 - 3
LUA_MODE_INCONSISTENCY X'08090000'
LUA_BRACKET_RACE_ERROR X'080B0000'
LUA_BB_REJECT_NO_RTR X'08130000'
LUA_RECEIVER_IN_TRANSMIT_MODE X'081B0000'
LUA_CRYPTOGRAPHY_FUNCTION_INOP X'08480000'
LUA_SYNC_EVENT_RESPONSE X'10010000'
LUA_RU_DATA_ERROR X'10020000'
LUA_RU_LENGTH_ERROR X'10020000'
LUA_INCORRECT_SEQUENCE_NUMBER X'20010000'

Bytes 4–6 contain up to the first 3 bytes of the original request unit that caused the error.