CPI Communications maintains a set of characteristics for each conversation used by a program. These characteristics are established for each program on a per-conversation basis, and the initial values assigned to the characteristics depend on the program's role in starting the conversation. Table 3 provides a comparison of the conversation characteristics and initial values as set by the Initialize_Conversation, Accept_Conversation, Initialize_For_Incoming, and Accept_Incoming calls. The uppercase values shown in the table are pseudonyms that represent integer values.
The CPI Communications naming conventions for these characteristics, as well as for calls, variables, and characteristic values, are discussed in "Naming Conventions--Calls, Characteristics, Variables, and Values".
In the example in "Establishing a Conversation", the programs used the initial set of program characteristics provided by CPI Communications as defaults. However, CPI Communications provides calls that allow a program to modify and view the conversation characteristics for a particular conversation. Restrictions on when a program can issue one of these calls are discussed in the individual call descriptions in Chapter 4. "Call Reference".
Note: CPI Communications maintains conversation characteristics on a per-conversation basis. Changes to a characteristic will affect only the conversation indicated by the conversation_ID. Changes made to a characteristic do not affect future default values assigned, nor do the changes affect the initial system values (in the case of values derived from the side information).
For example, consider the conversation characteristic that defines what type of conversation the initiating program will have, the conversation_type characteristic. CPI Communications initially sets this characteristic to CM_MAPPED_CONVERSATION and stores this characteristic value for use in maintaining the conversation. A program can issue the Extract_Conversation_Type call to view this value.
A program can issue the Set_Conversation_Type call (after issuing Initialize_Conversation but before issuing Allocate) to change this value. The change remains in effect until the conversation ends or until the program issues another Set_Conversation_Type call.
The Set calls are also used to prevent programs from attempting incorrect syntactic or semantic changes to conversation characteristics. For example, if a program attempts to change the conversation_type after the conversation has already been established (an illegal change), CPI Communications informs the program of its error and disallows the change. Details on this type of checking are provided in the individual call descriptions in Chapter 4. "Call Reference".
Table 3. Characteristics and Their Default Values
| Name of Characteristic | Initialize_Conversation sets it to: | Accept_Conversation sets it to: | Initialize_For_Incoming sets it to: | Accept_Incoming sets it to: |
|---|---|---|---|---|
| AE_qualifier | The application-entity qualifier from side information referenced by sym_dest_name. If a blank sym_dest_name was specified, AE_qualifier will be the null string. | For an OSI TP CRM, the initiating AE_qualifier received on the conversation startup request. For an LU 6.2 CRM, the null string. | Not set | For an OSI TP CRM, the initiating AE_qualifier received on the conversation startup request. For an LU 6.2 CRM, the null string. |
| AE_qualifier_length | The length of AE_qualifier. If a blank sym_dest_name was specified, AE_qualifier_length will be 0. | The length of AE_qualifier | Not set | The length of AE_qualifier |
| AE_qualifier_format | The format of AE_qualifier. If a blank sym_dest_name was specified, AE_qualifier_format will not be meaningful. | For an OSI TP CRM, the format of AE_qualifier. For an LU 6.2 CRM, AE_qualifier_format is not set. | Not set | For an OSI TP CRM, the format of AE_qualifier. For an LU 6.2 CRM, AE_qualifier_format is not set. |
| allocate_confirm | CM_ALLOCATE_NO_CONFIRM | Not applicable | Not applicable | Not applicable |
| AP_title | The application-process title from side information referenced by sym_dest_name. If a blank sym_dest_name was specified, AP_title will be the null string. | For an OSI TP CRM, the initiating AP_title received on the conversation startup request. For an LU 6.2 CRM, the null string. | Not set | For an OSI TP CRM, the initiating AP_title received on the conversation startup request. For an LU 6.2 CRM, the null string. |
| AP_title_length | The length of AP_title. If a blank sym_dest_name was specified, AP_title_length will be 0. | The length of AP_title | Not set | The length of AP_title |
| AP_title_format | The format of AP_title. If a blank sym_dest_name was specified, AP_title_format will not be meaningful. | For an OSI TP CRM, the format of AP_title. For an LU 6.2 CRM, AP_title_format_ is not set. | Not set | For an OSI TP CRM, the format of AP_title. For an LU 6.2 CRM, AP_title_format_ is not set. |
| application_context_name | The application context name from side information referenced by sym_dest_name. If a blank sym_dest_name was specified, application_context_name will be the null string. | For an OSI TP CRM, the initiating application_context_name received on the conversation startup request. For an LU 6.2 CRM, the null string. | Not set | For an OSI TP CRM, the initiating application_context_name received on the conversation startup request. For an LU 6.2 CRM, the null string. |
| application_context_name_length | The length of application_context_name. If a blank sym_dest_name was specified, application_context_name will be 0. | The length of application_context_name | Not set | The length of application_context_name |
| begin_transaction | CM_BEGIN_IMPLICIT | Not applicable | Not applicable | Not applicable |
| confirmation_urgency | CM_CONFIRMATION_URGENT | CM_CONFIRMATION_URGENT | CM_CONFIRMATION_URGENT | Not changed by Accept_Incoming |
| context_ID | Not set | The context_ID of the newly created context | Not set | The context_ID of the newly created context |
| context_ID_length | Not set | The length of context_ID | Not set | The length of context_ID |
| conversation_security_type | The security type from side information referenced by sym_dest_name. If a blank sym_dest_name was specified, conversation_security_type will be CM_SECURITY_SAME. | Not applicable | Not applicable | Not applicable |
| conversation_state | CM_INITIALIZE_STATE | For half-duplex conversations, CM_RECEIVE_STATE. For full-duplex conversations, CM_SEND_RECEIVE_STATE. | CM_INITIALIZE_INCOMING_STATE | For half-duplex conversations, CM_RECEIVE_STATE. For full-duplex conversations, CM_SEND_RECEIVE_STATE. |
| conversation_type | CM_MAPPED_CONVERSATION | CM_MAPPED_CONVERSATION if the CRM type is OSI TP, or the value received on the conversation startup request if the CRM type is LU 6.2. | CM_MAPPED_CONVERSATION | The value received on the conversation startup request if the CRM type is LU 6.2. Not changed if the CRM type is OSI TP. |
| deallocate_type | CM_DEALLOCATE_SYNC_LEVEL | CM_DEALLOCATE_SYNC_LEVEL | CM_DEALLOCATE_SYNC_LEVEL | Not changed by Accept_Incoming |
| directory_encoding | The directory_encoding referenced by sym_dest_name. If a blank sym_dest_name was specified or the side information entry did not contain a directory_encoding value, directory_encoding will be set to CM_DEFAULT_ENCODING. | Not applicable | Not set | Not applicable |
| directory_syntax | The directory_syntax referenced by sym_dest_name. If a blank sym_dest_name was specified or the side information entry did not contain a directory_syntax value, directory_syntax will be set to CM_DEFAULT_SYNTAX. | Not applicable | Not set | Not applicable |
| error_direction | CM_RECEIVE_ERROR | CM_RECEIVE_ERROR | CM_RECEIVE_ERROR | Not changed by Accept_Incoming |
| fill | CM_FILL_LL | CM_FILL_LL | CM_FILL_LL | Not changed by Accept_Incoming |
| initialization_data | Null | The value received on the conversation startup request | Null | The value received on the conversation startup request |
| initialization_data_length | 0 | The length of the initialization data received on the conversation startup request | 0 | The length of the initialization data received on the conversation startup request |
| log_data | Null | Null | Null | Not changed by Accept_Incoming |
| join_transaction | Not set | CM_JOIN_IMPLICIT | CM_JOIN_IMPLICIT | Not changed by Accept_Incoming |
| log_data_length | 0 | 0 | 0 | Not changed by Accept_Incoming |
| map_name | Null | Null | Null | Not changed by Accept_Incoming |
| map_name_length | 0 | 0 | 0 | Not changed by Accept_Incoming |
| mode_name | The mode name from side information referenced by sym_dest_name. If a blank sym_dest_name was specified, mode_name will be the null string. | The mode name for the logical connection on which the conversation startup request arrived | Not set | The mode name for the logical connection on which the conversation startup request arrived |
| mode_name_length | The length of mode_name. If a blank sym_dest_name was specified, mode_name_length will be 0. | The length of mode_name | Not set | The length of mode_name |
| partner_ID | The distinguished_name referenced by sym_dest_name. If a blank sym_dest_name was specified or the side information entry did not contain a distinguished_name, partner_ID will be the null string. | A program binding containing all available destination information on the partner program. | Not set | A program binding containing all available destination information on the partner program. |
| partner_ID_length | The length of partner_ID. If partner_ID is null, partner_ID_length will be 0. | The length of partner_ID. | Not set | The length of partner_ID. |
| partner_ID_type | CM_DISTINGUISHED_NAME | CM_PROGRAM_BINDING | Not set | CM_PROGRAM_BINDING |
| partner_ID_scope | CM_EXPLICIT | Not applicable | Not set | Not applicable |
| partner_LU_name | The partner LU name from side information referenced by sym_dest_name. If a blank sym_dest_name was specified, partner_LU_name will be a single blank. | For an LU 6.2 CRM, the partner LU name for the logical connection on which the conversation startup request arrived. For an OSI TP CRM, partner_LU_name is a single blank. | Not set | For an LU 6.2 CRM, the partner LU name for the logical connection on which the conversation startup request arrived. For an OSI TP CRM, partner_LU_name is a single blank. |
| partner_LU_name_length | The length of partner_LU_name. If a blank sym_dest_name was specified, partner_LU_name_length will be 1. | The length of partner_LU_name | Not set | The length of partner_LU_name |
| prepare_data_permitted | CM_PREPARE_DATA_NOT_PERMITTED | Not applicable | Not applicable | Not applicable |
| prepare_to_receive_type | CM_PREP_TO_RECEIVE_SYNC_LEVEL | CM_PREP_TO_RECEIVE_SYNC_LEVEL | CM_PREP_TO_RECEIVE_SYNC_LEVEL | Not changed by Accept_Incoming |
| processing_mode | CM_BLOCKING | CM_BLOCKING | CM_BLOCKING | Not changed by Accept_Incoming |
| receive_type | CM_RECEIVE_AND_WAIT | CM_RECEIVE_AND_WAIT | CM_RECEIVE_AND_WAIT | Not changed by Accept_Incoming |
| return_control | CM_WHEN_SESSION_ALLOCATED | Not applicable | Not applicable | Not applicable |
| security_password | The security password from side information referenced by sym_dest_name. If a blank sym_dest_name was specified, security_password will be the null string. | Not applicable | Not applicable | Not applicable |
| security_password_length | The length of security_password. If a blank sym_dest_name was specified, security_password_length will be 0. | Not applicable | Not applicable | Not applicable |
| security_user_ID | The security user ID from side information referenced by sym_dest_name. If a blank sym_dest_name was specified, security_user_ID will be the null string. | The value received on the conversation startup request | Not set | The value received on the conversation startup request |
| security_user_ID_length | The length of security_user_ID. If a blank sym_dest_name was specified, security_user_ID_length will be 0. | The length of security_user_ID | Not set | The length of security_user_ID |
| send_receive_mode | CM_HALF_DUPLEX | The value received in the conversation startup request | Not set | The value received in the conversation startup request |
| send_type | CM_BUFFER_DATA | CM_BUFFER_DATA | CM_BUFFER_DATA | Not changed by Accept_Incoming |
| sync_level | CM_NONE | The value received on the conversation startup request | Not set | The value received on the conversation startup request |
| TP_name | The program name from side information referenced by sym_dest_name. If a blank sym_dest_name was specified, TP_name will be a single blank. | The value received on the conversation startup request | Not set | The value received on the conversation startup request |
| TP_name_length | The length of TP_name. If a blank sym_dest_name was specified, TP_name_length will be 1. | The length of TP_name | Not set | The length of TP_name |
| transaction_control | CM_CHAINED_TRANSACTIONS | For an OSI TP CRM, the value received on the conversation startup request. For an LU 6.2 CRM, CM_CHAINED_TRANSACTIONS. | Not set | For an OSI TP CRM, the value received on the conversation startup request. For an LU 6.2 CRM, CM_CHAINED_TRANSACTIONS. |
Some conversation characteristic values are meaningful only for a particular CRM type. For example, an error_direction value of CM_SEND_ERROR has meaning only for an LU 6.2 CRM. On the other hand, a sync_level value of CM_NONE paired with a deallocate_type value of CM_DEALLOCATE_CONFIRM has meaning only for an OSI TP CRM. These CRM-type-sensitive characteristic values and value pairs are listed below:
CPI Communications considers a conversation to be using a particular CRM type if either one of the following events occurs:
When the conversation is using a particular CRM type, the implications are:
For example, suppose a program has successfully set the allocate_confirm characteristic on a conversation to CM_ALLOCATE_CONFIRM, using the Set_Allocate_Confirm call. CPI Communications now considers this conversation to be using an OSI TP CRM. If the program then issues a Set_Error_Direction call on the conversation with error_direction set to CM_SEND_ERROR, the program will receive a CM_PROGRAM_PARAMETER_CHECK return code.
Details on this type of checking are provided in the individual call descriptions in Chapter 4. "Call Reference".
If a conversation is using one CRM type and complete destination information is available for both CRM types, the Allocate call will try to establish a logical connection using only the destination information for the CRM type being used.
Table 4 lists the values of conversation
characteristics that are not applicable to a
half-duplex conversation,
a conversation with send_receive_mode
set to CM_HALF_DUPLEX.
Table 5 lists the values of conversation
characteristics that are not applicable to a full-duplex
conversation,
a conversation with send_receive_mode set to
CM_FULL_DUPLEX.
Table 4. Conversation Characteristic Values that Cannot Be Set for Half-Duplex Conversations
| Characteristic Name | Inapplicable Values |
|---|---|
| sync_level | CM_SYNC_POINT_NO_CONFIRM (for conversations using an LU 6.2 CRM only) |
Table 5. Conversation Characteristic Values that Cannot Be Set for Full-Duplex Conversations
| Characteristic Name | Inapplicable Values |
|---|---|
| confirmation_urgency | all values |
| deallocate_type | CM_DEALLOCATE_CONFIRM (for conversations using an LU 6.2 CRM only) |
| error_direction | all values |
| prepare_to_receive_type | all values |
| processing_mode | all values |
| send_type | CM_SEND_AND_CONFIRM |
| CM_SEND_AND_PREP_TO_RECEIVE | |
| sync_level | CM_CONFIRM |
| CM_SYNC_POINT |
On a conversation with a particular send-receive mode:
The following calls cannot be issued on full-duplex conversations and will receive a CM_PROGRAM_PARAMETER_CHECK return code on a full-duplex conversation:
Some conversation characteristics affect only the function of the local program; the remote program is not aware of their settings. An example of this kind of conversation characteristic is receive_type. Other conversation characteristics, however, are transmitted to the remote program or CRM and, thus, affect both ends of the conversation. For example, the local CRM transmits the TP_name characteristic to the remote CRM as part of the conversation startup process.
When an LU 6.2 CRM is used, CPI Communications requires that these transmitted characteristics be encoded as EBCDIC characters. For this reason, CPI Communications automatically converts these characteristics to EBCDIC when they are used as parameters on CPI Communications calls on non-EBCDIC systems. The conversion of characteristics not in character set 00640 is implementation dependent (see Table 61). When an OSI TP CRM is used, the transfer syntax is negotiated by the underlying support. CPI Communications automatically converts these characteristics to the transfer syntax when they are used as parameters on CPI Communications calls.
This means programmers can use the native encoding of the local system when specifying these characteristics on Set calls. Likewise, when these characteristics are returned by Extract calls, they are represented in the local system's native encoding.
The following conversation characteristics may be automatically converted by CPI Communications: