The programmer must be able to:

---

Note: This guide makes no attempt to serve as an introductory tutorial in SNA programming. Programmers needing such information can refer to the IBM manuals listed in the Related Documentation section of the “Introduction” to this guide.

---

The verbs provide the only interface into the IRIS SNA Scheduler. Each verb accepts valid parameters, executes to completion, and returns control to the program. There is no concept of interrupting and resuming a verb's execution. Each verb has been designed, however, so that it can execute in a non-blocking fashion. Blocking is optional on the accru, alnau, sndru, rcvru, rejru, gsync, and ssync verbs; the other verbs do not block.

Each verb returns a return code and the global variables snamaj, snamin, snamsg, and snastat. The return code is set to OK if the verb executed successfully, and to NOT OK if it did not. If the return code is NOT OK, snamaj and snamin contain codes describing the error.

The snamsg variable indicates if a message from the IRIS SNA Scheduler is queued within the PI verbs. Any time a PI verb is issued that reads messages from the scheduler, it is possible that other messages are received that are not returned on the current verb call.

For instance, a rcvru verb that returns a message for the requested NAU can have read messages for other allocated NAUs before reading the desired message. If this has occurred, the messages are queued within the PI layer, and snamsg is set. In general, the programmer should not let messages remain in the PI layer, as there is a finite amount of data space that PI will use before it no longer can receive messages from the scheduler.

The snastat variable is set to show which verbs can be issued at which time. It is a simple state, showing whether the NAU is not allocated, pending allocation, or allocated. When the NAU is pending allocation, only the rcvru and dalnau verbs can be issued. When snastat is set, any verb for the allocated NAU can be issued, except another alnau.

Verb functions, and any functions called by the verb, are archived in
/usr/sna/lib/liblu03.a. Programs that use verb functions must be linked against this library. In addition, link programs that use SNA LU 0-3 verb functions must be linked against two other archival libraries: /usr/sna/lib/libsna.a, which includes the IRIS SNA verb functions provided by the IRIS SNA SERVER, and /usr/lib/libbsd.a, which provides required TCP/IP support. Under most compilers, this is done with the -l option, for example:

cc sample.c -L/usr/sna/lib -llu03 -lsna -lbsd

Consult your compiler documentation for instructions on linking against the product's library.

The program operates as a process separate from the IRIS SNA Scheduler. The verbs communicate with the scheduler by exchanging messages over an interprocess communication channel, the nature of which varies from implementation to implementation. Verbs either execute locally, send messages to the IRIS SNA Scheduler, or send messages and expect a reply from the scheduler. Because some applications have a need to service events from sources other than the IRIS SNA Scheduler, verbs that send messages to the scheduler can execute in either a blocking or non-blocking fashion.

The following describes how verbs complete, in either the blocking or non-blocking manner. The blocking execution is easier to use, and is recommended for most applications. The non-blocking style is more complex, but is necessary for applications that service multiple sources of events. The programmer should determine which style of verb execution is appropriate to the application.

Execute Locally

The gfsm, initpi, and rcvru verbs execute locally. They do not send any message to the IRIS SNA Scheduler and return control to the application in the following manner:

• Local

  All processing occurs within the application. Control returns to the application immediately.

• Receive Nowait

  A message, if previously sent by the IRIS SNA Scheduler, is retrieved. Control returns to the application immediately, whether data is present or not.

• Receive Wait

  A message, if previously sent by the IRIS SNA Scheduler, is received. If not, the program will wait until the message is sent by the scheduler, or until the timer expires. Control returns to the application when a message is received or the timer expires.

Table 3-1 Illustrates the parameter settings that control verb execution.

Table 3-1. Locally Executed Verbs

Verb	Parameter	Verb	Completion	Type
			Receive	Receive
	wait	Local	Nowait	Wait
gfsm	- - -	X
initpi	- - -	X
rcvru	timeout value		X
	P_NOWAIT			X
	P_WAIT			X

---

Note: The wait parameter, present only on the rcvru verb, can be set to a timeout value in seconds, to constant P_NOWAIT, or to P_WAIT.

---

Send, Reply

The alnau, gsync, sndru, and ssync verbs generate replies from the IRIS SNA Scheduler. The alnau, gsync, and ssync verbs always operate in this way. The sndru verb operates in this way if certain parameter values are set. (The cases when the sndru verb does not generate a reply from the scheduler were covered in the previous section, “Send, No Reply.”)

The scheduler generates the reply to the gsync and ssync verbs as soon as it receives the request. The reply to the alnau verb can be constructed as soon as the scheduler receives the request, or the reply can be generated when the requested NAU is free. The when parameter controls this. The reply to the sndru verb is constructed according to the when parameter and the RH indicator settings. If the when parameter is P_NONE, or the RU is not last in chain (LIC), no reply is generated. If the when parameter is P_WHEN, and the chain is marked RQE, the reply is generated as soon as the scheduler has assigned the TH sequence number to the RU. If the chain is marked RQD, the scheduler waits until the response arrives from the partner half-session before constructing the reply. In this case, the reply contains not only the TH sequence number assigned, but the value of the response from the partner half-session.

Blocking has a meaning for these verbs in addition to the considerations described in the previous section. When blocking these verbs, wait for the reply from the scheduler before returning control to the application. The values on the reply are returned to the application as returned parameters on the verb. If the verb executes non-blocking, the verb does not wait for the reply before returning control. The application must issue a rcvru verb to read the reply.

---

Note: The blocking parameter on the alnau and sndru verbs is independent of the parameters that indicate when the reply is constructed.

---

These verbs return control to the application in the following manner:

• Send No Block

  A message is sent to the IRIS SNA Scheduler. Control returns to the application immediately. The verb completes successfully if the transport channel accepted the message. The verb completes unsuccessfully if the transport channel was not able to accept the message; the minor code gives the reason for the failure. An rcvru verb must be issued to read the reply.

• Send Block Short

  A message is sent to the IRIS SNA Scheduler. The verb handles any retry logic required to send the request. The IRIS SNA Scheduler constructs the reply as soon as the request is received in a relatively short period. The verb completes when the reply is received from the scheduler. The values on the reply are presented to the program as return parameters on the verb.

• Send Block Long

  A message is sent to the IRIS SNA Scheduler. The verb handles any retry logic required to send the request. The IRIS SNA Scheduler constructs the reply as directed, either when the requested NAU is free (alnau) or when the response is received from the partner half-session (sndru). The time required to complete is indefinite. The verb completes when the reply is received from the scheduler. The values on the reply are presented to the program as return parameters on the verb.

Table 3-3 illustrates the parameter settings that control verb execution.

Table 3-3. Send, Reply Verbs and Parameters

Verb		Parameters		Verb	Completion	Type
	block	when	rh_ind	Send	Send	Send
				No	Block	Block
				Block	Short	Long
alnau	P_BLOCK	P_IMMED	- - -		X
	P_BLOCK	P_WHEN	- - -			X
	P_NBLOCK	P_IMMED	- - -	X
	P_NBLOCK	P_WHEN	- - -	X
gsync	P_BLOCK	- - -	- - -		X
	P_NBLOCK	- - -	- - -	X
ssync	P_BLOCK	- - -	- - -		X
	P_NBLOCK	- - -	- - -	X
sndru	P_BLOCK	P_WHEN	LIC,RQE		X
	P_BLOCK	P_WHEN	LIC,RQD			X
	P_NBLOCK	P_WHEN	LIC,RQE	X
	P_NBLOCK	P_WHEN	LIC,RQD	X

The block parameter is present on the alnau, gsync, ssync, and sndru verbs.

The when parameter is present only on the alnau and sndru verbs. On the alnau verb, P_IMMED means that the IRIS SNA Scheduler should reply as soon as it receives the request. Either the NAU is allocated or it is not available. P_WHEN means that the scheduler should queue the request until the NAU is available. On the sndru verb, P_WHEN indicates that the reply should be generated according to the settings on the rh_ind parameter.

The rh_ind parameter, present only on the sndru verb, contains the RH indicators for the RU. LIC means last in chain, RQE means request exception response, and RQD means request definite response. When the chain is marked RQE, the reply is generated when the TH sequence number is assigned. When the chain is marked RQD, the scheduler waits for the response from the partner half-session before constructing a reply.

The IRIS SNA Scheduler sends unsolicited messages to the program. These messages are of two types: either SNA RUs from the session, or notification of an event within the IRIS SNA Scheduler. There are three varieties of notification:

Appendix B, “Supported SNA Request Units,” lists the SNA RUs and notes whether the IRIS SNA Scheduler passes them up to the program unaffected or whether the Scheduler responds to them itself and sends a notification. Appendix C, “Notification Events,” lists all the potential notifications that can be generated by the IRIS SNA Scheduler. Throughout the documentation, the term “receive data” is used when either an SNA RU or a notification can be received.

Whenever the scheduler sends these RUs or notifications to the program, it appends to the message an image of the states of the FSMs (finite-state machines) of the NAU. This image is the state of the FSMs immediately after the notification or RU in question has been processed by the scheduler. When the rcvru verb is executed, the notification or RU is returned to the program, and the FSM states that accompanied that message are displayed in a composite form in the naustat variable. The intention is to provide a simple method for a programmer to control the application in most cases.

Appendix F, “State Definition,” gives a complete listing of the various states of the naustat variable with suggested actions. If the programmer needs to see the complete set of FSM values, the gfsm verb displays those values. Note that the gfsm verb displays the complete image of the FSM states of the last notification or RU received via the rcvru verb. The naustat value is initially returned by the alnau verb, and is updated whenever a rcvru verb returns with data.

If the program issues verbs without intervening rcvru verbs, it is possible that the state of the session can change without the program being aware of it. For example, the program can be issuing sndru verbs with the RUs marked not LIC, so that no reply is coming from the scheduler. The link, meanwhile, may have become inoperative, and session-outage procedures would have brought the session down. If the program then issues a sndru verb marked LIC and P_NOWAIT, it sees the session-outage notification (SON) on the subsequent rcvru. If the program issues the sndru marked LIC and WAIT, however, the verb returns unsuccessfully, with a sense code indicating the error. The program, as part of its standard error recovery, should then issue rcvru verbs to read all the notifications and RUs that may have been sent by the scheduler. After all the messages from the scheduler have been read, the state values are re-established to reflect the correct state of the session.

Although the program is notified of the activation and deactivation of the SSCP-PU and SSCP-LU sessions, there is no management action for these sessions that the program can initiate via the PI verbs. The program can, however, use the node operator verbs to activate the link. After the link is active, it is the host's responsibility to issue the actpu and actlu verbs. A program can terminate all sessions on the link by issuing a Node Operator verb to deactivate the link. On a host connection, the Node Operator verb to deactivate a link issues a REQDISCONT, which causes the host to bring down the sessions in an orderly fashion. If the link should fail, the IRIS SNA Scheduler initiates session-outage procedures, bringing down the sessions. Programs are notified when this occurs.

The program is responsible for managing the LU-LU session when allocating an LU. If a BIND request arrives, it is a program's responsibility to reply to it. A program has the capability to initiate session activation by sending a formatted or character-coded login to the SSCP, and responds to the subsequent flows. A program can deactivate the session by sending an RSHUTD, TERMSELF, or an UNBIND. In addition, session management can be shared among several cooperating programs. This is because deallocating an LU does not cause the session to deactivate; the session, in fact, is not affected in any way if the program deallocates the LU. This enables several programs to share the same session serially, without having to activate the session each time. This feature provides a performance boost, but the programs using this feature need to account for the state of the session when allocating the LU.

Because the IRIS SNA Scheduler provides integrated support for PU 2.1 peer connections as well as PU 2.0 host connections, there are some differences in the way PUs are structured.

The IRIS SNA Scheduler is organized as a PU 2.1 node, which appears as a PU 2.0 node when seen from the host. As a PU 2.1 node, it can support multiple links, and, therefore, multiple SSCP-PU sessions. In this documentation, the term “PU” refers to one of these SSCP-PU sessions. When a PU is allocated, it means that the use of one of these sessions is allocated, and nothing more. Each of these PUs operates independently of the other. For instance, a dctpu verb received on one of these sessions resets all the LUs active on that link, but does not affect any other LU running in the IRIS SNA Scheduler.

When an LU is configured, the SSCP that controls it must be named. The DAF address for the LU must be unique for that SSCP's LUs, but need not be unique node-wide. The local names of each LU and LU pool, however, must be unique node-wide.

An LU can also be designated as a member of a pool, a group of LUs that has been combined for use on the alnau verb. When a pool name is requested on the alnau verb, an IRIS SNA Scheduler selects one of the free LUs in the pool. The system imposes no restriction on how LUs can be grouped into pools. The consideration should be that a user would not care which LU out of the pool was allocated when a pool name was requested on the alnau verb.

A single program can issue verbs from all the verb types, if necessary. That is, a single program can allocate an LU to issue PI verbs, and it can also allocate and use LU 6.2 conversations. There are no particular restrictions involved in doing this. The program needs only to be aware of which resource type it is working on, and to issue the correct verbs for it.

In the man pages, most of the parameters are defined as hex, shex, or lhex. These data types are used so that the valid values for each parameter are always the same, regardless of the actual integer size of the particular machine. Table 3-4 defines these three data types.

The file ddityp.h contains the actual typed statement for each of these types. This file is automatically included in the application when pgmin.h is included.

Each member (referred to in the following documentation as both
parameter and field) of the data structure can be Supplied, Returned, or Supplied/Returned.

Initialization of every member of the structure is the responsibility of the application. This is particularly true of pointers, which must be set to null if they are not set to a specific address.

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