Initialize_Conversation - Initializing the conversation characteristics

The Initialize_Conversation (CMINIT) call reads the entry specified by the symbolic destination name in the upicfile and initializes the conversation characteristics. The characteristics partner_LU_name, partner_LU_name_lth, TP_name, and TP_name_length are assigned corresponding values from the upicfile. All other conversation characteristics are initialized with default values.

In addition to initializing the conversation characteristics, this call also specifies whether the user data will be converted automatically from ASCII to EBCDIC (or vice versa) during the next Send or Receive calls. Conversion takes place:

• in Unix, Linux and Windows systems, if the identifier HD is placed before the symbolic destination name

• in BS2000 systems, if the identifier SD is placed before the symbolic destination name.

For details see also "Side information for standalone UTM applications".

The call returns an eight-character conversation_ID. This uniquely identifies the conversation and must be used in all subsequent CPI-C calls to address the conversation.

It is possible to change the initial values of the conversation characteristics TP_name, TP_name_length, receive_type and deallocate_type at a later stage. The Set_TP_Name, Set_Receive_Type and Set_Deallocate_Type calls are provided for this purpose. A value changed with a Set call is applicable until the end of the conversation or until a new Set call is issued.

The Set calls are not part of the CPI-C starter set, but are advanced-function calls.

Syntax

CMINIT (conversation_ID, sym_dest_name, return_code)

Parameters

<-- conversation_ID	Identifier assigned to the conversation and returned to the program as a result parameter.
--> sym_dest_name	If you use no upicfile, you must specify 8 blanks for sym_dest_name (“empty sym_dest_name”). If you work with the upicfile, enter the reference to the side information (8-character name). For sym_dest_name you can also specify 8 blanks (“empty sym_dest_name”). In this case the symbolic destination name .DEFAULT is sought in the side information (see "Side information for standalone UTM applications") and the corresponding values are set for partner_LU_name, partner_LU_name_lth, TP_name and TP_name_length. If you are working with the upicfile, you can specify 8 blanks for sym_dest_name (“empty sym_dest_name”).
<-- return_code	Result of the function call.

Result (return_code)

CM_OK

The call is OK.

CM_PROGRAM_PARAMETER_CHECK

• The value of sym_dest_name or local_name (with Enable_UTM_UPIC) is invalid or the specified entry in the upicfile could not be read or is syntactically invalid.

• An attempt (if any) to sign on to or sign off from the transport interface was unsuccessful.

• In sym_dest_name or in local_name (with Enable_UTM_UPIC) an empty name was specified but there is no corresponding default entry in the upicfile or the default entry is invalid.

• Error in the upicfile:
  The CD or ND entries for the specified sym_dest_name are not consecutive or the CD entries for the specified sym_dest_name contain different TACs.

CM_PRODUCT_SPECIFIC_ERROR

• A conversation is already active for this program, or no Enable_UTM_UPIC call has been issued yet.

• The transport interface did not respond as expected.

State change

If the return code is CM_OK, the program enters the “Initialize” state and the conversation characteristics are initialized. Further details can be found in “Conversation characteristics” (CPI-C terms). In all other error conditions, the program does not change its state.

Notes

• The Initialize_Conversation call must be executed by the program before another call is issued for this conversation.

• If the Initialize_Conversation call or the subsequent Set calls of the program supply invalid information for establishing the conversation, errors of a syntactical kind are detected immediately but semantic errors are not detected until the Allocate (CMALLC) call is executed.

• Multiple programs can connect with the same name if CONNECT-MODE=MULTI is defined for the corresponding TPOOL statement.

• With a remote connection:

  • The function may sign the program on to the transport system (e.g.TCP/IP, PCMX, BCAM) using the name of the preceding Enable_UTM_UPIC call. No signing on takes place if the program is already signed on with the same name.

  • Any remaining connection to a partner (except for the partner in the upicfile) is shut down.

• With a local connection (UPIC on Unix, Linux and Windows systems):

  • The function performs the sign-on to the UTM-internal process communication (with the UTM application name from the upicfile) if the program is not yet signed on with the same name. If the program is still signed on with a different name, it is first signed off from the UTM-internal process communication. An existing conversation with this UTM application is hereby implicitly shut down. Only then is the program signed on with the new name.

  • At sign-on to the UTM application, the applifile of the UTM application is read. For this purpose the shell variable UTMPATH, which points to the corresponding UTM directory utmpath, is interpreted. This variable must have been set.

Behavior in the event of errors

CM_PROGRAM_PARAMETER_CHECK

• Create the upicfile or set the environment variable or job variable UPICPATH to the correct values. Check the BCMAP entry in BS2000 systems.

• Enter the current sym_dest_name in the upicfile or check the entry for sym_dest_name for correct syntax.

• With a local connection on Unix, Linux and Windows systems: set the environment variable UTMPATH to the correct values. It is also possible that there is no longer a semaphore available.

• Modify the upicfile: Check and adjust the CD and ND entries, respectively.

CM_PRODUCT_SPECIFIC_ERROR

Modify the program or inform the service department and produce diagnostic report.

Function declaration: Initialize_Conversation

CM_ENTRY Initialize_Conversation ( unsigned char  CM_PTR  conversation_ID,
                                   unsigned char  CM_PTR  sym_dest_name,
                                   CM_RETURN_CODE CM_PTR  return_code)