RUI_PURGE

The RUI_PURGE verb cancels a previous RUI_READ. An RUI_READ can wait indefinitely if it is sent without setting lua_flag1 to LUA_NO WAIT (the immediate return option), and no data is available on the specified flow; RUI_PURGE forces the waiting verb to return (with the primary return code CANCELLED).

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_PURGE

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_ptr

A pointer to the RUI_READ LUA_VERB_RECORD that is to be purged.

lua_post_handle

This is a 4-byte handle that is used to post the completion of asynchronous verbs.

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 completed successfully, the following parameters are returned:

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.

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
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_prim_rc

LUA_PARAMETER_CHECK

lua_sec_rc

Possible values:

LUA_BAD_DATA_PTR: The lua_data_ptr parameter was set to zero.
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_SEC_RC_OK: A previous RUI_PURGE verb is still in progress on this session.
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_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_NO_READ_TO_PURGE: Either the lua_data_ptr parameter did not contain a pointer to an RUI_READ LUA_VERB_RECORD or the RUI_READ verb completed before the RUI_PURGE verb was issued.

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

This verb can only be used when an RUI_READ has been issued and is pending completion (that is, the primary return code is IN_PROGRESS). This verb should not be issued while another RUI_PURGE is in progress on this session.