Side information for standalone UTM applications

Each communication partner is addressed in the client program by its symbolic destination name. This name is specified when a conversation is initialized (in the Initialize_Conversation call).

An entry must be created in the upicfile for every Symbolic Destination Name which is used in the program. Each entry takes up one line in the upicfile.

The entry takes the following form for standalone UTM applications:

SD/HD/ND	symbolic destination name	blank	partner_LU_name	blank	transactioncode	blank	keywords	Z end-of-line character
2 bytes	8 bytes	1 byte	1-73 bytes1	1 byte	1-8 bytes	1 byte
				--- optional ---		--- optional ---

¹For Unix, Linux and Windows systems: With local connection via UPIC local, “partner_LU_name” can only be up to 8 bytes long.

Description of the entry:

• The names specified in the entry must be separated by blanks.
  Exception:
  There must be no blank between the identifiers SD/HD/ND and the symbolic destination name.

• Identifiers SD/HD/ND:
  The line begins with the identifier SD, HD or ND.

  The identifier HD or SD specifies whether or not UPIC is to perform automatic code conversion during sending and receiving of data. For more information on code conversion, see also section “Code conversion”.

  The identifier ND specifies that it is an entry for a list of partner applications. Please refer to section “Side information for list of partner applications” for details.

  HD and SD tags for Unix, Linux, and Windows systems:
          If you specify HD, then an automatic code conversion of the user data is carried out when sending and receiving.
          Data sent to the UTM partner application is converted from the locally used code to EBCDIC.
          Data arriving from the partner application is converted to local code by EBCDIC.
          Enter SD, then no automatic code conversion will be performed.
  Indicator HD and SD for BS2000 systems:
  On BS2000 systems, the tags have the opposite meaning.
      HD means in UPIC on BS2000 systems that no automatic code conversion is performed when sending and receiving data in the local system. HD should always be specified if the client communicates with a UTM application on BS2000 systems (BS2000 - BS2000 coupling).
      SD means that EBCDIC-> ASCII conversion is performed before sending data, and ASCII-> EBCDIC conversion when receiving.
      SD should be specified only for connections to UTM applications on Unix, Linux, or Windows systems.

    The indicator SD / HD in the upicfile can be overwritten with the Set_Convertion() call.

• symbolic destination name
  The symbolic destination name must be precisely eight characters long.

• partner_LU_name
  With connections via UPIC remote, the partner_LU_name can be between 1 and 73 characters long. For partner_LU_name you must specify the symbolic name under which the UTM partner application is known to the communication system.
  With connections via UPIC remote you should always specify the partner_LU_name in two levels (separated by a period) in the format applicationname.processorname. The values for TSEL (=applicationname) and HOSTNAME (=processorname) are derived from the two-part partner_LU_name.

  The following restrictions apply for the name lengths:

  • applicationname: maximum length eight characters

  • processorname: maximum length 64 characters

  BS2000 systems
  You have to specify the partner_LU_name in two parts on BS2000 systems. processorname must then match the BCAM name of the remote computer.

  Example: Specification in the upicfile

  SDsymbdest UTMAPPL1.D123ZE45

  An entry in the upicfile can be overwritten with the Set_Partner_LU_Name call.

  The individual values of a two-level partner_LU_name can be overwritten by entries in the side information file (HOSTNAME=, TSEL=) or by using the calls Set_Partner_Hostname and Set_Partner_Tsel.

  UPIC-L for Unix, Linux and Windows systems:

  With local connection to a UTM application via UPIC-L, the partner name must not exceed 8 characters and must be specified in one level.

• transaction code (optional):
  You can specify the transaction code of a UTM service. The transaction code is between 1 and 8 characters long. The transaction code you specify must have been generated in the UTM partner application (TAC statement) or dynamically configured. Specification of a transaction code in an entry is optional. If it is not specified, the transaction code (name of the service) in the program must be given in the Set_TP_Name call.

  An entry in the upicfile can be overwritten with the Set_TP_Name call.

• keywords (all entries are optional)
  The following keywords can be used to influence the UPIC-specific conversation characteristics (see also section “CPI-C terms”) in the upicfile. The keywords are used to enter addressing information and to specify whether encryption is to be implemented.

  You can enter keywords either after the partner name or after the transaction code. Keywords must be separated from the partner name or transaction code by a space. You can enter as many keywords as you like in any order. When entering more than one keyword, you must use a space to separate them.

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

  If you enter ENCRYPTION-LEVEL=NONE or ENCRYPTION-LEVEL=0 (both have the same effect), the user data is not encrypted. If the UTM application establishes a connection which demands encryption of data then the encryption level is automatically adjusted accordingly. The same happens if UPIC on a connection with ENCRYPTION-LEVEL=NONE calls a TAC which is generated using encryption and UPIC does not send user data when calling the TAC. When UPIC receives encrypted data, the value of the encryption level is automatically increased accordingly.

  If you specify ENCRYPTION-LEVEL=3, 4 or 5 and openUTM can implement this encryption on the connection, all user data of the subsequent conversation is encrypted with the same level before transfer.

  Values 3 to 5 mean:

  3	The user data is encrypted using the AES algorithm. An RSA key with a key length of 1024 bits is used for exchange of the AES key.
  4	The user data is encrypted using the AES algorithm. An RSA key with a key length of 2048 bits is used for exchange of 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 length of 2048 bits. Not available on BS2000

  The conversation is ended if openUTM does not support the specified encryption level.

  The value is ignored if the UTM application cannot implement encryption for one of the following reasons:

  • the software requirements are not met.

  • it does not want to implement encryption because the client partner was generated as ’trusted’.

  UPIC-L (Unix, Linux and Windows systems only): The value of ENCRYPTION-LEVEL is ignored.

  The entry in the upicfile can be overwritten using the Set_Conversation_Encryption_Level call.

  HOSTNAME=hostname

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

  An entry in the upicfile can be overwritten using the Set_Partner_Host_Name call.

  UPIC-L (Unix, Linux and Windows systems only): The value of HOSTNAME is ignored.

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

  You can enter an Internet address in IPv4 or IPv6 format.

  • If the Internet address is specified using 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. x represents a hexadecimal number between 0 and FFFF. The alternative methods of writing IPv6 addresses (e.g. the omission of zeros using :: or IPv6 mapped format) are permitted.

  If an Internet address is entered, the value of HOSTNAME is ignored.

  An entry in the upicfile can be overwritten using the Set_Partner_IP_Address() call.

  UPIC-L (Unix, Linux and Windows systems only): The value for IP-ADDRESS is ignored.

  UPIC on BS2000 systems using CMX as its communication system: The value for IP-ADDRESS is ignored.

  PORT=listener-port

  The port number is only entered for the address format RFC1006. The port number can be a value between 1 and 65535. The port number overwrites the port-number value assigned using Initialize_Conversation. Entering PORT is optional. The value of PORT is used as the port number and not 102.

  An entry in the upicfile can be overwritten using the Set_Partner_Port() call.

  UPIC-L (Unix, Linux and Windows systems only): The value of PORT is ignored.

  UPIC on BS2000 systems using CMX as its communication system: The value for PORT is ignored.

  RSA-KEY=rsa-key

  The public part of the RSA key of the partner application can be entered. If the public key is entered, the UPIC library compares the entered key with the one it received from the UTM partner application on connection setup. If there is a difference between keys, whether it be a change of at least one byte or just a change in length, the connection to is cleared down immediately by the UPIC library. This procedure is used to check whether the key is genuine.

  UPIC-L (Unix, Linux and Windows systems only): The value of RSA-KEY is ignored.

  T-SEL=transport-selector

  The transport selector (T-SEL) of the transport address addresses the partner application within the remote system. It must be the same as the entry in the remote system. The transport selector is a name and can be up to 8 characters long. The specified T-SEL overwrites the value assigned using Initialize_Conversation. The use of T-SEL is optional.

  The entry in the upicfile can be overwritten using the Set_Partner_Tsel call.

  UPIC-L (Unix, Linux and Windows systems only): The value of T-SEL is ignored.

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

  TSEL-FORMAT is the format indicator of the transport selector. The valid formats are:

  
  

  Valid formats for TSEL-FORMAT

  T for TRANSDATA
  E for EBCDIC
  A for ASCII

  
  

  TSEL-FORMAT overwrites the value assigned using Initialize_Conversation. The use of T-SEL-FORMAT is optional.

  The value of TSEL-FORMAT is used. The entry in the upicfile can be overwritten using the Set_Partner_Tsel_Format() call.

  UPIC-L (Unix, Linux and Windows systems only): The value of T-SEL-FORMAT is ignored.

• End-of-line character:
  The character that concludes the entry varies depending on the platform for which the upicfile is created:

  • Windows systems:
    Each line is concluded with a carriage return and line feed (the return key). A semicolon before the carriage return is optional.

  • Unix and Linux systems:
    The line is concluded with a <newline> character (line feed). A semicolon before the <newline> character is optional.

  • BS2000 systems:
    The end of 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

  In BS2000 systems, the next end of line character is also a semicolon. BS2000 editors such as EDT have a different view of lines from UPIC. If a further blank follows the semicolon of line n in the editor and line n+1 starts with SD and ends with a semicolon, UPIC sees a line which starts with " SD" and not with "SD". The "Symbolic Destination Name" in this line is not found.

Defining a DEFAULT server

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

SD/HD/ND	.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 ---

¹For Unix, Linux and Windows systems: With a local connection via UPIC locals, “partner_LU_name” can only be up to 8 bytes long.

With such an entry you define the UTM partner application partner_LU_name as the DEFAULT server. If you specify a transaction code, you also define the associated service as the DEFAULT service. You can call a different service on the DEFAULT server by setting a different transaction code in the program with the Set_TP_Name call (e.g. KDCDISP for the service restart). The specification in Set_TP_Name overwrites the value of transactioncode in the side information entry.

How to pass a list of communication endpoints via the upicfile is described in detail in the chapter Side information for UTM cluster applications.