Set_Mode_Name

The Set_Mode_Name call (function name cmsmn) is issued by the invoking program to specify the mode name for a conversation. This call overrides the system-defined mode name derived from the side information when the Initialize_Conversation call was issued. This call cannot be issued after Allocate has been issued. Issuing this call has no effect on the side information itself.

CM_ENTRY Set_Mode_Name(
  unsigned char FAR *conversation_ID,  
  unsigned char FAR *mode_name,    
  CM_INT32 FAR *mode_name_length,  
  CM_INT32 FAR *return_code        
);

Parameters

conversation_ID
Supplied parameter. Specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation.
mode_name
Supplied parameter. Specifies the starting address of the mode name (the name of a set of networking characteristics defined during configuration). The mode name can contain up to eight ASCII characters. The allowed characters are:

The value of mode_name must match the name of a mode associated with the partner LU during configuration. The mode name cannot be SNASVCMG or CPSVCMG.

mode_name_length
Supplied parameter. Specifies the length of the mode name. The range is from 0 through 8 bytes

If mode_name_length is set to zero, Set_Mode_Name is ignored.

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_state_check
Primary return code; the conversation is not in INITIALIZE state.
cm_program_parameter_check
Primary return code; one of the following occurred:
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 must be in INITIALIZE state.

There is no state change.

Remarks

Specifying an invalid value for mode_name is not detected until Allocate is issued.