SNAP-IX CPI-C Programmer's Guide - 3.42 Set_Conversation_Security_User

3.42 Set_Conversation_Security_User_ID (cmscsu)

The Set_Conversation_Security_User_ID call is issued by the invoking program to specify the user ID required to access to the invoked program. It overrides the initial user ID from the side information specified by the Initialize_Conversation call.

This call cannot be issued after the Allocate call has been issued. This call is not valid if the conversation security type is CM_SECURITY_NONE (Solaris systems)or XC_SECURITY_NONE (Windows systems).

3.42.1 Function Call

     void cmscsu (
                  unsigned char CM_PTR      conversation_ID,
                  unsigned char CM_PTR      security_user_ID,
                  CM_INT32 CM_PTR           security_user_ID_length,
                  CM_RETURN_CODE CM_PTR     return_code
                 );

3.42.2 Function Call for Java CPI-C

     public native void cmscsu (
                                 byte[]          conversation_ID,
                                 byte[]          security_user_ID
                                 CPICLength      security_user_ID_length,
                                 CPICReturnCode  return_code
                               );

3.42.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.

security_user_ID

This specifies the user ID required to access the partner program. This parameter is a character string of 1-10 characters (Solaris systems), or 1-8 characters (Windows systems), and is case-sensitive.

The following characters are allowed:

Uppercase and lowercase letters
Numerals 0-9
Special characters $, #, @, and . (period)

security_user_ID_length

This specifies the length of security_user_ID. This range for this value is 1-10 characters (Solaris systems), or 1-8 characters (Windows systems). If the length is 0 (zero), the security_user_ID parameter is ignored; this is equivalent to setting security_user_ID to a null string.

3.42.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_PARAMETER_CHECK

One of the following has occurred:

The value specified by conversation_ID is not valid.
The value specified by security_user_ID_length is out of range.

CM_PROGRAM_STATE_CHECK

One of the following has occurred:

The conversation is not in Initialize state.
The conversation's security type is set to CM_SECURITY_NONE.

CM_PRODUCT_SPECIFIC_ERROR

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

3.42.5 State When Issued

The conversation must be in Initialize state.

3.42.6 State Change

There is no state change.

3.42.7 Usage Notes

If the return code is not CM_OK, the security_user_ID and security_user_ID_length conversation characteristics are unchanged.

A user ID that is not valid is not detected until the allocation request, generated by the Allocate call, is sent to the partner LU. The error is returned to the invoking program on a subsequent call.