ISV IBM Z Program Development Tool installation
|
Important: This publication is about Independent Software Vendor (ISV) IBM Z Program Development Tool (IBM zPDT) (ISV zPDT). Many of the points that are described might also apply to IBM Z Development and Test Environment (IBM ZD&T) systems. If you are working with IBM ZD&T, you should obtain access to the full documentation that is provided for it.
Important: For ISV zPDT installation and operation, do not work with Linux root authority except when instructed to do so. This caution applies to both ISV zPDT installation and routine ISV zPDT operation.
Important: Some of the details that are mentioned in this publication (and especially in this chapter) are for ISV zPDT GA11, so they might differ from equivalent details for previous or later zPDT releases. GA11 was built on later Linux bases than previous ISV zPDT releases, which can change some of the Linux libraries that are needed.
|
ISV zPDT operates as a normal Linux application. As a best practice, follow the general procedures that are described here for initial ISV zPDT installation and usage. After you gain experience with ISV zPDT, you might explore other installation and usage arrangements.
This chapter describes the basic ISV zPDT installation process. Your product package might provide an enhanced installation method that is provided by your ISV zPDT vendor.
This publication does not provide detailed ordering information for ISV zPDT. The ordering process differs for various categories of users and for different countries. At a practical level, you must acquire the following items:
•A personal computer (PC) Linux operating system that is appropriate for your ISV zPDT release. This base Linux is not supplied by IBM. It must be ordered or downloaded from a vendor.
•An ISV zPDT token, which is known as an IBM 1090 token, and which might need to be activated through an IBM Business Partner, ISV zPDT supplier, or through IBM Resource Link®.
•The ISV zPDT software, which must be installed before the token can be activated (if it is not already activated). The base ISV zPDT software does not include any IBM zSystems operating systems.
•Whatever IBM zSystems software that you plan to use, in a format that is usable with
ISV zPDT. This software might require a different ordering process than the one that you use to order ISV zPDT itself. Typically, the software is an Application Development Controlled Distribution (ADCD) package, as described in Chapter 6, “Application Development Controlled Distribution installation” on page 137. Much of the material in this publication assumes that you install the z/OS ADCD system. If you install different IBM zSystems software (and have an appropriate license for it), you must obtain specific instructions for ISV zPDT from the supplier of that software.
ISV zPDT. This software might require a different ordering process than the one that you use to order ISV zPDT itself. Typically, the software is an Application Development Controlled Distribution (ADCD) package, as described in Chapter 6, “Application Development Controlled Distribution installation” on page 137. Much of the material in this publication assumes that you install the z/OS ADCD system. If you install different IBM zSystems software (and have an appropriate license for it), you must obtain specific instructions for ISV zPDT from the supplier of that software.
5.1 Linux installation
ISV zPDT GA11 was built and tested on several different Linux distributions, and informally tested on certain other distributions. For more information about which specific distributions were used, see 2.5, “ISV zPDT releases” on page 44. As a best practice, use one of the Linux distributions and levels that are listed. Earlier Linux levels might not work fully with ISV zPDT GA11, and later levels might contain subtle changes that create issues.
Disk planning
ISV zPDT does not care how you partition your Linux disks if you have sufficient room for whatever IBM zSystems emulated disk volumes that you need. A simple disk plan might be like the following one:
•A 30 GB partition, for example, for all the Linux files and the ISV zPDT program.
•An appropriate swap partition with 10 GB or whatever is appropriate.
•A large partition for emulated IBM zSystems volumes, which is at least 250 GB.
The separate Linux disk partition (and corresponding separate Linux file system) for the emulated IBM zSystems volumes allows the base Linux to be replaced easily without destroying the emulated volumes. In practice, most ISV zPDT customers have several disks, each with its own file system, and spread emulated volumes and various backup materials.
Basic adjustment example for installing ISV zPDT
Each of the various Linux distributions (and the distributions that are used for informal tests) might have a few “adjustments” that are needed for ISV zPDT installation and usage. Here is a specific set of additions that are needed by CentOS Stream 9 that was used for informal testing. The commands and syntax that are shown here were for that specific distribution, so slight changes might be needed with other Linux distributions.
We used the following commands after performing the basic CentOS Stream 9 installation from a USB flash drive in .isv format. These commands assume that your Linux system has an operational internet connection.
# yum install libstdc++.i686 (This library is needed for token operation.)
# yum install libnsl
# yum install perl
# yum install x3270 (Optional. A 3270 emulator package.)
# yum install x3270-x11 (Needed by x3270.)
The details are likely to change slightly with other distributions. For example, the libstc++ library installation for SUSE might be zypper install libstdc++6-32bit and for Ubuntu might be apt-get install lib32stdc++6.1 The library names here are the “search names” that you might use to find the library. Each library has a complete name, for example libstdc++-11.3.1-2.1.el9.i686.
During ISV zPDT installation, you might see error messages that indicate that other libraries are missing. If so, attempt to install them by using commands that are like the ones that are listed above. For example, for a SUSE installation, you might need zypper install libcap-progs or something similar.
ISV zPDT is not sensitive to the desktop manager. Some developers use GNOME and others use Xfce or KDE. A graphics Linux desktop is not required by zPDT, but many users find it convenient.
There might be other details that are involved in the initial Linux or ISV zPDT installation. For example:
•The ISV zPDT installation includes two Linux packages that are named sntl-sud and shk-server. You might find later versions of these packages elsewhere. Do not install the later versions. Use only the versions that are supplied with ISV zPDT.
•You might want the x3270 package. The package is probably not included with the Linux distributions, but it can be downloaded. Other 3270 emulation packages are available and might be used, but x3270 appears to be the most used one for ISV zPDT.
•We found that performing an online update for the Linux distribution is advisable when performing the initial Linux installation.
•You must manage whatever firewall and other security functions that you install with Linux. If possible, initially disable any firewall when first working with ISV zPDT. After you are familiar with the ISV zPDT operation, you can reestablish the firewall functions. If you have external TCP/IP connections (for local2 3270 connections, Open Systems Adapter (OSA) connections, license servers, Server Time Protocol (STP), or channel-to-channel (CTC) connections), you must provide the correct port holes in any firewall that you use.
•Select Coordinated Universal Time for your base PC, if possible. (This task might not be possible if you also run Microsoft Windows on the same PC.)
5.2 The ISV zPDT program package
The ISV zPDT program package is typically obtained by downloading it.3 The package file contains the Red Hat, SUSE, and Ubuntu versions of the ISV zPDT code.4 The correct version is automatically installed on your system.
5.3 ISV zPDT installation
Decide on the Linux user ID that you want to use for running ISV zPDT. We use ibmsys1 in our examples, but you can select any user ID that is 8 characters or fewer (unless the system_name statement is used in the device map (devmap), in which case there is no special limit on the length of the Linux user ID). This publication frequently uses ibmsys1 in examples.
In examples throughout this publication, the dollar sign prompt ($) indicates a non-root user ID, and the number sign prompt (#) indicates we are working as root. As a best practice, always log in as ibmsys1,5 and then use a su command to switch to root when needed.6 The following directions assume that a single ISV zPDT instance is used. (Multiple ISV zPDT instances require multiple user IDs, such as ibmsys2 and ibmsys3.)
If you have not done so, create user ibmsys1 (or whatever user ID that you selected for
ISV zPDT usage). By default, user ID ibmsys1 uses /home/ibmsys1 as its home directory, and some ISV zPDT control files appear in subdirectories there. We created file system /z as a separate partition during our Linux installation for our emulated volumes. We want user ID ibmsys1 to own this file system.
ISV zPDT usage). By default, user ID ibmsys1 uses /home/ibmsys1 as its home directory, and some ISV zPDT control files appear in subdirectories there. We created file system /z as a separate partition during our Linux installation for our emulated volumes. We want user ID ibmsys1 to own this file system.
To create ibmsys1, log on as ibmuser1 and run the following commands:
# su - (Switch to root.)
# chown ibmsys1 /z (User ibmsys1 owns the emulated volume directory.)
A single executable file is used to install the ISV zPDT software. The file name changes with maintenance releases, but has the following general format:
z1090-1-11.57.05.x86_64 (Verify your exact file name.)
The single file contains the following items:
•An sntl-sud rpm at the correct level (a driver for the tokens).
•A zpdt-shk-server rpm at the correct level (another token program).
•The primary ISV zPDT rpm for SUSE Linux.
•The primary ISV zPDT rpm for Red Hat Linux.
•The primary ISV zPDT deb for Ubuntu.
•An installer program that displays a license and then installs the rpms or debs. The correct rpm or deb (Red Hat, SUSE, or Ubuntu) is automatically selected for your base Linux system.
Place the ISV zPDT package file in a convenient library, such as /tmp. To do so, log in as ibmsys1 and run the following commands:
$ su - (Change to root.)
# cd /tmp (If the file is in /tmp.)
# chmod u+x z1090-1-11.57.05.x86_64 (Make the file executable.)
Run the file, which runs as the installer program:
# ./z1090-1-10.57.05.x86_64 (First, verify the exact file name.)7
Scroll through the license information that is displayed and reply to the question at the end. Then, the various components are installed automatically. The ISV zPDT installer program performs the following tasks, removing existing versions of these programs as needed:
•Two prerequisite token modules are installed.
•The ISV zPDT rpm or deb is installed, mostly in /usr/z1090/bin.
•A set of man files is loaded into /usr/z1090/man.
•A /usr/z1090/uim directory is also created.
Installer options
If an ISV zPDT fix is installed, it must be removed before a new ISV zPDT release can be installed. (ISV zPDT fixes are rare, but are produced when needed for specific problems.) An ISV zPDT patch is an rpm or deb. Fixes can be found by running rpm -qa | grep z109 commands and removed by running rpm -e commands, or their Ubuntu equivalents.
The installer program has three optional functions. Using the file name in the preceding example, the functions are listed here:
# ./z1090-1-10.57.05.x86_64 --refresh (Reinstall the ISV zPDT level.)
# ./z1090-1-10.57.05.x86_64 --refreshall (Reinstall ISV zPDT and its prerequisites.)
# ./z1090-1-10.57.05.x86_64 --removeall (Remove ISV zPDT and its prerequisites.)
The prerequisites that are mentioned here are two modules that are needed to access the USB token.
5.3.1 Altering Linux files
|
Important: You must complete the actions in this section before attempting to decrypt the initial program load (IPL) volumes of the z/OS ADCD system. You can use the supplied scripts (aws_sysctl and aws_bashrc) or edit the relevant files yourself, as described in this section.
|
You must alter two Linux files before you can use ISV zPDT. The first alteration is to /etc/sysctl.conf, which involves changing some Linux kernel parameters. The second alteration is to the .bashrc file in your home8 directory, which adds the ISV zPDT directories to your user ID’s PATH and LD_LIBARY_PATH variables. These changes are usually one-time changes. It is not necessary to make the changes again when upgrading to a new ISV zPDT release.
You can manually edit the relevant Linux files or use ISV zPDT commands to make the changes. The ISV zPDT commands are as follows:
# /usr/z1090/bin/aws_sysctl (You must be root to use this command.)
$ /usr/z1090/bin/aws_bashrc (You must not be root to use this command.)
The complete path name might be required for these commands (as shown here) because your Linux PATH might not yet include the ISV zPDT files. If you use these two commands, you can skip the following material about manually editing these files. You might want to restart Linux after making the changes.
Manually editing the files
If you want to manually edit /etc/sysctl.conf,9 we suggest using gedit, but you can use any suitable editor (such as vi or leafpad) to add the indicated lines.10
|
Important: The shmmax and shmall values that are installed by the /usr/z1090/bin/aws_sysctl script are suitable for many laptop environments where the emulated IBM zSystems memory size is not more than about 24 GB. If your emulated
IBM zSystems size is much larger, then you need larger shmmax and shmall values. Read the following notes carefully. |
Some Linux distributions have acceptable values for shmmax, msgmnb, msgmax, and core_uses_pid, but other distributions might need to have all these values set.
# gedit /etc/sysctl.conf (The following lines should begin in column 1.)
kernel.core_pattern=core-%e-%p-%t
kernel.core_uses_pid=1
kernel.msgmax=65536
kernel.msgmnb=65536
kernel.msgmni=512 (Change for large number of devices.)
kernel.shmmax=36000000000
kernel.shmall=24000000
kernel.sem=250 32000 250 1024
net.core.rmem_max=1048576
net.core.rmem_default=1048576
# /sbin/sysctl -p /etc/sysctl.conf
Notes for sysctl values
The shmmax value establishes the maximum shared memory segment size that a user can request. All IBM zSystems memory, plus other ISV zPDT work areas, is in Linux shared memory. The shmmax value should be at least 20% larger than the IBM zSystems memory that is defined for the largest ISV zPDT instance that you use. The example that is shown (36,000,000,000 bytes) is suitable for an ISV zPDT instance with up to about 32 GB memory (as specified in the devmap). There is no need to attempt an exact fit for the shmmax number.
Another parameter, shmall, sets the total shared memory size of all users. The value of shmall is specified in units of page size, which is usually 4096. The default value of shmall is usually large and acceptable.11 However, if you have multiple ISV zPDT instances and all of them have large IBM zSystems memory, you might exceed the default shmall value. If this scenario happens, you must include a parameter like this one:
kernel.shmall=24000000
This parameter sets the total amount of shared memory, for all users, at 24,000,000*4096, or about 96 GB. This value should be greater than the number of ISV zPDT instances times the IBM zSystems memory size for each instance, plus about 10 - 20%.
|
Remember: The shmmax value is for the number of bytes, and the shmall value is for the number of pages.
|
The kernel.msgmni value, which is specified as 512 in this example, might need to be larger if you have many emulated I/O devices, for example, more than 150 devices. The msgmax and msgmnb changes are not needed for some Linux releases because they are the default settings. However, including these parameters in sysctl.conf appears to do no harm.
Included in the example is the kernel.sem parameter that controls the maximum semaphore configuration for Linux. If you have many devmap devices in multiple ISV zPDT instances, you might need to change this parameter. An example of a change is shown above. However, the default values are suitable for most users.
The net.core parameters might be needed if Ethernet large frames are used. These parameters seem to do no harm, so you can always include them. In this context, any frame with more than 1500 bytes is considered large.
Notes for .bashrc
The .bashrc file is changed, as follows:
# exit (Leave root if you are in root.)
$ cd /home/ibmsys1 (My login directory)
$ gedit .bashrc (Use your favorite editor.)
(Add the following lines beginning in column 1>):
export PATH=/usr/z1090/bin:$PATH
export LD_LIBRARY_PATH=/usr/z1090/bin:$LD_LIBRARY_PATH
export MANPATH=/usr/z1090/man:$MANPATH
ulimit -c unlimited
ulimit -d unlimited
ulimit -m unlimited (If more than 128 emulated I/O devices)
ulimit -v unlimited (If more than 128 emulated I/O devices)
Double-check the entries in these two Linux files. Errors here might be difficult to detect later. The ulimit -m and -v statements are not required for most users and should probably be excluded unless you have more than 128 emulated I/O devices.)
5.3.2 Other Linux notes
Always use the same Linux user ID for ISV zPDT operation. This Linux user ID must be no longer than 8 characters unless the system_name statement is used in the devmap.12 Multiple concurrent ISV zPDT instances require a different Linux user ID for each instance.
One of the last ISV zPDT installation steps that is shown above changes the PATH and LD_LIBRARY_PATH environmental variables that are used by Linux shells. Do not add other directories before /usr/z1090/bin in these variables.13 There are many Linux commands that are provided with ISV zPDT, and they correspond to Linux file names that are accessed through the PATH variables. For example, the command d is used to display IBM zSystems memory and registers. If you place another directory containing a file that is named d earlier in the PATH, the ISV zPDT d function will not be available in the normal manner. Various internal ISV zPDT functions assume that they can access ISV zPDT modules through PATH and LD_LIBRARY_PATH, so you must ensure that this access is possible.
Restarting Linux
Restart Linux to pick up all the changes that you made. Then, use the z1090instcheck command to verify your environment for running ISV zPDT. Your new PATH is needed to find the command.
Log in as ibmsys1 and run the following command:
$ z1090instcheck
The same z1090 command is also used for 1091 systems.
If this command is not found, you do not have the PATH variables set or you did not install the ISV zPDT code correctly. This command does not check any devmaps that you might have defined or copied.
5.4 x3270
x3270 is an open-source Linux program that emulates IBM 3270 terminals.14 It is not distributed with ISV zPDT, so you must obtain it yourself. You might find many different levels of x3270 on various websites, and some of them might not match the libraries that are available on your base Linux system. The three Linux distributions (Red Hat Enterprise Linux (RHEL), SUSE Linux Enterprise Server, and Ubuntu) that are used by ISV zPDT normally have a version of x3270 that is available in their repository.
To install x3270, run the following commands:
sudo apt-get install x3270
sudo apt-get install xfonts-x3270-misc (This command might not be needed.)
yum install x3270
yum install x3270-x11 (This command might not be needed.)
Obtaining x3270 this way (from a Linux distribution repository) should provide a version that matches your base Linux libraries. Unfortunately, the x3270 versions that are provided this way are often earlier versions and might not have recent improvements. However, they provide the basic 3270 functions.
Many 3270 emulators are available for Microsoft Windows systems, and most of them can be used with local area network (LAN) connections to your ISV zPDT system.
5.4.1 x3270 keyboard maps
The default x3270 keyboard assignments are not in the traditional 3270 style. In particular, the large Enter key on the PC keyboard functions as the 3270 Enter key.15 With traditional 3270 keyboards, this same key provides a new line function, and the 3270 Enter key is where the right-side Ctrl key is on most PC keyboards.
One way to change the key mapping is to create a file (in your home directory) that is named .x3270pro (note the period as the first character of the file name), which has the following content:
! Use Bill’s overrides
x3270.keymap: bill
! Define the overrides
x3270.keymap.bill: #override
<Key>Control_R: Enter()
<Key>Control_L: Reset()
<Key>Return: Newline()
<Key>Pause: Clear()
<Key>End: Clear()
<Key>BackSpace: BackSpace() Delete()
The x3270 key map files are sensitive to extra spaces and tab characters. Do not have anything after the
in the text lines. In this file, we indented the <Key> field starting in column 4, although this action was arbitrary. Both the Pause and the End keys are mapped to the 3270 Clear function because some keyboards no longer have a Pause key.
Here are several default mappings for x3270:
PA1 alt-1
PA2 alt-2
F13 shift-F1 (and so forth for PF13-24)
x3270 fonts
If x3270 is installed from a separate rpm, it might not have its “normal” fonts.16 In the x3270 fonts menu, there might be an option for ISO fonts. We selected the following one:
-eti-fixed-bold-r-normal--18-180-72-72-c-90-iso8859-1
The 18 that is embedded in the name is the point size. A similar choice, with 24 in this position, selected a larger font. Some x3270 versions produce error or warning messages about font mismatches when started, and these messages can be ignored if the 3270 panel function is acceptable.
5.5 Starting your new ISV zPDT system
For initial testing purposes, you might create the following file (which we arbitrarily name devmap0) in your home directory:
[system]
memory 8G
3270port 3270
processors 1
[manager]
name aws3274 1000
device 0700 3279 3274
Then, you can start ISV zPDT with the following command:
$ awsstart devmap0
You should see startup messages from ISV zPDT. If you have not yet installed an
IBM zSystems operating system, there is not much else that you can do. You can stop
ISV zPDT with the following Linux command:
IBM zSystems operating system, there is not much else that you can do. You can stop
ISV zPDT with the following Linux command:
$ awsstop
If these steps complete without errors, your ISV zPDT system is installed. If your token (or a connection to a remote license server) does not contain a valid license, you do not see a message saying zPDTA license obtained, but the startup and shutdown should work correctly.
For an initial ISV zPDT startup, install something like the above devmap example in your home directory. However, as a practical matter, we usually place our “real” devmaps (usually much larger than the above example) in the same directory as the emulated disk volumes. This action is not required, but appears to be a common choice of ISV zPDT users.
5.6 Installing a different ISV zPDT release
|
Important: New releases of ISV zPDT are typically at a new IBM zSystems architecture level. You must verify that your IBM zSystems software is suitable for the new architecture level. This verification might include the installation of “toleration” program temporary fixes (PTFs) or similar actions. Do not migrate to a new ISV zPDT release without considering your IBM zSystems software levels. The same considerations apply to installing a new large IBM zSystems machine.
|
New ISV zPDT releases are typically available through your IBM Business Partner or (for IBM employees) through IBM Resource Link. The installation procedure is the same regardless of the source. Installation is the same as described earlier.
A summary of the steps is as follows:
1. Obtain the new distribution file.
2. Working as root, run the distributed file. It deletes the previous release and installs the new release. The process takes only a few seconds and does not disturb your customization.
You might want to install an older ISV zPDT release for some reason, which is done in the same manner.
1 These specific commands were correct in earlier releases of the indicated distributions. Later releases might need slightly different names.
2 The definition of a “local” 3270 connection involves some historical background on IBM mainframes. If you are not familiar with the term, do not worry about it.
3 A different package, not generally covered in this publication, is used for IBM ZD&T systems. The proper package must be used with the correct token (1090 or 1091).
4 The three ISV zPDT versions (in each package) are needed because the three Linux bases are typically at slightly different library levels or organizations.
5 There is nothing special about user ID ibmsys1. It was a convenient choice.
6 Another option is by using the sudo facility.
7 The “./” characters before the file name tell Linux to run this file from the current directory.
8 This home directory is the one for the Linux user ID that runs ISV zPDT. It is user ID ibmsys1 in all our examples.
9 Some versions of the IBM Open Client reset these values when maintenance is applied. If this scenario occurs, you should again enter the values that are shown here and run /sbin/sysctl.
10 Do not attempt to use vi unless you have a basic familiarity with it.
11 The default value on several distributions is 1,152,921,504,606,846,720, which is huge. However, on at least one Linux distribution, the default is much lower and might need to be adjusted.
12 The Linux user ID is used as the logical partition (LPAR) name under ISV zPDT, and LPAR names are limited to
8 characters or less. (Only a subset of LPAR-like functions is provided by ISV zPDT.)
8 characters or less. (Only a subset of LPAR-like functions is provided by ISV zPDT.)
13 Directions for updating the PATH variables are given later in this chapter.
14 There are variations of x3270 available, such as x3270c that might be used but are not discussed here.
15 Users with strong z/VM backgrounds prefer this default key arrangement, and users with z/OS backgrounds (especially IBM Interactive System Productivity Facility (ISPF) usage) prefer to reassign the keys.
16 There appears to be many levels or builds of x3270 on the web, and the differences include the way fonts are installed or used. We have experimented with different versions to find one that includes the wanted fonts.
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.