SLI_BID

This verb tells an SLI application program that a message is pending to be read by SLI_RECEIVE or that status is presented. SLI_BID is used to preview the pending data so the application can formulate a strategy for receiving the data. When data or status arrives for the SLI application program, SLI_BID is posted if an eligible SLI_RECEIVE is not active. The application program issues an SLI_BID verb after the session opens successfully (or during the SLI_OPEN if the initiation type is primary with SSCP access) to indicate that the application program will use the bid mechanism.

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_BID verb.
lua_opcode
LUA_OPCODE_SLI_BID

The operation code for the verb.

lua_correlator
A value that links the verb with other user-supplied information. This parameter is not used 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_post_handle
This is a 4-byte handle that is used to post the completion of asynchronous verbs.

Returned Parameters

If the verb completed successfully, the following parameters are returned:
lua_prim_rc
The primary return code, set by the verb function.
lua_sec_rc
The secondary return code, set by the verb function.
lua_data_length
The length of the peek data received.
lua_peek_data
This parameter contains up to the first 12 bytes of RU data to be read. The length of the data returned in this parameter is in the lua_data_length parameter.
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. 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_BIND
  • 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
  • LUA_MESSAGE_TYPE_STSN

The SLI receives and responds to the BIND and STSN requests through the LUA interface extension routines.

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

lua_flag2
A 1-byte flag that contains bits used as output parameters. At verb completion, all bits that are not described by value are reserved and must be set to 0. The flag in the high-order half-byte follows:
lua_flag2.async
A flag that indicates that this verb completes asynchronously
The low-order half-byte contains flags that describe the message session and flow. One of the following flags is returned:
lua_flag2.sscp_exp
Specifies SSCP-expedited flow
lua_flag2.sscp_norm
Specifies SSCP-normal flow
lua_flag2.lu_exp
Specifies LU-expedited flow
lua_flag2.lu_norm
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

Only one SLI_BID can be active for each session. The application program can be bid once for each flow if the SLI_BID is reactivated, even if the data is not read. If the application program does not read the bid data, it is not bid again for that specific flow.

Issuing the SLI_BID verb initially enables the bid function. After the SLI_BID verb posts complete, the bid function is disabled. The bid function can be reenabled in one of two ways:
  • By calling the SLI again with the address of an SLI_BID verb control block.
  • By issuing an SLI_RECEIVE with the lua_flag1.bid_enable parameter set to 1. If SLI_RECEIVE with lua_flag1.bid_enable is issued, the SLI uses the address of the last-accepted SLI_BID verb control block as the active bid.
Note:
  1. If multiple flows have data available when the SLI_BID is issued, the data returned by the SLI_BID is from the highest priority flow that has data. From highest to lowest, the priorities are:
    • SSCP–expedited
    • LU–expedited
    • SSCP–normal
    • LU–normal
  2. If, following SLI_BID completion, the LUA application issues an SLI_RECEIVE with multiple lua_flag1 flow flags set, the data read could be for a different flow from the data returned by the SLI_BID. This could happen if higher priority data arrived from the host between the time that the SLI_BID completed and the SLI_RECEIVE was issued.

    The LUA application can, however, guarantee that an SLI_RECEIVE reads the data for which it was just bid. It does so by setting only one of the lua_flag1 flow flags in the control block for the SLI_RECEIVE verb, specifying the same flow as that returned in the lua_flag2 field of the completed SLI_BID.

    The SLI_BID completes as soon as an RU arrives. This RU could be the only RU in a chain, or it could be the first RU in a multiple-RU chain. At SLI_BID completion, a single element chain is the only time a complete chain is bid to the application.

    If the SLI_BID completes with the first RU of a multiple-RU chain and the subsequent SLI_RECEIVE specifies the lua_flag1.nowait option, the lua_flag1.nowait option is ignored. The SLI_RECEIVE verb returns in progress and will complete asynchronously after all RUs in the chain arrive.

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_BID parameters returned are lua_prim_rc, lua_sec_rc, and lua_sid. If SLI_BID and SLI_RECEIVE are both active when status becomes available, only the SLI_BID is posted with the status. When the application program is bid for status, all information is presented and no SLI_RECEIVE is required.

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 SNA 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_OPEN.

  • 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_BID 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 lua_peek_data verb parameter. The format of the information in the lua_peek_data parameter is as follows:
  • 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'
The information returned to bytes 4 through 6 in lua_peek_data contain up to the first 3 bytes of the original request unit.
Parent topic: SLI Verbs