|
|
|
|
This chapter contains the following information:
Details of the LUA verb control block structure for all LUA verbs
A description of each LUA verb
The following information is provided for each LUA 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.
Symbolic constants are defined in the header files /usr/include/sna/lua_c.h and /usr/include/sna/values_c.h (Solaris operating system) or sdk/winlua.h (Windows operating system)for many parameter values. For portability, use the symbolic constant and not the numeric value when setting values for supplied parameters, or when testing values of returned parameters. The file values_c.h also includes definitions of parameter types such as AP_UINT16 that are used in the LUA VCBs.
Parameters marked as reserved
should always be set to
0 (zero).
The verb control block consists of two parts:
Specific data structure, used only for the RUI_BID verb and (in the Solaris environment) for the extended version of the RUI_INIT verb.
The definition of some parts of the VCB structure, in particular the ordering of bit fields, varies between different operating systems. For clarity, only one version of the ordering is shown here, although both versions are defined in the header file. When setting or testing values in bit fields, the application should access individual bits by name, to avoid dependencies on the bit ordering, rather than using bitwise AND or OR operations on complete bytes.
To allow for these differences, the LUA header file contains the following information:
A
The type definition for bit fields in the LUA data structures. This definition ensures that the data structures are stored in the correct format. The definition depends on the setting of PUCHARQD, which is in the file /usr/include/sna/svconfig.h.
The LUA VCB contains many parameters marked as reserved
;
some of these are used internally by the SNAP-IX 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. This
ensures that SNAP-IX will not misinterpret any of its internally-used parameters,
and also that your application will continue to work with future SNAP-IX
versions in which these parameters may be used to provide new functions.
To set the VCB contents to zero, use memset:
memset(vcb, 0, sizeof(vcb));
typedef struct
{
struct LUA_COMMON common;
struct LUA_SPECIFIC specific;
} LUA_VERB_RECORD;
struct LUA_COMMON
{
AP_UINT16 lua_verb; /* Verb Code */
AP_UINT16 lua_verb_length; /* Length of Verb Record */
AP_UINT16 lua_prim_rc; /* Primary Return Code */
AP_UINT32 lua_sec_rc; /* Secondary Return Code */
AP_UINT16 lua_opcode; /* Verb Operation Code */
AP_UINT32 lua_correlator; /* User Correlation Field */
unsigned char lua_luname[8]; /* Local LU Name */
AP_UINT16 lua_extension_list_offset; /* Offset of DLL Extention List*/
AP_UINT16 lua_cobol_offset; /* Offset of Cobol Extension */
AP_UINT32 lua_sid; /* Session ID */
AP_UINT16 lua_max_length; /* Receive Buffer Length */
AP_UINT16 lua_data_length; /* Data Length */
char * lua_data_ptr; /* Data Buffer Pointer */
unsigned long lua_post_handle; /* Posting handle */
struct LUA_TH { /* LUA TH Fields */
BIT_FIELD_TYPE flags_fid : 4; /* Format Identification Type 2 */
BIT_FIELD_TYPE flags_mpf : 2; /* Segmenting Mapping Field */
BIT_FIELD_TYPE flags_odai : 1; /* OAF-DAF Assignor Indicator */
BIT_FIELD_TYPE flags_efi : 1; /* Expedited Flow Indicator */
BIT_FIELD_TYPE : 8; /* Reserved Field */
unsigned char daf; /* Destination Address Field */
unsigned char oaf; /* Originating Address Field */
unsigned char snf[2]; /* Sequence Number Field */
} lua_th;
struct LUA_RH { /* LUA RH Fields */
BIT_FIELD_TYPE rri : 1; /* Request-Response Indicator */
BIT_FIELD_TYPE ruc : 2; /* RU Category */
BIT_FIELD_TYPE : 1; /* Reserved Field */
BIT_FIELD_TYPE fi : 1; /* Format Indicator */
BIT_FIELD_TYPE sdi : 1; /* Sense Data Included Ind */
BIT_FIELD_TYPE bci : 1; /* Begin Chain Indicator */
BIT_FIELD_TYPE eci : 1; /* End Chain Indicator */
BIT_FIELD_TYPE dr1i : 1; /* DR 1 Indicator */
BIT_FIELD_TYPE : 1; /* Reserved Field */
BIT_FIELD_TYPE dr2i : 1; /* DR 2 Indicator */
BIT_FIELD_TYPE ri : 1; /* Response Indicator */
BIT_FIELD_TYPE : 2; /* Reserved Field */
BIT_FIELD_TYPE qri : 1; /* Queued Response Indicator */
BIT_FIELD_TYPE pi : 1; /* Pacing Indicator */
BIT_FIELD_TYPE bbi : 1; /* Begin Bracket Indicator */
BIT_FIELD_TYPE ebi : 1; /* End Bracket Indicator */
BIT_FIELD_TYPE cdi : 1; /* Change Direction Indicator */
BIT_FIELD_TYPE : 1; /* Reserved Field */
BIT_FIELD_TYPE csi : 1; /* Code Selection Indicator */
BIT_FIELD_TYPE edi : 1; /* Enciphered Data Indicator */
BIT_FIELD_TYPE pdi : 1; /* Padded Data Indicator */
BIT_FIELD_TYPE : 1; /* Reserved Field */
} lua_rh;
struct LUA_FLAG1 { /* LUA_FLAG1 */
BIT_FIELD_TYPE bid_enable : 1; /* Bid Enabled Indicator */
BIT_FIELD_TYPE reserv1 : 1; /* reserved */
BIT_FIELD_TYPE close_abend : 1; /* Close Immediate Flag */
BIT_FIELD_TYPE nowait : 1; /* Don't Wait for Data Flag */
BIT_FIELD_TYPE sscp_exp : 1; /* SSCP expedited flow */
BIT_FIELD_TYPE sscp_norm : 1; /* SSCP normal flow */
BIT_FIELD_TYPE lu_exp : 1; /* LU expedited flow */
BIT_FIELD_TYPE lu_norm : 1; /* lu normal flow */
} lua_flag1;
unsigned char lua_message_type; /* sna message command type */
struct LUA_FLAG2 { /* LUA_FLAG2 */
BIT_FIELD_TYPE bid_enable : 1; /* Bid Enabled Indicator */
BIT_FIELD_TYPE async : 1; /* flags asynchronous verb */
completion */
BIT_FIELD_TYPE : 2; /* reserved */
BIT_FIELD_TYPE sscp_exp : 1; /* SSCP expedited flow */
BIT_FIELD_TYPE sscp_norm : 1; /* SSCP normal flow */
BIT_FIELD_TYPE lu_exp : 1; /* LU expedited flow */
BIT_FIELD_TYPE lu_norm : 1; /* lu normal flow */
} lua_flag2;
unsigned char lua_resv56[7]; /* Reserved Field */ unsigned char lua_encr_decr_option; /* Cryptography Option */ } ;
struct LUA_COMMON
{
unsigned short lua_verb; /* Verb Code */
unsigned short lua_verb_length; /* Length of Verb Record */
unsigned short lua_prim_rc; /* Primary Return Code */
unsigned long lua_sec_rc; /* Secondary Return Code */
unsigned short lua_opcode; /* Verb Operation Code */
unsigned long lua_correlator; /* User Correlation Field */
unsigned char lua_luname[8]; /* Local LU Name */
unsigned short lua_extension_list_offset; /* Offset of DLL Extention List*/
unsigned short lua_cobol_offset; /* Offset of Cobol Extension */
unsigned long lua_sid; /* Session ID */
unsigned short lua_max_length; /* Receive Buffer Length */
unsigned short lua_data_length; /* Data Length */
char far *lua_data_ptr; /* Data Buffer Pointer */
unsigned long lua_post_handle; /* Posting handle */
struct LUA_TH { /* LUA TH Fields */
unsigned char flags_fid : 4; /* Format Identification Type 2 */
unsigned char flags_mpf : 2; /* Segmenting Mapping Field */
unsigned char flags_odai : 1; /* OAF-DAF Assignor Indicator */
unsigned char flags_efi : 1; /* Expedited Flow Indicator */
unsigned char : 8; /* Reserved Field */
unsigned char daf; /* Destination Address Field */
unsigned char oaf; /* Originating Address Field */
unsigned char snf[2]; /* Sequence Number Field */
} lua_th;
struct LUA_RH { /* LUA RH Fields */
unsigned char rri : 1; /* Request-Response Indicator */
unsigned char ruc : 2; /* RU Category */
unsigned char : 1; /* Reserved Field */
unsigned char fi : 1; /* Format Indicator */
unsigned char sdi : 1; /* Sense Data Included Ind */
unsigned char bci : 1; /* Begin Chain Indicator */
unsigned char eci : 1; /* End Chain Indicator */
unsigned char dr1i : 1; /* DR 1 Indicator */
unsigned char : 1; /* Reserved Field */
unsigned char dr2i : 1; /* DR 2 Indicator */
unsigned char ri : 1; /* Response Indicator */
unsigned char : 2; /* Reserved Field */
unsigned char qri : 1; /* Queued Response Indicator */
unsigned char pi : 1; /* Pacing Indicator */
unsigned char bbi : 1; /* Begin Bracket Indicator */
unsigned char ebi : 1; /* End Bracket Indicator */
unsigned char cdi : 1; /* Change Direction Indicator */
unsigned char : 1; /* Reserved Field */
unsigned char csi : 1; /* Code Selection Indicator */
unsigned char edi : 1; /* Enciphered Data Indicator */
unsigned char pdi : 1; /* Padded Data Indicator */
unsigned char : 1; /* Reserved Field */
} lua_rh;
struct LUA_FLAG1 { /* LUA_FLAG1 */
unsigned char bid_enable : 1; /* Bid Enabled Indicator */
unsigned char reserv1 : 1; /* reserved */
unsigned char close_abend : 1; /* Close Immediate Flag */
unsigned char nowait : 1; /* Don't Wait for Data Flag */
unsigned char sscp_exp : 1; /* SSCP expedited flow */
unsigned char sscp_norm : 1; /* SSCP normal flow */
unsigned char lu_exp : 1; /* LU expedited flow */
unsigned char lu_norm : 1; /* lu normal flow */
} lua_flag1;
unsigned char lua_message_type; /* sna message command type */
struct LUA_FLAG2 { /* LUA_FLAG2 */
unsigned char bid_enable : 1; /* Bid Enabled Indicator */
unsigned char async : 1; /* flags asynchronous verb */
completion */
unsigned char : 2; /* reserved */
unsigned char sscp_exp : 1; /* SSCP expedited flow */
unsigned char sscp_norm : 1; /* SSCP normal flow */
unsigned char lu_exp : 1; /* LU expedited flow */
unsigned char lu_norm : 1; /* lu normal flow */
} lua_flag2;
unsigned char lua_resv56[7]; /* Reserved Field */ unsigned char lua_encr_decr_option; /* Cryptography Option */ } ;
The following list explains the fields in these data structures.
Identifies this as an LUA verb: always set to LUA_VERB_RUI.
Length of the verb control block (VCB).
Primary return code set by LUA.
Secondary return code set by LUA.
Verb operation code that identifies the LUA verb being issued.
A four-byte correlator that you can use to correlate this verb with other processing in your application. LUA does not use this parameter.
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 RUI_INIT.
This field is reserved.
This field is reserved.
The session ID of the LUA session on which this verb is issued.
The length of the buffer supplied to RUI_READ to receive data, or the total length of a waiting RU returned to RUI_BID.
The length of the data to be sent, or the actual length of data received.
A pointer to the data to be sent, or the data buffer to receive data.
A pointer to a callback routine that LUA will call to indicate completion if the verb completes asynchronously.
If the VCB is used in a RUI function call, set this field to an event handle. If the VCB is used in a WinRUI function call, this field is reserved.
A data structure containing the TH (transmission header) of the message sent or received, as follows:
Format Identification type 2: 4 bits
Segmenting mapping field: 2 bits
Origin Address Field-Destination Address Field (OAF-DAF) Assignor Indicator
Expedited Flow Indicator
DAF (Destination address field)
OAF (Originating address field)
Sequence Number Field
A data structure containing the RH (request/response header) of the message sent or received, as follows:
Request-Response Indicator
RU category: 2 bits
Format Indicator
Sense Data Included Indicator
Begin Chain Indicator
End Chain Indicator
Definite Response 1 Indicator
Definite Response 2 Indicator
Exception Response Indicator (for a request), or Response Type Indicator (for a response)
Queued Response Indicator
Pacing Indicator
Begin Bracket Indicator
End Bracket Indicator
Change Direction Indicator
Code Selection Indicator
Enciphered Data Indicator
Padded Data Indicator
A data structure containing flags for messages supplied by the application, as follows:
Bid Enable Indicator
Close Immediate Indicator
No Wait For Data flag
SSCP expedited flow
SSCP normal flow
LU expedited flow
LU normal flow
The type of SNA message received by an RUI_READ verb (or indicated to an RUI_BID verb)
A data structure containing flags for messages returned by LUA, as follows:
Bid Enabled Indicator
Asynchronous verb completion flag
SSCP expedited flow
SSCP normal flow
LU expedited flow
LU normal flow
Cryptography option
The following data structure is included for the RUI_BID verb, and for the extended form of the RUI_INIT verb:
union LUA_SPECIFIC
{
struct SLI_OPEN open;
unsigned char lua_sequence_number[2];
unsigned char lua_peek_data[12];
struct RUI_INIT init;
} ;
struct RUI_INIT
{
unsigned char rui_init_format;
unsigned char lua_puname[8];
unsigned char lua_lunumber;
};
The SLI_OPEN structure is defined in the LUA header file. This structure, and the lua_sequence_number parameter, are included in the definition of the LUA_SPECIFIC union for compatibility with other LUA implementations, but are not used by SNAP-IX LUA.
For RUI_BID, this data structure contains the following field:
Up to 12 bytes of the data waiting to be read.
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 RUI_INIT.
Reserved-this parameter must be set to 0 (zero).
The name of the local PU that owns the LU to be used for this session. The PU name must be specified in the definition of an LS or of an internal PU in the SNAP-IX configuration.
The LU number of the LU to be used for this session. This must match the LU number of a type 0-3 LU that is configured for the PU name specified by lua_puname.
The extended form of the RUI_INIT verb does not apply to Windows. The RUI_INIT data structure is not used.
|
|
|
 |
|