Registered Name Service

Overview

The UPSTREAM registered name service provides these optional function:

Registered Names: A Client (workstation/server) can be assigned a “Registered Name” that is independent of its network address (Registered Names).
Automatic Software Upgrades: The UPSTREAM software installed on a client can be automatically upgraded when a new version becomes available (Automatic Software Upgrades).

Registered Names

The registered name service allows an UPSTREAM Client to be assigned an arbitrary unique “registered” name that is independent of its TCP/IP network address or DNS Name. This name can then be used to refer to that Client in UPSTREAM operations, most notably in USTBATCH, but also in any other situation where the TCP/IP network address (TCPTARG), or DNS name (DNSNAME) would ordinarily be used.

The utilization of a registered name allows you to setup your USTBATCH jobs independently of your network addressing and configuration. Instead of hard-coding network addressing information in your USTBATCH jobs, you can refer to the target Client by its registered name. This is especially useful in environments where the network addressing is dynamically assigned via DHCP and may frequently change.

Naming

A registered name can be up to 16 characters in length and can include blanks. Care must be taken to ensure that the names are unique across all Clients.

Important

Recommendation: Use names that are meaningful, e.g., “Payroll Server”. If the registered name service is used across a large number of servers or workstations, the allocation of registered names should, ideally, be controlled centrally.

Assigning the Names

A registered name can be assigned during the initial configuration of the Client software. It can also be assigned at any time after the Client software has been installed. This is the recommended method as it validates that communications between the Client and the z/OS Storage Server are functioning correctly. When assigning the name using the Client Configurator, the Name field defaults to &SYSNAME. This causes registration to use the machines host name. For Linux OS on IBM Z systems, selecting Use VM Name uses the z/VM virtual machine name instead of the machines host name or a user defined name. If manually editing the TARGETNAME field in the upstream.cfg file, specify &VMNAME to use the z/VM virtual machine name. Specify $SYSNAME to use the machines host name. See the UPSTREAM Client Guide for more details on assigning registered names through the Client software.

Registered names can also be assigned using the TSO/ISPF dialog on the UPSTREAM z/OS Storage Server (see Maintaining the Table).

Registering the Names

For a registered name to be recognized and usable by UPSTREAM, the Client must first “register” that name with the z/OS Storage Server. Although this can be done manually (see Maintaining the Table), the recommended method is to configure your Client to do an automatic registration. For this to work correctly, the Client must be enabled for remote functions (see the UPSTREAM Client Guide).

When the UPSTREAM software is started on the Client it will automatically contact the z/OS Storage Server and transmit its registered name, together with the network address at which it is currently located. You can also request that the Client software periodically re-transmit this registered name and network address (see the UPSTREAM Client Guide for more details).

Details of all Clients that are currently “registered” with the z/OS Storage Server are maintained in a table in the CATALOG repository file (The UPSTREAM Repository). This table is also kept in memory for quick access.

For each record in the table, a timestamp is maintained showing the last time that the registered name was updated or referenced. If a given registered name has not been updated or referenced within 90 days it is automatically deleted from the table.

Contents of the table can be reported on at any time with the RPTYPE=REGISTRY option of USTRPORT (see REGISTRY). This information can also be viewed and modified through the either Client interface (see the UPSTREAM Client Guide), or the TSO/ISPF dialog. See Maintaining the Table.

Using the Registered Name

Once registered, an Client's registered name can be referenced by USTBATCH (or any other UPSTREAM operation) using the TARGNAME parameter instead of the usual TCPTARG or DNSNAME parameters.

The registered name table is searched for a match to the specified TARGNAME.

If a match is found, the corresponding current network address and PORT number stored in the table for that Client is used. As a check, UPSTREAM first verifies that the registered name in the table matches that of the Client at the network address indicated by the table entry.
If a match to TARGNAME is not found in the registered name table, the requested operation fails.

Maintaining the Table

As described earlier, the contents of the registered name table can be reported at any time using the RPTYPE=REGISTRY command of USTRPORT (Reporting with USTRPORT).

Entries in the table can also be displayed, modified, inserted or deleted through the Client interface (see the UPSTREAM Client Guide), or through the UPSTREAM TSO/ISPF dialog. Select option 8 (“REGISTRY”) and press ENTER.

UPSTREAM TSO/ISPF Dialog

-------------------------------- UPSTREAM --------------------
COMMAND ===> 8

1 USTBATCH - Host Initiated Services
2 STATUS - Current Status Information
3 DEFINE - Define Control Files
4 CONFIGURE - Main Options
5 PROFILE - Client Profile Names
6 OPER - Operator Commands
7 REPORT - Report
8 REGISTRY - Name Registry

- 10 SCHEDULE - Command Scheduler
  11 MANAGEMENT - Backup Management
  12 USTCRYPT - USTCRYPT Options
  
  11 Active Jobs:
  
  Sel Jobname System #ACT TCP/IP Address PORT VTAM APL
  --- -------- -------- ---- --------------- ---- --------
  S USTPRODA CPUA 1 192.168.0.1 2001 USTSAAPL
  USTPRODP CPUA VERSION < 3.9.1
  UI CPUB 192.168.0.2 1972 NONE
  USTEURO CPUE INACTIVE

This displays a panel showing all current entries in the registered name table. In our example below you see several registered names (“RED53”, “RED54” etc.), together with the current network address where that Client is located, and the date and time that this table entry was last referenced.

Important

This panel shows the current version of the UPSTREAM software running on each registered Client.

UPSTREAM - Name Registry

------------------------ UPSTREAM - Name Registry ------ Row 1 to 6 of 6
COMMAND ===> SCROLL ===> CSR
COL 1 TO 6 OF 11
Upstream communication parameters:
USERID ===> APPLPREF ===> UPSTR
PASSWORD ===> USAPPL ===> USTPAPPL

Mode ===> BROWSE (Edit Browse) (CMD values: Insert, Delete and Repeat)

CMD Registered Name LUNAME or TCP/IP address..port Last Access PC Version
--- ---------------- -------- ---------------------- -------------- ----------
RED53 192.168.1.1..1972 11/08/09 22:50 L39 3.6.0
RED54 192.168.1.2..1972 11/08/09 23:04 L39 3.6.2d
RED60A 192.168.1.3..1972 11/08/09 23:04 L39 3.6.4a
SUSE10 192.168.1.4..1972 11/08/09 22:47 L39 3.6.3
SUSE10A 192.168.1.5..1972 11/06/20 14:25 L39 3.6.0
SUSE90 192.168.1.6..1972 11/06/16 17:56 L39 3.6.2b
****************************** Bottom of data ********************************

From the above panel, various commands are available to maintain the entries in the registered name table, including Insert, Delete, and Repeat. The insert option is essentially a “manual” registration of a Client. You can also go into Edit mode to alter the contents of a table entry (e.g., to change its name). Any modifications made to an entry in the table are reflected by a UST285 message in the z/OS Storage Server log file.

Automatic Software Upgrades

The registered name service also incorporates a feature that can automatically upgrade the version of the UPSTREAM software running on a client. This removes the need to manually install new releases of the Client software.

When a client registers with the z/OS Storage Server (as described in Registered Names), the entry in the registered name table also records the version of the Client software currently installed.

As part of the initial client registration process, an option can be set to say that this client is eligible for automatic software upgrades. Alternatively, this option can be set later by the administrator, either through the client configuration panels (see UPSTREAM Client Guide), or through the TSO/ISPF dialog (see Maintaining the Table).

Once you have tested and proven a new release of the Client software, it can be automatically distributed to some/all other clients that have a registered name and which are enabled for automatic software upgrades.

The process, which is fully described in the UPSTREAM Client guide is as follows:

You first take a backup from a “testing/proving” client of the new version of Client software.
The registration record for that client is updated to say that it is running the “master” copy of the updated client software.

When other clients subsequently register with the z/OS Storage Server, their version of the client software is compared to the master copy and updated, if required, via an automatic restore.