Side information for UTM cluster applications

Every communication partner, including UTM cluster applications is addressed by its symbolic destination name in the client program. This name is specified when a conversation is initialized (Initialize_Conversation call). You must make entries in the upicfile for each symbolic destination name used in the program.

A UTM cluster application is made up of several identical node applications running on the individual nodes of the cluster. To allow a UPIC client to easily access all the node applications of a UTM cluster application, you must configure an openUTM cluster in the upicfile. In doing this, you must observe the following rules.

Rules for configuring an UTM cluster application

• For each symbolic destination name, you must create a separate entry for each node application in the upicfile with the identifier CD. If, for instance, the UTM cluster application is made up of three node applications, you must create three entries using the same symbolic destination name.

• All entries for a given symbolic destination name must follow each other consecutively.

• The entries for a given symbolic destination name differ only in terms of the address specifications for the node (partner_LU_name or, if used, the keywords HOSTNAME and IP-ADDRESS). The specifications for transaction-code and the other keywords must match.

Format of an entry

Each entry occupies one line in the upicfile. An entry takes the following form:

CD	symbolic destination name	blank	partner_LU_name	blank	transaction code	blank	keywords	end-of-line character
2 bytes	8 bytes	1 byte	1-73 bytes	1 byte	1-8 bytes	1 byte
				--- optional ---		--- optional ---

Description of the entry

• The names specified in the entry must be separated by blanks. Exception:No blank is permitted between the CD code and the symbolic destination name.

• CD code: The line starts with the code CD. This code has no effect on automatic code conversion.

• symbolic destination name: The symbolic destination name must be exactly 8 characters long.

  The combination CDsymbolic_destination_name can occur any number of times in the upicfile.

• partner_LU_name: The partner_LU_name can be between 1 and 73 characters in length. The symbolic name under which the UTM partner application is known to the system must be specified for partner_LU_name.

  You should always specify partner_LU_name on two levels in the form applicationname.processorname (separated by a dot). The values for TSEL (=applicationname) and HOSTNAME (=processorname) are derived from the two-level partner_LU_name.

  The following restrictions apply for the name lengths:

applicationname: maximum length eight characters

processorname: maximum length 64 characters

BS2000 systems

On BS2000 systems, you must specify the partner_LU_name with two levels. processorname must then match the BCAM-name of the remote host.

Example: Specification in the upicfile

CDsymbdest UTMAPPL1.D123ZE45

An entry in the upicfile cannot be overwritten by a Set_Partner_LU_Name call. The individual values of a two-level partner_LU_name must not be overwritten in the program. Any such call will be rejected.

• transaction-code (optional specification):
  The transaction code of a UTM service can be specified. The transaction code is a name of up to 8 characters in length. The specified transaction code must have been generated in the UTM partner application (TAC statement) or must have been configured dynamically. Specification of a transaction code in an entry is optional. If this specification is omitted, the transaction code (name of the service) must be specified in the program with the Set_TP_Name call.

  An entry in the upicfile can be overwritten by a Set_TP_Name call.

• Keywords (all specifications optional):

  You can influence the UPIC-specific conversation characteristics (see also “Conversation characteristics” (CPI-C terms)) in the upicfile with the following keywords. You use the keywords to specify the addressing information and specify whether encryption is to be used.You can specify the keywords after the partner name or after the transaction code, separated by blanks in each case. The sequence and number of keywords is arbitrary. Multiple keywords are separated by blanks.

  ENCRYPTION-LEVEL={NONE | 0 |  3 | 4 | 5}:
  ENCRYPTION-LEVEL specifies whether the data for the conversation is to be encrypted or not and what encryption level is to be used.

  If you specify ENCRYPTION-LEVEL=NONE or ENCRYPTION-LEVEL=0 (both have the same effect), the user data is not encrypted. If, however, the UTM application requires the data to be encrypted over a given connection, the encryption level is automatically increased. The same thing happens if UPIC calls a TAC generated with encryption over a connection with ENCRYPTION-LEVEL=NONE and UPIC does not send any user data when calling the TAC. If encrypted data is received, UPIC automatically increases the value for the encryption level.

  If you specify ENCRYPTION-LEVEL= 3, 4 or 5 and openUTM is able to encrypt the data accordingly over the connection, all the user data of the following conversation is transmitted in encrypted form using the same level.

  The values 3 through 5 have the following meanings:

  3	Encryption of the user data using the AES algorithm. An RSA key with a key length of 1024 bits is used to exchange the AES key.
  4	Encryption of the user data using the AES algorithm. An RSA key with a key length of 2048 bits is used to exchange the AES key.
  5	User data are encrypted and authenticated, using the AES/GCM algorithm. The Diffie-Hellman algorithm is used to exchange the AES key with a key length of 2048 bits. Not available on BS2000.

  If openUTM does not support the specified encryption level, the conversation is terminated.

  The value is ignored if a UTM application cannot perform encryption because

  • the software requirements are not met

  • it does not wish to perform encryption because the client partner has been generated as trusted

  HOSTNAME=hostname

  The hostname is the processor name and can be up to 64 characters in length. The hostname overwrites the value assigned with Initialize_Conversation.

  An entry in the upicfile cannot be overwritten by a Set_Partner_Host_Name call.

  IP-ADDRESS=nnn.nnn.nnn.nnn (IPv4) or = x: x: x: x: x: x: x: x (IPv6).

  An Internet address can be specified in IPv4 and IPv6 format.

  • If the Internet address is specified using the traditional dot notation, it is interpreted as an IPv4 address.

  • If the Internet address is specified in the form x: x: x: x: x: x: x: x, it is interpreted as an IPv6 address. In this notation, x is a hexadecimal number between 0 and FFFF. The alternative notations for IPv6 addresses (e.g. the omission of zeros using :: or IPv6 mapped format) are permitted.

  If an Internet address is specified, the value of HOSTNAME is ignored. An entry in the upicfile cannot be overwritten by a Set_Partner_IP_Address call.

  UPIC on BS2000 systems with CMX as the communication system

  The value for IP-ADDRESS is ignored.

  PORT=listener-port

  The port number is only specified for the address format RFC1006. The port number can assume a value of 1 through 65535. This port number overwrites the value for the port number assigned with Initialize_Conversation. The PORT specification is optional.

  The value of PORT is used as the port number instead of 102.

  An entry in the upicfile can be overwritten by a Set_Partner_Port call.

  UPIC on BS2000 systems with CMX as the communication system

  The value of PORT is ignored.

• RSA-KEY=rsa-key

  The public part of the RSA key of the partner application can be specified. If the public key is specified, the UPIC the library compares the specified key with the key it receives from the UTM partner application when the connection is established. If the two keys differ in at least one byte or even just in length, the connection is immediately cleared again by the UPIC library. This procedure allows the genuineness of the key to be checked.

  T-SEL=transport-selector

  The transport selector (T-SEL) of the transport address addresses the partner application within the remote system. It must match the specifications in the remote system. The transaction selector is a name of up to 8 characters in length. The T-SEL specified overwrites the value assigned with Initialize_Conversation. The T-SEL specification is optional.

  The entry in the upicfile can be overwritten by a Set_Partner_Tsel call.

  T-SEL-FORMAT={T | E | A }

  T-SEL-FORMAT is the format indicator of the transport selector. The valid formats are as follows:

  
  

  Valid formats for TSEL-FORMAT

  T for TRANSDATA
  E for EBCDIC
  A for ASCII

  
  

  T-SEL-FORMAT overwrites the value assigned with Initialize_Conversation. The T-SEL-FORMAT specification is optional.

  The value of TSEL-FORMAT is used. The entry in the upicfile can be overwritten by a Set_Partner_Tsel_Format call.

• CONVERTION={IMPLICIT | NO}CONVERTION=IMPLICIT specifies that automatic code conversion is performed on the user data on sending and receiving. For information on code conversion, see also the section “Code conversion”.

  If you do not specify CONVERTION= or if you specify CONVERTION=NO, no automatic conversion is performed.

• End of line character: The character used to terminate the entry differs for the various platforms for which the upicfile is created:

  • Windows systems:
    Lines are terminated by a carriage return and line feed (Return key). A semicolon can be optionally inserted in front of the carriage return character.

  • Unix and Linux systems:
    Lines are terminated with a <newline> character (linefeed). A semicolon can be optionally inserted in front of the <newline> character.

  • BS2000 systems:
    The end of the line is represented by a semicolon (;). No spaces are permitted after this.

  If there is a semicolon in a line (contents of the side information entry), UPIC treats this as the end of the line and interprets the rest of the line as a new line (until the next end of line character).

  BS2000

  Note that in BS2000 systems, the next end of line character is also a semicolon. BS2000 editors such as EDT regard lines differently from UPIC. If the semicolon in line n in the editor

  • is followed by another blank and

  • line n+1 starts with CD and ends with a semicolon,

  UPIC sees a line beginning with " CD" and not with "CD". The "symbolic destination name" in this line is not found.

Example

Two symbolic destination names (service1 and service2) are to be configured for one UTM cluster application. The UTM cluster application is made up of three node applications on the hosts CLNODE01, CLNODE02 and CLNODE03. In addition, the upicfile contains a further entry for a standalone UTM application UTMAPPL2.

The entries could, for instance, be as follows:

Example of an upicfile

* entries for UTM cluster application UTMAPPL1
CDservice1 UTMAPPL1.CLNODE01 TAC1
CDservice1 UTMAPPL1.CLNODE02 TAC1
CDservice1 UTMAPPL1.CLNODE03 TAC1
* entry for stand-alone application UTMAPPL2
SDservice2 UTMAPPL2.D123S234 TAC4

The transaction code TAC1 can be overwritten in the program using Set_TP_Name, thus allowing other TACs to be addressed. In addition, it is possible to configure further standalone UTM applications (with the prefix SD, HD or ND). These entries must, however, precede or follow the entries for the UTM cluster application described above.

Defining the DEFAULT server

You can define a DEFAULT server or a DEFAULT service for your client application (see also the section “Default server and DEFAULT name of a client”). A client program is connected to the DEFAULT server/service if an empty name is passed as the symbolic destination name in the program. In the DEFAULT entry, you specify the value .DEFAULT in place of the symbolic destination name. The DEFAULT server entry must therefore have the following format:

CD	.DEFAULT	blank	partner_LU_name	blank	transaction code	blank	keywords	end-of line character
2 bytes		1 byte	1-73 bytes1	1 byte	1-8 bytes	1 byte
				--- optional ---		--- optional ---

An entry such as this defines the UTM partner application partner_LU_name as the DEFAULT server. If you enter a transaction code, you also define the associated service as the DEFAULT service. You can call a different service on the DEFAULT server if you use the Set_TP_Name() call in the program to set a different transaction code (e.g. KDCDISP for a service restart). The specification in Set_TP_Name overwrites the value of transaction-code in the side information entry.