gtps2m1bACF/SNA Data Communications Reference

Presentation Services

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:

TPF Transaction Program ATTACH Interface

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:

Conversation Verbs

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:

Mapped Conversations

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.

Side Information

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:

Transaction program (TP) name
Specifies the name of the remote transaction program

Partner LU name
Is the name of the LU where the remote transaction program is located

Mode name
Is used by TPF/APPC to designate the properties for the session that will be allocated for the conversation.

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.

Type-Independent Conversation Verbs

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:

Basic 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:

Architecture and TPPCC Macro Comparison

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.)

Note:
In each figure, there is a line that separates the parameters that are passed to the processing components from the parameters that are returned. The passed parameters are shown above the line and the returned parameters are shown below the line. Parameters shown between 2 lines are both passed and returned.

Figure 38. ALLOCATE Verb


Figure 39. CONFIRM Verb


Figure 40. CONFIRMED Verb


Note:
RCODE returns state checks and parameter checks.

Figure 41. DEALLOCATE Verb


Figure 42. FLUSH Verb


Note:
RCODE returns state errors and parameter checks.

Figure 43. GET_ATTRIBUTES Verb


Note:
RCODE returns state checks and parameter checks.

Figure 44. GET_TYPE Verb


Figure 45. POST_ON_RECEIPT Verb


Note:
RCODE returns state checks and parameter checks.

Figure 46. PREPARE_TO_RECEIVE Verb


Figure 47. RECEIVE Verb


Figure 48. REQUEST_TO_SEND Verb


Figure 49. SEND_DATA Verb


Figure 50. SEND_ERROR Verb


Figure 51. TEST Verb


Figure 52. WAIT Verb


Change Number of Sessions

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.

Change Number of Sessions Components

The following is a description of the individual components for TPF's change number of sessions (CNOS) support.

TPF control operator transaction program (COPR.TP)
Serves as an interface between the TPF change number of sessions command (ZNCNS) and the presentation services for control operator (PS.COPR).

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:

Note:
You can create your own COPR.TP to issue CNOS requests. There can be as many COPR.TPs in the system as you need.

CNOS service transaction program (CNOS.TP)
Is a reserved SNA-defined transaction program in TPF. This program serves as an interface between the remote control operator transaction program and the TPF PS.COPR. When the remote LU makes a CNOS request to TPF, the TPF CNOS.TP is activated, and in turn, activates the PS.COPR to perform the PROCESS_SESSION_LIMIT function.

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.

Presentation service for the control operator (PS.COPR)
Serves as an interface between (1) the TPF COPR.TP and the remote CNOS.TP or (2) the remote COPR.TP and the TPF CNOS.TP. PS.COPR provides services for each TPF-supported change number of sessions verb.

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.

Managing Session Limits

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.

Setting Session Limits to Zero

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.

Managing Session Activation and Deactivation

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.

Finite State Machine

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.

Note:
TPF/APPC support implements 2 other types of finite state machines, which are not discussed in detail. 1 maintains the status of posting, and the other maintains the status of errors and failures.

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.
Note:
TPF does not support the states Prepare to Receive Defer (6) and Deallocate Defer (7) defined in the LU 6.2 architecture.

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
Note:
TPF does not support the states Prepare to Receive Defer (6) and Deallocate Defer (7) defined in the LU 6.2 architecture for the SYNCH_POINT options.


Footnotes:

2
This verb is a TPF extension to the LU 6.2 architecture.