Device maps for ISV IBM Z Program Development Tool
In this chapter, we provide reference information for Independent Software Vendor (ISV)
IBM Z Program Development Tool (IBM zPDT) (ISV zPDT) device map (devmap) entries for the IBM zSystems processors and I/O device managers. Information and guidance for using these device managers are found throughout this publication. Devmaps are generally not included with ISV zPDT distribution packages. However, a devmap must be created before ISV zPDT can be started.
This chapter describes all devmap options (including all the supported device managers) in some detail. As a practical matter, most ISV zPDT operations involve only a reasonable subset of the possible options. When reading this material for the first time, do not spend too much energy studying options that you are unlikely to use.
3.1 Device maps
A devmap consists of a system stanza, optional adjunct processors (APs), IBM zEnterprise Data Compression (zEDC) (if appropriate), Server Time Protocol (STP) stanzas, and a variable number of device manager stanzas. The descriptions in this chapter are intended to provide syntax and format information, but are not intended to represent typical use. Usage information is provided in other chapters of this publication.
A devmap is a simple Linux text file with an arbitrary file name. Many devmaps might exist, but only one can be in use for an instance of ISV zPDT. It is possible to have multiple ISV zPDT instances running, each under a different Linux user ID. Each instance has its own devmap. The remainder of this chapter assumes that a single instance of ISV zPDT is used.
Create a devmap file in lowercase,1 except for parameters that specify Linux file names. Devmap parameters begin in the first column of each statement. Stanzas are separated by blank lines. A number sign (#) signals the beginning of comments in a line. The square brackets that shown in the descriptions below are part of the syntax and must be entered as shown.
ISV zPDT reads the specified devmap when it is started. It does not process updates to the devmap while ISV zPDT is running. To alter the operational devmap, ISV zPDT must be stopped and then started again with the revised devmap. However, the Linux file that is associated with some devices (such as emulated tape drives or emulated disk drives) can be dynamically changed while ISV zPDT is operational by using the awsmount command.
3.2 System stanza
A [system] stanza might look like the following example:
[system]
memory 16G # 16 GB memory for IBM zSystems -- Use G and GB
processors 1 # number of CPs
3270port 3270 # specify unique IP port number for aws3274
expand 0m # no expanded storage. mostly obsolete
ipl 0A80 “0A8200” # automatic ipl control (optional; not recommended)
cpuopt alr=on # optional function (defaults to on)
command 2 x3270 localhost:3270 #Linux command run through the devmap
command 2 x3270 -model 3279-5 localhost:3270 #various x3270 options available
The “square brackets” around the system keyword are required. They also appear in other devmap elements and are required as shown in the text in this publication.
The memory statement specifies the size of the IBM zSystems memory to be emulated for an ISV zPDT operation. The number that is specified must be smaller than the maximum shared memory value that is specified for Linux, which must be set by the kernel.shmmax parameter in Linux.2 For z/OS, the memory value should normally be at least 4G. We typically use
8G - 12G, but the value might be much larger.3
You must have a processors statement unless your devmap is for a group controller. (For more information about group controllers, see Chapter 10, “Multiple instances and guests” on page 215.) The processors statement specifies the number of IBM zSystems processors to be used in this instance. The default is 1. The processors statement is also used to indicate the usage of specialty processing units (PUs) as in the following examples (where cp indicates a normal, general-purpose CP):
processors 3 # three CPs. Assumed “cp” type. 3 licenses needed.
processors 3 cp cp ziip # two CPs and one zIIP; 2 licenses needed
processors 2 cp cp ziip # invalid. Two processors, but three definitions
processors 1 ziip # invalid. Must have at least one cp or ifl
processors 3 cp ziip ifl # one of each; needs 2 licenses
processors 3 ziip cp cp # invalid; cp must be first in the list
processors 4 cp cp cp ziip # only 3 licenses needed; ziip is “free”
The operands for the processors statement are the number of processors (typically 1, 2, or 3)4, which (excluding IBM zSystems Integrated Information Processor (zIIP) processors) cannot exceed the number that is allowed by the number of licenses that is allowed by the
ISV zPDT token. The processors default to CPs; if you want specialty processors, list them after the number, as shown in the examples. The processor types are cp, ziip, zaap, and ifl. If zIIPs or IBM zSeries Application Assist Processor (zAAP) processors are specified in the processors statement, at least one CP must be listed first.5 Specialty SAP processors are not used and Coupling Facilities (CFs) are not specified in the devmap.6
The zAAP processors might not be useful in the IBM z13 (or later) environment that is created by ISV zPDT GA6 or later. Starting with ISV zPDT GA8, zIIP processors do not require an ISV zPDT license, although they are included in the maximum of eight processors for an
ISV zPDT instance and are included when determining the minimum number of personal computer (PC) cores that are needed. At the time of writing, the number of zIIPs cannot be greater than the number of CPs.
The expand statement specifies the size of expanded storage for the IBM zSystems machine. This statement is optional. z/OS no longer uses expanded storage. However, some older releases of z/VM still might use it. Do not specify this option unless you have a specific need for it.
The 3270port statement specifies a port number to be used by the base Linux TCP/IP for the aws3274 device manager. This port must be an unused one on the base Linux and is typically a number greater than 1024. In this publication, we arbitrarily use port 3270 because it is easy to remember. A TN3270e emulator connection to this Linux port appears as a local, channel-attached 3270 to the IBM zSystems processors.
The ipl statement is optional and indicates that the ipl command is to be run automatically when the ISV zPDT operation is started. However, using this option might prevent you from connecting 3270 emulator sessions in a timely way. Use this option carefully, if at all.
A cpuopt zVM_CouplingFacility statement (not shown in the above example) should not be used with ISV zPDT. In effect, the zVM_CouplingFacility function is always present for
ISV zPDT systems. Other cpuopt parameters produce non-standard configurations. They are described in 13.3, “The cpuopt statement” on page 279.
 
The command statement specifies Linux commands that are automatically run as part of
ISV zPDT operation. The syntax is as follows:
command phase-number [synchronous] command-string
The phase number is a digit 1 - 4:
•Phase 1 means that the command is run before ISV zPDT starts.
•Phase 2 means that the command is run after ISV zPDT is initialized.
•Phase 3 means that the command is run before ISV zPDT is shut down.
•Phase 4 means that the command is run after ISV zPDT is shut down.
By default, commands are run asynchronously but can be forced to run synchronously. (This approach should seldom be used because it forces other ISV zPDT operations to wait until the command completes. For example, do not use the synchronous approach for an x3270 operation.) The word command can be abbreviated to cmd, and synchronous can be abbreviated to sync. If asynchronous commands terminate while ISV zPDT is still running, they are not automatically restarted. If the commands are still running when ISV zPDT is shut down, they are sent a SIGTERM signal and should terminate.
Additional system stanza options include the following ones:
[system]
...
rdtserver [email protected] # not used with ISV zPDT
int3270port 3271 # HMC-style 3270 integrated port
intASCIIport 3300 # HMC-style ASCII port
system_name mybase # specify the “LPAR name”
oprmsg_file /home/ibmsys1/opmessages # for “HMC hardware console” output
The int3270port and intASCIIport statements provide emulation for Hardware Management Console (HMC)-style integrated terminal functions. The operand for each statement is a port number. After starting ISV zPDT with one of these operands, you start a 3270 emulator that is connected to the indicated Linux port number or start z1090term7 connected to the indicated ASCII terminal port number. These emulated terminals do not need to be on the base Linux system.
The 3270 terminal session that is associated with the int3270port function should8 be a 3270 model 3 (with a 32x80 screen). Any other 3270 terminal model might not connect properly. We found that, in some cases, the smpppd rpm must be included in Linux for the connection to work. In general, the int3270port function is used only when installing z/VM from the formal IBM distribution media. It is not needed when using an Application Development Controlled Distribution (ADCD) z/VM distribution.
 
Tip: Our examples involving int3270port use 3271 as the port number. There is nothing special about this port number; any unused port number can be selected. We found that when attempting to connect a local x3270 session to int3270port the usual link of “localhost:3271” sometimes did not work, while “127.0.0.1:3271” did work.
Restriction: The int3270port and intASCIIport functions have limited applicability. They should not be included in a devmap unless there is a specific need for one or the other one. Their usage can interfere with the default output of “HMC console” messages to a Linux window and the zPDT oprmsg command. We also found that in some environments including both options in the same devmap created issues.
By default, ISV zPDT uses the Linux user ID that was used to start ISV zPDT as the instance name (the “LPAR” name or “CPCNAME”).9 An LPAR name cannot be longer than
8 characters, which restricts the Linux user ID to no more than 8 characters. However, the system_name option in the devmap (maximum of 8 characters) can be used to specify the “LPAR” name, removing the length restriction on the Linux user ID that is used to start
ISV zPDT. The specified name is automatically converted to uppercase Extended Binary Coded Decimal Interchange Code (EBCDIC).
By default, ISV zPDT sends output that is directed to the “HMC hardware console” to the Linux command-line interface (CLI) that was used to start ISV zPDT. (If this CLI is closed, the output is not displayed.) By default, this output (along with any oprmsg commands) is written to an ISV zPDT log file. The oprmsg_file option specifies a Linux file that is to receive such messages.10 If an oprmsg_file is specified, the messages are no longer written to the default ISV zPDT log file. The file name is case-sensitive. This option has several implications:
•The messages are available in the specified Linux file whether the original Linux CLI is open or closed.
•If the oprmsg_file option is used, the default ISV zPDT log file will not contain the messages that are written to the specified oprmsg_file.
•Typically, this option is used with automation (running under Linux) that generates oprmsg commands that are sent to the emulated IBM zSystems. The responses, along with other operating system output, are placed in the specified Linux file where they can be inspected by the automation programs.11
The specified oprmsg_file can be deleted at any time by the user (working with Linux commands or programs). It will be re-created (empty) when the next message arrives for it.
A reasonable example of a system stanza might be as follows:
[system]
memory 8G
processors 2
3270port 3270
command 2 x3270 -model 4 localhost:3270
command 2 x3270 -model 4 localhost:3270
command 4 echo 'ISV zPDT operation has completed'
An ampersand (&) is not used after the x3270 commands in a [system] stanza. Also, the x3270 sessions are automatically closed when ISV zPDT is shut down.
A devmap has several additional features,12 as shown in the following list:
•The use of Linux environmental variables
•The include function
•The message function
An example of each of these functions is included in the following devmap:
[system]
memory $(SIZE)
3270port 3270
 
[manager]
name aws3274 1234
device 0700 3279 3274
device 0701 3279 3274
 
include dasd.def
 
[manager]
name awsosa 4567
device 0400 osa osa
...
message Remember to start or connect the x3270 sessions before you IPL
message
message For normal startup ipl A80 parm 0a8200
This devmap references a second file, dasd.def (in the same directory), which might contain the following stanza:
[manager]
name awsckd ABCD
device A80 3390 3990 /z/SBRES1
etc
The (SIZE) parameter in this example is a Linux environmental variable. The variable name must be enclosed in parentheses, as shown. The value of the variable must be set before the devmap is used. It can be set by the Linux shell command, for example:
$ export SIZE=6500m
This command can be issued before an awsstart command (in the same Linux terminal window), but then it will not be effective in other Linux terminal windows. Alternatively, the export command can be added to the .bashrc file, where it is effective for any terminal window that is then opened. For practical purposes, we suggest adding any devmap environmental variables to the .bashrc file.13 If the specified environmental variable is not set, a null string is placed in the devmap.
The include function in the example operates as you might expect. The file that is specified is logically inserted into the devmap at the point that is shown. The operand of the include function can specify a full Linux path name; if a simple name is specified, it is assumed to be in the current directory. The file name that is specified cannot contain blanks. The name can be an environmental variable instead of a file name, for example, include $(fileVAR). If the specified environmental variable is not defined, the include function is skipped.
The message function simply displays its text when the devmap is processed by the awsstart command. The message function name can be abbreviated to msg.
It is unlikely that all the [system] stanza options would be used at one time, but here is an almost full example for reference:
[system]
memory 6000m
processors 3 cp cp ziip
3270port 3270
int3270port 3271
intASCIIport 4000
expand 1000m #Who uses expanded memory today?
system_name old22 #maximum more than 8 characters
oprmsg_file /tmp/bill/messages
#ipl 0A80 “0A8200” (not recommended. Commented out here)
cpuopt alr=on
message This devmap is excessive
command 2 x3270 localhost:3270
command 2 x3270 localhost:3270
command 2 x3270 localhost:3271
message Remember to start more 3270 sessions
include devmap2
As a practical matter, typical devmaps use only the memory, processors, 3270port, and possibly a few command statements. The other statements tend to be for special cases.
3.3 Adjunct-processor stanza
The ISV zPDT system optionally provides emulation of the IBM zSystems cryptographic adapter.14 The release level of the cryptographic adapter varies with the ISV zPDT release level. The basic devmap format for this emulation is as follows:
[adjunct-processors]
crypto 0
crypto 1
This stanza defines two cryptographic processors, numbered 0 and 1. If multiple ISV zPDT instances and shared cryptographic processors are used, the sharing instances might have a definition such as the following example:
[adjunct-processors]
domain 0 2
domain 1 2
This stanza indicates that the instance is using domain 2 in cryptographic coprocessors 0 and 1. For more information, see Chapter 17, “Cryptographic usage” on page 331. The second domain number option should not be used for a single-instance ISV zPDT configuration.
3.4 Server Time Protocol stanza
The Linux daemons that are associated with STP must be started before you use a devmap that contains an STP stanza. The stanza is as follows:
[stp]
ctn 00000000F1F0F9F0 #16 hex digits beginning with 00
node 1 W520 * #asterisks marks this node
node 2 W510
All ISV zPDT systems participating in a CCT/STP network must have a similar stanza (with the asterisk denoting the local Linux name). When a devmap includes an stp stanza, the devmap cannot be started (with an awsstart command) unless the STP function is active on the base Linux system. The devmap stanza can also include a LEAPSECONDS statement, which is not shown in this example. Few ISV zPDT users use this function.
3.5 zEDC stanza
zPDT GA9 provides limited zEDC emulation. The required stanza can look like the following one:
[pcipchid]
name awszedc 120 zedc
function 0c0 3
This example has pchid=120, zEDC address 0c0, and virtual function 3. Operands such as these are required for zEDC operation, but the operand values are not relevant to ISV zPDT use. The IBM zSystems DFLTCC instruction, which is present in ISV zPDT GA11, replaces zEDC usage, and zEDC devmap statements are ignored with GA11.
3.6 Device manager stanzas
A device manager stanza has the following general format:
[manager]
name awsckd C700
device 0a80 3390 3990 /z/SBRES1
device 0a81 3390 3990 /z/SBRES2
etc
The stanza begins with [manager], including the square brackets. In this example, the device manager name is awsckd, but the name can be any of the supported device managers. The device manager name is followed by an arbitrary hex number (up to 4 digits, which is different for each name statement).15 The name statement is followed by as many device statements as needed.
The general format is as follows:
•For name statements:
 – The constant “name” starting in the first column.
 – The device manager name, such as awsckd.
 – A hex number. Each name statement must have a different number.
 – More optional parameters, such as:
 • --path=xx to specify an emulated CHPID number.
 • --pathtype=xxx to specify an emulated CHPID type (usually emulated I/O (EIO)).
 • --compress to specify compressed awstape generation.
 • Various optional tunnel parameters for an Open Systems Adapter (OSA) operation.
•For device statements:
 – The constant “device” starting in the first column.
 – The device number (“address”) to be used, which is expressed in hexadecimal. This number can be three or four digits.
 – The IBM device type, such as 3390. It must specify a correct device type for the device manager.
 – The IBM control unit type that is associated with the device, which can be up to
4 characters. (This parameter is not used for anything at the time of writing, but a wise approach is to use an appropriate control unit number.)
 – Parameter (or parameters) unique to the device:
 • A fully qualified file name.
 • --unitadd=x to specify a unit address for some device types (such as OSA). If this parameter is not used, the two low-order digits of the device number are used as the default unit address for OSA devices. The default is appropriate in almost all cases.
 • More parameters for OSA operation.
The --path, --pathtype, and --unitadd parameters are typically used only for OSA definitions. Except for OSA devices, the path for emulated devices defaults to 01, and the pathtype defaults to EIO16 for most device managers. In rare cases, you might change these values by using the --path and --pathtype operands on a name statement, as follows:
[manager]
name awsckd 20 --path=30 --pathtype=eio
device A90 3390 3990 /z/specialvolume
The path value is expressed as a hex number. Multiple stanzas for the same device manager can be used. A maximum of 256 devices can be listed in a stanza. The device numbers (addresses) that are assigned to each device do not need to be sequential or in any particular order.
3.6.1 The awsckd device manager
The awsckd device manager emulates 3380 or 3390 disk drives. The definitions for awsckd are simple, as this example illustrates:
[manager]
name awsckd 4321 [--shared]
device a80 3390 3990 /z/SYSRES
device a85 3390 3990 /tmp/my3390vol
device 0aa7 3390 2107 /z/SARES1
device 0AA8 3390 3990 #No file specified; can use awsmount
etc
The device type can be 3390 or 3380; in either case, the Linux file that is named by the fourth parameter of the device statement must be in the appropriate emulated format for that device type. The Linux file containing the emulated volume must have been created with the alcckd command, or copied from media that originated on a system where the file was initially created with alcckd. Each emulated volume is a single, separate Linux file.
 
Tip: Do not select 3380 device types unless you have a particular need for them. This device type is rarely used today.
Also, Linux file names containing space characters are not supported.
The third operand of a device statement is a control unit type. This information is not used by ISV zPDT, but it is a positional operand that must be specified. Starting with ISV zPDT GA 8, awsckd emulates IBM 2107 control units. However, you can specify 3990, 2107, or anything else up to 4 characters.
The most common CKD devices are 3390 units. Standard 3390s (models -1, -2, -3, and -9) can be used, or a variable number of cylinders can be used. The maximum size for a normal 3390 is 64 K-1 cylinders. ISV zPDT also supports extended address volume (EAV) 3390s. The volume size is specified when using the alcckd command to create the volume.
The extra cylinders of a 3390 are not emulated; they are the cylinders that are reserved as spares or for diagnostic use. For example, a 3390-3 contains 3339 usable cylinders, and these cylinders are what is emulated. Parallel Access Volumes (PAVs) are not supported.
Device statements can omit a file name. In this case, the indicated unit (3390 at address 0AA8 in the example) exists, but has no volume that is mounted. A volume (which is a Linux file in the appropriate CKD format) can be mounted (or dismounted) while ISV zPDT is operational, which provides dynamic changes to the direct access storage device environment without stopping ISV zPDT. The awsmount command is used for this operation.
The --shared option is relevant only if the volume (that is, the Linux file) is shared among multiple z/OS systems. This option causes the awsckd device manager to perform the following actions:
1. Emulate RESERVE and RELEASE channel commands.
2. Lock (at the Linux level) the logical tracks of the ckd volume while they are addressed by an active IBM zSystems channel program.
Much more is involved in sharing IBM zSystems volumes, and the --shared option is only one element that is involved. Use this option when multiple ISV zPDT instances (in the same Linux) are sharing direct access storage device volumes and when separate ISV zPDT systems (on separate Linux bases) are sharing direct access storage device through a Linux shared file system. Proper serialization, as seen by z/OS, is essential for shared direct access storage device, and implementing such serialization typically involves z/OS global resource serialization (GRS).17 The --shared option is not used when sharing direct access storage device volumes among multiple z/VM guests.
3.6.2 The awsfba device manager
The awsfba device manager provides emulation for Fixed Block Architecture (FBA) disk devices18 (as used by z/VM and a few other operating systems), as shown in the following stanza:
[manager]
name awsfba 6543
device 100 9336 9336 /z/DOSRES
device 101 9336 9336 /z/DOSWRK
The awsfba devices (volumes) must be created before they can be used. This task is accomplished by using the alcfba utility. This device manager does not support the more recent fiber open system FBA devices for z/OS.
ISV zPDT development performs only minimal testing for these FBA devices. As a best practice, use CKD disks unless there is a specific need for FBA disks.
3.6.3 The aws3274 device manager
The aws3274 device manager emulates local, channel-attached, DFT, non-Systems Network Architecture (SNA) 3270 sessions. These sessions are used for MVS operator consoles, simple IBM Virtual Telecommunications Access Method (IBM VTAM®) sessions (Time Sharing Option (TSO), IBM CICS, and so on), z/VM terminals, and similar purposes. The actual 3270 emulators (x3270, IBM Personal Communications, or other 3270 emulators) might be local (on the underlying Linux system running ISV zPDT) or remotely connected through a TCP/IP connection to the underlying Linux. In either case, they use the Linux TCP/IP port number that is assigned in the [system] section of the devmap, and they appear to be local, channel-attached 3270s to the IBM zSystems software. The same physical Ethernet interface can be used for Linux functions, such as Telnet, SSH, aws3274, and FTP, and also for emulated OSA connections.
There is a maximum of 32 emulated local 3270 device sessions, regardless of the number of aws3274 stanzas.
The devmap parameters for emulated local 3270s offer several options, which are best explained by an example:
[manager]
name aws3274 C700 # C700 is an arbitrary CUNUMBR
device 0700 3279 3274
device 0701 3279 3274 L701
device 0702 3279 3274 L702
device 0703 3279 3274 TSO
device 0704 3279 3274 TSO
device 0705 3279 3274 TSO
device 0706 3279 3274
device 0707 3279 3274
device 0708 3279 3274 IMS
device 0709 3279 3274 IMS
device 070A 3279 3274 IMS
device 070B 3279 3274 IMS
device 070C 3279 3274
device 070D 3279 3274
device 070E 3279 3274
The three operands after the device keyword are the address (device number), the device type, and the control unit type. The remaining optional operand controls potential client connections to the device. This operand is known as an LUname, although it is not used as a real SNA LU name. (TN3270e clients can pass an LU name, intended for SNA protocols, during startup. We use this LU name passing facility here without passing it to VTAM.) The LUnames can have a maximum of 11 characters.
In this example, LUnames are L701, L702, TSO, and IMS. The connection rules are as follows:
•The LUname is not case-sensitive.
•If an LUname is specified by the TN3270e client, then a free device with the matching LUname is used.
•If no LUname is specified by the TN3270E client, the next free device in the list is used, regardless of whether it has an associated LUname.
•If there is no free device to match the specified LUname, the connection is rejected.
•A device is freed when a previous TN3270E client connection is terminated.
The aws3274 device manager listens on a port in the base Linux TCP/IP system. Assume that the Linux TCP/IP address is 192.168.1.80 in the following examples. Also, assume that our devmap specifies 3270 as the aws3270 port number. A user can enter one of the following Linux commands to establish an x3270 session:
$ x3270 -port 3270 192.168.1.80 & case one
$ x3270 -port 3270 [email protected] & case two
$ x3270 -port 3270 [email protected] & case three
$ x3270 -port 3270 IMS@localhost & use local system
Assume that our x3270 client is on a remote machine that is connected to a private local area network (LAN) that includes the ISV zPDT system. In case 1, the user is connected to the next available 3270 session (in the devmap list). In case 2, the client is connected to the next free device with LUname TSO. In case 3, the client is connected to the single device with LUname L702 if that device is free currently. The fourth example illustrates that the same LUname rules apply to connections from the Linux desktop. You might use a shorter form of the x3270 command, as follows:
x3270 localhost:3270 &
In the examples, both TSO and L702 are LUnames. TSO happens to be used multiple times, but L702 is used only once. There is no requirement to have this arrangement and no requirement to have the LUname reflect the device address (device number).
The devmap for an ADCD z/OS system might be defined as follows, which is the most common example for ISV zPDT users:19
[manager]
name aws3274 C700
device 0700 3279 3274
device 0701 3279 3274
device 0702 3279 3274
device 0703 3179 3274
.....
device 070A 3179 3274
Client 3270 connections take the next free terminal in the devmap list if no LU conditions are specified. This action can be especially useful if the first terminal in the devmap is the MVS operator console20 and the next terminal is a suitable TSO address. In this case, without specifying any LU names, the first x3270 session is the MVS operator console, and the second session will be a TSO session (or CICS or some other VTAM application). As a practical matter, we observed that few ISV zPDT customers use the LU name facility.
From the user’s perspective, a 3270 terminal is a TN3270e session. The IBM Personal Communications product and the x3270 emulator that are available for Linux were tested for this usage.21 The TN3270e client might operate on the machine running the ISV zPDT processes (on the local Linux desktop, for example), or it might operate through a remote TCP/IP connection. In either case, the TN3270E terminal appears as a local, non-SNA channel-attached 3270 to the IBM zSystems operating system.
The usage of TN3270e (rather than TN3270) is required because the LU name (which is supported by TN3270e, but not TN3270) is needed. Most modern, supported 3270 emulators provide TN3270e functions.
Starting a 3270 session (through aws3274) requires a small amount of free space in the Linux /tmp file system. If /tmp is full, a new aws3274 session cannot be started.
3.6.4 The awstape device manager
The awstape device manager provides “emulated” tape drives that use Linux files as the “tapes” that are involved. This device manager is not related to “real” tape drives that might be attached to the Linux system. Definitions for awstape appear as follows:
[manager]
name awstape AB00 [--maxlength=1000m] [--compress] [--MNTCCWS]
device 560 3490 3490
device 561 3490 3490 /local/my.tape.vol.111111
The emulated device type can be 3420, 3480, 3490, or 3590. (The third operand, the control unit type, is not meaningful.) A file name can be specified as the last operand. If a file name is specified, the file must be in awstape format (if it is for input). This situation is like a premounted tape on a larger IBM zSystems server. Typically, no file is specified for emulated tape devices. Instead, the awsmount command is used to emulate the mounting of a tape volume.
The maxlength parameter is optional. If a maxlength value is specified, the device manager signals end of tape after the specified number of bytes are written. (Then, z/OS probably writes trailer labels and calls for another tape mount.) If maxlength is not specified, then the maximum tape content is limited by one or more of the following conditions:
•The amount of free disk space in the Linux file system.
•An architectural limit of approximately 4 million tape blocks for 3480 and 3490 device types. The device signals end-of-tape just before this limit is reached. This limit exists for both reading and writing tapes.
•Device types 3420 and 3590 do not have specific limits.
The --MNTCCWS parameter enables use of 4B and 54 channel command words (CCWs), which are used to manipulate the Linux file name that is associated with the emulated tape drive. This process is described in 13.19.5, “Using special channel command words to manipulate tape volume” on page 297.
Emulated tape volumes that are created through this device manager are in awstape format, and they can be exchanged with other systems that can process this format. All awstape files are compatible with all ISV zPDT emulated tape devices. An awstape file that is written by an emulated 3490 can be read by an emulated 3420, for example.
The correct responses for hardware compaction (IDRC) are emulated, although tape data is not compacted by this method. The awstape data can be optionally compacted by the awstape device manager, which is controlled through a devmap or an awsmount parameter. The compaction format is unique to ISV zPDT awstape. The default uncompacted form should be used for data interchange with other systems that use awstape data.
The awstape volumes are created when they are written, that is, it is not necessary to create or initialize the volume before writing to it unless the software expects a labeled tape. (An “empty” labeled tape can be created with the ISV zPDT aws_tapeInit command.)
 
Tip: On some IBM zSystems servers, there are various models of 3590 tape drives that are available that can present various and complex information about various “sense” commands. The zPDT emulated 3590 does not provide all of this information, which in rare cases might create a software problem. If this situation happens, emulate one of the other tape drive types that are available. (The only specific instance we know about involves DFSMShsm creating a new stored data set.)
3.6.5 The awsosa device manager
The awsosa device manager emulates various OSA-Express functions that are used by
IBM zSystems TCP/IP or SNA.22 At the time of writing, the emulation level is OSA-Express6s. Two manager formats are available:
[manager]
name awsosa 8888 --path=F0 --pathtype=OSD [--interface=xxxx]
device 400 osa osa --unitadd=0
device 401 osa osa --unitadd=1
device 402 osa osa --unitadd=2
 
[manager]
name awsosa 2345 --path=A0 --pathtype=OSD [--interface] [--tunnel_intf=y]
[--tunnel_ip=10.1.1.1] [--tunnel_mask=255.0.0.0]
device 404 osa osa
device 405 osa osa
device 406 osa osa
The first example is used with a typical PC Ethernet adapter. The second example is for a tunnel interface between the emulated OSA adapter and the underlying Linux TCP/IP system.23 The awsosa device manager can concurrently use the same Ethernet adapter that is used by Linux for normal Linux TCP/IP functions, but the OSA user and Linux cannot communicate with each other through it. Both OSA and Linux can share the adapter for connection to external TCP/IP systems, but they cannot communicate with each other.24 A tunnel interface (which is like another Ethernet adapter) is necessary for direct communication between the underlying Linux system and the IBM zSystems OSA operation.
 
Tip: For more information about using the emulated OSA functions, see Chapter 7, “Local area networks” on page 149.
The --path operand specifies a CHPID number. The correct number is determined with the find_io command. For these examples, we assume that the CHPID for wired Ethernet is F0 and the CHPID for a tunnel interface is A0. The --pathtype is OSA-Express Direct (OSD) (for QDIO) or OSA-Express (OSE)25 (for LAN Channel Station (LCS) or non-QDIO). In some cases, the find_io command does not provide a CHPID (path name) for a LAN interface, so the --interface=xxxx parameter can be used to name a specific LAN interface. The interaction of the --path and --interface parameters is explained in detail in Chapter 7, “Local area networks” on page 149. Here is an example of using the --interface parameter:
name awsosa 1234 --path=B0 --pathtype=OSD --interface=em1
The --unitadd operands specify the internal OSA interface number, which normally is not needed for QDIO operation. They might be needed for non-QDIO operation if more than one TCP/IP interface is used. z/OS TCP/IP requires three OSA addresses for QDIO operation.
The z/OS device type should be OSA, as shown in the z/OS input/output definition file (IODF) (and when displaying devices on the MVS console).26
The --pathtype parameter must specify OSD or OSE. When used in OSE mode, the OSA interfaces are associated with OSA Address Table (OAT) definitions that specify how each interface is used. At the time of writing, Open Systems Adapter/Support Facility (OSA/SF) (the z/OS program to manage OATs) is not available with z/OS releases, and its partial replacement, the QUERYINFO command, is not supported by ISV zPDT. SNA usage requires CHPID type OSE, although there is no ISV zPDT support for SNA usage. Do not use OSE mode unless you have a specific requirement for it.
Table 3-1 provides details about OSA-Express emulation at the time of writing.
 
Important: The larger specifications here should not be taken as reasonable designs for general ISV zPDT usage. These numbers relate to fixed table sizes in a zPDT OSA implementation. Actual usage of larger configurations (within the limitations that are shown in this table) might involve other considerations.
Table 3-1 OSA-Express limits, per port
Item
Value
Maximum OSAs (and maximum OSA CHPIDs)
4
Maximum home addresses (IPv4 + IPv6 + DVIPA) per OSA port
64
Maximum IPv6 addresses
32
Maximum multicast addresses (IPv4 + IPv6)
64
ARP table size
256
IP address stacks per port (OSD or OSE)
16
SNA PUs per OSA-Express port (SNA is not supported for ISV zPDT.)
512
OSE subchannels per stack
2
OSE or OSD maximum devices
48
OSE IP address stacks per OSA port or CHPID
16
OSD subchannels per stack
3
OSD subchannels per OSA or CHPID
48
Is OSA/SF or QUERYINFO available?
No
Is Generic VLAN Registration Protocol (GVRP) supported?
No
3.6.6 The awsrdr device manager
The awsrdr device manager emulates an IBM 2540 card reader. Only one awsrdr device can be configured for an instance of an ISV zPDT operation. Typically, the emulated card reader is used to submit jobs to the operating system.27 If we assume that the operating system is z/OS, then Job Entry Subsystem (JES) 2 or JES3 should be configured with a “hot” reader.28 The traditional address for an IBM 2540 is 00C, which we use in our examples.
The awsrdr device manager monitors the directory that is specified in the device statement. When a file is found in the directory, it is read (assuming an IBM zSystems program has a read that is outstanding for the card reader, which is the case with a JES hot reader). After the file (“card deck”) is read, it is moved to the old subdirectory. So, there is never a file in the directory that is assigned to the reader other than a file that you moved there to be read. When file is read, it is moved out of the reader directory. If awsrdr is not active or if there is no IBM zSystems program trying to read cards, then files sit in the reader directory indefinitely.
The devmap entry for the card reader might look like this:
[manager]
name awsrdr 010C
device 00C 2540 2821 /home/ibmsys1/cards/* (the asterisk is required)
The /home/ibmsys1/cards/ directory in the example is arbitrary. The default path is /home/<userid>/z1090/cards/.
ASCII and EBCDIC
Linux text files are normally in ASCII. z/OS cards are normally in EBCDIC, but they might contain binary or other formats for information. A “real” card reader uses fixed-length records (80 bytes), but a Linux text file has variable length records that terminate with an New Line (NL) character.
The conversion rules are as follows:
•If the input file name (in the directory that is used by awsrdr) contains the suffix .ebc or .bin, then the file is assumed to be in EBCDIC format and no translation is done.
•If the input file contains the suffix .txt or .asc, then the file is assumed to be in ASCII and converted to EBCDIC when it is read.
•If the input file contains the ASCII characters //, ID, $$, or USERID in the first bytes, the file is assumed to be in ASCII and converted to EBCDIC.
•If none of these conditions are true, then the file is assumed to be EBCDIC (or binary as used for IBM zSystems) and not converted.
•If a file is converted from ASCII, the record length is padded with blanks to 80 bytes, and the terminating NL bytes are removed.
•If the file is not converted from ASCII for one of these reasons, then awsrdr reads it in 80-byte chunks and passes the data (unchanged) to the emulated card reader.
Another way to convert ASCII text files to EBCDIC card files is by running the txt2card command.
The ASCII to EBCDIC translation table is fixed in all cases.
3.6.7 The awsprt device manager
The awsprt device manager emulates an IBM 1403 or 3211 printer. Forms Control Buffer (FCB) functions29 are supported for 3211 emulation, but Universal Character Set (UCS) functions for a 1403 are not supported. A fixed translation table is used to convert EBCDIC to ASCII. The device manager automatically inserts NL characters between output records. Unprintable characters are translated to blanks and no unit check is generated for them.
awsprt cannot recognize divisions between IBM zSystems jobs. It just concatenates all output (potentially from multiple jobs) into the output file. The device statement specifies the output file to use:
[manager]
name awsprt 0003 [--windows]
device 00E 1403 2821 /home/ibmsys1/print
If a file name is not provided with the device statement, the default file name (/home/<userid>/z1090/listings/dev-nnnn.lst) is used. The --windows option causes the output lines to be terminated with CR or LF characters instead of NL characters.
The awsmount command can be used to close the existing output file and open a new output file. The previous output file is closed, and then it is available for display or printing under Linux. For more information about printing output with the awsprt device manager, see 12.10, “Local printing” on page 259.
3.6.8 The awscmd device manager
This device manager provides a device that appears to IBM zSystems software as a tape drive. Its function is to send a command (and data) to the underlying Linux and then receive the output from the Linux command. Any Linux command might be sent, including the ones that might destroy the Linux system.30 Obviously, this device manager should be used with care, and it might not be appropriate for an ISV zPDT environment that can be accessed by untrusted users.
Configuration is like other device managers:
[manager]
name awscmd 20
device 580 3480 3480
The device type can be 3420, 3422, 3480, 3490, or 3590, which are the tape device types that are emulated by ISV zPDT. The device number (580) must match a corresponding device type in your z/OS IODF. (Any device number can be used with z/VM.)
The intended operation (by an IBM zSystems application program) is as follows:
1. A rewind is issued to the device.
2. The Linux command (expressed in EBCDIC) is written to the device.
3. Any stdin data to be used by the Linux command is written to the device.
4. EBCDIC to ASCII translation is done automatically, with a fixed translation table.
5. A tape mark is written to the device.
6. The awscmd device manager submits the command (and data) to Linux through a shell that does not appear on the Linux panel. The current Linux directory for the command is the same directory that was used to start ISV zPDT.
7. When the awscmd function completes, there are four files on the pseudo-tape device:
 – The command file that was submitted to Linux (with redirection operands that were automatically added by awscmd)
 – The stdout data from the Linux command
 – The stderr data from the Linux command
 – The return code (converted to characters) from the Linux command
8. The output (on the pseudo tape) was converted to EBCDIC.
9. Two tape marks are at the end of the pseudo-tape.
Restrictions
The command that is sent to Linux cannot include any redirection (less than (<) or greater than (>) characters), asynchronous indicator (ampersand (&) character), or pipe (“|” or vertical bar character). The pseudo-tape device appears as busy while Linux is running the command. Any Linux command that creates substantial delays (of many seconds) might cause I/O timeout errors to be generated in z/OS.31
At the time of writing, the following characters did not survive the conversion from EBCDIC to ASCII when included in the stdin data:
•Tilde (~)
•Caret (^)
•Colon (:)
•Double quotation marks (")
•Less than (<)
•Greater than (>)
•Question mark (?)
An extended example of awscmd usage is described in Chapter 11, “The awscmd device manager” on page 227.
3.6.9 The awsscsi device manager
The awsscsi device manager emulates a mainframe tape drive by using a physical SCSI tape drive. The specific adapters and tape drives that are supported are described in Chapter 14, “Tape drives and tapes” on page 303. The general format is as follows:
[manager]
name awsscsi 700
device 581 3490 3490 /dev/sg5
The last operand of the device statement denotes the SCSI device to be used, which must be given as a /dev/sgx name and not a /dev/stx name. The differences are complex. Chapter 14, “Tape drives and tapes” on page 303 describes methods for determining the correct /dev/sgx name. The SCSI tape drive appears as a 3420, 3480, 3490, or 3592 device to the IBM zSystems software.32 The awsmount command can be used with SCSI tape devices.
3.6.10 The aws3215 device manager
The aws3215 device manager provides emulation of a 3215 console by using devmap parameters like the following ones:
[manager]
name aws3215 AC00
device 009 3215 3215
It is possible but unusual to have multiple 3215 devices. Thee input to the 3215 console is done by running the awsin command in the Linux CLI. The output appears in the Linux panel that is used for the awsstart command.
3.6.11 The awsoma device manager
The awsoma device manager is used to read CDs or DVDs33 that are written in a special format that is known as OMA. OMA is for input only because it is not possible to write to an awsoma device. In earlier days, z/VM and z/VSE were available in OMA format, and some Linux distributions for IBM zSystems might use this format.
[manager]
name awsoma D000
device F00 oma oma /media/ROM/;xyz.tdf
The variable portion of the device statement (after the second oma) must be in a specific format, with two names separated by a comma or semicolon. There must be no blanks between the operands. The first name is a path name, and the second name is a specific file name. The second name is relative to the path that is specified by the first name.34
In a Linux based ISV zPDT system, the net effect is that the two names are concatenated. In the example stanza, the effective file name that is used for input to awsoma is /media/ROM/xyz.tdf. The slash (/) after ROM can be omitted, and a slash inserted before xyz.tdf, which results in the same effective file name.
Releases of ISV zPDT at the time of writing expanded the possible formats to include the following ones:
device 123 oma oma /tmp/;my.tdf results in /tmp/my.tdf
device 123 oma oma /tmp/my.tdf single fully qualified name
device 123 oma oma my.tdf results in /home/ibmsys1/my.tdf
(assuming ISV zPDT was started from /home/ibmsys1)
device 123 oma oma /media/myCD/TAPES/my.tdf
(data is assumed to be in /media/myCD/xxxxx)
The first example follows the original requirements. The second example uses a single fully qualified name. The third example causes the specified file name (my.tdf) to be relative to the directory that is used to start th ISV zPDT operation. The last example depends on the keyword TAPES to indicate that data files are relative to the directory above TAPES.
The variable portion of the device statement can be omitted. In this case, awsmount commands are used to associate the TDF file with the awsoma device. The two-operand format, as used in the initial description above, is not valid for awsmount.
3.6.12 The awsctc device manager
The awsctc device manager emulates a 3088 CTC control unit. A typical definition is as follows:
[manager]
name awsckd 5432
device E40 3088 3088 ctc://192.168.1.81:3088/E42
| | |
| | + remote device number
| + remote port number
+ remote IP address
Multiple devices can be defined for this device manager. Chapter 16, “Channel-to-channel” on page 323 describes the setup and usage of this device manager.
1 Lowercase is not required by some elements of a devmap, which ignore uppercase or lowercase. Not all devmap elements ignore case. To avoid problems, use lowercase for everything (except for Linux file names, which are case-sensitive).
2 This kernel variable is specified by the instructions in Chapter 5, “ISV IBM Z Program Development Tool installation” on page 125.
3 The memory size can also be specified in megabytes by using a “M” suffix.
4 The number of processors for an instance has a maximum value of 8. You might need multiple ISV zPDT tokens when individual tokens have a maximum of three licenses.
5 The first processor type that is listed becomes the initial program load (IPL) processor. zIIPs and zAAPs cannot handle an IPL.
6 ISV zPDT uses z/VM to provide emulated CFs.
7 For more information, see the command descriptions in Chapter 4, “ISV IBM Z Program Development Tool commands” on page 71.
8 This requirement appears to vary with z/OS releases. If you have a problem using the int3270 function, be certain you are using the correct 3270 model type.
9 ISV zPDT does not generally support logical partition (LPAR) functions, but the LPAR term is often used to describe an ISV zPDT instance.
10 This function is described in more detail in 13.5, “zPDT log files” on page 282.
11 ISV zPDT does not provide any such automation functions or examples.
12 These features were added for special purposes. We have not seen much usage by typical ISV zPDT users.
13 Other required changes to the .bashrc file are described in Chapter 5, “ISV IBM Z Program Development Tool installation” on page 125.
14 Do not confuse this emulation with the cryptographic instructions, which to do not require any special devmap statements.
15 This parameter originally matched a number in a separate IOCDS file. This separate IOCDS is no longer used, but the positional parameter in the name statement remains.
16 EIO is a special CHPID type for emulated I/O. ISV zPDT users normally do not need to specify this type anywhere.
17 GRS is a basic element of an IBM zSystems sysplex configuration.
18 These devices had IBM type numbers, such as 3370, 9332, 9335, and 9336.
19 You might notice that the third operand in the aws3274 examples is sometimes 3174 and sometimes 3274. This operand in device statements is not processed, and it can be any 4-character value. We suggest a meaningful value only for documentation.
20 The ADCD z/OS systems define the MVS console at address 700.
21 The aws3274 device manager sends an attention signal to the host when a session is first connected. In some cases, such as when it is connected to the IBM VTAM unformatted system services function, this action might prompt a full buffer read by the host software. If the TN3270e session buffer is not formatted for this buffer read, the host might display an “Unsupported Function” message. Clearing the TN3270 panel should resolve the situation. Some TN3270e emulators encounter this situation and others do not.
22 ISV zPDT SNA usage has not been tested by IBM, and there is no support for it.
23 If no IP address is specified for a tunnel interface, it defaults to 10.1.1.1.
24 This odd limitation is a characteristic of current Linux implementations.
25 We do not recommend that you use OSE unless you have a special need for it.
26 Older z/OS systems can use channel-to-channel (CTC) device definitions for these interfaces, especially when they are used for TCP/IP. These definitions should be replaced with device type OSA.
27 In principle, we can directly allocate the card reader to a job by using the appropriate DD statement. We did not try this approach.
28 The term “hot reader” means that there is always a read outstanding for the card reader. When an operator places cards in the reader, JES begins reading them.
29 As a best practice, do not use FCB functions because they have not been tested recently.
30 The Linux commands run with the authority of the user ID that started ISV zPDT operation.
31 Earlier versions of awscmd had a timeout function that limited the time that was allowed for the Linux command. This timeout check was removed at customer requests.
32 BM 3490 tape units have their own characteristics, one of which is a maximum block count of approximately
4 million (a 22-bit number).
33 It is possible to have OMA files on other media, but a CD or DVD is usually where they are found.
34 This operand convention was evolved for early OS2 based machines, where it helped deal with drive letters that might be needed before a file name.
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.218.1.11