RUI_INIT

The RUI_INIT verb establishes the SSCP-LU session for a given LUA LU.

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 LU_COMMON).

lua_opcode

LUA_OPCODE_RUI_INIT

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 or LU pool that you want to start the session. This must match a configured LUA LU name or LU pool name. For applications on the Personal Communications, the name is used as follows:

If the name is the name of an LU that is not in a pool, Personal Communications attempts to start the session using this LU.

If the name is the name of an LU pool, or the name of an LU within a pool, Personal Communications attempts to start the session using the first avaliable LU from the pool. This field is an 8-byte ASCII string, padded with trailing space (0x20) characters if necessary.

For applications on an SNA API client, the name should match a configured LUA Session Name.

: The following information only applies to Communications Server Win32 SNA API clients.

The default LUA session name for each user can be assigned using the appropriate configuration utility, either INI configuration or LDAP.

LUA programs, such as 3270 emulators, can choose to use a default LUA session name rather than specify one directly. When an LUA program issues an RUI_INIT verb with the lua_name field set to binary zeroes, or ASCII blanks, the RUI API uses the configured default LUA session name.

lua_post_handle

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

lua_flag1

The application should set this to LUA_ASYNC_STATUS.

lua_encr_decr_option

Session-level cryptography option. Personal Communications accepts the following two values:

0 Session-level cryptography is not used.

128 Encryption and decryption are performed by the
application program.

Any other value will result in the return code LUA_ENCR_DECR_LOAD_ERROR.

Returned Parameters

The following parameter will always be returned:

lua_flag2: This is only set to LUA_ASYNC if the verb completed asynchronously.
Note: RUI_INIT will always complete asynchronously, unless it returns an error such as LUA_PARAMETER_CHECK.

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_prim_rc: LUA_OK
lua_sid: A session ID for the new session. This can be used by subsequent verbs to identify this session.
lua_luname: The name of the local LU used by the session. This is required if the application specified an LU pool and needs to know which LU in the pool has been used.

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 before the RUI_INIT had completed.

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_INVALID_LUNAME: The lua_luname parameter could not be found. Check that the LU name or LU pool name was defined in Personal Communications System Management Programming API.
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: LUA_DUPLICATE_RUI_INIT
The lua_luname parameter specified an LU name or LU pool name that is already in use by this application (or for which this application already has an RUI_INIT verb in progress).

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_COMMAND_COUNT_ERROR: The verb specified the name of an LU pool, or the name of an LU in a pool, but all LUs in the pool are in use.
LUA_ENCR_DECR_LOAD_ERROR: The verb specified a value for lua_encr_decr_option other than 0 or 128.
LUA_INVALID_PROCESS: The LU specified by the lua_luname parameter is in use by another process.
LUA_LINK_NOT_STARTED: The link to the host has not been started.

The following values for lua_sec_rc are Personal Communications sense codes, and can be returned if lua_prim_rc is LUA_UNSUCCESSFUL (these values reflect the state of the LU):

X10020000: ACTPU has not been received. RUI_INIT will not activate the PU.
X10100000: ACTPU has not been received. RUI_INIT will activate the PU.
X10110000: ACTPU has been received. ACTLU has not been received. SSCP does not support self-defining dependent LU (SSDLU). RUI_INIT will activate the LU.
X10120000: ACTPU has been received. ACTLU has not been received. SSCP does support SSDLU. RUI_INIT will activate the LU.

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: LUA_LU_COMPONENT_DISCONNECTED
The LUA session has failed because of a problem with the communications link or with the host LU.
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 must be the first LUA verb issued for the session. Until this verb has completed successfully, the only other LUA verb that can be issued for this session is RUI_TERM (which will terminate a pending RUI_INIT). All other verbs issued on this session must identify the session using one of the following parameters from this verb.

The session ID is returned to the application in the lua_sid parameter.
The LU name is supplied by the application in the lua_luname parameter.

Usage Notes

The RUI_INIT verb completes after an ACTLU is received from the host. If necessary, the verb waits indefinitely. If an ACTLU has already been received prior to the RUI_INIT verb, LUA sends a NOTIFY to the host to inform it that the LU is ready for use.

Note: Neither the ACTLU nor NOTIFY is visible to the LUA application.

Once the RUI_INIT verb has completed successfully, this session uses the LU for which the session was started. No other LUA session (from this or any other application) can use the LU until the RUI_TERM verb is issued.