SNAP-IX CPI-C Programmer's Guide - 3.51 Set_Mode

3.51 Set_Mode_Name (cmsmn)

The Set_Mode_Name call 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 the Allocate has been issued. Issuing this call has no effect on the side information itself.

3.51.1 Function Call

     void cmsmn (
                 unsigned char CM_PTR       conversation_ID,
                 unsigned char CM_PTR       mode_name,
                 CM_INT32 CM_PTR            mode_name_length,
                 CM_RETURN_CODE CM_PTR      return_code
                );

3.51.2 Function Call for Java CPI-C

     public native void cmsmn (
                                byte[]          conversation_ID,
                                byte[]          mode_name,
                                CPICLength      mode_name_length,
                                CPICReturnCode  return_code
                              );

3.51.3 Supplied Parameters

The supplied parameters are:

conversation_ID

This is the identifier for the conversation. The value of this parameter is returned by the Initialize_Conversation call.

mode_name

This 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 following characters are allowed:

Uppercase letters
Numerals 0-9

The value of mode_name must match the name of a mode associated with the partner LU during configuration.

For a mapped conversation, the mode name SNASVCMG is reserved for SNA internal use; the Allocate call will fail if you use this name. You are recommended not to use SNASVCMG in a basic conversation, or CPSVCMG (another SNA reserved name) in either type of conversation.

mode_name_length

This parameter specifies the length of the mode name.

The range for this value is 0-8 bytes.

If mode_name_length is set to 0 (zero), the Set_Mode_Name call is ignored.

3.51.4 Returned Parameters

After the verb executes, SNAP-IX returns the following parameters:

return_code

Possible values are:

CM_OK

The call executed successfully.

CM_PROGRAM_STATE_CHECK

The conversation is not in Initialize state.

CM_PROGRAM_PARAMETER_CHECK

One of the following has occurred:

The value specified by conversation_ID is not valid
The value specified by mode_name_length is out of range (greater than 8 or less than 0).

CM_PRODUCT_SPECIFIC_ERROR

For an explanation of this return code, see Common Return Codes.

3.51.5 State When Issued

The conversation must be in Initialize state.

3.51.6 State Change

There is no state change.

3.51.7 Usage Notes

If the return_code is not CM_OK , the mode_name conversation characteristic is unchanged.

Specifying a value for mode_name that is not valid (a name that is not permitted by the configuration file) is not detected until the Allocate call is issued.