Initialize_Conversation

The Initialize_Conversation call (function name cminit) is issued by the invoking program to obtain an 8-byte conversation identifier and to set the initial values for the conversation's characteristics.

CM_ENTRY Initialize_Conversation(
  unsigned char FAR *conversation_ID,  
  unsigned char FAR *sym_dest_name,  
  CM_INT32 FAR *return_code          
);
 

Parameters

conversation_ID

Returned parameter. Specifies the identifier for the conversation. It is used by subsequent CPI-C calls.

sym_dest_name

Supplied parameter. Specifies the symbolic destination name—the name associated with a side information entry loaded from the configuration file or defined by Set_CPIC_Side_Information calls.

This parameter is an 8-byte ASCII character string. The allowed characters are as follows:

• Uppercase letters
• Numerals 0 through 9

This parameter can also be set to eight spaces. In this case, the invoking program must issue the following calls before issuing Allocate:

Set_Mode_Name

Set Partner_LU_Name

Set_TP_Name

return_code

The code returned from this call. The valid return codes are listed below.

Return Codes

cm_ok

Primary return code; the call executed successfully.

cm_program_parameter_check

Primary return code; the value specified by sym_dest_name does not match a symbolic destination name in the side information table and is not a space.

cm_product_specific_error

Primary return code; a product-specific error occurred and has been logged in the product's error log.

State Changes

The conversation is in RESET state.

If the return_code is cm_ok, the conversation changes to INITIALIZE state. For other return codes, the conversation state remains unchanged.

Remarks

The initial values are CPI-C defaults or are derived from side information associated with the symbolic destination name. For more information about initial values and side information, see Initial Conversation Characteristics and Side Information.

Initial values can be changed by the Set_ calls.

If the side information contains an invalid value or a Set_ call sets a conversation characteristic to an invalid value, the error is returned on the Allocate call.

If a CPIC application attempts to invoke more than one concurrent conversation, only a single Local APPC LU is used by all conversations. This prevents concurrent conversations across two or more dependent LU6.2 LU's, causing subsequent Initialize_Conversation (CMALLC)calls to wait for the first conversation to be deallocated.

If the CPIC application needs to invoke more than one concurrent conversation, independent LU6.2 must be used between Microsoft® SNA Server and the remote system.

Upon successful execution of this call, CPI-C generates a conversation identifier. This identifier is a required parameter for all other CPI-C calls issued for this conversation by the invoking program.