gtps2m1b | ACF/SNA Data Communications Reference |
Presentation services supports the TPF/APPC verb interface for both assembler language and C language. It provides the interface between the TPF transaction programs issuing the verbs and the rest of the components. The main functions include:
Figure 37 shows the TPF transaction program ATTACH interface.
Figure 37. TPF Transaction Program ATTACH Interface
When a remote LU 6.2 transaction program initiates a conversation with a TPF transaction program by issuing an ALLOCATE verb, TPF receives an ATTACH functional management header type 5 (FMH5) record. The ATTACH FMH5 record contains the local TPF transaction program name, which is used as a search argument against the user-defined TPF transaction program name table (TPNT). If the transaction program name is not found in the TPNT, an FMH7 error record is sent to end the conversation. If the transaction program name is found in the TPNT, control is transferred to the TPF E-type program associated with the transaction program name. When this program is activated, the following interface is set:
Other information carried in the ATTACH FMH5 received by TPF is not passed to the local TPF transaction program.
The conversation verbs provide program-to-program communication by means of conversations between programs. The verbs defining the conversation protocol boundary are divided into subcategories based on conversation type, as follows:
The mapped conversation verbs are intended for use by application transaction programs. These verbs provide functions that are suitable for application programs written in high-level programming languages.
The TPF/APPC mapped interface is based on the communication element of SAA's Common Programming Interface (CPI). Although TPF/APPC does not fully conform to CPI Communications, standard CPI Communications programs can be converted easily, provided the programs do not use the features that TPF does not support.
Mapped conversation support is provided only through the C language interface. For additional information and details on the C language functions, see TPF C/C++ Language Support User's Guide. For more information about CPI Communications, see the Systems Application Architecture Common Programming Interface Communications Reference.
For a program to establish a conversation with a partner program, TPF/APPC requires a certain amount of initialization information: the name of the partner program, the name of the LU at the partner's node, and the mode name. The TPF/APPC mapped interface provides a way to use predefined values for these required fields; these predefined values are called side information. The side information is accessed by a symbolic destination name and is maintained in an online database called the side information table. Each symbolic destination name corresponds to an entry in the side information table and contains the following 3 pieces of information:
When a transaction program requests the initiation of a conversation and specifies a symbolic destination name, the TPF/APPC mapped interface retrieves the corresponding entry from the side information table and uses the data to initialize the conversation characteristics mode_name, mode_name_length, partner_LU_name, partner_LU_name_length, TP_name, and TP_name_length.
The side information table offline program (CHQI) provides a way of generating the side information table, verifying the syntax of the entries before bringing them online, and managing the data contained in the online side information table. You can also modify the online side information table using the ZNSID command. For details on how to run CHQI, see Generating the Side Information Table for Mapped Conversations. For details on the format of the ZNSID command, see TPF Operations.
The type-independent conversation verbs are intended for use with both mapped and basic conversations. These verbs provide functions that span both conversation types.
TPF supports the following type-independent conversation verbs:
The basic conversation verbs are intended for use by application transaction programs and LU service programs.
The TPPCC macro provides the assembler language interface for basic conversations. For more information, see TPF General Macros. The tppc_ function calls provide the C language interface for basic conversations. For more information, see the TPF C/C++ Language Support User's Guide.
TPF supports the following basic conversation verbs:
The following figures compare the interface defined by the LU 6.2 architecture with the interface provided through the TPPCC macro. The C language interface is not shown but it is similar to the TPPCC macro except that all C language function calls use positional parameters instead of keyword parameters. (See TPF General Macros and the TPF C/C++ Language Support User's Guide for details about the TPF/APPC macros and functions.)
Figure 43. GET_ATTRIBUTES Verb
Figure 45. POST_ON_RECEIPT Verb
Figure 46. PREPARE_TO_RECEIVE Verb
Figure 48. REQUEST_TO_SEND Verb
The change number of sessions (CNOS) verbs change the (LU,mode) session limit, which controls the number of LU-LU sessions per mode name that are available between 2 LUs for allocation to conversations.
The 2 LUs may cooperate in the execution of the CNOS verbs by means of a CNOS request and CNOS reply. The LU executing the control operator transaction program sends a CNOS request to the partner LU. The partner LU starts an SNA service transaction program (the CNOS service transaction program), which causes the partner LU to process the CNOS request and send back a CNOS reply.
The following is a description of the individual components for TPF's change number of sessions (CNOS) support.
TPF COPR.TP is activated when the operator issues a ZNCNS command. Based on the parameters passed by ZNCNS, TPF COPR.TP issues a CNOSC macro to communicate with the remote LU's CNOS service transaction program (CNOS.TP). The macros that TPF COPR.TP can issue are:
When control returns from PS.COPR, the conversation with the source LU (in this case, the remote LU) has already been deallocated and the session limit parameters updated for the target LU (in this case, the local LU). A message that notifies the operator that the process is complete and displays the new session limits is then sent to the TPF operator console.
Control is passed to PS.COPR when COPR.TP issues CNOSC macros or from CNOS.TP to perform the PROCESS_SESSION_LIMIT function. When receiving change number of sessions requests, TPF PS.COPR issues TPF/APPC application verbs to communicate with the target LU. After processing those verbs, TPF PS.COPR interacts with the resource manager to request session changes. Control returns to the calling COPR.TP or CNOS.TP after the services are complete.
To understand the applications' options in managing session limits, you need an overview of how TPF processes change number of sessions (CNOS) requests.
The process of changing session limits involves the exchange of session limits between the 2 control operators. TPF does not negotiate the session limits; however, if TPF initiates the CNOS exchange, the remote LU can negotiate the limits. TPF accepts the remote control operator's session limits and processes them. The control operator that initiated the CNOS request is informed of the new limits in the reply to the CNOS request.
You can write your own COPR.TP application that issues CNOS requests with the CNOSC macros. There can be only 1 CNOSC macro outstanding at a time for a particular partner LU and mode name combination. A CNOSC macro must complete before another application can issue a CNOS request for the same partner and mode name combination. An application can have multiple outstanding CNOSC macros specifying different LUs or the same LU with a different mode name.
The CNOSC RESET macro and ZNCNS RESET command both provide the ability to set the session limit to zero. Setting session limits to zero deactivates sessions using the specified mode name and LU. Sessions being used by a conversation are not deactivated until the conversation finishes.
Setting session limits to zero is part of the orderly termination of an LU 6.2 application, or consider setting the session limits to zero to deactivate sessions that are active but not presently needed.
If the application requests a session limit of zero, the session limit cannot be negotiated; the partner LU must accept the zero limit. When the application sets session limits to zero, it can specify that the change is to apply to 1 of the following:
When making a CNOSC RESET request, the application can also specify whether to drain (or honor) all the queued ALLOCATE requests (those waiting for a session) before deactivating sessions or whether to reject the requests immediately.
The partner LU cannot negotiate the draining capability of the application making the CNOS request; it must accept whatever the application specifies. The partner LU can negotiate the draining capability for its side to indicate that it will not allow draining on the target side.
Change number of sessions requests frequently cause sessions to be activated or deactivated. TPF activates additional sessions when a transaction program requests an ALLOCATE, there are no sessions free, and the session limit has not been reached. If the CNOS request lowers the session limits, TPF deactivates sessions to meet the new limits. TPF only deactivates sessions when conversations are no longer using those sessions and TPF contains the LU responsible for deactivating sessions.
The LU 6.2 architecture uses a finite state machine as a method of defining a limited (finite) number of states (current status) so that only certain actions can take place. These actions can then change the current state. In general, actions can take place only when the finite state machine is in certain states, and the execution of the requested action can then cause the state of the finite state machine to change.
The TPF/APPC support implements a logical conversation finite state machine (FSM) to control the sequence in which verbs are issued for a conversation.
The TPF/APPC support package defines the following conversation
states:
State | Definition |
---|---|
Reset (0) | The state in which a new conversation can be allocated. |
Send (1) | The state in which a conversation can send data, status, or a confirmation request. |
Receive (2) | The state in which a conversation can receive data, status, or a confirmation request from the remote partner. |
Received Confirm (3) | A conversation that was in receive state received a confirmation request. |
Received Confirm Send (4) | A conversation received a send request with a confirmation request. |
Received Confirm Deallocate (5) | A conversation received a deallocate request with a confirmation request. |
Pending Deallocate (8) | A conversation issued a deallocate request with a confirmation request. |
End Conversation (9) | The state in which a conversation cannot continue. |
|
When the local TPF transaction program issues a TPF/APPC verb request or when the remote transaction program sends data, requests, or status messages to the local TPF transaction program, an action or an event results. The state of the conversation controls the events or actions. For example, the local TPF transaction program is allowed to issue a TPF/APPC CONFIRMED verb only after it has received a confirmation request from the remote transaction program. The TPF/APPC FSM checks for the validity of all the requested actions and maintains the current state of each conversation. Invalid requests cause a state check. If the state check is due to the local TPF transaction program's issuing a TPF/APPC verb, the return code parameter (RCODE) contains the state check. If the state check is due to the remote transaction program's sending invalid data, status, or confirmation, the session is unbound, and the local transaction program is notified when it issues its next TPF/APPC verb.
The following table shows the definition of the individual actions or
events. The first column contains an indication of whether the action
was sent (S) or received (R) by the local TPF transaction program (TP).
Action or Event | Description |
---|---|
S, Allocate | The local TPF TP issues the ALLOCATE verb. |
R, Attach | The local TPF TP is activated when it receives an ATTACH header from a remote TP that issued an ALLOCATE request for the local TPF TP. |
S, Send_Data | The local TPF TP issues the SEND_DATA verb. |
S, Prep_to_Rvc_Flush | The local TPF TP issues the PREPARE_TO_RECEIVE verb with the FLUSH option. |
S, Prep_to_Rvc_Confirm | The local TPF TP issues the PREPARE_TO_RECEIVE verb with the CONFIRM option. |
S, Flush | The local TPF TP issues the FLUSH verb. |
S, Confirm | The local TPF TP issues the CONFIRM verb. |
S, Send_Error | The local TPF TP issues the SEND_ERROR verb. |
S, Receive_and_Wait | The local TPF TP issues the RECEIVE verb. |
S, Post_on_Receipt | The local TPF TP issues the POST_ON_RECEIPT verb. |
S, Wait | The local TPF TP issues the WAIT verb. |
S, Test (posted) | The local TPF TP issues the TEST verb with the TEST=POSTED option. |
S, Test (RTSR) | The local TPF TP issues the TEST verb with the TEST=RTSRCVD option. |
S, Request_to_Send | The local TPF TP issues the REQUEST_TO_SEND verb. |
R, Send_Indicator | The local TPF TP in receive state is placed in send state when the remote TP enters receive state. |
R, Confirm_indicator | The local TPF TP receives a confirmation request when it is in receive state. |
R, Confirm_Send_Ind | The local TPF TP receives a confirmation request with the SEND indication when it is in receive state. |
R, Confirm_Dealloc_Ind | The local TP receives a confirmation request with the deallocation indication. |
S, Confirmed | The local TPF TP issues the CONFIRMED verb. |
R, Program_Error_RC | The local TPF TP receives an indication that the remote TP issued a SEND_ERROR verb because of a program failure. |
R, Service_Error_RC | The local TPF TP receives an indication that the remote TP issued a SEND_ERROR verb because of a service failure. |
R, Dealloc_Normal_RC | The local TPF TP receives an indication that the remote TP issued a DEALLOCATE verb with the FLUSH option. |
R, Dealloc_Abend_RC | The local TPF TP receives an indication that the remote TP issued a DEALLOCATE verb with 1 of the ABEND options. |
R, Resource_Failure_RC | The local TPF TP receives an indication that a conversation failure occurred. |
R, Alloc_Error_RC | The local TPF TP receives an indication that a conversation allocation request failed. |
S, Dealloc_Flush | The local TPF TP issues the DEALLOCATE verb with the FLUSH option. |
S, Dealloc_Confirm | The local TPF TP issues the DEALLOCATE verb with the CONFIRM option. |
S, Dealloc_Abend | The local TPF TP issues the DEALLOCATE verb with 1 of the ABEND options. |
S, Dealloc_Local | The local TPF TP issues the DEALLOCATE verb with the LOCAL option. |
R, Dealloc_Pend_Confirm | The local TPF TP receives the confirmation reply while waiting in response to a DEALLOCATE verb with the CONFIRM option. |
S, Get_Attribute | The local TPF TP issues the GET_ATTRIBUTES verb. |
S, Get_Type | The local TPF TP issues the GET_TYPE verb. |
The TPF/APPC conversation FSM is shown in Table 2. The columns of the matrix show the defined states,
and the rows show the individual actions or events. The number in each
box indicates the new state of the conversation following the completion of
the event. An empty box shows that the condition is not allowed, and,
if encountered, a state check results.
Table 2. TPF/APPC Conversation Finite State Machine Matrix
Actions or Events | States | |||||||
---|---|---|---|---|---|---|---|---|
Reset (0) | Send (1) | Receive (2) | Received Confirm (3) | Received Confirm Send (4) | Received Confirm Deallocate (5) | Pending Deallocate (8) | End Conversation (9) | |
S, Allocate | 1 |
|
|
|
|
|
|
|
R, Attach | 2 |
|
|
|
|
|
|
|
S, Send_Data |
| 1 |
|
|
|
|
|
|
S, Prep_to_Rvc_Flush |
| 2 |
|
|
|
|
|
|
S, Prep_to_Rvc_Confirm |
| 2 |
|
|
|
|
|
|
S, Flush |
| 1 |
|
|
|
|
|
|
S, Confirm |
| 1 |
|
|
|
|
|
|
S, Send_Error |
| 1 | 1 | 1 | 1 | 1 |
|
|
S, Receive_and_Wait |
| 2 | 2 |
|
|
|
|
|
S, Post_on_Receipt |
|
| 2 |
|
|
|
|
|
S, Wait |
|
| 2 |
|
|
|
|
|
S, Test (posted) |
|
| 2 |
|
|
|
|
|
S, Test (RTSR) |
| 1 | 2 |
|
|
|
|
|
S, Request_to_Send |
| 1 | 2 | 3 | 4 | 5 |
|
|
R, Send_Indicator |
|
| 1 |
|
|
|
|
|
R, Confirm_Indicator |
|
| 3 |
|
|
|
|
|
R, Confirm_Send_Ind |
|
| 4 |
|
|
|
|
|
R, Confirm_Dealloc_Ind |
|
| 5 |
|
|
|
|
|
S, Confirmed |
|
|
| 2 | 1 | 9 |
|
|
R, Progrm_Error_RC |
| 2 | 2 |
|
|
| 2 |
|
R, Service_Error_RC |
| 2 | 2 |
|
|
| 2 |
|
R, Dealloc_Normal_RC |
| 9 | 9 |
|
|
|
|
|
R, Dealloc_Abend_RC |
| 9 | 9 |
|
|
| 9 |
|
R, Resource_Failure_RC |
| 9 | 9 |
|
|
| 9 |
|
R, Alloc_Error_RC |
| 9 | 9 |
|
|
| 9 |
|
S, Dealloc_Flush |
| 0 |
|
|
|
|
|
|
S, Dealloc_Confirm |
| 8 |
|
|
|
|
|
|
S, Dealloc_Abend |
| 0 | 0 | 0 | 0 | 0 |
|
|
S, Dealloc_Local |
|
|
|
|
|
|
| 0 |
R, Dealloc_Pend_Confirm |
|
|
|
|
|
| 0 |
|
S, Get_Attribute |
| 1 | 2 | 3 | 4 | 5 |
| 9 |
S, Get_Type |
| 1 | 2 | 3 | 4 | 5 |
| 9 |
|