The Set_Partner_Host_Name (CMSPHN) call sets the value for the HOSTNAME characteristic of the partner application of the conversation. The call overwrites the value which was assigned using the Initialize_Conversation call. After an Allocate call it may no longer be issued.
This function is one of the additional functions of the UPIC carrier system; it is not a component of the CPI-C interface.
UPIC-Local on Unix, Linux and Windows systems:
The Set_Partner_Host_Name call is not supported for connection over UPIC-L.
UPIC-R using UTM clusters:
The Set_Partner_Host_Name call is not supported if an openUTM cluster is configured.
CMSPHN (conversation_ID, host_name, host_name_length, return_code)
Parameters
--> conversation_ID | Conversation identifier |
--> host_name | Specifies which host name is to be used. |
--> host_name_length | Specifies the length of host_name in bytes. Minimum:1, maximum:64 |
<-- return_code | Result of the function call |
Result ( return_code )
CM_OK
The call is OK
CM_CALL_NOT_SUPPORTED
This call is not supported in UPIC-L. It indicates to the program that a host_name cannot be used because UPIC-L does not need this information as a result of the underlying communication system.
The return code only occurs with UPIC-R if an openUTM cluster has been configured. It indicates to the program that the host_name cannot be modified.
CM_PROGRAM_PARAMETER_CHECK
The value of conversation_ID or host_name_length is invalid.
CM_PROGRAM_STATE_CHECK
The conversation is in the “Initialize” state.
CM_PRODUCT_SPECIFIC_ERROR
The UPIC instance could not be found.
State change
The call does not change the state of the conversation.
Note
The value of host_name is ignored if there is also a value set for ip_address, either in the upicfile or using a Set_Partner_IP_Address call in the UPIC program.
Behavior in the event of errors
CM_PROGRAM_PARAMETER_CHECK
Modify program.
CM_PROGRAM_STATE_CHECK
Modify program.
CM_PRODUCT_SPECIFIC_ERROR
The operating system cannot provide sufficient memory for internal buffers. Check whether the memory requirements of your program are too high and if necessary reboot your system.
CM_CALL_NOT_SUPPORTED
This return code only applies to Unix, Linux and Windows systems.
This is not necessarily an error: The program can take note of this return code and avoid making further calls to set address information.
CM_ENTRY Set_Partner_Host_Name( unsigned char CM_PTR conversation_ID,
unsigned char CM_PTR host_name,
CM_INT32 CM_PTR host_name_lth,
CM_RETURN_CODE CM_PTR return_code )