Devmaps
In this chapter, we provide reference information for zPDT device map entries for the z processors and I/O device managers. Information and guidance for using these device managers is found throughout this book.
3.1 Device maps
A device map (devmap) consists of a system stanza, optional adjunct processor, zEDC, and System Timer 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 document.
A device map is a simple Linux text file with an arbitrary file name. Many devmaps may exist, but only one can be in use for an instance of zPDT. It is possible to have multiple zPDT instances running, each under a different Linux userid. Each instance has its own devmap. The remainder of this chapter assumes a single instance of zPDT is being 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 shown in the descriptions below are part of the syntax and must be entered as shown.
zPDT reads the specified device map when it is started. It does not process updates to the devmap while zPDT is running. To alter the operational device map, zPDT must be stopped and then started again with the revised devmap. However, the Linux file associated with some devices (such as emulated tape drives or emulated disk drives) can be dynamically changed while zPDT is operational by using the awsmount command.
3.2 System stanza
A [system] stanza might look like this:
[system]
memory 6G # define 6 GB memory for z System
processors 1 # number of CPs
3270port 3270 # specify unique IP port number for aws3274
expand 0m # no expanded storage
ipl 0A80 “0A8200” # automatic ipl control (optional; not recommended)
cpuopt alr=on # optional function (defaults to on)
command 2 x3270 localhost:3270 #Linux command executed via the devmap
command 2 x3270 -model 3279-5 localhost:3270 #various x3270 options available
The memory statement specifies the size of the z System memory to be emulated for zPDT operation. For performance reasons the real memory size of the PC should be at least one gigabyte greater than the memory parameter.2 The number specified must be smaller than the maximum shared memory value specified for Linux; this is set by the kernel.shmmax parameter in Linux.3 For z/OS the memory value should normally be at least 4G; we typically use 8G-12G but it might be much larger than this.4
You must have a processors statement unless your devmap is for a group controller. (See Chapter 10, “Multiple instances and guests” on page 203 for more information about group controllers.) The processors statement specifies the number of z System processors to be used in this instance. The default is one. The processors statement is also used to indicate the use of speciality PUs as in the following examples (where cp indicates a normal, general-purpose CP):
processors 3 # three CPs. Assumed “cp” type
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)5, which (excluding ziip processors) cannot exceed the number allowed by the number of licenses allowed by the zPDT token. The processors default to CPs; if you want speciality processors, list them after the number as shown in the examples. The processor types are cp, ziip, zaap, and ifl. If zIIPs or zAAPs are specified in the processors statement, at least one CP must be listed first.6 Speciality SAP processors are not used and Coupling Facilities (CFs) are not specified in the devmap.7
The zAAP processors might not be useful in the z13 (or later) environment created by zPDT GA6 or later. Starting with zPDT GA8, zIIP processors do not require a zPDT license although they are included in the maximum of eight processors for a zPDT instance and are included when determining the minimum number of PC cores needed.
The expand statement specifies the size of expanded storage for the z System machine. This is optional. z/OS no longer uses expanded storage. However, some older releases of z/VM still use it.
The 3270port statement specifies a port number to be used by the base Linux TCP/IP for the aws3274 device manager. This must be an unused port on the base Linux and is typically a number greater than 1024. 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 z System.
The ipl statement is optional and indicates that the ipl command is to be run automatically when the zPDT operation is started. However, using this option might prevent you from connecting 3270 emulator sessions in a timely way. We suggest using this option carefully, if at all.
The cpuopt statement specifies optional parameters for the CPs. The following statement should be used only by zD&T customers who have the optional Coupling Facility feature with their license.
cpuopt zVM_CouplingFacility (no blanks in operand)
cpuopt zVM_Coupling (this abbreviation can be used)
In effect, the zVM_CouplingFacility function is always present for ISV zPDT systems. Other cpuopt parameters produce non-standard configurations and are described in 13.3, “cpuopt statement” on page 260.
|
Important: zD&T users must specify zVM_Coupling if their license has this feature. If the feature is present in the license and is not in the devmap, zPDT startup will fail to acquire licenses.
|
The command statement specifies Linux commands that are automatically executed as part of the zPDT operation. The syntax is as follows:
command phase-number [synchronous] command-string
The phase number is a digit from 1 to 4:
•Phase 1 means the command is to be executed before zPDT is started.
•Phase 2 means the command is to be executed after zPDT is initialized.
•Phase 3 means the command is to be executed just before zPDT is shut down.
•Phase 4 means the command is to be executed after zPDT is shut down.
By default, commands are executed asynchronously but may be forced to synchronous operation. (This should seldom be used, since it forces other zPDT operations to wait until the command is completed. For example, do not use it for x3270 startup.) The word command may be abbreviated to cmd, and synchronous may be abbreviated to sync. If asynchronous commands terminate while zPDT is still running, they are not automatically restarted. If they are still running when zPDT is shut down they are sent a SIGTERM signal and should terminate.
Additional system stanza options include these:
[system]
...
rdtserver [email protected] # Rational License Server and port
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 rdtserver statement is used only with a zD&T system. It points to an IBM Rational License Server used to supplement the zPDT license.8 A Rational License Server is not the same as a zPDT remote license server and is not required for basic zPDT operation. The operand can be a normal URL domain name or an absolute IP numeric address. Also, note the format with the port number placed before the address. Multiple rdtservers can be specified by using a colon as the separator:
rdtserver [email protected]:[email protected]
The int3270port and intASCIIport statements provide emulation for HMC-style integrated terminal functions. The operand for each statement is a port number. After starting zPDT with one (or both) of these operands you would start a 3270 emulator connected to the indicated Linux port number or start z1090term9 connected to the indicated ASCII terminal port number. These emulated terminals need not be on the base Linux system.
The 3270 terminal session associated int3270port function probably should10 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 AD-CD 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 could be selected. We found that when attempting to connect a local x3270 session to int3270port the usual link of “localhost:3271” sometimes does not work, while “127.0.0.1:3271” did work.
|
By default, zPDT uses the Linux userid that was used to start zPDT as the instance name (the “LPAR” name). An LPAR name cannot be longer than 8 characters and this restricts the Linux userid to not more than 8 characters. However, the system_name option (maximum 8 characters) may be used to specify the LPAR name, removing the length restriction on the Linux userid used to start zPDT. The specified name is automatically converted to upper-case EBCDIC.
By default, zPDT sends output directed to the “HMC hardware console” to the Linux command window that was used to start zPDT. (If this command window is closed, the output is not displayed.) By default, this output (along with any oprmsg commands) is written to a zPDT log file. The oprmsg_file option specifies a Linux file that is to receive such messages;11 If an oprmsg_file is specified the messages are no longer written to the default zPDT log file. The file name is case sensitive. This option has several implications:
•The messages are available in the specified Linux file whether or not the original Linux command window is open.
•If oprmsg_file option is used, the default zPDT log file will not contain the messages written to the specified oprmsg_file.
•Typically, this option is used in conjunction with automation (running under Linux) that generates oprmsg commands sent to the z system. The responses, along with other operating system output, are placed in the specified Linux file where they can be inspected by the automation programs.12
The specified oprmsg_file may be deleted at any time by the user (working with Linux commands or programs). It will be recreated (empty) when the next message arrives for it.
A reasonable example of a system stanza could be as follows:
[system]
memory 8G
processors 2
3270port 3270
command 2 x3270 -model 4 -geometry +10+10 localhost:3270
command 2 x3270 -model 4 -geometry +1100+10 localhost:3270
command 4 echo 'zPDT operation has completed'
An ampersand (&) is not used after the x3270 commands in a [system] stanza. The geometry parameters are optional, of course. They simply place the x3270 windows at convenient places on the Linux desktop. Also, the x3270 sessions are automatically closed when zPDT is shut down.
A devmap has several additional features 13 as follows:
•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:
[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 parenthesis, 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 prior to 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 will be effective for any terminal window subsequently opened. For practical purposes, we suggest adding any devmap environmental variables to the .bashrc file.14 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 specified is logically inserted into the devmap at the point 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 specified cannot contain blanks. The name could 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 very 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
rdtserver [email protected]
expand 1000m #Who uses expanded memory today?
system_name old22 #maximum 8 characters
oprmsg_file /tmp/bill/messages
#ipl 0A80 “0A8200” (not recommended. Commented out here)
cpuopt alr=on ,zVM_Coupling
message This devmap is excessive
command 2 x3270 localhost:3270
command 2 x3270 -geometry +1100+100 localhost:3270
command 2 x3270 -geomentry +1100+600 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.2.1 Adjunct-processor stanza
The zPDT system optionally provides emulation of the z System cryptographic adapter.15 The release level of the cryptographic adapter varies with the zPDT release level. The basic devmap format for this emulation is as follows:
[adjunct-processors]
crypto 0
crypto 1
This defines two cryptographic processors, numbered 0 and 1. If multiple 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 indicates that the instance is using domain 2 in cryptographic coprocessors 0 and 1. See Chapter 17, “Cryptographic usage” on page 313 for more details.
3.2.2 System timer protocol stanza
The system timer protocol (STP) function is described in Chapter 20, “Server Time Protocol (STP)” on page 343. The Linux daemons associated with STP must be started before using a devmap containing a 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 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 may also include a LEAPSECONDS statement, not shown in this example. This is further described in Chapter 20, “Server Time Protocol (STP)” on page 343.
3.2.3 zEDC stanza
zPDT GA9 provides limited zEDC emulation, which is described in 12.2, “zEDC emulation” on page 223. The required stanza can look like the following:
[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 zPDT use.
3.3 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 this could be any of the supported device managers. The device manager name is followed by an arbitrary hex number (up to four digits, different for each name statement)16. 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.
– Additional optional parameters, such as these:
• --path=xx to specify an emulated CHPID number.
• --pathtype=xxx to specify an emulated CHPID type (usually EIO).
• --compress to specify compressed awstape generation.
• Various optional tunnel parameters for OSA operation.
•For device statements:
– The constant “device” starting in the first column.
– The device number (“address”) to be used, expressed in hexadecimal. This may be three or four digits.
– The device type, such as 3390. This must specify a correct device type for the device manager.
– The control unit type associated with the device, up to four characters. (This parameter is not used for anything at this time, 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 (as it would appear in an IOCDS) 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.
• Additional parameters for OSA operation.
At this time, 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 EIO17 for most device managers. In very rare cases it may be desirable to change these values. This can be done with 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 may be used. A maximum of 256 devices may be listed in a stanza, where multiple devices are not limited by characteristics of the emulated control unit. The device numbers (addresses) assigned to each device need not be sequential or in any particular order.
3.3.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 3990 /z/SARES1
device 0AA8 3390 3990 #No file specifed; can use awsmount
etc
The device type can be 3390 or 3380; in either case, the Linux file 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.
The third operand of a device statement is a control unit type. This information is not currently used by zPDT, but it is a positional operand that must be specified. All our examples for the awsckd device manager use “3990” or “2107” as the control unit type; this is an older IBM control unit. Starting with zPDT GA8, awsckd emulates IBM 2107 control units. You can specify 3990, 2107, or anything else up to four characters.
The most common CKD devices are 3390 units. Standard 3390s (models -1, -2, -3, and -9) may be used, or a variable number of cylinders may be used. The maximum size for a normal 3390 is 64K-1 cylinders; however, zPDT supports extended address volume (EAV) 3390s.
The extra cylinders of a 3390 are not emulated; these are the cylinders reserved as spares or for diagnostic use. For example, a 3390-3 contains 3339 usable cylinders, and this is what is emulated. Parallel access volumes (PAV) are not supported.
Device statements may omit a file name. In this case the indicated unit (3390 at address 0AA8 in the example) exists, but has no volume mounted. A volume (which is a Linux file in the appropriate CKD format) may be mounted (or dismounted) while zPDT is operational, providing dynamic changes to the DASD environment without stopping 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 do these 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 z System channel program.
Much more is involved in sharing z System volumes and the --shared option is only one element involved. Use this option when multiple zPDT instances (in the same Linux) are sharing DASD volumes and when separate zPDT systems (on separate Linux bases) are sharing DASD through a Linux shared file system. Proper serialization, as seen by z/OS, is essential for shared DASD and implementing such serialization typically involves z/OS GRS.18 The --shared option is not used when sharing DASD volumes among multiple z/VM guests.
3.3.2 The awsfba device manager
The awsfba device manager provides emulation for FBA disk devices19 (as used by z/VM and z/VSE).
[manager]
name awsfba 6543
device 100 9336 9336 /z/DOSRES
device 101 9336 9336 /z/DOSWRK
awsfba devices (volumes) must be created before they can be used. This is done with the alcfba utility. This device manager does not support the more recent Fibre open system FBA devices for z/OS. It is unfortunate that there are two unrelated uses of FBA terminology.
zPDT development performs only minimal testing for these FBA devices. We recommend using CKD disks unless there is a specific need for FBA disks.
3.3.3 The aws3274 device manager
The aws3274 device manager emulates local, channel-attached, DFT, non-SNA 3270 sessions. These are used for MVS consoles, simple IBM VTAM® sessions (TSO, IBM CICS®, and so forth), z/VM terminals, and similar purposes. The actual 3270 emulators (x3270, PCOMM, or other 3270 emulators) might be local (on the underlying Linux system running zPDT) or remotely connected via 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 z System software. The same physical Ethernet interface can be used for Linux functions, such as Telnet, aws3274, FTP, and so forth and also for 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 a number of options. These 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 TN3270e 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 actually passing it to VTAM.) The LU names may 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, whether or not 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 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 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 our x3270 client is on a remote machine connected to a private LAN that includes the 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, provided that device is free at this time. The fourth example illustrates that the same LUname rules apply to connections from the Linux desktop.
In this example 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 AD-CD z/OS system might be defined like this (and this is the most common example for zPDT users):20
[manager]
name aws3274 C700
device 0700 3279 3174
device 0701 3279 3174
device 0702 3279 3174
device 0703 3279 3174
.....
device 070A 3279 3174
Connections take the next free terminal in the devmap list if no LU conditions are specified. This can be useful if the first terminal in the devmap is the MVS console21 and the next terminal is a suitable TSO address. In this case, without specifying any LU names, the first x3270 session will be the MVS console and the second will be a TSO session (or CICS or some other VTAM application). As a practical matter, we have observed that few 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 available for Linux have been tested for this usage.22 The TN3270e client might operate on the machine running the 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 z System operating system.
The use 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 (via aws3274) requires a small amount of free space in the Linux /tmp file system. If /tmp is completely full, a new aws3274 session cannot be started.
3.3.4 The awstape device manager
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 may be 3420, 3480, 3490, or 3590. (The third operand, the control unit type, is not meaningful.) A file name may 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 similar to a premounted tape on a larger z System. 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 has been written. (z/OS would then probably write trailer labels and call 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 four 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 CCWs used to manipulate the Linux file name associated with the emulated tape drive. This is described in “Use special CCWs to manipulate tape volume” on page 281.
Emulated tape volumes created through this device manager are in awstape format and can be exchanged with other systems that can process this format. All awstape files are compatible with all zPDT emulated tape devices. An awstape file written by an emulated 3490 can be read by an emulated 3420, for example.
The proper responses for hardware compaction (IDRC) are emulated, although tape data is not actually compacted by this method. The awstape data may be optionally compacted by the awstape device manager. This is controlled through a devmap or an awsmount parameter. The compaction format is unique to 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 labelled tape. (An “empty” labelled tape can be created with the zPDT aws_tapeInit command.)
3.3.5 The awsosa device manager
The awsosa device manager emulates various OSA-Express functions, as used by z System TCP/IP or SNA.23 Currently the emulation level is OSA-Express5s. Two manager formats are used:
[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.24 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. That is, both OSA and Linux can share the adapter for connection to external TCP/IP systems, but they cannot communicate with each other.25 A tunnel interface (which is similar to another Ethernet adapter) is necessary for direct communication between the underlying Linux system and the z System OSA operation.
|
Tip: See “LANs” on page 123 for details about using the emulated OSA functions.
|
The --path operand specifies a CHPID number. The correct number is determined with the find_io command. For these examples we assume the CHPID for wired Ethernet is F0 and the CHPID for a tunnel interface is A0. The --pathtype is OSD (for QDIO) or OSE 26(for LCS or non-QDIO). In some cases the find_io command does not provide a CHPID (path name) for a LAN interface and the --interface=xxxx parameter may be used to name a specific LAN interface. The interaction of the --path and --interface parameters is explained in detail in Chapter 7, “LANs” on page 123. An example of using the --interface parameter might be:
name awsosa 1234 --path=B0 --pathtype=OSD --interface=em1
The --unitadd operands specify the internal OSA interface number; normally these are not needed for QDIO operation. They may 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 seen in the z/OS IODF (and when displaying devices on the MVS console).27
When used in OSE mode, the OSA interfaces are associated with OAT28 definitions that specify how each interface is to be used. Please note that OSA/SF (the z/OS program to manage OATs) is not available with current z/OS releases; the partial replacement is the QUERYINFO command, which is not supported with zPDT. SNA usage would require CHPID type OSE, although SNA usage with zPDT is not supported.
The limits in Table 3-1 apply to OSA-Express emulation.
Table 3-1 OSA-Express limits, per port
|
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 stacks per port (OSD or OSE)
|
16
|
|
SNA PUs per OSA-Express port (SNA is not supported for zPDT)
|
512
|
|
OSE subchannels per stack
|
2
|
|
OSE or OSD maximum devices
|
48
|
|
OSE IP stacks per OSA port/CHPID
|
16
|
|
OSD subchannels per stack
|
3
|
|
OSD subchannels per OSA/CHPID
|
48
|
|
Is OSA/SF or QUERYINFO available?
|
No
|
|
Is Generic VLAN Registration Protocol supported? (GVRP)
|
No
|
3.3.6 The awsrdr device manager
The awsrdr device manager emulates a 2540 card reader. Only one awsrdr device may be configured for an instance of zPDT operation. Typically, the emulated card reader is used to submit jobs to the operating system.29 If we assume this to be z/OS, then JES2 or JES3 should be configured with a “hot” reader.30 The traditional address for a 2540 is 00C, and we use this in our examples.
The awsrdr device manager monitors the directory specified in the devmap. When a file is found in the directory, it is read (assuming a z System program has a read that is outstanding for the card reader, as would be the case with a JES hot reader). After the file (“card deck”) is read, it is moved to the old subdirectory. In this way, there is never a file in the directory assigned to the reader, other than a file someone has just moved there to be read. As soon as it is read, it is moved out of the reader directory. If awsrdr is not active, or if there is no z System 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 may contain binary information. A card reader uses fixed-length records (80 bytes) but a Linux text file has variable length records terminated with an NL character.
The conversion rules are as follows:
•If the input file name (in the directory used by awsrdr) contains the suffix .ebc or .bin, then the file is assumed to already be in EBCDIC 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 is converted to EBCDIC.
•If the input file contains the ASCII characters // or ID or $$ or USERID in the first bytes, the file is assumed to be in ASCII and is converted to EBCDIC.
•If none of these conditions are true (suffix .ebc, or .bin, or .asc, or .txt, or recognizable first characters in ASCII), then the file is assumed to be EBCDIC (or binary as used for z System) and it is 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 translate ASCII text files to EBCDIC card files is with the txt2card command.
The ASCII/EBCDIC translation table is fixed in all cases.
3.3.7 The awsprt device manager
The awsprt device manager emulates a 1403 or 3211 printer. FCB functions31 are supported for 3211 emulation, but 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 these.
awsprt cannot recognize divisions between z System jobs. It simply concatenates all output (potentially from multiple jobs) into the output file. The devmap specifies the output file to be used:
[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/LF characters instead of NL characters.
The awsmount command may be used to close the existing output file and open a new output file. The previous output file is closed properly, and is then available for display or printing under Linux. “Local printing” on page 239 provides more information about printing output with the awsprt device manager.
3.3.8 The awscmd device manager
This device manager provides a “device” that appears to z System 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 may be sent, including those that could destroy the Linux system.32 Obviously, this device manager should be used with care and may not be appropriate for a zPDT environment that can be accessed by untrusted users.
Configuration is similar to other device managers:
[manager]
name awscmd 20
device 580 3480 3480
The device type can be 3420, 3422, 3480, 3490, or 3590; these are the tape device types emulated by zPDT. The device number (580) must match a corresponding device type in your z/OS IODF. (Any device number may be used with z/VM.)
The intended operation (by a z System application program) is as follows:
1. A rewind is issued to the device.
2. The desired 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. At this point, the awscmd device manager submits the command (and data) to Linux through a shell that does not appear on the Linux screen. The current Linux directory for the command is the same directory that was used to start 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) has been converted to EBCDIC.
9. Two tape marks are at the end of the pseudo tape.
Restrictions
The command 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 will appear to be busy while Linux is executing the command. Any Linux command that creates substantial delays (of many seconds) may cause I/O timeout errors to be generated in z/OS.33
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 in Chapter 11, “The awscmd command” on page 213.
3.3.9 The awsscsi device manager
The awsscsi device manager emulates a mainframe tape drive using a SCSI tape drive. The specific adapters and tape drives supported are discussed in Chapter 14, “Tape drives and tapes” on page 285. 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. This must be given as a /dev/sgx name, and not as a /dev/stx name. The differences are complex; Chapter 14, “Tape drives and tapes” on page 285 describes methods for determining the correct /dev/sgx name. The SCSI tape drive appears as a 3420, 3480, 3490 or 3592 device to the z System software.34 The awsmount command may be used with SCSI tape devices.
3.3.10 The aws3215 device manager
The aws3215 device manager provides emulation of a 3215 console, using devmap parameters such as these:
[manager]
name aws3215 AC00
device 009 3215 3215
It is possible, but very unusual, to have multiple 3215 devices. Input to the 3215 console is via the awsin command, entered in a Linux command window. Output appears in the Linux window used for the awsstart command.
3.3.11 The awsoma device manager
The awsoma device manager is used to read CDs or DVDs35 written in a special format known as OMA. This is for input only; it is not possible to write to an awsoma device. In earlier days, z/VM and z/VSE were available in OMA format; some Linux distributions for z System may 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 particular file name. That is, the second name is relative to the path specified by the first name.36
In a Linux-based zPDT system, the net effect is that the two names are concatenated. In the example above, the effective file name used for input to awsoma is /media/ROM/xyz.tdf. The slash (/) after ROM can be omitted and a slash inserted before xyz.tdf; this results in the same effective file name.
Current releases of zPDT have expanded the possible formats to include these:
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 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 used to start zPDT operation. The last example depends on the keyword TAPES to indicate that data files are relative to the directory above TAPES.37
The variable portion of the device statement may 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.3.12 The awsctc device manager
The awsctc device manager emulates a 3088 channel-to-channel 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 may be defined for this device manager. Chapter 16, “Channel-to-channel” on page 305 describes the setup and usage of this device manager.
1 This is not required by some elements of a devmap, which ignore upper or lowercase differences. Not all devmap elements do this. To avoid problems, we suggest using lowercase for everything (except for Linux file names, which are case-sensitive).
2 This statement assumes a simple, dedicated environment. Other environments may require more planning for effective memory use.
3 This kernel variable is specified by the instructions Chapter 5, “zPDT installation” on page 101.
4 The memory size may also be specified in megabytes by using a “M” suffix.
5 The number of processors for an instance has a maximum value of 8. This is usable only if multiple tokens are used or nonstandard “high capacity” tokens are used, and may be limited to zPDT license terms and conditions.
6 The first processor type listed becomes the IPL processor; zIIPs and zAAPs cannot handle an IPL.
7 zPDT uses z/VM to provide emulated CFs.
8 Contact your IBM marketing representative for more information about Rational licenses.
9 See the command descriptions in Chapter 4, “zPDT commands” on page 57.
10 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.
11 This function is described in more detail in 13.6, “zPDT log files” on page 263.
12 zPDT does not provide any such automation functions or examples.
13 These features were added for special purposes. We have not seen much usage by typical zPDT users.
14 Other required changes to the .bashrc file are described in Chapter 5, “zPDT installation” on page 101.
15 Do not confuse this with the cryptographic instructions, which to do not require any special devmap statements.
16 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.
17 EIO is a special CHPID type for Emulated I/O. zPDT users normally do not need to specify this anywhere.
18 Global resource serialization (GRS) is a basic element of a z System sysplex configuration.
19 These had IBM type numbers such as 3370, 9332, 9335, and 9336.
20 You might notice that the third operand in the aws3274 examples is sometimes 3174 and sometimes 3274 in the examples. This operand in device statements is not processed and can be any four character value. We suggest a meaningful value only for documentation.
21 The AD-CD z/OS systems have always defined the MVS console at address 700.
22 The aws3274 device manager sends an attention signal to the host when a session is first connected. In some cases, such as when connected to the VTAM unformatted system services function, this may prompt a full buffer read by the host software. If the TN3270e session buffer is not formatted for this buffer read, the host may display an “Unsupported Function” message. Simply clearing the TN3270 screen should resolve the situation. Some TN3270e emulators encounter this situation and others do not.
23 zPDT SNA usage has not been tested by IBM and no support is available for it.
24 If no IP address is specified for a tunnel interface it will default to 10.1.1.1.
25 This odd limitation is a characteristic of current Linux implementations.
26 We do not recommend OSE use unless you have a special need for it.
27 Older z/OS systems may use CTC device definitions for these interfaces, especially when they are used for TCP/IP. These definitions should be replaced with device type OSA.
28 An OAT is an OSA Address Table.
29 In principle, we could directly allocate the card reader to a job using the appropriate DD statement. We did not try this.
30 The term “hot reader” means there is always a read outstanding for the card reader. As soon as an operator places cards in the reader, JES begins reading them.
31 FCB refers to the Forms Control Buffer.
32 The Linux commands are executed with the authority of the userid that started zPDT operation.
33 Prior version of awscmd had a timeout function that limited the time allowed for the Linux command. This timeout check has been removed at customer requests.
34 Remember that IBM 3490 tape units have their own characteristics. One of these is a maximum block count of approximately 4 million (a 22-bit number).
35 It is possible to have OMA files on other media, but a CD or DVD is usually where they are found.
36 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.
37 This convention was used in the original OMA support and is documented in IBM publication SC53-1200.
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.