2.2
Implementation-specific Verbs
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.
2.2.1
Transaction Program Connection Verbs
Before a program can issue any conversation, control-operator, or nodeoperator 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.
IRIS SNA SERVER Programming Guide
2-7
2-8
Verb Function attach detach rattach setctx
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.
Table 2-2
Transaction Program Connection Verbs
2.2.2
Transaction Program Utility Functions
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.
Utility Function
atoe etoa dspmaj dspmin prtnmsg
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.
Table 2-3
Transaction Program Utility Functions
Programming with the SNA SERVER Verbs
2.3
Configuration Verbs
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 2.1.5, “Data Structures.” For the characterstring 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.
2.3.1
Define Verbs
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.
IRIS SNA SERVER Programming Guide
2-9
2-10
Verb Function dfncp dfnline dfnllu dfnmode dfnnode dfnrlu dfnslu dfnsta dfntp dltcbl dltcbu initcbl initcbu
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.
Table 2-4
Define Verbs
The node define verbs use the parameter constants listed in Table 2-5.
Programming with the SNA SERVER Verbs
Constant Description
IGN_VAR
SUPPORT
NOT_SUP
Ignore this parameter.
Specifies that an optional parameter is to be ignored. Use the current or default value for this parameter.
Function is supported.
Indicates the specific function is supported.
Function is not supported.
Indicates the specific function is not supported.
Table 2-5
Parameter Constants for Node Define Verbs
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.
IRIS SNA SERVER Programming Guide
2-11
2-12
Constant Description
IGN_VAR
SUPPORT
NOT_SUP
RPL_VAR
DEL_VAR
ADD_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.
Function is supported.
Indicates the specific function is supported.
Function is not supported.
Indicates the specific function is not supported.
Replace parameter.
Specifies that a related field (such as a network name) is to replace the existing value on the control block.
Delete parameter.
Specifies that a related field (such as a network name) is to be deleted from a control block.
Add parameter.
Specifies that a related field (such as an user ID) is to be added to a control block.
Table 2-6
Parameter Constants for LU Define Verbs
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.)
2.3.2
Display Verbs
Display verbs return information about configuration elements for 6.2 LUs
(the local LU, remote LU, modes, and transaction programs), secondary LUs,
Programming with the SNA SERVER Verbs
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 dspcp dspcph dspline dspllu dspmode dspnode dsprlu dspses dspslu dspsta dsptp
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.
Table 2-7
Display Verbs
Display verbs for the node use the parameter constants listed in Table 2-8.
IRIS SNA SERVER Programming Guide
2-13
2-14
Constant Description
IGN_VAR
SUPPORT
NOT_SUP
NEXT
Ignore this parameter.
Specifies that an optional parameter is to be ignored. The current or default value for this parameter is to be used.
Function is supported.
Indicates the specific function is supported.
Function is not supported.
Indicates the specific function is not supported.
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.
Table 2-8
Display Verb Parameter Constants for the Node
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.
Programming with the SNA SERVER Verbs
Display verbs for the LU use the parameter constants listed in Table 2-9.
Constant Description
IGN_VAR
SUPPORT
NOT_SUP
NEXT
Ignore this parameter.
Specifies that an optional parameter is to be ignored. The current or default value for this parameter is to be used.
Function is supported.
Indicates the specific function is supported.
Function is not supported.
Indicates the specific function is not supported.
Display information on the next control block.
Table 2-9
Display Verb Parameter Constants for the LU
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.
IRIS SNA SERVER Programming Guide
2-15
2.4
Node Operator Verbs
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.
Verb Function actline actlu actpu actsta chgmsgq dctline dctlu dctpu dctsta dspmsgq rtvnmsg
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.
Table 2-10
Node Operator Verbs
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.
2-16
Programming with the SNA SERVER Verbs
2.5
Operation Diagnostics
Table 2-11 provides information to help you locate and solve a problem if you encounter trouble using the IRIS SNA SERVER.
Problem
The line is active but the station is pending-active, even after the partner activates its side.
“Link Inoperative” message received.
“Link Inoperative” message received (“too many aborts”)
Primary is polling; secondary is responding.
Line drops immediately after activation.
The message ends with
“CNOS allocation error.”
Solution
Check that the SDLC address in the station definition block matches your partner’s. If it does not and the problem persists, check for a defective cable between the system and the modem.
Deactivate the line, then reactivate it.
Consult Appendix C in the IRIS
SNA Administration Guide
for specific information about the condition that caused the line to drop.
The duplex, NRZI, and line speed settings re ceived must match. If they do not, reconfigure and try again. Also, check the modem's duplex setting.
The duplex, NRZI, and line speed settings must match. If they do not, reconfigure and try again. Also, check you modem's
duplex setting.
Check the log. It is likely that the exchange IDs were not recognized. Contact your partner and exchange exchange IDs.
Update the local node or remote node block, regenerate the configuration, and retry.
Partner needs to initialize session limits.
Table 2-11
Operation Diagnostics
IRIS SNA SERVER Programming Guide
2-17
Problem
The message states that the LU was not recognized.
No sessions are activated.
Solution
Your configuration does not match your partner’s mode. Modify the resource definition blocks, regenerate the configuration, and try again.
If you specified 0 auto-initiated sessions in the mode definition block, sessions are not activateed until needed by an application. If you did specify auto-initiated sessions, check the log for session-failure messages. Usually this problem is a mismatch of the mode parameters for
CNOS support and re-initialization.
Table 2-11 (continued)
Operation Diagnostics
2-18
Programming with the SNA SERVER Verbs
