Set_Conversation_Security_User_ID - Setting the UTM user ID

The Set_Conversation_Security_User_ID (CMSCSU) call sets the values for the conversation characteristics security_user_ID and security_user_ID_length.
The security_user_ID is understood as a user ID of a UTM application.

A program can only specify a user ID if the security_type characteristic is set to CM_SECURITY_PROGRAM.

The call must not be executed after the Allocate call.

This function is one of the advanced functions.

Syntax

CMSCSU (conversation_ID, security_user_ID, security_user_ID_length, return_code)

Parameters

--> conversation_ID	Identifier of the conversation.
--> security_user_ID	User ID used to establish the conversation. The UTM partner application uses the user ID and possibly the password to check access authorization. The partner application may also use the user ID for logging or accounting purposes.
--> security_user_ID_length	Length in bytes of the user ID specified in security_user_ID. Minimum: 0, maximum: 8 If 0 is specified here, despite the fact that security_type is set to CM_SECURITY_PROGRAM in the Set_Conversation_Security_Type call, a connection is not set up to UTM (error in the Allocate call).
<-- return_code	Result of the function call.

Result ( return_code )

CM_OK

The call is OK.

CM_PROGRAM_STATE_CHECK

The conversation is not in the “Initialize” state or security_type is not set to CM_SECURITY_PROGRAM.

CM_PROGRAM_PARAMETER_CHECK

The conversation_ID is invalid or the value in security_user_ID_length is less than 0 or greater than 8.

CM_PRODUCT_SPECIFIC_ERROR

The UPIC instance could not be found.

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

State change

None.

Notes

• The call does not check the user ID for validity. This is carried out by the partner application after the conversation is established. If the user ID is invalid, the UTM server rejects the conversation

• The program is notified of an invalid user ID or an incorrect password by means of the return code CM_SECURITY_NOT_VALID. This is returned following a Receive call issued after the Allocate call.

• If the security_type parameter is set to CM_SECURITY_NONE in the Set_Conversation_Security_Type call, the Set_Conversation_Security_User_ID call is not permitted.

Behavior in the event of errors

CM_PROGRAM_PARAMETER_CHECK

Modify program.

CM_PRODUCT_SPECIFIC_ERROR

The operating system cannot provide sufficient memory for the internal buffers. Check whether the memory requirements of your program are too high and if necessary reboot your system.

Function declaration: Set_ Conversation_Security_User_ID

CM_ENTRY   Set_Conversation_Security_User_ID (
                       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 )