RUI_INIT

The RUI_INIT verb transfers control of the specified LU to the Windows LUA application. RUI_INIT establishes a session between the SSCP and the specified LU.

Note  For 3270 emulator users, a Microsoft® SNA Server extension has been added that allows you to use 3270 LUs rather than the LUA LUs. For more information, see Remarks in this topic.

The following structure describes the LUA_COMMON member of the VCB used by RUI_INIT.

struct LUA_COMMON {
    unsigned short lua_verb;
    unsigned short lua_verb_length;
    unsigned short lua_prim_rc;
    unsigned long  lua_sec_rc;
    unsigned short lua_opcode;
    unsigned long  lua_correlator;
    unsigned char  lua_luname[8];
    unsigned short lua_extension_list_offset;
    unsigned short lua_cobol_offset;
    unsigned long  lua_sid;
    unsigned short lua_max_length;
    unsigned short lua_data_length;
    char FAR *     lua_data_ptr;
    unsigned long  lua_post_handle;
    struct LUA_TH  lua_th;
    struct LUA_RH  lua_rh;
    struct LUA_FLAG1 lua_flag1;
    unsigned char  lua_message_type;
    struct LUA_FLAG2 lua_flag2; 
    unsigned char  lua_resv56[7];
    unsigned char  lua_encr_decr_option;
};

Members

lua_verb
Supplied parameter. Contains the verb code, LUA_VERB_RUI for RUI verbs.
lua_verb_length
Supplied parameter. Specifies the length in bytes of the LUA VCB. It must contain the length of the verb record being issued.
lua_prim_rc
Primary return code set by LUA at the completion of the verb. The valid return codes vary depending on the LUA verb issued.
lua_sec_rc
Secondary return code set by LUA at the completion of the verb. The valid return codes vary depending on the LUA verb issued.
lua_opcode
Supplied parameter. Contains the LUA command code (verb operation code) for the verb to be issued, LUA_OPCODE_RUI_INIT.
lua_correlator
Supplied parameter. Contains a user-supplied value that links the verb with other user-supplied information. LUA does not use or change this information. This parameter is optional.
lua_luname
Supplied parameter. Specifies the ASCII name of the local LU used by the Windows LUA session.

RUI_INIT requires this parameter.

This parameter is eight bytes long, padded on the right with spaces (0x20) if the name is shorter than eight characters.

lua_extension_list_offset
Not used by RUI in Microsoft® SNA Server and should be set to zero.
lua_cobol_offset
Not used by LUA in SNA Server and should be zero.
lua_sid
Returned parameter. Specifies the session identifier.
lua_max_length
Not used by RUI_INIT and should be set to zero.
lua_data_length
Not used by RUI_INIT and should be set to zero.
lua_data_ptr
Not used by RUI_INIT and should be set to zero.
lua_post_handle
Supplied parameter. Used under Microsoft® Windows NT® and Microsoft® Windows® 95 if asynchronous notification is to be accomplished by events. This variable contains the handle of the event to be signaled or a window handle.

For all other environments, this parameter is reserved and should be set to zero.

lua_th
Not used by RUI_INIT and should be set to zero.
lua_rh.
Not used by RUI_INIT and should be set to zero.
lua_flag1
Not used by RUI_INIT and should be set to zero.
lua_message_type
Specifies the type of the inbound or outbound SNA commands and data. This is a returned parameter for RUI_INIT. Possible values are:

LUA_MESSAGE_TYPE_LU_DATA

LUA_MESSAGE_TYPE_SSCP_DATA

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_RQR

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

The SLI receives and responds to the bind, crv, and stsn requests through the LUA interface extension routines.

lu_data, lustat_lu, lustat_sscp, and sscp_data are not SNA commands.

lua_flag2
Returned parameter. Contains flags for messages returned by LUA.
lua_flag2.async
Indicates that the LUA interface verb completed asynchronously if set to 1. (Note that RUI_INIT always completes asynchronously unless it returns an error such as LUA_PARAMETER_CHECK.)
lua_resv56
Supplied parameter. A reserved field used by RUI_INIT and SLI_OPEN. All other reserved fields in the array must be left blank. See the discussion of these SNA Server extensions in the Remarks section.
lua_resv56[1]
Supplied parameter. Indicates whether an RUI application can access LUs configured as 3270 LUs, in addition to LUA LUs. If this parameter is nonzero, 3270 LUs can be accessed.
lua_resv56[2]
Supplied parameter. Indicates whether the RUI library will release the LU when the LU-SSCP session or connection goes away. If this parameter is nonzero, the LU will not be released.
lua_resv56[3]
Supplied parameter. Indicates whether incomplete reads are supported. If this parameter is set to a nonzero value, incomplete or truncated reads are supported. See the remarks for RUI_READ for more details.
lua_resv56[4]
Supplied parameter. Indicates whether the RUI library will allow the application to keep hold of the LU if it is recycled at the host. If this parameter is nonzero, the application can keep hold of the LU.
lua_encr_decr_option
Field for cryptography options. On RUI_INIT, only the following are supported:

Values from 1 through 127 are not supported.

Return Codes

LUA_OK
Primary return code; the verb executed successfully.
LUA_CANCELED
Primary return code; the verb did not complete successfully because it was canceled by another verb.
LUA_TERMINATED
Secondary return code; RUI_TERM was issued before RUI_INIT completed.
LUA_PARAMETER_CHECK
Primary return code; the verb did not execute because of a parameter error.
LUA_INVALID_LUNAME
Secondary return code; the lua_luname parameter did not match any LUA LU name or LU pool name in the configuration file.
LUA_INVALID_POST_HANDLE
Secondary return code; for a Windows NT or Windows 95 system using events as the asynchronous posting method, the Windows LUA VCB does not contain a valid event handle.

For a Windows version 3.x system, the Windows LUA VCB does not contain the valid procedure address returned by the MakeProcInstance command.

For OS/2, the Windows LUA VCB does not contain a valid semaphore or queue handle, which is needed when the verb completes asynchronously.

LUA_RESERVED_FIELD_NOT_ZERO
Secondary return code; a reserved field in the verb record, or a parameter not used by this verb, was set to a nonzero value.
LUA_VERB_LENGTH_INVALID
Secondary return code; an LUA verb was issued with the value of lua_verb_length unexpected by LUA.
LUA_STATE_CHECK
Primary return code; the verb did not execute because it was issued in an invalid state.
LUA_DUPLICATE_RUI_INIT
Secondary return code; the lua_luname parameter specified an LU name or LU pool name already in use by this application (or for which this application already has RUI_INIT in progress).
LUA_UNSUCCESSFUL
Primary return code; the verb record supplied was valid, but the verb did not complete successfully.
LUA_COMMAND_COUNT_ERROR
Secondary return code; one of the following occurred:
·    The verb could not be issued because the application had already reached its maximum number of active sessions. In the Windows environment, an application can have as many as 16 sessions active at any time. On Windows NT, Windows 95, and OS/2, an application can have as many as 512 sessions active at any time.
·    The verb could not be issued because the application had already reached its maximum number of active sessions. In the Windows environment, an application can have as many as 16 sessions active at any time. In OS/2, an application can have as many as 512 sessions active at any time.

LUA_ENCR_DECR_LOAD_ERROR
Secondary return code; the verb specified a value for lua_encr_decr_option other than 0 or 128.
LUA_INVALID_PROCESS
Secondary return code; the LU specified by lua_luname is in use by another process.
LUA_LINK_NOT_STARTED
Secondary return code; the connection to the host has not been started; none of the link services it could use are active.
lua_comm_subsystem_abended
Primary return code; indicates one of the following conditions:
LUA_SESSION_FAILURE
Primary return code; a required SNA Server component has terminated.
LUA_LU_COMPONENT_DISCONNECTED
Secondary return code; indicates that the LUA session failed because of a problem with the link service or with the host LU.
LUA_INVALID_VERB
Primary return code; either the verb code or the operation code, or both, is invalid. The verb did not execute.
LUA_STACK_TOO_SMALL
Primary return code; the stack size of the application is too small to execute the verb. Increase the stack size of your application.
LUA_COMM_SUBSYSTEM_NOT_LOADED
Primary return code; a required component could not be loaded or has terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.
LUA_UNEXPECTED_DOS_ERROR
Primary return code; after issuing an operating system call, an unexpected operating system return code was received and is specified in the secondary return code.

Remarks

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 terminates a pending RUI_INIT).

All other verbs issued on this session must identify the session using one of the following parameters from this verb:

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

After RUI_INIT 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 RUI_TERM is issued, or until an LUA_SESSION_FAILURE primary return code is received.

Using 3270 LUs

To provide 3270 emulator users the ability to use the Emulator Interface Specification (EIS) configuration call with the RUI API, an SNA Server extension has been added to the RUI. This extension allows you to use 3270 LUs rather than LUA LUs. If an application sets lua_resv56[1] to a nonzero value on the RUI_INIT call then 3270 LUs can be used.

Don't Release the LU

If an application sets lua_resv56[2] to a nonzero value on the RUI_INIT call then the RUI library will not release the LU when the LU-SSCP session or connection goes away. When this SNA Server extension is enabled, the application does not have to issue a new RUI_INIT after a session failure or connection failure. When the LU-SSCP session comes back up (the application can use WinRUIGetLastInitStatus to detect this), the application can start using it again.

Support Chunking on this Session

If an application sets lua_resv56[3] to a nonzero value on the RUI_INIT session establishment, this enables an SNA Server extension that can change the behavior of RUI_READ. The default behavior for an RUI_READ call is to truncate data (discarding any data remaining) if the application's data buffer is not large enough for receive all of the data in the RU, returning an error code. When lua_resv56[3] is set to a nonzero value on the RUI_INIT call, then an RUI_READ issued where the application's data buffer is not large enough will not result in the RU data being discarded. The RUI_READ verb will return success (LUA_OK) for the primary return code and LUA_DATA_INCOMPLETE for the secondary return code. Subsequent RUI_READ requests can then be issued to retrieve the data that exceeded the application's data buffer.

Ignore DACTLUs

If an application sets lua_resv56[4] to a nonzero value on the RUI_INIT session establishment, this enables an SNA Server extension and the RUI library will allow the application to keep hold of the LU if it is recycled at the host (that is, deactivated and reactivated).

Note  All other reserved fields must be left blank.

For more information, see the description of the sepdcrec function in the Microsoft SNA Server 3270 Emulator Interface Specification.

Encryption

Session-level cryptography is implemented through Cryptography Verification (CRV) requests; RUI applications must perform all necessary processing of these requests. For all interfaces other than RUI, CRV requests are rejected with a negative response by the SNA Server.

For RUI_INIT, the following options are supported:

Values from 1 through 127 (ACSRENCR and ACSROECR routines) are not supported.

The sending application is responsible for padding data to a multiple of eight bytes and for setting the padded data indicator bit in the RH as well as for encryption. The receiving application is responsible for removing the padding after decryption.

See Also

RUI_INIT, RUI_TERM, SLI_OPEN