Table of Contents
VM/CMS Survival Guide
LivingComputers.Org is shutdown due to the pandemic. So without them, we'll just copy the idea here and make things available more broadly - and in a different way.
This is a brief introduction to basic concepts and commands for using a virtual IBM 4381 midrange computer system.
The virtual 4381 runs the VM/370 virtual machine operating system.
VM is basically two components:
- The Control Program (CP) which controls the real hardware and provides a virtual machine (VM) for each user, and
- The single user Conversational Monitor System (CMS) is an operating system itself, which runs in a virtual machine (VM) to provide the user environment (this is the equivalent of a shell to you UNIX/Linux users or the Command Line to VMS and Windows users).
And Now, a Word From the Vendor
IBM has published an introductory document, The Basics of Using z/VM.1) This gives a short overview of VM in general. But it's not useful from a hobbyist perspective.
A far more useful document is one written by Melinda Varian: "What Mother Never Told You About VM Service - A Tutorial".
The VM user environment has not changed extensively between VM/SP 5 and z/VM (the hobbyist version of it is VM/370), but there are few differences to point out between the Virtual 4381 and the environment described in the document:
- The Virtual 4381 is a 32-bit machine with a 24-bit (16 megabyte) address space.
- MVS/XA, MVS/ESA, and z/OS guests (all descendants of MVS) cannot run under VM/SP.
- VM/SP does not have a POSIX shell or related utilities
- You cannot switch between sessions at the
- VM/370 only supports minidisks for storage; it does not support:
- SFS (Shared File System)
- BFS (Byte File System)
- NFS (Network File System)
- VM/370 supports the
CP TRACEcommand, but not as documented in the presentation. (Enter
HELP CP TRACE.)
- VM/SP does not support the
CP TERM MOREcommand.
Connecting to the 4381
Secure Shell (ssh)
You can connect to LCM+L's 4361 with Secure Shell (ssh).
Once you have connected to the 4361, you can follow the instructions on this page starting with the section “Log-on Procedure”.
The PA2 3270 terminal key (for clearing the screen) is mapped to Ctrl-A 2 (Control-A followed the number 2) when connecting with ssh.
(ssh is available as part of the OpenSSH package for MacOS, *BSD and Linux operating systems, or PuTTY for Microsoft Windows.)
3270 Terminal Emulator
The VM/CMS system was originally designed to be accessed from a 3270-compatible terminal. Today, since 3270 hardware is rare, you will probably use 3270 emulator software.
x3270 is a free open source software suite of 3270 terminal emulator tools by Paul Mattes and others. It includes clients for X11 (x3270; for Unix, Linux, *BSD, etc.), MS Windows console (wc3270), and others.
Download an appropriate package and follow the instructions to install it on your system.
Where to connect
On most platforms you can specific the model of terminal emulator if you start the program from the command line. The model is composed of two parts:
- The model number:
3278are monochrome terminals. These were the most common type when real 3270 terminals roamed the land.
3279are color terminals. VM/SP has good support for them, and are generally preferred when using modern terminal emulators.
- The model suffix, which specifies the screen size:
2is the classic 80 columns by 24 lines.
3is 80 columns by 32 lines.
4is 80 columns by 43 lines. This is useful for editing.
5is 132 columns by 27 lines. This is useful for reviewing listings.
Thus for a color terminal sized 80×43, the full model is specified as
Unix (Linux, *BSD, Mac, ...)
You can login via
x3270 from via a terminal window the X-Windows menus:
- Using a
xtermor other terminal window:
x3270 –model 3279-4 tty.livingcomputers.org 24
- Using X Windows menus:
- In your X session, run
- From the Connect menu click Other….
- In the “x3270 Connect” window, enter the following Hostname:
- Click Connect. (The host will automatically be added to the Connect menu for future sessions.)
You can also install and use the more limited text window version,
c3270; this will be limited by the size of the window it runs in:
c3270 –model 3279-4 tty.livingcomputers.org 24
- Run the wc3270 Session Wizard.
- On the Overview menu, select “1. Create new session (new)”.
- Enter the configuration parameters from the table below.
- Answer “y” to “Create session file '…'?”.
- Optionally, answer “y” to “Create desktop shortcut?”.
- Return to the Overview menu and select “8. Quit (quit)”.
If We Tell You Nothing Else ...
First things first:
- Figure how your terminal emulator sends
PA2to the host. For example, the default x3270 mapping is
Alt-2. This is because …
- … Once connectted to VM, to clear the screen, use host key
PA2. This clears all but the input area at the bottom of the screen.
You'll also need to know how your emulator sends:
^(Insert Mode) (by default, 3270 terminals overwrite)
Connect and Log-on
Start your 3270 terminal emulator and connect to the LCM+L's 4361.
You'll be rewarded with a screen like the one below, which is the front end terminal controller emulator for the 4361.
X on any device, and press
ENTER. You'll be rewarded with the VM Login screen:
Note: If this icon, , on the bottom line of your terminal, it means you tried to input data when the cursor was not located in an input field on the terminal screen. Press
TAB to move the cursor to the next input field.
Enter your Userid & Password (use
TAB to move the cursor to the next input field), press
ENTER and you're off to the races.
Your CMS Session
After you log-in, your terminal will look something like this:
The terminal screen is divided into four areas:
A: System output. Commands you input to CMS are echoed here, and all system output is printed.
B: User input. This is the only input area on the default CMS screen.
C: System status
D: Terminal status
When you see the ready prompt (
Ready; T=0.21/0.38 02:40:57 in the screen shot above, but yours can be customized), type commands into the user input area followed by
ENTER, and CMS will try to fulfill your every desire.
The system status area indicates the state of your CMS session and what kind of input the system is expecting from you. The following messages may be displayed:
| ||CMS is waiting for you to type a command. This is the most common message.|
| || The system is pausing in the middle of multi-screen output to give you a chance to read. After one minute the next screenful of output will be displayed. If you are ready for the next screen of output before then, press
| ||The system is waiting for you to read the current screen of output. Press PA2 to continue.|
| ||CMS or another VM program has requested input from you and is waiting for your answer.|
| || CP (the virtual machine hypervisor running underneath CMS) is waiting for a command. If you were previously working in CMS or a program you ran from CMS and got interrupted accidentally, try entering the command
| || You entered a command when the system wasn't ready. Press
Resources, including disk, are allocated by CP among users as disks and links defined by the user directory, a file maintained by the system administrator. Disks can be dedicated in their entirety to a single user2), or divided into disks for smaller users. Such smaller disks are called minidisks. Common minidisks are listed below.
|Common Name||Device Address||Detailed Description|
| System Disk |
|190||The CMS operating system and basic system programs are located on this disk.|
|User A-disk||191||The personal writable disk of the user.|
|D-Disk||192||A work disk which is automatically formatted if it is writable and unformatted.|
|G-Disk||19C||On the LCM+L 4361, it is read only and contains games.|
|Y-Disk||19E|| An extension of the S-Disk, this contains utilities which are not part of the base system. For example, on the 4361 it contains compilers,
|Help Disk||19D||The location for system help files. This is automatically accessed, usually at file mode Z, when needed by the Help system.|
As noted above, access to others' disks are done by link definitions in the system directory. Each disk in the directory may have one or more link passwords. If a disk is that is not defined as attached to your VM has a password for a mode, you may link it via a user command.
|RR||Read/Read||Attach to the disk read/only (R/O) if no one is linked to it, else attach to the disk R/O.|
|WR||Write/Read|| Attach to the disk writable if no one is linked to it, else attach to the disk R/O. Generally, not used in favor of
|MR||Multi-write/Read||Attach to the disk writable if no one is writing to it, else attach to the disk R/O.|
|MW||Multi-write/Write||Attach to the disk writable if no one is writing to it, else attach to the disk writable anyway. Using this mode will destroy a CMS-formatted disk. So forget you were told this option exists.|
A file on a CMS file system is described in three parts, separated by spaces. All three parts are required.
|file name||fn||The one to eight character name of the file.6)|
|file type||ft||The one to eight character type of the file. See below for a list of important types.|
|file mode||fm||The two-character mode of the file. The first character is the alphabetic letter of the disk, the second character a number between 0 and 6, described below.|
Like Windows, the function of a file on CMS is defined by its type. Common types are listed below.
| File Type |
are in italics)
| ASSEMBLE |
|Source files for programs|
|EXEC||An executable (human readable) script. The language may be EXEC, EXEC 2, or REXX|
|LISTING||The printable output from a compiler or other program.|
|MACLIB||Multiple source files organized into a single file, used as source includes for source programs.|
|MODULE||An executable binary program.|
|SYNONYM||A list of user command synonyms and acceptable abbrevations.|
|SCRIPT||A source file for the SCRIPT Markup language used for formatting text.|
|TEXT||Object code. They are linked into runnable MODULES.7)|
|TXTLIB||Multiple text (object) files organized into a single file, used as object code includes for compiled programs.|
|VMARC||Like a ZIP or TAR files on other platforms, this is file an archive for files on VM. It is specifically formatted to a standard format of 80 byte records to allow binary transfer via foreign systems, VM readers, RSCS, and IND$FILE without corrupting the data.|
|XEDIT||An executable (human readable) script executed by the XEDIT editor. Supports the same languages as EXEC.|
As noted above, file modes consist of the letter of the disk the file resides on, and number further defining a file.
|0||Private||The file is only visible to the current user with write access.|
|1||Normal||The file is visible to all users. This is the default mode for most files created.|
|2||Public|| The file is visible when accessed with a filter, such as
|3||Temporary||The file is deleted after open for reading. Useful for things like intermediate steps in compile procedures.|
|4||OS specific||The file is written according to special rules for OS emulation.|
|5||Normal (alternative)||The file is the same as file mode 1, but visually set apart by their number. Often used for generated LISTING files.|
|6|| Update |
|Normally, an update to a file occurs by allocating a new block on the disk and writing it. With mode 6, the original block is rewritten.8)|
HELP command at the command prompt on most of the commands below. Most commands can be abbreviated, and
CP can usually be omitted.
|DIRMAINT|| Change your password and set other account parameters. Use
|FILELIST9)||Display files in a scrollable display|
|FLIST10)||Display files in a scrollable display|
|GAME||Display games menu. This command has no help topic.|
|HELP||With no operands, lists a a top-level menu of topic areas.|
|LISTFILE||List files at the terminal|
|CP LOGOFF||Terminate your session|
|NAMES|| Edit your address book, which is used by
|NOTE||Send an email to another user on the local machine.|
|CP QUERY NAMES11)||Display list of currently connected users.|
|CP QUERY VIRTUAL12)||Display configuration of your virtual machine|
|RDRLIST||Display the contents of your virtual reader|
|RENAME||Rename files on a disk (will not move between disks|
|SENDFILE||Send a file to another user|
|TELL||Send a message to another user|
|XEDIT||Edit a file|
In addition, compilers for the following languages are available: Assembler (
ASSEMBLE), BASIC, C, COBOL, FORTRAN, PL/I (
PLI). (Where not otherwise noted, the compilers are invoked by their language name.) Not all of those have HELP files.
XEDIT Text Editor
For its environment, XEDIT is both an easy to use and powerful editor. It's primary lack is no cut-and-paste, but modern terminal emulators can do client-side pasting which is not visible to the mainframe.
However, this power does require a good explanation, so this humble author defers to IBM on the topic; see XEDIT Users Guide for z/VM for a proper overview of XEDIT.
Note: Most XEDIT examples show a prefix area with equal signs to the left of the screen, a scale across the middle of the screen, and the current line in the middle of the screen as well. The LCML4361 profile, which resides on the Y-Disk, changes this appearance to reduce the fixed “chrome”; it also moves the current line up, and provides line numbers in a right hand prefix area out of the way.
You can move current line back to the middle and turn on the left prefix area and scale by entering the following commands in XEDIT:
SET CURLINE ON M SET PREFIX ON SET SCALE ON
You can permanently customize the appearance by creating your own
PROFILE XEDIT A, or simply editing the file on the Y-DISK and changing the file mode to A (
SET FMODE A) before you save it.
Types of Scripts
File of type
XEDIT can be one of three languages:
- Rexx (Restructured Extended Executor), released with VM/SP 3 in 1982, is a block structured, high-level programming language. The first line of a Rexx program on CMS must begin with a C-style comment (
- EXEC 2, released with VM/SP 1981, is an enhanced version of EXEC, with longer tokens, ability to communicate with commands such as GLOBALV and EXECIO, and other enhancements. The first line of an EXEC2 program must start with
- EXEC dates back to 1966 and the original CP-67 System, and based on even older facility for CTSS . It's famous for truncating tokens in strings to eight characters, which is rather annoying if your last name is “Cowlishaw”. All EXEC and XEDIT files which are not flagged by their first line as Rexx or EXEC2 programs are processed as
See For Further Reading below for the primary IBM references and other resources on Rexx. The addition information on Rexx on the 4361 itself:
HELP REXXto get a basic feel of the language
- Browse the
KENDRA XEDIT Yto see a sample of the code.
EXEC and EXEC2 help
For help on the earlier scripting languages, enter:
HELP EXEC MENU
MENU is needed for EXEC but not the other languages because there is an
EXEC command which, not surprisingly, runs
Compilers & Interpreters
As of this writing, two modern (to the 1980's) compilers are installed on the 4361:
- C (
GCC) NOTE, be sure to
HELP GCCfor details on increasing VM STORAGE
- VS FORTRAN Version 2 (
- PL/I Optimizing Compiler (
Not-so Modern Compilers
Older compilers, most dating to the original OS/360 era, are also installed:
- FORTRAN G (
- FORTRAN H (
- PL/F (
All the compilers run
TEXT (object) files, which need to be combined with run-time libraries and saved as executable
MODULE files. Various sample scripts will do this for simple programs:
For a more detailed example of linking a program and running it, see vm_cms_fortran
Rounding out the language processors are interpreters, which were primarily oriented towards educational environments:
- PL/C for CMS (
- WATFIV FORTRAN (
These do not generate
TEXT files with object code, but instead run the translated programs immediately.
For Further Reading
Most the links in section are PDF files, many cases scanned copies of the original IBM manuals loaded to the site http://bitsavers.org/.
Core VM/SP Specific Manuals
Note: Where VM/SP Release 5 manuals are not available, other releases are used as listed. For release 6, most differences are minor and/or obvious, for example the new for release 6 Shared File System was supported. Usually, an appendix in each newer manual lists the differences from release 5.
|Title||Retrieved||Description / Comments|
|VM/SP CMS User's Guide Release 3||18-07-2018||CMS User Guide, release 3.
Note: This describes how to use
|VM/SP CMS Command Reference Release 5||18-07-2018||The command reference for CMS commands.
Note: Does not include
|VM/SP CP General User Command Reference Release 6||18-07-2018||The command reference for CP commands, release 6.|
|VM/SP System Product Editor User's Guide Release 6||18-07-2018||User guide for XEDIT, release 6.|
|VM/SP System Product Editor Command and Macro Reference Release 6||18-07-2018||Command Reference for XEDIT, release 6.|
|VM/SP System Product Interpreter User's Guide Release 6||18-07-2018||Rexx User Guide, release 6.|
|Vm/SP System Product Interpreter Reference Release 6||18-07-2018||Rexx Reference, release 6.|
|VM/SP EXEC2 Reference Release 5||18-07-2018||Reference for the older EXEC 2 language.|
|VM/SP CMS Command and Macro Reference||16-12-2018||Early version of the CMS Command Reference above, but also includes CMS Assembler Macros for programming. release 1.|
|VM/SP CMS for Systems Programming Release 5||18-07-2018||A guide to CMS for heavy hitting IBM Assembler Programmers.
It will bring out your inner CMS geek or send you screaming. (Or both.)
|VM/SP System Facilities for Programming Release||18-07-2018||Like the guide to CMS above, a guide to CP for heavy hitting IBM Assembler Programmers.
It will bring out your inner CP geek or send you screaming. (Or both.)
Other VM related documents
|Bitsavers VM/SP manual archive||07-18-2018||Index to All VM files collected by the archive. If looking for a particular manual and it's not found under Release 5 Dec86, look to the newer and older releases for a near match.|
|CALL/360: BASIC Reference Handbook||12-14-2018|
|VS FORTRAN Version 2 Programming Guide for CMS and MVS||07-18-2018|
|The Basics of Using z/VM||07-18-2018||Introduction referenced at the top of this guide.|
|Rexx Programmer's Reference||07-18-2018||Third partry Rexx reference from the The Rexx Language Association|
|VM/CMS. Fake Your Way Through Minis and Mainframes.||07-18-2018||Third party tutorial on CMS|
|VM/CMS User Guide and Reference Manual||07-18-2018||Another (less useful) third party tutorial on CMS|
|VM/SP General Information Release 4||18-07-2018||General overview, not very useful in the LCML environment. For Release 4.|
IND$FILEperforms transfers via a 3270 terminal emulator
SMARTshows system activity, similar to
topon UNIX or
Task Manageron Windows. It is invoked by the user command
VMC, or more easily via the
SNOWHITE NAMES A1and
SNOWHITE NETLOG A1.
FILELISTuses XEDIT, which makes it slower than
FLIST. However, XEDIT never gets confused by terminal sizes which don't match what the system was originally configured for.
FLISTis a compiled program, which makes it faster
FLISTcan be confused by non-standard terminal sizes.
HELP CPQUERY NAMES.
HELP CPQUERY VIRTUAL