HP-UX SNAplus2 R7 LUA Programmer’s Guide HP-UX 11i v1, 11i v2 and 11i v3 Edition: 4 Manufacturing Part Number: 5991–2747 April 2007 © 2007 Hewlett-Packard Development Company, L.P. All rights reserved.
Contents Legal Notices...............................................................................................................................................7 Warranty..............................................................................................................................................7 U.S. Government License.. ................................................................................................................ 7 Copyright Notices.. ................................
2.1.3 2.1.4 2.1.5 2.1.6 Supplied Parameters.. .................................................................................................25 Returned Values..........................................................................................................25 Usage.. ........................................................................................................................ 25 Callback Routine for Asynchronous Verb Completion................................................ 26 2.
2.8.3 Terminating Applications..............................................................................................51 2.9 Writing Portable Applications..................................................................................................51 Chapter 3 LUA VCB Structure.............................................................................................................. 53 3.1 LUA Verb Control Block (VCB) Format................................................................
4.8.1 4.8.2 4.8.3 4.8.4 Supplied Parameters.. .................................................................................................99 Returned Parameters.. .............................................................................................. 100 Interaction with Other Verbs......................................................................................104 Usage and Restrictions.............................................................................................
5.8.3 5.8.4 Interaction with Other Verbs......................................................................................147 Usage and Restrictions.............................................................................................147 5.9 SLI_STSN_ROUTINE........................................................................................................... 148 5.9.1 Supplied Parameters.. ...............................................................................................
Legal Notices Trademark Notices Legal Notices The information in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be held liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance, or use of this material.
Publishing History New and Changed Information in This Edition Publishing History The manual publishing date and part number indicate its current edition. The publishing date will change when a new edition is printed. Minor changes may be made without changing the publishing date. The manual part number will change when extensive changes are made. Manual updates may be issued between editions to correct errors or document product changes.
Before You Begin About This Book Before You Begin This book is a guide for developing C-language application programs that use the Conventional Logical Unit Application (LUA) interface to communicate with a Systems Network Architecture (SNA) host computer. The SNAplus2 implementation of LUA is based on the IBM implementation of the Request/Response Unit Interface (RUI) in its OS/2 products (such as Communications Server for OS/2), with modifications for the HP-UX environment.
Before You Begin About This Book • Chapter 1, Concepts, introduces the fundamental concepts of LUA. It is intended for programmers who are not familiar with LUA. • Chapter 2, Designing and Writing LUA Applications, contains general information a programmer needs when writing LUA applications. This chapter also includes information about SNA concepts relevant to the design of LUA applications, and on compiling and linking an LUA application.
Before You Begin SNAplus2 Publications Special Element Sample of Typography Function, call, or entry point ioctl Data structure termios 3270 key ENTER Keyboard keys [Ctrl+D]; [Enter] Hexadecimal value 0x20 Graphic Conventions UNIX This symbol is used to indicate the start of a section of text that applies only to the HP-UX operating system.
Before You Begin SNAplus2 Publications • Interpreting status-line information • Sending NetView user alerts • Viewing response times HP-UX SNAplus2 RJE User’s Guide Explains how to start and stop the RJE workstation, queue a job for submission to the host, list the queued jobs, cancel a queued job, and send commands to the host’s job entry subsystem (JES).
Before You Begin Related Publications HP-UX SNAplus2/TN3270 HLLAPI Programmer’s Guide Contains the information you need to write application programs using High-Level Language Application Program Interface (HLLAPI). HP-UX SNAplus2 LUA Programmer’s Guide Contains the information you need to write applications using the Conventional LU Application Programming Interface (LUA).
Concepts Choosing Which Interface to Use 1 Concepts This chapter introduces the fundamental concepts of LUA—the Conventional LU (Logical Unit) Application Programming Interface (API). The topics covered in this chapter are as follows: • What is LUA? • Choosing which interface to use (RUI or SLI) • LUs and sessions • LUA verbs • A sample LUA communication sequence • LUA compatibility 1.
Concepts LUs and Sessions • The Session-Level Interface (SLI) is a higher-level interface, allowing the programmer to work at a logical message level rather than being concerned with the detail of individual RUs. For example: • The session can be established and terminated with a single SLI verb (rather than with a sequence of RUI verbs corresponding to the individual RUs involved in session startup and termination).
Concepts LUs and Sessions An LUA application uses an LU of type 0–3 that communicates with the host system by means of the SNAplus2 node. There are three sessions between the SNAplus2 node and the host node, as follows: • The physical unit-system services control point (PU-SSCP) session, between the PU 2.1 and the host’s system services control point (SSCP); this is used for controlling the PU. • The SSCP session, between the SNAplus2 LU and the SSCP; this is used for controlling the LU.
Concepts LUA Verbs • LU session, normal flow The LU session normal flow carries application data; the other flows are used for control messages and start-up. The SNAplus2 implementation of LUA does not enable applications to send data on the SSCP expedited flow, and will not return data to an application on this flow. 1.3.
Concepts LUA Verbs RUI_TERM This verb ends the SSCP session for an LUA application. It also brings down the LU session if it is active. RUI_WRITE This verb sends data to the host on either the SSCP session or the LU session. 1.4.2 SLI Verb Summary The following list contains a brief summary of each of the LUA SLI verbs (for a detailed explanation of each verb, see Chapter 5, SLI Verbs): SLI_BID This verb enables the application to determine when information from the host is available to be read.
Concepts A Sample LUA Communication Sequence If the application does not provide an SDT routine, LUA returns a positive response. 1.4.3 Asynchronous Verb Completion Some LUA verbs complete quickly, after some local processing (for example the RUI_PURGE verb); however, most verbs take some time to complete, because they require messages to be sent to and received from the node or from the host application.
Concepts A Sample LUA Communication Sequence The SLI example shows the same sequence of messages flowing between the host and the application. The SLI verbs used are similar to those used in the RUI example, but note the following differences: • SLI_OPEN handles the complete session initialization; the application does not need to read and write each individual RU in the initialization sequence, as in the RUI example.
Concepts A Sample LUA Communication Sequence Figure 1–3 RUI Communication Sequence LUA Application RUI_INIT RUI_INIT return RUI_WRITE (SSCP norm) RUI_WRITE return LU Host Application ACTLU ACTLU +rsp INITSELF INITSELF +rsp RUI_READ (SSCP norm) RUI_READ return RUI_READ (LU exp) RUI_READ return RUI_WRITE (LU exp) RUI_WRITE return RUI_READ (LU exp) BIND BIND +rsp SDT RUI_READ return RUI_WRITE (LU exp) SDT +rsp RUI_WRITE return RUI_WRITE (LU norm) data, BC RUI_WRITE return RUI_WRITE (LU norm) dat
Concepts LUA Compatibility Figure 1–4 SLI Communication Sequence SLI Application SLI_OPEN LU Host Application ACTLU ACTLU +rsp INITSELF INITSELF +rsp SLI_BIND_ROUTINE SLI_BIND_ROUTINE return SLI_SDT_ROUTINE SLI_SDT_ROUTINE return BIND BIND +rsp SDT SDT +rsp SLI_OPEN completion SLI_SEND (LU norm) data, BC data, MC SLI_SEND completion data, EC,CD,RQD data +rsp SLI_RECEIVE (LU norm) SLI_RECEIVE completion SLI_RECEIVE (LU norm) SLI_RECEIVE completion SLI_SEND (LU norm) SLI_SEND completion SLI_RECEI
Concepts LUA Compatibility The RUI_INIT_PRIMARY and RUI_REINIT verbs are extensions to the standard LUA interface specification. They are not available in the Windows LUA implementation in SNAplus2, and may not be available in other LUA implementations. WINDOWS The SNAplus2 implementation of LUA is designed to be compatible with Windows LUA (as defined by the WOSA SNA specification); applications written for Windows LUA can be used with SNAplus2 without modification.
Designing and Writing LUA Applications LUA Entry Points for HP-UX Applications 2 Designing and Writing LUA Applications The information contained in this chapter will help you write LUA application programs.
Designing and Writing LUA Applications LUA Entry Points for HP-UX Applications 2.1.1 RUI Function Call void RUI(verb) LUA_VERB_RECORD * verb; 2.1.2 SLI Function Call AP_UINT32 SLI(verb) LUA_VERB_RECORD * verb; 2.1.3 Supplied Parameters Supplied parameter is: verb Pointer to a Verb Control Block (VCB) that contains the parameters for the verb being issued. The VCB structure is defined in the LUA header file /usr/include/sna/lua_c.h, and is described in Chapter 3, LUA VCB Structure.
Designing and Writing LUA Applications LUA Entry Points for HP-UX Applications happens, the verb returns synchronously; the primary return code is set to a value other than LUA_IN_PROGRESS, and the lua_flag2.async bit is set to 0 (zero). (For information about these returned parameters, see Chapter 4, RUI Verbs or Chapter 5, SLI Verbs.) At other times, LUA must wait for information from the remote LU or from the node before it can complete the verb.
Designing and Writing LUA Applications LUA Entry Points for Windows Applications Note Because of the way HP-UX callback routines operate, it is possible that the application’s callback routine will be called before control returns to the application from its initial function call for the verb. This means that, if the callback routine modifies or deletes the returned VCB, the program’s main thread of execution may be unable to check the VCB parameters to determine that the verb is operating asynchronously.
Designing and Writing LUA Applications LUA Entry Points for Windows Applications Issues an SLI verb. If the verb completes asynchronously, LUA will indicate the completion by posting a message to the application window. WinSLICleanup Unregisters the application when it has finished using SLI. An RUI application must call WinRUIStartup before attempting to issue any LUA verbs using the WinRUI call.
Designing and Writing LUA Applications LUA Entry Points for Windows Applications Note The LUA VCB contains many parameters marked as “reserved”; some of these are used internally by the SNAplus2 software, and others are not used in this version but may be used in future versions.
Designing and Writing LUA Applications LUA Entry Points for Windows Applications WORD wVersion; char szDescription[41]; } LUADATA; Supplied Parameters Supplied parameter is: wVersionRequired The version of Windows LUA that the application requires. SNAplus2 supports Version 1.0. The low-order byte specifies the major version number, and the high-order byte specifies the minor version number. For example: Version wVersionRequired 1.0 0x0001 1.1 0x0101 2.
Designing and Writing LUA Applications LUA Entry Points for Windows Applications • If the returned version number is the same as the requested version number, the application can use this Windows LUA implementation. • If the returned version number is lower than the requested version number, the application can use this Windows LUA implementation but must not attempt to use features that are not supported by the returned version number.
Designing and Writing LUA Applications LUA Entry Points for Windows Applications Returned Values The return value from the function is one of the following: 0 (zero) The function call was accepted, and the LUA verb will be processed. The application should check the lua_flag2.async parameter in the VCB structure to determine whether the verb has already completed synchronously or will complete asynchronously, as described in Section 2.2.3, WinRUI.
Designing and Writing LUA Applications LUA Entry Points for Windows Applications 2.2.4 WinRUIGetLastInitStatus The application uses this function to determine the status of a previous RUI_INIT verb that is still outstanding. It can use the returned information to decide whether to cancel the session initiation (by issuing RUI_TERM) or to wait for the session to be established.
Designing and Writing LUA Applications LUA Entry Points for Windows Applications WLUA_NTFY_MSG_SID The StatusHandle parameter contains a window handle. Identify the verb using the lua_sid value returned on the RUI_INIT verb. WLUA_NTFY_EVENT The StatusHandle parameter contains an event handle. If the StatusHandle parameter is null (to request current status information), or if the ClearPrevious parameter is set to TRUE (to cancel a previous notification request), LUA ignores this parameter.
Designing and Writing LUA Applications LUA Entry Points for Windows Applications The application has not issued the WinRUIStartup call, which is required before issuing any LUA verbs. WLUAUNKNOWN Internal error: the session status is unknown. WLUASIDINVALID The supplied Sid parameter did not match the session ID of an outstanding RUI_INIT verb.
Designing and Writing LUA Applications LUA Entry Points for Windows Applications Function Call BOOL WINAPI WinRUICleanup (void); Supplied Parameters There are no supplied parameters for this function. Returned Values The return value from the function is one of the following: TRUE The application was unregistered successfully. FALSE An error occurred during processing of the call, and the application was not unregistered. Check the log files for messages indicating the cause of the failure. 2.2.
Designing and Writing LUA Applications LUA Entry Points for Windows Applications The supplied data buffer is too small to hold the returned character string. 0x20000003 The dynamic link library, LUASTR32.DLL, which generates the returned character strings for this function, could not be loaded. If the return value is 0 (zero), the returned character string is in the buffer identified by the buffer_addr parameter.
Designing and Writing LUA Applications LUA Entry Points for Windows Applications lua_flag2.async bit is set to 1. The application can now perform other processing, or wait for notification from LUA that the verb has completed. LUA issues this notification by setting the primary return code to its final value, leaving the lua_flag2.async bit set to 1. As part of the supplied VCB, the application supplies an event handle in the lua_post_handle parameter.
Designing and Writing LUA Applications LUA Entry Points for Windows Applications WLUAVERNOTSUPPORTED The version number specified by the application is not supported by the Windows LUA software. The application was not registered. WLUAINITREJECT The application has already called WinSLIStartup and registered successfully. It must not call this function more than once. WLUASYSNOTREADY The SNAplus2 software has not been started, or the local node is not active. The application was not registered.
Designing and Writing LUA Applications LUA Entry Points for Windows Applications hWnd A window handle that LUA will use to post a message indicating asynchronous verb completion. lpVCB A pointer to the VCB structure for the verb. For the WinSLI function, the lua_post_handle parameter is reserved; leave it as 0 (zero). For more information about the VCB structure, see Chapter 3, LUA VCB Structure. For more information about on its usage for individual verbs, see Chapter 5, SLI Verbs.
Designing and Writing LUA Applications Issuing an LUA Verb • The lParam argument contains the address of the VCB that was supplied to the original WinSLI call; the application can use this address to access the returned parameters in the VCB structure. • The wParam argument is undefined. Synchronous and Asynchronous Verb Completion Sometimes LUA is able to complete all the processing for a verb as soon as it is issued.
Designing and Writing LUA Applications Issuing an LUA Verb UNIX #include < lua_c.h> WINDOWS #include < winlua.h > UNIX 2. Set up a callback function that LUA will use to indicate that the verb has completed asynchronously. (For more information, see Section 2.1, LUA Entry Points for HP-UX Applications.) void callback(verb) LUA_VERB_RECORD * verb; { . . .
Designing and Writing LUA Applications Issuing an LUA Verb UNIX rui_init.common.lua_post_handle = (unsigned long) callback; WINDOWS The rui_init.common.lua_post_handle parameter is reserved; leave it as 0 (zero). The values LUA_VERB_RUI and LUA_OPCODE_RUI_INIT are symbolic constants. These constants are defined in the header file /usr/include/sna/lua_c.h (HP-UX applications) or sdk/winlua.
Designing and Writing LUA Applications SNA Information if( rui_init.common.lua_prim_rc == LUA_OK ) { /* Init OK */ . . . } else { /* Do error routine */ . . . } 2.4 SNA Information This section explains some SNA information that you need to consider when writing SNAplus2 LUA applications for communications with a host. If you are writing an RUI Primary application for communications with a downstream LU, see Section 2.5, SNA Information for RUI Primary.
Designing and Writing LUA Applications SNA Information On the SLI_OPEN verb, the application can optionally specify the address of its own routine to process BIND requests from the host. If it has done so, LUA sends an additional verb SLI_BIND_ROUTINE to the applicationsupplied routine to allow it to process the request, as follows. It is the responsibility of the LUA application to check that the parameters specified on the BIND are suitable.
Designing and Writing LUA Applications SNA Information Distinguishing SNA Sense Codes from Other Secondary Return Codes Note The byte ordering used in LUA secondary return codes means that the most significant byte of the numeric value is the last byte, not the first byte. For a secondary return code that is not a sense code, the two most significant bytes of this value are always 0 (zero). As an example, 0x01000000 (LUA_INVALID_LUNAME) is a standard LUA secondary return code and not a sense code.
Designing and Writing LUA Applications SNA Information for RUI Primary If the host specifies exception response only (a negative response can be sent but a positive response should not be sent), SNAplus2 must still keep a record of the request in case the application subsequently sends a negative response. If the application does not send a response, the storage associated with this request cannot be freed.
Designing and Writing LUA Applications SNA Information for RUI Primary • Compression (if required). 2.5.2 Pacing Pacing is handled by the LUA interface; an LUA application does not need to control pacing, and should never set the Pacing Indicator flag. If pacing is being used on data sent from the LUA application to the host (this is determined by the BIND), an RUI_WRITE verb may take some time to complete.
Designing and Writing LUA Applications HP-UX Environment Considerations 2.6 Configuration Information The SNAplus2 configuration file, which is set up and maintained by the System Administrator, contains information that is required for LUA applications to communicate. For additional information, refer to the HP-UX SNAplus2 Administration Guide. UNIX For a Primary RUI application communicating with a downstream LU, the only configuration required is the downstream LU (or a Downstream PU template).
Designing and Writing LUA Applications Windows Environment Considerations usr/include/sna/values_c.h; these two files contain all the constants defined for supplied and returned parameter values at the LUA interface. The file values_c.h also includes definitions of parameter types such as AP_UINT16 that are used in the LUA VCBs. 2.7.
Designing and Writing LUA Applications Writing Portable Applications DWORD parameters are on DWORD boundaries, WORD parameters are on WORD boundaries, and BYTE parameters are on BYTE boundaries. Header File The header file to be included in Windows LUA applications is named winlua.h. This file is installed in the subdirectory /sdk within the directory where you installed the Windows Client software. Load-Time Linking To link the program to LUA at load time, link the program to the winsli32.lib library.
Designing and Writing LUA Applications Writing Portable Applications • Use the symbolic constant names for parameter values and return codes, not the numeric values shown in the header file; this ensures that the correct value will be used regardless of the way these values are stored in memory. • When accessing SNA sense codes in a data buffer, use the symbolic constants rather than the numeric values; this ensures that the byte storage order will be correct for your particular system.
LUA VCB Structure LUA Verb Control Block (VCB) Format 3 LUA VCB Structure This chapter contains details of the LUA verb control block structure used for all LUA verbs. Symbolic constants are defined in the header files /usr/include/sna/lua_c.h and /usr/include/sna/ values_c.h (HP-UX operating system) or sdk/winlua.h (Windows operating system)for many parameter values.
LUA VCB Structure LUA Verb Control Block (VCB) Format Note The LUA VCB contains many parameters marked as “reserved”; some of these are used internally by the SNAplus2 software, and others are not used in this version but may be used in future versions. Your application must not attempt to access any of these reserved parameters; instead, it must set the entire contents of the VCB to zero to ensure that all of these parameters are zero, before it sets other parameters that are used by the verb.
LUA VCB Structure LUA Verb Control Block (VCB) Format struct LUA_RH { BIT_FIELD_TYPE BIT_FIELD_TYPE BIT_FIELD_TYPE BIT_FIELD_TYPE BIT_FIELD_TYPE BIT_FIELD_TYPE BIT_FIELD_TYPE : : : : : : : 1; 2; 1; 1; 1; 1; 1; /* /* /* /* /* /* /* /* LUA RH Fields Request-Response Indicator RU Category Reserved Field Format Indicator Sense Data Included Ind Begin Chain Indicator End Chain Indicator */ */ */ */ */ */ */ */ BIT_FIELD_TYPE BIT_FIELD_TYPE BIT_FIELD_TYPE BIT_FIELD_TYPE BIT_FIELD_TYPE BIT_FIELD_TYPE BIT_FI
LUA VCB Structure LUA Verb Control Block (VCB) Format struct LUA_COMMON { unsigned short unsigned short unsigned short unsigned long unsigned short unsigned long unsigned char unsigned short unsigned short unsigned long unsigned short unsigned short char far unsigned long struct LUA_TH { unsigned char unsigned char unsigned char unsigned char unsigned char unsigned char unsigned char unsigned char } lua_th; struct LUA_RH { unsigned char unsigned char unsigned char unsigned char unsigned char unsigned cha
LUA VCB Structure LUA Verb Control Block (VCB) Format unsigned char unsigned char unsigned char unsigned char unsigned char unsigned char } lua_flag1; unsigned char close_abend nowait sscp_exp sscp_norm lu_exp lu_norm unsigned char unsigned char } ; 1; 1; 1; 1; 1; 1; lua_message_type; struct LUA_FLAG2 { unsigned char bid_enable unsigned char async unsigned char unsigned char unsigned char unsigned char unsigned char } lua_flag2; : : : : : : sscp_exp sscp_norm lu_exp lu_norm : 1; : 1; : : : : : 2;
LUA VCB Structure LUA Verb Control Block (VCB) Format The LU name used by the LUA session (in ASCII). This can be an LU name or an LU pool name; for more information, see Section 4.2, RUI_INIT or Section 5.3, SLI_OPEN. UNIX For RUI_INIT_PRIMARY, this must match the dslu_name parameter of a downstream LU configured for use with PU Concentration (or a downstream LU created implicitly by defining a downstream LU template). lua_extension_list_offset This field is reserved.
LUA VCB Structure LUA Verb Control Block (VCB) Format lua_th.oaf OAF (Originating address field) lua_th.snf Sequence Number Field lua_rh A data structure containing the RH (request/response header) of the message sent or received, as follows: lua_rh.rri Request-Response Indicator lua_rh.ruc RU category: 2 bits lua_rh.fi Format Indicator lua_rh.sdi Sense Data Included Indicator lua_rh.bci Begin Chain Indicator lua_rh.eci End Chain Indicator lua_rh.dr1i Definite Response 1 Indicator lua_rh.
LUA VCB Structure LUA Verb Control Block (VCB) Format lua_rh.pdi Padded Data Indicator lua_flag1 A data structure containing flags for messages supplied by the application, as follows: lua_flag1.bid_enable Bid Enable Indicator lua_flag1.close_abend Close Immediate Indicator lua_flag1.nowait No Wait For Data flag lua_flag1.sscp_exp SSCP expedited flow lua_flag1.sscp_norm SSCP normal flow lua_flag1.lu_exp LU expedited flow lua_flag1.
LUA VCB Structure LUA Verb Control Block (VCB) Format 3.1.
LUA VCB Structure LUA Verb Control Block (VCB) Format struct RUI_INIT { unsigned char unsigned char unsigned char unsigned char }; rui_init_format; lua_puname[8]; lua_lunumber; wait_for_link; For RUI_BID and SLI_BID, this data structure contains the following field: lua_peek_data Up to 12 bytes of the data waiting to be read. UNIX For the extended form of the RUI_INIT verb, this data structure contains the following fields. For more information about the extended form of RUI_INIT, see Section 4.
LUA VCB Structure LUA Verb Control Block (VCB) Format Type of extension routine (BIND, SDT, or STSN). UNIX lua_open_extension.lua_routine_ptr Pointer to the extension routine entry point. WINDOWS lua_open_extension.lua_module_name Name of the DLL containing the extension module. lua_open_extension.lua_procedure_name Procedure name to call within the extension module DLL.
RUI Verbs RUI_BID 4 RUI Verbs This chapter contains a description of each LUA RUI verb. The following information is provided for each verb: • Purpose of the verb. • Parameters (VCB fields) supplied to and returned by LUA. The description of each parameter includes information about the valid values for that parameter, and any additional information necessary. • Interaction with other verbs. • Additional information describing the use of the verb.
RUI Verbs RUI_BID 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 or RUI_INIT_PRIMARY 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. lua_sid The session ID of the session. RUI_INIT_PRIMARY verb.
RUI Verbs RUI_BID The RH of the received message.
RUI Verbs RUI_BID Unsuccessful Execution 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. Verb Canceled 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.
RUI Verbs RUI_BID An RUI_INIT or RUI_INIT_PRIMARY verb has not yet completed successfully for the LU name specified on this verb, or the session has failed. Negative Response Sent to Host The following return code indicates that SNAplus2 detected an error in the data received from the host. Instead of passing the received message to the application on an RUI_READ verb, SNAplus2 discards the message (and the rest of the chain if it is in a chain), and sends a negative response to the host.
RUI Verbs RUI_BID • 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 SNAplus2 support personnel. lua_prim_rc LUA_INVALID_VERB Either the lua_verb parameter or the lua_opcode parameter was not valid. The verb did not execute.
RUI Verbs RUI_INIT • 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.
RUI Verbs RUI_INIT lua_luname The name in ASCII of the LU or LU pool for which you want to start the session. This must match the name of an LU of type 0–3, or of an LU pool, configured for SNAplus2. The name is used as follows: • If the name is the name of an LU that is not in a pool, SNAplus2 attempts to start the session using this LU. An application can start multiple sessions by using multiple RUI_INIT verbs with a different LU for each verb; it cannot start more than one session for the same LU.
RUI Verbs RUI_INIT The name of the PU that owns the LU to be used for the session. The name must be in ASCII, padded with spaces on the right (0x20). It must match a PU name defined in the SNAplus2 configuration. lua_lunumber The LU number of the LU to be used for the session. This must match the LU number of a type 0–3 LU configured to use the specified PU.
RUI Verbs RUI_INIT LUA_TERMINATED An RUI_TERM verb was issued before the RUI_INIT had completed. Parameter Check 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 are: LUA_INVALID_LUNAME The LU identified by the lua_luname parameter could not be found on any active nodes.
RUI Verbs RUI_INIT LUA_DUPLICATE_RUI_INIT An RUI_INIT verb is currently being processed for this session. Other Conditions 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 are: 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.
RUI Verbs RUI_INIT lua_prim_rc LUA_COMM_SUBSYSTEM_ABENDED A required SNAplus2 software component (such as the node) has terminated or has been stopped. Contact your System Administrator if necessary. lua_prim_rc LUA_SESSION_FAILURE 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.
RUI Verbs RUI_INIT_PRIMARY 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, or until an LUA_SESSION_FAILURE primary return code is received. If the RUI_INIT verb returns with an LUA_IN_PROGRESS primary return code then the Session ID will be returned in the lua_sid parameter.
RUI Verbs RUI_INIT_PRIMARY A pointer to a callback routine. If the verb completes asynchronously, LUA will call this routine to indicate completion of the verb. For more information, see Chapter 2, Designing and Writing LUA Applications. lua_encr_decr_option Session-level cryptography option. SNAplus2 accepts the following two values: 0 Session-level cryptography is not used. 128 Encryption and decryption are performed by the application program.
RUI Verbs RUI_INIT_PRIMARY Parameter Check 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 are: LUA_INVALID_LUNAME The LU identified by the lua_luname parameter could not be found on any active nodes.Check that the LU name is defined in the configuration file and that the nodeon which it is configured has been started.
RUI Verbs RUI_INIT_PRIMARY lua_prim_rc LUA_COMM_SUBSYSTEM_NOT_LOADED This return code indicates one of the following conditions: • The SNAplus2 software has not been started. The SNAplus2 software must be started before you can use LUA verbs. Contact your System Administrator if necessary. • There are no active SNAplus2 nodes. The local node that owns the requested downstream LU must be started before you can use LUA verbs. Contact your System Administrator if necessary.
RUI Verbs RUI_PURGE 4.3.4 Usage and Restrictions The RUI_INIT_PRIMARY verb completes after an ACTLU positive response is received from the downstream LU. If necessary, the verb waits indefinitely. If the application needs to check the contents of this ACTLU positive response, it can do so by supplying a data buffer on RUI_INIT_PRIMARY (using the lua_max_length and lua_data_ptr parameters) in which SNAplus2 returns the contents of the received message.
RUI Verbs RUI_PURGE 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 VCB that is to be purged. lua_post_handle UNIX A pointer to a callback routine that LUA will call to indicate completion if the verb completes asynchronously. WINDOWS If the VCB is used in an RUI function call, set this field to an event handle.
RUI Verbs RUI_PURGE lua_prim_rc LUA_PARAMETER_CHECK lua_sec_rc Possible values are: LUA_BAD_DATA_PTR The lua_data_ptr parameter was set to 0 (zero). LUA_BAD_SESSION_ID The lua_sid parameter did not match the session ID of any active LUA LU session. UNIX LUA_INVALID_POST_HANDLE The lua_post_handle parameter was not a valid pointer to a callback routine. 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.
RUI Verbs RUI_PURGE lua_prim_rc LUA_COMM_SUBSYSTEM_ABENDED A required SNAplus2 software component (such as the node) has terminated or has been stopped. Contact your System Administrator if necessary. lua_prim_rc LUA_SESSION_FAILURE The LUA session has failed. If the session was started using RUI_INIT (not RUI_INIT_PRIMARY) and the secondary return code is not LUA_RUI_LOGIC_ERROR, then this LU can be reinitialized using an RUI_REINIT.
RUI Verbs RUI_READ The node was either not started or not configured properly for LUA applications. Check the SNAplus2 LUA configuration parameters and start the node before running your application. 4.4.3 Interaction with Other Verbs 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). 4.5 RUI_READ The RUI_READ verb receives data or status information sent from the host to the application’s LU.
RUI Verbs RUI_READ lua_data_ptr A pointer to the buffer supplied to receive the data. lua_post_handle UNIX A pointer to a callback routine that LUA will call to indicate completion if the verb completes asynchronously. WINDOWS If the VCB is used in an 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 Chapter 2, Designing and Writing LUA Applications. lua_flag1 parameters Set the lua_flag1.
RUI Verbs RUI_READ This parameter is set to 1 if the verb completed asynchronously, or 0 if the verb completed synchronously. lua_flag2.bid_enable This parameter is set to 1 if an RUI_BID was successfully re-enabled, or to 0 if it was not re-enabled. Other returned parameters depend on whether the verb completed successfully; see the following sections.
RUI Verbs RUI_READ LUA_MESSAGE_TYPE_SDT LUA_MESSAGE_TYPE_STSN LUA_MESSAGE_TYPE_UNBIND UNIX The following values can be returned only to an RUI primary application (one that started the session using RUI_INIT_PRIMARY): LUA_MESSAGE_TYPE_INIT_SELF LUA_MESSAGE_TYPE_NOTIFY LUA_MESSAGE_TYPE_TERM_SELF lua_flag2 parameters One of the following flags will be set to 1, to indicate on which message flow the data was received: lua_flag2.lu_exp lua_flag2.sscp_norm lua_flag2.
RUI Verbs RUI_READ LUA_BAD_SESSION_ID The lua_sid parameter did not match the session ID of any active LUA LU session. LUA_BID_ALREADY_ENABLED The lua_flag1.bid_enable parameter was set to re-enable an RUI_BID verb, but the previous RUI_BID verb was still in progress. LUA_DUPLICATE_READ_FLOW The flow flags in the lua_flag1 group specified one or more session flows for which an RUI_READ verb was already outstanding. Only one RUI_READ at a time can be waiting on each session flow.
RUI Verbs RUI_READ lua_prim_rc LUA_NEGATIVE_RSP lua_sec_rc A nonzero secondary return code contains the sense code sent to the host on the negative response. This indicates that SNAplus2 detected an error in the host data, and sent a negative response to the host. For information about interpreting the sense code values that can be returned, see Section 2.4, SNA Information.
RUI Verbs RUI_READ LUA_RUI_LOGIC_ERROR 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 SNAplus2 support personnel.
RUI Verbs RUI_REINIT flows, it will always accept the data if RUI_READ does not). The application must then issue another RUI_READ on the appropriate flow to obtain the data. If you want to use RUI_BID to handle data on all flows, rather than having the data on a particular flow handled by RUI_READ in preference to RUI_BID, you need to re-issue RUI_BID explicitly instead of using RUI_READ to re-enable the previous RUI_BID. 4.5.
RUI Verbs RUI_REINIT 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. lua_sid The session ID of the session. This must match a session ID returned on the previous RUI_INIT verb for the failed session.
RUI Verbs RUI_REINIT Possible values are: LUA_INVALID_POST_HANDLE The lua_post_handle parameter was not a valid pointer to a callback routine. 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.
RUI Verbs RUI_REINIT lua_prim_rc LUA_COMM_SUBSYSTEM_ABENDED A required SNAplus2 software component (such as the node) has terminated or has been stopped. Contact your System Administrator if necessary. lua_prim_rc LUA_SESSION_FAILURE 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.
RUI Verbs RUI_TERM Once the RUI_REINIT 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, or until an LUA_SESSION_FAILURE primary return code is received. If the secondary return code is not LUA_RUI_LOGIC_ERROR, then this LU can be reinitialized using an RUI_REINIT.
RUI Verbs RUI_TERM UNIX A pointer to a callback routine that LUA will call to indicate completion if the verb completes asynchronously. WINDOWS If the VCB is used in an 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 Chapter 2, Designing and Writing LUA Applications. 4.7.2 Returned Parameters LUA always returns the following parameter: lua_flag2.
RUI Verbs RUI_TERM The value of the lua_verb_length parameter was less than the length of the verb record required for this verb. State Check 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_NO_RUI_SESSION Either there is no LUA session with the LU name specified on this verb, or the session has failed.
RUI Verbs RUI_TERM 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 SNAplus2 support personnel. lua_prim_rc LUA_INVALID_VERB Either the lua_verb parameter or the lua_opcode parameter was not valid.
RUI Verbs RUI_WRITE 4.8 RUI_WRITE The RUI_WRITE verb sends an SNA request or response unit from the LUA application to the host, over either the LU session or the SSCP session. 4.8.1 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(LUA_COMMON). lua_opcode LUA_OPCODE_RUI_WRITE lua_correlator Optional.
RUI Verbs RUI_WRITE For a negative response, the buffer should contain the SNA sense code. lua_post_handle UNIX A pointer to a callback routine that LUA will call to indicate completion if the verb completes asynchronously. WINDOWS If the VCB is used in an 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 Chapter 2, Designing and Writing LUA Applications. lua_th.snf Required only when sending a response.
RUI Verbs RUI_WRITE If the application specified the lua_luname parameter when issuing this verb, rather than specifying the session ID, LUA supplies the session ID. lua_th The completed TH of the message written, including the fields filled in by LUA. You may need to save the value of lua_th.snf (the sequence number) for correlation with responses from the host. lua_rh The completed RH of the message written, including the fields filled in by LUA.
RUI Verbs RUI_WRITE The lua_flag1.sscp_exp flow flag was set, indicating that the message should be sent on the SSCP expedited flow. SNAplus2 does not allow applications to send data on this flow. UNIX LUA_INVALID_POST_HANDLE The lua_post_handle parameter was not a valid pointer to a callback routine. LUA_MULTIPLE_WRITE_FLOWS More than one of the lua_flag1 flow flags was set to 1. One and only one of these flags must be set to 1, to indicate which session flow the data is to be sent on.
RUI Verbs RUI_WRITE • The lua_rh.fi bit (Format Indicator) was set to 1, but the first byte of the supplied RU was not a recognized request code. • The lua_rh.ruc parameter (RU category) specified the Network Control (NC) category; SNAplus2 does not allow applications to send requests in this category. LUA_INVALID_PROCESS The operating system process that issued this verb was not the same process that issued the RUI_INIT or RUI_INIT_PRIMARY verb for this session.
RUI Verbs RUI_WRITE • 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 SNAplus2 support personnel. lua_prim_rc LUA_INVALID_VERB Either the lua_verb parameter or the lua_opcode parameter was not valid. The verb did not execute.
SLI Verbs SLI_BID 5 SLI Verbs This chapter contains a description of each LUA SLI verb. The following information is provided for each verb: • Purpose of the verb. • Parameters (VCB fields) supplied to and returned by LUA. The description of each parameter includes information about the valid values for that parameter, and any additional information necessary. • Interaction with other verbs. • Additional information describing the use of the verb.
SLI Verbs SLI_BID lua_luname 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 SLI_OPEN 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. lua_sid The session ID of the session.
SLI Verbs SLI_BID lua_message_type Message type of the received message, which is 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_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_SIGNAL LUA_MESSAGE_TYPE_STSN The SLI uses th
SLI Verbs SLI_BID LUA_NOT_READY The SLI session has been temporarily suspended for one of the following reasons: • A CLEAR command was received. The session resumes when an SDT command is received. • An UNBIND command type X’02’ (BIND forthcoming) was received. The session is suspended until a BIND, optional CRV and STSN, and SDT commands are received; it resumes after the SDT. Any user extension routines that were supplied by the original SLI_OPEN verb will be called again.
SLI Verbs SLI_BID LUA_INVALID_LUNAME The LU identified by the lua_luname parameter could not be found on any active nodes.Check that the LU name or LU pool name is defined in the configuration file and that the node on which it is configured has been started. UNIX LUA_INVALID_POST_HANDLE The lua_post_handle parameter was not a valid pointer to a callback routine. 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.
SLI Verbs SLI_BID lua_sec_rc LUA_INVALID_PROCESS The operating system process that issued this verb was not the same process that issued the SLI_OPEN 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: lua_prim_rc LUA_COMM_SUBSYSTEM_ABENDED A required SNAplus2 software component (such as the node) has terminated. Contact your System Administrator if necessary.
SLI Verbs SLI_CLOSE This value is the operating system return code. Check your operating system documentation for the meaning of this return code. 5.1.3 Interaction with Other Verbs The SLI_OPEN verb must complete successfully before this verb can be issued. Only one SLI_BID for each session can be outstanding at any one time. After the SLI_BID verb has completed successfully, it may be re-issued by setting the lua_flag1.bid_enable parameter on a subsequent SLI_RECEIVE verb.
SLI Verbs SLI_CLOSE LUA_VERB_SLI lua_verb_length The length in bytes of the LUA verb record. Set this to sizeof(LUA_VERB_RECORD). lua_opcode LUA_OPCODE_SLI_CLOSE lua_correlator 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. lua_luname The name in ASCII of the LU used by the session.
SLI Verbs SLI_CLOSE lua_prim_rc LUA_OK Unsuccessful Execution 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.
SLI Verbs SLI_CLOSE If the SLI_CLOSE verb was issued to cancel an outstanding SLI_OPEN verb, using the lua_luname parameter supplied to the outstanding verb, this return code may indicate that the SLI_OPEN completed before this verb was processed. The verb may have completed unsuccessfully (and so there is no session), or SLI_OPEN may have completed successfully using a different LU from the pool specified by lua_luname (and so there is no session for the specified LU name).
SLI Verbs SLI_CLOSE The following return codes indicate that the verb did not complete successfully for other reasons: lua_prim_rc LUA_COMM_SUBSYSTEM_ABENDED A required SNAplus2 software component (such as the node) has terminated or has been stopped. Contact your System Administrator if necessary. lua_prim_rc LUA_COMM_SUBSYSTEM_NOT_LOADED The node was either not started or not configured properly for LUA applications.
SLI Verbs SLI_CLOSE lua_prim_rc LUA_INVALID_VERB Either the lua_verb parameter or the lua_opcode parameter was not valid. The verb did not execute. 5.2.3 Interaction with Other Verbs This verb may be issued at any time after the SLI_OPEN verb has been issued. If SLI_OPEN has not yet completed and the application wants to cancel it, it should do so by issuing SLI_CLOSE with lua_flag1.close_abend set to 1 (indicating an abnormal close).
SLI Verbs SLI_OPEN In either of these cases, the SLI_CLOSE verb returns with the primary return code CANCELLED. The session is not closed; the application should issue SLI_BID or SLI_RECEIVE to get status information. Any user extension routines specified by the application on the SLI_OPEN verb will be called again when the host sends the new BIND.
SLI Verbs SLI_OPEN lua_data_ptr A pointer to the message, if any, that must be sent to the host to start the session. This depends on the lua_init_type parameter, as follows. • If lua_init_type is LUA_INIT_TYPE_SEC_IS, the application must provide an INITSELF request unit containing the required user information such as the mode name and PLU name. • If lua_init_type is LUA_INIT_TYPE_SEC_LOG, the application must provide an unformatted LOGON message to be sent on the SSCP normal flow.
SLI Verbs SLI_OPEN LUA_SESSION_TYPE_DEDICATED Send a positive response, and suspend the SLI session until BIND, optional CRV and STSN, and SDT commands are received. NOTIFY(disabled) is not sent to the SSCP. In this case the application can end the suspended session, without waiting for a new BIND from the host, by issuing SLI_CLOSE (abend). lua_wait Timeout (in seconds) for retrying a secondary-initiated session initiation.
SLI Verbs SLI_OPEN lua_open_extension.lua_module_name Name of the DLL containing the extension module. This parameter is not used in the last array entry, in which lua_open_extension.lua_routine_type is set to LUA_ROUTINE_TYPE_END. lua_open_extension.lua_procedure_name Procedure name to call within the extension module DLL. This parameter is not used in the last array entry, in which lua_open_extension.lua_routine_type is set to LUA_ROUTINE_TYPE_END.
SLI Verbs SLI_OPEN Unsuccessful Execution 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. Verb Canceled 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 SLI_CLOSE verb was issued before the SLI_OPEN had completed.
SLI Verbs SLI_OPEN 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. LUA_BAD_DATA_PTR The lua_data_ptr parameter contained a value that was not valid. LUA_BAD_SESSION_ID The lua_sid parameter did not match the session ID of any active LUA LU session.
SLI Verbs SLI_OPEN • 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 SNAplus2 support personnel. (any other value) Any other secondary return code here is an SNA sense code. For information about interpreting the SNA sense codes that can be returned, see Section 2.4, SNA Information.
SLI Verbs SLI_OPEN • 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 SNAplus2 support personnel. lua_prim_rc LUA_INVALID_VERB Either the lua_verb parameter or the lua_opcode parameter was not valid. The verb did not execute.
SLI Verbs SLI_PURGE 5.4 SLI_PURGE The SLI_PURGE verb cancels a previous SLI_RECEIVE. An SLI_RECEIVE may wait indefinitely if it is sent without using the lua_flag1.nowait (immediate return) option, and no data is available on the specified flow; SLI_PURGE forces the waiting verb to return (with the primary return code LUA_CANCELLED). 5.4.1 Supplied Parameters The application supplies the following parameters: lua_verb LUA_VERB_SLI lua_verb_length The length in bytes of the LUA verb record.
SLI Verbs SLI_PURGE 5.4.2 Returned Parameters LUA always returns the following parameter: lua_flag2.async 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.
SLI Verbs SLI_PURGE 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.
SLI Verbs SLI_PURGE 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 SNAplus2 support personnel. The following return codes indicate that the verb did not complete successfully for other reasons: lua_prim_rc LUA_COMM_SUBSYSTEM_ABENDED A required SNAplus2 software component (such as the node) has terminated or has been stopped.
SLI Verbs SLI_RECEIVE 5.5 SLI_RECEIVE The SLI_RECEIVE verb receives a complete chain of data, or status information, sent from the host to the application’s LU. You can specify a particular message flow (LU normal, LU expedited, SSCP normal, or SSCP expedited) from which to read data, or you can specify more than one message flow. You can have multiple SLI_RECEIVE verbs outstanding, provided that no two of them specify the same flow. 5.5.
SLI Verbs SLI_RECEIVE If the VCB is used in an SLI function call, set this field to an event handle. If the VCB is used in a WinSLI function call, this field is reserved. For more information, see Chapter 2, Designing and Writing LUA Applications. lua_flag1 parameters Set the lua_flag1.nowait parameter to 1 if you want the SLI_RECEIVE verb to return as soon as possible whether or not data is available to be read, or set it to 0 (zero) if you want the verb to wait for data before returning. Notes 1.
SLI Verbs SLI_RECEIVE Successful Execution or Truncated Data If the verb executes successfully, LUA returns the following parameters: lua_prim_rc LUA_OK The following parameters are returned if the verb completes successfully. They are also returned if the verb returns with truncated data because the lua_data_length parameter supplied was too small (see Section 5.5.2, Returned Parameters).
SLI Verbs SLI_RECEIVE lua_flag2.lu_norm The SNAplus2 implementation of LUA does not return data on the SSCP expedited flow, and so the sscp_exp flag will never be set (although it may be set by other LUA implementations). Successful Execution: Status Information Note SLI_RECEIVE can return status information only if there is no SLI_BID verb outstanding.
SLI Verbs SLI_RECEIVE Verb Canceled The following return codes indicate that the verb did not complete successfully because it was canceled by another verb or by a message from the host: lua_prim_rc LUA_CANCELLED lua_sec_rc Possible values are: LUA_PURGED This SLI_RECEIVE verb has been canceled by an SLI_PURGE verb. LUA_TERMINATED An SLI_CLOSE verb was issued while this verb was pending.
SLI Verbs SLI_RECEIVE 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. State Check 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 are: LUA_NO_SLI_SESSION An SLI_OPEN verb has not yet completed successfully for the LU name specified on this verb, or the session has failed.
SLI Verbs SLI_RECEIVE The operating system process that issued this verb was not the same process that issued the SLI_OPEN verb for this session. Only the process that started a session can issue verbs on that session. LUA_NAU_INOPERATIVE A required SNA component (such as the LUA LU) is not active or is in an abnormal state. LUA_NO_SESSION The SNA session to the remote LU is not active.
SLI Verbs SLI_RECEIVE The stack size of the application is too small for LUA to complete the request. Increase the stack size of your application. lua_prim_rc LUA_UNEXPECTED_DOS_ERROR An operating system error occurred. lua_sec_rc This value is the operating system return code. Check your operating system documentation for the meaning of this return code. 5.5.3 Interaction with Other Verbs The SLI_OPEN verb must have completed successfully before this verb can be issued.
SLI Verbs SLI_SEND between the SLI_BID and SLI_RECEIVE verbs. To ensure that it receives the same message that was identified in the SLI_BID, it should set the lua_flag1 flags on SLI_RECEIVE to accept data only on the flow identified in the SLI_BID response. Pacing may be used on the primary-to-secondary half-session (this is specified in the host configuration), in order to protect the LUA application from being flooded with messages.
SLI Verbs SLI_SEND When sending a positive response, this parameter is normally set to 0 (zero). LUA will complete the response based on the supplied sequence number. In the case of a positive response to a BIND or STSN, an extended response is allowed, so a nonzero value may be used. When sending a negative response, set this parameter to the length of the SNA sense code (four bytes), which is supplied in the data buffer. lua_data_ptr A pointer to the buffer containing the supplied data.
SLI Verbs SLI_SEND LUA_MESSAGE_TYPE_RSP LUA_MESSAGE_TYPE_BID LUA_MESSAGE_TYPE_BIS LUA_MESSAGE_TYPE_CANCEL LUA_MESSAGE_TYPE_CHASE 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 5.6.2 Returned Parameters LUA always returns the following parameter: lua_flag2.async This flag is set to 1 if the verb completed asynchronously, or 0 (zero) if the verb completed synchronously.
SLI Verbs SLI_SEND lua_prim_rc LUA_STATUS lua_sec_rc LUA_READY The SLI session is now ready to process additional commands. This status is used after a previous LUA_NOT_READY status was reported, or after an SLI_CLOSE verb completed with lua_prim_rc set to LUA_CANCELLED and lua_sec_rc set to RECEIVED_UNBIND_HOLD or RECEIVED_UNBIND_NORMAL. LUA_NOT_READY The SLI session has been temporarily suspended for one of the following reasons: • A CLEAR command was received.
SLI Verbs SLI_SEND lua_sec_rc Possible values are: LUA_BAD_DATA_PTR The lua_data_ptr parameter contained a value that was not valid. LUA_BAD_SESSION_ID The lua_sid parameter did not match the session ID of any active LUA LU session. LUA_INVALID_FLOW More than one of the lua_flag1 flow flags was set to 1. One and only one of these flags must be set to 1, to indicate which session flow the data is to be sent on. The lua_flag1.
SLI Verbs SLI_SEND An SLI_SEND was already outstanding for the session flow specified on this verb (the session flow is specified by setting one of the lua_flag1 flow flags to 1). Only one SLI_SEND at a time can be outstanding on each session flow.
SLI Verbs SLI_SEND A required SNAplus2 software component (such as the node) has terminated or has been stopped. Contact your System Administrator if necessary. lua_prim_rc LUA_COMM_SUBSYSTEM_NOT_LOADED The node was either not started or not configured properly for LUA applications. Check the SNAplus2 LUA configuration parameters and start the node before running your application. lua_prim_rc LUA_SESSION_FAILURE The LUA session has failed. To restart it, the application can reissue SLI_OPEN.
SLI Verbs SLI_SEND While an existing SLI_SEND is pending, you can issue a second SLI_SEND only if it specifies a different session flow from the pending SLI_SEND; that is, you cannot have more than one SLI_SEND outstanding for the same session flow. You cannot have more than two SLI_SENDs outstanding in total. The SLI_SEND verb can be issued on the SSCP normal flow at any time after a successful SLI_OPEN verb that specifies primary-initiated session initiation with SSCP access.
SLI Verbs SLI_BIND_ROUTINE 5.7 SLI_BIND_ROUTINE This verb is sent from LUA to the application (using the BIND extension routine entry point supplied by the application on the SLI_OPEN verb), and not from the application to LUA. The SLI_BIND_ROUTINE verb passes a BIND request from the host to the LUA application. The application can accept the BIND as it is, modify it in an attempt to negotiate the BIND parameters, or reject it with an appropriate SNA sense code. 5.7.
SLI Verbs SLI_SDT_ROUTINE A pointer to the buffer containing the supplied BIND RU. If the application is accepting the BIND as is, it must not modify the contents of the buffer; if it is attempting to negotiate one or more parameters in the BIND, it must modify the data to set the appropriate parameters to its preferred values.
SLI Verbs SLI_SDT_ROUTINE lua_sid The session ID of the session. lua_data_length The length of the supplied SDT RU. lua_data_ptr A pointer to the buffer containing the supplied SDT RU. lua_th The TH parameters from the SDT. lua_rh The RH parameters from the SDT. 5.8.2 Returned Parameters The parameters returned by the application depend on whether the verb completed successfully; see the following sections.
SLI Verbs SLI_STSN_ROUTINE 5.9 SLI_STSN_ROUTINE This verb is sent from LUA to the application (using the STSN extension routine entry point supplied by the application on the SLI_OPEN verb), and not from the application to LUA. The SLI_STSN_ROUTINE verb passes an STSN request from the host to the LUA application. The application can respond with an STSN response, or reject it with an appropriate SNA sense code. 5.9.
SLI Verbs SLI_STSN_ROUTINE Unsuccessful Execution: STSN Rejected If the application decides to reject the STSN, it returns the following parameters: lua_prim_rc LUA_NEGATIVE_RSP lua_data_length The length of the returned SNA sense code (in the lua_data_ptr parameter). lua_data_ptr A pointer to the buffer containing the SNA sense code associated with the application’s reason for rejecting the STSN. 5.9.
Sample LUA Application Processing Overview 6 Sample LUA Application This chapter describes the SNAplus2 sample LUA program /opt/sna/samples/lsample.c, written for the HP-UX operating system, which illustrates the use of LUA RUI verbs. The following information is provided: • Processing overview of the application • Instructions for compiling, linking, and running the application 6.1 Processing Overview The application is a very simple 3270 emulation program.
Sample LUA Application Testing the Application Figure 6–1 Program Flow for the Sample LUA Application Initialization Issue_read Control returns to application Read data from keyboard Issue_verb Callback routine read_done Response required? No Yes other_done Issue_rsp rsp_done 6.2 Testing the Application After examining the source code for the sample application, you may want to test it. The following steps are required: 1.
Sample LUA Application Testing the Application 6.2.1 Host Requirements To run the sample application, you will need an LU on the host computer. Because the sample application is emulating a 3270 display terminal, the LU must be configured at the host as a 3270 display LU (LU type 2) such as 3278 or 3279. The LU number assigned at the host must be used when configuring the LU on SNAplus2. 6.2.2 Configuration for the Sample Application SNAplus2 must be configured to include the required LU.
Sample LUA Application Testing the Application lsample puname lunumber In this example, luname is the name of the LU you configured for this application (or the name of the LU pool or any LU within it). In this example, puname is the name of the PU that owns the required LU, and lunumber is the LU number (specified as a decimal number). The application will display the message LU active when it has successfully established a session to the host. 4.
Appendix AReturn Code Values AppendixA Return Code Values This appendix lists all the possible return codes in the LUA interface in numerical order. The values are defined in the LUA header file lua_c.h (for HP-UX) or winlua.h (for Windows). You can use this appendix as a reference to check the meaning of a return code received by your application. A.1 Primary Return Codes The following primary return codes are used in LUA applications.
Appendix AReturn Code Values LUA_NO_SLI_SESSION LUA_SESSION_ALREADY_OPEN LUA_INVALID_OPEN_INIT_TYPE LUA_INVALID_OPEN_DATA LUA_UNEXPECTED_SNA_SEQUENCE LUA_NEG_RSP_FROM_BIND_ROUTINE LUA_NEG_RSP_FROM_CRV_ROUTINE LUA_NEG_RSP_FROM_STSN_ROUTINE LUA_CRV_ROUTINE_REQUIRED LUA_STSN_ROUTINE_REQUIRED LUA_INVALID_OPEN_ROUTINE_TYPE LUA_MAX_NUMBER_OF_SENDS LUA_SEND_ON_FLOW_PENDING LUA_INVALID_MESSAGE_TYPE LUA_RECEIVE_ON_FLOW_PENDING LUA_DATA_LENGTH_ERROR LUA_CLOSE_PENDING LUA_NEGATIVE_RSP_CHASE LUA_NEGATIVE_RSP_SHUTC LUA
Appendix AReturn Code Values LUA_LU_INOPERATIVE 0xFF000000 The following secondary return codes are SNA sense codes. They are listed both in the standard byte ordering used by LUA and in the byte ordering used for SNA sense codes in SNA reference manuals.
Appendix AReturn Code Values LUA_INVALID_PARAMETER LUA_CRYPTOGRAPHY_INOPERATIVE LUA_REQ_RESOURCES_NOT_AVAIL LUA_SSCP_LU_SESSION_NOT_ACTIVE LUA_SYNC_EVENT_RESPONSE LUA_SESSION_SERVICE_PATH_ERROR LUA_NEGOTIABLE_BIND_ERROR LUA_REC_CORR_TABLE_FULL LUA_NON_UNIQ_ID LUA_INV_NAU_ADDR LUA_BIND_FM_PROFILE_ERROR LUA_SSCP_PLU_SESS_NOT_ACTIVE LUA_SEND_CORR_TABLE_FULL LUA_NON_UNIQ_NAU_AD LUA_INV_ADPT_NUM LUA_BIND_TS_PROFILE_ERROR LUA_SSCP_SLU_SESS_INACT LUA_SLU_SESSION_LIMIT_EXCEEDED LUA_BIND_LU_TYPE_ERROR LUA_HDX_BRACK
Index A ACTLU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 ASCII to EBCDIC translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 asynchronous verb completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19, 26 B BIND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 BIND parameters, negotiating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44, 45 C callback routine . . . . . . . . .
RUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LUA_VERB_RECORD data structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 18 54 M manual set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . multiple processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 50 N normal flow . . . . . . . . . . . . . . . . . . . . .
supplied parameters . . . usage and restrictions . . RUI_TERM interaction with other verbs returned parameters . . . supplied parameters . . . RUI_WRITE interaction with other verbs returned parameters . . . supplied parameters . . . usage and restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 94 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SLI_SDT_ROUTINE interaction with other verbs . . . . . . . . . returned parameters . . . . . . . . . . . . supplied parameters . . . . . . . . . . . . usage and restrictions . . . . . . . . . . . SLI_SEND interaction with other verbs . . . . . . . . . returned parameters . . . . . . . . . . . . supplied parameters . . . . . . . . . . . . usage and restrictions . . . . . . . . . . . SLI_STSN_ROUTINE interaction with other verbs . . . . . . . . . returned parameters . . . . . . . . . . . .
