|
|
|
|
The RUI_BID verb is used by the application to determine when a received message is waiting to be read. This enables the application to determine what data, if any, is available before issuing the RUI_READ verb.
When a message is available, the RUI_BID verb returns with details of the message flow on which it was received, the message type, the TH and RH of the message, and up to 12 bytes of message data.
The main difference between RUI_BID and RUI_READ is that RUI_BID enables the application to check the data without removing it from the incoming message queue, so it can be left and accessed at a later stage. The RUI_READ verb removes the message from the queue, so once the application has read the data it must process it.
The application supplies the following parameters:
The length in bytes of the LUA verb record.
Set this to sizeof(LUA_VERB_RECORD).
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.
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.
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 completed 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 total number of bytes in the waiting message.
The number of bytes of data returned in the lua_peek_data parameter; from 0 to 12.
The TH of the received message.
The 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.sscp_exp
lua_flag2.lu_exp
lua_flag2.sscp_norm
lua_flag2.lu_norm
The first 12 bytes of the message data (or all of the message data if it is shorter than 12 bytes)
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
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_sid parameter did not match the session ID of any active LUA LU session.
The RUI_BID verb was rejected because a previous RUI_BID verb was already outstanding for this session. Only one RUI_BID can be outstanding for each session at any time.
The lua_post_handle parameter was not a valid pointer to a callback routine.
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 return code indicates that 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.
LUA_NEGATIVE_RSP
The secondary return code contains the sense code sent to the host on the negative response. See SNA Information, for information about interpreting the sense code values that can be returned.
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
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. 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 complete successfully before this verb can be issued.
Only one RUI_BID for each session can be outstanding at any one time.
After the RUI_BID verb has completed successfully, it may be re-issued by setting the lua_flag1.bid_enable parameter on a subsequent RUI_READ verb. If the verb is to be re-issued in this way, the application program must not free or modify the storage associated with the RUI_BID verb record.
If a message arrives from the host when an RUI_READ and an RUI_BID are both outstanding, the RUI_READ completes and the RUI_BID is left in progress.
Each message that arrives will only be bid once. Once an RUI_BID verb has indicated that data is waiting on a particular session flow, the application should issue the RUI_READ verb to receive the data. Any subsequent RUI_BID will not report data arriving on that session flow until the message which was bid has been accepted by issuing an RUI_READ verb.
The following items describe the difference between the lua_max_length and lua_data_length parameters returned on this verb:
The lua_max_length parameter indicates the length of the waiting message. When issuing the RUI_READ verb to accept the message, the application should supply a data buffer of at least this size, to ensure that the message can be received without truncation.
The lua_data_length parameter indicates the length of data in lua_peek_data. If this is less than 12, indicating that the waiting message is shorter than 12 bytes, the remaining bytes in lua_peek_data are undefined and the application should not attempt to examine them.
|
|
|
 |
|