Set_Partner_IP_Address - Setting the IP address of the partner application

The Set_Partner_IP_Address (CMSPIA) call sets the value for the IP-ADDRESS characteristic of the conversation. The call overwrites the value assigned using Initialize_Conversation call. After the Allocate call, this call can 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_IP_Address() call is not supported for connection over UPIC-L.

UPIC-R using UTM clusters:

The Set_Partner_IP_Address call is not supported if an openUTM cluster is configured.

Syntax

CMSPIA (conversation_ID, ip_address, ip_address_length, return_code)

Parameters

--> conversation_ID	Conversation identifier
--> ip_address	Specifies that an IP address is to be used instead of a hostname characteristic.
--> ip_address_length	Specifies the length of ip_address in bytes. Minimum:0, maximum:64.
<-- return_code	Result of the function call.

Result ( return_code )

CM_OK

The call is OK.

CM_CALL_NOT_SUPPORTED

The function is not supported.

On Unix, Linux and Windows systems, this code is always returned with UPIC-L. It indicates to the program that an ip_address cannot be used because UPIC-L does not need this information as a result of the underlying communication systems.

The return code only occurs with UPIC-R if an openUTM cluster has been configured. It indicates to the program that the ip_address cannot be modified.

The code is returned with UPIC-R for BS2000 systems in the event that the UPIC library on BS2000 is used together with CMX. The CMX communication system used by UPIC-R does not provide any option on BS2000 systems for passing IP addresses for addressing the partner application at the interface.

CM_PROGRAM_PARAMETER_CHECK

The value of conversation_ID or ip_address_length is invalid.

CM_PROGRAM_STATE_CHECK

The conversation is not 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.

Notes

• For IPv4, ip_address is specified using the usual dot notation:

  xxx.xxx.xxx.xxx

  The individual octets xxx are restricted to 3 digits. The contents of the octet are always interpreted as a decimal number. In particular, this means that octets which are padded with leading zeros not interpreted as octal numbers.

• ip_address

  is specified for IPv6 using normal colon notation:

  x:x:x:x:x:x:x:x

  x is a hexadecimal number between 0 and FFFF. The alternative methods of writing IPv6 addresses are permitted (see RFC2373).

  If an embedded IPv4 address in dot notation is specified in the IPv6 address, the above also supplies to the octet for the IPv4 address. The octets are always interpreted as octal numbers.

• If both ip_address and HOST_NAME are set, the value of HOST_NAME is ignored.

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 the internal buffers. Check whether the memory requirements of your program are too high and if necessary reboot your system.

CM_CALL_NOT_SUPPORTED

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

On BS2000 systems, this return code means that the application is connected to UPIC-R and CMX. The program can remember this return code and then no longer requires the Set_Partner_IP_Address and Set_Partner_Port calls.

Function declaration: Set_Partner_IP_Address

CM_Entry Set_Partner_IP_Address ( unsigned char   CM_PTR  conversation_ID,
                                 unsigned char    CM_PTR  ip_address, 
                                 CM_INT32         CM_PTR  ip_address_length,
                                 CM_RETURN_CODE   CM_PTR  return_code )