Set_Conversation_Security_New_Password - Setting new password

The Set_Conversation_Security_New_Password (CMSCSN) call sets the value for the conversation characteristics security_new_password and security_new_password_length. The ssecurity_new_password is understood as the new password of a UTM user ID.

A program can only specify a new 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 additional functions of the UPIC carrier system; it is not a component of the CPI-C interface.

Syntax

CMSCSN (conversation_ID, security_new_password, security_new_password_length, return_code)

Parameters

--> conversation_ID	Identifier of the conversation.
--> security_new_password	Password which is to replace the old password. The password must consist of characters which are allowed in the UTM partner application, see openUTM manual “Generating Applications”, USER statement. The UTM partner application uses this new password to replace the old password following a valid access authorization with the old password.
--> security_new_password_length	Length in bytes of the password specified in security_new_password. Minimum: 0, maximum: 16 If you specify 0 here, security_new_password is filled with 16 spaces, i.e. UTM does not alter the existing password.
<-- 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 value of conversation_ID is invalid, the value in security_new_password_length is less than 0 or greater than 16, or the new password only comprises blanks.

CM_PRODUCT_SPECIFIC_ERROR

The UPIC instance could not be found.

If the return code is not CM_OK, the security_new_password and security_new_password_length characteristics remain unchanged.

State change

The call does not change the state of the conversation.

Notes

• If a program calls Set_Conversation_Security_New_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.

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

• If only blanks were specified for the new password, this means the UTM application should reset the password, that is the user no longer requires a password. However, this is not permitted from the client, so consequently the error CM_PROGRAM_PARAMETER_CHECK is returned.

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_New_Password

CM_ENTRY Set_Conversation_Security_New_Password (
                         unsigned char  CM_PTR conversation_ID,
                         unsigned char  CM_PTR security_new_password, 
                         CM_INT32       CM_PTR security_new_password_length,
                         CM_RETURN_CODE CM_PTR return_code )