vmur - Work with z/VM spool file queues

Red Hat Enterprise Linux 9.2 z/VM guest

Use the vmur command to work with z/VM spool file queues.

The vmur command provides these main functions:

Receive

Read data from the z/VM reader file queue. The command performs the following steps:

Places the reader queue file to be received at the top of the queue.
Changes the reader queue file attribute to NOHOLD.
Closes the z/VM reader after the file is received.

The vmur command detects z/VM reader queue files in:

VMDUMP format as created by CP VMDUMP.
NETDATA format as created by CMS SENDFILE or TSO XMIT.

Punch or print

Write data to the z/VM punch or printer file queue and transfer it to another user's virtual reader, optionally on a remote z/VM node. The data is sliced up into 80-byte or 132-byte chunks (called records) and written to the punch or printer device. If the data length is not an integer multiple of 80 or 132, the last record is padded.

List

Display detailed information about one or all files on the specified spool file queue.

Purge

Remove one or all files on a spool file queue.

Order

Position a file at the top of a spool file queue.

Before you begin: To use the receive, punch, and print functions, the vmur device driver must be loaded and the corresponding unit record devices must be set online.

Serialization

The vmur command provides strict serialization of all its functions other than list, which does not affect a file queue's contents or sequence. Thus concurrent access to spool file queues is blocked to prevent unpredictable results or destructive conflicts.

For example, this serialization prevents a process from issuing vmur purge -f while another process is running vmur receive 1234. However, vmur is not serialized against concurrent CP commands that are issued through vmcp: if one process is running vmur receive 1234 and another process issues vmcp purge rdr 1234, then the received file might be incomplete. To avoid such unwanted effects, always use vmur to work with z/VM spool file queues.

Spooling options

With the vmur command, you can temporarily override the z/VM settings for the CLASS, DEST, FORM, and DIST spooling options for virtual unit record devices. The vmur command restores the original settings before it returns control.

For details about the spooling options, see the z/VM product information. In particular, see the sections about the z/VM CP SPOOL, QUERY VIRTUAL RDR, QUERY VIRTUAL PUN, and QUERY VIRTUAL PRT commands in z/VM: CP Commands and Utilities Reference, SC24-6268.

vmur syntax

Receive options

Punch and print options

Where these are the main command options:

re or receive: receives a file from the z/VM reader queue.
pun or punch: writes to the z/VM punch queue.
pr or print: writes to the z/VM printer queue.
li or list: lists information about one or all files on a z/VM spool file queue.
pur or purge: purges one or all files from a z/VM spool file queue.
or or order: places a file on a z/VM spool file queue at the top of the queue.

Note: The short forms that are given for receive, punch, print, list, purge, and order are the shortest possible abbreviations. In keeping with z/VM style, you can abbreviate commands by dropping any number of letters from the end of the full keywords until you reach the short form. For example, vmur re, vmur rec, or vmur rece are all equivalent.

The remaining specifications are listed alphabetically by switch. Variable specifications that do not require a switch are listed first.

<file>

specifies a file, in the Linux® file system, with data to be punched or printed. If this specification is omitted, the data is read from standard input.

<outfile>

specifies a file, in the Linux file system, to receive data from the reader spool file. If neither a file name nor --stdout are specified, the name and type of the spool file to be received (see the NAME and TYPE columns in vmur list output) are used to build an output file name of the form <name>.<type>. If the spool file to be received is an unnamed file, an error message is issued.

Use the --force option to overwrite existing files without a confirmation prompt.

<spoolid>

specifies the spool ID of a file on the z/VM reader, punch, or printer queue. Spool IDs are decimal numbers in the range 0-9999.

For the list or purge function: omitting the spool ID lists or purges all files in the queue.

-b <sep>,<pad> or --blocked <sep>,<pad>

receives or writes a file in blocked mode, where <sep> specifies the separator and <pad> specifies the padding character in hexadecimal notation. Example: <sep>

--blocked 0xSS,0xPP

Use this option to use character sets other than IBM037 and ISO-8859-1 for conversion.

For the receive function: All trailing padding characters are removed from the end of each record that is read from the virtual reader and the separator character is inserted afterward. The receive function's output can be piped to iconv by using the appropriate character sets. Example:
```
# vmur rec 7 -b 0x25,0x40 -O | iconv -f EBCDIC-US -t ISO-8859-1 > myfile
```
For the punch or print function: The separator is used to identify the line end character of the file to punch or print. If a line has fewer 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 size, an error is printed. Example:
```
 # iconv test.txt -f ISO-8859-1 -t EBCDIC-US | vmur pun -b 0x25,0x40 -N test
```

-c or --convert

converts a VMDUMP spool file into a format appropriate for further analysis with crash.

-C <class> or --class <class>

specifies a spool class.

For the receive function: The file is received only if it matches the specified class.
For the purge function: Only files with the specified class are purged.
For the punch or printer function: Sets the spool class for the virtual reader or virtual punch device. Output files inherit the spool class of the device.

The class is designated by a single alphanumeric character. For receive, it can also be an asterisk (*) to match all classes. Lowercase alphabetic characters are converted to uppercase.

See also Spooling options.

--dest <device>

sets the destination device for spool files that are created on the virtual punch or printer device. The value can be ANY, OFF, or it must be a valid device as defined on z/VM.

See also Spooling options.

-d or --device

specifies the device node of the virtual unit record device.

If omitted in the receive function, /dev/vmrdr-0.0.000c is assumed.
If omitted in the punch function, /dev/vmpun-0.0.000d is assumed.
If omitted in the print function, /dev/vmprt-0.0.000e is assumed.

--dist <distcode>

sets the distribution code for spool files that are created on the virtual punch or printer device. The value can be an asterisk (*), OFF, or it must be a valid distribution code as defined on z/VM.

OFF and * are equivalent. Both specifications reset the distribution code to the value that is set in the user directory.

See also Spooling options.

-f or --force

suppresses confirmation messages.

For the receive function: overwrites an existing output file without prompting for a confirmation.
For the punch or print option: automatically converts the Linux input file name to a valid spool file name without any error message.
For the purge function: purges the specified spool files without prompting for a confirmation.

--form <form_name>

sets the form name for spool files that are created on the virtual punch or printer device. The value can be OFF, to use the system default, or it must be a valid z/VM form name.

See also Spooling options.

-h or --help

displays help information for the command. To view the man page, enter man vmur.

-H or --hold

keeps the spool file to be received in the reader queue. If omitted, the spool file is purged after it is received.

-n <node> or --node <node>

specifies the node name of the z/VM system to which the data is to be transferred. Remote Spooling Communications Subsystem (RSCS) must be installed on the z/VM systems and the specified node must be defined in the RSCS machine's configuration file.

The default node is the local z/VM system. The node option is valid only with the -u option.

-N <name>.<type> or --name <name>.<type>

specifies a name and, optionally, a type for the z/VM spool file to be created by the punch or print option. To specify a type after the file name, enter a period followed by the type. For example:

# vmur pun -r /boot/parmfile -N myname.mytype

Both the name and the type must comply with z/VM file name rules, for example, they must be 1 - 8 characters long.

If omitted, a spool file name is generated from the Linux input file name, if applicable.

Use the --force option to suppress warning messages about automatically generated file names or about specified file names that do not adhere to the z/VM file naming rules.

-O or --stdout

writes the reader file content to standard output.

-q or --queue

specifies the z/VM spool file queue to be listed, purged, or ordered. If omitted, the reader file queue is assumed.

-r or --rdr

transferres a punch or print file to a reader.

-t or --text

converts the encoding between EBCDIC and ASCII according to character sets IBM037 and ISO-8859-1.

For the receive function: receives the reader file as text file. That is, it converts EBCDIC to ASCII and inserts an ASCII line feed character (0x0a) for each input record that is read from the z/VM reader. Trailing EBCDIC blanks (0x40) in the input records are stripped.
For the punch or print function: punches or prints the input file as text file. That is, converts ASCII to EBCDIC and pads each input line with trailing blanks to fill up the record. The record length is 80 for a punch and 132 for a printer. If an input line length exceeds 80 for punch or 132 for print, an error message is issued.

The --text and the --blocked attributes are mutually exclusive.

-u <user> or --user <user>

specifies the z/VM user ID to whose reader the data is to be transferred. If omitted, the data is transferred to your own machine’s reader. The user option is valid only with the -r option.

-v or --version

displays version information.