CPI-C terms

The terms ‘conversation’, ‘conversation characteristics’, and ‘side information’ exist in CPI-C.

• A conversation is a communication relationship processed by a CPI-C program in a UTM service.

• Conversation characteristics describe the current parameters and features of a conversation, see Conversation Characteristics.

• In connection with the UPIC carrier system, side information basically describes the addressing information required for a conversation. The addressing information necessary for a conversation is contained in the side information file (upicfile).

Conversation state

The state of a conversation reflects the last action of this conversation or defines the next actions that are permitted.

When you write a program that uses CPI-C calls, you must ensure that the appropriate calls are always used in the CPI-C program and in the UTM program unit. In particular, only the partner with send authorization is permitted to send data.

With the UPIC carrier system, a conversation can have one of the following states:

State	Description
Start	The program is not signed on to the UPIC carrier system. (before the Enable_UTM_UPIC call or after the Disable_UTM_UPIC call).
Reset	No conversation is assigned to the conversation_ID.
Initialize	The Initialize_Conversation call was completed successfully and a conversation_ID was assigned to the conversation.
Send	The program is authorized to send data in the conversation.
Receive	The program can receive information via the conversation.

Table 1: Conversation states

At the beginning, a conversation is in the “Reset” state and then enters various follow-up states, depending on the actual calls issued and the information received from the partner program.

The “Send” and “Receive” states have a special role to play. This role is described in section “Exchange of messages with a UTM service”. A table of states can be found in the appendix on page State table. Here you will find the state changes of a CPI-C conversation, depending on the CPI-C calls and their results.

UPIC monitors the current state of a conversation. If the synchronization of the two sides is violated by an illegal call, this error is displayed with the value CM_PROGRAM_STATE_CHECK as the result of the call.

The X/Open CPI-C Specification defines further states, but these do not apply to the UPIC carrier system.

Conversation characteristics

The conversation characteristics are managed in a control block together with the side information of a conversation. This section describes the characteristics relevant to CPI-C with the UPIC carrier system, as well as the values assigned to these characteristics in the Initialize_Conversation call. The X/OPEN interface CPI-C contains additional characteristics which are not listed here.

There are three types of conversation characteristics:

• those that are preset

• those that can be modified using CPI-C calls

• those that are UPIC specific

The following conversation characteristics are preset:

Conversation characteristics	Initialization value for Initialize_Conversation
conversation_type	CM_MAPPED_CONVERSATION
return_control	CM_WHEN_SESSION_ALLOCATED
send_type	CM_BUFFER_DATA
sync_level	CM_NONE

Table 2: Preset conversation characteristics

The following conversation characteristics can be modified using CPI-C calls:

Conversation characteristics	Initialization value for Initialize_Conversation
deallocate_type	CM_DEALLOCATE_SYNC_LEVEL
partner_LU_name	Value from side information, dependent on the symbolic destination name
partner_LU_name_length	Length of partner_LU_name
receive_type	CM_RECEIVE_AND_WAIT
security_new_password	Empty
security_new_password_length	0
security_password	Blank
security_password_length	0
security_type	CM_SECURITY_NONE
security_user_ID	Blank
security_user_ID_length	0
TP_name	Value from side information, dependent on the symbolic destination name
TP_name_length	Length of TP_name

Table 3: Conversation characteristics which can be modified

The following conversation characteristics are UPIC specific and can be modified. The distinction is made between characteristics for a partner application and values for a local application:

Conversation characteristics	Initialization value for Initialize_Conversation
CHARACTER_CONVERTION	CM_NO_CHARACTER_CONVERTION
CLIENT_CONTEXT	empty
ENCRYPTION-LEVEL	0
PORT	102
T-SEL	Value derived from partner_LU_name
T-SEL-FORMAT	Value derived from partner_LU_name
HOSTNAME	Value derived from partner_LU_name
IP-ADDRESS	Not initialized
RSA-KEY	Allocated by the UTM application
SECONDARY_RETURN_CODE	CM_RETURN_TYPE_SECONDARY
TRANSACTION_STATE	empty

Table 4: UPIC specific conversation characteristics for remote applications

Values for local applications	Initialization value for Enable_UTM_UPIC
PORT	102
T-SEL	Value derived from local application name
T-SEL-FORMAT	Value derived from local application name

Table 5: UPIC specific values for local applications

The characteristics and local values are not explained in greater detail. This list is merely given to enable the conversation characteristics in the CPI-C interface provided by UPIC to be compared with those in the X/Open CPI-C interface. A detailed explanation can be found in the X/Open specification “CPI-C Specification Version 2”.

Side information

Because the addressing information is dependent on the respective configuration, CPI-C applications use the following symbolic names for addressing.

• Symbolic Destination Name
  The Symbolic Destination Name addresses the communication partner. The Symbolic Destination Name comprises two components:

  • partner_LU_name
    addresses the partner UTM application and can be overwritten in the program by Set_Partner_LU-name.

  • TP_name
    addresses the UTM service within the UTM partner application. TP_name is a transaction code and can be overwritten by the program with Set_TP_Name, e.g. TP_name=KDCDISP for the restart.

    The UTM service addressed by this transaction code is started as soon as the program has issued the first Receive call or a Prepare_To_Receive call.

  • Keywords
    further UPIC-specific conversation characteristics can be set with various keywords. A program can overwrite these characteristics with the corresponding CPI-C calls (for example, Set_Conversation_Encryption_Level).

  The Symbolic Destination Name is linked with the “real” addressing (partner_LU_Name, TP_Name) using the upicfile. partner_LU_name, TP_Name and the keywords are just some of the conversation characteristics described below.

• local_name
  The local_name assigns the local application name for the local application. A symbolic name can be assigned for the local_name in the upicfile. UPIC-local values can be set using keywords. This means that the name assigned by the program is independent of the name used in the UTM configuration. A program can overwrite these characteristics with the corresponding CPI-C calls (for example, Specify_Local_Tsel).

A description of how the upicfile is created and how the entries are linked with the UTM configuration is found in section “Coordination with the partner configuration”.
When a upicfile is used, this offers the advantage that ther UTM configuration can be modified (e.g. by moving the UTM server application to another system) without the client programs having to be modified.