NAME¶
vmur - Work with z/VM spool file queues
SYNOPSIS¶
vmur [
OPTIONS]
vmur vmur_command [
command_options] [
command_args]
DESCRIPTION¶
The
vmur program allows to read, create, list, purge, or order files on
the z/VM spool files queues (RDR, PUN, and PRT).
vmur supports the following commands:
- - receive:
- Read a file from the reader queue
- - punch:
- Create a file on the punch queue
- - print:
- Create a file on the print queue
- - list:
- List one or all files on a spool file queue
- - purge:
- Purge one or all files on a spool file queue
- - order:
- Position a file at the top of a spool file queue
The
vmur program requires the vmcp kernel module as prerequisite. For the
receive, punch, and print commands the vmur kernel module is also required,
and the corresponding z/VM virtual unit record devices (in most cases 000c as
reader, 000d as punch, and 000e as printer) must be set online. See
chccwdev(8) for setting devices online or offline.
OPTIONS¶
- -h or --help
- Print help information, then exit.
- -v or --version
- Print version information, then exit.
All other options are command specific and will be discussed below in the
respective command context.
receive¶
Read file from reader queue¶
-
- Synopsis:
-
- receive [-fH] [-d dev_node] [-t | -b sep.pad | -c] spoolid [-O |
outfile]
Minimum abbreviation: re
Use
receive when you want to read a file from the z/VM reader queue. The
file to be read is identified by its spoolid, a 4-digit decimal number. Use
the 'vmur list' command to display information about files in the z/VM reader
queue.
receive options¶
The following command options are supported by
receive:
-
- -f or --force
-
- Specifies that outfile is to be overwritten without displaying any
confirmation message.
-
- -H or --hold
-
- Specifies that the reader file to be received shall remain in the reader
queue after processing. If omitted, the reader file is purged.
-
- -d or --device
-
- Specifies the device node of the virtual reader device. If omitted,
/dev/vmrdr-0.0.000c is assumed.
-
- -t or --text
-
- Specifies that a text file requiring EBCDIC-to-ASCII conversion is to be
received. Character sets IBM037 and ISO-8859-1 are used for the
conversion. An ASCII line feed character (0x0a) is inserted for each
80-byte input record read from the z/VM reader. Trailing EBCDIC blanks
(0x40) in the input records are stripped.
-
- -b or --blocked
-
- Specifies that the file is to be received using blocked mode. As parameter
for the -b option, the hex codes of a separator byte and a padding byte
have to be specified. The parameter has the following format: 0xSS,0xPP
All trailing padding bytes are removed from the end of each record read from
the virtual reader and the separator byte is inserted afterwards. The
receive function's output can be piped to iconv(1) using the
appropriate character sets, for example:
-
- # vmur re 7 -b 0x25,0x40 -O | iconv -f EBCDIC-US -t ISO-8859-1 >
file
-
- -c or --convert
-
- Specifies to convert the VMDUMP spool file into a format appropriate for
further analysis with crash or lcrash.
-
- -O or --stdout
-
- Specifies that the reader file's contents are written to standard
output.
receive arguments¶
The following command arguments are supported by
receive:
-
- spoolid
-
- Denotes the spoolid, which identifies a z/VM spool file.
spoolid is mandatory and must be a decimal number in the range 0-9999.
-
- outfile
-
- specifies the name of the output file to receive the reader file's data.
If both outfile and --stdout are omitted, name and type of the spool file to
be received (see NAME and TYPE columns in 'vmur list' output) are taken to
build output file name name.type. If the spool file to be received is an
unnamed file, an error message is issued.
receive example¶
Receive the z/VM console of your Linux guest machine. In the 'vmur list' output
this is an unnamed file with identifier CON in the right part of the CLASS
column. Assume its spoolid is 1234.
-
- # vmur re -t 1234 linux_console
-
punch or print¶
Write file to punch or printer queue¶
-
- Synopsis:
-
- punch|print [-fr] [-d dev_node] [-t | -b sep.pad] [-u user] [-n node]
[-N name.type] [file]
Minimum abbreviation: pun/pr
Use
punch/print when you want to write a file to the z/VM punch or
printer queue. Specify the --rdr option if you want the file to be transferred
to the z/VM reader queue.
punch/print options¶
The following command options are supported by
punch/print:
-
- -f or --force
-
- Specifies to automatically convert Linux input file name (or
<name>.<type> as specified with --name) to a valid spool file
name and type without any error message. Invalid characters are replaced
by _(underscore) and both <name> and <type> are truncated to a
length of maximal 8 characters.
-
- -r or --rdr
-
- Specifies that the punch or printer file is to be transferred to a
reader.
-
- -d or --device
-
- Specifies the device node of the virtual punch or printer device. If
omitted, /dev/vmpun-0.0.000d is assumed for punch, and /dev/vmprt-0.0.000e
for printer.
-
- -t or --text
-
- specifies to punch or print the input file as text file, that is perform
ASCII-to-EBCDIC conversion (using character sets ISO-8859-1 and IBM037)
and pad each input line with trailing blanks to fill up the unit device
record. The unit device record length is 80 for a punch and 132 for a
printer. If an input line length exceeds 80 or 132 for punch or print,
respectively, an error message is issued.
-
- -b or --blocked
-
- Specifies that the file is to be written using blocked mode. As parameter
for the -b option, the hex codes of a separator byte and a padding byte
have to be specified. The parameter has the following format: 0xSS,0xPP
The separator byte identifies the line end character of the file to punch or
print. If a line has less characters than the record length of the used
unit record device, the residual of the record is filled up with the
specified padding byte. If a line exceeds the record length, an error is
printed.
iconv(1) output can be piped to punch or print, for example:
-
- # iconv xyz -f ISO-8859-1 -t EBCDIC-US | vmur pun -b 0x25,0x40 -N abc
-
- -u or --user
-
- Specifies the z/VM user ID to whose reader the data is to be transferred.
The --user operand must adhere to z/VM user naming conventions. If a local
user is specified (that is the --node option is omitted), the user name is
validated against the CP directory.
The user option is only valid, if the -r option has been specified. If user
is omitted, the data is transferred to your own machine's reader.
-
- -n or --node
-
- Specifies the z/VM node ID of a remote z/VM system to which the data is to
be transferred. RSCS (Remote Spooling Communications Subsystem) must be
installed on the z/VM systems and the specified node ID must be defined in
the RSCS machine's configuration file. The node option is only valid, if
the -u option has been specified. If node is omitted, the data is
transferred to the specified user at your local z/VM system.
-
- -N or --name
-
- Specifies a name and, optionally, a type for the z/VM spool file to be
created by the punch or print function (see NAME and TYPE columns in 'vmur
list' output).
In the following situations the spool file type is ignored and only a spool
file name is set:
-
- - if the string specified in --name does not contain any period
delimiter.
-
- - if the only period appears at the very first beginning of string.
-
- - if a period appears at the very end of string and is not preceded by
another period.
-
- If --name is omitted:
-
- - The Linux input file name (if any) is taken instead and an error message
is issued, if it does not comply to z/VM file name rules (e.g. longer than
8 chars).
-
- - If the Linux input file name is also omitted (that is data is read from
standard input), then an error message is issued.
punch/print arguments¶
The following command arguments are supported by
punch/print:
-
- file
-
- Specifies the Linux file data to be punched or printed. If file is
omitted, the data is read from standard input.
punch/print example¶
Punch parmfile and transfer it to the reader queue.
-
- $ vmur pun -r /boot/parmfile
-
list¶
List file(s) on spool file queue¶
-
- Synopsis:
-
- list [-q queue] [spoolid]
Minimum abbreviation: li
Use
list when you want to display information about files on a z/VM spool
file queue.
list options¶
The following command option is supported by
list:
-
- -q or --queue
-
- Specifies the z/VM spool file queue to be listed. Possible values are rdr
(reader file queue), pun (punch file queue), and prt (printer file queue).
If omitted, the reader file queue is assumed.
list arguments¶
The following command argument is supported by
list:
-
- spoolid
-
- Identifies the z/VM spool file to be listed. If omitted, all spool files
on the specified queue are listed
-
purge¶
Purge file(s) on spool file queue¶
-
- Synopsis:
-
- purge [-f] [-q queue] [spoolid]
Minimum abbreviation: pur
Use
purge when you want to remove files on a z/VM spool file queue.
purge options¶
The following command options are supported by
purge:
-
- -f or --force
-
- Specifies to purge the specified spool file(s) without displaying any
confirmation message.
-
- -q or --queue
-
- Specifies which spool file queue contains the file(s) that you want to
purge. Possible values are rdr (reader file queue), pun (punch file
queue), and prt (printer file queue).
If omitted, the reader file queue is assumed.
purge arguments¶
The following command argument is supported by
purge:
-
- spoolid
-
- Identifies the z/VM spool file to be purged. If omitted, all spool files
on the specified queue are purged.
-
order¶
Order file on spool file queue¶
-
- Synopsis:
-
- list [-q queue] spoolid
Minimum abbreviation: or
Use
order when you want to place a spool file on top of a z/VM spool file
queue.
order options¶
The following command option is supported by
order:
-
- -q or --queue
-
- Specifies the z/VM spool file queue you want to order. Possible values are
rdr (reader file queue), pun (punch file queue), and prt (printer file
queue).
If omitted, the reader file queue is assumed.
order arguments¶
The following command argument is supported by
order:
-
- spoolid
-
- Identifies the z/VM spool file to be ordered.
EXAMPLES¶
Log and read the z/VM console from Linux¶
- 1.
- Start z/VM console spooling by issuing:
# vmcp sp cons start
- 2.
- Produce output to the z/VM console (for example, with CP
TRACE)
- 3.
- Close the console file and transfer it to the reader queue, find the spool
ID behind the FILE keyword in the corresponding CP message. In the example
below, the spool ID is 398:
# vmcp sp cons clo \* rdr
RDR FILE 0398 SENT FROM LINUX025 CON WAS 0398 RECS 1872
- 4.
- Read and save the spool file on the Linux file system in the current
working directory:
# vmur re -t 398 linux_cons
Prepare z/VM reader to IPL Linux¶
- 1.
- Send parmfile to the z/VM punch queue and transfer it to the reader queue:
# vmur pun -r /boot/parmfile
Reader file with spoolid 0465 created.
- 2.
- Send the Linux kernel image to the z/VM punch queue and transfer it to
reader queue:
# vmur pun -r /boot/vmlinuz -N image
Reader file with spoolid 0466 created.
- 3.
- Move the Linux kernel image to the first and parmfile to the second
position in the reader queue:
# vmur or 465
# vmur or 466
- 4.
- Prepare re-IPL from the z/VM reader and reboot:
# chreipl ccw 0.0.000c
# reboot
SEE ALSO¶
chccwdev(8),
vmcp(8),
iconv(1)
Linux on System z - Device Drivers, Features, and Commands