With KC_UPDATE_IPADDR, while the UTM application is running, you can update the IP addresses stored in the application’s object tables using the IP addresses in the hostname database. The host name database that applies to your system can be the hosts file (on Unix, Linux and Windows systems), the DNS (domain name service) or on BS2000 systems the processor table and the socket host table.
The prerequisite for a comparison on BS2000 systems is that the SOCKET protocol type is generated for the partner or partners.
UTM stores the IP addresses of the following communication partners in the UTM application:
Communication partners that use the socket interface (transport protocol SOCKET) to communicate with the UTM application. These communication partners are generated as clients of the type SOCKET (partner type KC_PTERM).
Only on Unix, Linux and Windows systems: Communication partners that use the transport protocol RFC1006 to communicate with the application. These can be clients with type='APPLI' or 'UPIC-R' (KC_PTERM), LU6.1 partner applications (KC_CON) or OSI TP partner applications (KC_OSI_CON).
For further information on communication using the socket interface and the communication via RFC1006, see the openUTM manual “Generating Applications”.
Each time the application is started, UTM reads the IP addresses of the communication partners from the name service and stores them in the object tables.
If the IP addresses of the relevant communication partners change while the application is running, you can request a dynamic update with KC_UPDATE_IPADDR.
With KC_UPDATE_IPADDR you can carry out the following operations:
update the IP address of a specific communication partner using the name service.
update the IP address of all communication partners using the name service.
In order to check, you can query the IP addresses stored for the communication partners in the UTM application using KC_GET_OBJECT. UTM returns the IP address in the field ip_addr of the data structure of the object type (kc_con_str, kc_osi_con_str or kc_pterm_str).
Execution / period of validity / transaction management / cluster
The job is not subject to transaction management. It takes immediate effect and the IP addresses will already be updated on return to the program unit. The job cannot be undone.
The IP addresses updated with KC_UPDATE_IPADDR remain stored in the UTM application until the application is terminated or until KC_UPDATE_IPADDR is next applied within the current application run.
The following applies in UTM cluster applications (Unix, Linux and Windows systems):
The call applies globally to the cluster, i.e. the IP address update is performed at all currently running node applications.
Data to be supplied
Function of the call | Data to be entered in the | |||
parameter area 1 | identification area | selection area | data area | |
Update IP addresses of a communication partner | subopcode1: | Union kc_id_area with the name or triad of names of the partner | —— | Pointer to the data area in which UTM returns the data structure of the object type with the new IP address. |
Update the IP addresses of all communication partners concerned with the database for the host names | subopcode1: | —— | —— | —— |
Parameter settings | |
Parameter area | |
Field name | Content |
version | KC_ADMI_VERSION_1 |
retcode | KC_RC_NIL |
version_data | KC_VERSION_DATA_11 |
opcode | KC_UPDATE_IPADDR |
KC_PARTNER / KC_ALL | |
KC_CON / KC_OSI_CON / KC_PTERM / KC_NO_TYPE | |
1 / 0 | |
Length of the partner name / 0 | |
select_lth | 0 |
Length of the data area / 0 | |
Partner name / — | |
Selection area | |
— | |
Data structure of the object type / — | |
KDCADMI call |
KDCADMI (¶meter_area, &identification_area, NULL, &data_area) or |
Data returned by UTM | |
Parameter area | |
Field name | Content |
Return code | |
Length of the date returned in the data area / 0 | |
Data structure of the object type/ — | |
subopcode1
In the field subopcode1 you must specify:
KC_PARTNER
if UTM is to update the IP address of a specific communication partner.
Pass the name of the partner in the identification area.
KC_ALL
if UTM is to update the IP addresses of all communication partners that communicate with the UTM application using the appropriate protocol with the data in the host name database.
The appropriate protocol types are:
SOCKET
RFC1006 (Unix, Linux and Windows systems)
obj_type
In the field obj_type you must specify the object type of the communication partner.
With subopcode1=KC_ALL you must specify obj_type=KC_NO_TYPE.
With subopcode1=KC_PARTNER you can make any of the following entries:
KC_PTERM
for partner applications configured as clients of the following type
SOCKET (BS2000 systems)
APPLI, UPIC-R or SOCKET (Unix, Linux and Windows systems)
KC_CON
(Unix, Linux and Windows systems)
for an LU6.1 partner application
KC_OSI_CON
(Unix, Linux and Windows systems)
for an OSI TP partner application
obj_number
In obj_number you must specify the number of objects for which the IP address is to be updated.
for subopcode1=KC_PARTNER you must enter obj_number=1
for subopcode1=KC_ALLyou must enter obj_number=0. UTM will then update the IP address of all communication partners with the relevant configuration.
id_lth
Which entries you must make in the field id_lth depends on the entry in the field subopcode1:
for subopcode1=KC_PARTNER:
you must enter the length of the data structure in id_lth which you pass to UTM in the identification area.for subopcode1=KC_ALL:
you must set id_lth=0.
data_lth
In the field data_lth you enter the length of the data area. You must make the following entries:
for subopcode1=KC_PARTNER:
length of the data structure of the object type in obj_type.for subopcode1=KC_ALL:
data_lth=0.
Identification area
Which data you must supply to the identification area depends on subopcode1.
for subopcode1=KC_PARTNER:
In the identification area, you must supply the union kc_id_area and the name of the communication partner. The entry must identify the partner unambiguously.for obj_type=KC_PTERM you must supply the name triad comprising client name (PTERM), the processor name and the BCAMAPPL name in the kc_long_triple_str structure of the union.
for obj_type=KC_CON on Unix, Linux and Windows systems you must supply the name triad comprising the application name, the processor name and the BCAMAPPL name in the structure kc_long_triple_str of the union.
for obj_type=KC_OSI_CON on Unix, Linux and Windows systems you must enter the name of the connection to the OSI TP partner application in the kc_name8 field of the union.
for subopcode1=KC_ALL you must pass the null pointer.
Data area
What values you enter in the data area depends on subopcode1:
for subopcode1=KC_PARTNER specify the data structure of the object type (kc_con_str, kc_osi_con_str or kc_pterm_str).
for subopcode1=KC_ALL you must pass the null pointer.
retcode
In the field retcode UTM supplies the return code of the call. Beside the return codes listed in section "Return codes", the follow return codes can also occur:
Maincode = KC_MC_REJECTED UTM rejected the call. Subcodes: |
KC_SC_TPROT_NOT_ALLOWED (only on Unix, Linux and Windows systems) This transport protocol is not supported, i.e. no communication partners for communication via SOCKET are generated in the application. |
KC_SC_SOCKET_ERROR It was not possible to update the IP address(es) due to an error in the communication interface (socket call). |
KC_SC_INVALID_NAME The communication partner specified in the identification area does not exist or it does not use the required transport protocol for communication with UTM. |
KC_SC_NO_IPADDR_FOUND subopcode1=KC_PARTNER: |
KC_SC_AT_LEAST_ONE_OBJ_FAILED The IP addresses have been compared using subopcode1=KC_ALL. However, an error occurred with at least one object. |
KC_SC_NO_GLOB_CHANG_POSSIBLE Only in UTM cluster applications: |
Maincode = KC_MC_RECBUF_FULL Subcode: |
KC_SC_NO_INFO The buffer containing the restart information is full (see openUTM manual “Generating Applications”, KDCDEF control statement MAX, parameter RECBUF). |
Maincode = KC_MC_REJECTED_CURR The call cannot be processed at present. Subcode: |
KC_SC_INVDEF_RUNNING Only in UTM cluster applications: |
data_lth_ret
data_lth_ret contains the length of the data returned by UTM in the data area.
for subopcode1=KC_PARTNER: length of the data returned by UTM in the data area
for subopcode1=KC_ALL: data_lth_ret=0
Data area
For subopcode1=KC_PARTNER UTM returns the data structure of the object type (kc_con_str, kc_osi_con_str or kc_pterm_str) in the data area with the following information:
If the new IP address of the communication partner is an IPv4 address, it is located in the ip_addr field of the data structure and has a length of 15. The ip_v field contains V4.
If the new IP address of the communication partner is an IPv6 address, it is located in the ip_addr_v6 field of the data structure and has a length of 39. The ip_v field contains V6.
The other fields of the data structure do not contain any information.