RUI_BID

The RUI_BID verb is used by the application to indicate when a received message is waiting to be read. This enables the application to determine what data, if any, is available before issuing the RUI_READ verb. When a message is available, the RUI_BID verb returns with details of the message flow on which it was received, the message type, the TH and RH of the message, and up to 12 bytes of message data. The main difference between RUI_BID and RUI_READ is that RUI_BID enables the application to check the data without removing it from the incoming message queue, so it can be left and accessed at a later stage. RUI_READ removes the message from the queue, so once the application has read the data it must process it.

Supplied Parameters

The application supplies the following parameters:
lua_verb
LUA_VERB_RUI
lua_verb_length
The length in bytes of the LUA verb record. Set this to
  • sizeof(struct LUA_COMMON) + 12.
lua_opcode
LUA_OPCODE_RUI_BID
lua_correlator
Optional. A 4-byte value, which you can use to correlate this verb with other processing within your application. LUA does not use or change this information.
lua_luname
The name in ASCII of the local LU used by the session. This must match the LU name of an active LUA session.

This parameter is required only if the lua_sid parameter is zero. If a session ID is supplied in lua_sid, LUA does not use this parameter.

This parameter must be 8 bytes long; pad on the right with spaces, 0x20, if the name is shorter than 8 characters.

lua_sid
The session ID of the session. This must match a session ID returned on a previous RUI_INIT verb. This parameter is optional; if you do not specify the session ID, you must specify the LU name for the session in the lua_luname parameter.
lua_post_handle
This is a 4-byte handle that is used to post the completion of asynchronous verbs.

Returned Parameters

The following parameter will always be returned:
lua_flag2
This is only set to LUA_ASYNC if the verb completed asynchronously.

Other returned parameters depend on whether the verb completed successfully; see the following sections.

If the verb completed successfully, the following parameters are returned:
lua_prim_rc
LUA_OK
lua_sid
If the application specified the lua_luname parameter when issuing this verb, rather than specifying the session ID, LUA supplies the session ID.
lua_max_length
The number of bytes of data in the received message.
lua_data_length
The number of bytes of data returned in the lua_peek_data parameter; from 0 to 12.
lua_th
Information from the transmission header (TH) of the received message.
lua_rh
Information from the request/response header (RH) of the received message.
lua_message_type
Message type of the received message, which will be one of the following values:
  • 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_CLEAR
  • LUA_MESSAGE_TYPE_CRV
  • 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_SHUTD
  • LUA_MESSAGE_TYPE_SIGNAL
  • LUA_MESSAGE_TYPE_SDT
  • LUA_MESSAGE_TYPE_STSN
  • LUA_MESSAGE_TYPE_UNBIND
lua_flag2
One of the following flags will be set to indicate which message flow the data was received on:
LUA_SSCP_EXP
SSCP expedited flow
LUA_LU_EXP
LU expedited flow
LUA_SSCP_NORM
SSCP normal flow
LUA_LU_NORM
LU normal flow
lua_peek_data
The first 12 bytes of the message data (or all of the message data if it is shorter than 12 bytes).
The following return codes indicate that the verb did not complete successfully because it was canceled by another verb:
lua_prim_rc
LUA_CANCELLED
lua_sec_rc
LUA_TERMINATED An RUI_TERM verb was issued while this verb was pending.
The following return codes indicate that the verb did not complete successfully because a supplied parameter was in error:
lua_prim_rc
LUA_PARAMETER_CHECK
lua_sec_rc
Possible values:
LUA_BID_ALREADY_ENABLED
The RUI_BID verb was rejected because a previous RUI_BID verb was already outstanding. Only one RUI_BID can be outstanding at a time.
LUA_RESERVED_FIELD_NOT_ZERO
A reserved field in the verb record, or a parameter that is not used by this verb, was set to a nonzero value.
LUA_VERB_LENGTH_INVALID
The value of the lua_verb_length parameter was less than the length of the verb record required for this verb.
The following return codes indicate that the verb was issued in a session state in which it was not valid:
lua_prim_rc
LUA_STATE_CHECK
lua_sec_rc
LUA_NO_RUI_SESSION

An RUI_INIT verb has not yet completed successfully for this session, or a session outage has occurred.

The following return codes indicate that the verb record supplied was valid, but the verb did not complete successfully:
lua_prim_rc
LUA_UNSUCCESSFUL
lua_sec_rc
LUA_INVALID_PROCESS

The application instance that issued this verb was not the same as the one that issued the RUI_INIT verb for this session.

The following return code indicates that Personal Communications detected an error in the data received from the host. Instead of passing the received message to the application on an RUI_READ verb, Personal Communications discards the message (and the rest of the chain if it is in a chain), and sends a negative response to the host. LUA informs the application on a subsequent RUI_READ or RUI_BID verb that a negative response was sent.
lua_prim_rc
LUA_NEGATIVE_RSP
lua_sec_rc
The secondary return code contains the sense code sent to the host on the negative response. See SNA Layers for information on interpreting the sense code values that can be returned.

A zero secondary return code indicates that, following a previous RUI_WRITE of a negative response to a message in the middle of a chain, Personal Communications has now received and discarded all messages from this chain.

The following primary and secondary return codes indicate that the verb did not complete successfully for other reasons:
lua_prim_rc
LUA_SESSION_FAILURE

The session has been brought down.

lua_sec_rc
Possible values:
LUA_LU_COMPONENT_DISCONNECTED
The LUA session has failed because of a problem with the communications link or with the host LU.
LUA_RUI_LOGIC_ERROR
This return code indicates one of the following things:
  • The host system has violated SNA protocols.
  • An internal error was detected within LUA.

Attempt to reproduce the problem with tracing active, and check that the host is sending correct data.

lua_prim_rc
LUA_INVALID_VERB

Either the lua_verb parameter or the lua_opcode parameter was not valid. The verb did not execute.

lua_prim_rc
LUA_UNEXPECTED_DOS_ERROR

An operating system error occurred, such as resource shortage.

lua_sec_rc
This value is the operating system return code. Check your operating system documentation for the meaning of this return code.

Comments

The RUI_INIT verb must complete successfully before this verb can be issued.

Only one RUI_BID can be outstanding at any one time. After the RUI_BID verb has completed successfully, it can be reissued by setting the lua_flag1 to LUA_BID_ENABLE on a subsequent RUI_READ verb. If the verb is to be reissued in this way, the application program must not free or modify the storage associated with the RUI_BID verb record.

If a message arrives from the host when an RUI_READ and an RUI_BID are both outstanding, the RUI_READ completes and the RUI_BID is left in progress.

Usage Notes

Each message that arrives will only be bid once. Once an RUI_BID verb has indicated that data is waiting on a particular session flow, the application should issue the RUI_READ verb to receive the data. Any subsequent RUI_BID will not report data arriving on that session flow until the message that was bid has been accepted by issuing an RUI_READ verb.

In general, the lua_data_length parameter returned on this verb indicates only the length of data in lua_peek_data, not the total length of data on the waiting message (except when a value of less than 12 is returned). The lua_max_length parameter returns the number of bytes in the received message. The application should ensure that the data length on the RUI_READ verb that accepts the data is sufficient to contain the message.