A program uses the Allocate (CMALLC) call to establish a conversation with a UTM application. The name of the CPI-C program is specified in the preceding Enable_UTM_UPIC call.
CMALLC (conversation_ID, return_code)
Parameters
--> conversation_ID | Identifier of the initialized conversation (supplied by the Initialize call). |
<-- return_code | Result of the function call. |
Result ( return_code )
CM_OK
The call is OK.
CM_ALLOCATE_FAILURE_RETRY
only with UPIC local on Unix, Linux and Windows systems
The conversation cannot be established due to a temporary resource bottleneck. Check the error message for the local UTM application as well.
CM_ALLOCATE_FAILURE_NO_RETRY
Possible causes:
The conversation cannot be established due to an error, e.g. the transport connection to the UTM application could not be set up.
The transport connection was rejected by the UTM end because in the UTM application a TPOOL or PTERM connecting point is defined with ENCRYPTION_LEVEL=1 (or 3, 4, 5), but but the encryption requisites are not met.
The transport connection was rejected by the UTM end because in the UTM application a TPOOL or PTERM connecting point is defined with ENCRYPTION_LEVEL=NONE and the called TAC with ENCRYPTION_LEVEL=2.
CM_OPERATION_INCOMPLETE
The call was interrupted by the expiry of the timer set using Set_Allocate_Timer.
CM_PARAMETER_ERROR
A TAC was not specified in the upicfile or in a Set_TP_Name() call, or the conversation_security_type is CM_SECURITY_PROGRAM and the security_user_ID characteristic is not set.
CM_PROGRAM_STATE_CHECK
The call is not permitted in the current state.
CM_PROGRAM_PARAMETER_CHECK
The value for conversation_ID is invalid.
CM_PRODUCT_SPECIFIC_ERROR
There is a protocol error.
For this conversation, there is an RSA key stored in the
upicfile; this key differs in either content or length from the received RSA key.
CM_SECURITY_NOT_SUPPORTED
The partner application does not support the desired security_type.
A new password has been set, but the partner application with which a conversation has been established does not support password changes for the UPIC-Client.
State change
If the return code is CM_OK, the conversation is established and the program enters the “Send” state.
If the return code is CM_ALLOCATE_FAILURE_RETRY/NO_RETRY or CM_SECURITY_NOT_SUPPORTED, the program enters the “Reset” state.
In all other error situations, the program does not change its state.
Notes
If the UTM application rejects initiation of the service, e.g. due to an invalid transaction code, this is not reported until the next Receive call is issued.
If the specified user ID was not generated in the UTM application, or if an incorrect password or no password was sent for a generated user ID, this is not reported until the next Receive call is issued.
Behavior in the event of errors
CM_ALLOCATE_FAILURE_RETRY
Temporary resource bottleneck has occurred during the conversation.
Initialize_Conversation, followed by the Allocate call.
CM_ALLOCATE_FAILURE_NO_RETRY
Reboot the UTM application or generate the PTERM specified in Enable_UTM_UPIC for openUTM. You may need to install the encryption module as well or change the encryption level.
CM_PARAMETER_ERROR
Add a TAC to the entry for the current sym_dest_name or specify a TAC with the Set_TP_Name call.
CM_PROGRAM_STATE_CHECK
Modify program.
CM_PROGRAM_PARAMETER_CHECK
Modify program.
CM_PRODUCT_SPECIFIC_ERROR
Store either a valid RSA key or no key at all.
Notify the service department and produce diagnostic report
CM_ENTRY Allocate ( unsigned char CM_PTR conversation_ID,
CM_RETURN_CODE CM_PTR return_code)