SLI_OPEN

This verb opens an SNA session for an application program that is requesting session-level communications on the link. The session-level function issues SNA commands on behalf of the application program to open the session. The LUA application program is simplified because SLI functions perform multiple RUI functions to establish the LU-LU session.

Supplied Parameters

The application supplies the following parameters:
lua_verb
LUA_VERB_SLI

The verb-code indicator for the LUA verbs.

lua_verb_length
The length of the verb control block. This number must equal the length expected by the SLI for the SLI_OPEN verb.
lua_opcode
LUA_OPCODE_SLI_OPEN
lua_correlator
A value that an LUA application program can supply to help correlate this verb with other information that the program supplies. This parameter is not used by the Windows® LUA interface.
lua_luname
The local LU name in ASCII. If the name contains fewer than 8 characters, you must pad it with blanks.

This parameter is required by SLI_OPEN. Other verbs require this parameter only if the lua_sid parameter is zero; however, using the lua_luname parameter on all verbs helps make debugging easier, especially when multiple LUs are configured.


Displays a Communications Server product icon.
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 SLI_OPEN verb with the lua_name field set to binary zeroes, or ASCII blanks, the SLI API uses the configured default LUA session name.

lua_data_length
The length of the unformatted LOGON or INITSELF data being sent.
lua_data_ptr
A pointer to the data buffer of the application. Because this buffer is used for data and SNA commands, the contents of the buffer are usually in EBCDIC.
This data buffer contains one of the following things:
  • The user's SNA INITSELF request unit (RU) with all of the required application program data filled in if the lua_init_type parameter specifies secondary initiated with INITSELF. The INITSELF contains user information, such as the mode name and the PLU name. For more information, refer to Systems Network Architecture Network Product Formats.
  • The LOGON message that is sent on the SSCP-normal flow when the lua_init_type parameter specifies secondary initiated with an unformatted LOGON message.
  • If the session is primary initiated, this buffer is not used and the lua_data_ptr parameter must be 0.
lua_post_handle
If asynchronous notification is to be accomplished by events, lua_post_handle contains the handle of the event to be signaled.
lua_encr_decr_option
Cryptography is not supported.
lua_init_type
Defines how the LU-LU session is initialized by the Windows® LUA interface. Valid values are:
LUA_INIT_TYPE_SEC_IS
Secondary-initiated; send the INITSELF command that is supplied in the data buffer of the OPEN
LUA_INIT_TYPE_SEC_LOG
Secondary-initiated with an unformatted LOGON message specified in the data buffer of the OPEN
LUA_INIT_TYPE_PRIM
Primary-initiated; wait on BIND
LUA_INIT_TYPE_PRIM_SSCP
Primary-initiated with SSCP access
lua_session_type
A value that defines how the SLI processes UNBIND type X'01', UNBIND normal. The valid values follow:
LUA_SESSION_TYPE_NORMAL
When an UNBIND normal is received from the primary logical unit, the SLI sends a positive response and issues RUI_TERM which causes a NOTIFY disabled to flow to the SSCP. The SSCP-LU flow is disabled. This is the default value for this parameter.
LUA_SESSION_TYPE_DEDICATED
When an UNBIND normal is received from the primary logical unit, the SLI sends a positive response and the SLI session is suspended until a new BIND, optional CRV and STSN, and SDT commands are received. In this case, the SLI does not issue RUI_TERM and NOTIFY disabled does not flow to the SSCP.

Displays a notepad icon that denotes important information.
LUA_SESSION_TYPE_DEDICATED is not supported by SNA API clients.
lua_wait
The number of seconds (up to a maximum of 65␠535) for the SLI to wait before automatically retrying the transmission of the INITSELF or the LOGON message after the host sends any one of these messages:
  • A negative response to the INITSELF or LOGON message and the secondary return code is one of the following values:
    • RESOURCE_NOT_AVAILABLE (X'08010000')
    • SESSION_LIMIT_EXCEEDED (X'08050000')
    • SSCP_LU_SESS_NOT_ACTIVE (X'0857nnnn' where nnnn is X'0002')
    • SESSION_SERVICE_PATH_ERROR (X'087Dnnnn' where nnnn is X'0000')
  • A Network Services Procedure Error (NSPE) message
  • A NOTIFY command, which indicates a procedure error
If the value of lua_wait is 0, no retries occur. This parameter applies only to sessions initiated by the SLU. If the PLU initiates the session, lua_wait is ignored.
lua_extension_list_offset
Specifies the offset from the start of the verb control block to the extension list of user-supplied DLLs. The value must be the beginning of a word boundary. If there is no extension list, the value must be set to zero.
lua_routine_type
The type of routine of the following module and procedure name. The valid entries follow:
lua_routine_type_bind
Bind routine
lua_routine_type_crv
Cryptography vector routine
Note:
Encryption is not currently supported.
lua_routine_type_sdt
Start data traffic (SDT) routine

Displays a notepad icon that denotes important information.
lua_routine_type_sdt is not supported by SNA API clients.
lua_routine_type_stsn
Set and test sequence numbers (STSN) routine
lua_routine_type_end
Ending delimiter for list of routines.
lua_module_name
Provides the user-supplied ASCII module name. The parameter can be up to eight characters in length, with the remaining bytes set to X'00'.
lua_procedure_name
Provides the user-supplied DLL procedure name, in ASCII. The parameter can be up to 32 characters in length, with the remaining bytes set to X'00'.

Returned Parameters

If the verb completed successfully, the following parameters are returned:
lua_flag2.async
A flag that indicates that this verb completes asynchronously.
lua_sid
The session ID that subsequent verbs use to identify the session to be used. The value of this parameter is valid only if the primary return code is OK or IN_PROGRESS. If the SLI_OPEN fails after having returned IN_PROGRESS, the session ID is no longer valid.
lua_prim_rc
The primary return code, set by the verb function. For details, see LUA Verb Return Codes.
lua_sec_rc
The secondary return code, set by the verb function. For details, see LUA Verb Return Codes.

Usage Notes

The SLI can perform the following session initialization tasks:
  • Start the RUI session
  • Write an INITSELF or an unformatted logon message (secondary initialization only).
  • Read and process an INITSELF response or the response to the logon message (secondary initialization only).
  • Read and verify a BIND command from the host.
  • Write a BIND response.
  • Read and process an UNBIND type X'02' or an UNBIND type X'01' if one is sent by the host.
  • Write the UNBIND response and prepare to receive the subsequent BIND.
  • Read and process the STSN command (if required).
  • Write the STSN response (if required).
  • Read and process the SDT command.
  • Write the SDT response.
  • Go to user routines to process BIND, STSN, and SDT commands when they are specified by the application program in the SLI_OPEN verb.

The SLI_OPEN verb handles all SNA message traffic through the response to the SDT command.

An application program issues an SLI_OPEN verb to select a particular defined LUA LU in the lua_luname parameter. This field is an ASCII string that should be padded with blanks.

The lua_init_type parameter tells the SLI how to establish the LU session. The following list describes the initialization options:
  • Secondary Initialization with INITSELF

    Set the lua_init_type parameter to LUA_INIT_TYPE_SEC_IS for this option. With this option, the application program must supply the INITSELF command used in the SLI_OPEN verb because the INITSELF contains all of the session-specific information needed by the host, such as the mode name and the PLU name. The lua_data_ptr parameter gives the address of the INITSELF, and the lua_data_length parameter gives its length.

  • Secondary Initialization with an Unformatted LOGON Message

    Set the lua_init_type parameter to LUA_INIT_TYPE_SEC_LOG for this option. In secondary initialization with an unformatted LOGON message, the lua_data_ptr parameter contains the address of the user's EBCDIC LOGON message of the length that is specified in the lua_data_length parameter.

  • Primary Initialization

    Set the lua_init_type parameter to LUA_INIT_TYPE_PRIM for this option. In primary initialization, the SLU does nothing to start the session with the host. The SLI_OPEN remains IN_PROGRESS until the host starts the session with a BIND command and a subsequent SDT command.

  • Primary Initialization with SSCP Access

    Set the lua_init_type parameter to LUA_INIT_TYPE_PRIM_SSCP for this option. In primary initialization with SSCP access, the SLI does not send commands to the host to start the session. Instead, the SLI allows the application program to issue SLI_SEND and SLI_RECEIVE verbs for SSCP-normal flow data to send INITSELF commands or LOGON messages and to receive their responses. With this option, the application program is not limited to one INITSELF or LOGON message as it is for the secondary initialization types. This is the only SLI_OPEN type that allows the application program to issue SLI verbs before the SLI_OPEN completes. After the SLI_OPEN verb is issued, the application program can issue an SLI_BID or an SLI_RECEIVE to get INIT_COMPLETE status. This status tells the application program that it can begin to issue the SLI_SEND and SLI_RECEIVE verbs for SSCP-normal flow data.

The optional lu_session_type parameter tells the SLI how to process UNBIND type X'01', UNBIND normal. This parameter takes effect after the SLI_OPEN verb passes initial parameter checking and stays in effect until SLI_CLOSE abend is issued or until the SLI issues RUI_TERM. The following list describes standard UNBIND and dedicated UNBIND processing:
  • Standard UNBIND Normal Processing SLI_CLOSE Normal
    Set the lua_session_type parameter to LUA_SESSION_TYPE_NORMAL for this option. This is the default value. With this option, the SLI sends a positive response to an UNBIND Normal sent by the primary LU and issues RUI_TERM, which causes a NOTIFY Disabled to flow to the SSCP. These actions do the following things:
    • End the LU-LU session.
    • Indicate to the SSCP and the PLU that the SLU is unable to process new BINDs. New BINDs that are received are rejected.
    • Prevent data from flowing on the SSCP-LU session.

      The SLI will issue RUI_TERM when it receives any UNBIND except type X'02' (UNBIND with BIND forthcoming).

    • Dedicated UNBIND Normal Processing

      Set the lua_session_type parameter to LUA_SESSION_TYPE_DEDICATED for this option. With this option, the SLI sends a positive response to an UNBIND normal sent by the primary logical unit. However, the SLI does not issue RUI_TERM. The status of the SSCP-LU session is not changed (enabled). The SLI session is suspended until BIND, optional CRV and STSN, and SDT commands are received. An SLI session that is waiting for a new BIND can be terminated by issuing an SLI_CLOSE Abend.

      The SLI issues RUI_TERM when it receives any UNBIND except type X'02' or type X'01'.

      This option is useful when the primary LU is unable to send an UNBIND with BIND forthcoming, but expects this type of behavior when UNBIND normal is sent.

Application-Supplied BIND, SDT, or STSN Routines
  • If the application program supplies BIND, SDT, or STSN routines, the DLL module names and procedure entry points are passed in the SLI_OPEN extension routine list. If the corresponding SNA request is received, these routines are called during the SLI_OPEN. If no BIND routine is supplied, the SLI does a limited amount of BIND checking and responds as needed. If an STSN routine is not supplied and an STSN request is received, the SLI issues a positive response to indicate that no information is available. If an SDT routine is not supplied and an SDT request is received, the SLI issues a positive response.
Posting
  • The posting of the SLI_OPEN with OK in the lua_prim_rc parameter means that the SLI_OPEN completed successfully and that an LU-LU data flow session was established. After the session is opened successfully, the application program can issue SLI_SEND, SLI_RECEIVE, SLI_PURGE, SLI_BID , or SLI_CLOSE verbs.
Session Recovery
  • The SLI supplies limited session recovery for the application program. When any SLI verb completes with SESSION_FAILURE in the lua_prim_rc parameter, the application program must reissue the SLI_OPEN. In this situation, the program does not have to issue an SLI_CLOSE verb before it issues a new SLI_OPEN verb.
Terminating a Pending SLI_OPEN
  • To terminate a pending SLI_OPEN, issue an SLI_CLOSE with lua_flag1.close_abend parameter set to 1.