Chapter 1. Programming with API

Chapter 1. Programming with API
Prev		Next

This chapter contains information about writing transaction programs using the verb library functions. It also has information to help you diagnose application errors. The material in this chapter provides an introduction and overview of the verbs. Appendix A lists the major and minor codes returned by the verb functions. Appendix B, “API Verb Catalog,” lists all of the API verbs in alphabetical order, giving their full names and verb types.

The IRIS SNA SERVER incorporates verbs that are of interest to the programmer using IRIS SNA LU 6.2. The relevant server verbs are noted first in this chapter. The LU 6.2 Application Program Interface (API) overview and verb catalogs follow. A description of the LU 6.2 security features and a diagnostics guide for applications complete this chapter. See Appendix C, “Man Pages,” for a more complete description of the LU 6.2 verbs.

SNA SERVER Verb Categories

This section describes the functions provided by the IRIS SNA SERVER that are of interest to the programmer using the LU 6.2 Application Program Interface (API) verbs. There are three general categories of IRIS SNA SERVER API verbs used with the IRIS SNA LU 6.2 API verbs:

Implementation-specific verbs
Configuration verbs
Node operator verbs

Note: Details about the configuration and node operator verbs are contained in the IRIS SNA SERVER Programming Guide. Because the implementation-specific verbs listed below are used by all applications, man pages for them are included with this guide's man pages for convenience.

Implementation-specific Verbs

Although the implementation-specific verbs, also called the transaction program connection verbs, are not part of the IBM SNA, they are required for the IRIS SNA SERVER.

Before a program can issue any conversation, control-operator, or node-operator functions, it must establish a connection with the IRIS SNA SERVER. This is called attaching. Conversation verbs and control operator verbs attach by specifying the name of the configuration and the local LU that the transaction program wants to use.

The names specified in the attach request are called the context of the attach. Since a program can issue verbs to more than one configuration or LU, the program can issue multiple attach requests. Each of these attaches creates a new logical instance of the program. The setctx verb switches from one instance to the other before issuing verbs to the different LUs.

Because transaction program connection verbs establish or break the connection between the transaction program and the IRIS SNA SERVER, they are the first and last verbs the program issues. The verbs listed in Table 1-1 attach and detach the application to the IRIS SNA SERVER. All applications must use the attach and detach verbs. The setctx verb is optional.

Table 1-1. Transaction Program Connection Verbs

Verb	Function
attach	Initiates communication between the local program and the IRIS SNA SERVER
detach	Detaches the current context from the IRIS SNA SERVER.
rattach	Initiates communication between a remotely invoked transaction program and the IRIS SNA Scheduler.
setctx	Establishes the current context under which subsequent verbs are issued.

Configuration Verbs

Configuration verbs define and display the resources of the node and logical unit. The following IRIS SNA SERVER verbs are useful to the programmer using the LU 6.2 API verbs and are divided into two groups: define verbs and display verbs. Table 1-2 lists the configuration define verbs.

Table 1-2. Configuration Define Verbs

Verb	Full Name
dfncp	Define Control Point

dfnline	Define Line

dfnllu	Define Local LU

dfnmode	Define Mode

dfnnode	Define Node

dfnrlu	Define Remote LU

dfnsta	Define Station

dfntp	Define Transaction Program

Table 1-3 lists the configuration display verbs.

Table 1-3. Configuration Display Verbs

Verb	Full Name
dspcp	Display Control Point

dspline	Display Line

dspllu	Display Local LU

dspmode	Display Mode

dspnode	Display Node

dsprlu	Display Remote LU

dspses	Display Session

dspsta	Display Station

dsptp	Display Transaction Program

Node Operator Verbs

The IRIS SNA SERVER node operator verbs (Table 1-4) control the links and activate, deactivate, and supervise the configured local resources of the server.

Table 1-4. Node Operator Verbs

Verb	Full Name
actline	Activate Line

actlu	Activate Logical Unit

actpu	Activate Physical Unit

actsta	Activate Station

chgmsgq	Change Message Queue

dctline	Deactivate Line

dctlu	Deactivate Logical Unit

dctpu	Deactivate Physical Unit

dctsta	Deactivate Station

dspmsgq	Display Message Queue

rtvnmsg	Retrieve Node Message

API Overview

Advanced Program-to-Program Communications (APPC) provides high-level access to data communications facilities. It defines a machine-independent programmatic interface that offers a standard solution to the problems of data communications. This high-level approach frees the programmer to spend time designing the features of distributed applications rather than laboring over the details of communications protocols.

An APPC application is a couplet of programs that exchange both data and control information using the LU 6.2 programmatic interface. The second program in the couplet is started at the remote site at the request of the first. IRIS SNA LU 6.2 enables the two programs to exchange information. This exchange, called a conversation, is transparent to low-level communications. The programs conduct the conversation by issuing verbs, which are high-level procedural calls that perform the tasks of starting the conversation (and the partner program at the remote site), sending and receiving data, controlling error handling, and stopping the exchange.

In the IRIS implementation, these verbs take the form of C-language function calls. The Application Program Interface (API) is a library containing verb functions and header files defining the structures and variables used by applications that call the verb functions. For more LU 6.2 protocol information, consult the IBM Transaction Programmer's Reference Manual, which is referred to in this guide as the TPRM.

IRIS SNA LU 6.2 Verb Categories

Verbs are divided into categories according to their function. These categories, in turn, are divided into groups. Two categories of LU 6.2 verbs exist: conversation verbs and control operator verbs. A description of the groups that comprise each category and their respective functions follows. See the man pages in Appendix C for individual verb details.

Conversation Verbs

Application programs use conversation verbs to exchange data. These verbs are divided into three groups:

Mapped conversation verbs
Basic conversation verbs
Type-independent verbs

Mapped and basic verbs conduct peer-to-peer conversations. They differ in the amount of formatting the application program must do. Type-independent verbs are used on either mapped or basic conversations.

Control Operator Verbs

Control operator verbs define and control the resources of the logical unit. They are divided into two groups: change number of sessions (CNOS) verbs and session control verbs.

Both CNOS and session control verbs control the sessions between the local LU and the remote LU.

Verb Library

Verb functions and functions called by the verb are archived in
/usr/lib/liblu62.a. Programs that use verb functions are linked against this library. For most compilers, use the -l option. For example:

cc sample.c-llu62.a

See your compiler documentation for instructions on linking with IRIS libraries.

Header Files

The structures and variables used in IRIS SNA LU 6.2 verbs are defined in header files located in /usr/include/sna. These header files are available:

basic.h		Contains definitions of the verb parameter structures for the basic conversation verbs
mapped.h		Contains definitions of the verb parameter structures for the mapped conversation verbs
cntrl.h		Contains definitions of the verb parameter structures for the control operator verbs
global.h		Contains definitions of the global variables used by all of the verb types
imp.h		Contains definitions of the verb parameter structures for the implementation-specific verbs
mc_mcb.h		Contains definition of the mapping control block structure
		In addition to these header files, /usr/include/sna has a number of files of type definitions and constant values used by the LU 6.2 verbs. These files need not be explicitly included but can be examined for their contents.
ddhvtyp.h		Type definitions for the LU 6.2 verbs.
ddhverr.h		Constants for major and minor return codes.
ddhvicn.h		Constants used for verb parameter values.
ddhviex.h		External variable declarations.

Data Type Definitions

The verb parameter structures use data types defined in the header file ddhvtyp.h. These data types are:

typedef		unsigned char hex (Used for strings or bytes where all bits are significant)
typedef		unsigned short shex (Used for values that must be two bytes long)
typedef		unsigned long lhex (Used for values that must be four bytes long)

Data Structures

Each member (referred to as both parameter and field) of the data structure is described as being Supplied, Returned, or Supplied/Returned.

Supplied parameters are set by the application program.
Returned parameters are set automatically by the successful operation of the verb.
Supplied/Returned parameters are set by the application program when the verb is issued, but their value can change after the successful operation of the verb.

Initialization of every member of the structure is the responsibility of the application. Pointers not set to a specific address are set to null.

Note: For the character-string parameters in the Display and Get Attribute verbs, Returned and Supplied have a slightly different meaning. These verbs require the application program to allocate space for returned names and strings. If the pointer is nulled, the name is not returned. Thus, even though the value in a name field is returned by the verb, the pointer must still be supplied by the application program. If a name parameter is listed as Supplied/Returned in a display verb, a different name can be returned in the same space after the successful completion of the verb.

Supplied parameters are specified as Required, Conditional, or Optional.

Required parameters must be set by the application program.
Conditional parameters may have a value required, depending on the setting of another parameter.
Optional parameters need not be set.

Global Variables

Information on the state of the conversation and feedback on the execution of verb calls is returned in three global variables. These variables are defined in the header file global.h. This file must be included in each program that uses APPC functions. Routines that query the values of these variables should refer to them as external variables.

Return Code: snamaj and snamin

After executing a verb function, return information is placed in global variables snamaj and snamin. The values carried here correspond to the verb return-code parameters defined in the TPRM. If the function completes normally (return code of OK), the function returns 0 and the major and minor codes also are 0.

A return code set in the major or minor fields returns the verb function -1.
In general, the major code is sufficient for controlling program logic.

Table 1-5 describes the major codes used. See Appendix A for a complete list of the major and minor return codes.

Table 1-5. Major Return Codes

Major Code	Description
S2_OK (0)	Function completed successfully.

S2_UNSUC (2)	Function completed unsuccessfully.
	(Set when a function, such as “Receive
	Immediate” or “Test,” completes normally but does not return data.)

S2_USAGE (1)	Function aborted, usage error.
	(The function was not performed because a parameter was in error or requested an unsupported function. The majority of the minor codes provided specific information on usage errors.)

S2_STATE (3)	Function aborted, state error.
	(The function was not performed because it is not allowed in the current conversation state.)
S2_ALCER (5)	Allocation error.
	(The program could not allocate a conversation for the reason specified in the minor code. The conversation is in deallocated state when an allocation errors occurs.)

S2_PGMER (7)	Program Error. (The partner program issued an error indication. A send state conversation is changed to a receive state.)

S2_DEALC (9)	Deallocation indication.
	(The conversation has been deallocated, normally or abnormally, for the reason specified in the minor code. The conversation is in deallocated state.)

S2_COERR (10)	Control-operator function error.
	(A control-operator function has ended abnormally. Since the control operator verb may not have been using a conversation, the conversation state does not apply.)

S2_NPERR (11)	Operation function error.
	(An operation function was not accepted. Since operation verbs do not use conversations, the conversation state does not apply.)

Conversation State: snastat

After the execution of any of the conversation verb functions, the conversation state is set in the variable snastat. Table 1-6 describes the values. The states are referred to by their constant identifier throughout the conversation verb documentation.

Table 1-6. Conversation State Constant Identifiers

Constant Identifier	Description
S2_NONE (0)	No state.
	(The program has not allocated a conversation.)

S2_RESET (1)	Reset state.
	(The conversation has not been fully allocated.)
S2_SEND (2)	Send state.
	(The conversation can send data and confirmation requests.)

S2_RECV (3)	Receive state.
	(The conversation can receive information from the partner program.)

S2_CNFRM (4)	Confirm state.
	(The conversation can respond to a confirmation request from the partner program.)

S2_CSEND (5)	Confirm send state.
	(The partner has issued a prepare-to-receive of type SYNC. When the program issues a confirm, it is in send state.)

S2_CDELC (6)	Confirm deallocate state.
	(The partner has issued a deallocate of type SYNC or type CONFIRM. When the program issues a confirm, it is in deallocate state.)

S2_DLCED (7)	Deallocate state.
	(The partner has ended the conversation. The program must deallocate the conversation locally.)

Conversation Verbs

Full connectivity among programs requires that all transaction programs interpret the records they transfer in the same way. Data is transferred between SNA components or sublayers via message units (MUs), which are any bit-strings that contain an SNA-defined format. The type of format depends on the type of conversation.

The basic conversation protocol boundary, usually used by service transaction programs, is implemented in a low-level language, such as assembler. Basic conversations format MUs into logical records, which consist of a two-byte length prefix (LL) followed by data. A transaction program sending data over a basic conversation must include the LL field in its data, and complete the formatting of the logical record it is sending before leaving the send state.

The mapped conversation protocol boundary, usually used by application transaction programs, is implemented in a high-level language, such as C. Mapped conversations transform MUs into a standard format called a general data stream, or GDS. The basic structural unit in the GDS is a two-byte length prefix (LL), a two-byte GDS identifier (ID), and a variable length data field. A transaction program sending data over a mapped conversation is responsible for providing only the data and a map name. The receiving LU automatically converts the data into its original form.

Figure 1-1 illustrates the significant difference between basic and mapped conversation formats.

Figure 1-1. Basic and Mapped Conversation Formats

Because the LL prefix of a logical record has the same format as the LL field in a GDS variable segment, a GDS variable segment is also a logical record. Application transaction programs that use basic conversations do not need to supply ID fields. If they are supplied, the basic conversation treats everything following the LL prefix of the logical record as user data.

Conversation verbs are divided into three categories: mapped, basic, and type independent. Mapped verbs communicate between user-written transaction programs. Basic verbs are normally used only by service programs, such as the Change Number of Sessions program. Type-independent verbs provide functions that span both mapped and basic verbs.

Note: Since a transaction program that uses basic verbs is responsible for all data formatting, it can also use basic verbs to format mapped conversation flows. This feature is useful in implementations that provide only basic-verb support.

Mapped Conversation Verbs

All mapped conversation verb functions and functions called by a mapped conversation verb are in /usr/lib/liblu62.a. Data structures for the mapped conversation verbs are in /usr/include/sna/mapped.h. The global variables are defined in the header file /usr/include/sna/global.h.

The mapped conversation verbs listed in Table 1-7 are supported.

Table 1-7. Mapped Conversation Verbs

Verb	Function
malcnv	Allocates a mapped conversation connecting the local
	transaction program to a remote transaction program.

mcnfrm	Sends a confirmation request to the remote transaction
	program and waits for a reply so that the two
	programs can synchronize their processing.

mcnfrmed	Sends a confirmation reply to the remote transaction
	program so that the two programs can synchronize
	their processing.

mdalcnv	Deallocates a mapped conversation resource from the
	transaction program.

mflush	Transmits all information that the LU has buffered.

mgetatr	Returns information pertaining to a mapped
	conversation.

mprprcv	Changes the mapped conversation from send state to
	receive state in preparation to receive data.

mpstrct	Requests posting of the specified mapped
	conversation when information is available for the
	program to receive.

mrcvim	Receives any information available from the specified
	mapped conversation, but does not wait for the
	information to arrive.

mrcvwt	Waits for information to arrive on the mapped
	conversation and then receives the information.
mrqssnd	Notifies the remote program that the local program is
	requesting to enter send state for the mapped conversation.

msnddta	Sends one logical record to the remote transaction program.

msnderr	Informs the remote transaction program that the local
	program has detected an application error.

mtestcv	Tests the mapped conversation to determine whether or not it has been posted.

Conversation States

Certain verbs are only issued in certain states. An application can be designed to use the state variable to determine which verb to issue. For example, the program may be designed with a receive loop that issues mrcvim while in S2_RECV state and a switch statement that issues msnddta, mdalcnv, or mcnfrm when the state changes from S2_RECV. (See the sample transaction programs in Chapter 2 for examples of the use of the state variable.)

Table 1-8 lists the states in which each mapped verb are issued.The states listed in the table heading are described in Section , “Global Variables.”

Table 1-8. Mapped Verb Conversation States and Verb Validity

	S2_	S2_	S2_	S2_	S2_	S2_	S2_
	REQUEST	SEND	ECV	CONFIRM	CSEND	SDELC	DLCED
malcnv	yes	no	no	no	no	no	no
mcnfrm	no	yes	no	no	no	no	no
mcnfrmed	no	no	no	yes	yes	yes	no
mdalcnv
Type:
flush	no	yes	no	no	no	no	no
sync	no	yes	no	no	no	no	no
abend	no	yes	yes	yes	yes	yes	no
local	no	no	no	no	no	no	yes
confirm	no	yes	no	no	no	no	no
mflush	no	yes	no	no	no	no	no
mgetatr	no	yes	yes	yes	yes	yes	yes
mprprcv	no	yes	no	no	no	no	no
mpstrct	no	no	yes	no	no	no	no
mrcvwt	no	yes	yes	no	no	no	no
mrcvim	no	no	yes	no	no	no	no
mrqssnd	no	no	yes	yes	no	no	no
msnddta	no	yes	no	no	no	no	no
msnderr	no	yes	yes	yes	yes	yes	no
mtestcv
Type:
posted	no	no	yes	no	no	no	no
rqssnd	no	no	yes	yes	no	no	no

Data Mapping

At its simplest level, the information sent between two transaction programs consists of a stream of data bytes formatted into logical records. At the logical-record level, however, the data may require further transformation before the transaction program can receive it. Map names provide this function. A map name is a non-null user-defined name that identifies the format of the logical record and describes the mapping performed before the data is sent in a manner transparent to the transaction program.

The map name specified by the local program and the map name received by the remote program can be different. For example, the local LU can translate a map name with a meaning known locally into a global map name known to the remote LU. The remote LU in turn can translate the received map name into one that is known locally to the remote transaction program.

Data mapping is optional on a mapped conversation. That is, the logical record can be sent without being mapped. A null map name specifies that no data mapping should be done. A null map name is never translated into a non-null map name, although a non-null map name may be translated into a null map name, which would disable mapping.

Mapper: The Mapping Utility Interface

When data mapping is specified, the programmer is responsible for supplying it. A defined interface exists between the LU Mapped-conversation Component (MC) and the user-supplied Mapping Utility (Mapper). The Mapper must adhere to this interface to ensure correct operation of the LU mapped-conversation component.

Under the LU 6.2 architecture, the Mapper is responsible for map-name transmission as well as data transformation. Under this implementation of data mapping, the Mapper handles only data transformation. The MC handles the transmission of map names between the local and remote LUs.

The function that performs mapping, mc_map, is defined in a man page. To use data mapping, an application programmer creates a function with the name mc_map and links it to the executable object.

Type-independent Conversation Verbs

The type-independent conversation verbs described in Table 1-9 are used on either mapped or basic conversations and are supported in IRIS SNA LU 6.2.

Table 1-9. Type-independent Conversation Verbs

Verb	Function
gtype	Returns the type of resource to which the specified resource ID is assigned.
waitcv	Waits for posting to occur on any basic or mapped conversation from among a list of conversations.

Conversation States

After the execution of any of the conversation verb functions, the conversation state is set in the variable snastat.

Table 1-10 lists the states in which each type-independent verb can be issued. (The states listed in the table header are defined in Section , “Global Variables.”)

Table 1-10. Conversation States ansd Verb Validity

	S2_ RESET	S2_ SEND	S2_ RECV	S2_ CNFRM	S2_ CSEND	S2_ CDELC	S2_ DLCED
gtype	no	yes	yes	yes	yes	yes	no
waitev	no	no	yes	no	no	no	no

S2_
RESET

S2_
SEND

S2_
RECV

S2_
CNFRM

S2_
CSEND

S2_
CDELC

S2_
DLCED

gtype

yes

waitev

yes

All type-independent conversation verb functions, and functions called by a type-independent conversation verb are in /usr/liblu62.a. The data structures for the type-independent verbs are in /usr/include/lu62/basic.h.

The global variables are defined in the header file global.h.

Basic Conversation Verbs

Basic conversation verbs can conduct basic or mapped conversations. The application is responsible for correctly formatting the data that is sent using basic verbs. That is, the data must be packed into logical records, including the GDS variables if a mapped conversation is being conducted. Basic verbs are intended for use by LU service programs, such as CNOS or Document Interchange Architecture (DIA). Mapped verbs also use basic verbs; the mapped verbs format the data and the verb request and then call the basic verb to perform the action.

The basic conversation verbs listed in Table 1-11 are supported.

Table 1-11. Basic Conversation Verbs

Verb	Function
alcnv	Allocates a conversation connecting the local transaction program to a remote transaction program.
cnfrm	Sends a confirmation request to the remote transaction program and waits for a reply, so that the two programs can synchronize their processing.
cnfrmed	Sends a confirmation reply to the remote transaction program, so that the two programs can synchronize their processing.
dalcnv	Deallocates a conversation resource from the ransaction program.
flush	Transmits all information that the LU has buffered.
getatr	Returns information pertaining to a conversation when information is available for the program to receive.
prprcv	Changes the conversation from send state to receive state in preparation to receive data.
pstrct	Requests posting of the specified conversation when information is available for the program to receive.
rcvim	Receives any information that is available from the specified conversation, but does not wait for the information to arrive.
rcvwt	Waits for information to arrive on the conversation and then receives the information.
rqssnd	Notifies the remote program that the local program is requesting to enter send state for the conversation.
snddta	Sends information to the remote transaction program.
snderr	Informs the remote transaction program that the local program has detected an application error.
testcv	Tests the conversation to determine whether it has been posted.

Conversation States

Some verbs are issued only in certain states (see Table 1-12). An application can use the state variable to determine which verb to issue. One example is a program designed with a receive loop that issues rcvim while in S2_RECV state and a switch statement that issues snddta, dalcnv, or cnfrm when the state changes from S2_RECV.

Table 1-12. Conversation States and Verb Validity

	S2_	S2_	S2_	S2_	S2_	S2_	S2_
	RESET	SEND	RECV	CONFIRM	CSEND	CDELC	DLCED
alcnv	yes	no	no	no	no	no	no
cnfrm	no	yes	no	no	no	no	no
cnfrmed	no	no	no	yes	yes	yes	no
dalcnv
Type:
flush	no	yes	no	no	no	no	no
sync	no	yes	no	no	no	no	no
abend	no	yes	yes	yes	yes	yes	no
local	no	no	no	no	no	no	yes
confirm	no	yes	no	no	no	no	no
flush	no	yes	yes	yes	yes	yes	yes
getatr	no	yes	yes	yes	yes	yes	yes
prprcv	no	yes	no	no	no	no	no
pstrct	no	no	yes	no	no	no	no
rcvwt	no	yes	yes	no	no	no	no
rcvim	no	no	yes	no	no	no	no
rqssnd	no	no	yes	yes	no	no	no
snddta	no	yes	no	no	no	no	no
snderr	no	yes	yes	yes	yes	yes	no
testcv
Type:
posted	no	no	yes	no	no	no	no
rqssnd	no	yes	yes	no	no	no	no

Control Operator Verbs

Control operator verbs, which define and control LUs, modes, and sessions, are divided into two categories: change number of session verbs and session control verbs.

CNOS verbs establish the number of sessions allowed between two LUs over a particular mode. Session control verbs activate and deactivate sessions after the session limits have been established.

The verb functions and functions called by the verb are archived in
/usr/lib/liblu62.a. Programs that use verb functions are linked with this library. The data structures for the CNOS and session control verbs are in
/usr/lib/cntrl.h. The global variables are defined in the header file global.h.

Note: Feedback on the execution of control operator verb calls is returned in two global variables: snamaj and snamin. The third global variable, snastat, is not used by the control operator verbs.

Change Number of Session Verbs

The CNOS verbs set the allowed number of sessions between the local LUs and the remote LUs. The limits are set for each mode defined between the LUs. When the node is first activated, the session limits on all modes is 0; that is, no sessions can be activated. Limits are raised by the initsl verb. If pre-bound sessions were defined for the mode, sessions can also be activated as a result of raising the limits. If not, sessions can be started using the session control verbs. Once limits have been raised initially, they can be changed by the chgsl verb. All session activity can be terminated by using the rstsl verb, which reduces the session limits to 0.

When parallel sessions are supported by the LUs (that is, the defined session limit can be greater than 1), the two LUs must agree on the number of sessions allowed. This agreement is negotiated between the LUs by an LU 6.2 conversation over a special mode. The mode, named SNASVCMG, is defined by default for all LUs that support parallel sessions. The session limit on this mode is always set to 2 so the LUs need not negotiate these limits. Nevertheless, these modes must be initialized by both LUs before any other mode can be initialized. The LU starts the negotiation when the operator issues initsl (initialize session limits), chgsl (change session limits), or
rstsl (reset session limits) for a parallel-session mode. The LU then allocates a conversation with the partner LU, requesting the CNOS model as its target program, and sends a defined message that contains the requested limits. The CNOS model (s2_cnos) issues the procsl verb to handle the target side of the negotiation. This verb determines the defined limits for the mode and returns a message containing limits that are the lesser of those defined for the mode or requested by the source. The target returns the limits which the mode will observe.

Note: When LUs try to initiate the CNOS exchange at the same time, the LU with the “greater” network name prevails.

When parallel sessions are not supported, the initsl verb is still issued, although no CNOS negotiation takes place. Do not use the chgsl verb (limits are either 0 or 1). See the man pages in Appendix C for detailed information on the verbs listed in Table 1-13.

Table 1-13. CNOS Verbs

Verb	Function
chgsl	Changes the session limit and contention-winner
	polarities for parallel-session connections.

dspsl	Provides information on the mode's current session
	limit.

initsl	Establishes the initial session limit for single-session
	or parallel-session connections.

procsl	Processes the session limit, contention-winner
	polarities, and related CNOS parameters from the
	source LU and, if necessary, negotiates them to values
	acceptable to the target LU.

rstsl	Resets to 0 the session limit for single-session or
	parallel-session connections, and the contention
	winner polarities for the parallel-session connections.

Session Control Verbs

Session control verbs explicitly activate and deactivate sessions. Sessions are activated by any one of three ways:

By issuing the actses verb.
By issuing a CNOS verb if pre-bound (also called “auto-activated”) sessions are defined for the mode.
By issuing the alcnv verb if session limits have been raised, but no sessions are active.

Sessions can be deactivated by issuing either a dctses verb or a CNOS verb to reduce the number of allowed sessions. In fact, if pre-bound sessions are defined, a session may be activated to replace one brought down by a dctses verb, leaving the same number of sessions active. The session control verbs listed in Table 1-14 are supported. See Appendix C, “Man Pages,” for additional information about these verbs.

Table 1-14. Session Control Verbs

Verb	Function
actses	Activates a session with the specified mode name to the target LU. The session is activated as a contention winner for either the source or target LU.
dctses	Deactivates the specified LU-LU session.

Security Features

Three levels of security are defined for IRIS SNA LU 6.2:

LU-LU security
Conversation-level security
Resource-level security

LU-LU security at session activation verifies the identity of the remote LU.

Conversation-level security verifies access to the remote system (that is, it determines whether or not the requesting user is authorized to allocate a conversation to the remote system).

Resource-level security verifies the user's authority to access the requested resources on the remote system; for example, whether the user is authorized to access the requested transaction program.

This section explains the three types of security and how they are implemented Following the explanation is a comparison of this implementation to the specifications in the TPRM.

LU-LU Security

LU-LU security verifies the identity of the remote LU when a session is activated between local and remote LUs using passwords configured at both LUs. Both LUs verify the identify of the other by using the following exchange protocol during session activation.

The local LU transmits random text to the remote LU, which encrypts the text using its password. The remote LU sends the encrypted data back to the local LU. The local LU then encrypts the original random data with its password and checks that the two encrypted versions match. The same exchange takes place in the opposite direction with the remote LU transmitting random data to the local LU, which then sends back the encrypted form to the remote LU.

To initiate LU-LU security, define an LU password for the remote LU with the dfnrlu verb by specifying the pswd and pswdop parameters. The hex characters must match the password of your partner. A partner using LU 6.2 specifies the same characters in defining the remote LU for your site. If your partner is an IBM system, consult the relevant IBM manual for information on how to specify security information. The encryption algorithm makes only the first seven bits of each byte significant. Therefore, passwords 0x000000 and 0x01010101 are identical.

Note: Because of federal export regulations, the LU-LU security feature is not available on all systems.

Conversation-level Security

Conversation-level security verifies that a user requesting a program start on a remote site is authorized to that site. When allocating a conversation, the user of the transaction program specifies a user ID, password, and profile. If the user does not specify this information, the source LU captures the information from the sign-on ID under which the program is being run. The security information is transmitted with the conversation-initiation information to enable the remote site to validate the request for access.

The security information is specified on the alcnv verb parameters sec, user, pass, and prof.

The parameter sec controls how security information is specified:

SEC_NONE indicates that no security information should be transmitted.
SEC_SAME specifies the use of the sign-on ID of the user running the transaction program. In this case, the password is flagged as being already verified and is not transmitted.
SEC_PGM indicates that the information provided in the user, pass, and prof parameters is to be transmitted to the remote site.

Note: Since data is not encrypted, any password sent on the allocate request is transmitted in readable form and captured with a line trace. For this reason, the SEC_SAME option is preferred.

The acceptance of the security information is configured with the dfnrlu verb at the site receiving the allocation request (remote site). The secacc parameter indicates the type of security information that can be accepted for each of the remote LUs.

The following values are defined:

NO_SEC indicates that security information is not accepted. Allocation requests received from this LU that carry security information are rejected. This means that the initiation program can specify only SEC_NONE on the alcnv request.
USERID indicates that security information is accepted from this LU, but the password-verified option is not allowed. Therefore, the initiating program cannot specify SEC_SAME on the alcnv request.
VERIFIED indicates that security information is accepted and that the verified option can be used. This means the initiation program can use any valid setting for the sec parameter of the alcnv request.

After sessions have been established between the LUs, each reads the security-acceptance level of its partner from the psecacc field returned in the dsprlu verb. The three values specify only the acceptable level of security information, and not the level required.

Accepted security information is verified against the IRIX™ system file
/etc/passwd when the allocation request is received at the remote site. The user is authorized if listed in /etc/passwd. The password is verified against the encrypted password in /etc/passwd (through the IRIX login program). If the
/etc/passwd entry for the user lacks a password, the user is verified without checking the allocation request password. Also, if SEC_SAME was specified, indicating a verified allocation request password, no password check is performed. The transaction program initiator s2_tpi performs the check against the IRIX password file.

Note: The dfnllu and dfntp verbs define a list of authorized users for the LU and the transaction program. This defined security information is never used in this implementation. The IRIX security information is used in its place. Defining users has no adverse effect on operations, although it increases memory resource usage.

Resource-level Security

Resource-level security is defined for IRIS SNA LU 6.2 to add another level of access authorization above conversation-level security. Resources, such as transaction programs, can be restricted to a small group of users. Resource security is provided in two ways. First, when a transaction program is defined, specify the level of security information required to run the program. Second, when the program is started, it is initiated under the IRIX user ID specified in the allocation request, so that IRIX security can control access to other resources, such as data files.

The dfntp verb's secrq parameter specifies whether or not security is required. Several values are provided for this parameter, indicating whether conversation-level security is required and giving the level of resource security required. However, since this implementation verifies security against the IRIX password file, not against the user information specified on the dfntp verb, the secrq parameter functions as though it were a Boolean value. Specifying SQ_NONE indicates that security information is not required. Security information can be specified in the allocation request, but is not required. Any other value indicates that security information must be provided in the allocation request. The user and password fields are verified against /etc/passwd. If a profile is specified, it is verified against /etc/group.

There is a connection between the secacc parameter of the dfnrlu verb and the secrq parameter of dfntp. The requirement for security information is determined by the transaction program configuration, but the acceptance of security information is determined by the remote LU configuration. Mismatched configurations can lead to situations where no allocation request is accepted. For example, if the transaction program requires security, but security information cannot be accepted from the remote LU, allocation requests for the transaction program from the remote LU are always rejected. Requests that contain security information are rejected because secacc is SEC_NONE. Requests that do not specify security are rejected because secrq is not SQ_NONE.

After an allocation request has passed all edits and the user has been verified, the transaction program initiator s2_tpi invokes the transaction program process and changes the process group ID and process user ID values to those in the /etc/passwd entry for the user. The transaction program runs under the IRIX security limitations of the group ID and user ID and is, in effect, logged in as the requesting user. When no security information is specified, the transaction runs by default under the group ID and user ID of the s2_tpi process. Underlying IRIX security enhances the LU 6.2-defined user verification by limiting system resources available to the transaction program to those resources available to the specified user.

In addition to user and password, LU 6.2 implements a special use of the profile field. A profile specified in the allocation request identifies an IRIX group name. The IRIX system file /etc/group is checked to see if the group is available to the user. If so, the transaction program runs under the group ID indicated in /etc/group for the group name (specified by the profile parameter) as well as under the user ID specified for the user in /etc/passwd. This way a given user has multiple groups available under which to run the transaction program. The group is specified by the profile parameter in the allocation request.

The s2_tpi process requires the effective user ID of a superuser to enable it to set the group ID and the user IDs for the transaction program processes. This is accomplished either of two ways:

Start s2_tpi from a superuser logon.

This is dangerous since transaction programs run by default under the user ID of the s2_tpi process if no security information is specified in the allocation request. If no security information is specified, the evoked program runs as root.
Run the s2_tpi program under an effective user ID of a superuser.

The s2_tpi program owned by a superuser has its file mode set to run under an effective user ID of the file's owner (for example, mode 04111) and runs under the effective user ID of the superuser. s2_tpi always removes the process-effective user ID from invoked transaction program processes. This is the preferred method.

Comparison of TPRM and LU 6.2 Security

This section compares the methods used by IRIS SNA LU 6.2 to provide LU to LU security, conversation-level security, and resource level security to those described in the IBM System Network Architecture Transaction Programmer's Reference Manual for LU 6.2 (TPRM).

LU-LU Security

The IBM TPRM configures LU-LU security via the DEFINE_REMOTE_LU verb. The LU_LU_PASSWORD parameter defines the 64-bit password used during session activation for the LU-LU verification.

LU 6.2 configures LU-LU security with the dfnrlu verb. The pswd and pswdop parameters define the LU-LU password.

Conversation-level Security

In the IBM TPRM, the DEFINE_LOCAL_LU verb provides a list of users and their associated passwords to the local LU. This list identifies the user specified in the allocation request; or, if the user is not already identified in the request, the list provides passwords to verify that the user has system access. In LU 6.2, the list of users is provided by the IRIX system file /etc/passwd. User and password information can be specified by the dfnllu verb, but this information is not used.

In the TPRM, the DEFINE_REMOTE_LU verb defines the acceptable remote LU allocation request security information. In LU 6.2, security acceptance is defined by the dfnrlu verb in a fashion similar to TPRM.

Resource-level Security

In the TPRM, the DEFINE_TP verb indicates the security required by a specific transaction program. In LU 6.2, the security required is defined similarly by the dfntp verb. However, the various flavors of security have been collapsed into one in the LU 6.2 implementation.

In the TPRM, the DEFINE_TP verb defines the users, passwords, and profiles authorized to access the program. In LU 6.2, the authorities can be defined, but the list of authorized users is not checked at program-initiation time. Instead, IRIX security is contained in /etc/passwd and /etc/group files. This provides unauthorized access protection for resources, such as files, not directly under the control of LU 6.2.

Application Diagnostics Guide

Table 1-15 provides information to help locate the source of problems encountered when creating an application with IRIS SNA LU 6.2.

Table 1-15. Application Error Codes

Problem	Solution
Compile Errors:
Include files not found	Use the -I option of the cc command to direct the compiler to load in /usr/lib.
Unresolved references	The program must be linked against the LU 6.2 library /usr/lib/liblu62.a.
Execution Errors:
LU name and/or mode are not recognized	Your program must know the configuration's names for the local LU, remote LU, and mode names to attach and to allocate a conversation.
Verb function returns a usage error (Major Code 01)	A usage error indicates that a verb parameter is being used incorrectly. Refer to the Message Guide in the IRIS SNA SERVER Administration Guide for an exact description of the error received and how to change the parameter settings.
Remote program not known (Major Code 05) (Minor Code 08)	If a fully qualified pathname is not specified, the program must be located in one of the directories in the standard path. Either relocate the target program or specify a pathname.
Remote program starts, but does not begin to receive data.	The remote program must issue an LU rattach verb connect itself to the conversation. It then must reissue a rcvwt verb to begin to receive data. Consult the man pages on these verbs for more information.
When communicating with an IBM system, PIP arrive with unexpected values.	Parameters sent to an IBM system must be sent in EBCDIC. Use the routines atoe and etoa to perform the translation. (CICS does not support Program Initialization Parameter (PIP).
When communicating with an IBM System/36, transaction error received. (Major Code 07) (Minor Code 11)	The RPG support on the System/36 required mapped conversations. The data service must be packaged in GDS variable 0x12ff. See the sample transaction programs in Chapter 2 for an example of a mapped conversation.

Prev	Table of Contents	Next
Introduction		Chapter 2. Sample Transaction Programs