Allocate

The Allocate call (function name cmallc) is issued by the invoking program to allocate a conversation with the partner program, using the current conversation characteristics. CPI-C can also allocate a session between the local LU and partner LU if one does not already exist.

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

Parameters

conversation_ID

Supplied parameter. Specifies the conversation identifier. The value of this parameter was returned by Initialize_Conversation.

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_operation_not_accepted

Primary return code; this value indicates that a previous operation on this conversation is incomplete.

cm_operation_incomplete

Primary return code; a nonblocking operation has been started on the conversation but is not complete. The program can issue Wait_For_Conversation to wait for the operation to complete or Cancel_Conversation to cancel the operation and conversation.

cm_parameter_error

Primary return code; one of the following occurred:

• The mode name derived from the side information or set by Set_Mode_Name is not valid.
• The mode name is used by SNA service TPs; the invoking program does not have the authority to use this mode name. An example is SNASVCMG.
• The partner program derived from the side information is an SNA service TP; the local program does not have the privilege required to allocate a conversation to an SNA service TP.
• The partner program is a service TP, which participates in basic conversations, but the conversation is set to CM_MAPPED_CONVERSATION.
• The partner LU name derived from the side information or set by Set_Partner_LU_Name is not valid.

cm_program_parameter_check

Primary return code; the value specified by conversation_ID is not valid, or the address of a variable is invalid.

cm_program_state_check

Primary return code; the conversation is not in INITIALIZE state.

cm_product_specific_error

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

cm_unsuccessful

Primary return code; the conversation's return-control characteristic is set to CM_IMMEDIATE and the local LU did not have an available contention-winner session.

The following return codes can be generated if the conversation's return-control type is set to CM_WHEN_SESSION_ALLOCATED.

cm_allocate_failure_no_retry

Primary return code; the conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the system administrator should examine the error log file. Do not retry the allocation until the error has been corrected.

cm_allocate_failure_retry

Primary return code; the conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation.

State Changes

The conversation must be in INITIALIZE state when Allocate is issued.

State changes, summarized in the following table, are based on the value of the return_code parameter.

Remarks

The type of conversation allocated is based on the conversation type characteristic: mapped or basic.

When the conversation has been allocated by this call, the following conversation characteristics cannot be changed:

• Conversation type
• Mode name
• Partner LU name
• Partner program name
• Return control
• Synchronization level
• Conversation security
• User identifier
• Password

To send the allocation request immediately, the invoking program can issue Flush or Confirm immediately after Allocate. Otherwise, the allocate request accumulates with other data in the local LU's send buffer until the buffer is full.

By issuing Confirm after Allocate, the invoking program can immediately determine whether the allocation was successful (if the conversation synchronization level is set to CM_CONFIRM).

If the partner LU rejects the allocation request generated by Allocate, the error is returned to the invoking program on a subsequent call.