|
|
|
|
The RUI_WRITE verb sends an SNA request or response unit from the LUA application to the host, over either the LU session or the SSCP session.
The application supplies the following parameters:
The length in bytes of the LUA verb record.
Set this to sizeof(struct LUA_COMMON).
Optional. A four-byte value that you can use to correlate this verb with other processing within your application. LUA does not use or change this information.
The name in ASCII of the LU used by the session. This must match the LU name of an active LUA session, as returned on the RUI_INIT verb.
This parameter is required only if the lua_sid parameter is 0 (zero). If a session ID is supplied in lua_sid, LUA does not use this parameter.
This parameter must be eight bytes long; pad on the right with spaces, 0x20, if the name is shorter than eight characters.
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.
The length of the supplied data. 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 0 (zero). LUA will complete the response based on the supplied sequence number. In the case of a positive response to a BIND or STSN, an extended response is allowed, so a nonzero value may be used.
When sending a negative response, set this parameter to the length of the SNA sense code (four bytes), which is supplied in the data buffer.
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 lua_data_length.
For a negative response, the buffer should contain the SNA sense code.
A pointer to a callback routine that LUA will call to indicate completion if the verb completes asynchronously.
If the VCB is used in a RUI function call, set this field to an event handle. If the VCB is used in a WinRUI function call, this field is reserved.
For more information, see Designing and Writing LUA Applications.
Required only when sending a response. The sequence number of the request to which this is the response.
When sending a request, most of the lua_rh bits must be set to correspond to the RH (request header) of the message to be sent. Do not set lua_rh.pi and lua_rh.qri ; these will be set by LUA.
When sending a response, only the following two lua_rh bits are used. The others must be 0 (zero). The lua_rh bits are:
Set to 1 to indicate a response
Set to 0 for a positive response, or 1 for a negative response
Set one of the following flags to 1 to indicate which message flow the data is to be sent on:
lua_flag1.lu_exp
lua_flag1.sscp_norm
lua_flag1.lu_norm
One and only one of the flags must be set to 1. SNAP-IX does not allow applications to send data on the SSCP expedited flow (the lua_flag1.sscp_exp flag).
LUA always returns the following parameter:
This flag is set to 1 if the verb completed asynchronously, or 0 (zero) if the verb completed synchronously.
Other returned parameters depend on whether the verb completed successfully; see the following sections.
If the verb executes successfully, LUA returns the following parameters:
LUA_OK
If the application specified the lua_luname parameter when issuing this verb, rather than specifying the session ID, LUA supplies the session ID.
The completed TH of the message written, including the fields filled in by LUA. You may need to save the value of lua_th.snf (the sequence number) for correlation with responses from the host.
The completed RH of the message written, including the fields filled in by LUA.
One of the following flags will be set to 1 to indicate which message flow the data was sent on:
lua_flag2.lu_exp
lua_flag2.sscp_norm
lua_flag2.lu_norm
The SNAP-IX implementation of LUA does not allow applications to send data on the SSCP expedited flow, and so will never set the sscp_exp flag (although other LUA implementations may set it).
If a verb does not complete successfully, LUA returns a primary return code to indicate the type of error and a secondary return code to provide specific details about the reason for unsuccessful execution.
The following return codes indicate that the verb did not complete successfully because it was canceled by another verb:
LUA_CANCELLED
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_PARAMETER_CHECK
Possible values are:
The lua_data_ptr parameter contained a value that was not valid.
The lua_sid parameter did not match the session ID of any active LUA LU session.
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 to 1). Only one RUI_WRITE at a time can be outstanding on each session flow.
The lua_flag1.sscp_exp flow flag was set, indicating that the message should be sent on the SSCP expedited flow. SNAP-IX does not allow applications to send data on this flow.
The lua_post_handle parameter was not a valid pointer to a callback routine.
More than one of the lua_flag1 flow flags was set to 1. One and only one of these flags must be set to 1, to indicate which session flow the data is to be sent on.
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 to 1.
The RUI_WRITE verb was used to send a response, and the response required more data than was supplied.
A reserved field in the verb record, or a parameter that is not used by this verb, was set to a nonzero value.
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_STATE_CHECK
Possible values are:
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 session before the session is bound. Check the sequence of SNA messages sent.
An RUI_INIT verb has not yet completed successfully for the LU name specified on this verb, or the session has failed.
The following return codes indicate that the verb record supplied was valid, but the verb did not complete successfully:
LUA_UNSUCCESSFUL
Possible values are:
This return code indicates one of the following cases:
The lua_rh.fi bit (Format Indicator) was set to 1, but the first byte of the supplied RU was not a recognized request code.
The lua_rh.ruc parameter (RU category) specified the Network Control (NC) category; SNAP-IX does not allow applications to send requests in this category.
The operating system process that issued this verb was not the same process that issued the RUI_INIT verb for this session. Only the process that started a session can issue verbs on that session.
The application used RUI_WRITE to send a positive response to a BIND message received from the host. However, the SNAP-IX node cannot accept the BIND parameters as specified, and has sent a negative response to the host. For more information about the BIND profiles accepted by SNAP-IX, see SNA Information.
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.
The lua_data_length parameter contained a value that was not valid. 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 secondary return code here is an SNA sense code indicating that the supplied SNA data was not valid or could not be sent. For information about interpreting the SNA sense codes that can be returned, see SNA Information.
The following return codes indicate that the verb did not complete successfully for other reasons:
A required SNAP-IX software component (such as the node) has terminated or has been stopped. Contact your System Administrator if necessary.
The LUA session has failed.
If the secondary return code is not LUA_RUI_LOGIC_ERROR , then this LU can be reinitialized using an RUI_REINIT. If it is not reinitialized, then an RUI_TERM must be issued before an RUI_INIT can be issued for the same LU.
Possible values are:
This return code indicates that the LUA session has failed because of a problem with the communications link or with the host LU.
This return code indicates one of the following:
The host system has violated SNA protocols
An internal error was detected within LUA
Attempt to reproduce the problem with SNA tracing active (contact your System Administrator if necessary), and check that the host is sending correct data. If this does not solve the problem, contact your SNAP-IX support personnel.
Either the lua_verb parameter or the lua_opcode parameter was not valid. The verb did not execute.
The stack size of the application is too small for LUA to complete the request. Increase the stack size of your application.
An operating system error occurred.
This value is the operating system return code. Check your operating system documentation for the meaning of this return code.
The node was either not started or not configured properly for LUA applications. Check the SNAP-IX LUA configuration parameters and start the node before running your application.
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.
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 may be used on the secondary-to-primary half-session (this is specified on the BIND), in order to prevent the LUA application from sending more data than the SNAP-IX LU or the host LU can handle. If this is the case, an RUI_WRITE on the LU normal flow may be delayed by LUA and may take some time to complete.
|
|
|
 |
|