RUI_READ

The RUI_READ verb receives data or status information sent from the host to the application's LU. You can specify a particular message flow (LU normal, LU expedited, SSCP normal, or SSCP expedited) from which to read data, or you can specify more than one message flow. You can have multiple RUI_READ verbs outstanding, provided that no two of them specify the same flow.

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).

lua_opcode

LUA_OPCODE_RUI_READ

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_max_length

The length of the buffer supplied to receive the data (see lua_data_ptr).

lua_data_ptr

A pointer to the buffer supplied to receive the data.

lua_post_handle

This is a 4-byte handle that is used to post the completion of asynchronous verbs.

lua_flag1

The flags can be one or more of the following values ORed together:

Set LUA_NOWAIT if you want the RUI_READ verb to return immediately whether or not data is available to be read, or do not set it if you want the verb to wait for data before returning.
Set LUA_BID_ENABLE to reenable the most recent RUI_BID verb (equivalent to issuing RUI_BID again with exactly the same parameters as before), or do not set it if you do not want to reenable RUI_BID.
Note: Reenabling the previous RUI_BID reuses the LUA_VERB_RECORD originally allocated and does not permit the LUA_VERB_RECORD to be freed or modified.
Set one or more of the following flags to indicate which message flow to read data from:
LUA_SSCP_EXP

SSCP expedited flow

LUA_LU_EXP

LU expedited flow

LUA_SSCP_NORM

SSCP normal flow

LUA_LU_NORM

LU normal flow
If more than one flag is set, the highest-priority data available will be returned. The order of priorities (highest to lowest) is as follows:
1. SSCP expedited
2. LU expedited
3. SSCP normal
4. LU normal
The equivalent flag will be set in lua_flag2 to indicate which flow the data was read from (see Returned Parameters).

Returned Parameters

The following parameters will always be returned:

lua_flag2: LUA_ASYNC is set if the verb completes asynchronously (and not set if the verb completes synchronously).
LUA_BID_ENABLE is set if an RUI_BID was successfully reenabled (and not set if it was not reenabled).

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

If the verb executes successfully, LUA also returns the following parameters:

lua_prim_rc: LUA_OK

The following parameters are returned if the verb completes successfully. They are also returned if the verb returns with truncated data because the lua_data_length parameter supplied was too small.

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_data_length

The length of the data received. LUA places the data in the buffer specified by lua_data_ptr.

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 parameters

This will be set to one of the following values, 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

The following return codes indicate that the verb did not complete successfully because it was canceled by another verb or by an internal error:

lua_prim_rc

LUA_CANCELLED

lua_sec_rc

Possible values:

LUA_PURGED: This RUI_READ verb has been canceled by an RUI_PURGE verb.
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_BAD_DATA_PTR: The lua_data_ptr parameter contained an incorrect value.
LUA_BID_ALREADY_ENABLED: The lua_flag1 was set to LUA_BID_ENABLE to reenable an RUI_BID verb, but the previous RUI_BID verb was still in progress.
LUA_DUPLICATE_READ_FLOW: The flow flags on lua_flag1 specified one or more session flows for which an RUI_READ verb was already outstanding. Only one RUI_READ at a time can be waiting on each session flow.
LUA_INVALID_FLOW: None of the lua_flag1 flow flags was set. At least one of these flags must be set to indicate which flow or flows to read from.
LUA_NO_PREVIOUS_BID_ENABLED: The lua_flag1 was set to LUA_BID_ENABLE, to reenable an RUI_BID verb, but there was no previous RUI_BID verb that could be enabled. (See Comments for more information.)
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 primary return code indicates one of the following two cases, which can be distinguished by the secondary return code:

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.
The LUA application previously sent a negative response to a message in the middle of a chain. Personal Communications has purged subsequent messages in this chain, and is now reporting to the application that all messages from the chain have been received and purged.

lua_prim_rc: LUA_NEGATIVE_RSP
lua_sec_rc: A nonzero secondary return code contains the sense code sent to the host on the negative response. This indicates that Personal Communications detected an error in the host data, and sent a negative response to the host. 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 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

Possible values:

LUA_DATA_TRUNCATED: The lua_data_length parameter was smaller than the actual length of data received on the message. Only lua_data_length bytes of data were returned to the verb; the remaining data was discarded. Additional parameters are also returned if this secondary return code is obtained.
LUA_NO_DATA: The lua_flag1 was set to LUA_NOWAIT to indicate immediate return without waiting for data, and no data was currently available on the specified session flow or flows.
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 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.

Try 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 have completed successfully before this verb can be issued. While an existing RUI_READ is pending, you can issue another RUI_READ only if it specifies a different session flow or flows from pending RUI_READs; that is, you cannot have more than one RUI_READ outstanding for the same session flow.

The lua_flag1 can only be set to LUA_BID_ENABLE if all of the following things are true:

An RUI_BID has already been issued successfully and has completed.
The storage allocated for the RUI_BID verb has not been freed or modified.
No other RUI_BID is pending.

Usage Notes

If the data received is longer than the lua_max_length parameter, it will be truncated; only lua_max_length bytes of data will be returned. The primary and secondary return codes LUA_UNSUCCESSFUL and LUA_DATA_TRUNCATED will also be returned.

Once a message has been read using the RUI_READ verb, it is removed from the incoming message queue and cannot be accessed again.

Note: The RUI_BID verb can be used as a nondestructive read; that is, the application can use it to check the type of data available, but the data remains on the incoming queue and need not be used immediately.

Pacing can be used on the primary-to-secondary half-session (this is specified in the host configuration) to protect the Personal Communications node from being flooded with messages. If the LUA application is slow to read messages, Personal Communications delays the sending of pacing responses to the host in order to slow it down.