Additional ISV IBM Z Program Development Tool notes
This chapter contains various notes about Independent Software Vendor (ISV) IBM Z Program Development Tool (IBM zPDT) (ISV zPDT). This information is not required for basic ISV zPDT operation, but it is helpful for better understanding ISV zPDT and for more advanced uses.
13.1 Minor ISV zPDT notes
The notes that are shown here were relevant at the time of writing, but personal computer (PC) Linux is known to have frequent minor changes or updates, so some of these notes might not apply to later versions:
•Known z/VM issue when z/VM hibernates
If an ISV zPDT base PC is running z/VM and the PC is placed in a hibernation state (by closing the laptop lid, for example) for a lengthy period, then z/VM might fail with a PRG009 ABEND message. In this example, the “lengthy period” is 17 hours. The underlying problem relates to time-of-day (TOD) clock skews on the PC, and there are multiple variables that are involved. This situation is rare, and at the time of writing is a permanent restriction for ISV zPDT.
•Linux library prune
It is possible to “”prune” a Linux system to remove unused libraries. Unfortunately, this action sometimes removes the 32-bit libraries that are needed by the SafeNet modules that are used by ISV zPDT. If you must “prune” your Linux system, you might need to reinstall the 32-bit library that is needed by SafeNet. The name of the library varies with different distributions, as described in 5.1, “Linux installation” on page 126.
•Unexpected termination
In some cases with Ubuntu (more recent releases), the ISV zPDT session might terminate under some conditions, especially if the terminal window that is used to start ISV zPDT is closed. The following command resolved this situation in one case:
sudo loginctl enable-linger
The Linux “improvement” behind this condition might migrate to other Linux distributions or might disappear. It was unexpected when we encountered it.
•S/390 Compatibility Mode
S/390 Compatibility Mode is available in IBM z15 (and later) systems and in ISV zPDT GA10 (and later). However, some functions within this mode are “model-dependent” and might react differently with an ISV zPDT “model” than with a “real” z15 or later machine. S/390 Compatibility Mode is used by the Conversational Monitor System (CMS) (running under z/VM), and is used internally by a few components of other operating systems.
Some instructions (or suboptions of certain complex instructions) that do not exist in an S/390 system might function in S/390 Compatibility Mode. Proper S/390 programming would not attempt to use such instructions (or options) because they do not exist on an S/390 system.
•Free IBM zSystems Integrated Information Processor (zIIP) processors
Starting with ISV zPDT GA8, a token license is not needed for emulated zIIP processors. However, the “free zIIPs” count toward the maximum of eight emulated processors per
ISV zPDT instance and the requirement for the number of PC cores to be at least equal to the number of emulated processors. Also, there cannot be more zIIPs than CPs.
ISV zPDT instance and the requirement for the number of PC cores to be at least equal to the number of emulated processors. Also, there cannot be more zIIPs than CPs.
You should be aware that zIIP usage by z/OS interacts with workload manager (WLM) options (and parmlib options) and in some cases can substantially reduce your system performance. If a workload is in a discretionary dispatching level and zIIP-eligible work is dispatched, then the task is dispatched only on a zIIP, even if idle CPs are available.
For example, a user with a 1090-L03 token (three licenses) that uses a PC with four cores can configure three CPs and one zIIP, which creates an ISV zPDT system with the number of CPs equal to the number of cores. Will this configuration improve performance? The usage of “free” zIIPs might appear attractive to all z/OS users (assuming that they have sufficient cores in their PC.) However, as a best practice, doing some performance testing might be a good idea because the zIIPs might add performance or, in a few cases, might harm performance.
With ISV zPDT releases GA11 and later, the “free zIIPs” are no longer a “new” offering but the situation is still confusing to some users.
•zPDT build information
The /usr/z1090/bin/librarybuild file contains information about the levels of Linux that are used to create the copy of zPDT. In general, you should not use a version of Linux that is earlier than the libraries that are noted in this file.
•Copying emulated direct access storage device volumes
Never use Linux to copy an emulated direct access storage device volume while ISV zPDT is active and potentially using that volume, that is, if the emulated volume is in the device map (devmap). For example, never use Linux cp, rsync, gzip, or similar commands to copy a potentially active volume. The Linux commands are unaware of any buffer or cache information that is held within z/OS that must be written to the volume. Violating this rule can lead to corrupted data or a corrupted emulated volume format.
When ISV zPDT is not active, any Linux commands that copy files can be used to copy (“back up”) an emulated volume. An emulated direct access storage device volume is a single Linux file. As a practical matter, the gzip command is often used to copy and compress a volume.
•Token dates and times
The ISV zPDT tokens remember the latest date and time that they obtain from the underlying Linux system. If the token sees the date or time move backward, a time cheat condition is produced, and ISV zPDT does not start.
For example, if you set the PC date ahead several months (perhaps to test an expiration function in the application that you are developing) and you use ISV zPDT with this advanced date, you cannot then return to the correct date and use the same token. If you inadvertently used an incorrect (future) date with the token and you now find the token unusable with the correct date, you should contact your ISV zPDT supplier.
If you must temporarily change the PC clock (when not using ISV zPDT), remove the token before changing the clock and reset the clock to the current time before adding the token again. If you move a token among multiple PCs, ensure that the hardware time-of-day (TOD) clocks reflect times close to each other on all the machines.1
The settod command that is provided with ISV zPDT provides a way to test software by using different dates, but it does not change the value of the PC hardware clock or the Linux software clock.
•Typing OPRMSG too many times.
The default IBM zSystems console (normally a Hardware Management Console (HMC)) is emulated by ISV zPDT by using the Linux window that was used to start ISV zPDT. Operating system output that is sent to the default console appears in the Linux window. To enter IBM zSystems commands from the default console (that is, from the Linux window), use the oprmsg command, as in this example:
$ oprmsg 'CN(*),ACTIVATE'
Typing oprmsg for every input line becomes tedious. The Linux alias function can be used to assign a single character to create the oprmsg text:
$ alias +=oprmsg (Use th plus character to create oprmsg.)
$ + 'cn(*),activate'
$ + d a,l
A space is needed after the plus sign (+) like a space is needed after the oprmsg command before the command text is entered. Single quotation marks might be needed to prevent the Linux shell from processing special characters such as parentheses.
•PC Hyper-Threading
As a best practice, PC Hyper-Threading should be disabled in the BIOS of any PC running ISV zPDT. Sometimes, you encounter z/OS “excessive spinloop” messages when running with Hyper-Threading enabled, and disabling Hyper-Threading usually eliminates these messages. While we cannot verify our assumption, we assume that z/OS is spinning on one “half” of a core, and the z/OS process that would resolve the spin is waiting for cycles on the other “half” of the same core.
With limited Hyper-Threading experimentation, we have not seen spinloop messages recently while running simple batch and Time Sharing Option (TSO) sessions. However, this absence does not mean that the spinloop situation does not exist, but means that any spinloop conflict does not last long enough to trigger a z/OS message.
All formal zPDT testing by IBM occurs with Hyper-Threading disabled. This approach is the “safe” way to run zPDT. If you have a larger server with many cores, there is probably no need to consider Hyper-Threading. If you have a common environment with an L03 token and a four-core PC and verifying zIIP processing is important to you, you might consider the experience that we related here. However, some ISV zPDT users operate with Hyper-Threading enabled and seem to experience no problems.
|
Important: We have not experimented with the C/C++ compiler SMP option. This option provides for parallelization of a program, which might create more exposure for spinloop problems when using Hyper-Threading.
We also saw problems that involved heavy z/OS Java loads (such as z/OSMF) when using Hyper-Threading.
|
•Important Linux command-line interface (CLI)
The Linux CLI that is used to enter the awsstart command is important. Asynchronous messages from ISV zPDT are sent to this window. (User commands that are sent to
ISV zPDT can be entered from any Linux window that is operating under the same user ID that started ISV zPDT). Asynchronous messages include ISV zPDT error messages (such as an unexpected channel-to-channel (CTC) disconnection) and z/OS messages that are directed to the HMC console.
ISV zPDT can be entered from any Linux window that is operating under the same user ID that started ISV zPDT). Asynchronous messages include ISV zPDT error messages (such as an unexpected channel-to-channel (CTC) disconnection) and z/OS messages that are directed to the HMC console.
If you inadvertently close the Linux CLI that is used to start ISV zPDT, you do not see these asynchronous messages. At the time of writing, there is no way to recover the function of this panel.
•Linux “out of memory”
In rare circumstances, you see an “out of memory” error message from Linux, typically when starting ISV zPDT. Assuming that your ISV zPDT runs correctly most of the time, we believe that this message is related to fragmentation of the shared memory locations in Linux. ISV zPDT uses Linux shared memory extensively, and ISV zPDT startup, shutdown, configuration change, startup, shutdown, and so forth might eventually result in an out-of-memory message. Advanced Linux users might try to rework shared memory parameters (while ISV zPDT is not running), but the easiest solution is to restart Linux. We emphasize that this condition is rare.
• The crontab and sudo entries
ISV zPDT places entries in the Linux cron tables at root level. You can see them as follows:
$ su (Change to root.)
# crontab -l (List crontab entries for root.)
@reboot /usr/z1090/bin/safenet_daemons_restart reboot > /dev/null
*/11 * * * * /usr/z1090/bin/safenet_daemons_restart > /dev/null
# exit (Leave root.)
Remote license servers and Unique Identity Manager (UIM) functions result in extra cron entries. Do not change or delete these entries if you use cron functions for other purposes. If you use the SecureUpdate_authority command, an entry is added to the Linux /etc/sudo file for every user ID that you authorize. Do not remove these entries from /etc/sudo.
•Linux disk partition full
In rare cases, you might find a Linux disk partition unexpectedly full, but normal Linux commands do not list any files that would fill the partition, and deleting files in the partition does not seem to help. (This issue is not unique to ISV zPDT, but it is something that can be frustrating to ISV zPDT users.) The following Linux commands might be useful:
su - (Switch to root to display more information.)
cd xxxxx (Change to the relevant directory or partition.)
ls -al (List the file names and sizes.)
You see no files with excessive sizes:
df -h (List sizes and the “fullness” of all the partitions.)
Your partition seems full:
du -h (Read the instructions for this command.)
ls -al . (Notice the period to help list “invisible” files.)
dmesg (Does these files seem large?)
rm .xxxx (Delete unreasonable files by using a period before the names.)
Check your partition again to see whether these commands corrected the problem.
If you do not find the full partition, try switching to different file systems or directories and running the same set of commands again. In the specific cases that we saw, the excessively large file (when it was finally found) seemed to be in the same format as typical dmesg records. (The “normal” dmesg files are typically in the /var/logs directory, but the excessively large files we found were in other locations.)
There are multiple ways that a disk partition might appear full, and the notes here are not inclusive.
•Too many directory levels
While not especially related to ISV zPDT, some Linux tools seem to create many directory levels, making it tedious to delete all the files that are involved because the common rmdir command cannot delete a directory that contains files. Change to the directory that owns the top level of the offending structure and then issue the command rm -rf xxxx (where xxxx is the offending directory name). This command deletes the named directory and anything that it holds (including subdirectories). Be careful with this command.
•Copying large Linux files
While not a specific ISV zPDT issue, you should be aware of a particular limitation in copying Linux files larger than about 4.4 GB. (We encountered this limitation when one of the z/OS Application Development Controlled Distribution (ADCD) gz files was over this size.) Most USB flash drives apparently come with FAT32 file systems, which places a limitation on the maximum file size that can be handled. In our case, there was a PC panel message (that we sometimes did not notice) about a splice error because the file was too large. In a more obscure version of the problem, the same error occurred when attempting to copy the file to a DVD. The solution (for a USB flash drive) is to change the file system format to ext4 or one of the other recent Linux file system types.2 (The error does not occur when copying between two Linux file systems that are not in FAT32 format.)
•Doing clever things with Linux disk partitions
Although not a direct ISV zPDT issue, we noted some obscure customer problems that seem to occur after manipulating disk partitions on disks that are shared among multiple Linux systems.3 The problems seemed to be related to extended partitions for the basic Linux directories. We have not seen reports of this situation from many ISV zPDT customers, but have seen it from those customers who use the same PC or disks for a dozen (or more) other operating systems, projects, configurations, and so forth.
•Odd messages about direct access storage device during initial program load (IPL)
During z/OS IPL, a number of console messages beginning with the text “CU AUTHORIZATION FAILED...” might be seen. These messages should be ignored because they do not indicate a real problem with the emulated direct access storage device volumes.
13.2 Need for Linux root operation for Open Systems Adapter
Earlier releases of zPDT required Linux root access for some functions, especially for the Open Systems Adapter (OSA) emulation function. Starting with fixes for ISV zPDT GA10, root access is no longer required.
The detailed operation of the earlier releases required a setuid permission bit for module eDMosa, which is no longer required. Instead of the setuid bit (to obtain root access), zPDT uses the Linux cap or setcap function, which should not be disabled. You can check whether these functions are enabled by running the following command:
$ getcap /usr/z1090/bin/eDMosa
/usr/z1090/bin/eDMosa = cap_net_admin,cap_net_raw+eip (expected result)
The result that is shown here, at the time of writing, was based on CentOS, so other or later Linux versions might be different.
13.3 The cpuopt statement
The cpuopt statement in a devmap specifies optional parameters for the CPs. At the time of writing, here are the valid parameters:
cpuopt asn_lx_reuse=on No blanks in the operand
cpuopt asn_lx_reuse=off No blanks in the operand
cpuopt zVM_CouplingFacility No blanks in the operand
cpuopt alr=on,zVM_Coupling Abbreviations
cpuopt ZARCH_ONLY=NO Uppercase with no spaces)
The asn_lx_reuse operand can be abbreviated as alr. The zVM_CouplingFacility operand can be abbreviated as zVM_CouplingFac or zVM_Coupling. These operands do not contain blanks, so be certain that no blank exists before or after the equal sign.
The ZARCH_ONLY parameter is new with zPDT GA8. It defaults to YES and is the standard mode of operation for IBM z14 systems. It causes the IBM z14 to undergo an IPL in normal z/Architecture mode. Specifying ZARCH_ONLY=NO4 causes zPDT to undergo an IPL in ESA390 mode, but the machine otherwise operates as a IBM z14 system. This configuration is a non-standard one that might be useful with older operating systems that are not designed to undergo an IPL in z/Architecture mode. Using this option creates an environment that is not supported by IBM, and it should be used with caution. (The ZARCH_ONLY function is sometimes documented as the CZAM facility.) Performing an IPL of an older z/OS operating system (that does not support IPL in z/Architecture mode) on a IBM z14 can produce disabled wait state 19. The ZARCH_ONLY=NO option might be useful in such situations. The default is ZARCH_ONLY=YES.
The asn_lx_reuse parameter defaults to “on”, which is the normal mode of operation for zPDT. This mode matches the relevant architecture of IBM z10 and later machines. When this parameter is set to “off”, zPDT indicates that the LX and ASN REUSE facility is not present. This mode might be useful for running early z/OS releases. The usage of alr=off produces an environment that is not supported or tested by IBM. Although this model might be useful for working with earlier z/OS releases, the user must assume all responsibility for the correctness of operation and results.
The zVM_CouplingFacility operand is significant only for IBM Z Development and Test Environment (ZD&T) systems, which must have the proper license feature to enable it. In effect, the zVM_CouplingFacility function is always present for ISV zPDT systems.
13.4 Read-only and shared direct access storage device
Emulated direct access storage device volumes can be used as read-only volumes by setting the Linux permissions to disallow writing to the Linux file that contains the emulated volume. For example, assuming that you have a 3390 volume that is stored in /z/WORK02, the following Linux command5 makes it read-only for the owner (normally, the Linux user ID that started ISV zPDT), the owning group, and all other user IDs:
$ chmod 444 /z/WORK02 (You can use other forms of chmod.)
The execute permission for the file is not relevant. A more detailed permissions setting might be used, but the result should be to prohibit write permission to ISV zPDT. An alternative method is available as an option with the awsmount command.
|
Important: Sharing, as controlled by Linux or zPDT, is not the same as “shared direct access storage device” that is controlled by z/OS.
|
Older z/OS levels
When z/OS accesses the volume, an error message might be displayed (probably due to an attempt to update the Volume Table of Contents (VTOC) statistics), but the operation continues in read-only mode.6 You can browse data sets, for example. If you attempt to change a data set (with IBM Interactive System Productivity Facility (ISPF), for example), an error message is produced, and you must cancel the SAVE operation. The error messages are like the following example:
•On the MVS console: IOS000I 0AA0,01,WRI,1D.........
•On the MVS console and TSO: IEC212I 414-04,IFG0201......
We informally used basic sequential data sets, partitioned data sets (PDSs), and PDS/E data sets without problems. We were unable to use Virtual Storage Access Method (VSAM) data sets on a read-only volume, but there might be techniques to bypass this restriction. z/OS APAR OA50068 provides z/OS support for read-only volumes and extended documentation for their use. ISV zPDT implementation of read-only (at the Linux permissions level) differs from the technique that is described in the APAR, which might produce operational differences.
Recent z/OS levels
z/OS recently added more formal support for read-only volumes, which is documented in z/OS DFSMS Using Data Sets, SC23-6855. With this support, JCL support and a degree of VSAM support are available for read-only volumes.
13.4.1 Shared read-only volumes
You can share read-only direct access storage device volumes. The sharing is done at the Linux level and not visible to z/OS. You do not use the --shared option with the awsckd entry in your devmap. Because of the read-only nature of the volumes, there is no need to coordinate Linux disk cache operations. Various Linux facilities are available to share files. The most common is NFS.
|
Important: The usage that is described here requires all access to the volume to be read-only. It is not suitable, for example, to allow one ISV zPDT system to have write access while all other sharing systems are read-only.
|
There are many ways that you might configure such an operation. The more obvious example involves sharing a direct access storage device among different zPDT instances on the same PC. A more complex example might involve NFS sharing, as follows:
1. We placed the intended read-only 3390 volumes (that is, the Linux files containing these volumes) in a separate directory (named /z3) on our first Linux system and changed the permissions on each file in the directory to read-only.
2. We started an NFS server on this Linux system and indicated that we wanted to export /z3 as read-only mode (specified as ro). We did not use NFSv4 or GSS security. Depending on your firewall status, you might need to open a port in your firewall. You can limit your export operation to specific clients or export to anyone. Other Linux systems (and more recent versions) have various methods of configuring NFS server operation, and you must use whatever interface is appropriate for your Linux version.
3. We changed our devmap to find the read-only volumes in their new directory (/z3).
4. On our second zPDT machine, we defined a mount point. In our case, we named it /z3 to match what we did on our first Linux system, but any mount point name can be used.
5. We configured an NFS client on this machine, mounting /z3 (from our server) to /z3 (on our local client).
6. On the client, we changed to root and issued a mount command:
# mount -t nfs 192.168.1.80:/ /z3
Our NFS server used IP address 192.168.1.80. We needed 192.168.1.80:/ and not 192.168.1.80:/z37 in the mount command. In principle, we should be able to see the shared volumes by issuing the ls /z3 command on the client machine. In practice, we sometimes must restart the client to have the contents of the remote /z3 directory appear on our client /z3 mount point. The following line appears in /etc/fstab:
192.168.1.80:/z3 /z3 nfs defaults 0 0 (Assuming 192.168.1.80 is the server.)
7. We changed the devmap for our second zPDT to point to the read-only volumes at their location in /z3.
8. We start ISV zPDT and perform an IPL of z/OS on the server and client. We were able to access the shared volumes (read-only) from both systems.
9. If you want to change the contents of a read-only volume, you must disable the client systems so that no “stale” information is available for volumes. In practice, this action means ending ISV zPDT operation and possibly closing down Linux. (We did not explore the exact details of this scenario.) You end ISV zPDT on the server; change the permissions for the volumes that you want to alter; start ISV zPDT; perform an IPL of z/OS; make the changes; end ISV zPDT; and change the file permissions back to read-only. Then, you can restart the client system (or systems) and ensure that they can “see” the volumes at the mount point. This scenario is not convenient, and read-only operation is not appropriate for volumes that are frequently updated.
One reason for this seemingly excessive technique is that residual data for the volume might be in various forms of z/OS caches, or in the base Linux disk cache.
We noticed that ISV zPDT start on the client was a little slower than with the previous operation and z/OS shutdown (with a quiesce command) was definitely slower. The details in these notes might change with more recent PC Linux releases, but the overall technique should be about the same.
13.5 zPDT log files
zPDT writes a number of log files that are based in the ISV zPDT user’s home directory. If Linux user ibmsys1 starts ISV zPDT, the log files are in /home/ibmsys1/z1090/logs. Most of the log types are for IBM use when working with a problem and are not interesting otherwise. The log types include the following ones:
awsstart_pnnnn_000001.log One line. Created when starting zPDT.
CPU_QUEUE_SEQMEWNT....gz For internal use only.
dv_0A8A_pnnnn_000001.log Created when starting each device.
emily_uim_pnnnn_000001.log Created when starting a UIM server.
log_console-pnnnn-t2018-11-03_10.12.00.txt Console log.
summaryFile IBM debugging only.
tnportl2_pnnnn.log Created by aws3274.
uimclient_pnnnn_000001.log Created by the UIM client start.
The “pnnnn” in these descriptions is the Linux process ID (PID) that was used. Older log files are not immediately cleared and typically have various PID numbers.
One of the log types might be more interesting to ISV zPDT users, which are the log_console files. There might be several of these files. The name includes a timestamp indicating when the log file started. In our example, the log_console was started November 3, 2018 at
10:12 AM. The log_console file includes the following information:
10:12 AM. The log_console file includes the following information:
•Start messages from ISV zPDT.
•Asynchronous messages from ISV zPDT that are displayed in the Linux command terminal that is used to start ISV zPDT.
•ISV zPDT commands that are entered in any Linux terminal window.8
•Messages from z/OS (or another operating system) that are directed to the “HMC hardware console.” These messages are displayed in the Linux command terminal that is used to start ISV zPDT.
Notice the two categories of messages that are displayed in the Linux command terminal that is used to start ISV zPDT. If this Linux command terminal is closed, these messages are not displayed anywhere but are still written to log_console.
The following Linux commands might be useful to zPDT users:
oprmsg ‘V CN(*),ACTIVATE’
oprmsg d a,l (A z/OS command)
These commands activate the “HMC hardware console” as a z/OS operator terminal. The oprmsg commands can be entered in any Linux CLI, but the resulting messages from z/OS are shown only in the Linux window that was used to start ISV zPDT and are also placed in the log_console file. If you want to automate (from Linux) the various z/OS commands and responses, these commands might be useful.
The optional oprmsg_file statement in the ISV zPDT devmap is used for direct placement of the log_console file in a different location. For example, the following stanza writes the log to /tmp/sysmessages instead of a file in the /home/ibmsys1/z1090/logs/ directory:
:[system]
memory 20G
processors 3
oprmsg_file /tmp/sysmessages
...
Numerous logs can accumulate in the default logs directory. You can clear them by using the --clean option with the awsstart command. A fix pack for ISV zPDT GA10 (and for later releases) includes changes to reduce potentially the amount of log information that is written.
13.6 Large PC memory
Large PC memory usually improves ISV zPDT performance. Large memory helps you avoid paging and provides a large Linux disk cache function. In rare cases, large PC memory9 can create a problem. A rare problem situation might be as follows:
•The z/OS workload is not using especially large memory, for example, Db2 with active large tables is not being used.
•The z/OS system is quickly producing many multiple asynchronous disk operations (especially write operations).
•RAID 5 usage might be involved. RAID 510 requires two disk writes for each logical write operation.
•The PC memory is large enough that the Linux disk cache can absorb many gigabytes of disk output without writing to disk.
•Linux decides that it has too many “dirty” pages in the cache and must write them to disk before allowing more disk operations.11
•z/OS starts seeing disk timeouts, typically as Missing Interrupt Handler (MIH) actions, and can create many error messages. z/OS usually eventually resolves the situation.
We have seen this situation when using pathological test cases. We have rarely seen it in normal usage. One extreme example that we investigated was as follows:
•The PC server had 160 GB of memory.
•z/OS was running under z/VM.
•RAID 5 was being used.
•The user defined five new, full 3390-9 volumes for Job Entry Subsystem (JES) 2 spool space.
•When cold starting JES2 the first time, it started formatting the five volumes, asynchronously, in parallel. (JES2 formatting is fast and efficient, which contributed to the overloading of the Linux I/O functions.)
•A short time later, the MVS console was flooded with MIH and other error messages. The system did not recover in this situation.
In this particular case, running the same z/OS functions without using z/VM allowed the JES2 formatting to complete. (There were still MIH and other disk error messages, but the functions completed.) Subsequent usage of the z/OS system under z/VM operated normally.
Recent Linux levels appear to better handle situations like the one that is described here. We stress that the overrun situations that are described here are rare. We often use PCs with large memory (256 GB, most recently) with no problems during “normal” z/OS operation.
13.7 Dynamic configuration changes
ISV zPDT does not support dynamic changes to an operational devmap. The selected devmap is read when ISV zPDT is started (by using the awsstart command) and any changes to the devmap after that point are not effective unless ISV zPDT is stopped and restarted.
The most common reason for wanting to change the devmap is to alter the direct access storage device configuration, usually by adding more volumes. This task can be done with a little planning. The basic requirement is to include “spare” direct access storage device devices in your devmap by using device numbers (addresses) that are valid for your input/output definition file (IODF). Here is an example:
[manager]
name awsckd ABCD
device 0A80 3390 3990 /z/H1RES1 (normal emulated direct access storage device definitions)
..... (other direct access storage device definitions)
device 0AB0 3390 3990 (spare device definition)
device 0AB1 3390 3990 (spare device definition)
You can use a spare device to add a work volume while ISV zPDT is running:
$ alcckd /z/LOCAL4 -s500 -d3390 (Create emulated volume of 500 cyls.)
$ awsmount 0AB0 -m /z/LOCAL4 (Mount on spare device.)
The new volume has no label or VTOC and cannot be varied online to z/OS. You must run an ICKDSF job:
//INITVOL JOB 1,OGDEN,MSGCLASS=X
// EXEC PGM=ICKDSF,REGION=40M
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
INIT UNIT(AB0) NOVALIDATE NVFY VOLID(LOCAL4) -
PURGE VTOC(2,1,15)
/*
This job should request the operator to reply U to allow the volume initialization. After the ICKDSF job completes, the operator can issue the VARY AB0,ONLINE command and the volume is ready for use. You probably want to change your devmap so that the volume is routinely available when ISV zPDT is started the next time.
|
Intense Linux I/O: The alcckd command, when creating an emulation volume, creates intense Linux I/O while it is formatting the volume, which might disrupt or slow concurrent z/OS operation, especially if z/OS jobs are running.
|
13.8 Security exposures
Although most ISV zPDT usage occurs in environments where base Linux security is not a concern, the following items might be of concern to some users.
13.8.1 Reducing root usage
After ISV zPDT is installed, few functions normally require running as root. The most common are the commands that are involved in updating the token licenses and the clientconfig command. You can avoid using root in this situation by completing the following steps:
1. Select a user ID (not root) of someone who is allowed to use the token update commands. These commands are SecureUpdateUtility (for zPDT releases before GA5), Z1090_token_update, and Z1091_token_update.
2. As root (probably when installing ISV zPDT), run the following command:
# SecureUpdate_authority -a <userid> (Specify your selected user ID.)
or
# /usr/z1090/bin/SecureUpdate_authority -a <userid>
The full path name for the command is needed if you are not in the /usr/z1090/bin directory when issuing the command. This command is issued only once, and it makes an entry in the /etc/sudo file. To remove a user ID from the authorized list, run the following command:
# SecureUpdate_authority -d <userid>
or
# /usr/z1090/bin/SecureUpdate_authority -d <userid>
3. Thereafter, use the sudo zpdtSecureUpdate command12 while operating as the selected user ID. This command automatically switches to the /usr/z1090/bin directory and runs the appropriate commands with root authority. The sudo function provides temporary root authority, and the zpdtSecureUpdate command temporarily switches to the required directory, runs the appropriate token administration command, and returns to the previous directory.
4. Select a user ID (not root) who is allowed to use the clientconfig command and issue the following command as root:
# clientconfig_authority -a <userid>
A user ID can be removed from the authorized list by using a -d flag instead of -a.
5. Thereafter, the indicated user ID can use the clientconfig command.
As a practical matter, the same user ID can be selected for both functions. The ability to bypass root use with these commands does not alter the operation of the SecureUpdateUtility, Z1090_token_update, Z1091_token_update, or clientconfig commands if used by root in the normal way.
Starting with ISV zPDT GA10 Fix Pack 2, the token access functions that are encountered while running ISV zPDT no longer require root access. Some administrative commands, such as the ones in this section, still require root, but routine operation of ISV zPDT no longer requires it. Table 4-1 on page 72 lists the specific commands that require Linux root authority. The OSA emulation function of ISV zPDT no longer requires Linux root access.
13.8.2 Gen1 token server monitoring
Although it is not part of the IBM zPDT product, the Gen1 token software that is provided by the company supplying the license tokens and associated software has a web monitoring function. This function is not relevant to normal ISV zPDT operation, but it might be construed as an exposure. You can disable this monitor function as follows:
# cd /opt/safenet_sentinel/common_files/sentinel_keys_server
# cp -p sntlconfigsrvr.xml sntlconfigsrvr.xml.orig (Make backup.)
# (edit sntlconfigsrve.xml, find <ConfigureLicenseMonitorPort>
and change 7002 to 0)
# ./loadserv restart
13.9 z1090instcheck
The z1090instcheck command should be run after ISV zPDT software is installed and Linux configuration changes are completed. It should be run again after any Linux updates. The output varies somewhat from release to release. Here is an example of the output from z1090instcheck:
1. SUSE os level at 11.4 which is greater the minimum level OK
2. SUSE kernel.shmmax of 36000000000 is greater than min. *NOTE*
shmmax should be greater than 1.1 times the sum
of z memory (as specified in your devmap) for
ALL your 1090 instances.
3. SUSE (kernel.shmall * PAGE_SIZE) is 4722366482869644165120
which is greater/equal to kernel.shmmax which is OK
4. SUSE kernel.msgmni is 512 which is OK
5. SUSE kernel.msgmax is 65536 which is OK
6. SUSE kernel.msgmnb is 65536 which is OK
7. SUSE net.core.rmem_default is 1048576 which is OK
8. SUSE net.core.rmem_max is 1048576 which is OK
9. SUSE kernel.core_uses_pid is 1 which is OK
10. SUSE kernel.core_pattern is core-%e-%p-%t which is OK
11. SUSE ulimited -c is set to unlimited OK
12. SUSE ulimited -d is set to unlimited OK
13. SUSE rpm libstdc++45-32bit-(x86_64) is installed OK
14. SUSE sntl-sud-7.5.2-0.i386 rpm is greater than required OK
15. SUSE zpdt-shk-server-1.3.1.2-0.i586 rpm is equal to required level OK
16. SUSE dmidecode-2.11-15.1.x86_64 rpm is greater than required OK
17. SUSE rpm beagle is not installed which is OK
18. SUSE rpm zmd is not installed which is OK
Running uimcheck ...
The UIM client is configured in remote mode.
Local Host Name....... w510.itso.ibm.com
Local Serial Number... 32683
Local machine UUID.... 81402112-2551-CB11-A1F3-D9473378A894
Remote server......... 192.168.1.2
Remote server port.... 9451
The output details include the following lines:
•Line 1 verifies that you are using SUSE (or Red Hat or Ubuntu) and that it is at an acceptable level.
•Lines 2 and 3 check kernel controls for virtual shared memory. The values that are shown here are examples. The shmmax value should be at least as large as stated in the note. The shmall value that is shown is typical of a 64-bit Linux distribution. However, some distributions have this number set much smaller and you might receive a warning message for this line.
•Line 4 (msgmni) is appropriate for a reasonable number of ISV zPDT I/O devices.
•Lines 5 and 6 are needed for OSA operation. The exact values are not important but should be larger than the default sizes in most distributions.
•Lines 7 and 8 reflect values for heavy OSA usage or larger frames.
•Lines 9, 10, and 11 reflect parameters for core image files. These files are potentially important if ISV zPDT problems are encountered.
•Line 12 should be set as shown.
•Lines 11 and 12 are for the token modules and verify that the correct levels are present. The levels that are distributed with ISV zPDT should not be replaced with other versions, even if the other versions have later levels.
•Line 13 verifies that 32-bit support is installed with Linux, which is needed by the token modules.
•Line 16 reflects a module that might be useful for debugging. It is not critical.
•Lines 17 and 18 address applications that caused ISV zPDT problems in the past.
Additional checks might be added to later versions of z1090instcheck. Some checks are absolute, and others look for values in a range that is appropriate. Your output from z1090instcheck might differ slightly from what is shown here as minor details can change with ISV zPDT updates or new Linux distributions.
The evaluations that are listed by this command might not be required for your system. The command output is intended as a starting point only.
13.10 CKD versioning
A function is available to allow an emulated 3390 volume to be “reset” to a selected point in time. This function is known as CKD versioning. The usage is as follows:
•A command is issued for selected emulated volumes (which might be all the emulated volumes in your configuration) to enable versioning. This task must be done when
ISV zPDT is not active.13
ISV zPDT is not active.13
•ISV zPDT is started; an IPL of an operating system is done; and the volumes are used normally.
•Later (when ISV zPDT is not running), commands are issued to either commit whatever changes were made to the volumes or restore the volumes to the exact content they had when CKD versioning was enabled.
A typical usage might be for a demonstration or benchmark. After the demonstration or benchmark is completed, the volumes can be restored to their original state.
A CKD-emulated volume can be considered to have two versions. Version zero is the original state of the volume and version one is a volume that was changed after versioning was enabled. Only one restore version is possible for changed volumes, that is, multiple concurrent generations of versions are not possible.
The following commands are associated with CKD versioning:
$ alcckd /z/WORK01 -ve Enable versioning for the indicated volume.
$ alcckd /z/WORK01 -vr Restore the volume to the original content.
$ alcckd /z/WORK01 -vc Commit the changes to the volume.
$ alcckd /z/WORK01 -vi Inquire about the versioning status of the volume.
$ alcckd /z/WORK01 -vd Disable versioning (if no changes were made).
These examples use an emulated volume that is stored in /z/WORK01. You specify the name of the Linux file containing your volume.
When changes are made to a track of a version-enabled volume, the original track contents are saved at the end of the emulated volume file. Only one “original track” is saved, and subsequent changes to the track update the track within the emulated volume. If the volume is restored, the original tracks replace the changed tracks. If the changes are committed, the original tracks are discarded. Restoring or committing a volume results in a volume that is not enabled for versioning. It can be enabled again with the -ve option.
The version-enabled status of a volume is carried over subsequent ISV zPDT starts and stops, and subsequent operating system IPLs. The version-enabled status remains until the volume is restored or committed. The Linux file size for the emulated volume grows as more “original tracks” are stored. In an extreme case, where every track on the volume is changed, the Linux file grows to twice its original size. In typical cases, relatively few tracks on a volume are changed through normal usage and the Linux file growth is minor.
If versioning was enabled for a volume but there were no changes to the volume, the -vd option can be used to disable versioning. If there were changes to the volume (causing the versioning function to start operation), then the -vd option is rejected. You must use -vr (to restore the volume to the original state) or -vc (to commit the changes) to disable the versioning function. The -vi (inquiry) option displays the current versioning state of the volume and, if versioning is active, displays the number of CKD tracks that were versioned.
13.11 ISV zPDT messages
Most messages that are issued by ISV zPDT have unique message numbers. The msgInfo command can be used to obtain more information about a message. An example of its usage might be as follows:
$ awsckmap aprof1 (Check your devmap.)
AWSCHK200I Checking DEVMAP file 'aprof9' ...
AWSCHK204I Processed 204 records from DEVMAP /home/ibmsys1/aprof1
AWSCHK208I Check complete, 0 errors, 0 warnings detected.
$ msgInfo AWSCHK208I
AWSINF010I Format:
AWSINF013I AWSCHK208I Check complete, %d error%s, %d warnings detected.
AWSINF013I
AWSINF011I Description:
AWSINF013I The DEVMAP check is complete.
AWSINF013I
AWSINF012I Action:
AWSINF013I Informational message only. No corrective action is needed, but
AWSINF013I if errors are present, the DEVMAP cannot be used to start the system.
All message numbers are in the form AWScccnnns, where:
•ccc is the component code issuing the message.
•nnn is the message number within the component.
•s is the message severity (Debug, Information, Warning, Error, Severe, or Terminal).
The message code that is specified on the msgInfo command can omit the AWS prefix and the severity code. For example, msgInfo chk208 is sufficient. There is also an environment variable that is named Z1090_MSG that controls message formatting. It can be set to FULL (the default), CODE (prints only the message number and no text), TEXT (prints the message text and no code), or SHORT (drops the AWS prefix on the message number).
13.12 Linux TCP/UDP ports
Several Linux TCP/IP ports are used by normal ISV zPDT operations. In most cases, a default port number is used and you should be aware of these port numbers. When using these ports for connections outside your base Linux machine, you must ensure that any firewall permits the usage of these ports. The port information is as follows:
•The ISV zPDT token device is accessed through TCP/UDP and requires a port number. Linux port 9450 is assigned for this device. The UIM function uses Linux port 9451, which is meaningful only when using a remote license manager.
•The Gen2 license server, if used, uses port 1947.
•If you use the awsctc device manager, it uses Linux port 3088 by default. Additional CTC devices use different port numbers, typically 3089, 3090, and so on.
•The aws3274 device manager (for “local” 3270 connections) typically uses Linux port 3270.
•The migration tool (see Chapter 15, “Direct access storage device volume migration” on page 313) uses port 3990 by default.
•The Server Time Protocol (STP) function uses port number 4567 by default.
•The SafeNet Gen1 license manager provides a status web display page by using port 7002. This manager is not part of the IBM zPDT product, but it is provided with the SafeNet software that manages the token activities.
•If you are operating your base Linux system through VNC, the default ports are 5900+N, where N is the VNC display number.
13.13 Remote operation
An ISV zPDT system (including z/OS) can be operated remotely by using a Linux CLI (Telnet, VNC, or SSH) and TN3270e sessions that are connected to the base Linux on the ISV zPDT system. No special techniques or setups are required. As with local operation, connecting the TN3270e session for the z/OS console before doing an IPL of z/OS is important.
Security considerations in your environment determine whether simple Telnet or the more secure SSH should be used for the Linux CLIs that are used to control ISV zPDT.
Complete remote operation of a Linux system running ISV zPDT might be most convenient when using VNC. When using VNC, it is most convenient to start ISV zPDT from a VNC window so that the owner can disconnect the VNC session and reconnect to it later without affecting ISV zPDT operation. Managing the VNC server on the base Linux system typically requires a Linux command-level connection with something like Telnet, SSH, or PuTTY.
13.14 ISV zPDT devices
The current version of ISV zPDT has a maximum of 2048 emulated I/O devices for an instance. If you define more than approximately 100 devices, you might need to change Linux kernel definitions. You might need to alter the following items:
•The total amount of Linux shared virtual memory, which is set by the kernel.shmall parameter.
•The amount of Linux shared virtual memory that is available to a process, which is set by the kernal.shmmax parameter.
•The maximum number of shared memory segments, which is set by the kernel.shmmni parameter.
•The parameter that relates to the number of Linux semaphores that are available, which is the kernel.msgmni parameter.
•The number of semaphore devices that are available, which is set by the kernel.sem parameter.
The default values for these parameters appear to vary considerably with various Linux releases. In many cases, the default shmall and shmmax parameters are large and do not need to be changed. The other parameters might need to be changed.
Each I/O device that is defined in your devmap requires approximately 300 KB of shared virtual memory. The total of this virtual memory, plus the memory that is defined for your
IBM zSystems server, must be within the allowed total Linux shared virtual memory. Your defined IBM zSystems server memory size (plus 20% overhead) must fit within the shared virtual memory that is available for a process.
IBM zSystems server, must be within the allowed total Linux shared virtual memory. Your defined IBM zSystems server memory size (plus 20% overhead) must fit within the shared virtual memory that is available for a process.
The ISV zPDT developers do not have exact formulas for these parameters. The default numbers that are created by the /usr/z1090/bin/aws_sysctl script are reasonable for typical ISV zPDT systems with a few dozen defined devices and around 10 - 20 GB that are defined for IBM zSystems server memory.
We found the following formula for msgmni to be reasonable:
kernel.msgmni = (350 + 3 * number of I/O-devices)
This formula is not exact, but it should produce safe values. Also, if you have more than approximately 128 emulated I/O devices, you should use the ulimit -m and -v statements that are described in Chapter 5, “ISV IBM Z Program Development Tool installation” on page 125.
Using multiple ISV zPDT instances, each with many devices, might exhaust the semaphore space in Linux, which results in a hang when starting an ISV zPDT instance. This issue might be addressed by another kernel parameter:
kernel.sem 250 32000 32 128 (default values in some distributions))
kernel.sem 250 32000 250 1024 (You might try these values.)
Unusually large numbers of I/O devices (across multiple ISV zPDT instances), generally in excess of a total of more than about 1200 devices, can require a higher shmmni value:
kernel.shmmni 8192 (Default is typically 4096.)
In one rather large case, by using 2048 devices in a single ISV zPDT instance, we defined the following values:
kernel.shmmall=4300000000
kernel.shmmax=10000000000 (Make larger for larger IBM zSystems server memory.)
kernel.shmmni=32000
kernel.msgmni=6500
These numbers might not be optimal, but they worked for us.
13.15 Startup scripts
We created several startup scripts for our z/OS ISV zPDT system, such as this example:
$ gedit start00
cd /home/ibmsys1
awsstart aprof1
sleep 6
echo ISV zPDT started
x3270 -port 3270 mstcon@localhost &
sleep 2
x3270 -port 3270 tso@localhost &
sleep 5
ipl a80 parm 0a8200
sleep 2
echo IPL issued
Using this script, you can start your system with a single ./start00 command. The scripts (differing only in the IPL parm data) are trivial and can be enhanced in many ways. Be certain to allow sufficient time for the 3270 sessions to start before running the IPL command.
A better alternative to a Linux startup script is to embed Linux commands in the ISV zPDT devmap, as described in 3.2, “System stanza” on page 50.
13.16 Suspension and hibernation
Laptop PCs with Linux software offer suspend (“save to RAM”) and hibernation (“save to disk”) functions to save the current PC state and move to a non-operational state that uses little power. ISV zPDT is not tested for and does not support these functions. These functions become problematic when timed token drivers or time-dependent LAN connections are involved, such as with ISV zPDT license servers.
Some ISV zPDT users reported using these functions successfully. One technique is to use a z/OS quiesce command before the suspend operation, which allows z/OS to complete in-progress I/O and prepare other internal operations for a restartable disabled wait. After restarting the PC, an ISV zPDT restart command (entered in the same ISV zPDT operations window that was visible before the hibernation) should cause z/OS to resume operation.
We had erratic experiences with this approach on different PCs and different Linux versions. In one case, using Fn-7 after “opening the lid” restored the graphic window and the restart command worked as expected. In another case, we could not restart the graphic window, but in yet another case the graphic desktop restarted by itself.
Some users reported that the token driver or license manager did not restart. A common symptom is an “invalid license” or “heartbeat missing” for one or more CPs.14 Linux commands such as the following ones might help:
•# service shk_usb restart (older Linux)
•# service sentinel_shk_server restart (older Linux)
•# systemctl start sentinel-shk-usb.service (more recent Linux systems)
•# systemctl start sentinel-shk-server.service (more recent Linux systems)
The systemctl command might be more appropriate than service, depending on the Linux distribution. The action parameter can be start or restart.
You must determine whether hibernation or suspension works for you. It is a Linux function, and not part of ISV zPDT.
13.17 Channel measurement blocks
With ISV zPDT GA9 and later, certain fields in channel measurement blocks are meaningful for ISV zPDT users, as shown in Figure 13-1. As specified in the IBM zSystems architecture, the unit of timing is 128 microseconds.
Figure 13-1 Channel Command Blocks
Equivalent fields in a subchannel extended measurement word have a granularity of 0.5 microseconds. The data in the measurement blocks (and measurement word) might not match what is found on a large IBM zSystems server. Various Linux cache and ISV zPDT buffer operations (not visible to z/OS) can result in measurement times that appear impossibly short for a standard IBM zSystems server.
13.18 x3270 scripting
The x3270 emulator has a scripting function that is not well documented. Web searches for “x3270 scripting” and “x3270if” are good starting points. The following partial script starts an x3270 session (so you can follow the action by watching it) and logs on to TSO. This script15 is entered into a simple Linux file in your home directory, and this file is later run.16
#!/bin/bash
x3270 -socket & (Start the x3270 session.)
pid=$! (no internal spaces here)
until x3270if -p $pid ''''> /dev/null (four single quotation marks without spaces)
do sleep 0.1
done
x3270if -p $pid 'connect(“localhost:3270”)'
x3270if -p $pid 'wait()' (wait until 3270 unlocks at writable field)
x3270if -p $pid 'string(“logon ibmuser”)'
sleep 3 (optional; helps watching action)
x3270if -p $pid 'enter'
x3270if -p $pid 'wait()'
sleep 3 (optional)
x3270if -p $pid 'string(“xxxxxxxx”)' (the TSO password)
x3270if -p $pid 'enter'
x3270if -p $pid 'CloseScript()' (See following note.)
The CloseScript functions leave the x3270 session running. You can manually enter whatever TSO commands that you want to use. The wait function is blocked until the 3270 keyboard is unlocked and the cursor is positioned on a writable field. The quit function (not documented) ends the x3270 session.
The scripting function provides multiple ways to save the 3270 panel output, but it does not provide a way to wait for a particular output string. A user can save the current 3270 panel (in ASCII character format) and use Linux shell commands to search the saved data for whatever keywords are needed, but this method quickly turns into a substantial effort in Linux shell programming.
Among the other functions that are documented for x3270 scripting is the MoveCursor(row,col) function. The row and col parameters in this function are zero-based, and the row and column numbers that are displayed at the bottom of an x3270 panel are one-based.
13.19 Scenarios for awstape
The practical usage of the ISV zPDT awstape device manager can be a bit confusing to users without hands-on experience with mainframe tape units. The physical mounting of a tape volume on a tape drive, and the reading, writing, and positioning of the “tape” that is involved, must be emulated. The ISV zPDT awsmount command emulates the physical mounting of a tape volume and the ISV zPDT ready command emulates a tape drive (with a mounted tape) going from not-ready to the ready state. Both of these commands produce an emulated interrupt that informs the IBM zSystems operating system of the action.
There is only one awstape format. The IBM zSystems operating system (working with devmap definitions) handles an emulated tape drive as an IBM 3420, 3480, 3490, or 3590 drive, with appropriate commands for the specified drive type. However, the Linux file that is created (containing the emulated tape volume) is the same in all cases. For example, you can create an awstape volume by using an emulated 3420 drive and later read it by using an emulated 3490 drive.
The following scenarios describe several approaches to using awstape.
13.19.1 Creating a labeled tape volume
Consider the following job that calls for a standard label tape volume with the volume serial TAPE99. Furthermore, assume that we do not have an awstape volume with volser TAPE99.
//OGDEN30 JOB 1,OGDEN,MSGCLASS=X
// EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN DD DUMMY
//SYSUT2 DD UNIT=561,VOL=SER=TAPE99,DSN=MY.TAPE,DISP=(NEW,KEEP)
//SYSUT1 DD DISP=SHR,DSN=OGDEN.CARD.SEQ
The z/OS console interaction for this job might be as follows:
JOB01855 IEF403I OGDEN30 - STARTED - TIME=14.32.27
JOB01855 *IEF233A M 0561,TAPE99,,OGDEN30,,MY.TAPE
(In a Linux CLI, enter awsmount 561 -m TAPE99.aws.)
JOB01855 IEC512I LBL ERR 0561, ,NL,TAPE99,SL,OGDEN30,,MY.TAPE
JOB01855 *IEC704A L 0561,TAPE99,SL,NOCOMP,OGDEN30,,MY.TAPE
JOB01855 *09 IEC704A REPLY 'VOLSER,OWNER INFORMATION','M'OR'U'
JOB01855 R 9,TAPE99
JOB01855 IEC705I TAPE ON 0561,TAPE99,SL,NOCOMP,OGDEN30,,MY.TAPE,MEDIA1
JOB01855 IEC205I SYSUT2,OGDEN30,FILESEQ=1, COMPLETE VOLUME LIST, 066
DSN=MY.TAPE,VOLS=TAPE99,TOTALBLOCKS=1
JOB01855 IEF234E K 0561,TAPE99,PVT,OGDEN30
The IEF233A message requests that the operator mounts tape volume TAPE99 on tape drive 0561. Then, the job waits until the operator mounts the requested tape. The ISV zPDT user must enter an awsmount command in a Linux CLI. This action satisfies the z/OS mount request. In the example here, we specified Linux file name TAPE99.aws.17 This Linux file name is arbitrary, and it does not need to contain the tape volser or an aws suffix. As a best practice, use a naming convention. In this example, file TAPE99.aws is created in the Linux directory that was used to start ISV zPDT. Alternatively, a complete Linux path name can be specified.
In this example, after the awsmount command is issued z/OS attempts to read the standard label but there is nothing in the file. This situation outputs the z/OS messages that are shown and allows the z/OS operator to enter the volume serial number. After this task is done, the job runs and presumably writes data on the tape. At the end of the job, the tape is [logically] dismounted, as shown by the IEF234E keep message.
The -m flag in awsmount indicates a simple mount function. If there is already a tape volume that is logically mounted on the drive, an -o flag specifies that whatever emulated tape file is mounted is replaced by the newly specified file. There are many more awsmount options that are described in 4.2.18, “The awsmount command” on page 84.
13.19.2 Quick SL volume creation
You can use the aws_tapeInit command to create a standard label awstape volume with no data and with minimal label information. Here is an example:
$ aws_tapeInit tape01 /tmp/mywork/TAPE01
This command creates a Linux file (/tmp/mywork/TAPE01) in awstape format with the standard label TAPE01. (The conversion of the volume serial to uppercase Extended Binary Coded Decimal Interchange Code (EBCDIC) is automatic.) The new volume is a Linux file, and the command does not perform a mount function.
13.19.3 Using an existing labeled tape
If you run the IEBGENER job in the previous example and want to use an existing awstape volume, the console interaction might be as follows:
JOB01855 *IEF233A M 0561,TAPE99,,OGDEN30,,MY.TAPE
(In a Linux CLI, enter awsmount 561 -m TAPE99.aws.)
JOB01855 IEC205I SYSUT2,OGDEN30,FILESEQ=1, COMPLETE VOLUME LIST, 066
DSN=MY.TAPE,VOLS=TAPE99,TOTALBLOCKS=1
JOB01855 IEF234E K 0561,TAPE99,PVT,OGDEN30
In this case, the TAPE99.aws in the awsmount command should specify the Linux file that holds the awstape volume.
13.19.4 Automatically premounting an existing labeled tape
We can use the ISV zPDT awscmd device manager (described in Chapter 11, “The awscmd device manager” on page 227) to issue the awsmount command for an existing awstape volume. An example is as follows:
//MNTCMD JOB 1,OGDEN,MSGCLASS=X
// COMMAND 'VARY 561,ONLINE'
// COMMAND 'UNLOAD 561'
//* Use either PARM or SYSIN to specify the awsmount command.
//AWSCMD EXEC PGM=AWSCMD
//STEPLIB DD DISP=SHR,DSN=OGDEN.LIB.LOAD
//SYSPRINT DD SYSOUT=*
//TAPE DD UNIT=(560,,DEFER),LABEL=(1,BLP),VOL=SER=123456,DSN=X
//SYSIN DD *
awsmount 561 -m /z/zos23/TAPE99
//*
// EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN DD DUMMY
//SYSUT1 DD DISP=SHR,DSN=OGDEN.ASM
//SYSUT2 DD DISP=NEW,VOL=SER=TAPE99,UNIT=561,DSN=OGDEN.TAPE.DATA
While working with this technique, we noted the following points:
•The VARY and UNLOAD commands (in lines 2 and 3 of the example) were necessary to avoid device status conflicts.
•The AWSCMD step mounts a standard label tape volume (by using the awsmount command) that z/OS has not yet requested. This action invokes the z/OS automatic volume recognition (AVR) function, making the volume available for a subsequent request for the volume.
•The example uses in-stream SYSIN to provide the awsmount command. A more general approach would point to a data set containing the awsmount command, which might have been generated by an earlier job or job step.
•The TAPE DD statement in the AWSCMD job step points to the “dummy” tape that is used by the awscmd function. For more information, see Chapter 11, “The awscmd device manager” on page 227.
This technique requires experimenting with the setup and JCL to make it work. However, this general approach might be considered by ISV zPDT users working toward an automatic tape library function.
13.19.5 Using special channel command words to manipulate tape volume
zPDT GA9 and later provides two special channel commands for working with awstape. These functions were requested by many ISV zPDT customers. The active devmap must specify the --MNTCCWS option on the awstape name statement to enable this function.
Channel command 4B is used to change the Linux file that is associated with an emulated tape unit. Channel command 54 is used to obtain the Linux file name that is associated with an emulated tape unit. These operations are not reflected on the IBM zSystems operating system in any way: They do not create device interrupts, and they cannot satisfy a z/OS operating system mount request.
These channel command words (CCWs) are of limited use with z/OS because z/OS wants to control all device mounts and dismounts, and attempts to read standard labels even if JCL specifies an unlabeled tape (UNLABB). Other IBM zSystems operating systems might have more permissive tape drive usage and might find these CCWs more useful.
A slightly complicated example of using these CCWs with z/OS is as follows:
//TAPECCW2 JOB 1,OGDEN,MSGCLASS=X
// EXEC ASMACLG,PARM.C='NOXREF',PARM.L='NOLIST,NOMAP'
//C.SYSIN DD *
TAPECCW CSECT
STM 14,12,12(13) Save caller's registers
LR 12,15 Use entry-point as base register
USING TAPECCW,12
LR 2,13 Get @caller's savearea
LA 13,SAVEAREA Get @my savearea
ST 2,SAVEAREA+4 Chain old to new
ST 13,8(2) Chain new to old
* Open tape drive.
A OPEN STAPEO Assume BLP on DD statement
TM STAPEO+48,X'10' Did OPEN work?
BZ ERROR1 If not, branch
* Write the name of th target awstape file (the name is coded as a constant in this example).
D MVC SECB,=F'0' Zero your ECB
LA 1,SCCMOUNT @(CCW)
ST 1,SIOB+16 Place address in IOB
LA 2,L'PARM Get length of Linux file name
STH 2,SCCMOUNT+6 Put length in CCW
D1 EXCP SIOB Run the CCW
WAIT ECB=SECB Wait for it
D2 TM SECB,X'20' Completed OK?
BZ ERROR2 If not, branch
* Read the Linux file name that is mounted (to verify the mount).
C MVC SECB,=F'0' Zero your ECB
LA 1,SCCRNAME @(CCW)
ST 1,SIOB+16 Place address in IOB
C1 EXCP SIOB Run the CCW
WAIT ECB=SECB Wait for it
C2 TM SECB,X'20' Completed OK?
BZ ERROR3 If not, branch
CLOSE CLOSE (STAPEO)
RETURN L 13,4(13) Get @(caller's save area)
LM 14,12,12(13) Restore caller's registers
SR 15,15 Assume return code 0
BR 14 Exit
* Problems
ERROR1 ABEND 1 OPEN failed for TAPE
ERROR2 ABEND 2 Error with mount CCW
ERROR3 ABEND 3 Error with query CCW
*
* Constants and work areas
*
SAVEAREA DC 24F'0'
STAPEO DCB DSORG=PS,MACRF=(E),DDNAME=TAPE,DEVD=TA
PARM DC C'/z/zos23/UNLABC' a Linux awstape file with this name
BUFF1 DC CL64' ' Buffer for reading current file name
DS D'0'
SCCMOUNT DC X'4B',AL3(PARM),X'20',AL3(0) Mount awstape
SCCRNAME DC X'54',AL3(BUFF1),X'20',AL3(64) Read Linux name
SECB DC F'0'
SIOB DC X'43000000' IOBFLAG1, FLAG2,SENSE
DC A(SECB) A(ECB)
DC 2F'0' CSW (& Residual count)
DC A(0) A(CCW)
DC A(STAPEO) A(DCB)
DC 2F'0'
LTORG
END
/*
//G.TAPE DD UNIT=(561,,DEFER),LABEL=(1,BLP),DSN=X,
// VOL=(,RETAIN,,,SER=UNLABB)
//*
// EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN DD DUMMY
//SYSUT2 DD SYSOUT=*,DCB=(LRECL=50,BLKSIZE=50,RECFM=F)
//SYSUT1 DD UNIT=561,LABEL=(1,BLP),DSN=X,VOL=(,RETAIN,,,SER=UNLABB),
// DCB=(LRECL=50,BLKSIZE=50,RECFM=F)
The flow of this job might not be obvious. Here are some details about it:
•z/OS requires that a device (an emulated tape drive in this case) must be “open” before it can be accessed.18
•The TAPE DD statement in the first job step specifies a tape volume (UNLABB). When the job is run, the ISV zPDT user must use the ISV zPDT awsmount command to mount an unlabeled awstape volume to satisfy the z/OS mount request. The tape volume that is mounted this way is not used. Instead, it is needed to allow the OPEN function to complete so that commands can be sent to the tape drive.
•The TAPECCW program (in the example) uses the CCWs to change the Linux file name that contains the awstape volume. In this example, the new Linux file name is coded in the program (/z/zos23/UNLABC), but a more realistic approach probably would have the name in another data set.
•The mount CCW (4B) is followed by the query CCW (54). The query reads the same name that was mounted. However, the query must be coded and cannot be command-chained to the mount CCW. Failure to follow the mount with the query results in an ABEND 214-08 when a CLOSE is issued.19
•Conversion of the Linux file name from EBCDIC to ASCII (for mount) and ASCII to EBCDIC (for query) is automatic.
•The second job step, an IEBGENER utility that represents an application program, has a DD statement specifying the same UNLABB that was specified in the first step and passed to the second step through the RETAIN option. However, the first step changed the actual file to be used (/z/zos23/UNLABC).
•This mount CCW (4B) does not perform a z/OS mount, that is, there is no mount interrupt that is generated and z/OS is unaware that the awstape volume name was changed in the background.
•The new Linux awstape file that is mounted is positioned at the beginning of the file but is not opened (at the Linux level of open) until a read or write command is directed to it.
•The mount CCW (4B) points to the Linux file name. The length field in the CCW must be correct and not include trailing blanks with the Linux file name. The length field for the query command in the example is arbitrary. You probably have a buffer longer than needed and use the residual count from the I/O buffer to determine the actual length of the returned data. In the example, the query data is not examined.
•The general flow that is described here is unlikely to work for labeled tapes in z/OS.
These CCWs were requested by several ISV zPDT users. Some experimentation might be needed to effectively use them.
13.19.6 Premounted tape
It might be convenient to mount an emulated tape that is ready to use without MVS console interactions after z/OS undergoes an IPL. There are several ways to approach this task depending on your exact requirements. As a starting point, assume you have a standard labeled tape volume (an “awstape” volume) in /home/ibmsys1/TAPE01. Assume that the tape (with a tape label) was previously created. In these examples, we assume that your z/OS IODF defines address 561 as a 3480 device.20 There is nothing unique to 3480 drives in these examples: We use them to present concrete definitions and commands.
Complete the following steps:
1. You can include the tape in your devmap definitions. For example:
[manager]
name awstape 3000
device 561 3480 3480 /home/ibmsys1/TAPE01
After starting ISV zPDT and performing an IPL of z/OS, you can run one job by using this volume without encountering any z/OS mount messages. The job should contain a DD statement like the following one:
//SYSUT2 DD DISP=(OLD,KEEP),VOL=SER=TAPE01,UNIT=561,DSN=MY.DATA
The DISP also could be NEW. After the first z/OS job that uses this tape completes, the tape is logically dismounted and more uses produce z/OS console MOUNT messages. In general, you respond to these messages through a Linux CLI with the following command:
$ awsmount 561 -m /home/ibmsys1/TAPE01
2. Instead of including the tape file name in the device statement, you can include a command in the devmap, such as:
[system]
memory 8G
processors 3
3270port 3270
command 2 x3270 localhost:3270
command 2 awsmount 561 -m /home/ibmsys1/TAPE01
...
...
[manager]
name awstape 3000
device 561 3480 3480
The usage is the same as in the previous example, that is, the tape is automatically mounted for the first (and only the first) job that calls for it.
3. After z/OS undergoes an IPL21 but before the z/OS job is submitted, you can enter the following command through a Linux CLI:
$ awsmount 561 -m /home/ibmsys1/TAPE01
This command provides an unsolicited mount and triggers the AVR function in z/OS. The next z/OS job that calls for the tape volume immediately runs without producing any MVS console MOUNT messages.
4. You can issue a mount command from the MVS console:
MOUNT 561,VOL=(SL,TAPE01)
This command produces a mount message on the MVS console. Enter the awsmount command through a Linux panel:
$ awsmount 561 -m /home/ibmsys1/TAPE01
This usage differs from the other examples in that the tape volume remains mounted after the jobs that are using it end. You can repeatedly submit jobs that use the volume without producing mount messages on the MVS console. (This same technique can be used for a non-labeled tape.)
5. Many z/OS systems invoke the VTAMAPPL program during system startup. This program runs a series of MVS commands (a “script”). The MOUNT command can be included in this script. For example, a recent z/OS ADCD system has a script in parmlib member VTAM00 that can be modified like the following stanza:
S RRS,SUB=MSTR
S TSO
...
...
PAUSE 2
VARY 561,ONLINE
MOUNT 561,VOL=(SL,TAPE01)
PAUSE 2
VARY 561,ONLINE
This example assumes that you included the file name (/home/ibmsys1/TAPE01 in our examples) in the device statement in the devmap. This method results in the tape staying mounted for use in multiple jobs. The second vary 561,online command might be necessary to complete the mount. In some cases, the mount remains pending after vary 561,online. In this case, a ready 561 command from a Linux console completes the mount.
13.19.7 The awstape utilities
ISV zPDT users sometimes build a substantial “tape” library on disk, which is all in awstape format. The tapeCheck command can be used to verify that a file (that corresponds to a tape volume) is in the correct awstape format:
$ tapeCheck /z/TAPE01 (Verify th format of the awstape file.)
The tape2file command copies an awstape file to a simple byte stream in a Linux file and removes the awstape control blocks within the file:
$ tape2file /z/mytape /tmp/filex
The card2tape command copies a Linux text file (in ASCII or EBCDIC) to an awstape file as 80-byte records by using the same conversion conventions as the awsrdr device manager:
$ card2tape /tmp/myLinux.stuff /z/tape01 (Copy without conversion.)
$ card2tape -a /tmp/myLinux.xyz /z/tape01 (Force conversion of ASCII to EBCDIC.)
The tape2tape command copies an emulated tape volume (an awstape file in Linux) to another emulated tape volume (another awstape file in Linux):
$ tape2tape /tmp/old.tape /z/new.tape
$ tape2tape -i -s /tmp/old.tape (Scan and summarize tape content.)
$ tape2tape -c /tmp/old.tape /mine/new.tape (Copy and compress.)
The -s flag (scan flag) prevents the creation of an output file. The -i flag displays a summary of the contents of the input tape. This command is normally used to compress or decompress an awstape volume or to scan the content. A simple copy of an emulated tape volume (without any additional processing) is easily done with the Linux cp command.
The tapePrint command lists the contents of an emulated tape volume. Data is displayed in hex and character format. The characters are assumed to be EBCDIC unless the -a flag is used:
$ tapePrint /tmp/my.awstape.file
$ tapePrint -a /tmp/my.awstape.file | more
Both the card2tape and tape2tape commands can produce compressed awstape files.
1 This statement is a technical one. Your zPDT license agreement might restrict this usage.
2 We assume that changing a USB flash drive file system format results in the deletion of whatever files are on the USB flash drive. Be careful.
3 In one instance, the problem appeared to be local area network (LAN) operations that worked in some instances but failed (for no apparent reason) in other instances.
4 The ZARCH_ONLY=NO option also disables the CM390 feature of the IBM z14 architecture, which should have no direct effect for most users.
5 Depending on your Linux file ownership, you might need to operate as root to issue this command.
6 We noticed that z/OS 2.1 is less likely to produce error messages than earlier z/OS releases.
7 The mount -t nfs 192.168.1.80:/z3 /z3 command did not work.
8 Any Linux terminal window operating under the Linux user ID that started zPDT. This detail is relevant if multiple zPDT instances are operational.
9 In this case, “large” means at least 100 GB.
10 Most RAID adapters have sizable cache memory. This discussion assumes volumes of data such that the RAID adapter cache is relatively small.
11 This description is probably an inaccurate one of exactly how Linux manages the disk cache, but it describes the general situation.
12 This situation applies to zPDT release GA5 and earlier releases.
13 zPDT can be active if the selected volumes are not in the active devmap.
14 After these error messages, zPDT might acquire the missing license automatically. If this event happens, z/OS is probably unaffected and continues to run. The error messages are seen only in the Linux CLI that is used to start zPDT.
15 We thank Paul Mattes, the primary author of x3270, for help with bypassing a timing problem while producing this script.
16 Use a chmod command to make the Linux file an executable file.
17 In this example, the Linux file does not yet exist. It is created by the awsmount command.
18 There are techniques for working around this requirement, but these techniques require authorized programs working with z/OS interfaces that are not intended for external use.
19 This situation was true at the time of writing, and the zPDT developers are not clear about why z/OS creates this ABEND.
20 This configuration is consistent with z/OS ADCD releases.
21 Assuming that you have tape drive 561 in you devmap, as in the previous example.
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.