|
|
|
|
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.
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 buffer supplied to receive the data.
A pointer to the buffer supplied to receive the data.
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.
Set the lua_flag1.nowait parameter to 1 if you want the RUI_READ verb to return as soon as possible whether or not data is available to be read, or set it to 0 (zero) if you want the verb to wait for data before returning.
Setting the lua_flag1.nowait parameter to 1 does not mean that the verb will complete synchronously. The LUA library needs to communicate with the local node to determine whether or not any data is available, and this normally requires an asynchronous verb return to avoid blocking the application. The parameter means that, if there is no data available immediately, the asynchronous verb return will occur as soon as possible to indicate this.
Set the lua_flag1.bid_enable parameter to 1 to re-enable the most recent RUI_BID verb (equivalent to issuing RUI_BID again with exactly the same parameters as before), or set it to 0 (zero) if you do not want to re-enable RUI_BID. Re-enabling the previous RUI_BID re-uses the VCB originally allocated for it, so this VCB must not have been freed or modified. (For more information, see Interaction with Other Verbs.)
Set one or more of the following flags to 1 to indicate which message flow to read data from:
lua_flag1.sscp_exp
lua_flag1.lu_exp
lua_flag1.sscp_norm
lua_flag1.lu_norm
If more than one flag is set, the highest-priority data available will be returned. The order of priorities (highest first) is: SSCP expedited, LU expedited, SSCP normal, LU normal. The equivalent flag in the lua_flag2 group will be set to indicate which flow the data was read from (see Returned Parameters).
The SNAP-IX implementation of LUA does not return data on the SSCP expedited flow. The application can set the sscp_exp flag, for compatibility with other LUA implementations, but data will never be returned on this flow.
LUA always returns the following parameters:
This parameter is set to 1 if the verb completed asynchronously, or 0 if the verb completed synchronously.
This parameter is set to 1 if an RUI_BID was successfully re-enabled, or to 0 if it was not re-enabled.
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
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 (see Other Conditions ).
If the application specified the lua_luname parameter when issuing this verb, rather than specifying the session ID, LUA supplies the session ID.
The length of the data received. LUA places the data in the buffer specified by lua_data_ptr.
Information from the transmission header (TH) of the received message.
Information from the request/response header (RH) of the received message.
Message type of the received message that will be one of the following:
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
One of the following flags will be set to 1, to indicate on which message flow the data was received:
lua_flag2.lu_exp
lua_flag2.sscp_norm
lua_flag2.lu_norm
The SNAP-IX implementation of LUA does not return data on the SSCP expedited flow, and so the sscp_exp flag will never be set (although it may be set by other LUA implementations).
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 or by an internal error:
LUA_CANCELLED
Possible values are:
This RUI_READ verb has been canceled by an RUI_PURGE verb.
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_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.
The lua_flag1.bid_enable parameter was set to re-enable an RUI_BID verb, but the previous RUI_BID verb was still in progress.
The flow flags in the lua_flag1 group 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.
None of the lua_flag1 flow flags was set. At least one of these flags must be set to 1 to indicate which flow or flows to read from.
The lua_post_handle parameter was not a valid pointer to a callback routine.
The lua_flag1.bid_enable parameter was set to re-enable an RUI_BID verb, but there was no previous RUI_BID verb that could be enabled. (For more information, see Interaction with Other Verbs.)
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
An RUI_INIT verb has not yet completed successfully for the LU name specified on this verb, or the session has failed.
The following primary return code indicates one of the following two cases, which can be distinguished by the secondary return code:
SNAP-IX detected an error in the data received from the host. Instead of passing the received message to the application on an RUI_READ verb, SNAP-IX 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. SNAP-IX 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_NEGATIVE_RSP
A nonzero secondary return code contains the sense code sent to the host on the negative response. This indicates that SNAP-IX detected an error in the host data, and sent a negative response to the host. For information about interpreting the sense code values that can be returned, see SNA Information.
A 0 (zero) secondary return code indicates that, following a previous RUI_WRITE of a negative response to a message in the middle of a chain, SNAP-IX 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_UNSUCCESSFUL
Possible values are:
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; see Successful Execution or Truncated Data.
The lua_flag1.nowait parameter was set to indicate immediate return without waiting for data, and no data was currently available on the specified session flow or flows.
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 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.
LUA_COMM_SUBSYSTEM_NOT_LOADED
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 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; you cannot have more than one RUI_READ outstanding for the same session flow.
The lua_flag1.bid_enable parameter can only be used if the following are true:
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
If you use this parameter to re-enable a previous RUI_BID, at least one of the message flow flags on RUI_READ must still be set, to indicate the flow or flows on which the application will accept data. If the first data to be received is on a flow accepted by the RUI_READ verb, RUI_READ will return with this data, and RUI_BID will not return. Otherwise, RUI_BID will return to indicate that there is data to be read (since RUI_BID accepts data on all flows, it will always accept the data if RUI_READ does not). The application must then issue another RUI_READ on the appropriate flow to obtain the data.
If you want to use RUI_BID to handle data on all flows, rather than having the data on a particular flow handled by RUI_READ in preference to RUI_BID, you need to re-issue RUI_BID explicitly instead of using RUI_READ to re-enable the previous RUI_BID.
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. (The RUI_BID verb may be used as a non-destructive read; 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 may be used on the primary-to-secondary half-session (this is specified in the host configuration), in order to protect the LUA application from being flooded with messages. If the LUA application is slow to read messages, SNAP-IX delays the sending of pacing responses to the host in order to slow it down.
|
|
|
 |
|