An important LU 6.2 feature is the ability of a program in one node to start corresponding programs in other nodes. The attach manager handles incoming requests to start programs.
This chapter considers programs in your (local) workstation that start at the request of partner programs. The local program is referred to as remotely started. Workstation users and administrators want to control which programs can be remotely started for security and resource control. Users at remote nodes should not start programs that destroy data or use the local workstation's memory at critical times. The attach manager acts as a gate keeper, handling incoming requests to start programs on the local workstation.
The attach manager takes its name from an SNA message, called an Attach, that flows between a pair of LUs. An Attach flows when a program that uses the partner LU initiates a conversation. The LU 6.2 component in the local workstation passes any Attach it receives to its attach manager for handling. A received Attach is called an incoming allocation request or incoming Attach. In this chapter, the phrase incoming allocation request means that the SNA Attach is generated by a partner LU.
The attach manager does the following things:
Figure 7 illustrates the attach manager function.
In a communicating pair of transaction programs, only the node that receives allocation requests needs the attach manager. The attach manager manages three kinds of input:
The TP name is a key piece of information in an incoming allocation request. The attach manager uses the transaction program name to decide which program to start in the local workstation. Programmers and administrators at both nodes need to agree on each transaction program name. A program that issues an allocation request supplies a transaction program name as a parameter to the APPC [MC_]ALLOCATE or [MC_]SEND_CONVERSATION verb.
When an Attach is received, the transaction program name in the Attach is matched against transaction program names from the transaction definitions. If a match is found, the executable name from that definition is started or routed to a client workstation. If a match is not found, then the name of the executable is assumed to be the same as that which is specified in the Attach appended with .EXE.
The term transaction program has a special meaning in APPC. A transaction program is not an application; it is a section of an application.
A transaction program starts either when an application successfully issues an APPC RECEIVE_ALLOCATE or TP_STARTED verb. Both of these methods identify the transaction program as a new transaction program that APPC needs to know about. APPC reserves a group of memory blocks for the transaction program and creates a unique transaction program identifier, tp_id, which it returns to the calling program.
When an application issues a TP_ENDED verb, APPC clears its buffers for that transaction program and marks the tp_id as not valid. When an application terminates, APPC ends any active transaction programs associated with that process.
When the attach manager receives an allocation request and ensures it is valid, and if a RECEIVE_ALLOCATE is not pending, it starts the application that corresponds to the incoming transaction program name. Notice that it starts a program, not a transaction program. Generally, the application then issues a verb that establishes it as a transaction program. Given mutual consent between the sending node and the local workstation, you can configure the attach manager to start any application in the local workstation.
A transaction program must be established before a conversation can be allocated. An application must supply a tp_id on all conversation verbs that it issues while it is a part of that transaction program. Many conversations can use a single tp_id concurrently (such as in multiple threads) or sequentially (where one conversation follows another). When a transaction program ends, APPC deallocates any active conversations.
Personal Communications and Communications Server configuration uses two naming levels to identify the remotely started program:
Using two names enables flexible reconfiguration that can increase the portability of your APPC programs among workstations.
The partner transaction program and the local program must both know the transaction program name. The transaction program name is a supplied parameter for RECEIVE_ALLOCATE verbs in programs on local LUs. Partner transaction programs supply a transaction program name with APPC [MC_]ALLOCATE or [MC_]SEND_CONVERSATION verbs.
Multiple transaction program definitions can specify the same transaction program file specification. The attach manager must determine whether to run one or multiple instances of a program, so a given transaction program file specification must be configured as either queued or nonqueued in all definitions that name it. For example, if a definition that specifies MYTP.EXE is configured as "queued--attach manager started", MYTP.EXE cannot be configured as nonqueued in another transaction program definition. However, the transaction program filespec is case sensitive.
If the program identified by the attach manager cannot be started, the attach manager rejects the allocation request; the program that issued an allocation request is notified that the attach manager could not start the program.
Users or administrators define transaction programs during Personal Communications configuration to build the list of defined transaction program names. Each unique transaction program name to be accepted from a partner requires a transaction program definition in the local (accepting) workstation unless you are willing to accept the default. The transaction program definition contains information about the transaction program. Similarly, during configuration, a list of security information (allowable passwords and user IDs) is built from the LU 6.2 conversation security information. Refer to Quick Beginnings configuration information. Following is a description of the configuration data that must be specified to define a transaction program.
The conversation parameters sync_level, conv_type, and security_rqd do not directly influence how the attach manager starts a program. However, the attach manager uses the parameters to determine whether to reject an incoming allocation request before queuing it, or checking for corresponding RECEIVE_ALLOCATE verbs.
Specify whether your transaction program will support the verbs and parameters for confirmation processing when you define sync_level. These APPC verbs are [MC_]CONFIRM and [MC_]CONFIRMED. Certain parameters on the [MC_]ALLOCATE, [MC_]SEND_CONVERSATION, [MC_]PREPARE_TO_RECEIVE, and [MC_]DEALLOCATE are for confirmation processing. For Common Programming Interface Communications (CPIC) users, sync_level can be set by the Set_Sync_Level (CMSSL) call.
Incoming allocation requests contain a field that indicates whether a partner transaction program issues verbs or parameters for confirmation processing. The attach manager checks the field on the incoming allocation request against the configured value in its list of transaction program definitions. If the values do not match, attach manager rejects the incoming allocation request. The possible configuration choices are:
The conv_type parameter is used to determine both the conversation type and conversation style of the program to be started. The conversation type attribute determines whether the program to be started supports basic or mapped records when it sends and receives data. The conversation style attribute determines whether the program to be started supports half-duplex conversations. The attach manager checks whether a transaction program uses basic or mapped verbs and if it uses half-duplex or full-duplex.
The conversation types are:
The conversation styles are:
The conversation style associated with the conversation indicates the style of data transfer to be used, two-way alternate or two-way simultaneous. A conversation that specifies a two-way alternate style of data transfer is also known as a half-duplex conversation. A conversation that specifies a two-way simultaneous style of data transfer is referred to as a full-duplex conversation.
When a full-duplex conversation is allocated to a session, a send-receive relationship is established between the transaction programs connected to the conversation, and a two-way alternate data transfer occurs where information is transferred in both directions, one direction at a time. Like a telephone conversation, one transaction program calls the other, and they "converse", one transaction program talking at a time, until a transaction program ends the conversation. One transaction program issues verbs to send data, and the other transaction program issues verbs to receive data. When it finishes sending data, the sending transaction program can transfer send control of the conversation to the receiving transaction program. One transaction program decides when to end the conversation and informs the other when it has ended.
On a half-duplex conversation, only one of the two partner transaction programs has the right to send data at a time. That transaction program is in send state. The other transaction program has the responsibility to receive data. It is said to be in receive state. At specified times, the transaction programs exchange these duties. When the conversation is first set up, the client transaction is in send state and the server program is in receive state.
When a duplex conversation is allocated to a session, both transaction programs connected to the conversation are started in send-and-receive state, and a two-way simultaneous data transfer occurs where information is transferred in both directions at the same time. Both transaction programs can issue verbs to send and receive data simultaneously with no transfer of send control required. The conversation ends when both transaction programs indicate they are ready to stop sending data, and each transaction program has received the data sent by the partner. If an error condition occurs, one transaction program can decide to end both sides of the conversation abruptly.
A transaction program definition can specify that incoming allocation requests must supply a password and user ID. The password and user ID are optional parameters on the [MC_]ALLOCATE and [MC_]SEND_CONVERSATION verbs or the CPIC calls Set_Conversation_Security_UserID (CMSCSU) and Set_Conversation_Security_PassWord (CMSCSP). If a local transaction program definition specifies conversation security, the attach manager validates the password and user ID of incoming allocation requests. The attach manager rejects the allocation request if a user ID and password are not present, or if they do not match a valid combination of passwords and user IDs.
The attach manager checks the validity of any incoming allocation requests that arrive with a password and user ID, even if the transaction program definition specifies that conversation security is not required. The allocation request is rejected if the password and user ID do not match a valid combination in the list. Thus, if a password or user ID arrives in an allocation request, it is never ignored.
A remotely started transaction program (one started by another transaction program) can validate a user ID and password before it allocates a conversation to a third transaction program. In such a case, the security(SAME) parameter in the [MC_]ALLOCATE and [MC_]SEND_CONVERSATION verbs can indicate that the conversation security is already verified. The second Attach automatically gets the user ID from the first Attach, that started the first conversation.
APPC can obtain the current user ID and send it, with an indicator that the user ID was validated. In the Attach for a locally started transaction program that uses the security(SAME) parameter in either the [MC_]ALLOCATE or the [MC_]SEND_CONVERSATION verb, the partner must be able to accept the already validated indication.
Refer to System Management Programming for more information about using the user ID and password.
The following sections describe how to start programs located on either the Personal Communications or Communications Server machine.
Users can start and stop the attach manager while the SNA node is active. Each time the attach manager starts, it begins to process incoming Attaches. When the attach manager stops, it purges any queued Attaches. Refer to System Management Programming for the applicable verbs.
The attach manager needs to be started only in nodes that run remotely started transaction programs. The attach manager does not need to be started in a node if all transaction programs in the node initiate conversations (that is, they all issue APPC [MC_]ALLOCATE or [MC_]SEND_CONVERSATION verbs). Personal Communications and Communications Server node operations facility enables authorized users to start or stop the attach manager at any time. Authorized programs issue the Enable Attach Manager and Disable Attach Manager node operations verbs to start or stop the attach manager.
When the attach manager starts a program on a workstation, it uses the load_type field in the defined transaction program list to decide how to run the program. A remotely started program can be configured to start in one of the following ways:
If the attach manager cannot start the program (for example, Personal Communications and Communications Server cannot provide sufficient memory), the attach manager rejects the incoming allocation request.
If a transaction program issues a RECEIVE_ALLOCATE call and specifies a transaction program name that has not previously been defined, the system performs an implicit definition of the transaction program and assigns default values to the parameters.
The defaults used are:
| Attach timeout | = 0 | (no timeout is applied) |
| Receive Allocate timeout | = 0 | (no timeout is applied) |
| Attach Manager dynamically loaded | = Yes | (the transaction program can be loaded by the attach manager) |
These defaults mean that if you issue a call to RECEIVE_ALLOCATE as previously described, it will not complete until an attempt is made to attach to the named transaction program, or you can cancel the call.
A remotely started program in a local workstation normally issues an APPC RECEIVE_ALLOCATE verb to start both a transaction program and a conversation. The APPC RECEIVE_ALLOCATE verb specifies the same transaction program name that the remote transaction program specified in its APPC [MC_]ALLOCATE or [MC_]SEND_CONVERSATION verb. APPC passes the RECEIVE_ALLOCATE verb to the attach manager for processing. When the attach manager sees a RECEIVE_ALLOCATE verb that matches a received Attach (and the attach manager performs several cross-checks), it signals APPC that a conversation can begin. At this point, the attach manager ends its involvement in the conversation.
During transaction program configuration, you have two choices for handling multiple incoming allocation requests for the same program. You can run multiple instances of the same program concurrently in the local workstation (nonqueued operation), or you can run one instance of the same program at a time (queued operation). These values are configured in the queued and dynamic load parameters, that have the following options:
When a program is configured as nonqueued, each incoming allocation request causes the attach manager to load and execute another instance of the program associated with the incoming transaction program name.
The attach manager holds valid incoming allocation requests indefinitely, waiting for a matching RECEIVE_ALLOCATE verb from the program it started. If that program fails to issue a RECEIVE_ALLOCATE verb (for example, it loops in the code that precedes the RECEIVE_ALLOCATE verb), the attach manager holds the allocation request until the process terminates.
Queued programs can start in one of two ways:
The attach manager maintains two queues for each queued transaction program name in the defined transaction program list. One queue is for incoming allocation requests; the other is for RECEIVE_ALLOCATE verbs. For example, when an incoming allocation request arrives, the attach manager starts the corresponding local program or sends a message to the operator. The node holds the incoming allocation request until the program that the attach manager started issues a matching RECEIVE_ALLOCATE verb or until a timeout occurs. The node uses the value configured for the incoming_alloc_timeout parameter to determine when time-outs occur. Other allocation requests can arrive for that transaction program or for another transaction program. The other programs wait in their respective queues until a matching RECEIVE_ALLOCATE verb is issued, or until they time out.
Local programs can issue RECEIVE_ALLOCATE verbs before any matching allocation request arrives. The attach manager holds the RECEIVE_ALLOCATE verb on its respective queue and waits for an allocation request to arrive from a partner LU. Each queue has a timeout value; the rcv_alloc_timeout parameter specifies how long a RECEIVE_ALLOCATE verb can wait on a queue before the verb times out. The attach manager returns queued RECEIVE_ALLOCATE verbs to the associated programs with an ALLOCATE_NOT_PENDING return code. The timeout value for RECEIVE_ALLOCATE verbs can be 0 to enable programs to check whether any allocation requests are queued, and, if not, to continue other processing.
The RECEIVE_ALLOCATE verb can be issued as a nonblocking verb. This enables the transaction program to service multiple conversations from a single thread in a single process.
When RECEIVE_ALLOCATE is issued as a nonblocking verb, the attach manager returns control to the transaction program immediately; the transaction program need not remain in a wait state while waiting for the matching incoming allocation request to arrive. Instead, the transaction program can perform other work, and choose when to wait for the matching incoming allocation request.
The transaction program can queue multiple nonblocking RECEIVE_ALLOCATE verbs for different conversations. The maximum number of verbs that can be queued is limited only by resource constraints. A nonblocking RECEIVE_ALLOCATE verb will remain on the attach manager’s RECEIVE_ALLOCATE verb queue until either the matching allocation request arrives or the verb times out, that is, the rcv_alloc_timeout value has been reached.
The attach manager saves the information that identifies the transaction program when a queued program issues a valid RECEIVE_ALLOCATE verb call for a transaction program. When the queued program ends, the attach manager examines the queue of allocation requests for that transaction program. If the queue is not empty, the attach manager starts a new instance of the program, or sends a message that directs the operator to start the program.
You should configure the maximum size of the incoming allocation request queue for each transaction program. Resource constraints limit the number of queued RECEIVE_ALLOCATE verbs.
The following two cases summarize queued operations:
Table 7 provides a summary of the verbs and incoming allocation requests associated with queued and dynamic load parameter values.
| Verb Processing | Transaction Program Operation | ||
|---|---|---|---|
| Nonqueued--attach manager started | Operator started | Queued--attach manager started | |
| Incoming allocation request with pending RECEIVE_ALLOCATE verb. |
Cannot occur; no queue of pending RECEIVE_ALLOCATE verbs. |
OK RECEIVE_ALLOCATE verb. | OK RECEIVE_ALLOCATE verb. |
| Incoming allocation request without pending RECEIVE_ALLOCATE verb. |
Load and execute another program instance. Hold incoming allocation request. Wait for RECEIVE_ALLOCATE verb. |
Put incoming allocation request on queue unless queue is full. Wait for RECEIVE_ALLOCATE verb or for allotted time to expire. |
If program is not started, load and execute it. Put incoming allocation request on queue unless queue is full. Wait for RECEIVE_ALLOCATE verb or for allotted time to expire. |
| RECEIVE_ALLOCATE verb with incoming allocation request pending. | OK RECEIVE_ALLOCATE verb. | OK RECEIVE_ALLOCATE verb. | OK RECEIVE_ALLOCATE verb. |
| RECEIVE_ALLOCATE verb with no pending incoming allocation request. | Cannot occur; pending allocation requests for nonqueued operations cannot run out of time. |
Hold RECEIVE_ALLOCATE verb. Wait for incoming allocation request or for allotted time to expire. |
Hold RECEIVE_ALLOCATE verb. Wait for incoming allocation request or for the allotted time to expire. |
| Transaction program operation ends. | Nothing happens. |
Nothing happens. |
If there is a pending allocation request, reload the program; otherwise, reload on the next incoming allocation request. |
The following sections describe how to start programs that are located on Communications Server SNA API client machines.
The SNA API Client Attach Manager only supports operator started or nonqueued attach manager started programs.
Transaction programs located at client machines require transaction program definitions on both Communications Server and client machines in order to be remotely started. Following is the transaction program information required on the server:
Communications Server will verify this information when the incoming allocate arrives. In addition, the local LU that receives the incoming allocation request must be enabled to route the request to the client machine.
The client attach manager must have a transaction program defined so that it knows how to start the requested program. Following is the transaction program information required on the client:
Once these definitions are complete and the client attach manager is started, incoming allocates for transaction programs located on client machines will be routed to the client for processing.
The default local LU alias for each user can be assigned using the appropriate configuration utility, either INI configuration or LDAP.
Attach manager started programs can also choose to use a default local LU alias rather than specify one directly. When the local_LU_alias field is left blank in the attach manager record, the attach manager uses the configured default local LU alias when processing incoming conversation requests.
Users can start and stop the client attach manager while the SNA node is active.
The client attach manager needs to be started only in clients that run remotely started transaction programs. The attach manager does not need to be started in a node if all transaction programs in the node initiate conversations (that is, they all issue APPC [MC_]ALLOCATE or [MC_]SEND_CONVERSATION verbs).
To start the client attach manager, click the attach manager icon located in Communications Server for SNA client folder. This will connect the attach manager to the configured Communications Server and send the list of transaction definitions that have been defined for that client.
The Attach Manager Panel displays the list of configured transaction programs and the name of the configured Communications Server. To stop the attach manager, select Quit.