Set_Conversation_Security_Password - Setting the password

The Set_Conversation_Security_Password (CMSCSP) call sets the values for the conversation characteristics security_password and security_password_length. The security_password is understood as the password of a UTM user ID.

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

The call cannot be issued after an Allocate call.

This function is one of the advanced functions.

Syntax

CMSCSP (conversation_ID, security_password, security_password_length, return_code)

Parameters

--> conversation_ID	Identifier of the conversation.
--> security_password	Password used to establish the conversation. The UTM partner application uses this password together with the user ID in order to check access authorization.The password is specified in the local code used on the machine and converted into EBCDIC if necessary (see section “Code conversion”.
--> security_password_length	Length in bytes of the password specified in security_password.Minimum: 0, maximum: 16If you specify 0 here, security_password is filled with 16 blanks; that is no password is transferred to openUTM for checking access authorization.
<-- 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_password_length is less than 0 or greater than 16.

CM_PRODUCT_SPECIFIC_ERROR

The UPIC instance could not be found.

If the return code is not CM_OK, the security_password and security_password_length characteristics remain unchanged.

State change

None.

Notes

• If a program calls Set_Conversation_Security_Password, a user ID must also be specified. The user ID is set in the program using the Set_Conversation_Security_User_ID call.

• An invalid password is not detected with this call. The partner application checks the password for validity after the conversation is established. If the password is invalid, the partner application issues an error message which is stored in the UPIC log file (see section “UPIC log file”).

• The program is notified of the incorrect password by means of the return code CM_SECURITY_NOT_VALID. This is returned following a CPI-C call issued after the Allocate call.

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 excessive and if necessary reboot your system.

Function declaration: Set_Conversation_Security_Password

CM_ENTRY Set_Conversation_Security_Password (
                             unsigned char  CM_PTR conversation_ID,
                             unsigned char  CM_PTR security_password,
                             CM_INT32       CM_PTR security_password_length,
                             CM_RETURN_CODE CM_PTR return_code )