How to activate Rational Development and Test Environment for System z Version 9.0 or earlier releases

Answer

The process for activating a high capacity USB hardware device has changed. You can use the Rational License Key Center to obtain the files needed.

Terminology considerations

The words “license” and “token” have more than one meaning depending on the context in which they are used.

You can encounter at least four different associated meanings for the word “license” as you work with Rational Development and Test Environment for System z:

1. The word “license” can mean the product entitlement that you purchased and the corresponding terms and conditions under which use is allowed.
   
   
2. The same word “license” can also refer to a technical indicator on the USB hardware device that is used to activate the hardware device and allow an emulated System z instance to operate. The zPDT® Redbooks® and System z emulator messages use the words “license” and “licenses” in reference to these indicators stored on the hardware device. There is a “remote license server” that you can optionally use with the offering that derives its name from this particular usage of the word.
   
   
3. The Rational License Key Center uses the word “license” and “licenses” in reference to a quantity of product entitlement parts purchased.
   
   
4. The file that is generated in the Rational License Key Center that is applied to thare device to enable Rational Development and Test Environment for System z operation can be construed in the website user interface as a generated “license” file.
   
   

In an attempt to clarify the use of the term in the context that is intended, this publicationtechnote uses the following phrases:

• The phrase “product entitlement” refers to the terms and conditions under which the product can be run by the licensee.
• The phrase “license entitlement” is used when referencing the Rational License Key Center interface and the quantity of entitlement parts purchased
• The phrase “USB hardware device activation” or “activation” refers to the condition of the hardware device and its readiness for operation with the emulator
• The phrase “update file” refers to the specific file that is generated in the Rational License Key Center and applied to the USB hardware device to activate it.
  

You can encounter at least two different associated meanings for the phrase “license server” as you work with Rational Development and Test Environment for System z:

1. The phrase “license server” can mean the remote server set up to distribute authentication from a single high capacity USB hardware device to remote instances of the product as an alternative to having discrete USB hardware devices attached to each computer hosting one or more instances of the product.
   
   
2. The same phrase “license server” can mean the Rational License Key Server that is used to share license entitlements among several Rational products.
   

To clarify the context that is intended, this publication uses the following phrases
• The phrase “product license server” refers to the remote Rational Development and Test Environment for System z license server.
• The phrase “Rational License Key Server” refers to the license server used exclusively to share Rational Token license entitlements among a set of Rational products.
  

You can encounter at least two different associated meanings for the word “token” as you work with Rational Development and Test Environment for System z:

1. The word “token” can mean the USB hardware device that is required by Rational Development and Test Environment for System z. The zPDT Redbooks and System z emulator messages use the words “token” and “tokens” in reference to these hardware devices. In such places, you can find further reference to the 1091 token intended for use with the Rational Development and Test Environment for System z offering.
   
   
2. The same word “token” can mean a type of IBM Rational product entitlement that allows great flexibility in the deployment and use of associated, purchased products.
   

To clarify the context that is intended, this publication uses the following phrases
• The phrase “USB hardware device” refers to the hardware part.
• The phrase “Rational Token” refers to IBM Rational Token licensing.
  

In this publication, the word “instance” is used to refer to a single installation of Rational Development and Test Environment for System z on a physical or virtual machine.
Rational Development and Test Environment for System z can be purchased with several different product entitlements. The various types of entitlements allow you to use the product in specific ways.

For details on the product entitlement you purchased, see the documentation that is provided with your copy of the offering or refer to the Product License available at the IBM Software License Agreement website (http://www-03.ibm.com/software/sla/sladb.nsf).
The Product License can be found by searching the site for the product name.

Rational Developer for System z Unit Test
Rational Development and Test Environment for System z

An overview of the activation process

Rational Development and Test Environment for System z requires a USB Hardware Device containing a license key that controls the licensee's access to all or portions of the program. The licensee is not authorized to use Rational Development and Test Environment for System z or any of its components except when that key is made available to the program. The key is made available to the program by first obtaining a license key file providing proof of license entitlement from the Rational License Key Center. That file, called an update file, must then be applied to the USB Hardware Device to activate it and allow the licensee to use Rational Development and Test Environment for System z. The update file is specific to a customer account. The update file only works with a single hardware device, which is identified by its unique serial number. The USB hardware device is either installed on the machine hosting the offering or it is installed on a remote product license server that communicates over the network to one or more instances of the offering.

A single high capacity USB hardware device can authenticate many instances of Rational Development and Test Environment for System z. The number of instances that can be authenticated varies based on the number of emulated Central Processors or CPs used in each instance.

When an instance of the offering starts, it seeks an activation for the number of CPs specified in the emulator’s device mapping file. When an instance of the emulator is stopped, the CPs authenticated by the USB hardware device become available for another instance
If you purchase entitlement to Rational Development and Test Environment for System z using Rational Tokens, the offering can also communicate with a Rational License Key Server to share license entitlements among several Rational products. The license entitlements are tracked by temporary use of a given number of Rational Tokens. For information on setting up and using the Rational License Key Server, see the associated documentation available on the offering’s installation discs.

Note: Both the USB hardware device and the Rational License Key Server are required for the product to operate with Rational Tokens. Implementing a product license server is recommended when Rational Tokens are used. For more information on using Rational Tokens, see the section titled "Rational Tokens" in this document.

The process for activating the product is similar for all versions of Rational Development and Test Environment for System z. For detailed installation and configuration instructions, see the IBM Rational Development and Test Environment for System z Installation and Sample Configuration Guide (SC14-7281).

1. Purchase the Rational Development and Test Environment for System z offering and license metric that best suits your needs.
   
   
2. Obtain one or more USB hardware devices by ordering the appropriate media pack through Passport Advantage®.
   Note: USB hardware devices are not tied to a particular release of the offering.
   
   
3. Obtain an update file to activate the USB hardware device from the Rational License Key Center. If you purchased entitlement using Rational Tokens, you must set up the Rational License Key Server and obtain the corresponding license from the Rational License Key Center.
   
   
4. Optionally, you can set up a product license server
   
1. Install Rational Development and Test Environment for System z on the license server.
2. Connect the USB hardware device to the license server.
3. Apply the update file to the USB hardware device attached to the license server.
4. Start the product license server.
   
   
5. Install Rational Development and Test Environment for System z on computers that meet the System Requirements.
   
   
6. Configure each computer that is hosting the offering to use the product license server you set up earlier or separately connect an activated USB hardware device to each computer.
   
   
7. If you are not using a product license server, apply the corresponding update file to the locally attached USB hardware device of each computer that is hosting the offering.
   
   
8. On the computers that run the emulator, create the device maps used to define your emulated systems
   
1. If you purchased entitlement to Rational Development and Test Environment for System z with Parallel Sysplex®, include a line to enable the coupling facility.
2. If you purchased entitlement using Rational Tokens, include a line to identify the Rational License Key Server to be used.
   
   
9. To install z/OS on the emulator, follow the instructions in the IBM Rational Development and Test Environment for System z Installation and Sample Configuration Guide (SC14-7281).

You can now use the emulator.

The USB hardware device

Rational Development and Test Environment for System z always requires access to an activated USB hardware device. The USB hardware device is ordered through Passport Advantage in a media pack that is separate from the DVD media packs or electronic media packs that contain the offering software. It can be connected directly to the USB port on a computer that is hosting the offering or it can be plugged into the USB port of a separate computer on a TCP/IP network that acts as a product license server.

State of the hardware device

The USB hardware device is not activated by default. When activated, the device allows Rational Development and Test Environment for System z to run one or more emulated central processors, referred to as Central Processors or CPs. Most instances of Rational Development and Test Environment for System z run 3 CPs.

In some cases, the number of CPs in an instance can be more or less than 3. Activations are placed on the USB hardware device by using a command to apply an update file to the hardware device. For instructions on obtaining update files and applying the files to your USB hardware devices, see the sections titled "Obtaining an update file" and "Activating the USB hardware device" in this document.

Capacity of the hardware device

While every release of the offering included a USB Hardware device, the maximum number of CPs that can be activated by a single device varied over time. The two variations issued are high capacity devices and low capacity devices.

High capacity devices

High capacity USB hardware devices can activate up to 100 CPs. These parts have a green label. Since an instance is usually 3 CPs, a high capacity device can typically enable up to 33 product instances of the offering. High capacity devices became available for order with Rational Development Unit Test v8.0.3 and subsequent releases. As of IBM Rational Development and Test Environment for System z v8.5, only high capacity devices are packaged with the offering.

Low capacity devices

Low Capacity USB hardware devices can activate up to three CPs. These devices have a blue label. As of IBM Rational Development and Test Environment for System z v8.5, low capacity devices are no longer available for order.

If you are using a low capacity USB hardware device, you can successfully apply an update file that activates more than 3 CPs. However, you can use only three CPs due to the device limit. These hardware devices are intended for direct installation on the computer that hosts the offering. Only one instance of the offering is expected to run on the hosting machine.

Serial number of the USB hardware device

Each USB hardware device has a unique serial number that is required during the activation process. To locate the serial number of a key, turn the key to the side opposite the colored label. You see three rows of numbers. The lowest or bottom row of numbers is the serial number. The serial number is always of the form 03-xxxxx or 02-xxxxx where xxxxx is five hexadecimal digits.

Expiration dates

USB hardware device activations expire after one year from the date they were generated or less if entitlement is from a term license that expires in less than a year. If your purchase entitles you to use the product for more than one year, you need to renew the USB hardware device activation each year. Renewal activates the USB hardware device for a subsequent year or until the end of the fixed term if less than a year as applicable.

You can check the expiration date of an activation by using the token command. You can run the token command only while the emulator is running, and you must run the command from the same user ID that started the emulator.

Capability configuration of the USB hardware device

Based on details in the update file applied to the USB hardware device, the device is configured to make Rational Development and Test Environment for System z capable of operating within one and only one of the following parameters:

1. Parallel Sysplex® support is not enabled and there is no requirement to use Rational Tokens.
   
   
2. Parallel Sysplex support is enabled and there is no requirement to use Rational Tokens.
   
   
3. Parallel Sysplex support is not enabled and Rational Tokens are required.
   
   
4. Parallel Sysplex support is enabled and Rational Tokens are required.
   
   

Although the hardware device itself permits the application of more than one update file, it is best to avoid mixing Sysplex and Non-Sysplex update files on the same USB hardware device. Mixing the update files can make it difficult to manage and track the deployment of license entitlements as well as potentially separate expiration dates for each update file applied to the device. Because of these concerns, the Rational License Key Center does not allow you to generate multiple update files for the same USB hardware device.

Parallel Sysplex Activations

Some entitlements of Rational Development and Test Environment for System z enable emulation of the Coupling Facility under z/VM® while others do not. Entitlements that enable the coupling facility are referred to in Rational Development and Test Environment for System z documentation as Sysplex activations.

Although a coupling facility is not related to an individual processor in real System z hardware, every CP in a Rational Development and Test Environment for System z instance requires a corresponding Sysplex CP activation to enable the coupling facility for the instance.

Similarly, instances that do not enable the coupling facility require non-Sysplex CP activations for every CP in the instance. The update file that you receive to activate your USB hardware device is based on the type of license you purchased. With non-Sysplex CP activations, you can create instances that use up to 3 CPs. With Sysplex CP activations, you can create instances that use up to 8 CPs.

Rational Token Activations

USB activations that are specific to Rational Tokens must be used when Rational Token licensing is implemented. The emulator uses the USB hardware device activation stored on the USB hardware device to determine whether Rational Tokens are required.

Attention: When you are using multiple USB hardware devices, especially in a product license server, you must not mix activations that require Rational Tokens with activations that are not intended for Rational Tokens.

If the emulator receives inconsistent USB activations, your environment might be out of compliance with your licensing terms or you might be unable to access some of the CPs to which you are entitled.

Rational Development and Test Environment for System z usage can be governed by Rational Tokens. When you use Rational Tokens, the emulator coordinates with a Rational License Key Server instance and starts or continues to run only if sufficient Rational Tokens are available.
Use of Rational Tokens does not replace the USB hardware device. A USB hardware device that is activated with a valid update file is still required.

When Rational Development and Test Environment for System z is started, the emulator verifies that a valid USB hardware device activation is found and enough Rational Tokens are available from the Rational License Key Server to run the emulator. Rational Tokens control product operation as long as a sufficient number of CPs are available from the USB hardware device or devices used. Each high capacity USB hardware device activated for use with Rational Tokens has a limit of 100 CPs. If you need to serve more than 100 CPs across all product instances, you can obtain additional high capacity USB hardware devices and activate them for use with Rational Tokens. The Rational License Key Center allows you to generate as many additional update files as needed to activate such additional USB hardware devices. Multiple USB hardware devices may be attached to the product license server.

Both the activated USB hardware device and the Rational Tokens must be available to the emulator while the emulator is running. The emulator suspends operation if either becomes unavailable.

Obtaining an update file

To activate a USB hardware device and enable the Rational Development and Test Environment for System z to run, you must first obtain a unique "update file" for each USB hardware device you will be using. Updates to the processes are are published on the IBM Development and Test Environment Hub on developerWorks® (http://ibm.co/rationalsystemzdevtest).

Important: The method for obtaining update files for the Rational Development and Test Environment for System z USB hardware device is different than the method described in the Redbooks.

Most update files are now distributed as part of an archive with a file extension of .zip. These files are obtained through the Rational License Key Center. You should unzip the zip file and use the *.upw file alone with your USB hardware device just as you have in the past. Version 9.0.0 and earlier releases do not require any other content in the zip file.

To obtain an update file the first time, log in to the Rational License Key Center at https://licensing.subscribenet.com/control/ibmr/login, select your account and use the Get Keys screen to select the order for which you want to generate and download an update file.

If you want to use a previously activated USB hardware that is near the expiration date, you need to renew the update file to obtain a replacement To renew an update file, log in to the Rational License Key Center, select your account and use the Return Keys link to return the old update file. Then use the Get Keys link to generate a new one. The return function does not require that you provide the old update file. The return function tells the Rational License Key Center to allow you to regenerate a new update file.

Before you sign in to the Rational License Key Center, locate the serial number of your USB hardware device. You have to know this number to generate an update file. To locate the serial number of a key, turn the key to the side opposite the colored label. There are three rows of numbers etched on the device. The lowest or bottom row of numbers is the serial number. The serial number is always of the form 03-xxxxx or 02-xxxxx where xxxxx is five hexadecimal digits.

Figure 1. USB hardware device

In Figure 1, the entire serial number is 02-00222.

If you are unable to read the etched serial number from the USB hardware device contact IBM support. They ask for a “request file” created by the SecureUpdateUtility or the Z1091_token_update command with the -r switch. From this request file, IBM can determine the serial number of the USB hardware device.

Note: The Rational License Key Center now requires the entire serial number of the USB Hardware Device, not just the last (5) digits. For example, 03-00123.

Getting the update file from the Rational License Key Center

The following section describes the process for using the Rational License Key Center to obtain update files. If your installation is using Rational Tokens to govern entitlement to Rational Development and Test Environment for System z, see the section titled "Obtaining update files for Rational Tokens" in this document.

Steps to get the initial file

Use the following steps to obtain an update file from the Rational License Key Center.

1. Log in to the Rational License Key Center at https://licensing.subscribenet.com/control/ibmr/login and select your account.
   
   
2. On the left side of the screen, select Get Keys
   
   
3. Select the product line for Rational Development and Test Environment for System z. You see a list of license key names that show the Rational Development and Test Environment for System z licenses that are available.
   
   
4. Select the Rational Development and Test Environment for System z license type that you want to apply to the key.
   
   
5. You see one or more boxes that show the separate orders that you can apply to one or more USB hardware devices.
   
   

Important: For some license entitlements, you can combine multiple orders on a single USB hardware device or spread the licenses across multiple USB hardware devices. Regardless of how many Rational Test and Development Environment for System z instances you deploy for your licensed users, you must make sure you maintain proper entitlement for the number of end users accessing each instance of the product. License entitlements based on Resource Value Units (RVUs) do not limit the number for end users accessing the offering. All other types of License entitlements require at least one product entitlement for each end user accessing the product.

6. Check the box next to all of the orders from which you would like to use licenses and click Next.
   
   
7. A screen is displayed showing a table that you must complete with the USB hardware device serial numbers you want to activate. Depending on the license entitlement selected, you might also be asked for the number of instances, the number of licenses to associate with each USB hardware device, and the number of Emulated Central Processors you intend to use for the specific USB Hardware Device activation.
   
   You can enter information for more than one USB hardware device. A separate update file is generated for each key specified. You can download the generated update files either during this process or from the View keys by host screen.
   
   More help is available by clicking the column headings in the table, but briefly stated:
   
1. The Serial Number of USB Hardware Key field is where you specify the full eight character serial number that is etched on the last line of the USB hardware device. It has a format of 02-xxxxx or 03-xxxxx where xxxxx is five hexadecimal digits. The two-digit prefix and the dash must be included when you specify the serial number.
2. The Number of Server Instances field refers to the number of separate emulated systems you plan to enable with each USB hardware device. The number of central processors (CPs) that is available is automatically calculated for you. For some older entitlements, this value is forced to one.
3. The Number of Licenses field is applicable to some offering entitlements. Where applicable, each user accessing a separate instance of a virtual System z machine requires a separate license. Individual users are licensed to a specific instance of a virtualized System z. The total number of licenses for all serial numbers must not exceed the number of licenses to which you are entitled. For example, if you are entitled to five Authorized User licenses, you might enable 2 instances, and 5 licenses so that one workstation can be used by two people and another workstation can be used three people. Designating the number of licenses that are associated with a USB hardware device ensures that you are tracking the number of entitlements used.
4. The Emulated Central Processor field is applicable only to entitlements metered as Resource Value Units (RVUs). For this entitlement, each emulated central processor within an instance of a virtual System z machine requires a separate RVU entitlement. For each serial number, you should enter the total number of emulated central processors that you intend to enable with that specific USB hardware device. The total number of emulated CPs for all serial numbers must not exceed your total number of RVU entitlements.
   
   
8. After you indicate how you want to distribute license entitlements across USB hardware devices, select Generate at the bottom of the page and you are presented with a screen where you can download the update files.
   
   
9. Click Download for each update file generated to save the update files. If you need to download the update files in the future, use the View Keys by Host link on the left side of the Rational License Key Center web page.
   
   

Note: You cannot generate separate activations for the same USB hardware device at the same time. Before you generate update files for a given USB hardware device that you wish to reuse, be sure to return the update file that was previously created for that device. Returning license entitlements that are assigned to the USB hardware device also makes the corresponding active entitlements available for assignment to a USB hardware device again.

Steps to get the replacement file

For perpetual license entitlements, USB hardware device activations are set to expire one year from the date an update file is generated. For this type of entitlement, you can return previously generated update files at any time and generate a new update file.

For term license entitlements, if term expiration occurs in more than one year, USB hardware device activations are set to expire one year from the date an update file is generated. Update files can be returned and generated again before term expiration. If term expiration occurs in less than one year, USB hardware device activations are set to expire at term end. After term end, update files cannot be generated in the Rational License Key Center.

To generate a new update file, you must first return the existing license entitlement in the Rational License Key Center, and then generate a new update file. Returning the license entitlements is a process of telling the Rational License Key Center that you are no longer using the license entitlements that you previously assigned to your USB hardware device. You do not need to return the physical update file to the Rational License Key Center.

There are several ways to return a license entitlement in the Rational License Key Center. The easiest method is to use the View Keys by Host link. You can also use the Return Keys link.
For Rational Development and Test Environment for System z the term host in the Rational License Key Center refers to the USB hardware device that is uniquely identified by its serial number.

1. Log in to Rational License Key Center at https://licensing.subscribenet.com/control/ibmr/login and select your account.
   
   
2. On the left side of the screen, select View Keys by Host.
   
   
3. Select the serial number of the USB hardware device you want to work with. This serial number is in the Host column.
   
   
4. A table is displayed with data for the USB hardware device selected. At the far right of the table, click the Change link.
   
   
5. You see a list of devices with license entitlements that are assigned to them from the same Order Line. Locate the serial number of the USB hardware device you are working with and click Return. A message is displayed to confirm that the license entitlements have been successfully returned.
   
   
6. Use the Get Keys link on the left side of the page to generate a new license. For detailed instruction on generating new licenses, see the section titled "Steps to get the initial file" in this document.

Obtaining update files for Rational Tokens

The following section shows the process for using the Rational License Key Center to obtain update files if your installation is using Rational Tokens to govern entitlement to Rational Development and Test Environment for System z.

Use of Rational Token licensing requires purchase of Rational Tokens. After the Rational Tokens are purchased, follow these instructions for obtaining Rational Token license files and update files for your USB hardware devices.

Steps to get the initial update file and Rational Token license

Use the following steps to get an update file for your USB hardware device and a Rational token license file from the Rational License Key Center.

1. Log in to the Rational License Key Center at https://licensing.subscribenet.com/control/ibmr/login and select your account.
   
   
2. On the left side of the screen, click Get Keys.
   
   
3. Select a product line that contains your Rational Token orders with Rational Development and Test Environment for System z.
   
   
4. On the "Select License Keys" screen, you see one or more boxes for orders. Find the order that includes Rational Development and Test Environment for System z. Make a note of the part number for the Development and Test Environment product you want to activate. Select the order that contains the parts you noted and click Next.
   
   
5. Enter the required information to create the Rational Token license file for your host. Additional information for each field is available by clicking the descriptive link next to the input field. Fields with a red star are required fields.
   
   
6. Click Generate to generate the Rational Token license file. You are presented with a screen with the generated license information.
   
   
7. Click Download License Keys to download the Rational Token license file to your computer. This token license file is the file that is applied to your Rational License Key Server. It is named license.dat by default.
   
   
8. On the same screen, press Generate Token License Keys for USB Hardware Device to generate and download the update file for your USB hardware device.
   
   
9. A Required Information screen is displayed showing a table that you must complete with the USB hardware device serial numbers and associated Development and Test Environment product you want to activate with each device.
   
   You can enter information for more than one USB hardware device. A separate update file is generated for each key and can be downloaded either during this process or at some time in the future from the View keys by host screen.
   
   The serial number is the full eight character serial number that is etched on the last line of the USB hardware device. It has a format of 02-xxxxx or 03-xxxxx where xxxxx is five hexadecimal digits. The two-digit prefix and the dash must be included when you specify the serial number.
   
   The Catalog Item select list allows you to confirm the part you want to use to generate an update file. This is important if you have entitlement to both Rational Development and Test Environment for System z and Rational Development and Test Environment for System z with Parallel Sysplex. You cannot combine Token and Sysplex Token activations on a single USB hardware device. From the drop-down list available, select the entitlement part number that corresponds to the activation you want on the specified USB hardware device.
   
   
10. After you indicate how you want to distribute licenses across USB hardware devices, click Generate at the bottom of the screen and you will be presented with a screen where you can download the update files.
    
    
11. Click Download for each update file to save the update files. If you need to download the update files at some time in the future, use the View Keys by Host link on the left side of the page.
    
    

Note: You cannot generate separate activations for the same USB hardware device at the same time. Before you generate update files for a given USB hardware device that you want to reuse, be sure to return the update file that was previously created for that device. Returning license entitlements that are assigned to the USB hardware device also makes the corresponding active entitlements available for assignment to a USB hardware device again.

Steps to get a replacement update file and Rational Token license

To return and regenerate your update file and existing Rational Token license files, use the Return Keys function in the Rational License Key Center. This is the process you use to renew the USB hardware device activation for another year.

Use the following steps:

1. Go to the Rational License Key Center at https://licensing.subscribenet.com/control/ibmr/login to return the existing USB hardware device update file. For more information about returning update files, see Steps to get the replacement file.
   
   
2. After you return the update file, click Get Keys on the left side of the screen.
   
   
3. Click the product line for IBM Rational Tokens.
   
   
4. You see a screen titled Select license keys. Keys that include Rational Development and Test Environment for System z have a link to generate update files for USB hardware devices.
   
   

Click the link titled Generate Token License Keys for USB Hardware Device and complete the form to generate and download the new update file.

Activating the USB hardware device

Applying the update file you obtained from the Rational License Key Center to your USB hardware device activates the device. Each time you apply an update file, it overwrites the previous activation on the USB hardware device. To change the activation of a USB hardware device, you must obtain and apply a new update file that activates the total number of license entitlements you intend to use on that device. Changing the activation of a USB hardware device involves returning and regenerating licenses in the Rational License Key Center.

Before you insert the USB hardware device into a computer's USB port, verify that the computer's clock is set correctly. If your computer is new or recently repaired, ensure that the clock is correct before you insert the USB hardware device.

Warning: Never set the system clock to a future date or time when the USB hardware device is plugged in or you will damage the USB hardware device.

Note: If the USB hardware device is attached to a computer with a clock set to a future date, the device remembers that future date, will become inoperable when the clock is restored to the current time, and will remain inoperable until the computer's clock reaches that future date. If Rational Development and Test Environment for System z is unable to authenticate with the USB hardware device because the clock was set to a previous time or date, you receive a message that indicates a “time cheat” state.

If the update file you obtain from the Rational License Key Center is an archive file with the extension .zip, you need to extract the contents of the archive to a temporary directory during the process that is described here to get the *.upw file needed for Rational Development and Test Environment for System z version 9.0 or earlier releases.

If you have an older update file that has an extension of .upw, you can use that file with the SecureUpdateUtility as described in step 4, step 5, and step 7 below.

Read the entire set of instructions before you start activating your USB hardware device. In summary, you connect the device to a computer that has Rational Development and Test Environment for System z or Rational Developer for System z Unit Test installed. Extract the contents of your update compressed file and run the SecureUpdateUtility command against the *.upw file that was extracted from the zip file. The entire procedure is described here:

1. Connect the USB hardware device to the computer that is running Rational Development and Test Environment for System z.
   
   Note: Update files are written for specific USB hardware devices, so it is acceptable to have more than one USB hardware device attached to the computer during this process.
   
   
2. Use a browser on your Linux computer to download the update file directly from the Rational License Key Center or use whatever method is available (for example, FTP, SFTP, or an external hard disk) to copy your update file to that computer.
   
   Note: Be sure to use the binary transfer mode and not a text mode such as ASCII.
   
   
3. Log in to the computer, create a new, temporary directory and extract the contents of your update file to that directory. For example:
   
   mkdir /tmp/myupdatedir
   cd /tmp/myupdatedir
   unzip update-file.zip ls
   
   You see a list of file names. Note the name of the file that ends in .upw. The upw file has a name similar to RDT-xxxxx-yyyymmddhmm-Lcc.upw or RDT-xxxxx-yyyymmddhmm-Lcc.-Sysplex.upw where:
   
   xxxxx
   Is your device's serial number
   
   yyyymmddhmm
   Is the expiration date of the activation
   
   cc
   Is the number of licensed CPs in hexadecimal format
   
   
4. If you are not running as root, enter su followed by the root password.
   
   
5. Change to the /usr/z1090/bin directory
   
   cd /usr/z1090/bin
   
   
6. If you are applying an update file for Parallel Sysplex, run the SecureUpdateUtility command with the n switch and the full path of the adcd.NLF file: For example (all on one line),
   
   ./SecureUpdateUtility n /tmp/myupdatedir/adcd.NLF
   
   This command produces several messages but indicates that the update was successful or that the license exists, meaning the update file has already been applied. You need to run this command only one time for a USB hardware device.
   Note: Running this command each time you apply an update file does not cause problems.
   
   
7. Run the ./SecureUpdateUtility u update-file.upw command where update-file.upw is the full path and file name of the update file. For example (all on one line),
   
   ./SecureUpdateUtility u /tmp/myupdatedir/RDT-00DF0-201502152359-L03-Sysplex.upw
   
   This command produces several messages but indicates that the update was successful.
   
   
8. To ensure that the system sees newly applied licenses, run the following command to restart the local product license server:
   

/opt/safenet_sentinel/common_files/sentinel_keys_server/loadserv restart

For answers to common errors related to USB hardware device activation, see Troubleshooting USB hardware device activation.

Stand-alone .upw update files

IBM recently changed the way that it distributes update files. Update files are now distributed as compressed file archives that contain, among other things, update files with the upw extension. Previously, IBM distributed just the update file. You can still use the SecureUpdateUtility command with the stand-alone update files that have the .upw extension.

Preparing the USB hardware device for Sysplex activation

You need to apply the file that is named RDT_SP.NLF that was installed in the directory you specified during the installation of Rational Development and Test Environment for System z to your USB hardware device. If you do not know the installation location, you can locate the RDT_SP.NLF file on your system by running the command:

find / -name RDT_SP.NLF 2>/dev/null

For example, if the find command returns the location /opt/IBM/Rational Development and Test Environment for System z/RDT_SP.NLF, then prepare your USB hardware device by using the following command:

./SecureUpdateUtility n “/opt/IBM/Development and Test Environment/RDT_SP.NLF”

This is a single command, even if it appears as multiple lines in some formats of this documentation. Double quotation marks are used in this example because the file name contains spaces.