This chapter contains information to help you write transaction programs using the verb library functions and to help diagnose application errors should they arise. 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 C describes messages displayed during normal system activity or when errors are detected. Appendix G, “API Verb Catalog,” lists all of the API verbs in alphabetical order, giving their full names and verb types.
Some of the verbs presented in this chapter are relevant to users of IRIS SNA LU 6.2. See the IRIS SNA LU 6.2 Programming Guide for information about these verbs.
The Application Program Interface (API) is a library of verb functions and header files that define the structures and variables needed by applications that call the verb functions. In the Silicon Graphics implementation, these verbs take the form of C-language function calls. The API supplied by the IRIS SNA SERVER also contains the verbs needed by other related Silicon Graphics SNA products such as IRIS SNA LU 6.2, IRIS SNA 3770, and IRIS SNA 3270. The API library for the IRIS SNA SERVER is installed as /usr/lib/libsna.a and /usr/lib/liblu03.a.
The IRIS SNA SERVER verbs are divided into three categories according to their function:
Implementation-specific verbs
Configuration verbs
Node Operator verbs
Implementation-specific verbs are not specified in the IBM SNA Transaction Programmer's Reference Manual for LU Type 6.2 (referred to subsequently in this guide as TPRM) but are defined and implemented in Silicon Graphics SNA products. These verbs are divided into two groups:
Transaction program connection verbs
Transaction program utility functions
The connection verbs establish or break the connection between a transaction program and the IRIS SNA Scheduler. The utility functions, while not true verbs, provide routines that APPC transaction programs commonly need, such as ASCII-to-EBCDIC translation.
Configuration verbs define and display the resources of the node and logical unit. They are divided into two groups:
Define verbs
Display verbs
The first group contains both LU define and node define verbs. The LU define verbs configure information about LUs, modes, and transaction programs. The node define verbs configure PU 2.1 components. The second group, the display verbs, provide information about the configured LUs and PU 2.1 components.
Verb functions, and functions called by the verb, are archived in
/usr/lib/libsna.a. Programs that use verb functions must be linked against this library. Under most compilers, this is accomplished by using the -l option; for example:
cc sample.c -L/usr/lib/sna -lsna.a |
Note the case-specific use of the letter l in the example. See your compiler documentation for instructions on linking against product libraries.
The structures and variables used in the SNA verbs are defined in header files located in /usr/include/sna. Here are some of the header files you can include in your application:
In addition to these header files, /usr/include/sna contains several files that contain the type definitions and constant values used by the SNA verbs. They do not need to be explicitly included; examine them for their contents.
The verb parameter structures use data types defined in the header file ddhvtyp.h. Several of these data types may not be familiar to you:
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
Each member (referred to as both parameter and field) of the data structure is described as being Supplied, Returned, or Supplied/Returned.
Initialization of every member of the structure is the responsibility of the application. This is especially true of pointers, which must be set to null if not set to a specific address.
 | 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 names and other strings that are to be returned. If the pointer is nulled, the name is not returned. |
Even though the value in a name field is returned by the verb, the pointer must still be supplied by the application program. A display verb with a name parameter listed as Supplied/Returned can return a different name in that space after the successful completion of the verb.
Supplied parameters are further specified as Required, Conditional, or Optional.
Required parameters must be set by the application program.
Conditional parameters can have a value required, depending on the setting of another parameter.
Optional parameters need not be set.
Information on the state of the conversation and feedback on the execution of verb calls are 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 functions described in the IRIS SNA SERVER API. Routines that query the values of these variables can refer to them as external variables.
After a verb function is executed, 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 completed normally (return code of “OK”), the function returns 0 and the major and minor codes are also 0. If a return code was set in the major or minor fields, the verb function returns -1. In general, the major code is sufficient for controlling program logic.
Table 2-1 describes the major codes used. (For a complete list of the major and minor return codes, see Appendix A.)
Major Code | Description |
|---|---|
S2_OK (0) | Function completed successfully. |
S2_USAGE (1) | Function aborted, usage error. |
| The function was not performed because a parameter was in error or requested a function that was not supported. Most of the minor codes provide specific information on usage errors. |
S2_UNSUC (2) | Function completed unsuccessfully. |
| Set when a function, such as “Receive Immediate” or “Test,” completes normally but does not return data.
|
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 error occurs. |
S2_PGMER (7) | Program error. |
| The partner program has issued an error indication. If the conversation was in send state, it is now in 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) | Node-operator function error. |
| A node-operator function was not accepted. Since node operator verbs do not use conversations, the conversation state does not apply.
|
Although the implementation-specific verbs are not part of the IBM SNA, they are required for the IRIS SNA SERVER. These verbs perform specific functions, such as opening and closing the connection between the transaction program and the IRIS SNA Scheduler.
The implementation-specific verbs are divided into two groups: transaction program connection verbs and transaction program utility functions. Each of these groups is described on the following pages. The verb structures and variables are in /usr/include/sna/imp.h.
Before a program can issue any conversation, control-operator, or node-operator functions, it establishes a connection with the IRIS SNA Scheduler. Establishing this connection 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. Node operator verbs require only the configuration. 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 Scheduler, they are the first and last verbs the program issues.
Table 2-2 shows the supported transaction program connection verbs.
Table 2-2. Transaction Program Connection Verbs
Verb | Function |
|---|---|
Initiates communication between the local program and the IRIS SNA Scheduler. | |
Detaches the current context from the IRIS SNA Scheduler. | |
Initiates communication between a remotely invoked transaction program and the IRIS SNA Scheduler. | |
Sets the current context under which subsequent verbs are issued. |
The transaction program utility functions shown in Table 2-3 are not considered verbs because they do not set snastat, snamaj, or snamin. Rather, they provide useful routines for writing APPC applications.
Table 2-3. Transaction Program Utility Functions
Utility | Function |
|---|---|
Translates an ASCII string into EBCDIC for partner programs running on IBM computers so they may receive application-specific information. | |
Translates an EBCDIC string into ASCII so partner programs running on IBM machines can send application-specific information. | |
Formats major return code messages. | |
Formats minor return code messages. | |
Prints a formatted message from the message structure returned by the rtvnmsg verb. |
Configuration verbs are divided into two categories: define verbs and display verbs. The define verbs include LU define verbs, which configure local and remote LUs, modes, and transaction programs; and node define verbs, which define the components of the PU 2.1 node. (Display verbs display information about LUs, modes, transaction programs, and PU 2.1 node components.)
The verb functions, and functions called by the verb, are archived in
/usr/lib/libsna.a. Programs that use verb functions are linked against this library. LU define verb data structures are in /usr/include/sna/ludef.h. Data structures for the node define verbs are in /usr/include/sna/noop.h. The global variables are defined in header file /usr/include/sna/global.h.
Each verb has an associated data structure that contains the verb's parameters. These data structures are more complex than those for the conversation verbs. To simplify their use, two special verbs are provided—initcbu for the node and initcbl for the LU—to initialize the values in the structure members. Each pointer within the structure is nulled. All other fields are set to the constant value, indicating that the parameter is not being specified.
As stated earlier, each member of the data structure is described as being Supplied, Returned, or Supplied/Returned. For more information on these parameter qualifiers, see Section , “Data Structures.” For the character-string parameters in the display verbs, Returned and Supplied have a slightly different meaning. These verbs require the application program to allocate space for names and other strings that are to be returned. If the pointer is nulled, the name is not returned. Even though the value in a name field is returned by the verb, the pointer must still be supplied by the application program. A name parameter listed as Supplied/Returned in a display verb means a different name can be returned in the same space after the successful completion of the verb.
Define verbs define the configuration elements of the LU (the local LU, remote LU, modes, and transaction programs) and the PU 2.1 node (the lines, stations, control points, and the node itself). Table 2-4 lists the define verbs that are provided.
Verb | Function |
|---|---|
Defines the addressing information for the control point at the remote node. | |
Defines line name, line type, and line characteristics. | |
Initializes or modifies parameter values that control the operation of the local LU. | |
Initializes or modifies parameter values that control the operation of the local LU in conjunction with a group of sessions (identified by a mode name) with a remote LU. | |
Defines the system-wide operating parameters for an instance of the SNA node. | |
Initializes or modifies parameter values that control the operation of the local LU in conjunction with a remote LU. | |
Defines a secondary LU. | |
Defines the station name and other parameters that pertain to the adjacent link station. | |
Initializes or modifies parameter values that control the operation of the local LU in conjunction with a local transaction program. | |
Deletes the operating parameters for the local LU that were set by the define verbs. | |
Deletes control blocks defined by the node define verbs. | |
Initializes a define verb structure. | |
Initializes a define verb structure of the type specified in the stype parameter.
|
The node define verbs use the parameter constants listed in Table 2-5.
Table 2-5. Parameter Constants for Node Define Verbs
Constant | Description |
|---|---|
IGN_VAR | Ignore this parameter. |
| Specifies that an optional parameter is to be ignored. Use the current or default value for this parameter.
|
SUPPORT | Function is supported. |
| Indicates the specific function is supported.
|
NOT_SUP | Function is not supported. |
| Indicates the specific function is not supported.
|
These parameter constants and the data structures are defined in the header file uadef.h.
| Note: Some of the node define verb parameter constants listed in Table 2-5 and Table 2-6 have the same underlying values. Specifically, NOT_SUP, ADD_VAR, and RPL_VAR have a value of 0. DEL_VAR and SUPPORT have a value of 1. IGN_VAR has a value of -1. Use only the documented constants for any parameter value since these equivalencies can change in later releases. |
The LU define verbs use the parameter constants listed in Table 2-6.
Table 2-6. Parameter Constants for LU Define Verbs
Constant | Description |
|---|---|
IGN_VAR | Ignore this parameter. |
| Specifies that an optional parameter is to be ignored. The current or default value for this parameter is to be used. |
SUPPORT | Function is supported. |
| Indicates the specific function is supported.
|
NOT_SUP | Function is not supported. |
| Indicates the specific function is not supported.
|
RPL_VAR | Replace parameter. |
| Specifies that a related field (such as a network name) is to replace the existing value on the control block. |
DEL_VAR | Delete parameter. |
| Specifies that a related field (such as a network name) is to be deleted from a control block. |
ADD_VAR | Add parameter. |
| Specifies that a related field (such as an user ID) is to be added to a control block. |
These parameter constants and the data structures are defined in the header file ludef.h.
| Note: Before issuing a define or display verb, the transaction program uses the attach verb to establish a connection to s2_schd, the IRIS SNA SERVER. |
The verbs return 0 if the control block was successfully defined or displayed and -1 if an error occurred. For errors, the global variables snamaj and snamin are set to the major code and minor code of the error. Use the verbs dspmaj and dspmin to translate these codes into printed error messages. (For a list of the major and minor codes, see Appendix A.)
Display verbs return information about configuration elements for 6.2 LUs (the local LU, remote LU, modes, and transaction programs), secondary LUs, and the PU 2.0/PU 2.1 node (the lines, stations, control points, and the node itself). Table 2-7 lists the display verbs.
Verb | Function |
|---|---|
Returns addressing information for a control point defined with the dfncp verb. | |
Returns data describing the current status of sessions with a host-type control point. | |
Returns information about a line defined with the dfnline verb. | |
Returns parameter values that control Local LU operation. | |
Returns parameter values that control the operation of the local LU in conjunction with a group of sessions (identified by a mode name) with a remote LU. | |
Returns information stored in the Node Control Block. | |
Returns parameter values that control the operation of the local LU in conjunction with the remote LU. | |
Returns information about sessions between local and remote LUs. | |
Returns information about a secondary LU. | |
Returns information about a station defined with the dfnsta verb. | |
Returns parameter values that control the operation of the local LU in conjunction with a local transaction program. |
Display verbs for the node use the parameter constants listed in Table 2-8.
Table 2-8. Display Verb Parameter Constants for the Node
Constant | Description |
|---|---|
IGN_VAR | Ignore this parameter. |
| Specifies that an optional parameter is to be ignored. The current or default value for this parameter is to be used. |
SUPPORT | Function is supported. |
| Indicates the specific function is supported.
|
NOT_SUP | Function is not supported. |
| Indicates the specific function is not supported.
|
NEXT | Display information on the next control block. |
| The Display Verbs can return information on a specific block or the next block so that you can step through all of the blocks of a specific type. If a block is named and the next parameter is set to IGN_VAR, the information for that block is returned. If next is set to NEXT, information for the next block is returned. |
These parameter constants and the data structures are defined in the header file uadef.h.
| Note: Some of these widely used constants have the same underlying values. Specifically, NOT_SUP and NEXT have a value of 0. SUPPORT has a value of 1. IGN_VAR has a value of -1. Use only the documented constants for any parameter value since these equivalencies can change in later releases. |
Display verbs for the LU use the parameter constants listed in Table 2-9.
Table 2-9. Display Verb Parameter Constants for the LU
Constant | Description |
|---|---|
IGN_VAR | Ignore this parameter. |
| Specifies that an optional parameter is to be ignored. The current or default value for this parameter is to be used.
|
SUPPORT | Function is supported. |
| Indicates the specific function is supported. |
NOT_SUP | Function is not supported. |
| Indicates the specific function is not supported. |
NEXT | Display information on the next control block. |
These parameter constants and data structures are defined in the header file ludef.h.
| Note: Some of these widely used constants have the same underlying values. Specifically, NOT_SUP, ADD_VAR, RPL_VAR, and NEXT all have a value of 0. DEL_VAR and SUPPORT have a value of 1. IGN_VAR has a value of -1. Use only the documented constants for any parameter value since these equivalencies can change in later releases. |
The verbs return 0 if the control block was successfully defined or displayed and -1 if an error occurred. If there was an error, the global variables snamaj and snamin are set to the major code and minor code of the error. Use the verbs dspmaj and dspmin, described in “Transaction Program Utility Functions,” to translate these codes into printed error messages. (For a list of the major and minor codes, see Appendix A.)
| Note: Before issuing a define or display verb, the transaction program uses the attach verb to establish a connection to the IRIS SNA SERVER, s2_schd. |
Node operator verbs activate lines, stations, LUs, and the local PU and control the node logging and message facilities. While their format is not determined by IBM, their function is implied.
The Node Operator verb function is archived in /usr/lib/libsna.a. Programs that use verb functions must be linked against this library. The data structures used in these verbs are in /usr/include/sna/noop.h. The global variables are defined in the header file /usr/include/sna/global.h.
Table 2-10 lists the node operator verbs provided.
Table 2-10. Node Operator Verbs
Verb | Function |
|---|---|
Activates the line. | |
Activates the LU locally. | |
Activates the node's physical unit locally. | |
Instructs the node to enable the link connection to a particular remote node. | |
Instructs the node to change the status parameters of a message queue. | |
Deactivates the named line from use. | |
Terminates the use of the named LU. | |
Terminates the use of the PU. | |
Instructs the node to issue the proper commands to disable the link connection to a particular remote node. | |
Instructs the node to display the status parameters of a message queue. | |
Retrieves a message from the named message queue. |
The activation and deactivation requests issue a message to the Node Operator message queue indicating whether the activation or deactivation was successful. Each of these requests returns a correlation number used to retrieve the completion message from the queue.
Table 2-11 provides information to help you locate and solve a problem if you encounter trouble using the IRIS SNA SERVER.
Table 2-11. Operation Diagnostics