RUI_READ(3) — Subroutines
Name
RUI_READ − Receives data from the remote host application program.
FORMAT
#include <lua_c.h>
void RUI(LUA_VERB_RECORD ∗rui_read_vcb);
Parameter
rui_read_vcb
A pointer to an LUA_VERB_RECORD structure appropriately initialized for the RUI_READ verb.
Required Verb Control Block Fields
common.lua_verb
An unsigned short value specifying the verb code LUA_VERB_RUI.
common.lua_verb_length
An unsigned short value specifying the length of the verb control block. Specify the value LUA_COMMON_LENGTH.
common.lua_post_handle
A pointer to a sem_t structure specifying the DIGITAL UNIX semaphore that the interface should use for asynchronous calls. See the DIGITAL UNIX sem_init() man page for more information about the data type of this parameter.
common.lua_opcode
An unsigned short value specifying the verb opcode. Specify the value LUA_OPCODE_RUI_READ.
common.lua_luname
An 8-element unsigned char array specifying the local LU name (in ASCII). If the name is fewer than 8 characters in length, pad the name with space characters.
common.lua_cobol_ptr
This parameter is not currently implemented and should be set to NULL.
common.lua_sid
An unsigned int value specifying the session ID that the interface should use to identify the local LU. If this parameter is 0, the interface uses the common.lua_luname parameter.
common.lua_max_length
An unsigned short value specifying the length of the data buffer referenced by the common.lua_data_ptr parameter.
common.lua_data_ptr
An unsigned char pointer to the data buffer that the interface should use to receive the data from the remote host application program.
common.lua_flag1
An LUA_FLAG1 structure specifying various flags that control how the interface executes the verb. Specify one or more of the following flags:
bid_enable---If set, specifies that the LUA application has previously used an RUI_BID verb and that the interface should reissue the RUI_BID verb using the existing RUI_BID verb control block.
nowait---If set, specifies that the interface should return the primary return code of UNSUCCESSFUL with a secondary code of NO_DATA when there is no available data.
sscp_exp---If set, specifies that the interface should return the next available message on the SSCP-expedited data flow.
sscp_norm---If set, specifies that the interface should return the next available message on the SSCP-normal data flow.
lu_exp---If set, specifies that the interface should return the next available message on the LU-expedited data flow.
lu_norm---If set, specifies that the interface should return the next available message on the LU-normal data flow.
Flow flags set cannot conflict with flow flags set in other outstanding RUI_READ verbs.
common.lua_flag3
This parameter is not currently implemented. Any fields set are ignored.
Optional Verb Control Block Fields
common.lua_correlator
A void ∗ pointer that can contain either a value or an address of a user-supplied data structure. The LUA application can use this parameter to correlate this verb control block with other user-supplied data structures. The interface does not read from or write to this field.
Returned Verb Control Block Fields
common.lua_prim_rc
An unsigned short value containing the primary error code.
common.lua_sec_rc
An unsigned int value containing the secondary error code.
common.lua_sid
An unsigned int value containing the session ID that subsequent verbs can use to specify the session to the interface.
common.lua_data_length
An unsigned short value containing the length of the received data.
common.lua_th
An LUA_TH structure containing the transmission header (TH) which accompanied the received data. The following TH fields are returned:
flags_efi---The single-bit expedited flow indicator.
flags_odai--- The single-bit originating address field (OAF) destination address field (DAF) assignor indicator.
flags_mpf---The 2-bit segmenting mapping field.
flags_fid---The 4-bit format identification type field.
daf---The destination address field.
oaf---The originating address field.
snf---The sequence number field.
common.lua_rh
An LUA_RH structure containing the request/response header (RH) which accompanied the received data. The following RH fields are returned:
eci---The end chain indicator.
bci---The begin chain indicator.
sdi---The sense data included indicator.
fi---The format indicator.
ruc---The request unit category.
rri---The request-response indicator.
qri---The queued response indicator.
ri---The exception response indicator (ERI) for requests or the response type indicator (RTI) for responses.
dr2i---The definite response 2 indicator.
dr1i---The definite response 1 indicator.
pi---The pacing indicator.
pdi---The padded data indicator.
edi---The enciphered data indicator.
csi---The code selection indicator.
cdi---The change direction indicator.
ebi---The end bracket indicator.
bbi---The begin bracket indicator.
common.lua_flag2
An LUA_FLAG2 structure containing various flags that indicate how the interface executed the verb. The following flags are returned:
async---If set, indicates that the interface is completing the verb asynchronously.
bid_enable---If set, indicates that the bid enable function of the RUI_READ request completed successfully; the interface reenabled the bid. See the return codes for the status of the data receive function of the RUI_READ request.
sscp_exp---If set, indicates that the message was received on the SSCP-expedited data flow.
sscp_norm---If set, indicates that the message was received on the SSCP-normal data flow.
lu_exp---If set, indicates that the message was received on the LU-expedited data flow.
lu_norm---If set, indicates that the message was received on the LU-normal data flow.
common.lua_message_type
An unsigned char value containing the SNA message type. The following values are possible:
LUA_MESSAGE_TYPE_LU_DATA
LUA_MESSAGE_TYPE_SSCP_DATA
LUA_MESSAGE_TYPE_RSP
LUA_MESSAGE_TYPE_PASSTHRU
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_RQR
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
Description
Use the lua_flag1 parameter to indicate on which data flow you wish the interface to receive data. If you set multiple data flow flags in the lua_flag1 parameter, the interface returns the data on the highest priority flow according to the priority shown in the following list:
SSCP-expedited
LU-expedited
SSCP-normal
LU-normal
The interface uses the lua_flag2 parameter to return an indication of the data flow on which the returned data was received.
The interface transfers the data to the buffer referenced by the lua_data_ptr and lua_max_length parameter. The RUI places the actual length of the data in the lua_data_length parameter. If the data exceeds the buffer size, the interface returns the secondary return code LUA_DATA_TRUNCATED.
The returned data does not include the TH or RH; the interface returns this information in the lua_th and lua_rh parameters respectively.
The LUA application can have up to four RUI_READ requests pending for each LU; one for each of the four data flows.
A special use of the RUI_READ verb allows the LUA application to repost an RUI_BID request.
The RUI_READ verb can wait indefinitely if no data is sent by the remote application. If necessary, use RUI_PURGE to cancel an outstanding RUI_READ verb.
Primary Return Codes
LUA_OK
LUA_CANCELLED
LUA_COMM_SUBSYSTEM_ABENDED
LUA_COMM_SUBSYSTEM_NOT_LOADED
LUA_IN_PROGRESS
LUA_INVALID_VERB
LUA_INVALID_VERB_SEGMENT
LUA_NEGATIVE_RESPONSE
LUA_PARAMETER_CHECK
LUA_SESSION_FAILURE
LUA_STATE_CHECK
LUA_UNEXPECTED_DOS_ERROR
LUA_UNSUCCESSFUL