VMUR(8)

📦 version 2.44.1, in opensuse-leap 16.0

🦋 VMUR(8) — Work with z/VM spool file queues 🦋

🌸 NAME 🌸

vmur — work with z/VM spool file queues, bestie 💅

✨ SYNOPSIS ✨

vmur [OPTIONS]
vmur vmur_command [command_options] [command_args]

💖 DESCRIPTION 💖

With the vmur program you can read, create, list, purge, or order files on the z/VM spool files queues (RDR, PUN, and PRT). Literally so many queue slay possibilities 🎀

vmur supports these 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. No cap, device vibes must be correct first 🫶

✨ 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. iykyk 🌈

💌 receive

Read file from reader queue

Synopsis:

receive [-fH] [-d dev_node] [-C class] [-t | -b sep.pad] 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. Bestie, this is your reader-queue main character moment 👑

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. Bye-bye file 👋
  • -C or --class — Specifies the spool file class to match particular reader files. The class value is a 1-character alphanumeric field whose values can be A through Z, 0 through 9, or asterisk (*).

If you omit this option, the asterisk (*) is used to receive files of any class.

  • -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. Conversion slay ✨
  • -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 — Dump file conversion has been removed from vmur(8) and -c is no longer a valid option. An error message is displayed and the program terminates. Use zgetdump(8) to convert VMDUMP files to a format appropriate for further analysis with crash.
🚨 Okay bestie, this one is gone-gone. -c is not valid anymore. Use zgetdump(8) instead, fr fr.
  • -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. Unnamed file? Not the vibe 😭

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] [-C class] [--form form] [--dest dest] [--dist distcode] [-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 queue? Printer queue? Reader queue? Choose your fighter 💅

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.
  • -C or --class — Specifies the spool file class assigned to the spool files created on this punch or print. The class value is a 1-character alphanumeric field whose values can be A through Z and 0 through 9.
  • --form — Specifies the form to be assigned to the spool files on this punch or print. The value is a 1- to 8-character value.
  • --dest — Specifies the destination value to be assigned to the spool files on this punch or print. The value is a 1- to 8-character value.

If the destination value has not been changed otherwise, for example, by a CP SPOOL command, the default is OFF. OFF is the initial setting of the destination value for virtual devices. Specify ANY to indicate that the resulting spool file can be processed on any CP output device that meets other selection criteria, regardless of the device's DEST setting.

  • --dist — Specifies the distribution code to be assigned to the spool files on this punch or print. The distribution code, distcode, is a 1- to 8-character value and appears on the separator page.

If OFF or an asterisk (*) is specified, the distribution code of the spool file is reset to the distribution code in the system directory.

  • -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. Peek at the queue, bestie 👀✨

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 one argument list fucks with:

  • spoolid — tells list which z/VM spool file you want to see. Leave it out and it'll spill the tea on all the spool files chilling on the queue you picked. 👀

🗑️ purge

Purge file(s) on spool file queue — aka the "delete it, delete it now" era.

Synopsis:

purge [-f] [-q queue] [-C class] [--form form] [--dest dest] [spoolid]

Minimum abbreviation: pur

Use purge to yeet files off a z/VM spool file queue. You choose which files get the boot with the class, form, or dest options, plus the spoolid argument. Omit all of those and — no cap — every spool file on the specified queue gets purged. All of them. Gone. 💀 So maybe double-check before you hit enter, bestie.

✨ purge options

Here's what purge takes:

  • -f, --force — purges the spool file(s) you named with zero confirmation message. No "are you sure?", no pause, no vibe check. Just gone. 🔥
  • -q, --queue — which spool file queue has the file(s) you want to purge. Possible values are rdr (reader file queue), pun (punch file queue), and prt (printer file queue). If you omit it, the reader file queue is assumed. 🧚
  • -C, --class — a spool file class. Every file of that class gets purged. The class value is a 1-character alphanumeric field whose values can be A through Z, 0 through 9.
  • --form — a form name. Every file with that form name gets purged. The form name is a 1- to 8-character value.
  • --dest — a destination value. Every file with that destination value gets purged. The destination is a 1- to 8-character value.

🧾 purge arguments

One argument, and it's the important one:

  • spoolid — identifies the z/VM spool file to be purged. Bye boo 👋

👑 order

Order file on spool file queue — main character energy for your spool file, because it jumps the line.

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. Like, front of the line, VIP section, velvet rope situation. 🎀

Yes, the synopsis really does say list up there — that's exactly what's printed, and I'm not out here editing the source, bestie. 🙈

💅 order options

Just the one:

  • -q, --queue — which 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 you omit it, the reader file queue is assumed.

🌸 order arguments

  • spoolid — identifies the z/VM spool file to be ordered. Give it the front-row seat it deserves. ⭐

🌈 EXAMPLES

💜 Log and read the z/VM console from Linux

  1. Start z/VM console spooling by issuing:
# vmcp sp cons start
  1. Produce output to the z/VM console (for example, with CP TRACE)
  2. 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
  1. 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.
  1. 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.
  1. Move the Linux kernel image to the first and parmfile to the second position in the reader queue:
# vmur or 465
# vmur or 466
  1. Prepare re-IPL from the z/VM reader and reboot:
# chreipl ccw 0.0.000c
# reboot

👀 SEE ALSO

chccwdev(8), vmcp(8), iconv(1), zgetdump(8)

Linux on System z - Device Drivers, Features, and Commands

That's the whole page, bestie — you made it to the end and I'm so proud of you 🫶✨ This one ships as part of s390-tools, dated January 2015, and it's registered under VMUR(8) — go forth and spool responsibly 💖🎀

📦 where this page comes from