RUI_WRITE

The RUI_WRITE verb sends an SNA request or response unit from the LUA application to the host, over either the LU-LU session or the LU-SSCP session.

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_WRITE
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_data_length
The length of the supplied data (see lua_data_ptr). When sending data on the LU normal flow, the maximum length is as specified in the BIND received from the host; for all other flows the maximum length is 256 bytes.

When sending a positive response, this parameter is normally set to zero. LUA will complete the response based on the supplied sequence number (see lua_th.snf). In the case of a positive response to a BIND or STSN, an extended response is permitted, so a nonzero value can be used.

When sending a negative response, set this parameter to the length of the SNA sense code (4 bytes), which is supplied in the data buffer (see lua_data_ptr).

lua_data_ptr
A pointer to the buffer containing the supplied data.

For a request, or a positive response that requires data, the buffer should contain the entire RU. The length of the RU must be specified in data_length.

For a negative response, the buffer should contain the SNA sense code.

lua_post_handle
This is a 4-byte handle that is used to post the completion of asynchronous verbs.
lua_th.snf
Required only when sending a response. The sequence number of the request to which this is the response.
lua_rh
When sending a request, most of the lua_rh flags must be set to correspond to the RH (request header) of the message to be sent. Do not set LUA_PI and LUA_QRI; these will be set by LUA.
When sending a response, only the following two lua_rh flags are set:
LUA_RRI
Is set to indicate a response.
LUA_RI
Is not set for a positive response, or set for a negative response.
lua_flag1
Set one of the following flags to indicate which message flow the data is to be sent on:
LUA_LU_EXP
LU expedited flow
LUA_SSCP_NORM
SSCP normal flow
LUA_LU_NORM
LU normal flow
One and only one of the flags must be set.
Note:
Personal Communications does not permit applications to send data on the SSCP expedited flow (LUA_SSCP_EXP).

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 executes successfully, LUA also returns the following parameters:
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_th
The completed TH of the message written, including the fields filled in by LUA. You might need to save the value of lua_th.snf (the sequence number) for correlation with responses from the host.
lua_rh
The completed RH of the message written, including the fields filled in by LUA.
lua_flag2
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:
lua_prim_rc
LUA_CANCELLED
lua_sec_rc
LUA_TERMINATED

The verb was canceled because an RUI_TERM
verb was issued for this
session.

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_DUPLICATE_WRITE_FLOW
An RUI_WRITE was already outstanding for the session flow specified on this verb (the session flow is specified by setting one of the lua_flag1 flow flags). Only one RUI_WRITE at a time can be outstanding on each session flow.
LUA_INVALID_FLOW
lua_flag1 was set to LUA_SSCP_EXP, indicating that the message should be sent on the SSCP expedited flow. Personal Communications does not permit applications to send data on this flow.
LUA_MULTIPLE_WRITE_FLOWS
More than one of the lua_flag1 flow flags was set. One and only one of these flags must be set to indicate which session flow the data is to be sent on.
LUA_REQUIRED_FIELD_MISSING
This return code indicates one of the following cases:
  • None of the lua_flag1 flow flags was set. One and only one of these flags must be set.
  • The RUI_WRITE verb was used to send a response, and the response required more data than was supplied.
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
Possible values:
LUA_MODE_INCONSISTENCY
The SNA message sent on the RUI_WRITE was not valid at this time. This is caused by trying to send data on the LU-LU session before the session is bound. Check the sequence of SNA messages sent.
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
Possible values:
LUA_FUNCTION_NOT_SUPPORTED
This return code indicates one of the following cases:
  • lua_rh was set to LUA_FI (Format Indicator), but the first byte of the supplied RU was not a recognized request code.
  • lua_rh was set to LUA_RH_NC (RU category specified the Network Control (NC) category); Personal Communications does not permit applications to send requests in this category.
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.
LUA_INVALID_SESSION_PARAMETERS
The application used RUI_WRITE to send a positive response to a BIND message received from the host. However, the Personal Communications node cannot accept the BIND parameters as specified, and has sent a negative response to the host. See SNA Layers for more information on the BIND profiles accepted by Personal Communications.
LUA_RSP_CORRELATION_ERROR
When using RUI_WRITE to send a response, the lua_th.snf parameter (which indicates the sequence number of the received message being responded to) did not contain a valid value.
LUA_RU_LENGTH_ERROR
The lua_data_length parameter contained an incorrect value. When sending data on the LU normal flow, the maximum length is as specified in the BIND received from the host; for all other flows the maximum length is 256 bytes.
(any other value)
Any other secondary return code here is an SNA sense code indicating that the supplied SNA data was not valid or could not be sent. See SNA Layers for information on interpreting the SNA sense codes that can be returned.
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 be issued successfully before this verb can be issued. While an existing RUI_WRITE is pending, you can issue a second RUI_WRITE only if it specifies a different session flow from the pending RUI_WRITE; that is, you cannot have more than one RUI_WRITE outstanding for the same session flow.

The RUI_WRITE verb can be issued on the SSCP normal flow at any time after a successful RUI_INIT verb. RUI_WRITE verbs on the LU expedited or LU normal flows are permitted only after a BIND has been received, and must abide by the protocols specified on the BIND.

Usage Notes

The successful completion of RUI_WRITE indicates that the message was queued successfully to the data link; it does not necessarily indicate that the message was sent successfully, or that the host accepted it. Pacing can be used on the secondary-to-primary half-session (this is specified on the BIND) to prevent the LUA application from sending more data than the local or remote LU can handle. If this is the case, an RUI_WRITE on the LU normal flow can be delayed by LUA and can take some time to complete.
Note:
Personal Communications does not permit applications to send data on the SSCP expedited flow (LUA_SSCP_EXP).