GC20 1804 3_VM370_Command_Language_Rel_2_Jan75 3 VM370 Command Language Rel 2 Jan75

User Manual: GC20-1804-3_VM370_Command_Language_Rel_2_Jan75

Open the PDF directly: View PDF .
Page Count: 458

Download
Open PDF In Browser	View PDF

File No.
8370-36
Order No. GC20-1804-3

Systems

IBM Virtual Machine
Facility/370:
Command Language Guide
for General Users
Release 2 PLC 13
This publication provides general users with the basic information they need to use the CP and CMS command
languages of VM/370. General users are those users who
program, test, and execute applications in a virtual machine.
VM/370 (Virtual Machine Facility/370) is an operating
system that manages the resources of a single System/370
computer so that multiple computing systems (virtual
machines) appear to exist. VM/370 consists of a Control
Program (CP), which manages the real computer, a Conversational Monitor System (CMS), which is a generalpurpose conversational time-sharing system that executes
in a virtual machine, and a Remote Spooling Communications Subsystem (RSCS), which spools files to and from
geographically remote locations.
This publication has two parts and several appendixes.
Part 1 is the usage information; it contains the rules for
using the command languages and information about virtual disks, CMS files, and virtual machine operation.
Part 2 is the reference information; it describes each of the
CP and CMScommands for general users. The appendixes
include information about the functions of VM/370
commands, problem program debugging, the CMS Batch
Facility, CMS macro instructions, and CMS filetype and
filemode conventions.
Prerequisite Publications

Introduction to Virtual Storage in System/370, Order
No. GR20-4260

IBM Virtual Machine Facility/370: Terminal Users'
Guide, Order No. GC20-181 0

GC20-1804-3 Page Modified by TNL GN20-2659

This edition, together with Technical Newsletter GN20-2659 dated March
31, 1975, corresponds to B~l~~§~ l g1~ 11 (Program Level Change) of the
IBM Virtual Machine Facility/370, and to all subsequent releases unless
otherwise indicated in new editions or Technical Newsletters.
Changes are periodically made to the specifications herein; before using
this publication in connection with the operation of IBM systems,
consult the latest 1~~ ~1§1~~LJ§Q ~nQ ~1§1~~LJ1Q ~i~liQ~!~E~l, Order No.
GA22-6822, and its Yi!1g~1 ~1Q!~~~ ~gEE1~~~n1, Order No. GC20-0001, for
the editions that are applicable and current.
Technical changes and additions to text and illustrations are indicated
by a vertical bar to the left of the change.
Requests for copies of IBM publications should be made to your
representative or to the IBM branch office serving your locality.

IBM

A form for readers'
comments is
provided at the back of this
publication.
If the form has been removed, comments may be addressed to
IBM Corporation, VM/370 Publications,
24 New England Executive Park,
Burlington, Massachusetts 01803. Comments become the property of IBM.

Business Machines Corporation

1972, 1973,

GC20-1804-3 Page Modified by TNL GN20-2659

Preface

This publication is an introduction to, and
a user's guide and reference manual for,
all general users of the VM/370 command
languages (CP and CMS) •
It
contains
only
those
commands
available for general users; other commands
are listed in the publications !~~ Virtual

~~£h!B~

~~f!1!!IL11Q:

Order

No. GC20-1806,

Order

No.

~~£!l!1ILllQ:

~~£~!n~

GC20-1807,

f!Qg!~~~~!~§

~~£!l!!IL11Q:

~2~~Yn!£~!!Qn§
~Y!£~'

§I§!~!

Q£~!~!2!~§

IBM Virtual
!~~

and

2Y~§I§!~m

~~~Q!~

(~2~2)

-Guide:
Machine
-Guide:
vIrtual

2~QQ!Ing
~§~!~§

Order No. GC20-1816.

The publication is organized in
parts: "Part 1: Usage Information"
"Part 2:
Reference Information".

two
and

Part 1 has six sections:
"section 1: Introduction and General
Concepts" is a summary of general concepts
you should be familiar with when you are
using VM/370.
"Section 2: The VM/370
CP and CMS
Command Languages" describes the VM/370
command environments, the general structure
of the command language, and, in general,
how to use the features of the VM/370
command
languages to
help you
solve
programming problems.

machine. It includes information about the
virtual machine console, attaching devices,
handling tape drives, loading operating
systems, spooling the
console, reading
cards, printing, punching, disconnecting
the terminal, and alternating execution of
operating systems in one virtual machine.
Part 2 is in two sections:
"Section 7: Format and Usage Rules for
CMS Commands" and "Section 8: Format and
Usage Rules for CP Commands" provide you
with all the information you need to use
the commands and facilities of VM/370.
Also
included is
a
summary of
the
notational conventions used to describe the
commands.
The "Appendixes" include more reference
information. They include a list of the
functions performed by VM/370 commands,
information on how to debug using VM/370,
how to use 'the CMS Batch Facility, a list
of macros you can use with the VM/370
assembler, a chart showing the filemodes
related
to files
manipulated by
CMS
commands, and a list of filetypes reserved
by VM/370.
In this
publication,
terminology is used:
~

"Section 3: CMS Virtual Disks and How to
Use Them" describes the virtual disk system
for your virtual machine and how to use
it.
"Section
4: The
CMS
describes the file as it is
system. This section gives
on how to create and name a
are used in the system, and
OS data sets and DOS files.

•
File
System"
used in the CMS
you information I .
file, how files
how CMS handles
•

"Section 5: Writing and Executing a
Sample
Program
US1ng
CMS"
is
an
introduction to the
VM/370 interactive
programming environment.
In this section,
you are given a program that you can enter
at your terminal as you read the book.
Together with the information in the four
preceding sections, this sample program
should
provide
you
with
the
basic
information you need to use your virtual
machine and its interactive capabilities.
"section 6:
describes the

Virtual Machine
operation of

Operation"
a virtual

the

following

"3330 series" is used to refer to the
IBM 3330 Disk Storage Models 1, 2, and
11, and the IBM 3333 Disk Storage and
Control Models 1 and 11.
2305 refers to the IBM 2305
Storage, Models 1 and 2.
to

3270
refers
station.

the

Fixed Head

3277

Display

Any information pertaining to the IBM
2741 terminal also applies to the IBM
3767 terminal unless otherwise noted.
For a

glossary of VM/370 terms

!]~ !!!!~~1 ~~£~!~
~nQ ~~§!~! !nQ~!,

see the

~~f!!!!IL11Q: Q!~§§~!I

Order No. GC20-1813.

PREREQUISITE PUBLICATIONS
You should be familiar with the information
in the publications listed on the front
cover before you use this publication.

If the IBM 3767 Communication Terminal
is a virtual console, the publication !~~
1167 Q£~!~!Q!~§ §~!g~, Order Ho. GA18-2000,
is also a prerequisite.

~1§!~! R!Q9I~!~!~§

GC20-1807
~l§te! ~~SSgg~§,

§~ide,

Order

No.

Order Ho. GC20-1808

COREQUISITE PUBLICATIONS
The
information
in
the
following
publications
describes
certain
VM/370
facilities in greater detail and with more
examples than can be contained in this
pUblication:

~~!I ~~!g~,

Order Ho. GC20-1805

References
in
text to
titles
of
prerequisite
and
corequisite
VM/370
publications will be given in abbreviated
form.

GC20-1804-3 Page Modified by TNL GN20-2659

summary of Amendments
for GC20-1804-3
VM/370 Release 2 PLC 13

VM/370 MEASUREMENT FACILITY
!g!: Program Feature

!g!: Program Feature

new class G coamand, INDICATE, allows you
to display, at
your terminal, certain
system load conditions and your virtual
machine's use of system resources.
The
following changes to this aanual reflect
this support:

VM/370
now
supports
the
IBM
3270
Information Display System as a remote
virtual
machine console
attached
via
nonswitched point-to-point lines to a 2701
Data
Adapter Unit,
2703
Transmission
Control Unit, or 3704/3705. Communications
Controller in emulation aode.
The remote
3270 user also has
the capability of
copying an entire screen display on a 3284,
3286, or
3288 Printer at
the remote
location.

•

"section 8: Format and Usage Rules for
CP Commands" is updated to include the
new INDICATE command.

•

"Figure 34. Commands Accepted from Each
User Class" is updated.

•

"Figure 35.
updated.

•

"Figure 44.
Commands for System
Hardware Analysis" is updated.

Command

Summary"

The following changes to
reflect this new support:

this

manual

•

"Section 7. Format and Usage Rules for
CMS Commands" is updated to reflect
additional operands and subcommands of
the EDIT command.

•

"Section 8. Format and Usage Rules for
CP Commands" is updated to include the
COpy function of the SET command.

•

"Figure 34. Commands Accepted from Each
User Class", "Figure 36. Commands to
Control a Terminal Session", and "Figure
42.
Commands to Control VM/370" are
updated to reflect additional operands
to
the
NETWORK,
QUERY,
and
SET
commands.

and

VM/VS HANDSHAKING FEATURE
!g!: programming Feature
The
VM/VS
Handshaking feature
is
a
communication path
between VM/370
and
OS/VS1 that makes
each system control
program aware of certain capabilities and
requirements of the other.
The following
changes
to this
manual reflect
this
support:

NEW OPERANDS FOR SET COMMAND
•

A new operand, PAGEl, is added to the CP
SET command.

•

The response for the
command line is updated.

!g!: Program Feature
CP

QUERY

SET

•

"Figure 34. Commands Accepted from EAch
User Class" is updated.

•

"Figure 41 Commands
Control is updated.

for Virtual Machine

Two new
operands to the
SET command
described in "Section 8: Format and Usage
Rules for CP Commands" allow the virtual
machine user to enable and disable the
EeMODE and/or ISAM options, dynamically.

GC20-1804-3 Page Modified by TNL GN20-2659

NEW OPERAND FOR SLEEP COMMAND

MISCELLANEOUS

!g~:

fh~~ggQ:

Program feature

A delay time interval may now be specified
as an operand on the SLEEP command line.
The use of this optional operand causes the
virtual machine to automatically awaken at
the end of the specified time interval.
The new command format is described in
"Section 8: Format and Usage Rules for CP
Commands".

Documentation Only

This Technical Newsletter contains other
minor technical and typographic changes.

Summary of Amendmen~s
for GC20-1804-3
VM/370 Release 2 PLC 11

NEW DEVICE SUPPORT

•

"Section
updated.

!&!! Program Feature

•

The IBM 3340 Direct Access Storage Facility
is now supported by VM/370.
This support
includes Rotational Position Sensing (RPS)
and the 3348 Data Module, Models 35, 70 and
70F (supported
as a Model
70) •
The
following changes to this manual reflect
this support:

The
eMS
ACCESS,
FILEDEF,
LISTDS,
MOVEFILE, and STATE command descriptions
in "Section 7: Format and Usage Rules
for CMS Commands" ar~ updated.

•

"Figure 37. Commands to Develop Programs
and Process Data" is updated.

•

The control statements and messages of
the DASD
Dump Restore
program are
updated.

CMS ZAP SERVICE PROGRAM ENHANCED

•

T3340 is a new operand for the CP DEFINE
command.

The CMS

File

System"

!g!: Program Feature

•

The device type field in the response
for the CP QUERY VIRTUAL DASD command
line is updated.

VM/370 supports the IBM 3767 Communication
Terminal (at 300 bps) operating as an IBM
2741 Communication
Terminal only.
No
coding
changes
were
necessary;
the
following changes to this .anual reflect
this support:
•

The list of prerequisite publications in
the preface is updated.

•

"The Terminal: Your Virtual Console"
discussion in "Section 5: Writing and
Executing a Program Using VM/370" is
updated.

•

The discussions of the BLIP and AUTOREAD
functions of the CMS SET command are
updated.

•

The discussion of the APL operand of the
CP TERMINAL command is updated.

The CMS ZAP service program is enhanced so
that it can now modify or dump TXTLIB and
MODULE files in addition to LOADLIB files.
"Figure 13. CMS Command Summary" is updated
to reflect this support.
This service
program is intended for use by system
support personnel only.

NEW SUBSYSTEM SUPPORTED AS VM/370 COMPONENT
!~!:

The
Remote
Spooling
Communications
Subsystem (RSCS)
is nov supported as a
VM/370 component.
RSCS transmits spool
files across a teleprocessing network to
and from remote stations.
Re.ote stations
supported include HASP- and ASP-type batch
processors and work stations.
The new
component is a control program designed to
run in a virtual machine dedicated to
remote spooling.
The following changes
reflect this support:
•

The Preface is updated.

•

"Section 1: Introduction
Concepts" is updated.

•

"Figure 34. Com.ands Accepted fro. Each
Privilege Class" is updated.

•

"Figure 35.
updated.

•

The CP CHANGE, DEFINE, DETACH, ORDER,
SET,
SPOOL,
and
TRANSFER
com.and
descriptions are updated.

READING DOS FILES FROM DOS DISKS
!~!:

Programming Feature

Using OS macros, CMS can now read DOS files
that reside on DOS disks.
No DOS macros
are simulated. The following changes to
this manual reflect this support:

Component

Command

and

General

summary"

•

A new CP command, TAG, is described.

•

control
"Figure 36.
Co.mands to
Terminal Session" is updated.

•

"Figure
43. Co •• ands
Control" is updated.

•

"Appenidx
C: Using
Facility" is updated.

CMS

Batch

The CMS

•

Additional information about entering
the continuation character in column 72
is included in "Section 5: Writing and
Executing a Sample Program using CMS."

•

"Section 6: Virtual
A new section,
Machine Operation" is added to Part 1 •

Spooling

for
the

CMS is included in "Section 4:
File System."

"Part 2: Reference Information"
following changes:

has

the

ENHANCEMENT FOR THE VIRTUAL MACHINE
!~!:

Program feature

Programs using block multiplexer channel
operations (for example, DOS/VS, VS1, and
VS2)
can now
be
executed in
block
multiplexer mode on the virtual machine.
This virtual machine option may increase
the throughput of the virtual machine's
operating system because it allows the
overlap of SIOs to virtual devices without
encountering the channel busy condition.
The following changes to this publication
reflect this support:
•

"Figure 34. Com.ands Accepted from Each
Privilege Class" is updated.

•

The CP DEFINE and QUERY commands have a
new operand, CHANNELS.

•

The "Notational Conventions"
expanded.

•

"Figure
13.
CMS
Command
contains editorial changes.

•

The following CMS command
are clarified:

Documentation Only

Numerous minor editorial changes have been
made; these are too numerous to mention.
However, a list of the major editorial
changes and all miscellaneous technical
changes follows.
"Part 1:
Usage Information"
has many
editorial changes.
In addition, several
sections about the operation of virtual
machines and CMS, which were in the !~LllQ:
f!~nn!ng ~nQ
~I2~~! Q~n~!~!!g~ Q~!Q~, are
now included in Part 1:
•

Additional
information
about
the
terminal mode of operation, attention
interrupts, and the CMS command search
order is included in "Section 2: The
VM/370 CP and CMS Command Languages."

•

Additional information about accessing
CMS disks is added to "Section 3: CMS
Virtual Disks and How to Use Them."

•

Additional information about compiling
programs under CMS and tape handling in

summary"

descriptions

-ACCESS
-ASSEMBLE
-COMPARE
-COPYFILE
-DDR control statements
-EDIT
-ERASE
-EXEC
-FILEDEF
-FORMAT
-GENDIRT
-GENMOD
-GLOEAL
(Two new
options, DUP and
-INCLUDE
NODUP, are described)
-LISTFILE
-LOAD (Two new options, DUP and NODUP,
are described)
-PRINT
-PUNCH
-QUERY
-READCARD
-RELEASE
-RENAME
-RUN
-SET
-START
-STATE
-SVCTRACE
-SYNONYM
-TAPE
-TAPPDS
-TXTLIB
-TYPE
-UPDATE

MISCELLANEOUS
£h~ng~~:

section is

•

"Figure 17. Summary of EDIT Subcommands
and Macros" contains editorial changes.

•

Two previously undocumented immediate
commands RO and SO are now included. SO
temporarily suspends the recording of
trace
information and
RO
restarts
tracing that was suspended via the SO
command.

•

"Figure
33.
CP
privilege
Descriptions" is updated.

•

"Figure 34. Commands Accepted from Each
Privilege Class" is reformatted.

•

"Figure 35.
upda ted.

•

The following CP
are clarified:
-'CP
-CLOSE
-CP
-DEFINE
-DISCONN
-DISPLAY
-DUMP

Class

Command

summary"

command

descriptions

-EXTERNAL
-IPL
-LINK
-LOGOFF
-LOGON

-ftESSAGE
-QUERY
-SET
-TERftINAL
-TRACE
-TRANSFER

•

The RDTAPE and PRINTL macro descriptions
in "Appendix D: CftS ftacro Instructions"
are clarified.

•

"Figure 48.
updated.

Reserved

Filetypes"

Summary of Amendments
for GC20-1804-2
as updated by GN20-2640
VM/370 Release 2 PtC 4

CMS EDITOR LINE RENUMBERING FEATURE

•

"Figure 31.
CP Command Summary" in
"Section 7: Format and Usage Rules
for CP Commands" is updated.

A new CMS Editor subcommand recomputes
the line numbers of VSBASIC and FREE FORT
source files.
"Figure 13. Summary of
EDIT Subcommands" and the EDIT command
error messages in "Section 6:
Format
and Usage Rules for CMS Commands" were
changed to support this feature.

•

The DIAL, DISCONN, LOGON and LOGOFF
descriptions in "Section 7: Format
and Usage Rules for CP Commands" are
updated.

•

"Figure 38.
Commands
to control
VM/370" in "Appendix A:
Functions of
VM/370 Commands" is updated.

IBM 3704/3705 COMMUNICATIONS CONTROLLERS
NETWORK
CONTROL
PROGRAM
(NCP)
AND
PARTITIONED EMULATION PROGRAM (PEP) SUPPORT

•

"Figure 43.
Disk Determination" in
"Appendix
E:
Disk
Determination
(Filemode Management)" is updated.

•

"Figure 44.
Reserved Filetypes" in
"Appendix
F:
Reserved
Filetype
Descriptions" is updated.

!~!:

Program Feature

VM/370 now support all three
3704/3705 control programs:
•
•
•

the

Emulation Program (EP)
Network Control program (NCP)
Partitioned Emulation Program (PEP)

The following
support
•

changes

reflect

MISCELLANEOUS
fh~~~~g:

Documentation Only

this

•

The Preface is updated to remove the
statement limiting support of the
3704/3705.

The running foot for section 7 is
corrected on the TNL pages to read
"Section 7:
Format and Usage Rules
for CP Commands"

•

The Index is corrected.

"Figure 9. eMS Com.and Summary~ in
"Section 6: Format and Usage Rules
for CMS Commands" is updated.

Su •• ary of Amendments
for GC20-1804-2
'M/370 Release 2 PLC 1

!~!:

new options MEMBER and CONCAT.
Also,
6250 bpi tapes are now supported by
FILEDEF.

Documentation Change

Part
of the publication has been
changed
to include
information
on
general concepts for 'M/370 users, on
the ep and eMS command languages, on the
CMS disk system, and on the CMS file
system.
Also, there
is an example
program for use as an introduction to
the interactive processing capabilities
of 'M/370.

GLOBAL COMMAND
Updated to support use
FILEDEF CONCAT option.

the

new

MO'EFILE COMMAND
Updated to include support for accessing
OS data sets.
QUERY COftftAND

£hg~g~g:

Documentation expanded

Editorial
throughout
usage.

changes
have
the publication

been
made
to clarify

Updated to inclUde support for querying
the status of OS disks accessed by CMS.
SET COftftAND

]~~:

Documentation Change

In section 6, "Format and Usage Rules
for CMS Commands", the error messages
and return codes have been included in
the command descriptions.

Updated to
conditions
terminal.

include support
for
use with

for setting
a display

STATE COMftAND

Ch~~~~~:

Updated to include support for verifying
the existence of an OS disk accessed by
CMS.

Documentation Expanded

SYNONYM COMMAND

TAPE COftftAND

Updated to charify use of the command.

Updated to include support
tapes.

Ch~~~~~:

for 6250 bpi

Program Feature
UPDATE COMMAND

ACCESS COtlMAND
Updated to clarify
Read/Only disk.

its

use

with

Updated to allow flexibility in format
specification of auxiliary files.

DDR COMMAND
!~!:

Updated to support 9-track 6250
tapes and 3330 Model 11 disks.

Program Feature

bpi

EDIT COMMAND
Updated to support new subcommands for
graphic display devices.

ASSEMBLE COMMAND
Updated to reflect the new options for
the assembler and to clarify use of the
command.
LISTDS COMMAND

FILEDEF COMMAND
Updated to reflect
new support for
dynamic entry of a data set name and for

Added to the system: Lists information
about data sets on OS disks accessed by
CMS.

£h~~g~g:

Program Feature

DEFINE COM"AND
~h~lig~~:

Documentation Expanded

(asterisk) COMMAND

Updated to clarify its use.

DISPLAY CO"MAND
ADSTOP COMMAliD
Updated
virtual
ADSTOP.

to clarify use
machine assist

Updated to include support for the GRAF
operand. GRAF allows you to define a
teaporary
graphic device
for
your
virtual aachine.

of the VM/370
feature with

Updated to allow you to specify a range
of registers or storage.
DUMP COftMAND

CHANGE COMMAND

Updated to allow you to specify a range
of registers or storage.

Updated to clarify use.

MESSAGE COMMAND

CLOSE COMMAND

Name of the MSG command has been changed
to "ESSAGE.

Updated to clarify use.
QUERY COMMAND
DISCONN COMMAND
Updated to clarify use.
IPL COMMAND

Updated to
support GRAF,
and PFnn
operands. These new operands allow you
to query the status of console spool
files, display terminals, and program
function keys, respectively.

Updated to clarify use.
SET COMMAND
LOGOFF COMMAND

Updated to clarify use.

Updated to include
support for the
ASSIST and PFnn options. ASSIST invokes
the virtual machine assist feature; PFnn
allows
you
to
define
functions
associated with program function keys on
a graphic display terminal.

REWIND COMMAND

SPOOL COMftAND

Updated to clarify use.

Updated to support the * (asterisk)
character
option.
* specifies a
universal spooling class which allows
your virtual reader to read all classes
of spool files.

Updated to clarify use.
LOGON COMMAND

SET COMMAND
Updated to clarify use.
SLEEP COMMAND

Also, the CLOSE, FOR,
are supported.

and PURGE options

Updated to clarify use.
TERMINAL COMMAND
TRACE COMMAND
Updated to clarify use.

Updated to clarify use.
Also, updated
to reflect support for the MODE operand,
which allows you to set the mode of your
terminal to either CP mode (Control
Program) or VM (virtual machine).
TRANSFER COM"AND
Updated to support
the FROft userid
operand, which allows you to reclaim a
file that you spooled to another user.

!g!: Program Feature

CP COMMAND

'CP COft!UND

Added to allow entry of
"CP" while processing in
environment.

Added to allow you to enter CP commands
from a
virtual machine
environment
without issuing an interrupt.
ATTN COftftAND
Added to allow an attention interrupt to
be entered at the keyboard.

the characters
the CP command

REQUEST COMftAND
Added to allow you to enter an attention
interrupt at the keyboard of you virtual
console.

Contents

PART 1: USAGE INFORMATION ••

• ••

SECTION 1: INTRODUCTION AND GENERAL
CONCEPTS. • • • • • • • • • • • • •
VM/370 Control Program (CP), the
Conversational Monitor System (CMS),
and the Remote Spooling Communications
Subsystem CRSCS). • • • • • • • •
•
~n~ Virtual Machine. • • • • • •
The CP and CMS Command Languages • • •
SECTION 2: THE VM/370 CP AND CMS COMMAND
LANGUAGES. • • • • • •
•
VM/370 Command Environments.
•
How to Enter CP and CMS Commands •
•
The Command Name • • •
•
The Command Operands •
•
The Command Options. •
•
Comments in the CP and CMS Command
Languages • • • • • •
•
Character Set Usage. •
•
How to Write User-Defined Commands • • •
EXEC Commands. • • • • • • • • •
•
Commands Created by LOAD and GENMOD. •
Truncating and Abbreviating Commands ••
•
Synonyms for CMS Commands. •
CMS Command Search Order • •
•
Interrupting the Execution of a
Command
•
SECTION 3: CMS VIRTUAL DISKS AND HOW TO
USE THEM. • • • • • • •
•
Virtual Disk Identifiers and Addresses •
•
The A-Disk • • • • • • • • •
Disks B through G, Y, and Z.
•
The S-Disk • • • • • . •
•
Formatting Virtual Disks •
•
Virtual Disk Addresses and How They Are
Defined • • • • • • • • •
•
Permanent Virtual Disks.
• • • • •
Defining Temporary Virtual Disks • • •
Accessing and Releasing Virtual Disks. •
Linking to Another User's virtual Disk.
Extending One Virtual Disk from Another.
Virtual Disk Search Order • • • • • • • •
Read/Write Status of Virtual Disks: R/O
and R/W •
• • • • • • •
•
SECTION 4: THE CMS FILE SYSTEM • •
•
Creating or Defining Files • •
•
Naming Your Files: The File Identifier •
•
The Filename Field
•
The Filetype Field • • •
•
The Filemode Field • •
CMS Filetypes. • • • • •
•
Filetypes for Assembler and Compiler
Source Files. • • • • • • • • •
•
Object Files: Filetype TEXT. • • • • •
Files with the Filetype LISTING • • • •
Files with the Filetypes EXEC and
MODULE..
• •••••••••••

.9
11

11
11
13
15
15
16
16
16
17
17
17
18
18
19
19
20
20
22
27
27
27
27
28
28
28
28
29
29
29
30
30
30
33
33
33
33
34
34
35
36
36
36
36

File Groups Created by the Language
Processors • • • • • • • • • • • • • •
Using OS Programs and Macros under CMS •
Assembling a Program Usinq OS Macros •
Executing a Program that Uses OS
Macros • • • • • • • • • • •
Reading OS Data Sets from OS Disks and
DOS Files from DOS Disks. • • •
using Program Products under CMS •
How to Specify the Filemode Field ••
Specifying Search Order Using the
Filemode Field.
• • • •
• •
Libraries • • • • • • • • •
• •
CMS Tape Handling. • • • •
• •
CMS unit Record Support ••
• •
Card Reader. • •
• •

37
37
39
39
40
43
43
44
44
45
46
46

SECTION 5: WRITING AND EXECUTING A
SAMPLE PROGRAM USING eMS • • • •
47
Getting Started • • • • • • • • •
• 47
What You Should Know before You Can
Use CP and CMS • • • • • • • • • • • • 47
Contacting VM/370 and Logging On • • • 50
Loading CMS in the Virtual Machine:
The IPL Command. • • • • •
• 50.1
Using CMS to Create, Assemble, Load, and
Execute a Program • • • • • • • ••
52
How to Use the CMS Editor. • • • • • • 52
Creating Your Source Records: The
INPUT Subcommand. ••
• •••
53
Other EDIT Subcommands You Need •• • • 53
A Sample Program • • • • • • • • • • • 55
Creating and Executing Your Program. • • 56
Input for the Program • • • • • • • • • 57
Assembling Your Program • • • • • • • • 57
Loading and Executing the Program. • • 58
Logging Off. • • • • • • • • • ••
58
SECTION 6: VIRTUAL MACHINE OPERATION
Virtual System Console • • •
Attaching Devices. •
Tape Devices • • • • • •
Loading an Operating system into a
Virtual Machine • • • • • • • •
Spooling Virtual Console I/O • •
Reading Cards in a Virtual Machine •
Printing and Punching in a Virtual
Machine • • • • • • • • • • • • • •
Disconnecting the Terminal • • • • •
Using Multiple Consecutive Operating
Systems • • • • • • • • • • • •
Transferring output • • • • • •
Configurations • • • • • • • •
Execution Control. • • •

•• 59
59
59
• • 60

•
•
•
•

PART 2: REFERENCE INFORMATION ••
Notaticnal Conventions • • • • •

69
• • 69

60
61
62
• • 63
• • 64
•
•
•
•

65
65
67
68

SECTION 7: FORMAT AND USAGE RULES FOR
73
CMS COMMANDS • • • • •
CMS Command Summary.
• • 73
ACCESS • • • • • • •
• • 78

GC20-1804-3 Page Modified by TNL GN20-2659
ASSEMBLE
CMSBATCH
COMPARE.
COPYFILE •
CP
DDR.
DDR Control Statements
I/O Definition Statements.
DEBUG.
DISK •
EDIT
ERASE.
EXEC •
FILEDEF.
FORMAT
GENDIRT.
GENMOD •
GLOBAL
INCLUDE.
LISTDS
LISTFILE •
LOAD
LOAD MOD.
MACLIB •
MODMAP
MOVEFILE
PRINT.
PUNCH.
QUERY.
READCARD •
RELEASE.
RENAME
RUN.
SET.
SORT
START.
STATE.
SVCTRACE •
SYNONYM.
TAPE •
TAPPDS
TXT LIB
TYPE
UPDATE •
IMMEDIATE COMMANDS
HB •
HO
HT •
HX
RO •
RT •
SO •
SECTION 8: FeRMAT AND USAGE RULES FOR
CP COMMANDS
CP Command Privilege Classes •
CP Command Summary

*.
'CP.
ADSTCP •
ATTN
BEGIN.
CHANGE •
CLOSE.
COUPLE •
CP
DEFINE
DETACH

82
88
89
91
.103
.104
.104
.105
.114
.116
• 118
.125
.127
.132
.142
.145
• 146
.148
.150
• 155
• 157
.161
.169
.170
.175
.176
.179
.181
.184
.189
.192
.193
.195
.197
.200
.202
.203
.204
• 208
.212
.217
.220
.223
.225
.237
.237
.237
.238
.238
.239
.239
.240
.241
.241
.245
.249
.250
• 252
.254
.255
• 256
.258
.261
• 263
• 264
.267

.269
DIAL •
.271
DISCONN.
.272
DISPLAY.
DUMP
.277
.280
ECHO •
EXTERNAL
.281
.282
INDICATE •
.282.3
IPL.
.284
LINK
LOADVFCB
.287
LOGOFF
.288
LOGON.
.290
MESSAGE.
.292
NOTREADY
.293
ORDER.
.294
PURGE.
.295
QUERY.
.296
The QUERY Command for Class G Users.
.297
QUERY Command for All Classes of Users
(Except Class Any) •
.306
READY.
.308
REQUEST.
.309
RESET.
.310
REWIND
.311
SET.
.312
SLEEP.
.317
SPOOL.
.318
STORE.
.324
SYSTEM •
.327
TAG.
.328
TERMINAL •
.331
TRACE.
.334
TRANSFER •
.338
APPENDIXES

.339

APPENDIX A: FUNCTIONS OF VM/370
COMMANDS •

.341

APPENDIX B: DEBUGGING A PROBLEM PROGRAM
WITH VM/370
.351
How To Start Debugging
.351
Does A Problem Exist?
.351
Identifying The Problem.
.351
Analyzing The Problem.
.352
How To Use VM/370 Facilities To Debug •• 352
Problem Program ABEND.
.353
Unexpected Results in a Problem
Program
.353
Problem Program Disabled Loop.
.353
Problem Program Enabled Loop.
.354
Problem Program Disabled wait.
.354
Problem Program Enabled Wait.
.355
Comparison Of CP And CMS Facilities For
Debugging.
.356
APPENDIX C: USING THE CMS BATCH
FACILITY.
Using The Batch Facility Virtual
Machine •
Input To The Batch Facility Virtual
Machine
Batch Facility Output •

.358
.360

APPENDIX D: CMS MACRO INSTRUCTIONS •
COMPSWT Macro •
FSCB Macro
FSCLOSE Macro.

.363
.365
.366
.367

.357
.357

GC20-1804-3 Page Modified by TNL GN20-2659
FSERASE Macro • • •
FSOPEN Macro •
FSREAD Macro • • • • •
FSSTATE Macro.
FSWRITE Macro.
HNDEXT Macro •
HNDINT Macro •
HNDSVC Macro •
LINEDIT Macro.
PRINTL Macro •

.368
.369
.370
~

372

.373
.375
.376
.377
.378
.390

PUNCHC Macro

•

RDCARD Macro •
RDTAPE Macro •
RDTERM Macro •

.393
.394
.396

")0')

...J~L

REGEQU Macro •
TAPECTL Macro • •
WAITD Macro.
WAITT MacrQ~
WRTAPE Macro •
WRTERM Macro •

•
•
•
·
•
•

.397
.398
.400
.401
.402
.404

APPENDIX E: DISK DETERMINATION
(Filemode Management) • • • • • • • • .405

APPENDIX F: RESERVED FILETYPE
DESCRIPTIONS. •
INDEX.

• • • • • •

• .407
• .413

Figures

Figure

Figure
Figure

5.
6.

Figure
Figure

7.
8.

Figure 9.
Figure 10.
Figure 11.
Figure 12.
Figure 13.
Figure 14.
Figure 15.

Figure 16.
Figure 17.
Figure 18.
Figure

19~

Figure 20.

Character sets and Their
Contents ••••••••••••••••••••• 18
How CMS Searches for the
Command to Execute •••••••••• 21
Effects of Attention
Interrupt While Virtual
Console Is Set to the VM
Terminal Mode •••••••••••••••• 24
Effects of Attention
Interrupt While Virtual
Console Is Set to the CP
Terminal Mode •••••••••••••••• 25
CP and CMS Disk Access ••••••• 31
Determining Pilemode
Numbers •••••••••••••••••••••• 35
OS Macros simulated by CMS ••• 38
CMS Commands Used in
processing Data Sets on OS
Disks and Files on DOS Disks.40
Logical Editing Symbols •••••• 48
Loading an OS/MFT virtual
Machine •••••••••••••••••••••• 61
OS Job Stream Transfer ••••••• 66
Directory Entry for
Alternating Operating
Systems •••••••••••••••••••••• 67
CMS Command Summary •••••••••• 73
COPY FILE Option
Incompatibilities ••••••••••• 99
An Annotated Sample of
Output from the TYPE and
PRINT Functions of the tDR
Program ••••••••••••••••••••• 111
Summary of DEBUG
Subcommands ••••••••••••••••• 115
Summary of EDIT Subcommands
and Macros •••••••••••••••••• 120
Summary of EXEC Control
Statements •••••••••••••••••• 128
summary of EXEC Built-in
Functions ••••••••••••••••••• 130
Valid File Characteristics
for Each Device Type for the
FILEDEF Command ••••••••••••• 134

Figure 21.
Figure
Figure
Figure
Figure
Figure
Figure
Figure

22.
23.
24.
25.
26.
27.
28.

Figure 29.
Figure 30.
Figure 31.
Figure 32.
Figure 33.
Figure 34.
Figure 35.
Figure 36.
Figure 37.
Figure 38.
Figure 39.
Figure 40.
Figure 41.
Figure 42.
Figure 43.
Figure 44.
Figure 45.
Figure 46.

Resolution of Unresolved
References •••••••••••••••••• 152
SLC statement Format •••••••• 164
LDT Statement Format •••••••• 165
ICS Statement Format •••••••• 165
REP Statement Format •••••••• 166
ENTRY Statement Format •••••• 166
LIBRARY Statement Format •••• 167
Default Device Attributes
for MOVEFILE Command •••••••• 177
Header Card Format •••••••••• 182
Format of the READ Control
Card •••••••••••••••••••••••• 191
Summary of SVC Trace Output
Lines ••••••••••••••••••••••• 207
System and User Truncations.211
CP Privilege Class
Descriptions •••••••••••••••• 242
Commands Accepted from Each
User Class •••••••••••••••••• 243
CP Command Summary •••••••••• 245
Commands to Control a
Terminal Session •••••••••••• 341
Commands to Develop Programs
and Process Data •••••••••••• 342
Commands to Test and Debug a
Program ••••••••••••••••••••• 343
Commands to Update Data
Files ••••••••••••••••••••••• 344
Commands to Control Disks ••• 345
Commands for Virtual Machine
Control ••••••••••••••••••••• 346
Commands to Control VM/370 •• 348
Commands fer Spooling
Control ••••••••••••••••••••• 349
Commands for System and
Hardware Analysis ••••••••••• 350
Comparison of CP and CMS
Facilities for Debugging •••• 356
A Sample Listing of a
Program that Uses CMS
Macros •••••••••••••••••••••• 364

Figure 47.
Figure 48.

Disk Determination •••••••••• 405
Reserved Filetypes •••••••••• 407

Part 1: Usage Information

This part of the publication contains rules and information to help you
use all of the facilities of VM/370. It contains six sections.
"Section 1: Introduction and General Concepts" is a summary of
general concepts you should be faailiar with when you are using VM/370.
"Section 2: The VM/370 CP and CMS Command Languages" describes the
command environments, the general structure of the command
language, and how you can use the features of the VM/370 command
languages to aid you in solving programming problems.
V~/370

"Section 3: CMS virtual Disks and Bow to use Them" describes the
virtual disk system for your virtual machine and how to use it.
"Section 4: The CMS Pile system" describes the file as it is used in
the CMS system. This section gives you information on how to create and
name a file, how these files are used in the system, and how CMS handles
OS data sets and DOS files.
"Section 5: Writing and Executing a Sample Program Using CMS" is an
introduction to the Vft/370 interactive programming environment. In this
introductory section, you are given a program that you can enter at your
terminal as you read the book. Together with the information in the four
preceding sections, this sample p~ogram should provide you with the
basic information you need to use your virtual machine and its
interactive capabilities.
additional
"Section
6:
virtual ftachine
Operation"
contains
information
information about
operating virtual
machines.
This
generally applies to non-CftS virtual machines and includes an exaaple of
alternately executing CMS and another operating system in the same
virtual machine.

Part 1: Usage Information

Section I: Introduction and General Concepts

This section is a summary
when vou are usinq VM/370.
which-describe how to use
system.

of general concepts that are useful to you
It is a proloque to the followinq sections,
virtual disks, -and how to use the CMS file

virtual Machine Pacility/370 (VM/370)
is a system control program
that controls "virtual machines." A virtual machine is the functional
equivalent of a real machine, but where the real machine has lights to
show status, and buttons and switches on the real system console to
control it, the virtual machine has a virtual system console to display
status and a command language to start operations and control them. The
virtual system console is your terminal; there are three command
languages, the CP, CMS, and RSCS Command Languages. using your terminal
(as a virtual console)
and the command languages, you have many of the
capabilities of the operator of a real machine.

VM/370 Control Program (CP), the Conversational Monitor System (CMS),
and the Remote Spooling Communications Subsystem (RSCS)
VM/370
has three
components:
the
Control Program
(CP),
the
Conversational
Monitor System
(CMS) ,
and
the Remote
spooling
Communications Subsystem (RSCS).
CP controls the resources of the real
machine; that is, the physical machine in your computer room. CMS is the
conversational operating system designed specifically to run under CP.
RSCS is a SUbsystem designed to supervise transmission of files across a
teleprocessing network controlled by CP. This section describes CP and
CMS; for information about RSCS, see the !~LJ1~: ~~!g!~ ~Egg!!~g
~Q!!YBi£~!igB§ ~Y~§~§l~!

(~~~~)

Q§~~~§ gy!g~.

THE VIRTUAL MACHINE
The virtual machine is a software counterpart of a real machine. Its
control program can be any of those supported by VM/370. These are
listed in the !~LJ1Q: !B!~ggY£!!QB.
The virtual machine components are the virtual system console (your
terminal), a virtual CPU, virtual storage, and virtual channels and
input/output (I/O) devices.
Your virtual machine is a logical extension of the real computer. The
virtual machines are defined in the VM/370 directory, which is a list of
all the virtual machines logically extended from the real machine. Each
entry in the VM/370 directory lists the configuration of a virtual
machine.

A virtual disk is a logical subdivision of a real disk. Por practical
purposes, it is the same as a real disk on a real machine. Virtual disks
Section 1: Introduction and General Concepts

GC20-1804-3 Page Modified by TNL GN20-2659

have their own device addresses and cylinder numbers.
Each CMS virtual
disk has a Master File Directory that lists each of the files contained
on it.
The size of your virtual disks is defined in the VM/370 directory
entry for your virtual machine.
The virtual disk can be equal to or
less than the size of the real disk.
For CMS, the maximum size of a
virtual disk is less than the real disk and varies with the device type.
If you need more space, your system programmer can give it to you by
redefining the number of cylinders, by defining more disks in your
VM/370 directory entry; or you can assign temporary disk (T-disk) space
for your virtual machine.
with CMS, you can have up to ten virtual
disks logically attached to your virtual machine. These ten disks are
called the A, B, C, D, E, F, G, S, Y, and Z disks and are described in
more detail in section 3.

The file is the essential data unit in the VM/370 system. Programs,
program input, procedures, and any other type of data unit you want to
use on the system, are files in the VM/370 system.
In CMS, a file is a logically related group of records that you
create.
Using the EDIT command, you can create and modify a file
yourself in the CMS command environment; using FILEDEF, you can define
os data sets and DOS files as files for use under CMS.

On a real machine, spooling is, in general, the process of transmitting
a unit record file from the CPU' to a peripheral device for processing or
from a device to the CPU for processing. When the file is sent to the
peripheral device, the CPU is free for aore work.
The concept of spooling also applies to virtual unit record I/O
devices. You process virtual unit record files in your virtual machine
and, while they are processing, transmit them to your virtual printer or
to your virtual punch. Your virtual machine is then available for more
work. This collection of data directed to your virtual printer or punch
is called a spool file.
The output spool file can be transmitted to its
counterpart on the real machine, to your own reader, or to the reader of
another virtual machine.
Thus, the spool file is waiting to be
processed by a real device or another virtual machine.
VM/370 expands the concept of spooling to include the creation of a
spooled console log which is a record of all of your virtual console
input/output, including CP commands and responses. This console spool
file can be sent to the real printer when you want a copy of it.
The Remote Spooling Communications subsystem (RSCS) lets you transmit
files across a teleprocessing network to geographically remote locations
via the CP TAG and SPOOL commands. For details on how the network is
structured and operated, see the !~Ll1Q: ~~~Q!~ §EQQ!!ng £Q!~Yn!£g!!Qn2
§~B2~2!~!

(]~~~)

Q2~~~2 g~!g~.

IBM VM/370: Command Language Guide for General Users

THE CP AND CftS COftftAND LANGUAGES
You control your virtual aachine using the CP and CftS co.aand languages.
Any virtual machine can use the CP coamand language; you can use the CftS
command language only if your virtual =achine operating sfstea is ens.

The CP co.mand language gives you control of the devices attached to
your virtual machine. ftany of the functions of a real coaputer console
are simulated via the CP coaaand language.
Also, there are coa.ands
that provide spooling and disk-sharing capabilities.
CP comaands fall into one or aore privilege classes; this pUblication
provides information on only those coa.ands that can be used by the
general user (class G) or any user (class any). General users are those
users who program, test, and execute applications on a virtual aachine.
The CP command privilege classes available to your virtual aachine are
defined in your Vft/370 directory entry.
Using CP commands, you can send messages to the Vft/370 systea
operator and other users, modify the configuration of your virtual
aachine, and use the virtual machine input/output devices. CP coaaands
are available to all virtual machines under Vft/370. You can invoke these
commands when you are in the virtual machine environaent using CftS (or
some other operating system) in your virtual machine.

The CftS command language allows you to create, modify, debug,
general, manipulate a system of files.

and, in

ftany language processors can be executed under CftS: the assembler, VS
BASIC, as PORTRAI IV, as COBOL, and OS PL/I Optimizing and Checkout
Coapilers. You can find a coaplete list of language processors that can
be executed under CftS in the !AL170: In!I2gycti2!. CftS executes the
assembler and the coapilers when you invoke thea with CftS coaaands. The
ASSEftBLE comaand is described in this aanual; the supported coapiler
commands
are
described
in
the
appropriate
program
Product
documentation.
The CftS EDIT co •• and allows you to create and aodify files; the IIIC
com.and helps you to create a procedure consisting of CP and CftS
commands, which has the conditional execution capability of a aacro
language; the DEBUG com.and gives
you several program debugging
subcom.ands.
Other CftS coaaands allow you to read cards froa a virtual card
reader, punch cards to a virtual card punch, and print records on a
virtual printer. ftany commands are provided to help you aanipulate your
virtual disks and files.
since you can invoke CP coa.ands froa within the CftS virtual machine
environment, the CP and CftS co •• and languages are, for practical
purposes, a single, integrated com.and language for CftS users.

Section 1: Introduction and General Concepts

Section 2: The VMi370 CP and CMS Command Languages

Th1S section describes the V8/370 command environments, ~ne general
structure of the CP and CMS command languages, the user-defined
commands, command abbreviations, truncations, synonyms, and the command
search order.

The VM/370 system is comprised of the Control Program (CP)
and the
Conversational ~onitor system
(CMS). CP controls the real machine. You
can use CP commands to manipulate your virtual machine. CMS is an
interactive system designed specifically for use with CP for problem
solving and program development. CMS gives you a file system and the
commands required to manipulate files, and the virtual disks on which
they reside.
There are two types of
VM/370 commands:
system commands and
user-defined commands. The system commands are those defined by the CP
and CMS command languages. User-defined CMS commands are those you
create yourself using the EXEC command or the LOAD and GEHMOD commands.
User-defined CP commands are also allowed; your installation system
programmer must create them. The procedure is described in the VM/370:
~~§tem R~gg~~~~~~ g~!g~.

Depending on the way you are using the system, you may want to be in
a specific command environment. A command environment is the environment
of your virtual machine as defined by the command language subset you
are using. If you are using the CP command language, you are in the CP
command environment; if you are using CMS or another operating system,
you are in the virtual machine command environment.
Many commands can also have abbreviations and minimum truncations, as
defined by the system, and can have synonyms, which you define.
since there are many types of com.ands, VM/370 provides a set of
conventions for searching through the system for a given command. For
example, you may have defined your own command with the same name as a
CMS -system com.and, therefore, you must know which command actually
executes. The rules governing the search for the correct command are
contained in this section.

VM/370 Command Environments
There are two basic command environments: the CP command environment and
the virtual machine command environment.
The CP command environment is reached when you log on to VM/370 and
issue CP commands. Depending on the task you want to perform on your
virtual machine, you may want to switch in and out of this environment.
The means for entering and exiting from this environment are described
in "Interrupting the Execution of a Command" in this section.
You can find out which command environment you are in by entering a
null line (that is, pressing the Enter key, or equivalent, with no
data). VM/370 responds to a null line by displaying the current command
environment.
section 2: The VM/370 CP and CMS Command Languages

The virtual machine command environment is the environment you reach
when you load your virtual machine with the CMS operating system or
another operating system.
When you load CMS in your virtual machine, you can use both the CP
and CBS co.mand languages.
The CftS command environment has three
subcommand environments that are entered by means of the EDIT, EXEC, and
DEBUG commands.
The EDIT co.mand places your virtual machine in the EDIT subcom.and
environment, where you can use the CftS Editor to create and modify
files. In the EDIT subcommand environment, you can place your virtual
machine in either of two modes, the EDIT mode or the IIPUT mode. BDIT
mode lets you modify a file; INPUT mode lets you create or add to a
file.
The EXEC subcommand environment is entered via the EXEC command. In
this environment, you execute procedures that contain combinations of CP
and CftS commands to perform the functions you specify. These procedures
are usually created in the EDIT environment.
The DEBUG command places your virtual machine in the DEBUG subco •• and
environment, in which you can issue co •• ands to display registers and
storage, specify breakpoints (address instruction stops), display the
contents of control words, and so on.

How to Enter CP and CMS Commands

A V"/370 command consists of a command name, usually followed by one or
more positional operands and, in some cases, by an option list. The
general form for the command line is:
[operand ••• ] [(option ••• [) ]]

You must use one or more blanks
line unless otherwise indicated.

to separate each entry

in the command

THB COftftAND IAftE
The command name is an alphameric symbol of not more than eight
characters. In general, the names are verbs which describe the function
you want the system to perfor.. Por example, you may want to find out
whether a certain user is logged on the Vft/310 system. In this case,
you would use the CP QUBRY command.

THE COftftAND OPERANDS
The command operands are keywords and positional operands of no more
than eight alphameric characters each.
The operands specify the
information on wbich the system operates when it performs the command
function. Por the QUBRY command, for example, you could use the USER or
userid operand to find out whether the user is on the system.
16

IBft Vft/370: Co •• and Language Guide for General Users

Some commands require no operands; others require several. You can
find each class G, class Any, and CftS command with all of its operand
requirements in Part 2 of this publication.
You must write the operands in the order in which they appear in the
co.mand formats in Part 2, unless otherwise specified.- When you are
using CftS, blanks should be used to separate the last operand and the
option list.

tHE COftftliD OPTIONS

The command options are keywords used to control the execution of the
co.mand. The command formats in Part 2 show all the options for each
command.
The option list must be preceded by a left
parenthesis is not necessary.

parenthesis; the closing

If conflicting or duplicate options are entered, the last entered is
the option in effect for the command. Exceptions to this rule are the
CftS COPYPILE, PILEDEP, ERASE, and PORftAT commands.
See the individual
descriptions of these co.mands in Part 2 for more information.

COftftENTS IN THE CP AND CftS COftftAND LANGUAGES
You can write comments with CP commands of the following types:
•

Commands with no operands

•

Commands with a fixed number of operands

•

Commands

~ith

a single optional operand

You cannot write
of

comments with commands that have
than

a variable number

If you want to write comments with CftS commands, you enter them
following the closing parenthesis of the option list.
The only
exception to this rule is the ERASE command, for which com.ents are not
allowed.
You can enter comments on your console by using the CP

command.

CHARACTER SET USAGE
CP and CftS commands may be entered using a combination
from six different character sets. The contents of
character sets is described in Pigure 1.

of characters
each of the

section 2: The 'ft/370 CP and CftS Command Languages

Ba.es
I Character Set I
I
Blank
I Separator
I
Dollar Sign
I lIational
Pound Sign
I
At Sign
~
Alphabetic

•

Upper Case
Lower Case

a - z

lIumeric

lIu.eric

Alphameric

lIational
Alphabetic

$, "

lIu.eric
Special
Figure

Symbols

9
it

All other
characters

Character Sets and Their Contents

How to Write User-Defined Commands

You can update existing commands and create your own commands using the
CBS EXEC command and the LOAD and GEIMOD commands.

EIEC COBBAIDS
The BXBC command allows you to create an BXBC procedure that has the
effect of a command and which can be invoked by its filename, just as a
invoked. BXBC procedures
can contain CP,
CftS, and
command is
user-defined commands and provide a convenient way of generating a
predefined sequence of commands. You are implicitly specifying the BXBC
command when you issue the filename of the EIEC procedure.
There is one case when you must specify the EXBC com.and and its
associated filename explicitly: when an EXEC is nested within another
EIBC, the nested BXEC must be specified explicitly.
Certain EIEC control statements
let you conditionally execute
statements within the procedure. You conditionally execute statements by
means of the SIF, SLOOP, and
SGOTO statements, similar to the
conditional and looping facilities found in high level languages.
You can find all the information you need to write
the !!L11Q: 111~ Use~~§ Guid!.

EIEC com.ands in

A special type of BXEC procedure called a PROPILB BIBC can be used to
set up a predetermined operating environment within CftS each time you
use your virtual machine. If you have a PROPILE BIEC it is executed
before the first command after you IPL CBS. It defines the conditions
you want while you are programming under CBS. For example, if you are an
assembler language programmer, you need the CBS, TEIT, and OS macro
libraries accessed while you are processing. In your PROFILE EIBC, then,
you could issue a GLOBAL command to access these libraries automatically
whenever you IPL the CftS operating system.
18

IBft V8/310: Command Language Guide for General Users

CO~~ARDS

CREATED BY LOAD ARD GERftOD

You can use the LOAD and GBR~OD commands to create program modules. I
.odule is a relocatable file whose external references have been
resolved; that is, a module is a file that you can execute by invoking
its filename.
The module filename is, effectively, a CftS co.aand you
define for your own use.
A source prograa aust be assembled or compiled to produce an object
file that has a filetype of TEXT. The LOAD coa.and loads the object
file into virtual storage in your virtual machine. When LOAD executes,
all external references for the file are resolved. You then use GIIIOD
to create an absolute core-image of the file or files loaded in storage.
Its filetype is always ftODULE. This core-image copy may then be used as
a CftS command by invoking its filename.
If you are creating a module containing aore than one TEXT file, you
include the additional TEXT files with the IRCLUDE command, then issue
the GEBftOD.
Truncating and Abbreviating Commands

To make the entering of commands on the keyboard more convenient, CP and
CftS allow .any com.ands (as well as many operands and options) to be
used in a shortened form.
The shortened form can be either an
abbreviation or a truncation to its minimum form. ~iniau. truncations
are shown within the foraat box and abbreviations are shown with the
description that follows the foraat box for all the com.and foraats in
Part 2.
In those foraats, the minimum truncation is shown in uppercase
letters in the coa.and foraat box; the optional letters are shown in
lowercase. This rule holds for options and operands as well. I good
example of com.and truncation is the EDIT command. The format shows the
co •• and bame as "Edit". This means you can enter the IDIT co •• and in
any of the following forms:
EDIT
ED
E

I is the .ini.u.
for the command.

truncation, but CftS accepts all of

the above for.s

Abbreviations
are shorter
for.s
of
coamands and
operands.
Abbreviations for co.mands are shown below the full name of the coaaaDd
in the format box. Abbreviations for operands and options are shown in
the description of the individual operands and options that follow the
foraat box.
lor exa.ple, the operand RIADER has both a .1n1au.
truncation and an abbreviation. In the foraat box, it is shown as:
Reader
indicating the .1n1.U. truncation is R.
operand that follows, it is shown as:

In the discussion of the reader

READER
RDR
indicating that the abbreviation is RDR.
section 2: The Vft/370 CP and CftS Co •• and Languages

Synonyms lor CMS Commands
Using the EDIT com.and, you can create a table of synonyms for both C8S
commands and co.mands you define yourself.
You create the file using
the EDIT command in the form
EDIT filenaae SYNONY8
(the filetype must be SYIOIY8).
in the table, in the for.

You then enter the records that will be

commandname synonymname count
where "commandname" is the name of the command for which you are
creating a synony., "synonyaname" is the name of the synonym for the
command name, and "count" is the number of characters you want to use as
a minimum truncation value for the synonym.
In order to use the synonym table once you have created it and filed
it in your systea, you must invoke the SYNONY8 command at the beginning
of every terminal session in which you want to use the table.
You can find a more detailed explanation
command in section 7.

of how to use

the SYNONY8

CMS Command Search Order
You can create a user-defined comaand (that is, a aodule or EXEC
procedure) which executes in your virtual machine and resides on disk.
To execute such a co.mand or EXEC procedure, you only have to enter the
filename from the terminal.
However, be aware of the C8S search order
for terminal input.
Once a match is found, the search stops.
The
search order is:
1.

EXEC file on any currently accessed
an EXEC file.)

disk.

(The C8S RUN co.mand is

Valid abbreviation or truncation for an
accessed disk.

Nucleus resident or transient area command.
(The nucleus resident
C8S commands are: CP, DEBUG, ERASE, GEN80D, INCLUDE, LOAD, LOAD!OD,
START, and STATE. The transient commands are: ACCESS, CO!PARE,
DISK, PILEDEP, GENDIRT, GLOBAL, LISTPILE, !OD8AP, PRIIT, PUICH,
QUERY, READCARD, RELEASE, RENA!E, SET, SVC~RACE, SYIOIY8, TAPE, and
TYPE. )

Command module on any currently accessed disk.
(All the reaaining
C8S commands are disk resident and execute in the user area.)

Valid abbreviation or truncation
area command module.

Valid abbreviation or truncation for disk resident co.aand.

EXEC file on any currently

for nucleus-resident or transient

Por example, if you create an EXEC file with the same name as a disk
resident co.mand, the C8S search always finds the EXEC file first.
Thus, the disk resident command is never executed.
Figure 2 shows more details of the coa.and search order; you can find
complete description of the search order in the V8/370: ~ystem
~l'oqra.!!!!r' s ~uid!.
a

IB! V!/370: Command Language Guide for General Users

(

KEY IN A
COMMA!'JD NAME

EXECUTE
YES

THE F!LE
AND RETURN
CONTROL TO
CMS.

I I
CMS
EXEC
SEARCH

YES

EXPAND THE
NAME TO THE
FULL REAL
NAME, EXECUTE
IT, AND RETURN
CONTROL TO CMS.

EXECUTE THE
FILE AND
RETURN CONTROL
TO CMS.

CMS
MODULE
SEARCH

YES

CP
SEARCH

EXPAND THE
NAME TO THE FULL
REAL NAME, EXECUTE
IT, AND RETURN
CONTROL TO CMS.

EXECUTE THE
COMMAND
AND RETURN
CONTROL TO
CMS.

ISSUE
AN ERROR
MESSAGE

I Figure

Bow CftS Searches for the Command to Execute
section 2: The VM/370 CP and CMS Co •• and Languages

IITEBBUPTIIG THE EXECUTION OF A COaaAND
You can suspend the execution of a coaaand in your virtual machine using
the Attention key (or its equivalent) on your terainal keyboard.
Functionally, the Attention key requests
the Control Program to
interrupt the coaaand currently executing, thus allowing you to key in
new input. The interrupt takes effect iamediately in aost cases, but
soae coaaands coaplete execution before the interrupt takes effect.
The name and physical location of the Attention key varies with
different styles of terainals supported by VB/370.
See the VB/370:
I~!!!~~! y§~!!§ §ui~! for details on various styles of terainals.

Using the Attention key, you can switch coamand environaents (that is,
switch from the CP to the VB co.aand environment or vice versa), at the
saae tiae you request an interrupt. What happens when you press the
Attention key depends on two factors: the comaand environaent of your
virtual aachine and the aode setting of your virtual console.
Your virtual machine can be in one of two coamand environments: the
CP command environaent (CP) or the virtual Bachine comaand environment
(Va). These environments are defined by usage. When you IPL an operating
systea for your virtual machine, your virtual aachine is in the VB
environment, otherwise, it is in the CP environment.
You set the mode of your virtual console using the CP TEBBINAL
command. The ~ODE operand of this cosmand allows you to set your virtual
console in either the CP or va mode.
These modes correspond, in
general, to the preceding cosmand environments description. Each of the
terminals that can be used with the Va/370 system has a key that is the
equivalent of the Attention key on the 2741 (with which you signal an
attention interrupt). Unless otherwise noted, where the tera "Attention
key" is used in this publication, the phrase "(or equivalent)" is
implied. The equivalent key on the 1050 terminal is the BESET LIIE key;
on the 3270 terainal, the Enter key.
On a 3270 terminal you can signal an attention interrupt to the
virtual machine with the ATTN or BEQUEST commands. Issuing the ATTI or
BEQUEST commands on a 3270 is equivalent to pressing the Attention key
once on a 2741. On a 3270 terminal, pressing the Enter key is equivalent
to pressing the Attention key twice quickly on a 2741.
Fo-r a 3215, you press the Attention key once to signal an attention
interrupt to the virtual machine, then enter the ICP command to get to
CP mode.
How CP interprets attention interrupts issued by the virtual machine
users depends on whether the terminal mode is set to CP or VB.
The default mode setting for the primary systea operator is:
TEBBINAL BODE CP
If your default ter.inal mode is CP, or if you issued the above
co.mand, pressing the Attention key one or more times forces your
virtual machine into CP mode.
22

IBB VB/370: Comaand Language Guide for General Users

For all other users, the default mode setting is:
TERftIIAL ftODE V"
If the terainal aode is Vft, pressing the Attention key once passes an
interrupt pending condition to the virtual machine operating system.
Pressing the Attention key twice quickly (or pressing the 3270's Enter
key) places your virtual machine in CP mode.
If you execute CftS from a 3270 device, you must issue the ATTI or
REQUBST command if you are in CP mode and want to return to the virtual
aachine mode.
The following two figures show the effect of an Attention interrupt
when your virtual console is in either Vft or CP aode.
Pigure 3 shows
the action taken by V"/370 when your virtual console is in V" mode and
you press the Attention key. The first coluan represents the condition
of the terminal keyboard when you press the Attention key. The second
coluan represents the number of tiaes you press the Attention key. If
your virtual console is in the Vft mode, one Attention requests an
interrupt and two quick Attentions force your virtual machine to the CP
co.mand environment. The third coluan represents the action Vft/370
takes depending on the number of times you press the Attention key.
"any" means that the effect of the Attention key is the same no matter
how many tiaes you press it.
If the operator sets his terminal mode to V" and resets his
virtual machine, his console acts as described in the first state of
Pigure 3 (that is, more than one attention is required to unlock the
keyboard for CP input).

!Q1~:

section 2: The Vft/370 CP and CftS Com.and Languages

state of Terainal before
Attention Key Pressed
Terminal idle; keyboard
locked; virtual aachine
running

I 10.1
I of I

IATTNI

1 IAttention interrupt pending; virtual

I
)1

Terminal receiving output
from virtual machine

Resulting
Action
aachine running

IKeyboard unlocked for CP input

1 IAttention interrupt pending; virtual

aachine running

)1 IKeyboard unlocked for CP input at

I
Keyboard unlocked for inputl 1
to virtual machine; no
I
data entered or all data
deleted
I )1
I

completion of console I/O

IDevice end (DE) and attention status
I pending; virtual machine runningl

1-------------------------------------------IUnit exception (UB)status pending;
I

virtual aachine running

Keyboard unlocked for input I 1 IUnit exception (UB) status pending:
to virtual machine; soae I
I virtual aachine running
data entered
I )1 IDevice end (DE) status pending;
I keyboard unlocked for CP input
I

1--------------------------------------------

Keyboard locked; executing lany IAttention ignored
CP command
I
Keyboard locked; in SLBBP lany IKeyboard unlocked for CP input
mode entered via co •• and I
I
Keyboard locked; in SLEEP lany IVirtual machine resumes execution
mode entered via Diagnose I
I
instruction
I
I
Terminal receiving output I 1 IAttention interrupt pending; virtual
from CP but not from userl
I machine running
command
I )1 IKeyboard unlocked for CP input

1--------------------------------------------

Terminal rece1v1ng output lany 10utput line canceled and in soae
in response to CP co •• andl
I cases coamand output canceled
Keyboard unlocked for CP
lany IAttention interrupt made pending;
input; no data entered orl
virtual aachine running
all data canceled
I
Keyboard unlocked for CP
lany IInput line canceled; keyboard
input; soae data entered I
I unlocked for CP input
ITo perform this function on a 3270, position the cursor one position
to the left of the user input area (line 22, position 0) and press
the Enter key.
Figure

3. Effects of Attention Interrupt While Virtual Console
to the V! Terminal Bode

IB! V8/370: Co.mand Language Guide for General Users

Is Set

Figure 4 shows the action taken by VM/370 when your virtual console
is in CP mode. If your virtual console is in CP mode and you press the
Attention key one or more times, you force the virtual machine to the CP
command environment.

state of Terminal before
Attention key Pressed

Resulting
Action

Terminal idle; keyboard locked; IKeyboard unlocked for CP input
virtual machine running
I
Terminal receiving output from
virtual machine

IKeyboard unlocked for CP input
I

Keyboard unlocked for input to
to virtual machine; no data
entered or all data deleted

IUnit exception CUE) status pending;
keyboard unlocked for CP input

Keyboard unlocked for input to
virtual machine; some data
entered

IDevice end CDE) status pending;
I keyboard unlocked for CP input
I

Keyboard locked; executing CP
command

Keyboard locked; in SLEEP mode
entered via co.mand

IKeyboard unlocked for CP input
I

Keyboard locked; in SLEEP mode
entered via Diagnose
instruction

I
I

Terminal receiving output from
CP but not froa user com.and

Terminal receiving output in
response to CP co •• and

IOutput line canceled and in some
cases command output canceled

IAttention ignored

IVirtual machine resumes execution

IKeyboard unlocked for CP input

Keyboard unlocked for CP input; IAttention interrupt made pending;
no data entered or all data
virtual machine running
canceled
Keyboard unlocked for CP input; IInput line canceled; keyboard
some data entered
unlocked for CP input
Figure

4. Effects of Attention Interrupt While Virtual Console
to the CP Terminal Bode

Is set

Section 2: The VM/370 CP and CMS Command Languages

Section 3: eMS Virtual Disks and How To Use Them

This section describes your virtual disk system and how you use it. It
describes how the disks are naaed, how they are accessed, when they need
to be formatted, how to access and release thea and, in general, how to
Ilanipula te them.
Your virtual machine can have many disks defined for it in the Vft/370
directory, but it can have at most ten virtual disks logically accessed
at any time. Virtual disks are logical subdivisions of real disks; but
they can be considered real disks. Each has its own virtual device
address, virtual cylinders, and for CftS disks, a ftaster File Directory,
which lists the files contained on the disk.
You can request the operator to attach an entire real disk to your
virtual aachine. This real disk, once attached, is considered a virtual
disk.
When your virtual aachine is defined, the system programmer estimates
your disk storage requireaents and allocates cylinders for your virtual
disks accordingly.

Virtual Disle Identifiers and Addresses

Virtual disks have disk identifiers and virtual addresses. The virtual
disk identifier (or fileaode letter) is a single-letter specificatio~ of
A, B, C, D, I, P, G, S, Y, or Z. The disk identifier is a part of the
filemode specification used in the CftS command line.
The virtual disk
address is a three-character hexadeciaal nuaber.
The address can be
assigned permanently in the Vft/370 directory or temporarily via the CP
DBPIIB command.

THE A-DISK
The A-disk is the priaary user disk. It is a read/write disk which is
accessed when you begin your CftS terllinal session. You can create,
store, and aodify files using this disk. Usually, the address of the
A-disk is 191.

DISKS B THROUGH G, Y, AID Z
You aay have several disks defined in your Vft/370 directory entry.
During a terminal session you may want to make these disks a part of
your active virtual machine. In this case, you use the ACCESS coamand to
acquire a disk and give it a naae. The identifiers B through G, Y and Z
are used to identify these disks.
If you have a virtual 192 disk defined for your virtual aachine in
the Vft/370 directory, or if you specifically define a virtual disk with
address 192 before loading CftS, that disk is accessed as your D-disk at
the time your A-disk is accessed.

Section 3: CftS Virtual Disks and How to Use Thea

THE S-DISK
The S-disk is the system disk and is read-only. It contains the CftS
nucleus and disk-resident co •• and aodules. The Y and Z disks can be
eItensions of the syste. disk, depending on your virtual aachine
configuration. If you have 190 and 19E disks defined in your Vft/370
directory entry, these are accessed as the S and I disks after you IPL
CftS.

Formatting Virtual Disks

Before you USe your virtual disks, you must ensure that they have been
formatted. Each disk must be formatted the first time you use it; it
need not be formatted thereafter.
Use the CftS PORftAT co •• and to format a virtual disk the first time
you use it. However, the FORftAT command erases the contents of the disk,
so you should take care not to issue FORftAT for a disk whose contents
you want to save.
Each tiae you use the CP DEPINE comaand to attach a teaporary virtual
disk to your virtual machine, you must issue the FORftAT co •• and.
If you are formatting a disk to contain as or DOS files, use the
IBCDASDI virtual disk initialization program, which is described in the
!.a/37.Q: ~.E!!~g!2~2

Guig!!.

Virtual Disk Addresses and How They Are Defined

Iou can have both permanent and temporary disks attached to your machine
during a terainal session. Permanent disks are predefined in the Vft/370
directory entry for your virtual machine. Temporary disks are those you
define for your own virtual aachine using the CP DEFIlE coaaand.

PBRftAIBIT VIRTUAL DISKS
The Vft/370 directory entry for your virtual machine defines the
permanent virtual disks. Bach disk has associated with it an access mode
specifying whether you can read or write on the disk or only read froa
it. The virtual disk entries in the V8/370 directory aay typically look
like the following:
ftDISK
ftDISK
ftDISK

197
198
194

2314
3330
3330

000
010
050

050
005
005

CftS190
CftS001
CftS192

R
W
W

The first two fields describe the device, virtual disk in this
example, and the virtual address of the device. The third field
specifies the device type of your virtual disk. The fourth and fifth
fields specify the starting real cylinder at which your virtual disk
logically begins and the nuaber of cylinders allocated to your virtual
disk, respectively. The siIth field is the label of the real disk on
28

IBft Vft/370: Coaaand Language Guide for General Users

which the virtual disk is defined and the seventh field is a letter
specifying the read/write aode of the disk. The ftDISK control state.ent
of the Directory Service Program is described in the Vft/370: Operator's
Guide.
Even though these devices are per.anently attached to your virtual
aachine, you .ust access thea using the CftS ACCESS co •• and before you
can use the ••

DilljljG TifiPOiAiY VIiTUAL DISKS

Using the CP DEPIIE co •• and, you can attach a teaporary disk to your
virtual aachine for the duration of a terainal session. Once attached,
the disk .ust be accessed using the CftS ACCESS co •• and. Por exa.ple, the
co ••ands below allow you to use a temporary G-disk.
define t3330 as 291 cyl 10
You should then foraat it using the CftS POiftAT co •• and:
for.at 291 9
You should respond to the

eftS

response .essages.

Accessing and Releasing Virtual Disks

Even though virtual disks may be defined in the Yft/370 directory entry
for your virtual aachine, you cannot use thea until you access thea.
There may be .any disks defined in that entry, but your CftS virtual
aachine .ay have access to only ten of the. at a ti.e. The CftS ACCESS
co •• and allows you to logically access a virtual disk for your CftS
virtual .achine.
Since you can have only ten virtual disks active in your CftS machine
at a tiae, you Bay want to release a disk so that you can access
another. You use the CftS BELEASE coaaand to logically release the
virtual disk fro. your CftS virtual aachine, then access the new disk
using the ACCESS co.aand.

Linking to Another User's Virtual Disk

Yft/370 lets you link to a virtual disk owned by another user. Use the CP
LII! co •• and as shown in the example below:
link to bensid 193 as 194 r pass= go
This co •• and links another user's vixtual disk (whose address is 193) to
your virtual aachine, where it has the address 194. The B specifies that
the disk can only be read and GO is the read password.
BEISID is the
use rid for the virtual .achine to which you are linking.
You .ay also have another user's
directory entry.

virtual disk defined in your Yft/370

Once you have linked a disk to your virtual
ACCESS command to access it and give it a na.e.

aachine, use

the CftS

Section 3: CftS Virtual Disks and Bow to Use Thea

Extending One Virtual Disk from Another
Using the CMS ACCESS command w you can make one virtual disk a read-only
extension of another so that when you specify that a disk is to be read w
any extension to that disk is read also. For exallple w the co •• and:
access 192 d/a
lIakes the D-disk an extension of the A-disk.
When one virtual disk is an extension of another w the extension disk
isw by definition w a read-only disk. However w you can respecify its
access status by issuing the ACCESS again, this time not extending the
D-disk from the A-disk.
access 192 d
Not only does extending one disk from another alter its access status w
it may also affect the search order for the disk accessed on your
systell.

When you issue a CftS com.and and specify
as the filemode, the
extensions set via the ACCESS cOII.and are not in effect, that is, the
search is in alphabetical order.
Only one level of disk extension is permitted.

Virtual Disk Search Order
When you specify a file to be acted upon in a CMS cOllmand w the default
(or standard)
CftS search for that file is in alphabetical order; the
A-disk first w B second, and so on.
The standard search order is used
when no mode letter is specified or implied.
If a mode letter is
specified or implied, the search order is first the given disk and then
all the disks that are read-only extensions of the given disk (except
for certain co •• ands, such as LISTFILE and TAPE DUftP, which purposely
ignore read-only extensions) •

Read/Write Status of Virtual Disks: R/O and R/W
The read/write status for a virtual disk defines whether you can read or
read and write on a disk on your virtual machine. You can access disks
in two ways: read-only, where files on that disk can only be read; and
read/write, where files can be read and written.
To access a disk, you must:
1.

Identify a disk as part of your virtual machine configuration. If
the disk appears in your Vft/370 directory entry it is already a
part of your virtual .achine configuration. Also, you can .ake a
disk part of your configuration by issuing a CP LII! or DEFIlE
command.

Identify the disk to CftS and assign it a file directory name. You
issue the ACCESS comlland after you load CftS to do this.
The CftS
ACCESS co •• and associates a particular disk with a given file
directory name and, optionally, specifies which files on the disk
are to be used and specifies the disk as read-only.

IBft Vft/370: Com.and Language Guide for General Users

The following example shows how you add a temporary disk
disk to your CftS virtual machine.

and a user

ipl cms
link dept637 230 197 r 12601
define t3330 as 192 cyl 5
format 192 d
access 197 b
lirst the LIIK command adds a device at virtual address 197 to your
virtual machine. (The disk added is defined in the V8/370 directory for
a virtual machine with a userid of DEPT637 as device address 230 with a
read password of 12601.)
Then the DElIIE command adds temporary disk space (from a CP pool of
such space) to your virtual machine at address 192.
The CftS lORftAT
the CftS format.

command initializes the temporary disk

area (192) in

The ACCESS command activates the disk at virtu?l address 197 (similar
to VARY OILIIE in OS) and assigns the disk the file directory name B.
The importance of the directory name was explained in the preceding
section "Virtual Disk Search Order"
If ACCBSS is not the first command entered after CftS is loaded, an
automatic ACCESS is performed to access a disk at device address 191 as
the A-disk.
Both CP and CftS can
illustrated in ligure 5.

control read/write

access

disks, as

CftS ACCESS
CP

ACCBSS

Read-only
Read/Write

Readonly

I Read/
I write

I Bead-only I Bead-only
I Bead-only I Read/irite

ligure 5. CP and CftS Disk Access

Access allowed by CP is determined by the Vft/370 directory entry or
the form of LIIK issued by a virtual machine operator for a particular
disk.
The read/write status
ways:

of virtual disks can be

controlled in several

•

It can be specified explicitly in the Vft/370 directory.

•

It can be specified by the CP DElIIE com.and.

•

A disk can be made read-only by extending it from another disk.

If the read/write status is defined in the Vft/370 directory, it is
either a read/write (B/i) or read-only (R/O) disk. R/i disks can be read
from and written on; R/O disks only may be read.
Section 3: CftS Virtual Disks and Bow to Use Them

When you define
always a R/i disk.

a teaporary

disk at

your terainal,

that disk

The read/write status of a particular disk affects the way you use
it. R/O disks cannot be written on. For example, you cannot use a R/O
disk to contain the output of a language processor.
You can find the read/write
coaaand with the DISK option.

status of a

file by issuing

IBM VM/370: Co.aand Language Guide for General Users

the QUERY

Section 4: The eMS File System

The file is the essential unit of data in the CMS system. A CMS file is
a logically grouped unit of data you define via a CMS command. This
section gives you information on how you can create a file and name it,
how files are used in the system, and how CMS handles as data sets and
DOS files.

Creating or Defining Files

You can create a file using the CMS Editor, which is invoked with the
CMS EDIT command. The Editor lets you create and modify a file on your
virtual disk. The FILEDEF command defines data sets created under an as
system such as OS/VS1 or OS/VS2 so that they can be recognized by CMS.
You use as macros to perform I/O operations for these data sets.
The files
(or data sets) defined by PILEDEP can be as data sets
created by an as system, DOS files created by a DOS system, or files
created under eMS using os macros simulated by eMS and residing on a eMS
virtual disk.
You can then access them under CMS just as you do files
you create using the Editor. Files may also be introduced to the system
by means of the READCARD, DISK, and TAPE commands.
All the information you need to create a CMS file using the Editor
can be found in the !AL11Q: ~~IT ~~!de.
The FILEDEF command is
described later in this section and in section 7.
In order to create a file, you must define a name for the file and
decide upon the filetype of the file; use of the file determines its
filetype. This information is entered along with the command in the form
of a file identifier.
Appendix F lists the reserved filetypes and
describes the use of each.
For a description of how to load existing source card decks into your
virtual machine, see the CMS READCARD command description.

Naming Your Files: The File Identifier

When you create a file in CMS, you name it using a file identifier. The
file identifier consists of three fields: the filename
(fn), the
filetype (ft), and the file.ode (fm). This file identifier is then used
to refer to the file while you are using CMS.

THE FILENAME FIELD
The filename for a file is a one- to eight-character alphameric symbol.
The characters can be A through Z, a through z, 0 through 9, and the
special characters $, I, or i. You should be careful when using the 1
and i
characters, since they are used also as VM/370 logical editing
characters.

Section 4: The eMS File System

You can use any filenaae you wish: however, you should avoid
duplicating naaes or abbreviations for CP or CftS systea coaaands. If
you duplicate the name of a system command and invoke the naae from CftS,
the execution of that file depends on the CftS coamand search order,
which is described in section 2 under "CftS Coaaand Search Order."
Pilenames, in some cases, becoae user-defined command naaes.
filenaaes for files with the filetype ftODULE or EXEC have the
effect as a command, in aany cases.

The
saae

TH! fILETYPE fIELD
The filetype is also a one- to eight-character alphameric symbol. The
characters can be A through Z, a through z, 0 through 9,·and the special
characters $, I, or i. You can find more infor.ation about the filetype
specification in the sections that follow.
Certain filetypes have special meaning to CftS, that is, CftS assumes
the file has specific characteristics such as record length, tab
settings, truncation column, upper or lowercase, and other information
of significance for use by a coamand. These special filetypes are
described in a later section "CftS Piletypes" and are summarized in
Appendix F.

THE PILEftODE FIELD
The filemode field has two characters: the filemode letter and the
filemode nuaber. The file80de letter is established by the ACCESS
co.aand, and specifies the virtual disk on which a file resides: A
through G, S, Y, or Z. The file_ode nu.ber can be a number from 0-5.
Figure 6 shows what each file_ode number means. The first coluan is the
filemode number, the second coluan specifies the read/write status
associated with the number,
and the third column gives a brief
description of how to use the file.ode number.

IBft Vft/370: Command Language Guide for General Users

Filellode
Number

Read/Write
Status

Meaning

R/W

The file specified is a private fi19! vou
cannot access a file with the 0 fii~~ode
unless you have read/write privileges for
the virtual disk on which the file resides.

R/W

You can read froll and write into this file,
depending on how the disk is accessed.

R/W

You can read from and write into this file,
depending on how the disk is accessed.
Certain files on the S-disk are mode 2;
you can access these files. You can also
use mode 2 to describe files on disks
other than the system disk.

R/E

The file is to be erased after it is read.
Usually, this filellode is used for
temporary work files created by the
language processors and sOlie CMS commands.

This file is created using OS macros. It
may be blocked and, if in as variable
format, may contain Block Descriptor Words
(BDWs) and Record Descriptor Words (ROWs).

R/W

Has the same meaning as filemode 1.

Reserved for IBM use.

6-9

Figure

Determining Filellode Numbers

The other information you need when using this field of the file
identifier is found later in this section, "How to Specify the Filemode
Field."

eMS Filetypes

The filetype field specifies the type of the file; that is, how the file
functions in the CMS system.
The filetype field is used by the EDIT
command to define standards for record length, tab settings, upper or
lowercase, truncation column, and so on.
For other cOllmands, the
filetype field is used to identify a subset of all files that are
appropriate for processing by that command, for example you may want to
process all files with the filetype ASSEMBLE.
Source files have a filetype describing the language in which the
file is written; files containing relocatable object code have the
filetype TEXT; files containing executable object code have the filetype
MODULE; files containing listings have the filetype LISTING, and so on.
The filetypes described in this section are reserved; that is, they
have a special meaning to CMS when you specify them in the filetype
field of the file identifier. They are most useful in the programming
environment (for example, filetypes describing source files, EXEC, TEXT,
MODULE, and LISTING files).
There is also a description of files
created during certain types of processing under CMS.
Section 4: The CMS File System

FILETYPES FOR ASSEMBLER AND COMPILER SOURCE FILES
When you create a source file using the Editor you assign a filetype
that describes the source language used to create the file. For example,
when you create an assembler language file using the CMS Editor, the
command you issue might be:
edit myfile assemble
where MYFILE is the filename of the file and ASSEMBLE is its filetype.
When you specify the filetype as ASSEMBLE, you are telling the Editor
that the file is an asse.bler language file, and that the records
created should be appropriate for processing by the system assembler.
The Editor uses the filetype ASSEMBLE to define suitable conditions for
creation of an assembler language source file.
That is, the Editor
creates a file consisting of fixed-length, SO-character records, with
all input translated to uppercase, and with standard tab settings of 1,
10, 16, 31, 36, and so on.
See "Appendix P. Reserved Piletype Descriptions" for a list of the
filetypes associated with the other supported programming languages and
the CMS commands. When you create source files, there are rules
concerning usage of the file, the command you use to process the file
under CMS, the record format of the file and the contents of the file.

OBJECT PILES: PILETYPE TEXT
When you execute one of the language processors, the results of the
processing (asse.bled or compiled object code) are placed in a file with
the same filename as the source file for the program, but with a
filetype of TEXT.
PILES WITH THE PILETYPE LISTIIG
Also, when you execute the language processors, a listing describing the
source code and the results of execution is contained in a file with the
same filename as the source file and filetype LISTING.

PILES WITH THE PILETYPES EXEC AND MODULE
There are two types of files that can be executed by invoking the
filename of the file.
These two types of files are files that have
either the filetype EXEC or the file type MODULE.
An EXEC file may be a procedure (a sequence of predefined commands to
be executed as a unit). EXEC procedures also provide you with a
conditional execution capability similar to the looping facilities of
high level languages. You can find information about how to write and
use EXEC procedures in the !AL11~: IXE~ ~~~~~ §~!~~.
In CMS, a MODULE file is a non-relocatable copy of a program or
routine that resides in storage in executable form.
A MODULE file is
created by loading an object file
(filetype TEXT)
in your virtual
machine (via the LOAD co.mand) and then generating the module via the
GEIMOD command. Like the EXEC file, the MODULE file can be executed by
invoking its filena.e.
36

IBM VM/370: Command Language Guide for General Users

FILE GROUPS CREATED BY THE LANGUAGE PROCESSORS
ftany CftS commands create groupings of files, each related to the other
by the same filename. Some of these files are permanent and some are
temporary. For example, if you issue the co.mand
assemble Ilyfile
the system assembler executes to assemble the file nailed ftYFILE.
Execution of the assembler generates several files, some per_anent and
some teaporary.
You can request eMS to list the permanent files by
means of the LISTPILE command:
listfile myfile

CftS then generates a list of all files with the filename of ftIPILE,
including the permanent files created during the execution of the
assembler, which might look like this:
ftIFILE ASSEftBLE Al
Al
ftIPILE TEXT
ftYFILE LISTING A1
where the TEXT file contains the object code resulting frail the
assembly, and the LISTING file contains the program listing generated by
the assembly.
The source input file, ftI!ILE ASSEftBLE Al, is not
erased.
Temporary
workfiles:

files

are

also

created by

the

assembler

for

use

ftIPILE SISUTl
ftYFILE SISUT2
ftIPILE SISUT3
The filetypes of the workfiles Ilay vary depending on the processor
you are using. Disk space 1S allocated for the assembler work areas on
an as-needed basis. They are erased when processing is complete.
Iou should ensure that a file created durinq the execution of a
language processor does not have the same file identifier as one you
wish to save. CftS, when instructed by a language processor to write a
file, erases any file with the same file identifier as the one
specified.

Using OS Programs and Macros under eMS
Iou can assemble and execute programs under CftS that require the use of
OS macros simulated by Cfts. Figure 7 lists the OS macros that CftS
simulates.

Section 4: The CftS Pile System

SVC
Nu!12~!

Maf!:Q
XDAP
WAIT
POST
GETMAIN
FBEEMAIR
GETPOOL
FBEEPOOL
LINK
ICTL

01
02
04
05

LOAD
DELETE
GETMAIN/
FREEMAIN
TIME
ABEND
SPIE

11
13
14

BLDL/FIND

OPEN
CLOSE
STOW
OPENJ
TCLOSE
DEVTYPE

19
20
21
22
23
24

TBKBAL
WTO/WTOR
EXTRACT
IDENTIFY
ATTACH
CHAP
TTIMEB
STIMER
DEQ
SNAP
ERQ
FREEDBUF
STAE

25
35
40

57
60

DETACH
CBKPT
RDJFCB

62
63
64

SYBAD
BSP
GET/PUT
READ/WRITE
ROTE/POIRT
CHECK
TGET/TPUT
TCLEARQ
STAX
RETURB

68
69

Figure 7.

08
09
10

41
42
44
46

47
48
51
56

93
94
96

Function
Bead or-write direct access volumes
wait for an I/O completion
Post the I/O completion
Conditionally acquire user storage
Belease user-acquired storage
Simulate as SVC 10
Simulate as SVC 10
Link control to another phase
Delete, then link control to another
load phase
Read a phase into storage
Delete a loaded phase
Manipulate user free storage
Get the time of day
Terminate processing
Allow processing program to
handle program interrupts
Manipulate simulated partitioned
data files
Activate a data file
Deactivate a data file
Manipulate partitioned directories
Activate a data file
Temporarily deactivate a data file
Obtain device-type physical
cha racteristics
BOP
Com.unicate with the terminal
Effective BOP
Add entry to loader table
Effective LIBK
Effective BOP
Access or cancel timer
Set timer
Effective BOP
Dump specified areas of storage
Effective BOP
Release a free storage buffer
Allow processing program to
decipher ABEBD conditions
Effective BOP
Effective BOP
Obtain information from FILEDEF
com.and
Handle data set error conditions
Backup a record on a tape or disk
Access system-blocked data
Access systea-record data
Manage data set positioning
Verify READ/WRITE completion
Read or write a terminal line
Clear terminal input queue
create an attention exit block
Return from a linked or
attached routine

OS Macros Simulated by CMS

IBM VM/370: Command Language Guide for General Users

ASSEeBLING A PROGRAM USING OS MACROS
To assemble a program that uses OS macros, you must first issue a GLOBAL
command to make the macro library containing the macros available to the
assembler.
global maclib

osmacro

Once you have accessed the macro library, you can use macros from the
library to assemble a program like the one shown in the following
example:
TESTER

CSECT

OPEl

PUT

(OUTDCB, (OUTPUT»

OUTDCB,lREA

OUTDCB

DCB

DDNIME=OUT, •••

To assemble the example, issue the command:
assemble tester
After the file is assembled, you can load the resulting TEXT file and
then execute the program.

EXECUTING ! PROGRA! THAT USES OS
In order to execute a program that uses OS macros, you must associate
each DCB statement in your program with the device specified to perform
the input/output operation for it. As in OS, this association is made
via the ddname.
In CMS, however, you issue the PILEDEP com.and, which
performs a function for CMS that parallels the function performed by the
DD statement in OS.
Thus, to execute
commands:

the

preceding example

program,

you issue

these

filedef out disk tester output a1
load tester
start
When you use the OS macros simulated by CMS to read and write (as in
the example), you can write only to CMS disks. You cannot issue a write
to an OS or DOS disk. Also, CMS does not simulate all reads and writes;
only the OS BSAM, BPAM, OSAM, and BDAe access methods are simulated.
Piles written on a CMS disk can, in turn, be read by programs running
under CMS when those programs request that CMS simulate a read (for
instance a GET or READ macro).
Section 4: The

ces Pile System

READIIG as DATA SBTS PROB as DISKS AID DOS PILES !ROB DOS DISKS
sequential and partitioned data sets
residing on as disks, and
sequential files residing on DOS disks, can be read by prograas using as
aacros running under CBS. Also, certain CBS co.aands can be used to
process these data sets and files on as and DOS disks. Pigure 8 lists
coaaands you can use to aanipulate as data sets and DOS files under CBS,
and briefly describes the function of the coaaand in relation to its use
with as data sets and DOS files.

Operation
ACCESS

Bakes the as or DOS disk containing the as data set or DOS
file available in R/O status to your CBS virtual machine.

RELBASB

Releases the as or DOS disk you have accessed (via ACCESS)
froa your CBS virtual aachine.

LISTDS

Lists inforaation describing as data sets residing on an
as disk, or DOS files on a DOS disk.

STATB

Yerifies the existence of an as data set or DOS file on a
disk. Before STATE can verify the existence of the data
set or file, you aust have defined it (via PILEDBP).

PILEDBP

Defines the as data set or DOS file for use under CBS by
associating an as ddnaae with an as data set name or DOS
file-ide Once defined by PILEDEP, the as data set or DOS
file can be used by an as program running under CBS and
can be aanipulated by the other commands that support as
functions.

DDR

copies an entire as or DOS disk to tape.

GLOBAL

Bakes aacro libraries available to the asseabler. You can
prepare an as macro l{brary for reference by the GLOBAL
coaaand by issuing !ILEDE! for the data set and giving
the data set a filetype of BACLIB.
12~§:
If you are going to assemble, reaeaber that the
ddnaae to use on the PILEDEP co.aand aust be CBSLIB.

ASSBBBLB

Assembles an as data set or DOS file under CBS.

BOYBPILB

Boves data records from one device to another device. Each
device is specified by a ddnaae, which must have been
defined via PILBDBP.

QUBRY

Lists (1) the status of virtual machine features specified
by the CBS SBT coa.and, (2) the files that have been
defined via PILBDBP in your system of virtual disks, and
(3) the status of virtual disks attached to your virtual
.achine.

Pigure 8. CBS Co.aands Used in Processing Data Sets on as Disks and files
on DOS Disks

IBB YB/370: Coaaand Language Guide for General Users

The following restrictions apply when you read OS data sets under ens:
•

Read password-protected data sets are not read.

•

VSAM, BDAM, and ISA! data sets are not read.

•

Multivolume data
sets are read
as
single-volume
data sets.
End-of-volume is treated as end-of-file and there is no end-of-volume
switching.

•

Keys in data sets with keys are ignored; only the data is read.

•

User labels in user-labeled data sets are bypassed.

The following restrictions apply when you read DOS files under CMS:
I •

No DOS aacros are siaulated.

I.
I
I
I

Only DOS sequential files can be read. CMS operands and options that
do not apply to OS sequential data sets (such as the MEftBER and
COBCAT options of PIL!D!P and the PDS option of ftOVEPILE) also do not
apply to DOS sequential files.

The following types of DOS files cannot be read:
-DOS VSAft, DAft and ISAft files.
-DOS core
libraries.

image,

relocatable,

source

statement

and

procedure

-Piles with the input security indicator on.
-Files that contain more than 16 user label and/or data extents. (If
the file has user labels, they occupy the first extent; therefore
the file must contain no more than 15 data extents.)
I.
I

Multivolume files are read as single-volume files. End-of-volume is
treated as end-of-file. There is no end-of-volume switching.

User labels in user-labeled files are bypassed.

I •
I
I
I

Since DOS files do not contain BLKSIZE, RECPft, or LRECL options,
these options must be specified via the PILED!P command or the DCB
statement; otherwise, defaults of BLOCKSIZE=32760 and RECPft=U are
assigned. LB!CL is not used for RECPft=U files.

I.
I
I
I
I

If a DOS file-id does not follow as naaing conventions (that is, oneto eight-byte qualifiers with each qualifier separated by a period;
up to 44 characters including periods), you must use the DSN 1
operand of PILED!P and the 1 operand of LISTDS to enter the DOS
file-ide

Section 4: The CftS Pile System

The following examples show how to use the FILEDEF and MOVEFILE commands
to handle as data sets and DOS files under CMS.
The following sequence of CftS com.ands moves an as STOW macro file
from an as partitioned data set called SIS1.ftACLIB or a CMS file called
SIS1 MACLIB to the CMS file STOW MACRO.
access 195 b/a
filedef test1 disk sys1 maclib b1 (member stow)
filedef macro disk stow macro
movefile test1 macro
The following sequence of CftS commands moves all the members of an as
partitioned data set called SIS1.ftACLIB or a CftS file called SIS1 MACLIB
into separate CftS files, each with a filename equal to its member name
and a filetype of MACRO.
access 195 b
filedef test2 disk sys1 aaclib b1
filedef macro disk
movefile test2 macro (pds)
Either of the following sequences of CMS commands can be used to
verify the existence of the as data set called TEST.OS.SAftPLE.1 and
assemble it with SYS1.MACLIB on an as disk and CftSLIB on a CftS disk.
access 198 d
listds test os sample 1 *
filedef assemble d1 dsn test os sample 1
filedef cmslib disk sys1 maclib * (concat
global maclib sys1 cmslib
assemble file
-- or -access 198 d
filedef assemble disk test1 assemble d1 dsn ?
test.os.sample.1
state test1 assemble *
filedef cmslib disk cmslib maclib * (block 3360 lrecl 80 recfm fb concat)
filedef cmslib disk sys1 maclib * (concat)
global maclib cmslib sys1
assemble test1
The following sequence of CftS commands moves a DOS file named DAILY
ACCOUNT JAN 1 from the DOS 195 disk to the CMS file FILE OUT.
access 195 b
filedef in disk file in b1 dsn ?
DMSFLD220R ENTER DATA SET NAftE
daily account jan 1
movefile in out
(A default FILEDEF is issued for FILE OUT.)

IBft VM/370: Command Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659

USING PROGRAM PRODUCTS UNDER CMS
The CMS assembler and the Program Product language processors supported
by CMS (listed in the !~LllQ: !~!I2gY£!!2n) are as programs that require
definition via FILEDEF in order to perform input/output processing. For
input, all of these programs can use sequential or partitioned data sets
that reside on as disks, or sequential files that reside on DOS disks.
When a supported language processor is executed under CMS, CMS issues
FILEDEFs for the data sets or files it requires in order to execute the
program.
You can override these default definitions by issuing a
FILEDEF for those data sets or files before you invoke the language
processor. You must issue the FILEDEF for the data set or file each
time you want to use it, since the processors clear all file definitions
when they complete their processing.
When

compilers execute under CMS, they normally:

•

Run the compilation to completion.

•

Display any diagnostics at the terminal.

•

Generate a CMS disk file with the same filename as the source program
and a filetype of TEXT, which contains the object deck created by the
assembler or compiler.

•

Direct the printed output of the assembler or compiler to the spooled
printer or to a disk file with a filetype of LISTING.

The filename of files created by the assembler
under CMS is equal to that of the source file.

or compilers running

Disk work files required by the assembler or as compilers under CMS
are automatically created during compilation and erased at the end of
compilation.
No cataloging or erasing of data sets is required.
Object programs (TEXT files) produced under CMS and under OS in real
or virtual machines may be executed under CMS if they do not utilize
certain os functions not simulatea oy eMS.
(aS macro functions that are
simulated are discussed in "Using as Programs and Macros under CMS.")
Object programs
(except for the PL/I Checker) using non-simulated as
macro functions must be transferred to an appropriate real or virtual as
machine for execution.
PL/I Checker programs that use non-simulated as
macro functions must be both assembled and executed on the appropriate
real or virtual as machine.

How to Specify the Filemode Field

The filemode field of the file
identifier is comprised of two
characters: a virtual disk letter and a filemode number. In almost all
CMS commands, this field is optional. You need not specify it since CMS
itself has the ability to search for the file. Some commands, in fact,
do not permit a filemode entry.
There are four ways to specify this field of the file identifier:
•

Explicitly, by actually entering
number in the filemode field.

the filemode

•

Implicitly, by leaving the entire field blank.

letter and

filemode

Section 4: The CMS File System

GC20-1804-3 Page Modified by TNL GN20-2659

•

By specifying an asterisk (*) in the filemode field.

•

By specifying an equal sign

(=)

in the filemode field.

If you specify the filemode explicitly, the virtual disk you specify
and any extensions of it are searched for your file. If, however, the
virtual disk you specify is an extension, the extension disk is
searched, but not the parent disk. If you specify a read-only virtual
disk when you are writing a file, CMS returns an error message.
If you specify the filemode field implicitly by leaving it blank,
only your A disk and its extensions are searched for the file.
The asterisk (*) can have two meanings, depending on the command with
which it is specified: (1) search all disks until the specified file is
found, or (2) search all disks for all occurrences of the file.
The equal sign (=) as the filemode is specified when you want to read
from and write on the same virtual disk.
This character can be used
only on disks for which you have read/write privileges.
When you are using one of the Program Product language processors to
write to a virtual disk, CMS first attempts to write to the virtual disk
you specify and then attempts to write to that disk's parent (if one
exists). If there is no room on either of these disks, or if both disks
are read-only, writing is done only to the A-disk.

SPECIFYING SEARCH ORDER USING THE FILEMODE FIELD
A CMS function that is trying to locate
that file in either of two ways:

a file on a disk may search for

•

If it is searching for a file with a particular filemode,
"A", that disk and its immediate extensions are searched.

•

If it is to search all accessed disks
(Filemode *), the
searched in alphabetical order (A BCD E F G S Y Z).

such as
disks are

CMS functions or commands that do not allow you to specify the
filemode (such as LOAD, ASSEMBLE, and MACLIB) use the second type of
search, and search all accessed disks in alphabetical order.
Commands that allow you to specify the filemode may do either type of
search. If you specify a particular disk or allow it to default to "A",
then the first type of search is done. If you specify filemode as "*",
then the second type of search is done.
However, the LIST FILE and TAPE DUMP commands do not use extensions in
search of a particular disk.

Libraries
CMS provides two types of libraries: macro libraries and text, or
program libraries.
A library is a file with the filetype MACLIB or
TXTLIB. Unlike other CMS files, a library file consists of members plus
a dictionary for locating the members by name within the library file.

IBM VM/370: Command Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659

A macro library is a file whose filetype is MACLIB. It contains a
dictionary and members which are macro definitions. The system macro
libraries are CMSLIB MACLIB, OS MACRO MACLIB, OSMACR01 MACLIB and TSOMAC
MACLIB. CMSLIB MACLIB contains the eMS macros. OSMACRO MACLIB contains
selected OS macros from the OS macro library, SYS1.MACLIB, which are

Section 4: The CMS File System

44.1

simulated by CMS. OSMACR01 MACLIB contains the other macros from
SYS1.MACLIB, making it possible to assemble a program in CMS for os
execution. And, TSOMAC MACLIB contains selected TSO macros.
You can create your own macro library by using the MACLIB command.
Files with the filetype HACRO or COpy can be specified in the nlCLIB
command for inclusion in the library.
The MACLIB command can also be
used to add, delete, or replace macros in an existing library; to list
the name, size, and location of macros in a library; and to compress a
library.
A text library is a file whose filetype is TITLlE: It contains a
dictionary and members that are relocatable text files. The system text
library CMSLIB TIT LIB contains
extended precision floating point
simulation routines.
If you are a TSO user, you can also access the
TSOLIB TITLIB.
YOU can generate your own text library by using the TITLIB command.
Only files with the filetype TEIT may be included. A maximum of 1000
control section names and entry points can be contained in a TITLIB
file. The TITLIB command may also be used to add or delete members from
a library or to list the entry points, control section names, and the
location of members of the library.
CMS has no automatic library calls. A library must be made available
using the GLOBAL command before CMS will search it. GLOBAL has two
forms, the TITLIB form for specifying text libraries, and the MACLIB
form for specifying macro libraries. The command GLOBAL MAC LIB CMSLIB
OSMACRO would make CMSLIB MACLIB and OS MACRO MAC LIB available to be
searched during an assembly for macro operation codes, and they would be
searched in the order they were named in the GLOBAL command.
Text
libraries that are made available with the GLOBAL command are searched
for missing subroutines or undefined filenames whenever the LOAD or
INCLUDE commands are issued.
Up to eight libraries may be specified
with either form of GLOBAL.
The commands GLOBAL TITLIB and GLOBAL
MACL~B, specifying no
library names, terminate searching of previously
specified libraries.
Descriptions of
section 7.

the MACLIB,

TITLIB, and

GLOBAL commands

appear in

eMS Tape Handling

CMS has two commands that handle tapes.
The CMS TAPE command dumps CMS formatted files from disk to tape,
loads such files from tape to disk, and performs various control
operations on a specific tape, such as setting tape modes, forward or
backward spacing, and rewinding the tape.
The TAPE command is used
solely for CMS files. The files on tape are created in a unique format
that can be read only by the TAPE LOAD command.
The TAPPDS command reads tapes created by the OS utility programs
such as IEHMOVE, IEBUPDTE, and IEBPTPCH. If the tape contains an OS
partitioned data set (PDS) produced by the OS IEBPTPCH utility, the
TAPPDS command can
write the members as
individual CMS files.
Optionally, it produces CMS files from tape in the OS IBBUPDTB control
file format,
blocked or unblocked. TAPPDS can also create CMS files
from unloaded partitioned data sets in IEHMOVB format, blocked or
unblocked. The tape may be unlabeled or may have a standard OS label.

section 4: The CMS Pile System

lote: The 80VErILE
can-handle tapes.

and DDR commands, as well

as user-written programs,

eMS Unit Record Support
CftS supports one virtual card reader at virtual address OOC, one virtual
card punch at virtual address OOD, and one virtual printer at virtual
address OOE. Under V8/310, these devices are spooled. CftS does not
support real or dedicated unit record devices, nor does it support a
virtual 2520 Card Punch.

I CARD READER
The READCARD co •• and reads data records froa the spooled card reader to
a C8S disk. Input records of 151 or less characters are accepted.
Column binary data is not acceptable.
All user-generated card decks
.ust be read into the virtual reader before a BE1DCABD co •• and can be
issued. You can get card decks into a C8S reader in either of two ways:
•

1 card deck, containing only one file, is placed in a real card
reader and read by CP. The deck must be preceded by a V8/310
identification (ID) card specify~ng the userid of the virtual machine
to receive the card images.
(Files must be read in separately, even
if they are for the same virtual machine. If a second deck is placed
behind the first, the second ID is ignored and the second file is
treated as though it were part of the first file.
The only
end-of-file condition recognized is an end-of-file on the real
device.) The card i.ages are placed on a spool file in the specified
virtual machine's virtual card reader. If the specified user is not
logged on to the system, the deck re.ains in his virtual card reader
until he logs on and issues the BEADC1BD co •• and.

I.
I

One virtual machine transfers records from its virtual card punch or
printer to a virtual card reader (its own or that of another user).

IBft V8/310: Command Language Guide for General Users

Section 5: Writing and Executing a Sample Program Using eMS

Once you have read the preceding four sections, you can use the sample
program in this section as an introduction to the interactive facilities
of Yft/370. This section contains the information you need to create and
use a program that runs under the CftS operating system. The text is
organized so that you can enter the sample program at your terminal as
you read ..
The sample program treats a number
of Y8/370 commands in a
"one-situation" manner. That is, most of the commands cari be used in
ways other than that shown in the sample program.
The first part of this section describes the steps you take before
creating the program: learning to use your terminal, contacting the
computer, loading the CftS operating system and formatting a disk with
which to work.
The second part of this section deals with two topics: how to use the
CftS Editor to create a program and how to use Yft/370 commands to execute
it.
The program you write is a simple one, even though it is coded in
assembler language. It consists of only a few statements; all you need
to do is enter them.
When the program executes, you can use it
interactively, so you get an idea of how to use Y8/370 interactively.

Getting Started

Y8/370 is an operating system that
provides you with a unique
facility--your own machine. This machine is a virtual machine, that is,
a machine with software counterparts for almost all of the hardware
components of a real machine. All of these components are controlled
from your ter.inal, which is your virtual console.
On the real machine console, there are lights and keys that help you
manipulate. the .achine; on the virtual console (your terminal), you
manipulate the machine using the command languages of the CP and CftS
operating systems.
The CP command language lets you manipulate your virtual machine
components. For example, you could temporarily define a new device for
your virtual machine using the CP DEFIlE command.
The CftS command
language allows you to manipulate the virtual disks on your system and
the files contained in them. For example, you can create and assemble a
program file in asse.bler language using the CftS EDIT and ISSEftBLE
cO~lIands.

WHIT YOU SHOULD KIOW BEFORE YOU CAl USE CP liD CftS
Before you can use CP and C8S, you should know (1) how to operate your
terllinal and (2) your userid (user identification) and password.

section 5: Writing and Executing a Sa.ple Program Using CftS

There are many types of terminals you can use as a V8/370 virtual
console.
Before you can conveniently use any of the co •• ands and
facilities described in this section, you have to familiarize yourself
with the ter.inal you will be
using.
Generally, you can find
information about the type of terminal you are using and how to use it
with V8/370 in the !~Ll1Q: Ier~i~g! Us§!!§ ~Yide. If your ter.inal is a
3767, you also need the !~! 11~1 ~E§~g~Q~~§ Guide.
The sa.ple progra.
is designed for typewriter terminals.
Where parallel com.ands are
needed for display terminals, you can find these co.mands described in
the !~Ll1Q: I~!I ~Yi~~·

your userid is a symbol that identifies your virtual machine to V8/370
and allows you to access V8/370. Your password is a symbol that
functions as a protective device ensuring that only those authorized to
use your virtual machine can use it. Both symbols are usually defined
by the system programmer for your installation and you can obtain them
from him.
When you are familiar with your terminal and know your userid and
password, you are nearly ready to use V8/370.
But before you begin
using your terminal to enter commands, you should know how the V8/370
Logical Editing Characters can help you correct the typing mistakes you
may make at your terminal.

V8/370 has a set of symbols you can use to correct typing errors and to
change data as you enter lines at your keyboard. Using these logical
editing symbols, you can cancel a line entirely, change a character in a
line, logically end a line and begin a new one without pressing the
Enter Key (or equivalent) and ignore the special meaning of a character
on a line. Figure 9 lists the default logical editing symbols. To
change the symbols' use, you must either define different logical
editing symbols in your V8/370 directory entry or issue the CP TER8INAL
command.
r

I
I
I
I
I
I
I

Symbol
~

•

Figure 9.

Function
Logical
Logical
Logical
Logical

Character Delete
Line End
Line Delete
Escape

Logical Editing Symbols

When you enter your input lines using these symbols, you do not see
the effect they have immediately, since Vft/370 is simply accepting the
input you are entering.
You can see the effect the logical editing
symbols have when you request Vft/370 to show you your input file.

IB8 Vft/370: Command Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659

199i£!± ~h!f!£!~! ~~1~!~ ~y~~gl (~): Deletes the character preceding
it on the input line. A string of character delete symbols deletes a
corresponding number of preceding characters.
For example, if you make
a typing error such as:

I~~

permnaent
just enter five character delete symbols
correct letters, as follows:

and

them with

the

permnaentaaaaaanent
when you press the
VM/370

Enter Key on your terminal, the

line is accepted by

permanent
I~~

199!£~1 1!n~
~~1~!~ ~I!B£l
(~):
Causes your virtual machine
delete the logical line you are entering. Por example,

a formula of the highest affirmation ¢
causes the entire line to be ignored by VM/370. You can press the Enter
key to continue typing, or you can continue on the same input.

199!£!1 1!~~ End ~I!~21 (!): Causes your virtual machine to
logically end the lIne you are entering. This symbol allows you to
enter many logical lines on one physical line, for example,

I~~

a formulalof the highestlaffirmation
is accepted by VM/370 as
a formula
of the highest
affirmation

("): Tells your virtual machine to ignore the
special line-editing meaning of the character that follows. You use the
logical escape symbol to ignore the line-editing meaning of the special
characters that you do not want VM/370 to misinterpret. Por example,
VM/370 misinterprets the following line:

I~~ 12g!£~1 ]§£!£~ ~I!~21

gross .2 pencils a 92¢ per dozen
The special characters on this line are interpreted by VM/370 as:
•
•
•

Begin a new line after "gross"
Delete the blank space after "pencils"
Erase everything starting with the 1 sign through the ¢.

However, the line is correctly interpreted if entered as follows:
1 gross "12 pencils "a 92"¢ per dozen

section 5: Writing and Executing a Sample Program Using CMS

GC20-1804-3 Page Modified by TNL GN20-2659

!gte: The user may not be able to predict the results of mixing three or
more consecutive line editing symbols because of the way the input line
is acted upon by V"/370. For example:
abc""Cildef
and
abc'"'CiliiJdef
both result in
abcdef

CONTACTING V"/370 AND LOGGING ON
The next steps to take before you begin to create the program are:
contacting V"/370 and (2) identifying yourself to the computer.

(1)

To contact V"/370, you switch the terminal device on and V"/370 responds
with the message:
vm/370 online
to let you know that V"/370 is running and that you can use it. If you
do not receive the "vm/370 online" message, see the .!~LllQ: !,gil!1!~.!
Q§g~~§
§Y!Qg for help.
You can now press the Attention key
(or
equivalent) on your terminal and issue the LOGON command to identify
yourself to the system:
logon smith
where SMITH is used as your userid. The LOGON command is entered by
pressing the Return
(or Enter) key.
If V"/370 accepts your userid, it
responds by asking you for your password:
ENTER PASSWORD:
You then enter your password, which is, in most installations, hidden by
the system.
The series of lines you and the
like this:
vm/370 online

(!ii,g!!i!Q!! )

logon smith
ENTER PASSWORD:
IIIIIII

computer have exchanged so far looks

When you switched your terminal on, V"/370 responded
to let you know it was ready for your input.
You press the Attention key.
You entered the LOGON command and your userid, and
then pressed the Return key.
V"/370 asked you for your password in response.
You entered your password and the system hides it.

The logging on process is now complete and you can load your virtual
machine with an operating system, such as the Conversational Monitor
system (C" S) •

IBM VM/370: Command Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659

LOADING eMS IN THE VIRTUAL MACHINE: THE IPl COMMAND
The Conversational Monitor System is an interactive operating system
designed for VM/370 virtual machines.
CMS provides commands for
manipulating virtual disks (virtual disks correspond to real disks on
real machines)
and files
(units of data records such as programs or
input data for programsj. You load eMS in your virtual machine using
the CP IPL command:
ipl cms
where "cms" is
assumed to be the saved system
name for your
installationis eMS. VM/370 responds by displaying a message such as:
CMS VERSION v.l - mm/dd/yy
to indicate that
loaded.

12:02

the IPL command executed successfully and

that CMS is

Section 5: Writing and Executing a Sample Program Using CMS

50.1

If this is the first time the virtual disk is used you should make sure
that it is formatted. Be careful to use this information only if you
know your disk aust be for.atted. Ask your syste. prograamer whether or
not you should format your virtual disk. PORBAT takes the form:
for.at 191 a
CBS then prompts you with the following message:
DBSPOR603R PORBAT WILL ERASE ALL PILES
WISH TO COITIIUE? (YESIIO):

ON DISK 'A(191) '.

DO YOU

You answer:
~s

CftS then asks you for the disk label of the disk to be formatted, which
you can get fro. the system programmer:
DftSPOR605R EITER DISK LABEL:
You answer by entering a disk label:
ftYDISK
CftS then erases all the files on that disk, if any existed, and formats
the disk for your use. When you enter the label, CBS responds by telling
you:
PORftATTIIG DISK 'A'
'3' CYLIIDEBS PORBATTED 01 'A(191)'.
B; T=0.15/1.60

11:26:03

You have to issue this command the first time you use the virtual disk.

lh~ Cft~

Read~

ftessage

The last line of the response fro. CftS in the preceding example was a
Ready message. All CftS co.man~s generate a Beady message when they
co.plete processing. The Ready message is a response from the system to
let you know you can enter data into the system. The form of the Ready
message can vary, since it can be changed using the SET co.mand. The
preceding exa.ple shows the long form of the Beady .essage.
If your
Beady message is set to a short form, Yft/370 lets you know when you can
enter another co •• and by sending you a .essage that looks like:

B;
Until now, the com.ands discussed have had to do with the process of
getting you situated on your virtual machine; you have learned to use
the ter.inal, contacted Yft/370, logged on, loaded an operating syste.,
and formatted a disk to use. low you can go on to create a progra.,
asse.ble, load, and execute it.

Section S: Writing and Executing a Sample Program Using CftS

Using CMS to Create, Assemble, Load, and Execute a Program

The following infor.ation is a description of the four steps in writing
a program using CftS: (1) creating a program file, (2) assembling the
source file, (3) correcting the file if there are errors in it, and (4)
loading and executing the program. Before you can begin, however, you
should know a little about the CftS Editor.

HOW TO USE THE CftS BDITOB
The CftS Editor is the progra •• ing tool you can use to create and .odify
your program. The information you are about to read tells you how to use
the basic EDIT subco •• ands you need to create your program.

The Editor is a CftS component designed to make it convenient to cteate
and .odify files using the CftS operating system. The Editor is invoked
by the EDIT com.and, which, for your program, takes the form:
edit sample assemble
where SAftPLE is the name of the file you are creating, and ASSEftBLE is
the filetype of the file. The filetype tells the Editor that the file
you are creating is a file written in the assembler language.
The
Editor sets the correct logical tab settings you should use when
entering the Assembler language statements.
When you enter the preceding EDIT co.mand line, CftS responds with the
message
HEW FILE:
BDIT:
YOU

are now in the EDIT .ode.

The Editor can be used in two .odes, EDIT mode and IHPUT mode. The
IIPUT mode is used solely for entering new lines of data into your file.
The EDIT .ode is used to correct mistakes you made when you initially
created the file or to modify the file. The EDIT com.and automatically
places your virtual .achine in the EDIT mode; you enter the EDIT
subcommand IIPUT to place your virtual machine in the INPUT mode. To
get out of INPUT mode, press the Return key (or equivalent) on a null
line, that is, press the Beturn key without entering any data.
Usually, when you create a file, you first create the source records
and then check them for errors. The Editor provides subco.mands to make
the creation and correction of files convenient. The two sections that
follow describe (1) the subcommand you use when creating the file and
(2) other EDIT subcom.ands that are useful to you in creating and
correcting the program file. All of the facilities of the EDIT com.and
are described in the !,U37Q: J~!! Guide.

IBft Vft/370: Co •• and Language Guide for General Users

When you use the Editor, you change one line at a time. The Editor uses
a "current line pointer" to point to, or show you, the current line in
your file.
If you enter the TYPE subcommand, the Editor displays the
line it is currently pointing to without changing the pointer.

CREATING YOUR SOURCE RECORDS: THE INPUT SUBCOMMAND
You can use the INPUT subcommand in two ways:
(1) to enter the INPUT
mode or (2)
to insert a single line of data into your file.
To enter
the INPUT mode, you enter the INPUT subcommand and press the Return key.
To insert a single line of data, you enter the INPUT subcommand followed
by the line of data, then press the Return key.
When you are in the INPUT mode, the Editor accepts anything you enter
on the command line, regardless of its internal system definition. Only
the logical editing symbols can be used in the INPUT mode to change a
line. All you can do in the INPUT mode is add new lines of data to your
file.
Usually the Editor is used to create new files and modify existing
files, so it has features that make this convenient, such as line number
prompting for some language processors and tab settings for all
supported language processors.
For the assembler language program you
are creating, you can use tab settings provided by the Editor to space
to the correct position for assembler language instruction fields.

OTHER EDIT SUBCOMMANDS YOU NEED
The EDIT subcommands described here are almost self-descriptive. They
let you see what your file contains, alter its contents, and store it on
disk.
Remember that these are only a few of the Editor's facilities and
that you can find the rest described in the !~Lll~: ~~11 §EiQ~.

To see the first record of your
top record:

file, instruct the Editor

to type the

top
The top record of the file is always a null line, placed there by CMS
so that you can always insert records at the beginning of your file.
So, to see the first actual line of data,
use the subcommand DOWN 1,
which points the Editor to the line below the null line.
To see the last record in your
the bottom record of the file:

file, instruct the Editor

to locate

bottom

Section 5: Writing and Executing a Sample Program Using eMS

GC20-1804-3 Page Modified by TNL GN20-2659

To see records above the current line, instruct the Editor to move up in
your file:
up number
where number is the number of lines above the active line. For example,
UP 7 moves the current line pointer seven lines above the current line.
To see records below the current
down in your file:

line, instruct the Editor

to move

down number
where number is the number of lines below the current line.

To delete a line from your file, move up or down in the file so that the
line you want to delete is the current line.
When the line you want
deleted is displayed as the current line, instruct the Editor to delete
it:
delete number
where number specifies the number of lines deleted beginning with the
current line.
If you enter DELETE 9, the Editor deletes the current
line and the next eight lines following it. The new current line is the
one following the last deleted line.

To display records in your file, enter the TYPE subcommand:
type number
where number is the number of lines you want displayed, beginning with
the current line. The last line displayed then becomes the current
line. If you are using a 3270 display terminal in display mode use the
SCROLL, FORWARD, and BACKWARD subcommands to display records.

To change the contents of a record, issue the CHANGE subcommand:
change /string1/string2/
where string1 is the string of characters you want to replace
string2 is the string of characters you want to replace them with.

IBM VM/370: Command Language Guide for General Users

and

To store the co.mands and the data you have created in your file~
instruct the Editor to file your data for you, using- the PILE
subcommand. Before you issue PILE, however, you must return your virtual
machine to the EDIT mode. So press the Return key to enter EDIT mode,
and then issue PILE:
file
All of the records you created are now filed on your virtual disk.
The PILE subcommand takes your virtual machine back to the CftS
environment. CftS responds to the PILE subcommand with a Ready !essage,
to let you know your virtual machine is back in the CftS environment.
The subcommands just discussed should be adequate for writing and
editing a simple program. As you follow the prograa example you will
see how these EDIT subcoamands are used.

1 SA!PLE PROGRA!

The program you are about to create is a sample program designed to
familiarize you with the interactive facilities of Vft/370. The program,
when it executes, calls for you to enter a line of data in response to a
direction from the program.
It asks you to enter another item of
information. Then, it tells you what you told it.
Enter the prograa just as you see it. What you enter is shown in
lowercase; the Editor responses are shown in uppercase. The first field
the Editor allows you to enter is the label field, which begins with
column 1. When you press the tab key, the type ball moves to the next
tab setting on the terainal,'and this lets the Editor know that the next
field you enter goes in the operation field, which begins in column 10.
When you press the tab key again, the Editor spaces to the operand
field, beginning in column 16.
There are several ways you can get a continuation mark in column 72;
see the !A~l~: EDIT §yid~ for this information. In this exaaple, the
$!ARK edit macro is used. You must add the $!lRK edit aacro to your CftS
system; it is not distributed with CftS. The V!LJ1~: lDIT Guid~ tells
you how to add it to your CftS system.
Bote that the example shows one space after the third LIBEDIT macro
instead of pressing the tab key. The third LIBEDIT macro line is so
long that is does not fit if you tab to column 31.
When you enter the
third LINEDIT macro you aust press the Return key twice after the last
com.a: once to enter the line and one to return to EDIT mode. You know
you are in EDIT mode when EDIT: is displayed. Then you must enter the
macro '$!lRK'.
This places an * continuation mark in column 72. To
return to INPUT aode, enter 'input'.

section 5: Writing and Executing a Sample Program Using CftS

edit .yfile asseable
lEW PILE:
EDIT:
tabs 1 10 16 31 36 41 46 69 72 80
input
IIPUT:
When IBPUT: is displayed, you continue entering your program.
sample
csect
set up address ability
using sample,r12
load base register
lr
r12,r15
st
r14,savret
save return address
linedit
text='please enter your name'
rd term
name
linedit
text='please enter your age'
rd term
age
linedit text='hi, •••••••••• , you just told me you are

. ... , ,

EDIT:
$mark
input
IIPUT:
I

name
age
savret

sub=(chara,name,chara,age),rent=no
r14,savret
get return address
r14
return to caller

br
eject
dc
c1130'
dc
c1130'
dc
floe
regequ
end

name field
age field
save return address

When you finish entering the program, you can display it,
you should file it. If you display the program, it should be:

SlftPLB

IAftE
AGE
SAVRET

CSBCT
USIIG SAftPLE,R12
SET UP ADDRESSABILITY
LR
R12,R15
LOAD BASE REGISTER
ST
R14,SAVRET
SAVE RETURN ADDRESS
LIIEDIT
TEXT='PLEASE EITER YOUR NAftE'
RDTERft
IAftE
LIIBDIT
TEXT='PLEASE EITER YOUR AGE.'
RDTERft
AGE
LIIEDIT TEXT='BI, •••••••••• , YOU JUST TOLD ftE YOU ARE
SUB=(CBARA,llftE,CBARA,AGE),REIT=IO
GET RETURN ADDRESS
R14,SAVRET
L
R14
RETURI TO CALLER
BR
EJECT
IAftE PIELD
DC
CL130'
AGE PIELD
DC
CL130'
SAVE RETURI ADDRESS
DC
P'O'
REGEQU
EID

and then

Col
72
I

.... " *

Creating and Executing Your Program

This section describes the CftS commands you use to create, load, and run
your sample program: EDIT, GLOBAL, ASSEftBLE, LOAD, and START. These
cOllmands represent the most basic method of creating and executing a
program using CftS.
56

IBft Vft/370: Com.and Language Guide for General Users

INPUT FOR THE PROGRAft
To create

the program file,

enter the EDIT

command to invoke

the CftS

Editor~

edit sample assemble
The Editor responds to the command by
file and that you can begin creating it

telling you that this is a new

NEW PILE:
EDIT:
You then place your virtual machine in the INPUT mode by entering the
INPUT subcommand
input
When you press the Return key, the Editor responds with the message
IIPUT:
low you can enter the program statements. When you have entered all
of your program statements, press the Return key to return to the EDIT
environment. low issue the FILE subcommand to save the statements you
have entered and to return to the CftS command environ.ent.

ASSEftBLIIG YOUR PROGRAft
To assemble SAftPLE, you issue two commands: GLOBAL and ASSEftBLE. The
GLOBAL command accesses libraries needed by the assembler during its
execution. The ASSEftBLE command causes your program to be assembled by
the assembler. You should enter both GLOBAL and ASSEftBLE just as they
are shown here:
global maclib cmslib
assemble sample
CftS notifies you when the assembly is done by displaying a message at
your terminal. You receive one of two kinds of messages: one to tell
you there were no errors, the other to tell you there were errors and
where they were in the program. In either case, a Ready message is
generated to tell you that ASSEftBLE has completed execution.
If there are no errors, the message is
ASSEftBLER DOlE
10 ERRORS PLAGGBD II THIS ASSBftBLY

If you have errors, you receive a message like
ASSEftBLB DOlE
SAft00331
B
ERRT
IP0024
lEAR OPERAID
COLUftNl--UIDEPIIED SYftBOL
1 STATBftEIT WAS PLAGGED II THIS ASSEftBLY
8 WAS HIGHEST SEVERITY CODE
R(008);

section 5: Writing and Executing a Sample Program Using CftS

If you receive the error message, you have to go back and correct
your prograa; the asseabler language error message you receive tells you
where and how you aade the mistake. Use the EDIT coamand to correct the
file:
edit saaple asseable
This stateaent allows you to correct your source file.
The Editor
places your virtual machine in the EDIT mode and places the file in
storage so you can edit it. You can now begin aaking corrections using
the EDIT subcom.ands described in the first part of this section.
When you have corrected the program, file it again and reasseable it
(assemble sample).
This tiae you need not enter the GLOBAL command,
since the first GLOBAL command is in effect for the duration of your
terainal session.
If the prograa assembles
storage and execute it.

with no errors, you can load

it in virtual

LOADING AND EXECUTING THE PROGRAM
The CMS LOAD and START co •• ands load your program in virtual storage and
begin its execution. The LOAD coamand processes the relocatable object
code produced by the ASSEMBLE co •• and.
The LOAD co •• and loads the
assembler TEXT file into storage and establishes the proper linkage.
Enter the LOAD com.and as it is shown here:
load saaple
After you press the Return key, CMS responds with a
(R;) when your program is loaded successfully.

Ready message

low enter the START co.mand to begin execution of the program:
start sample
The virtual machine, with your prograa
the messages supplied by your program:

now in control, proapts you with

PLEASE EITER YOUR lAME:
PLEASE ENTER YOUR AGE:
After you answer its questions, your program writes you a message and
returns a Ready aessage.

LOGGIIG OPP
When you want to end the terainal session, use the LOGOPP co.mand,
logoff

IBM VM/370: Coa.and Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659

Section 6: Virtual Machine Operation

Virtual System Console
The major differences
operating under CP are:

between

operating

the

real

machine

and

•

You can enter CP commands by entering CP mode, or by issuing the iCP
command while a virtual machine's console is able to read.

•

The Request key of a real operator's console
signalling attention once from the terminal.

simulated

To reply to messages from a virtual machine operating system, you:

Must enter VM mode (if you on a 2741 communication terminal).

•

Enter the information requested.

•

press the carriage return (Return)
key on
Terminal (or equivalent on other terminals) •

the 2741

Communication

If communication with CP is required before responding to specific
error messages issued by some virtual machine operating systems, enter
CP mode and perform the necessary console functions.
When control
returns to the virtual machine environment,
the virtual machine read is
canceled by a unit exception and the virtual machine operating system
responds by reissuing the read.
The required virtual machine response
may then be entered.
The Cancel key of the system console keyboard is simulated by the
Attention key on the 2741.
To enable the CPU operator to make input
line and character corrections to operating system responses, the VM/370
logical editing symbols may be used.

Attaching Devices

When a virtual machine operating system requires a specified device, as
in a MOUNT request, you should do one of the following:
•

If the device is already defined as part of the virtual machine
configuration, enter CP mode.
Then enter the CP command READY cuu
(with cuu replaced by the virtual I/O device address), followed by
the CP BEGIN command.
This is the virtual machine equivalent of
physically making a device ready,
if it is not already in a ready
state.

•

If the device is not a standard device already defined as part of the
virtual machine configuration, enter CP mode, and issue the CP DEFINE
command to add the device to the virtual machine configuration. If a
DASD device is already defined for some other user in the VM/370
directory, you can use the CP LINK command to add the device to your
virtual machine configuration.
Otherwise, send a message to the
Section 6: Virtual Machine Operation

system operator to attach it to your virtual machine.
device is ready, enter the BEGIN command.

When the real

Note:

If the virtual device is an attached real device at the time you
it mounted, the real device can be taken out of and put back into
ready status to cause an interrupt.

need

TAPE DEVICES
Tape drives, because they cannot be shared, are usually not defined in
the VM/370 directory as part of a virtual machine configuration.
When
you require a tape drive for a job, a system operator with privilege
class B must attach an available real device to your virtual machine
with the virtual device address you require.
When the job involving
that tape drive is complete, you can issue a DETACH command, naming the
virtual device address of the tape to release the tape.
In this way,
real tape drives are allocated to a virtual device only for the duration
of the jobs that need them.

Loading an Operating System into a Virtual Machine
Figure 10 shows how you could load an OS/MFT system on a virtual
machine, and the subsequent mounting of a virtual device at address
232.
(For clarity, the information you enter is shown in lower case,
and messages displayed by CP and OS are shown in uppercase).
The virtual machine that is to run OS must have a configuration
compatible with that for which the operating system's nucleus was
generated. An example of an appropriate VM/370 directory entry is:
USER BATCH PASSWORD 512K
ACCOUNT NUMBER BIN10
OPTION REALTIMER ISAM
CONSOLE 01F 3215
SPOOL C 2540 READER A
SPOOL D 2540 PUNCH A
SPOOL E 1403 A
DEDICATE 230 BATCH1
DEDICATE 231 BATCH2

IBM VM/370: Command Language Guide for General Users

r--------------------------------------------------------------------------------,
logon os/mft
ENTER PASSWORD:
(Printing of the password is inhibited)
LOGON AT 13:24:30 EST THURSDAY
ipl 230

m./dd/yy

IEE007A READY
set date = 72.355, Q = (231)
start rdr, OOc
start vtr, OOe
start
IEl233A e 232, VOLABC,JOB,STEP

IPL the OS system residence device.
You must respond to alIOS IPL co.mands.
OS ready message.

OS requests operator to mount a pack labeled
"VOLABC" on 232.
You press the attention key once to present
an interrupt to OS.

Icp link to usera 330 as 232 w pass
DASD 232 LINKED TO R/i

.cp ready 232

Because the LINK co •• and vas prefaced by 'CP,
the OS virtual machine acts as though you
had pressed the CANCEL key, and issues
another READ to the syste. console. The LINK
co.mand is passed directly to CPo
You request that a disk belonging to usera,
with a virtual address of 330, be linked
to your own virtual machine. You issue the
CP LINK com.and to access that other user's
disk, with virtual address 232 in his virtual I
aachine. Alternately, you could issue the
I
"vary 232,online" OS comaand.
I
I

Then enter READY to siaulate a ready
I
interrupt to OS and end the read by pressing I
the carriage return or Enter key.
I
I

Figure 10. Loading an OS/8FT Virtual 8achine

Spooling Virtual Console 1/0

CP lets you spool your virtual aachine's console input/output to disk,
instead of, or in addition to, having it displayed at your terainal.
The data spooled includes aessages from or to the virtual .achine
operating systea, and froa or to CP. This facility, invoked by the
SPOOL CONSOLE co •• and, is particularly useful when the virtual .achine
is executing with the terminal disconnected, or when the virtual aachine
console is a display device, since the virtual console output, which
would otherwise be lost, is saved on disk. The saved data is later
printed on the real printer.
If the real printer cannot print lower-case characters, the operator
can use the FOLD option when he loads the buffer for the print train
image. This causes the printer to print, in upper case, data that you
enter in lower case.
You can invoke or ter.inate virtual console I/O spooling at any tiae
and as often as you like. If the console file is not closed when you
log off (or are forced off) the V8/370 syste., CP closes the console
spool file and schedules it for printing.
Section 6: virtual ftachine Operation

GC20-1804-3 Page Modified by TNL GN20-2659

Reading Cards in a Virtual Machine
When an operating system such as DOS, DOS/VS, or OS/PCP, MFT, MVT, VS1,
or VS2 is running batch production jobs in a virtual machine, it aay
occasionally be necessary to dedicate a real card reader to that virtual
machine.
In that case,
jobs are entered through the card reader in
exactly the same way they are entered on a standalone system, and no
double spooling occurs.
If, however, there is no extra reader availatle to dedicate in such a
manner, or if the virtual machine is being run from a terainal not
located near a real card reader, other methods of handling card input
are necessary.
Card images can be placed into the (spooled) virtual
your virtual machine in four ways:

card reader of

•

A card deck can be placed in the real card reader and read by VM/370.
The deck must be preceded by a special VM/370 identification (ID)
card specifying your virtual machine userid. VM/370 reads the cards
and transfers the card images to your virtual machine's virtual card
reader as a spool file.
When your virtual machine issues a read to
the card reader, VM/370 presents the cards, one at a time, to the
virtual machine. The format of the ID card is described in the CMS
READCARD command description.

•

A virtual machine's printer can transfer printer listing images and
the punch can transfer punch images to its own
(or to some other
user's)
virtual card reader.
CP can handle up to 150-character
records in virtual card readers. The CP SPOOL transfers these unit
record files. For example:
spool punch to usera
causes all cards punched to be transferred (after the punch file is
closed) as an input file to usera's spooled card reader.
CMS cannot print files that have records greater than 160 characters
long. However, CMS can display records greater than 160 characters
long.

•

Via the CP TRANSFER command, you can transfer your virtual reader
file(s)
to another user's virtual reader, or retrieve previously
transferred files back to your own virtual reader.

•

A card deck can be placed in the card reader of any of the remote
stations supported by the Remote Spooling Communications Subsystem
(RSCS). The same VM/370 ID control card, as mentioned previously,
must precede the deck.
RSCS receives the card file and spools it to
the specified VM/370 user's virtual card reader.

Normally you should find it helpful to
options for your virtual card reader:
spool

cont

~Oc

set the

following spooling

cont noeof

specifies that reading be "continuous" (that is, not to indicate
an EOF condition to the virtual machine after each input file,
but to continue reading all the card images until the reader
IBM VM/370: Command Language Guide for General Users

files spooled to the virtual machine are exhausted).
If this
option is not in effect, a unit exception is reflected to your
virtual machine at the end of each spooling file. This option
eliminates the need to repeatedly enter the CP RBADY and CLOSB
commands between the reading of each spooled file.
noeof

indicates that the virtual reader's end-of-file button is
assumed not to have been pushed.
When all reader spool files
are exhausted, an intervention-required
status pending is
reflected to the virtual machine.
When additional reader files
are transfered to the virtual card reader, a device end
interrupt i~ reflected to the virtual machine, and card reading
normally resumes automatically (because a device end interrupt
"wakes up" the virtual machine).

The operator of a virtual machine operating system such as OS or DOS
may choose to prepare his own job streams at his terminal using the CMS
Bditor facilities, and then IPL another operating system to process the
job streams.
This procedure is
discussed under "Using Multiple
Consecutive Operating Systems."

Printing and Punching in a Virtual Machine
VM/370 provides unit record spooling facilities.
When operating systems
that also provide unit record spooling facilities are running in a
virtual machine, double spooling of printed and punched output may
occur. If you wish, you can eliminate one of the spooling facilities.
To eliminate CP spooling, a real printer or punch can be temporarily
attached to a virtual machine, or dedicated to a virtual machine in the
VM/370 directory via the DBDICATE statement.
In either case, CP
performs no spooling for that virtual device.
Interrupt processing can
be initiated by the virtual machine whenever it receives control of the
CPU from CP.
CP spooling has priority over any virtual machine execution. The
real printer and punch are better utilized by CP than by a virtual
.achine. ~~ spooling provides .ore efficient shared use O~ a i1.1~ed
number of readers, printers, or punches by many virtual machines.
OS spooling can be eliminated by using OS JCL in the form UNIT=OOB or
UNIT=OOD instead of SYSOUT=A or SYSQUT=B, where OOB and OOD are virtual
device addresses.
DOS POWER spooling can be eliminated by using the Job Entry Control
Language (JECL) option of POWER and by indicating no spooling on the
JECL control statements for dedicated spooling devices.
When printer or punch spooling is performed by CP, the CP CLOSE
command specifying the virtual printer or punch address should be issued
periodically.
This releases previously finished and stacked output
files for CP spooling and results in better utilization of the DASD
spooling areas and of the unit record devices.
CMS has no spooling facilities of its own, and does not cause double
spooling when running in a virtual machine. It does not support an
attached or dedicated printer, punch, or reader, and must use the
facilities of CP. CMS closes the virtual printer or punch after the
completion of each command that uses them.

Section 6: virtual Machine Operation

Disconnecting the Terminal
Once you load a virtual machine operating system and start jobs you .ay
want to use your terminal for some other purpose while the batch jobs
are running. The DISCOII coaaand allows you to disconnect your terminal
from the V~/370 system, but allows the virtual aachine to continue
operation.
You can reconnect your ter.inal by issuing the LOGOI
co •• and.
Unless the CP com.and, SPOOL COISOLE START, is issued to spool the
virtual console and CP output, all "writes" or output messages to the
virtual console are ignored.
A BOLD option is provided with the DISCOII coamand to prevent a
communication line in
a switched line configuration
from being
disabled.
Disconnecting the terminal frees it for other uses, but is useful
only for operating systems that can run in an unattended mode.
If a
virtual machine that is running disconnected issues a "read" to the
virtual console or enters a disabled wait state, virtual machine
execution is halted and a 15-minute time-out begins.
If you do not
re-establish your connection to the V~/370 systea (by logging on again)
within 15 minutes, you are logged off the system.
A virtual
aachine aay also
be placed in
disconnect status
automatically. If a teleprocessing line error occurs, or you turn off
your terminal without logging off, the virtual machine is disconnected
and execution stops.
(If you turn off a 3210 without logging off, the
virtual machine is disconnected if someone sends a message to the
terminal.)
A 15-minute time-out begins.
If you do not log on again
within 15 minutes, your virtual machine is logged off the system.
When a disconnected machine is logged off, V~/370 closes
spool files and schedules them for printing or punching.

all open

You reconnect to a disconnected virtual machine via the noraal logon
procedure.
(If there was a read active on the ter.inal at the time of
disconnect, you aay have to issue a RESET co.aand for the terminal.)
Your running virtual machine is placed in the CP com.and mode.
To
resume execution of the virtual machine operating system, issue the
BEGI) command.
For example,
(a) shows the disconnect
subsequent reconnect, as long as PROGA
reconnects.

procedure, and (b) shows the
is still running when USERA

(a)

logon usera
EITER PASSWORD:
(displaying of the password is inhibited)
LOGOI AT 05:30:30 EST FRIDAY mm/dd/yy
ipl 190
C~S VERSIOI 2 LEVEL 0
run proga

•••

CP
disconn
DISCOIIECT AT 05:35:30 EST FRIDAY mm/dd/yy

IB~

V~/370:

Command Language Guide for General Users

(b)

logon usera
FafTER PASSWORD:
(displaying of the password is inhibited)
RECONNECT AT 07:42:45 EST FRIDAY mm/dd/yy
begin
(if one exists)
is not executed
Note: A PROFILE EXEC procedure
automatically when you log on after disconnecting. Also, if you set a
as specifying TERMINAL APL
ON)
before you
system option (such
disconnect, that option may be returned to its default when you log on
again.

Using Multiple Consecutive Operating Systems

You may require the facilities of
a single terminal session.

more than one operating system during

When you run an operating system such as as, DOS, OS/VS1, OS/VS2, or
DOS/VS from a terminal, you can use the CMS Editor facilities to create
and modify job streams.
If you are an applications programmer who normally uses CMS to
interactively create, modify, and test your programs you may require
facilities not supported or available in CMS for compilation (for
example, programs using DOS macros) or for execution (for example, any
DOS object program, or any as object program that utilizes certain as
supervisory functions. and access methods not simu1a ted under CMS).
The
following
technique
uses
multiple
operating
systems
consecutively.
Job
control cards, compiler or
assembler source
programs, and test data streams are created and modified at the terminal
under control of the CMS Editor. Then the job stream is executed, only
after control has been passed to an appropriate operating system with
the necessary facilities.
In this way, you can use the terminal-oriented facilities of CMS to
create and update source progra.s and ~CL. When you are ready to
compile or test, you can give control of your virtual machine to DOS or
as. After execution is finished, you can transfer the printer and punch
output back to CMS for selective scanning and displaying at the
terminal.
This approach assumes you have created source program files and data
files under CMS. To execute under another operating system (in this
example, OS)
you must also create JCL records that specify the
compilation, link edit, or execution, as appropriate. These records are
created under CMS and named with a distinctive filename and filetype
(for example, PLICOMP JCL). Job control records, source program files,
and data files can then be merged together in the virtual card reader to
form a single as job stream. CP and CMS commands (shown in Figure 11)
create and transfer this job stream.

I TRANSFERRING OUTPUT
The CP SPOOL command transfers card images from the virtual card punch
of one virtual machine to the virtual card reader of that same or some
other virtual machine. During this time, no real cards are punched or
read; CP manages the transfer of CMS card-image data files through disk
spooling operations only.
section 6: virtual Machine Operation

Figure 11 shows how files are transferred between virtual machines.
The virtual machine is in eMS mode at the start of the example. The
co •• and "SPOOL OOc cont eof" specifies that reading be continuous until
all files spooled to the virtual machine are exhausted and the virtual
end-of-file button on the reader is pushed.
NOHEADER specifies that no
special control cards are to be inserted in front of each punched file.
virtual device 230 is an as system volume. virtual device 231 contains
the as job queue, SYS1.SYSJOBQE. All standard as responses
(for
example, R;T=0.04/0.12 09:36:08) are omitted from the example; however,
the as READY message is included to more fully illustrate the IPL
sequence. Also, assuming you are using a 2741, you must press the
Attention key before entering each as command. The attention interrupts
are not shown in Figure 11.

r----------------------------------------------------------------------------,
CMS
cp close OOc
cp close OOd
cp spool OOd to
punch jobcard jc1 (noheader)
punch plicomp jc1
(noheader)
punch plimain pl1
(no header)
punch asmcomp jc1
(noheader)
punch asmsub assemble
(noheader)
punch linkgo jc1
(noheader)
punch godata dat (noheader)
punch slshstar jc1 (noheader)
cp spool OOc cont eof
cp ipl 230

Not~:

The following are issued once under as control:

IEE007A READY
set date=xx.355,Q=(231)
start rdr,OOc
start wtr,OOe
start
Figure 11.

as Job stream Transfer

To transfer files between virtual machines, you must" have access to
both operating systems being used. Access to both systems can be
provided either in your virtual machine's VM/370 directory entry, or
dynamically before loading the new system.
Figure 12 illustrates a virtual machine configuration and the
corresponding VM/370 directory control statements.
Virtual device
addresses 190 and 191 contain the CMS system and user disk area.
virtual device addresses 230 and 231 contain the os system and user disk
area. The two systems use a common card reader, card punch, printer,
and console.

IBM VM/370: Command Language Guide for General Users

USER OS2 PASSWORD
ACCOUBT BUftBBR BIB16
COBSOLB 01F 3215
SPOOL C 2540 RBADBR
SPOOL D 2540 PUBCB
SPOOL B 1403
LIBK JFK 230 230 R
LIBK CftSSYS 190 190 RR
ftDISK 231 2314 120 82 W
ftDISK 191 2314 101 10 UDISK1 WR RPASS WPASS
Figure 12.

Directory Bntry for Alternating Operating Systems

I CONFIGURATIOBS

You can alternate operating systems more simply if:
I.
I

The devices used by both
address, and

The common addresses are not used to support different devices

systems are

supported at the

If these two conditions do not exist, you must modify
machine configuration before each IPL of a new system.
If the two systems require online typewriter
addresses, the CP DBFIBB com.and can be used to
the virtual system console. For example, if the
Figure 12 required an online typewriter keyboard
the command

same device

the virtual

keyboards at different
change the address of
OS system specified in
at address 01F,·issue

cp define 009 as 01F
before loading
command

230.

When

the OS

job stream

is completed,

issue the

cp define 01F as 009
before loading CftS. virtual storage size can be changed and virtual
card readers, printers and punches can be added with this procedure.
If the systems expect different device types at the same address (for
example, in Figure 12 CftS expects a 2314 at address 191, but the OS
system might be generated to support a 3330 at that address), the common
address must be assigned to the appropriate device each time a new
system is loaded. If CftS is running with a disk at address 191, you
should issue the following command before loading OS:
cp detach 191
An appropriate device can then be added to the virtual machine at
address 191 either befOre loading, or in response to a mount request
from the OS system.
!Qte:
For direct access storage devices, the above procedure is
necessary even if both systems support the same device type at the same
address. The disk format used by CftS is unique, and is not compatible
with that of other operating systems. Files can be shared between CftS
and OS or DOS only through the spooling facilities, of CP.

section 6: Virtual ftachine Operation

Execution Control
1 string of arguments can be passed to your program from the terminal
when execution is begun with the CKS START command. If arguments are
specified, the storage address of a parameter list is placed in general
register 1. The parameter list is a string of double words, one
arguaent per double word.
The first argument is the entry operand.
Other arguments are accessed with displacements of 8, 16, 24, and so on,
from the address contained in register 1 when execution begins. For
exallple:
load proga
start epg 071374
causes execution to begin at a control section or entry point named
EPG. When execution begins, general register 1 points to a string of
two double words, the first containing lPG, the second containing
071374.
If a program is to be executed frequently, you can create a
non-relocatable copy of it on one of your disks. Subsequent invocation
of this program causes the absolute module to be read from disk storage,
ready to begin execution.

IBK V"/370: Command Language Guide for General Users

Part 2: Reference Information

This part of the publication contains reference information.
contains all the formats and rules for using CBS commands.
contains the formats and rules for using CP commands.

Section 7
section 8

Notational Conventions
The notation used to define the command syntax in this publication is:
•

Truncations and Abbreviations of Commands
Where truncation of a command name is permitted, the shortest
acceptable version of the command is represented by uppercase
letters.
(Remember, however, that VB/370 commands can be entered
with any combination of upper and lowercase letters.)
The example
below shows the format specification for the FILBDBF command.
FIledef
This representation means that FI, FIL, FILB, FILBD, FILBDB,
FILBDBF are all valid specifications for this command name.

and

Operands and options are specified in the same manner.
Where
truncation is permitted, the shortest acceptable version of the
operand or option is represented by uppercase letters in the command
format box. If no minimum truncation is noted, the entire word
(represented by all capital letters) must be entered.
Abbreviations are shorter forms of co •• and names, operands, and
options. Abbreviations for command names are shown below the full
name in the format box. Abbreviations for operands and options are
shown in the description of the individual operands and options that
follows the format box. For example, the operand RBADBR has both a
minimum truncation and an abbreviation. In the format box it is
shown as:
Reader
indicating that the minimum truncation is R. In the
the RBADER operand that follows, it is shown as:

discussion of

READER
RDR
indicating that the abbreviation is RDR.
Thus, the acceptable
specifications for the REIDER operand are: R, RE, REI, REID, RBIDB,
REIDER, and RDR.
In some cases what appears to be a minimum truncation is really the
only valid abbreviation. For example, the abbreviation for BEBBER is
BEB. Only these two forms are valid and no truncations are allowed.
The format box contains

Part 2: Reference Information

MEMBER {n:ae}
and the description that follows the format box is
MEMBER { nalle}
"EM
*
•

The following symbols are used to define the coaaand foraat
should never be typed when the actual co.aand is entered.
underscore
braces
brackets
ellipsi's

•

{ }
[]

Uppercase letters and words, and the following syabols,
entered as specified in the format box.
asterisk
comma
hyphen
equal sign
parentheses
period
colon

and

should be

*
=

()

•

Lowercase letters, words, and symbols that appear in the comaand
format box represent variables for which specific information should
be substituted.
Par exaaple, "fn ft f." indicates that file
identifiers such as "MIPILE EXEC 11" should be entered.

•

Choices are represented in the command format boxes by stacking.
1
B
C

•

1n underscore indicates an assumed default option. If an underscored
choice is selected, it need not be specified when the coa.and is
entered.
~!!!£!.!!

The representation
1
~
C

indicates that either 1, B, or C may be selected.
However, if B is
selected, it need not be specified. Or, if none is entered, B is
assumed.

IBM VM/310: Coa.and Language Guide for General Users

•

The use of braces denotes choices, one of which

~§!

be selected.

EX~l!.El~

The representation

{~ }
indicates that you !!§! specify either A, or B, or C.
choices is enclosed by neither brackets or braces,
treated as if enclosed by braces.

•

The use of brackets denotes choices, one of which

~!~

If a list of
it is to be

be selected.

~.!!.!!.El~

The representation
r

I A I
I B I
I C I
L

indicates that you may enter A, B, or C, or you may omit the field.
•

An ellipsis indicates that the preceding item or group
be repeated more than once in succession.

of items may

~!!!tE!g

The representation
(options ••• )

indicates that
parentheses.

than

one

option

may

coded

within

Part 2: Reference Information

the

Section 7: Format and Usage Rules for CMS Commands

CMS Command Summary

This section contains descriptions of the commands acceptable in the CMS
environment.
Pigure 13 contains an alphabetical list of the CMS
commands and ~ne functions performed by each.
Unless otherwise noted,
CMS commands are described in this manual.
I

ICommand

Usage

1------------------------------------------·------------------------IACCESS
IDefine direct access space for a CMS virtual machine,
1
1
1

IASM3705 1
1
IASSEMBLE
CMSBATCH

Icreate extensions and relate the disk space to a logical
1directory.
1
IAssemble 3704/3705 source code.
1

IAssemble Assembler Language source code.

Invoke the CMS Batch Pacility.

COBOL2

Compile ANS Version 4 COBOL source code.

COMPARE

Compare all or part of records in two existing disk files.

COIVERT2

Convert free form PORTRAN statements to fixed form.

COPYPILE

Copy files according to spedifications.

Enter CP commands from CMS environment.

CPEREp3

Dump error information which was recorded by VM/370 error
recording routines.

DDR1,3

Perform backup, restore, and copy operations for virtual
disks.

DEBUG"

Enter DEBUG subenvironment, DEBUG mode.

DIRECT1,3

Set up VM/370 directory entries.

DISK

Perform
Ifiles.

disk-to-card and card-to-disk operations for CMS

lThis co.mand .is described in the VML170: PlanninE ~~~ ~st~~
'I
Generation Guide.
1
2ThIs-COimand-rnvokes an IBft Program Product, available fro. IBM for 1
a license fee.
1
3This com.and is described in the VM/170: QR~~at2~~§ Guid~.
1
"This command is described briefly in this manual and in detail in thel
VMn70: .§.l!!!~! Pr2.9!:~!~!:~!! ~!!!g~.
1
I

Pigure 13.

CMS Command Summary (Part 1 of 4)

Section 7: Pormat and Usage Rules for CMS Commands

•I Command

Usage

1------------------------------------------------------------------IEDITs
IEnter EDIT sUbenvironaent, EDIT aode.
I

IERASE
I

I EXEC6

I
I

PILEDEP

IDelete files from user disks.
I

IProcess special procedures aade up of frequently used
Isequences of coa.ands.
I

IProvide simulation of OS job control language data
(DD) stateaents.

Id~finition

POR!AT

Prepare disks in CftS 800-byte block foraat.

PORTGI2

Compile PORTRAI source code using the G1 coapiler.

POR'IBX2

Coapile PORTRAI source code using the

GEN37051

Generate an EXEC file that assembles and link edits the
3704/3705 control program.

GENDIRT

Create auxiliary module directories.

GENftOD

Generate absolute non-relocatable files (ftODULE files).

GLOBAL

Define specific CftS libraries to be searched for
and subroutines.

GOPORT2

Compile PORTRAN' source code and execute the program just
coapiled using Code and Go compiler.

INCLUDE

Bring additional TEXT files into storage and establish
linkage.

LISTDS

List information about data sets on an OS disk.

LISTPILE

List information about user CftS files.

LKEDI

Link edit the 3704/3705 control program.

LOAD

Bring TEXT files into storage and establish linkages.

LOAD BOD

Bring a single ftODULf file into storage.

BACLIB

Create and modify C!S .acro libraries.

B-extended coapiler.

aacro~

lThis command is described in the 'ftLJ70: Rlanni~~ A~~ §I~!~!
Generation Guide.
2ThIs-coiiand-iiivokes an IB! Program Product, available froa IB! fOl: a
license fee.
5This command is described briefly in this manual and in detail in the
'ftLJ70: ED.!~ Guide.
6This command is described briefly in this manual and in detail in the
'!/~lQ: 111~ Y2~~§ §!!!de.

Pigure 13.

C!S Co •• and Suamary (Part 2 of 4)

IB! '1'/370: Command Language Guide for General

U~ers

Coaaand
ftODftlP
ftOVEFILE

Usage
IDisplay load map of a ftODULE file.
I

Iftove data fro. one device to another device of the same or

1different type.
1
-

ICPDUftPl,3 Process CP spool reader files created by 3704/3705
duaping operations.
PLIC2

Co.pile the PL/I source code using the PL/I Checkout
Compiler.

PLICB2

Execute the PL/I object code generated by the PLjI Checkout
Coapiler.

PLIOPT2

Coapile the PL/I source code using the PL/I Optiaizing
Compiler.

PBIRT

spool a specified CftS file to the virtual printer.

PURCH

Spdol a specified CftS file to the virtual punch.

QUEBY

Bequest information about a CftS virtual machine.

BEIDCIBD

Bead data froa spooled card input device.

BELEISE

ftake a disk and its directory inaccessible to a CftS virtual
machine.

BEIAftE

Change the name of a CftS file or files.

BUI

Initiate series of functions to be perforaed on a file.

SAVEICPl

Bead 3704/3705 control program load into virtual storage
and save an image on a CP-ovned disk.

SCBIPT?

Foraat and print documents according to embedded SCBIPT
control vords in the document file.

lThis comaand is described in the Vft/112: f!!!!i!g !nd ~ste~
2This coaaand invokes an IBft Program Product, available froa IBft for al
license fee.
1
3This command is described in the !!l112: Q~!~!!2~~§ §yide.
1
?This co.mand invokes a text processor that is an IBft Installed User 1
Program, available froa IBB for a license fee.
1
Figure 13.

CBS Co.mand Suaaary (Part 3 of 4)

Section 7: Format and Usage BuIes for CftS Coa.ands

Command

Usage

SET

Establish, set, or reset CMS virtual machine
characteristics.

SORT

Arrange a specified file in ascending order according to
specified fields in the data record.

START

Begin execution of programs previously loaded.

STATE

Verify the existence of a file.

SVCTRACE

Record information about supervisor calls.

SYRORYM

Invoke a table containing synonyms you have created for
CMS commands.

TAPE

Perform tape-to-disk and disk-to-tape operations for CMS
files.

TAPPDS

Load OS partitioned data set (PDS) files or card image
files from tape to disk.

TESTCOB2

Execute the OS COBOL Interactive Debug Program Product.

TESTFORT2

Execute the "FORTRAN Interactive Debug Program Product.

TXTLIB

Generate and modify text libraries.

TYPE

Display all or part of a file at the terminal.

UPDATE
VMFDUMp3
VSBASIC2
VSBUTIL2
ZApl,3

Make changes in a file as defined by control cards in a
Icontrol file.

I
IFormat and print system ABBRD dumps.
I
ICompile and execute VS BASIC programs under CMS.
I
IConvert BASIC 1.2 data files to the format required by
IVS BASIC.
I
IModify or dump LOADLIB, TXTLIB, or MODULB files.

lThis command is described in the !AL11Q: g!~!!iBg !~g System
Generation Guide.
"
2This-coimand-invokes an IBM Program Product, available from IBM for a
license fee.
3This command is described in the !1L~lQ: QEerator's Guide.
Figure 13.

CMS Command Summary (Part 4 of 4)

IBM VM/370: Co.mand Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659

Any of the commands listed in Figure 13 may be entered when you are
running CMS in your virtual machine, the terminal is idle, and the
virtual machine is receptive for input. If however, CMS is processing a
previously entered command and your typewriter terminal keyboard is
locked, you must
signal your virtual machine
via an attention
interrupt.
The system acknowledges the interrupt by unlocking the
keyboard: Now you can enter commands. If your terminal is a display
device, there is no problem of entering commands while the virtual
machine is busy as its keyboard remains unlocked for additional command
input. Note that in these circumstances the most recent command is
stacked and is not executed until the command that is currently
executing completes.
In addition to the commands listed in Figure 13, there are seven
commands called Immediate Commands which are handled in a different
manner from the others. They may be entered while another command is
executing by pressing the Attention key (or its equivalent) and are
executed immediately. The Immediate Commands are:
I

•
•
•
•
•
•
•

HE - Halt batch execution
HO - Halt tracing
HT - Halt typing
HX - Halt execution
Re - Resume tracing
RT - Resume typing

so - Suspend tracing

section 7: Format and Usage Rules for CMS Commands

ACCESS

ACCESS
Use the ACCESS co.mand to acquire disk space and to set up file
directories in storage to be used during a ter.inal session. A Master
File Directory is the disk-resident file directory containing an entry
for each CMS file on a virtual disk.
A User File Directory is the
directory created in storage when the ACCESS co.mand is executed. It
contains an entry for each CMS file that is available to you in your CMS
virtual machine. The specifications of the ACCESS com.and deter.ine the
entries in the User File Directory.
The format of the ACCESS co •• and
is:

r-----

------------------------------------------------------------------------,

ACcess

Icuu 1I0de[/ext [fn [ft [fm]]]]1 [(options ••• [)]]
L

2E!iQ!!§:
r

INOPROFI
IERASE 1
L
L-_ _ _ _ __

cuu

[ NODISK]

makes the disk at the specified virtual device address
available. This field must be specified if other than the
default value is desired.
The default value is 191, except
when the NODISK option is
specified.
(When BODISK 1S
selected, the only disk accessed is the system disk and any of
its extensions.)
Note that 000 is not a valid address.

mode

assigns the one-character filemode letter to the disk being
accessed. This field must be specified if cuu is specified
(except when the NODISK option is selected). The default
value is A.

ext

indicates the mode of the parent disk.
The User File
Directory of this disk is logically associated with the User
File Directory of the read-only extension. There must not be
a blank preceding or following the slash (I).

searches the Master 'File Directory of the disk being accessed
and includes the files with the specified filename in the User
File Directory for that disk. An asterisk coded in this field
means that all filenames are to be included.
(See Bote 5.)

searches the Master File Directory of the disk being accessed
and includes the files with the specified filetype in the User
File Directory for that disk.
If an asterisk is coded in this
field, all filetypes are included. (See Note 5.)

searches the Master File Directory of the disk being accessed
and includes the files with the specified filemode in the User
File Directory for that disk. An asterisk coded in this field
means that all files on the disk specified by the filemode
letter and device address are selected, regardless of the
filemode number.
(See Note 5.)

IBM VM/370: Command Language Guide for General Users

ACCESS
An asterisk (*), preceded by any number of characters for filename
or filetype, allows the specified characters to be used as the leading
characters for that identifier. For example, ABC* for fn allows access
to all files with filenames beginning with ABC.

I~te:

lOPROF

suppresses execution of a PROFILE EXEC file (see lote 1).
This option is valid only if the ACCESS co •• and is the
first co.mand entered after an IPL of the CftS operating
system. On subsequent ACCESS co •• ands, the NOPROr option
is ignored.

BRASB

creates a User File Directory with no entries for the
disk being accessed; this option is valid only for disks
in read/write mode. The ftaster File Directory on the
disk re.ains unchanged; only. the directory in virtual
storage is altered (see Bote 3).

BODISK

lets you gain access to the CftS operating system with no
disks
accessed except
the
system
disk and
its
extensions.
This option is valid only on the first
co •• and you enter after loading CftS.
If BODISK is
specified, no other operands or options may be used.

The PROFILE EXEC file is a user-generated EXEC procedure often used
to perform initialization and to set system parameters required by
the virtual .achine.
For exa.ple, whenever programs that use
macros are assembled or compiled, the PROFILE EXEC procedure can
issue the GLOBAL co.mand to indicate where the system should search
for the macros. For OS programs, the PROFILE EXEC procedure can
issue FILEDEF state.ents for the files to be used.

If an ACCBSS co •• and is not entered as the first
IPL com.and for CftS, the command:

co •• and after an

access 191 a
is auto.atically perfor.ed and the PROFILE EXEC file, if one
exists, is executed. Any disk being accessed must previously have
been formatted using the CftS co.mand FORftAT.
3.

If an ACCESS co •• and with the ERASE option is entered by mistake,
you can regain access to the existing files on the disk either by
issuing another ACCESS com.and without the ERASE option, or by
issuing a RELEASE com.and for the disk.
Since the ERASE option
does not alter the ftaster File Directory or disk files, but only
specifies that the directory built in virtual storage is to contain
no entries, the original disk files can be recovered as long as
they were not altered. However, if a CftS command is executed which
causes a new file to be written on the disk, the ftaster File
Directory is updated and the files which were on the disk before
the execution of the ACCESS co.mand with the BRASB option are no
longer available. The space previously used for the erased files
is now available for new files.

If the initial ACCESS command
(either explicit or implied)
encounters an error, a message is displayed at the terminal and you
can enter another co.mand; no disk has been accessed at this time.

section 7: Pormat and Usage Rules for CftS Co.mands

ACCESS
5.

The filena.e, filetype and file.ode can only be specified with
disks which are accessed as read-only extensions. Piles with a
mode nu.ber of 0 are not be accessed in this case.

If you have disk addresses 190, 191, 192, and 19E defined in the
V"/370 directory, or if they are defined before you IPL C"S, these
disks are accessed as the S, A, D, and Y disks, respectively. The S
and Y disks are read-only disks.

If you are using ACCESS to access a read-only OS or DOS disk, you
cannot specify the fn, ft, or fm operands, nor can you specify any
options.

A read-only OS or DOS disk cannot be accessed unless
is already accessed, in read/write .ode.

Only one virtual machine at a time
mode.

Command

a C"S A-disk

can access a disk in read/write

Result

ACCESS 192 B

IMakes all files on 192 (which is to become the
IE-disk) availa~le for reading.

AC 192 B/B ABC

IProvides read-only access to all files on the
IB-disk, with a filename of ABC.

ACC 192 B/B ABC*

IProvides read-only access to all files on the
IB-disk whose filenames have ABC as the first
Ithree characters.

ACCE 192 B/B ABC * B2 IProvides read-only access to all files on the
IE-disk that have a filename of ABC and that
lare in read-only mode (mode number of 2).

ACCES 191 A/A

IPlaces the A-disk in read-only mode.

ACCESS 194 D/A

IMakes the D-disk a read-only extension of the
lA-disk. The A-disk must have been accessed
Ibefore this com.and is issued. The effect of
Ithis can be negated by issuing
I ACCESS 194 D

ACC (ROPROP)

IAccesses 191 as the A-disk and does not
lexecute your PROPILE EXEC file if this is the
Ifirst command executed after you load CMS.

AC 191 A (ERASE)

IMakes 191 available as the A disk but builds
Ithe file directory in virtual storage with no
lentries. All'space on the disk becomes availlable for new files, when the execution of a
ICMS co •• and causes the "aster Pile Directory
Ito be updated.

IBM VM/370: Command Language Guide for General Users

ACCESS

DMSACC7231 mode (cuu) R/O [-OS]
The specified disk is attached to the
read-only mode.
When the disk specified
CMS adds the "-OS" to the response.

CMS virtual machine in
is in OS or DOS format,

DMSACC7241 cuul REPLACES mode(cuu2)
Before execution of the command the disk represented by cuu2 was
the "mode" disk. The disk i Guul, is nnv assigned that file~ode
letter. This message is followed by message DMSACC726I.
DMSACC7251 cuu ALSO = 'mode' [-OS]
The disk specified by cuo is the "mode" disk and an ACCESS command
was issued to assign it another filemode letter. When the disk
specified is in OS or DOS format,
CMS adds the -os to the
response.
DMSACC7261 'cuu mode' RELEASED
The disk located at virtual address cuu that is being accessed as a
read/write disk is already currently accessed. The effect of the
previous ACCESS command is canceled and the disk is released from
the virtual machine configuration.

DMSACC002E
DMSACC003E
DMSACC017E
DMSACC048E
DMSA~C059E

DMSACC060E
DMSACCl12S
D5SACC113S
DMSACC230W
DMSACC240S

lILE 'DMSROS TEXT' NOT FOUND RC=28
IRVALID OPTIOR 'option'
RC=24
INVALID DEVICE ADDRESS 'cuu' RC=24
IRVALID MODE 'mode'
RC=24
'cuu' ALREADY ACCESSED AS READ/WRITE 'mode' DISK RC=36
lILE(S) 'fn [ft [fm]]' ROT 10URD. DISK 'mode(cuu), WILL HOT
BE ACCESSED RC=28
DISK 'mode (cuu) , DEVICE ERROR RC=100
mode (cuu) ROT ATTACHED RC=100
OS DISK - lILEID AHD/OR OPTIOHS SPECI1IED ARE IGRORED
ERROR LOADING READ OS ROUTINE 'DMSROS TEXT'

Section 7: Format and Usage Rules for CMS Co •• ands

ASSEftBLE
ASSEMBLE

Use the ASSEftBLE coaaand to invoke the Asseabler to asseable the
specified file. The Assembler processing and output are controlled by
the options selected. The foraat of the lSSEftBLE co •• and is:

Asse.ble

[ (options ••• [) ]]

1!1:!2g!£ I
INOALOGICI
r

IftCALL

11ISI I
I NOLISTI
L

IIjlI lIy'LLl I
IIREF (SHOR T) I
I NOIREF
I
L

...

ITEST

INO!~I
L
.J

I NUftBER I
INONUft I

ISTft! I
INOSTftTI

ITERft!NA1:1
I JOTERft I

...

111:!g! I
INOALIGN I

IBUlSIZE (ftIN) I
IBUlSIZJ lSTDll

IRENT I
I NO,!!ENTI

ILIBftAC I
I].QLI.ID!!f I

I
INORLD I

...

IRL~

I.Qlhl1!£! I
I NOOBJECTI

...

I
I!Oft1:QGI~ I

IDECK I
I.!ODEClSl

11:1!1!~OU! j~~ll
L

I PRINT I
INOPRINTI
I~!.§!
I

ILINECOUN (nn) I

IftLOGIC

I!Q!!~AL1:1
L
...

IFLAG (nnn) I
Illl.§ 1Ql I

I
INOESDI

r
11!~~

...

ISYSPARft (string) I
I SYSPARft (1)
I
I SYSPARft ()
i
L

...

is the filenaae of the source file to be asseabled. The file
ASSBftBLB and
fixed-length,
must
have a
filetype
of
80-character records.

1:!§!!!2 ~Q!1!91: OPTIONS: The list below describes the assembler options
you can use to
the assembler listing. The default values are
underscored.

control

lists
code.
82

conditional

assembly

state.ents

IBft Vft/370: Coaaand Language Guide for General Users

open

ASSEftBLE
BOILOGIC

suppresses the ALOGIC option.
lists the external symbol dictionary (ESD).

NOESD

suppresses the printing of the ESD listing.

FLAG (nnn)

does not include diagnostic ·messages and ftNOTE
messages below severity code nnn in the listing.
Diagnostic messages can have severity codes of 4,
8, 12, 16, or 20 (20 is the most severe); and
ftNOTE severity codes can be between 0 and 255. For
example, FLAG (8) suppresses diagnostic messages
with a severity code of 4 and MNOTE messages with
severity codes of 0 through 7.

~1!~

lQl.

LINECOUN (nn)
LI1!1!~Q!!l! J.2~1

nn specifies the number of lines
page.

to be listed per

produces an assembler listing.
NCLIST

does not produce an assembler listing. This option
overrides ESD, RLD, and XREF.

ftCALL

lists the inner macro instructions encountered
during macro generation following their respective
outer macro instructions. The assembler assigns
statement numbers to these instructions. The ftCALL
option is implied by the ftLOGIC option; NOftCALL
has no effect if ftLOGIC is specified.
suppresses the "CALL option.

"LOGIC

lists all
statements of a
macro definition
processed during macro generation after the macro
instruction. The
assembler assigns
statement
numbers to them.
suppresses the !LOGIC option.
produces the relocation dictionary
listing.

as part of the

NORLD

does not print the relocation directory.

LIBftAC

lists the macro definitions read from the macro
libraries and any assembler statements following
the logical END statement.
The logical END
statement is the first END statement processed
during macro generation. It may appear in a macro
or in open code; it may even be created by
substitution •. The assembler
assigns statement
numbers to the statements that follow the logical
END statement.
section 7: Format and Usage Rules for CftS Commands

ASSB"BLB
suppresses the LIB"AC option.
includes in
the assembler
listing a
cross
reference table of all
symbols used in the
assembly. This includes symbols that are defined
but never referenced. The assembler listing also
contains a cross reference table of literals used
in the assembly.
XRBF (SHORT)

includes in
the assembler
listing a
cross
reference table of all symbols that are referenced
in the assembly.
Any symbols defined but not
referenced are not included in the table. The
assembler listing contains a cross reference table
of literals used in the assembly.

NOXRBF

does not print the cross-reference tables.

PRINT
PR

writes the LISTING file to the printer.

NOPRINT
NCPR

suppresses printing the LISTING file.

~!.§!

places the LISTING file on a virtual disk.

DI
OUTPUT CONTROL OPTIONS: The output control options are
the-Qbject-iodule output of the assembler.
DECK

used to control

writes the object module on the device specified
on the 'ILEDE' statement for PUNCH.
If this
option is specified together with the OJBECT
option, the object module is written both on the
PUNCH and TEXT files.
suppresses the DECK option.
writes the object module on the device specified
in the TEXT 'ILEDE' statement.
If this option is
specified together with the DBCK option, the
object module is written on the two devices
specified in the 'ILEDE' statement for TBXT and
PUNCH.

NOOBJECT
NOOBJ

does not create the object module.

TBST

includes the special source
cards) in the object module.

symbol

Does not produce SY" cards.

IB" V"/370: Command Language Guide for General Users

table

(SY"

ASSE"BLE
SYSTER" OPTIOIS: These
wIth-Jour-assembly.

are used to control the

SYSTER" file associated

writes the line nuaber field (columns 73-80 of the
input records)
in the
SYSTER" listing
for
statements for which diagnostic information is
given. This option is valid only if TER"IBAL is
specified.
BOBU"

suppresses the BU"BER option.
writes the state.ent number
assigned by the
assembler in the SYSTER" listing for statements
for which diagnostic information is given. This
option is valid only if TER"IBAL is specified.

IOST"T

suppresses the ST"T option.
writes the
diagnostic
infor.ation
on
the
SYSTER" data set.
The diagnostic information
consists of the diagnosed statement followed by
the error message issued.

IOTER"

suppresses the TER"IBAL option.

OTHER ASSE"BLER OPTIONS: The options below
functions-an~values-for the assembler.

!1!!H!
!1!H!

." .... ,..,.. '."

"VAJ.,~\:rl'l

BOALGI

BUPSIZE (811)

allow you to specify various

aligns all data on the proper boundary in the
object module; for exa.ple, an P-type constant is
aligned on a fullword boundary. In addition, the
asse.bler checks storage addresses used in machine
instructions for alignment violations.
does not align
data areas other
than those
specified in CCW instructions. The assembler does
not skip bytes to align constants on proper
boundaries.
Alignment
violations in
machine
instructions are not diagnosed.
uses the minimum buffer sizes (790 bytes) for each
of the utility data sets
(SYSUT1, SYSUT2, and
SYSUT3).
Storage normally used for buffers is
allocated to work space.
Because more work space
is available,
more complex programs
can be
assembled in a given virtual 'storage size; but the
speed of the assembly is substantially reduced.
chooses the
buffer size that
gives optimum
performance. The buffer size depends on the amount
of virtual storage. Of the assembler working
storage in excess of minimum requirements, 371 is
allocated to the utility data set buffers and the
rest to .acro generation dictionaries.

Section 7: Pormat and Usage Rules for C"S Commands

ASSEMBLE
RENT

checks your program for a possible violation of
program reenterability.
Code that makes your
program nonreenterable is identified by an error
message.
suppresses the RENT option.

SYSPARM

(string) J
() null
string
{ (1)

'string' is the value assigned to the system
variable symbol &SYSPARM. The varible (string)
cannot be greater than 8 characters.
If you
wish to enter a string of more than 8 characters,
use the SYSPARM (1) format.
with the SYSPARM (1)
form, CMS prompts you with the message:
EITER SYSPARM:
You can enter a string of characters up to the
option limit of 100 characters.
You can also
enter parentheses and embedded blanks from the
terminal.
SYSPARM ()
enters a null string of
characters.

Q!Jjjl~l!~ ~~~

IlLE ~~!!~1~~: When you issue the ASSEMBLE command, there
are default FILEDEF commands issued for assembler data sets.
You may
want to override these with explicit FILEDEF commands. The ddnames most
likely to be overridden are:
ASSEMBLE
TEXT
LISTING
PUNCH
CMSLIB

(SYSIN input to the assembler)
(SISLII output of the assembler)
(SYSPRIRT output of the assembler)
(SYSPUNCH output of the assembler)
(SYSLIB input to the assembler)

The default FILEDEF commands issued by
are:

the assembler for the ddnames

FILEDEF ASSEMBLE DISK fn ASSEMBLE fm (RECFM FB LRECL 80 Block 800
FILEDEF TEXT DISK fn TEXT fm
FILEDEF LISTING DISK fn LISTING fm (RECFM FBA Block 1210
FILEDEF PUNCH PUNCH
FILEDEF CMSLIB DISK CMSLIB MACLIB

(RECFM FB LRECL 80 Block 800

A FILEDEF command, issued for any of the above ddnames prior to
invoking the assembler, overrides the default FILEDEF issued by the
assembler. Assume that there is an assembler source file in card deck
form which you want to assemble. If you have this card deck read into
your virtual machine reader, you must issue an overriding FILEDEF
command prior to assembling, that is, FILEDEF ASSEMBLE READER. Now you
can invoke the assembler as follows:
ASSEMBLE SAMPLE (options • • • •
The name SAMPLE is used by the assembler as the filename for any TEXT
or LISTING files produced by the assembler, provided a file SAMPLE
ASSEMBLE does not exist on any accessed disk, in which case, the first
file is erased.

IBM VM/370: Command Language Guide for General Users

ASSEMBLE

Similarly, if you have a tape containing an assembler input
which you want to assemble, you must issue the following commands:
FILEDEF ASSEMBLE TAPn

file

(RECFM F LRECL 80 BLOCK 80

or, if the file is blocked,
FILEDEF ASSEMBLE TAPn

(RECFM FB LRECL 80 BLOCK 80*n

followed by
ASSEMBLE SAMPLE

(options....

You can use as data sets as CMS files
with the FILEDEF command. For example,

by defining those

data sets

FILEDEF ASSEMBLE DISK MYDSET ASSEMBLE B4 DSN as DATASET

is the mode of as disk to be accessed.

OS.DATASET is the name of the as data set to be used for input.
To assemble this, issue:
ASSEMBLE MYDSET
The same examples used here for input files can be applied to other
ddnames. Care should be taken that any attributes specified for the
file conform to the assembler expected attributes for the device, that
is, PUNCH, LRECL 80 BLOCK 80, TERMINAL 132.

For the messages and return codes associated with the ASSEMBLE command,
see the g~L!~ ~Bg !~LJ1Q !§§~!~1~£ R£9g~~~~~~§ ~~~g~.

section 7: Format and Usage Rules for CMS Commands

GC20-1804-3 Page Modified by TNL GN20-2659
CMSBATCH
CMSBATCH

You use the CMSBATCH command to invoke the
format of the CMSBATCH command is:

CMS Batch

Facility.

The

CMSBATCH

[sysname]

sysname

is the name of the saved system that the CMS Batch Facility
loads for all subsequent batch jobs. This operand can only be
used if the installation has set up the CMS Batch Facility as
a saved system.

You issue this command immediately after loading CMS with the IPL
command. You can find a complete description of the CMS Batch Facility
in "Appendix C: Using the CMS Batch Facility" and in the !lUllQ:
QE~~~lQ£~§ §y~g~.

DMSBTB100E
DMSBTB101E
DMSBTP105E
DMSBTP106E
DMSBTP107E
DMSBTP108E
DMSBTP109E

NO BATCH PROCESSOR AVAILABLE RC=40
BATCH NOT LOADED RC= 88
NO JOB CARD PROVIDED RC=None
JOB CARD FORMAT INVALID RC=None
CP/CMS COMMAND 'command, (device)' NOT ALLOWED
/SET CARD FORMAT INVALID RC=None
CPUIPRINTERIPUNCH LIMIT EXCEEDED RC=None

IBM VM/370: Command Language Guide for General Users

RC=88

COMPARE
COMPARE

Use the COMPARE command to compare two disk files of fixed or variable
length format and to display the contents of corresponding unlike
records at the terminal. The format of the COMPARE command is:
r-

I COMpare I fileid 1 fileid2

[(COL mm-nn[)]]
-J

L-

fileid

is the file identification of the two files to be compared.
All three identifiers
(filename, filetype, and filemode)
must be specified for each fileid.

(COL mm-nn)

defines any contiguous portion of the corresponding
for comparison.
The comparison begins at
position mm of
each record 1n both
files. The
comparison proceeds up to and including position nn of
each record in both files.
If mm is not specified, the
comparison starts with the first character of each
record in both files.
If nn is not specified, the
default ending position is the last character of each
record.
The "_" is required and may not be preceded or
followed by a blank.
IIlrecl ll is the logical record
length of the file.

(~g1 l=!f~~!l records

If you want to stop the displaying
CMS immediate command HT.

of the dissimilar records,

use the

COMPARE ABC lIZ A1 ABC MNO A1
Each record in file ABC lIZ A1 is compared with the corresponding record
in file ABC MNO A1.
Comparison begins at the first position of each
record and proceeds for the entire length of the record. Records which
do not match are displayed at the terminal.
COMPARE MYFILE ASSEMBLE A1 YOURFILE ASSEMBLE A1

(COL 10-72)

positions 10 through 72 of each record in file MYFILE ASSEMBLE A1 are
compared with corresponding positions of each record in file YOURFILE
ASSEMBLE A1. Records in which these positions do not match are displayed
at the terminal.

If corresponding records in each file do not match, the record from the
first file is displayed, followed by the record from the second file.

section 7: Format and Usage Rules for CMS Commands

GC20-1804-3 Page Modified by TNL GN20-2659
COMPARE

DMSCftP002E
DMSCMP003E
DMSCftP005E
DMSCftP009E
DMSCMP010E
DMSCftPOllE
DMSCMP019E
DftSCftP029E
DMSCMP054E
DMSCftP062E
DMSCftPl04S
DftSCftP209W

PILE 'fn [ft [fa]]' NOT POUND RC=28
INVALID OPTION 'option' RC=24
NO 'option' SPECIPIED RC=24
COLUMN 'col' EXCEEDS RECORD LENGTH RC=24
PREMATURE EOP ON PILE ['fn ft [fa']] RC=40
CONPLICTING PILE PORMATS RC=32
IDtNTICAL PILEIDS RC=24
INVALID PARAMETER 'param' IN THE OPTION 'col' FIELD RC=24
INCOMPLETE PILEID SPECIFIED RC=24
INVALID * IN PILEID
RC=20
ERROR Inn' READING FILE 'fn ft fm' PROM DISK RC=100
PILES DO NOT COMPARE RC=4

IBM VM/370: Command Language Guide for General Users

COPYPILE
COPYFILE

Use the COPYPILE co.~and to copy d~ta froll specified input files to the
output files accordlng to converS10ns and specifications indicated by
the options selected. The manner in which the file identifiers are
entered determines whether one output file is created (single output
aode) or aultiple files are created (multiple output mode).
The COPYPILE command is used to:
•
•
•
•

Copy one file to another
Combine two or more files into a single output file
Copy files i~to aultiple output files
Copy a file from one minidisk to another
with the COPYPILE command, you can:

•

Display the naaes of files copied at the terminal.

•

Replace the existing output files with the new output files.

•

Change the record foraat and logical record length.

•

selectively copy records from the input file(s) based on either:
- Record nUllber
- Label field of record

•

Re.ove the trailing fill characters from each record.

•

Compress an input file.

•

Convert 026 key punch characters to corresponding 029 characters.

•

Convert lowercase letters
lowercase.

•

Overlay data
file.

•

Append one file to another file.

•

ftove selected positions within each
the records of another file.

•

Insert a specified charact'er string or hexadecimal character
selected positions of each record in the output file.

•

Perfor. character translations.

in an

~ppercase

existing file

and uppercase

with selected

letters

data from

another

record to specified positions in

section 7: Poraat and Usage Rules for CftS Co •• ands

into

COpy FILE

The format of the COPYPILE cOllmand is:
COPYfile

fileidi 1 [fileidi2 ••• ] [fileido] [ (options ••• [) ]]
~:Etion.§:

IType

IIEWDatel
10LDDatei

I!OT:!~I
L
.J

ITRUnc I
I!QIiy!£1

IPRolI recno
I
IPRLabel xxxxxxxxi

IPRo.!£! I
INOPRollpt I
L

[LRec1 nn]

I PAck I
IUNPackl

[EBcdic]

IPOR recno
I
ITOLabel xxxxxxxxi
.J

IUPcase I
ILOwcase I
L

IREPlacel
10Vly
I
IAPpend I
L

IPIll c I
IPl1l hh I
IPl11 40 I
L

ISPecs

I1!EWPi1~1

[TRAns]

II0S.f~£.§1
L
.J

fi1eidi 1

is the first (or only) input file. Each file identifier
(filename, fi1etype and filemode) must be specified either
by indicating the specific identifier or by coding an
asterisk. However, all three file identifiers of fi1eidil
cannot be specified by asterisks.

fileidi2

is an additional input file(s).
Each file identifier
(filename, fi1etype, and fi1emode) must be specified. In
single output mode, any of the three ,input file identifiers
may be
specified either
by indicating
the specific
identifier or by coding an asterisk.
However, all three
file identifiers
of fi1eidi2 cannot be
specifi~d
by
asterisks.
In multiple output mode, an asterisk 1S an
invalid file identifier. An equal sign (=) may be coded for
any of the file identifiers, indicating that it is the salle
as the corresponding identifier in fi1eidl.

fi1eido

is the output fi1e(s) to be created.
Each file identifier
(filename, filetype and fi1ellode) IIUSt be specified.
To
create multiple output files, an equal sign (=) must be
coded in one or aore of the identifier fields. If there is
only one input fi1eid, fi1eido aay be omitted, in which case
it defaults to - - = (the input file represented by fi1eidil
is replaced).

The following options are the most used options of the COPYPILE
com.and. Binor variations of these options are described in the "Other
Options" section.

IB! V!/370: COIIIRand Language Guide for General Users

COPYFILE

TYPE

displays at
copied.

ROTYPE
-----

suppresses the displaying at the
the files being copied.
uses the
files.

the terminal

current date

the names

of the

files being

terminal the

as the creation

names of

date of

OLDDATE

uses the date en the first input
date of the new files.

RECFt!

is the record format of the output files.
specified, the output record format is the same
of the input.

LRECL nn

is the logical record length of the output file(s) if it
is to be different from that of the input files. The
maximum value of nn is 65535.
displays the messages which
translation lists.

file as

the new

request

the creation

If not
as that-

specification

NOPROt!PT

suppresses the
display of
prompting
specification and translation lists.

FROt! recno

is the starting record number for
copy operation.

messages

or
for

each input file in the

FRLABEL xxxxxxxx
xxxxxxxx is a character sequence which appears at the
beginning of the first record to be copied from each
input file.
up to eight characters may be specified.
The character sequence may not contain embedded blanks.
FOR recno

is the
file.

number of

records to be

copied from

each input

TOLABEL xxxxxxxx
xxxxxxxx is a character sequence which, if at the
beginning of a record, stops the copy operation for that
input file. The record containing the given character is
not copied.
Up to eight characters may be specified.
The character sequence may not contain embedded blanks.

TRUNC

removes trailing
blanks (or fill
characters)
converting to RECFt! V output file record format.

when

The RECFt! and LRECL options can be used to specify the
record format and logical record lengths of the output
files being created.

section 7: Format and Usage Rules for Ct!S Commands

COPYPILB
There are two record formats,
F (fixed) or V (variable).
All records in a fixed record foraat file are the saae
size (for exaaple, card image files, where all records
are 80 bytes long). Variable record format files have
records of varying sizes. SCRIPT files, where the length
of each record is usually different, are variable record
fora at files.
The logical record length (LRBCL) applies only to fixed
record foraat
(F) files.
For exaaple, for card image
files, the logical record length is 80.
If the R!CFB or LRBCL options are not specified, the
record foraat and logical record length for the output
file are the same as for the current or only input file.
If the output file record foraat is V, then the LRBCL
option (if specified) is ignored.
When the output file record format is F, the input
records are truncated or padded, as necessary, to the
logical record length.
When the output file record
foraat is V, the input records are simply copied to the
output file, unless the TRUNC option is specified. If
THUIC and H!CFB V are specified, all blanks at the end of
each record are removed before the record is written
out.
Por information on variations of this option, see
discussion of the FILL option under "other Options."

the

suppresses the removal of trailing blanks (or fill
characters) when converting to RBCFB V output file record
format.
PACK

converts repetitively occurring characters to compressed
foraat. If the FILL option is not used, all occurrences
of two or more blanks in the file are encoded as one
character, and four or more occurrences of any other
character in the file are encoded as three characters.
If a FILL character is specified, that character replaces
the blank as the special packing character, and blanks
are treated as any other non-fill character.
Source files generally take up a great deal of disk
space, because they contain
aany blanks.
This is
particularly wasteful in the case of source files which
are seldoa used.
Use the PACK option of the COPYFILB coamand to encode a
file so that aultiple blanks are represented as a single
character, and multiple occurrences of other characters
also produce space savings.
When the PACK option is used, the output file is in a
foraat which can be decoded only by the UNPACK option of
the COPYPIL! command.
Por exaaple, the co •• and:
COPYPILB

ASS!BBL! A1

(PACK

causes all ASSBftBLB files on the A-disk to be packed.
94

IBB VB/370: Com.and Language Guide for General Users

COPYPILE
If you know that a particular character occurs a great
many times in a file (and if this character occurs more
often than the blank character), specify that character
as the fill character for the file.
Two or more
occurrences of the specified fill character are encoded
as one
character.
Then four or
more consecutive
occurrences of any other character (including the blank)
are encoded as three characters.
However, not every file should be packed. In fact, if
the file does not contain very many occurrences of
multiple characters, it is possible for the packed file
to be longer than the original file.
CAOTIQ!: A file in packed format should not be modified
in any way. If such a file is modified in any way, the
OIPACK routines will be
unable to reconstruct the
original file. Packed files should never be combined or
split.
OIPACK

reverses the PACK operation.

EBCDIC

converts a file that was created with 026 keypunch
characters (BCD), to 029 keypunch characters (EBCDIC) •
The following conversions are made:

< to

)

& to +

"• toto =
(

to •
• to

OPCASE

converts all lowercase characters in each record to be
written to an output file to uppercase before the record
is written out.

LOWCASE

converts all uppercase characters in each record to be
written to an output file to lowercase before the record
is written out.

In addition to the options
offers several variations:

already described, the

COPYPILE co ••and

checks that output files did not previously exist. If
one or more output files do exist, an error message is
displayed and the COPYPILE co.mand terminates.
This
option is the default so that existing files are not
inadvertently destroyed.
RBPLACE

causes the output file to be replaced by an input file of
the same name. REPLACE is the default option when the
output file identification is "= = =."

section 7: Format and Osage Rules for CftS Com.ands

COpy PILE
OYLY

overlays the data in an
froa the input file.

APPEND

appends the data froa the input file to the end of a file
specified by the output file identifiers. If no output
file exists, one is created.

PILL c
PILL hh

is the padding and truncation character or the principal
packing character for the PACK option. The fill character
aay be specified by entering a single character, c, or by
entering a two-digit hexadeciaal representation of a
character.
The
default is
40
(the
hexadeciaal
representation for a blank in EBCDIC).

l!~

existing output file

with data

When the output file record foraat is P, the input
records are truncated or padded, as necessary, to the
logical record length.
The
padding and truncation
character is usually a blank, but this default aay be
overridden if you specify a new padding and truncation
character with the PILL option.
When RECPft Y
end of each
written. To
use the PILL

and TRUIC are specified, all blanks on the
record are reaoved before the record is
truncate some character other than blanks,
option.

The PACK routine treats the blank as a "special packing
character". If desired, the PILL option aay be used to
change the "special packing character" to a non-blank
character.
SPECS

requests a user specification list defining the aanner in
which data is to be copied.
If the SPECS option
proapting message:

used,

COPYPILE

issues

the

DftSCPY601R ENTER SPECIPICATION LIST
The- keyboard
unlocks,
specification list.

and

you

aay

type

the

The format of the specification list is:
source target [source target] •••
where source can be specified in several ways and target
is a deciaal nuaber representing a position in the output
record. Source can be specified as:
•

A pair of coluans of the input file, specified in the
foraat "nn-am", two decimal nuaber values separated by
a hyphen. This foraat causes the specified positions
in the input file record to be copied to the output
file. Por each record that is copied, the value of aa
(the ending record position) is compared to the length
of the record. Whenever the specified ending record
position exceeds the length of the record, the end of
the record becoaes the assumed ending position for
that record.
Por example, the source specification
"23-40" causes coluans 23 through 40 of the input file
record to be copied to the output file.

IBft Yft/370: Coamand Language Guide for General Users

COPYPILE
•

I string of characters, delimited by nonalphaaeric
characters. Such a specification causes the specified
string of characters to be placed in the output file
record.
Por example, a
source specification of
"/lbCd 1234/" causes the string "lbCd 1234" to be placed
in each record of the output tile. The letters in the
string of characters are not automatically raised to
uppercase; if you wish capital letters, you must type
them in as such.

•

I string of characters, specified by the letter "B"
followed by an even number of hexadecimal digits
entered using numeric characters and either upper or
lower case alphabetic characte~s.
Por example, the
specification, "hb7c1ff" causes the characters given
by the hexadecimal values X'B7', X'e1', and X'PP' to
be placed in the output file.

Por example, consider the following specification list:
1-5 10 /IBC/ 3

/XYZ/ 20 BOO 25

This
specification
list
contains
four
sets
of
specifications, and causes data to be placed into the
output record in the following manner: Pirst, positions
1 through 5 of the input record are placed in positions
10 through 14 of the output record. Next, the characters
"IBC" are placed in positions 3 through 5 of the output
record.
Next, the characters
"XYZ" are placed in
positions 20 through 22 of the output record. Pinally,
the character X'OO' is placed in position 25 of the
output record.
Por variable length output files, the length of the
output record is determined by the position of the
rightmost byte of data that was placed in the output
record. Por fixed length output files, the record is
padded or truncated to the logical record length.
Positions of the output record for which no data is
specified are filled with blanks. Use the PILL option to
specify another fill character. In the example shown
above, positions 1-2, 6-9, 15-19 and 23-24 of the output
file record contain blanks. In addition, if the output
record format is P, positions 26 through to the end of
the record contain blanks.
The SPECS option is particularly useful in conjunction
with the OfLY option.
If
these options are used
together, the specification list indicates the exact
positions of the output file record to be overlaid. Por
example, if the specification list 1-10 20 is used with
the OfLY option, then positions 1-10 of each input file
record overlay positions 20-29 of each record of the
existing output file, and the other positions of the
output file records remain unchanged.
The specification list can be continued onto additional
lines by typing '++' at the end of the first line. If
these
two
characters
are
encountered
when
a
source-specification is expected, all scanning of that
line ceases, and the keyboard unlocks so that a new line
may be entered.

Section 7: Pormat and Usage BuIes for CMS Commands

COPYPILE
indicates that no specification list is to be entered.
TRINS

specifies that you are to be asked for a list of
character translations to be made as the file is copied.
The TRINS option allows you to specify your own list of
translations; it overrides any
of the other three
translation options (OPC1SE, LOWC1SE or EBCDIC).
When the TRINS option is specified, the COPYPILE command
displays the prompting message:
DftSCPY602R EITER TR1NSL1TION LIST
You may then enter the translation list.
The translation list consists of a series of pairs of
characters, separated by blanks. Each character may be
specified either by entering the character itself or by
entering a two-digit hexadecimal equivalent (the latter
is particularly useful for characters not available on
your teraina1 keyboard).
Por exaaple, the translation list:

1 fO 00 ff

specifies that the character '*' is to be translated-to
I_I, the character 'I' is to
be translated to X'PO', and
the character X'OO' is to be translated to X'PP'. If the
preceding translation list is specified in conjunction
with the LOWC1SE option, then the translation 'l' to
X'pO' overrides the LOWC1SE translation, 'I' to 'a'.
The translation list can be continued onto additional
lines by typing '++' as the last two characters of the
present line.
Whenever these
two characters
are
encountered when the first character of a character pair
is expected, all scanning of that line ceases,
(for
typewriter terainals, the keyboard unlocks), then a new
line aay be entered.

Pigure 14 shows coabinations of options which should not be specified
together in the same COPYPILB co.aand.
If the option in the first coluan is specified, none
in the second coluan can be coded.
)

IBft Yft/370: Command Language Guide for General Osers

of the options

COPYlILE

Incompatible options

option

LRECL, IEIDATE, IEllILE, OLDDATE, OVLY, PACK, RECP!,
REPLACE, UIPACK
PACK, UIPACK
PACK, TOLABEL, UIPICK
PROB, PACK, UIPACK
PRLABBL, PACK, UIPACK
PACK, UIPACK
APPEID, PACK, UIPACK
APPIID, OLDDATI
APPIID, OVLY, REPLACE
PROBPT
PACK, SPICS, UIPICK
PACK, TRUIC, UIPACK
TYPI
APPIID, IBIDATI
APPEID, IEIPILE, PACK, REPLACE, UIPACK
APPEID, IBCDIC, lOR, PRLABBL, lROB, LOICISE, LRECL,
OfLY, RECPB, SPECS, TOLABEL, TRAIS, TRUIC, UIPACK,
UPCASE
10PROBPT
APPEID, PACK, UIPACK
APPIID, IIIPILI, OfLY
10SPICS, PACK, UIPACK
POR, PACK, UIPACK
PICK, UIPACK
10TRUIC, PACK, UIPICK
10TYPE
APPIID, IBCDIC, lOR, lRLABEL, lROB, LOICASE, LRECL,
OfLY, PACK, RECPB, SPECS, TOLIBEL, TRAIS, TRUIC,
UPCASB
PACK, UIPACK

lPPBID
BBCDIC
lOR
FRLABBL
lROB
LOICASB
LRECL
IBIDATB
IEllILE
10PROBPT
10SPECS
10TRUIC
10TYPE
OLDDATE
OVLY
PACK
PROBPT
RBCPB
RBPLACB
SPECS
TOLIBBL
TRAIS
TRUIC
TYPE
UIPACIC
UPClSE
Figure 14.

COPYPILI option Incompatibilities

COPYPILI OLD PILE A1 III lILE A1
Copies the file OLD PILB A1 to a new file named lEI lILE A1.
COPYPILI

PILB A1 BIG PILI A1

Copies all files with filetype of lILE and filemode of A1 and combines
them into a single output file named BIG lILI A1. If the files A PILE
A1, B PILE A1, and C PILE A1 exist, they are copied to BIG PILE A1 and
are not erased.
COPYPILI OLD

B1 III

= B1

Copies a group of files, each with a filename of OLD and a filemode of
B1, to a new group of files each with a filename of lEI and a filemode
of B1. If the files named OLD IABI B1, OLD BIRTBDA B1, and OLD ADDRBSS
B1 exist, they are copied to files named lEI IABE B1, lEI BIRTBDA B1,
and III ADDRISS B1, respectively.

Section 1: lormat and Usage Rules for CBS Commands

COPY1ILE
COPYPILE I Y 11 P

11 BIG PILE 11

Coabines files X Y 11 and P Q 11
11.

in a single output file naaed BIG PILB

COPYPILI X • 11 = PILI =
Coabines all files with a filenaae of X and a fileaode of 11 in a single
output file naaed X PILI 11.
COPY1ILE X • 11 = T 11 BIG PILE 11
Coabines all files having a filenaae I and fileaode 11 with the file
having a filenaae I, a filetype T, and fileaode 11 to fora a single file
naaed BIG PILE 11. The co.aand
COPYPILI X • 11 = T = BIG PILI =
produces the saae result.
COPYPILB X • 11 P

11 BIG = 11

Co.bines each file with a filenaae of X and a fileaode of 11 with the
file P Q 11 to create a file naaed BIG. 11. One file is created for
each existing file with a filenaae X and file.ode 11.
COPYPILB I • 11 P = 11 BIG = 11
Co.bines each file with a filenaae of I and a fileaode of 11 with a file
with a filenaae of P, a fileaode of 11 and a filetype corresponding to
that of the first input file; to produce a file with a filenaae of BIG,
a corresponding filetype, and a file.ode of 11.
COPYPILI X

* 11

P = = BIG = =

produces the saae result.
COPYPILI BIGIIBB 1 11 XYZ= == =
Copies the file BIGI1BI 1 11 to a file naaed XYZBIGII 11 11.
COPYPILB 1 B 11 C D 11 (PROB 10 POR 25)
Copies 25 records froa file 1 B 11
tenth record of 1 B 11.

to file C D 11,

beginning with the

COPYPILI OLD B 11 IBi B 11 (PRL1BBL BYPROG TOL1BIL PIllS)
Copies records froa file OLD B 11 to Iii B 11, beginning with a record
containing the characters 'BYPROG' and
continues until a record
containing the characters 'PIllS' is encountered.
COPYPILI

ISSBBBLB

(PICK

CODverts all files with a filetype of ISSIBSL! to packed foraat.

100

ISB YB/370: Coaaand Language Guide for General Users

COPYPILE
COPYPILE ftY PILE A1 YOUR PILE A1 (SPECS
Copies the file naaed ftY PILI A1 to a new
aodified according to the specification list.
DftSCPY601B

file naaed YOUR PILE
The aessage

EITIR SPICIPICATIOI LIST

is displayed.
Por exaaple, if you enter the following specification list:
JABC; 3

nnn

IlVV

Positions 1 through 5 of the input record are copied to positions 10
through 14 of the output record, the character string "ABC" is placed in
positions 3 through 5 of the output record, and the character X·OO· is
placed in the first position of the output record. All other positions
in the output record contain blanks unless a PILL character is
specified, in which case the PILL character is placed in all unspecified
posi tions.
COPYPILE OLD PORft A1 NEi PORft A1 (SPECS OVLY
Portions of the existing output file are to be overlaid by portions of
the input record, or by character strings specified in a specification
list.
COPY PILE XYZ TEXT C = = A
Copies a file froa one virtual disk to another.

DftSCPY601R IITIR SPECIPICATION LIST:
This aessage requests the specification list which is to be entered
in conjunction with the SPICS option.
DftSCPY602R ENTER TRANSLATIOI LIST:
This aessage requests the translation list which is
in conjunction with the TRANS option.

to be entered

DftSCPY7211 COpy 'fn ft f.' {TO IAPPIIDI OVLY) 'fn ft f.' {OLDIIEi) PILE
This aessage appears in conjunction with the TYPE option.
indicates the naaes of the input file and output file.

DftSCPY002E
DftSCPY003E
DftSCPY024E
DftSCPY029E
DftSCPY030E

{IIPUTIOVERLAY} PILE 'fn ft f.' NOT POUND RC=28
IIVALID OPTIOI 'option' RC=24
lILE 'fn ft fa' ALREADY EXISTS -- SPECIlY 'REPLACE' RC=28
IIVILID PIRlftlTER 'para' IN THE OPTION 'option' lIELD RC=24
lILE 'fn ft fa' ILRIIDY ICTIVI RC=28
section 7: loraat and Usage Rules for CftS Co•• ands

101

COpy FILE
DftSCPY037E
DftSCPY042E
DftSCPY048E
Dft SC PY054 E
DftSCPY062E
DftSCPY063E
DftSCPY064E
DftSCPY065E
DftSCPY066E
DftSCPY067E
DftSCPY068E
DftSCPY101S
DftSCPY102S
DftSCPY103S
DftSCPY156E
DftSCPY157E
D8SCPY172E
DftSCPY173E
DftSCPY901T
DftSCPY903T
DftSCPY904T

102

DISK '.ode' IS READ/ONLY RC=36
liO lILEID[ (S) ] SPECIFIED RC=24
INVALID ftODE '.ode' RC=24
lliC08PLETE FILEID 'fn [ft'] SPECIFIED RC=24
INVALID CHAR '[=I*lchar]' IN FILEID '[fn ft f.]' RC=20
liO {TRAISLATIONISPECIFICATION} LIST ENTERED RC=40
INVALID [TRANSLATE] SPECIFICATION AT OR NEAR
RC=24
'option' OPTION SPECIFIED TWICE RC=24
'option' AND 'option' ARE CONFLICTING OPTIONS RC=24
COftBINED INPUT FILES ILLEGAL WITH PACK OR UNPACK OPT lOIS
RC=24
INPUT FILE 'fn ft f.' NOT IN PACKED FORftAT RC=32
'SPECS' TEftP STRIIG STORAGE EXHAUSTED AT •••••••••• RC=88
TOO ftANY FILEIDS RC=88
liU8BER OF SPECS EXCEEDS ftAX 20 RC=88
'FROft nnn' NOT lOUND --FILE 'fn ft f.' HAS ONLY 'nnn' RECORDS
RC=32
LABEL 'label' NOT FOUND IN FILE 'fn ft f.' RC=32
TO LABEL 'label' {EQUALSI IS AN INITIAL SUBSTRING Ol} FRLABEL
'label' RC=24
liO RECORDS WERE COPIED TO OUTPUT FILE 'fn ft f.' RC=40
UNEXPECTED ERROR AT 'addr': PLIST 'plist' AT 'addr', BASE
'addr', RC Inn' RC=256
IftPOSSIBLE PHASE CODE 'hh' RC=256
UNEXPECTED UNPACK ERROR AT 'addr', BASE 'addr' RC=256

IBft Vft/370: Co •• and Language Guide for General Users

CP
CP

Use the CP command to transmit co •• ands to the Vft/370 control program
environment without leaving the CftS environment. The for.at of the CP
cO!l!land is:

[ commandline ]

commandline

is any CP co •• and permitted for your CP co.mand privilege
class. If this field is omitted, you are placed in CP
.ode and may enter CP com.ands without preceding each
co.mand with CP.
To return to CftS issue the CP com.and
BEGII.

111 responses are from the CP command which was issued.

CP TERMIIAL LIIESIZE 80
The TERMIIAL command is passed to the control program for processing.

section 7: Format and Usage Rules for CftS Co.mands

103

DDR

DDR
Use the DASD Du.p Restore (DDR)
service prograa to dump, restore, copy,
or print Vft/310 user ainidisks. The DDR program may run as a standalone
program, or under CftS via the DDR co •• and.
The DDR progra. has five functions:
1.

Dumps part or all of the data from a DASD device to tape.

Transfers data fro. tapes created by the DDR DUftP function to a
direct access device. The direct access device must be the same as
that which originally contained the data.

Copies data from one device to another of the same type. Data may
be reordered, by cylinder, when copied from disk to disk. In order
to copy one tape to another, the original tape must have been
created by the DDR DUftP function.

Prints selected parts of DASD and tape records
EBCDIC on the virtual printer.

Displays selected parts of DASD and tape records in hexadecimal and
EBCDIC on the terminal.

Note: To generate the Vft/310 starter system from the
the standalone RESTORE function must be used.

in hexadecimal and

distributio~

tape,

The format of the DDR co.mand is:

DDR

r
,
[filename [filetype I filemode I

filename filetype [filemode]

]]

is
the
identification of
the
file
containing the control statements for the
DDR program. If no file identification is
provided, the DDR program attempts to
obtain
control
statements
from
the
console. The filemode defaults to
if a
value is not provided.

!~te:

If you use the CftS DDR command, CMS ignores the SYSPRINT control
statement and directs the output to the CftS printer OOE.

DDR CONTROL STATEMENTS
Control statements describe the intended processing and the needed I/O
devices. I/O definition statements must be specified first.
All control statements may be entered from either the console or the
card reader. Only colu.ns 1 to 11 are inspected by the program. All
data after the last operand in a statement is ignored.
An output tape
must have the DASD cylinder header records in ascending sequences;
therefore, the extents must be entered in sequence by cylinder. Only
104

IBM VM/310: Co •• and Language Guide for General Users

DDR
one type of function - du.p, restore, or copy - may be performed in one
execution, but up to 20 statements describing cylinder extents may be
entered. The function statements are delimited by an input or output
statement, or by a null line if the console is used for input. If
additional functions are to be performed. the seauence of certain
control cards must be repeated.- Only those statements needed to
redefine the I/O devices are necessary for subsequent steps. All ot~er
I/O definitions remain the same.
To return to CftS, enter a null line (carriage return) in response to
the prompting message (EITER:). To return directly to CP, key in ICP.
The PRINT and TYPE statements work differently from other DDR control
statements in that they operate on only one data extent at a time. If
the input is from a tape created by the dump function, it must be
positioned at the header record for each step. The PRINT and TYPE
statements have an implied output of either the console (TYPB) or system
printer (PRINT). Therefore, PRINT and TYPE statements need not be
delimited by an input or output statement.

I/O DEFINITION STATEftENTS
The I/O definition statements describe the tape, DASD, and
devices used while executing the DASD Du.p Restore program.

An INPUT or OUTPUT statement describes each
The format of the INPUT/OUTPUT statement is:

INput
OUTput

cuu

type

unit used.

Ivolserl
laltapel
L

.Q~ti2~~:
r
,

tape and DASD

printer

[(options ••• )]

ISKip nnl IftOde 62501 IREWindl
la!iR Q I IBOde 16001 IUNl2!~1
L
J IftOde
8001 ILEave I
L

INPUT

indicates that the device described is an input device.

OUTPUT

indicates that the device described is an output device.

cuu

is the unit address of the device.

type

is the device type (2314, 2319, 3330, 3330-11, 3340-35,
3340-70, 2305-1, 2305-2, 2400, 2420, or 3420) (no 7-track
support for any tape devices). specify a 3410 device as a
3420, a 3340-70P as a 3340-70, and a 3333 as a 3330.
section 7: Format and Usage Rules for CftS Commands

105

DDR
The DASD Dump Restore (DDR) program, running in a
virtual machine, uses
I/O DIAGIOSE 20 to
perf ora I/O
operations on tape and DASD devices. DDR under CftS requires
that the device type entered agree with the device type of the
real device as recognized by Vft/310. If there is a conflict
with device types, the following message is issued:

!~!~:

I
I
I
I
I
I

DftKDDR101E IIVALID OPTIOI
However, if DDR runs standalone in a virtual aachine, DDR uses
DIAGIOSE 20 to perform the I/O operation if the device types
agree and SIO if the device types do not agree.
volser

is the volume serial number of a DASD device. If the keyword
'SCRATCH' is specified instead of the voluae serial number, no
label verification is performed.

altape

is the address of an alternate tape drive.
If multiple reels of tape are required and "altape" is
not specified, DDR types the following at the end of the reel:
"END OF VOLUftE CYL xxx HD xxx, ftOUNT ftOUNT NEXT TAPE." After
the new tape is mounted, DDR continues automatically.

Noj:~:

SKIP nn
Q

forward spaces nn files on the tape. nn is any nuaber up to
255. The SKIP option is reset to zero after the tape has been
posi tioned •

ftODE 6250 causes all output tapes that are opened for the first tiae
ftODE 1600 and at the load point to be written or read in the specified
ftODE 800 density. All subsequent tapes aounted are also set to the
specified density. If no mode option is specified, then no
mode set is performed and the density setting reaains as it
previously was.
REWIRD

rewinds the tape at the end of a function.

UILOAD

rewinds and unloads the tape at the end of a function.

LEAVE

leaves the tape positioned
of a function.

at the end of the file

at the end

Use the SYSPRIIT control statement (in the standalone application only)
to describe the printer that is to print data extents specified by the
PRIRT statement. It also can print a map of the cylinder extents froa
the DUftP, RESTORE, or COpy stateaent. If the SYSPRINT state.ent is not
provided, the printer assignment defaults to OOE.
CftS ignores the
SYSPRINT statement when you invoke DDR as a coaaand under CftS, and CftS
always directs the output to OOE.
The for.at of the SYSPRIIT control
statement is:
SYsprint

cuu

.!~:

cuu
106

specifies the unit address of the device.
IBft Vft/310: Command Language Guide for General Users

DDR

The function statements tell the DDR program what action to perform.
The function commands also describe the extents to be dumped, copied, or
restored. The format of the DUnP/COPYjRESTORE control statement is:

DUmp
COpy
RBstore

Icyl1 [To]
ICPvol

!lL!

[cyl2 [Reorder] [To] [cyI3]] I
I
I
I

IBUcleus

DUMP

requests the program to move data from a direct access volume
onto a magnetic tape or tapes. The data is moved cylinder by
cylinder. Any number of cylinders may be moved. The format
of the resulting tape is:
Record

descrIbing

a
volume header
the volumes.

record,

consisting

data

Record 2: a track header record, consisting of a list of count
to restore the track, and the number of data records
written on tape. After the last count field the record
contains key and data records to fill the 4K buffer.

fields

3: track
records -packed
truncated.

~~£QIg

Record

data
into

records, consisting of
blocks,
with the

key and data
last record

either the end-of-volume or end-of-job trailer
The end volume label contains the same information as
the next volume header record except that the ID field
contains EOV. The end-of-job trailer label contains the same
information as record 1 except that the cylinder number field
contains the disk address of the last record on tape and the
ID field contains EOJ.

label:

COpy

requests the program to copy data from one device to another
device of the same or equivalent type. Data may be recorded
on a cylinder basis from input device to output device. A
tape-to-tape copy can be accomplished only with data dumped by
this program.

RESTORE

requests the program to return data that has been dumped by
this program. Data can be restored only to a DASD volume of
the same or equivalent device type as it was dumped from. It
is possible to dump from a real disk and restore to a minidisk
as long as the device types are the same.

cyll [TO] [cyl2 [REORDER] [TO] [cyI3]]
Only those cylinders specified are moved, starting with the
first track of the first cylinder (cyll), and ending with the
last track of the second cylinder (cyI2). The REORDER operand
causes the output to be reordered, starting at the specified
cylinder (cyI3) or at the starting cylinder (cyll) if "cyI3"
is not specified.
The REORDER operand must not be specified
Section 7: Pormat and Usage Rules for CMS Commands

107

DDR
unless specified limits are defined for the operation; the
starting and, if required, ending cylinders (cyl1 and cyl2)
must be specified.
CPVOL

specifies that cylinder 0 and all active directory and
permanent disk space are to be copied, dumped, or restored.
This indicates that both source and target disk must be in CP
format, that is, the CP Pormat/Allocate service program must
have formatted them.

ALL

specifies that
cylinders.

BUCLEUS

specifies that record 2 on cylinder 0, track 0 and the nucleus
cylinders will be dumped, copied, or restored.

the

operation

is to

performed

all

Re2!rictiQ!§:
1.

Each track must contain a valid home address,
cylinder and track location.

Record zero must
characters.

Plagged tracks are treated just as any other track for all 2314,
2319, and 2305 devices. That is, no attempt is made to substitute
the alternate track data when a defective primary track is read.
In addition, tracks are not inspected to determine whether they
were
previously flagged
when
written.
Therefore,
volumes
containing flagged tracks should be restored to the same cylinders
of the volume from which they were dumped. The message DftKDDR115E
occurs each time a defective track is dumped, copied or restored,
and the operation continues.

Plagged tracks for a 3330 device are handled automatically by the
control unit and may never be detected by the program. The program
may detect a flagged track if, for example, no alternate track is
assigned to the defective primary track. If a flagged track is
detected by the program, message
DBKDDR115E occurs and the
operation terminates.

not

contain aore

than

containing the real

eight

key and/or

data

IIPUT 191 3330 SYSRES
OUTPUT 180 2400 181 (BODE 800
SYSPRIIT OOP
DUBP CPVOL
IIPUT 130 3330 BIII01
DUBP 1 TO 50 REORDER 51
60 10 101
This example sets the density to 800 bpi, then dumps all pertinent
data froa the voluae labeled 'SYSRES' onto the tape that is mounted on
unit 180. If the program runs out of room on the first tape, it
continues dumping onto the alternate device (181). While dumping, a aap
of the dumped cylinders is printed on unit OOP. When the first function
is coaplete, the volume labeled 'BIBI01' is dumped onto a new tape. Its
108

ISB VB/310: Command Language Guide for General Users

DDR
cylinder header records are labeled 51 to 100. 1 map of the duaped
cylinders is printed on unit 001. lext, cylinders 60 to 70 are duaped
and labeled 101 to 111.
This extent is added to the cylinder aap on
unit OOP. When the DDR processing is coaplete, the tapes are unloaded
and the prograa stops.
If cylinder extents are being defined froa the console, the following
is displayed:
EITER CYLIIDER EXTENTS
EITER:
Por any extent after the first extent, the aessage
EITER IEIT BITBIT OR lULL LIIB
BITER:
is displayed.
You aay then enter additional extents to be duaped, restored,
copied. 1 null line causes the job step to start.

Use the PRIIT and TYPE function stateaent to print or type (display) a
hexadeciaal and BBCDIC translation of each record specified. The input
device aust be defined as direct access or tape. The output is directed
to the system console for the TYPB function, or to the SYSPRIIT device
for the PRIIT function. (This does not cause redefinition of the output
unit definition.) The foraat of the PRIIT/TYPB control stateaent is:

PRint
TYpe

cyll [hh 1 [rr 1]]

[TO cy12 [hh2 [rr2 ]]]

QptiOiiS:
[ Hex] [ Graphic]

[(options)]

[ Count]

I
I
I
,I

where:
cyl1

is the starting cylinder.

hh1

is the starting track. If present, it
operand. The default is track zero.

rr1

is the starting record. If present, it aust follow the hh1
operand. The default is hoae address and record zero.

aust follow

the cy11

[TO] cy12 is the ending cylinder.
If aore than 1 cylinder is
printed or typed "TO cy12" aust be specified.
hh2

is the ending
operand.
The
cylinder.

rr2

is the record ID of the last record to print.
the last record on the ending track.

to be

track. If present, it aust follow the cy12
default is the last track on the ending
The default is

Section 7: Poraat and Usage Rules for CftS Coaaands

109

DDR
QRtion§:
HEI

prints or displays a hexadeciaa1 representation of each record
specified.

GRAPHIC

prints or
specified.

displays

COUIT

prints or
specified.

displays only

an EBCDIC
the

translation
count

each

record

field for

each

record

PRIIT 0 TO 3
Prints all of the records from cylinders 0, 1, 2, and 3.
PBIIT 0 1 3
Prints only one record, from cylinder 0, track 1, record 3.
PRIIT 1 10 3 TO 1 15 4
Prints all records starting with cylinder 1, track 10, record 3,
and ending with cylinder 1, track 15, record 4.
The example in Figure 15 shows the information displayed at the
console (TYPE function) or system printer (PRINT function) by the DDR
program. The listing is annotated to describe soae of the data fields.

Responses

DftKDDR711R

YOLID BEAD IS vo1id2 [NOT vo1id1]
DO YOU WISH TO COITIIUE? RESPOID YES 10 OR RERBAD:

vo1id2

is the volume serial number from
DASD unit.

vo1id1

is the volume
control card.

serial number

the YOL1 label

from the

IIPUT or

on the
OUTPUT

The volume serial number read from the device at cuu is not the
same as that specified on the IIPUT or OUTPUT control card.
DftKDDR716R

vo1ser

NO YOLl LABBL FOUID FOR volser
DO YOU WISH TO CO.TIIUE? RESPOND YES NO OR RBREAD:

is the volume serial number of the DASD
INPUT or the OUTPUT control card.

device from the

The DASD device at cuu contains no volume serial number.

110

ISft Yft/370: Command Language Guide for General Users

DDR

Home Address
Record 0
Data
(hexadecimal)

Home Address of track
in hexadecimal format

Record 1 - + - _ -

'CYL 019 HD 00 REe 001'eOUNT 0013000001'

~----Cylinder, head, and
record numbers in
decimal

7rth;-cta;a

•

l~h ~ is : ; z e : -

A heading is printed containing the
data length from the count field first in
decimal, then in hexadecimal
• The data is the_ n_ printed in hexadecimal
with graphic interpret,tion to the right
L,/- ~ts~nhere). _ _ _

Record ID
(hexadecimal)

~
_---------?
Ii

I
I

04096 1000 DATA LENGnl ......

00000 0000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
SUPPRESSED CHARACTERS SAME AS ABOVE ...

1st Halfof-+---_CYL 019.HD 00 REC 002 COUNT 0013000002 00 09A8
Record 2
02472 09A8 DATA LENGTH

Note: Data Length field repeated
in heading.

00000 0000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
SUPPRESSED CHARACTERS SAME AS ABOVE ...
ABOVE RECORD WRITTEN USING RECORD OVERFLOW

r::;--------,

This statement indicates that this portion
of Record 2 was written using the Write
Special Count, Key, and Data command. The
remainder of Record 2 is found on the next
track as the first record after Record O.

I
I

L _ _ _ _ _ _ ...J
Home Address+---_ CYL 019 HD 01 HOME ADDRESS 0000130001 RECORD ZERO 0013000100 00 0008 00000000 00000000
Record 0
CYL 019 HD 01 REC 002 COUNT 0013000102 00 0658-'-----------------~
2nd Half of
Record 2
01624 0658 DATA LENGTH
00000 0000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
SUPPRESSED CHARACTERS SAME AS ABOVE ...

~----------..,

I
G
Record 3

--t----- CYL

019 HD 01 REC 003 COUNT 0013000103

If the key length field is not zero

e A he2cting is printf>d ront,ining the key length

•

;JT
/;

first in decimal, then in hexadecimal.
The key is then printed in hexadecimal with
graphic interpretatIon to the nght(not shown here).

________

800F80

!
I
...1

•

00128 0080 KEY LENGTH - ' - - - - - - - - -

00000 0000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
SUPPRESSED CHARACTERS SAM6 AS ABOVE ...
03968 OF80 DATA LENGTH
00000 0000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000
SUPPRESSED CHARACTERS SAME AS ABOVE ...
Record 4 --t---- CYL 019 HD 01 REC 004 COUNT 0013000104 000000
END OF FILE RECORD

r::;--------,

~
II
L

Figure 15. An Annotated Sa.ple of output fro.
Functions of the DDR Program

Whenever the data length field is zero
an end-of-file prints next.

_ _ _ _ _ _ _ .J

the

TYPB

and

section 7: Poraat and Usage Rules for CftS Co ••ands

111

DDR
DftKDDR717R

DATA DOftPED FROft volidl TO BE RESTORED TO volid2
DO YOO WISH TO COITIBOE1 RESPOID YES NO OR REREAD:

volidl

is the volume serial number
record (volu.e du.ped) •

from the input

tape header

volid2

is the volume serial number from the output DASD device.

The above aessage is printed to verify the input parameters.
EITER CYLIRDER EXTEITS
EITER:
This message is
terminal.

received only if you are entering

input from your

EID OF VOLOftE CYL III HD II, ftOOIT IEXT TAPE
DDR continues processing,
reel.

volser

after

the mounting

the neIt

tape

is the volume serial nuaber of the disk dumped.

The RESTORE operation has begun.
COPYING volser

volser

is the volume serial number described by the input unit.

The COpy operation has begun.
DOftPIIG volser
.!h!!!:

volser

is the voluae serial number described by the input unit.

The dumping operation has begun.
PRIBTING volser

volser

is the volume serial number described by the input unit.

The PRIIT operation has begun.
EID OF DOftP
The DO!P operation has ended.

112

IBft Vft/370: Com.and Language Guide for General Users

DDR
END OF RESTORE
The RESTORE operation has ended.
END OF COpy
The COFY operation has ended.
END OF PRINT
The PRINT operation has ended.
END OF JOB
All specified operations have completed.'
ENTER:
Prompts input from the terminal.
A null line (Enter key or
equivalent) causes control to return to CMS, if the virtual machine
is in the CMS environment.

Section 7: Format and Usage Rules for CMS Commands

113

GC20-1804-3 Page Modified by TNL GN20-2659
DEBUG
DEBUG

Use the DEBUG command to acquire online facilities for debugging
programs running under CMS and to acquire an entry in CMS for handling
external interrupts, program interrupts, and unrecoverable errors. The
subcommands which may be issued in the DEBUG environment allow you to
examine and change the contents of certain control words and registers
as well as portions of virtual storage.
The facilities of DEBUG are
made available when:
•

The DEBUG command is issued

•

An external interrupt occurs

•

A break point
(instruction address stop)
is encountered
program execution; this causes a program interrupt.

during

Once the DEBUG environment has been entered due to any of the above
circumstances, you are in the DEBUG environment.
Only DEBUG subcommands
are valid input in this environment.
When the DEBUG environment is entered,
the contents of all general
registers, the channel status word, and the channel address word are
saved so they may be examined and changed before being restored when
leaving the DEBUG environment.
If DEBUG is entered via an interrupt,
the old program status word for that interrupt is also saved.
If DEBUG
is the first command entered after an ABEND occurs, the contents of all
general registers, the CSW, the CAW, and the old PSW are available from
the time of the ABEND.
The format of the DEBUG command is:

------------------------,I

r-----

IL-______
DEBUG __

The CMS commands HB, HO, HT, RO,
the DEBUG environment.

The floating-point registers
DEBUG environment.

RT and SO are

not recognized in

cannot be examined or

changed in the

None.
~]]~2 2Q]£Q~~!M~2:

For a complete description of
refer to the !~LJ1Q: §~§!~~ g!29!~!!~!~§ ~YiQ~.
the DEBUG subcommands.

114

the DEBUG subcommands
Figure 16 summarizes

IBM VM/370: Command Language Guide for General Users

DEBUG

Subcommand Pormat

Punction

BReak id {SymbOl}
hexloc

Istops program execution at the
Ispecified breakpoint.

CIW

IDisplays the contents of the
IChannel lddress Word at the ti.e
IDEBUG vas entered.

CSW

IDisplays the contents of the
IChannel status Word at the ti.e
IDEBUG vas entered.
r

DEPine symbol hexloc I n I
I .! I
L

.J.J

DUmp I symboll ISYllbol211 [ident]
Ihexloc1 Ihexloc211
I
I
* II
r

IDu.ps the contents of specified
Ivirtual storage locations to the
Ivirtual spooled printer.
I
I
IReturns to the CftS environment and
Istarts execution at the specified
Ilocation.
I

GO Isymboll
I hexlocl
L

IAssigns a symbolic name to the
Ivirtual storage address.
I
I

GPR regl [reg2]

IDisplays the contents of the
Ispecified general registers.

IReturns to the CftS cOII.and enviIron.ent.
r

ISpecifies the base address to be
ladded to locations specified in
lother DEBUG subco.mands.
I

ORigin Isymboll
Ihexlocl
L

iDisplays the contents of the old
IProgram status Word.
IExits froll DEBUG environ.ent to
Ithe CftS co •• and environment.

RETurn
SET {CIW
CSW
PSW
GPR

hexinfo
\
hexinfo [hexinfo]
hexinfo [hexinfo]
reg hexinfo [hexinfo]

STore {SymbOl} hexinfo
hexloc
r

I {SymbOl} I n I
hexloc I.! I
L

Pigure 16.

IChanges the contents of specified
Ilocations or registers.
I
I
IStores information in a specified
Ivirtual stbrage location.
IExamines virtual storage locaItions.
I
I

Summary of DEBUG Subcommands

section 7: Pormat and Usage Rules for CftS COII.ands

115

DISK
DISK

Use the DISK command to:

•

Punch disk files to the virtual spooled card punch in a special
format which allows the punched deck to be restored to disk in the
form of the original disk file.

•

Restore punched
file.

decks created

by the

DISK DUMP

command to

a disk

The format of the DISK comaand is:

DISK

DUMP
{ LOAD

fn ft [fa]

}

I
I
I

DUMP fn ft fm indicates that the specified file (fn ft fa)
is to be
punched.
The
file
may
have
either
fixed
or
variable-length records.
After all data is punched, an
end-of-file card is created with an N in column 5. This
card contains directory information, and must remain in
the deck. The original disk file is retained.
LOAD

indicates that one or more card files are to be read from
the spooled card reader and written as CMS files on disk.
The DISK LOAD operation reads a card deck consisting of
any number of logical decks previously punched by DISK
DUMP. The file designations are obtained from the card
stream. If a file exists with the same designation as one
of those in the card stream, it is erased and replaced.
DISK LOAD loads files onto the primary read/write disk.

DISK DUMP MIPILE OLD A1
The specified file, MIFILE OLD Al, is written to the
punch and followed by an end-of-file card.

virtual spooled

DISK LOAD
All files which were previously read into the virtual card reader are to
be loaded onto disk; each file must be followed by an end-of-file card
as created by the DISK DUMP function.

There is no response to the DISK DUMP command. The file identifiers of
each file loaded is the response for the DISK LOAD command:
fn ft fm

116

IBM VM/370: Command Language Guide for General Users

DISK

DMSDSK002E
DMSDSK009E
DMSDSK014E
DMSDSK037E
DMSDSK047E
DMSDSK048E
DMSDSK054E
DMSDSK062E
DMSDSK070E
DMSDSK077E
DMSDSK078E
DMSDSK104S
DMSDSK105S
DMSDSK118S
DMSDSK124S
DMSDSK205W

FILE 'fn ft fm' NOT FOUND RC=28
COLUMN 'col' EXCEEDS RECORD LENGTH RC=24
INVALID FUNCTION 'function' RC=24
DISK 'mode' IS READ/ONLY RC=36
NO FUNCTION SPECIFIED RC=24
INVALID MODE 'mode' RC=24
INCOMPLETE FILEID SPECIFIED RC=24
INVALID * IN FILEID ['fn ft fm'] RC=20
INVALID PARAMETER 'param' RC=24
END CARD MISSING FROM INPUT DECK RC=32
INVALID CARD IN INPUT DECK RC=32
ERROR Inn' READING FILE 'fn ft fm' FROM DISK RC=100
ERROR Inn' WRITING FILE 'fn ft fm' ON DISK RC=100
ERROR PUNCHING FILE RC=100
ERROR READING CARD FILE RC=100
READER EMPTY OR NOT READY RC=8

section 7: Format and Usage Rules for CMS Commands

117

GC20-1804-3 Page Modified by TIL GH20-2659
EDIT

EDIT
Use the C"S Editor to:
•

Create, froa the terminal, sequential
fixed or variable length records.

files

consisting of

•

Provide, on the basis of certain known filetypes, automatic selection
of record length, record foraat, logical tab settings, serialization,
linemode, and lowercase to uppercase translation.

•

Add, delete, or change any part of a CftS file.

•

Extract all or part
it in another file.

•

Allow searching and changing of portions of the file through
context-directed searches or by using a specific line number.

•

Receive automatic prompting with line numbers.

•

Allow any or all of the file to be displayed at your terminal.

•

Provide an interface to the CftS EXEC interpreter to provide a macro
facility.
Refer to the !~Ll1Q: IQ!% QYigg for a complete description
of the macro facility.

of a CftS file to create a new

either

file, or to embed

The format of the EDIT command is:
r

I Edit
I
I
I
I

fn ft [fa]

[(options ••• [)]]

QE!iQ!!§:

[LRECL nn]
[NODISP ]

fn ft

is the filename and filetype of the file to be created or
edited. If a file with the specified filename and filetype
does not exist, the CftS Editor assumes that you want a new
file created, and after the input environment is entered,
information entered by you becomes input to that file. If a
file with the same filename and filetype does exist, the
EDIT environment is entered, enabling you to issue EDIT
subcoamands and to modify the specified file.
Both the
filename and filetype must be specified.

is the filemode of the file to be created or edited. If the
filemode is specified, EDIT searches only the indicated
disk. If the filemode is specified as an asterisk, EDIT
searches all disks for the existence of that file.
If the
filemode is not specified, only the primary disk and its
extensions are searched.
If the file is found, its mode is
saved, and EDIT later writes the altered file back to that
same disk.
If an existing file is not found, the newly
created file is placed on the disk specified by the filemode
or on the primary disk.

118

IBft Vft/370: Command Language Guide for General Users

GC20-1804-3 Page Modified by TNl GN20-2659
EDIT

lRECl nn

is the record length of the file to be created or
edited.
If the record length
is not specified, the
following default values are assumed:

Existing record length is kept regardless of format.

variable for.at:
Filetype lISTING
121 maximum
Filetype SCRIPT:
132 maximum
Filetype FREEFORT:
81 maximum
Fixed format:
All filetypes:

The maximum record length supported
characters.
NODISP

by the Editor is 160

forces a display terminal into lINE
(typewriter) mode.
When the HODISP option is in effect, all subco.mands that
are solely for control of display terminals (BACKWARD,
CHANGE with no operands, FORWARD, and SCROLl(UP»
are
made invalid for the EDIT session.
This option is used when an EDIT session is initialized
from a local 3270 terminal and the typewriter mode is
desired.
The default mode of operation for an EDIT
session is DISPLAY for a local 3270 and lINE for a remote
3270.
The mode of operation for either terminal can be changed
during the session via the FORMAT subcommand and the
DISPLAY or lINE operand, unless the NODISP option is in
effect.

section 7: Format and Usage Rules for CftS Commands

119

GC20-1804-3 Page

by TNL GN20-2659

~odified

EDIT

Refer to the !!L]l~: ~~!1 §y!gg for a functional description of each of
the EDIT subcoamands. The formats are given in Pigure 17 for reference
only.
Subcoaaand Pormat

Punction

ALter {parm 1} {parm2} I n r
, I
I * I G I I
I .1 I * I I
L

.J.J

IAutomatically saves the file
Ion disk after the indicated
Inumber of lines have been
Iprocessed.

AUTOsa ve {n }
OPP

IPoints the current line
IPointer to a line above the
Iline currently pointed to.
I (Por display terminals.)

BAckward I 11
I nI
L

Bottom
r

I~akes the last line of the
Ifile the current line.

IIndicates whether translation
Ito uppercase is to be done, or
Idisplays the current status.

CASE I U I
I M I
L

IScans the next ~ records of
Ithe file, altering the speciIfied parameter, either once in
leach line or for all occurIrences in the line.

I
r

Change /string1/string21/ I n r
I 1.1 I
I
I * I
L

IChanges string1 to string2 for
"
,1 I I~ records or to EOP, either
III Ifor the first occurrence in
III leach line or for all
.J.J.J
loccurrences.

L-

Figure 17.

120

Summary of EDIT Subcommands and

~acros

(Part 1 of 5)

IBM VM/370: Command Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659
EDIT

Subcommand Format

Function
IEnters CMS subset command
I mode.

CMS

IDeletes B lines or to the end

DELete ! n !
I 1 I
I * I

lof the file

(*).

IPoints to the Bth line from
lthe current line.
I

DOwn I n I
I 1 I
I

DString /string [I]

Ideletes all lines from the
Icurrent line down to the line
Icontaining the indicated
Istring.

FILE [fn [ft [fm]]]

ISaves the file being edited on
Idisk or changes its identiIfiers. Returns to CMS.

Find [line]

ISearches the file for the
Igiven line.

FMode [fm]

IResets or displays the
Ifilemode.

FName [fn]

IResets or displays the
Ifilename.

FORMat {DISPLAY}
LINE

Iswitches the 3270 terminal
Ibetween DISPLAY mode and LINE
I mode.

IPoints the current line
Ipointer to a line currently
Ipointed to. (For display
Iterminals.

FOrward I 1 I
I n I
L

JJJJ

Getfile fn I ft I fm I min I I I I
I * I * I 1 I * I I I I
r

IExpands text into line images
lor displays current settings.

IMAGE ION
I
IOFF I
ICANONI
L

I
I
I

IInserts 'line' in the file or
lenters INPUT mode.

Input [line]
r

IInserts some, or all, of the
Igiven file following the curIrent line.
I

LINEmode ILeft I
IRightl
IOFF I

ISets or displays current line
Isetting.
I
I
I

L---__________ _______________________________________.___________
l

Figure 17.

Summary of EDIT Subcommands and Macros (Part 2 of 5)
section 7: Format and Usage Rules for CMS Commands

120.1

EDIT

r------

Subco.aand Format

Function

Locate Istring [I]

IScans file froll next line for
Ifirst occurrence of 'string'.

LONG

IEnters LONG error message
;mode.

I
I

I
I
r,
I Next I n I
!
! 1 I
L.J
I
I
I Overlay line
I
I
I PREserve

IPoints to the nth line down
Ifrom the current line.
I
I
IReplaces all or part of the
Icurrent line.
ISaves current 1I0de settings.

1----------------------------------------------------------------ISets or displays line number
I PROMPT [n]
lincrellent. Initial setting is

I
I
I
I QUIT
I
I
I
r,
I RECfa I F I
I
I V I
I

110.

ITerainates EDIT session with
Ino updates since last 'SlVE'.
ISets or displays record format
Ifor subsequent files.
I
I

L.J

1-----------------------------------------------------IRecollputes line numbers
I
r
r
"
I RENum Istrtno lincrnol I
I
11.Q
I §1!:1l!!2 I I

I L L

I
r
,
I
I REPEAT I n I
I

I
I * I
L
.J
I
I
I Replace [line]
I
I
I
I
I REstore
I
I
I RETURN
I
1------·
:{RE~SE} [subcommand]
I
I
I

Figure 17.

.J.J

for
IVSBASIC and FREEFORT source
Ifiles.
I

IExecutes the following OVERL1Y
Isubcommand ~ times.
!
I
I
I
IReplaces the current line withl
I'line' or deletes the current I
Iline and enters INPUT mode (if I
Ino data line is specified).
I

----------------------1I

IRestores mode settings to
Ivalues last preserved.

IReturns to EDIT environment
Ifrom CMS subset.

I
I

1
I

------------------1

IStacks (LIFO) the last EDIT
I
Isubcommand that does not startl
Iwith REUSE or the question
I
Imark (1) and then executes anyl
Igiven EDIT subcommand. ._ _ _.JI

Summary of EDIT Subcommands and Macros (Part 3 of 5)

section 7: Format and Usage Rules for CMS Commands

121

GC20-1804-3 Page Modified by TNL GN20-2659
EDIT

r------------------I
Subcommand

Format

Function

SAVE [fn [ft [f.J]]
r

IDisplay a number of lines
labove or below the current
Iline. (For display terminals.)
I
I

I
I
I
I

-------------------1I

S[croll][Up] 1* I
In I
11 I
.J

ISaves the file on disk and
Istays in EDIT environment.

I
I
I
I

SERial { OFF
ON rlincrl' }
ALL I l.Q I
seq l
.J

ITurns serialization on or off
lin columns 73 through 80.
I

SHORT

IEnters SHORT error message
I mode.
r

IStacks ~ lines, beginning with
Icurrent line, in terminal
linput tuffer.

STACK I
n
I
I
1
I
Isubcommandl

I
I

TAESet {n1 n2 ••• nx}

ISets the given tabs.

TOP

IPoints to the beginning of the
Ifile.
r

ISets or displays the column of
I truncation. An asterisk (*)
Imeans end of logical record.
I

TRUNC I n I
I * I
r

IDisplays ! lines beginning
Iwith the current line or the
Ibeginning of the file.

Type I m I n I I
I 1 I * I I
I * I
I I
r

I
I

IPoints to the line In' lines
labove the current line.

Up I n I
I 1 I

Verify ION I
10FFI

{; }

Isubcommandl
n
I
I
I
I
1
r

Zone I m I n I I
I 1 I * I I
I * I
I I

L
L
.J .J
L-_____________________
___

Figure 17.
122

Iistartcollendcoll
II
1
I *
I
.J

ISets, displays, or resets
Iverify mode. The asterisk (*)
Imeans end of logical record.
I
,Assigns to X or Y the given
IEDIT subcommand or executes
,the previously assigned subIcommand n times.
I
ISets or displays the columns
Ibetween which editing is to
,t ake place.
I
I

Summary of EDIT Subcommands and Macros (Part 4 of 5)

IBM VM/370: Command Language Guide for General Users

IDIT

Subcoaaand For.at

Function

-----------------------------------------------------------------1
IDisplays the last EDIT subcoa1
I.and which did not begin with
IBEUS! or a question .ark (1).
,Locates the line specified by
Ithe given line nuaber and in,serts tezt if given.

nnnnn [text]

;nuplicates the current line

SDUP. I n I
I .1 I

Iti.es. SoUP is an BOlT .acro.
I
I

SBOVI n { Op a
}
Down •
TO label

IBoves ! lines up or down!
tlines. $BOY! is an BOlT aacro.
I

I Figure 17.

Su.aary of IDIT Subco.aands and !aeros (Part 5 of 5)

Iii .FILI:
The specified file does not ezist.
EDIT:
The EDIT environ.ent is entered. The logical tab settings .ay be
either those defined by the user or those assn.ed according to the
filetype. In EDIT subco •• and .ay now be issued.
IIPUT:
The input environ.ent is entered by issuing the BDIT subco ••ands
III subsequent input lines are
REPLICE or IIPOT with no operands.
accepted as input to the file.
11DIT: line
"line" was entered in the EDIT environaent and is an invalid BDIT
subcoa.and or aacro.
This aessage appears while in LOIG error
.essage aode.

In invalid subcoaaand was entered in
SHORT error aessage .ode •
....

the EDIT environ.ent while in

,
In. invalid
.ode.

EDIT aaero

was entered

while in

SHORT error

aessage

section 7: For.at and Osage Rules for CBS Co.aands

123

EDIT

DftSEDI003E
DftSEDI024E
DftSEDI029E
DftSEDI044E
DftSEDIOS4E
D!SEDI076E
D!SEDI104S
D!SEDI10SS
DftSEDI132S

124

IIVALID OPTIOI 'option' RC=24
PILE 'fn ft f.' ALREACY EXISTS RC=28
I.VALID PARAftETER 'para.' II THE OPTIOI 'LRICL' PIELD
RECORD LEIGTH EXCEEDS ALLOWABLE ftAXI!Uft RC=88
I.CO!PLETE PILEID SPECIPIED RC=24
ACTUAL RECORD LEIGTH EXCEEDS THAT SPECIPIED RC=40
ERROR Inn' RBADIIG PILE 'fn ft f.' PRO! DISK RC=100
ERROR Inn' WRITING PILE 'fn ft fa' 01 DISK RC=100
PILE 'fn ft f.' TOO LARGB RC=88

IBft V!/370: Co •• and Language Guide for General Users

RC=24

ERASE

ERASE
Use the ERASE co •• and to delete a file or a related group of files fro.
a read/write disk.
The file to be deleted aust not be on a read-only
disk. The for.at of the ERASE co •• and is:

ERASE

I fn

[fa']

[(options ••• [) ]]

1**

I
I
I
I
I

IType

I~!I
L

..I

wh.!I!:
fn

is the filenaae of the files to be erased. An asterisk aay be
coded in this position to indicate that all filena.es are to be
used. This field aust be specified, either with a na.e or an
asterisk.

is the filetype of the files to be erased. An asterisk aay be
coded in this position to indicate that all filetypes are to be
used. This field .ust be specified, either with a na.e or an
asterisk.

is the file.ode of the files to be erased. If this field is
oaitted, the priaary read/write disk is searched for the files
to be erased.

lote: If asterisk is specified for filenaae and filetype then fileaode
iUst be specified. The fileaode aust include both a aode letter and
nuaber.

TYPE

displays at
erased.

the terainal the

file identifier for

IOTIlJ

file identifiers are not displayed at the terainal.

each file

ERASE OLDlILE TEftP (TYPE)
The file with the identifier
read/write disk, is erased.
ter.inal.

OLD1ILE TEftP, ilf located on the priaary
Its file identifier is displayed at the

Responses
fn

If the TYPE option is specified,
erased is displayed.

the file identifier for each file

Section 7: loraat and Usage Rules for CftS Coa.ands

125

ERASE

DMSERS002E
DMSERS003E
DMSERS037E
DMSERS048E
DMSERS054E
DMSERS069E
DMSERS070E
DMSERS071E

FILE ['fn [ft [fa]]'] NOT FOUND RC=28
INVALID OPTIOI 'option'
RC=24
DISK '.ode' IS READ/ONLY RC=24
IIVALID MODE '.ode'
RC=24
INCOMPLETE FILEID SPECIPIED RC=24
DISK 'mode(cuu)' NOT ACCESSED RC=36
IIVALID PARAMETER 'para.' RC=24
ERASE * * [*1 NOT ALLOWED RC=24

Note: You can invoke the ERASE command from the terminal, from an EXEC
file, or as a function from a program. If ERASE is invoked as a function
or from an EXEC file that has the &COITROL NOMSG option in effect, the
DMSERS002E PILE fn ft fm NOT POUID error message is not issued.

126

IBM VM/370: Command Language Guide for General Users

EXEC

EXEC
Use the EXEC command
co.mands or

if you want to be able to execute

EXEC control

statements contained in

one or more CftS

a specified

file bi

issuing a single command. If this command is entered from the CftS
co.mand mode but not nested within another EXEC procedure, the initial
word 'EXEC' may be omitted. The format of the EXEC command is:

EXec

[args ••• ]

is the filename of a file containing one or more CftS commands to
be executed. The filetype of the file must be EXEC and the file
must be fixed format with a logical record length not exceeding
130 characters. EXEC files can be created with the EDIT command
or by a user program. EXEC files created by the CftS Editor have
a logical record length of 80 characters. Each EXEC file can
contain a maximum of 4096 lines.

args

are the arguments to replace the numeric variables in the EXEC
file specified. within an EXEC file, up to thirty symbolic
variables can be used (each one indicated by an ampersand (&)
followed by an integer ranging from one to thirty) to indicate
values which are to be replaced when the EXEC file is executed.
The arguments are assigned to symbolic variables in the order in
which they appear in the argument list. For example, each time
an &1 appears in an EXEC line, the first argument specified with
the EXEC command temporarily replaces the &1, the second
argument specified with the EXEC command replaces &2, and so on,
to argument N of the EXEC co.mand.
If the percent sign (I) is used in place of an argument, the
corresponding variable (&1) is ignored in all the commands which
refer to that variable.
If the specified EXEC ~1~e contains
more variables than arguments given with the EXEC command, the
higher numbered variables are assumed to be missing, and are
ignored when the com.ands are executed.

EXEC CONTROL ST1TEftENTS
Control statements begin with a control word, which is usually followed
by a list of tokens, and in some cases by additional lines of data.
Figures 18 and 19 list the control statements and their functions and
the EXEC built-in functions. Refer to the !!L~70: !XEC Q2~r's Guide for
detailed information on how to use EXEC.

section 7: Format and Usage Rules for CftS Commands

127

EXEC

Function

Control statement
&variable = ae

IAssigns the value of ae to
Ithe symbol specified by
I&variable; ae is an algebraic
lexpression; the equal sign
Imust be preceded and followed
Iby a blank.

&lRGS [arg1 [arg2 ••• ]]

IRedefines the arguaents &1,
1&2, ••• with the value of
I ' ar g 1 " , a r g2 " ••• , and reIsets the variable &INDEX.

&BEGPUNCH [llL]
line1
line2

I Punches 'line1', 'line2', •••
linto the card punch, without
Itokenizing them.

&END

I
I
I
r

&BEGST1CK
line1
line2

IStacks 'line 1', 'line2', ••• ,
lin the console input buffer
I without tokenizing thea.
I
I
I
I
I
I

IIIFQ I 11ll I
IlIFO I L
.J
L

&EID
&BBGTYPB [lll]
line1
line2

IDisplays 'line1', 'line2', ••• 1
lat the console, without tokenlizing them.
I
I
I
I

&END
&CONTINUE

IProvides a branch address for
I&ERROR, &GOTO, and other conIditional branching statements.

&CONTROl
r

101'1' I I TI!B I If!~! I IA~~ I
IBRRORI I!QTI!~I IUIP1CKI IIO!SGI
I Cft~ I L
.J
L
.J L
.J
11lt I
L

&BRROR action

Figure 18.

128

ISets, until further notice,
Ithe characteristics of the
Isummary of execution, which is
lautomatically printed at the
Iconsole.
I
I
IExecutes 'action' following
lany CftS command which yields
Ian error return code (that is,
la return code which is not
Izero). 'action' can be any
lexecutable statement.

Summary of EXEC control Statements (Part 1 of 3)

IBft Vft/370: Command language Guide for General Users

EXEC

Control statement

Function

-----------------------------------------------------------------------1
IExits from the EXEC file with I
r
,
Ithe given return code.

&EXIT Ireturncodel
i
Q
I
L

I
I
I

I
I

-----------------------------------------------------------------1
ITransfers control to the top I
&GOTO {TOP
}
lof the EXEC file, to the given
Iline, or to the line starting
i.ith !label'.

linenuaber
label

&If {token 1 } ( EQ) (token2 I executable IExecutes the 'executable
&$
)NE )&$
(statement I statement' if the condition is
; satisfied.
&*
) a~) &*
)
I

&LOOP {n
}
label

I
I

ILoops through the following Q
Ilines, or down to (and includling) the line starting with
I'label', for m tilles, or until
I 'condition' is satisfied.

{IIcondition }

IPunches a card containing
Itokenl, token2, •••

&PUNCH token 1 [token2 ••• ]

&REID In

I
I
I

IIRGS
IVIRS

var 1 [var 2 ••• ] I

&SKIP

IIf n > 0, skips the next ~
Ilines of the EXEC file. If
In < 0, transfers centrol to
Ithe line which is ~ lines
labove the current line. If
In = 0, transfers control to
Ithe next line.

I n I
I 1 I
L

IDisplays Q blank lines at the
I terminal.

&SPICE I n I
I 1 I
L

I
I

&STICK IlIlQI [tokenl [token2 ••• ]]
ILIlO 1
L

ligure 18.

IReads the next ~ lines froll
Ithe terllinal and treats thea
las if they had been in the
IEXEC file; or reads a line,
lassigns the tokens in it to
Ithe argullents &1, &2, ••• , and
I resets &INDEX to the number of
larguments thus set; or reads a
Isingle line and assigns the
Itokens in it to the variables
I'varl', 'var2', •••

IStacks a line in the terainal
linput buffer containing
I 'token 1 " 'token2', ••• , or
Istacks a null line if the
Itokens are absent.

Su.mary of EXEC Control statements (Part 2 of 3)

section 1: lormat and Usage Rules for CMS Commands

129

EXEC

Control State.ent
r

&TI!E

101
10FF

IDisplays timing information.

I
I

IRBSETI
ITYPB I
L

Function

I
I
I
I
I

&TYPB tokenl [token2 ••• ]

Figure 18.

IPrints at the ter.inal a line
Icontaining 'tokenl,' 'token2,'
I· · ·
Summary of EXBC Control State.ents (Part 3 of 3)

An BXBC built-in function consists of the name of the function and,
usually, a list of arguments.
Built-in function names are BXBC
keywords, and start with an ampersand.
with the exception of &LITERAL,
they are recognized only, if they appear as the token following the equal
sign of an assignment statement. Figure 19 lists the BXEC built-in
functions with their format and an explanation.

Bxplanation

Built-in Function
&COlCAT tokenl [token2 ••• ]

IConcatenates 'tokenl',
l'token2' ••••• into a single
Itoken. with a maximum length
lof eight.

&DATATYPB token

I Has the value IUft or CHAR.
Idepending on the data.

&Length token

IGives the number of nonblank
Icharacters in 'token'.
I

SLlteral token

IUses the literal value of
I 'token'. without sUbstitution
Ifor any EXBC variable which
Imay appear in it.

SSUBSTR token i [ j ]

IExtracts that part of 'token'
Iwhich starts at character "in.
Iwith length "j"; or which
Istarts at character "in and
Iruns to the end of the token.

Figure 19.

Su.mary of EXEC Built-in Functions

As each CBS co.mand in the EXBC file is processed. it is displayed at
the terminal along with any nonzero return code.
The SCOBTROL co •• and
can be used to augment or reduce the amount of displaying done during
execution.
130

IB! '!/370: Co •• and Language Guide for General Users

EXEC

If the EXEC interpreter finds an error, it displays

~he

message:

ERROR IN PILE 'fn EXEC fm', LINE n, 'description of error'
where "description of error" is one of the following conditions with its
appropriate return code:
Return
~Qg§- ~§2gipt.!.Q1!

(802)

(804)

(805)
(806)
(807)
(808)
(809)
(810)
(811 )
(812)
(813)
(814)
(815)
(816)

SSKIP OR SGOTO ERROR
TOO !INY lRGUftENTS
MAX DEPTH OP LOOP NESTING EXCEEDED
DISK OR TER!INAL READ ERROR
I Ii VALI D SI IT AX
INVALID FOR! OP CONDITION
IIIVALID ASSIGNMEIT
!ISUSE OP SPECIAL VARIABLE
ERROR II SBBBOR ACTION
CONVERSION ERROR
TOO ftAIII TOKEIS III STATEftENT
ftISUSE OP BUILT-IN PUNCTION
EOP POUID II LOOP
INVALID CONTROL WORD

D!SBXC001E NO PILENAftE SPECIPIED RC=24
DftSEXC002E PILE 'fn ft' NOT POUID BC=28
DftSEXC034E PILB 'fn ft f.' IS NOT PIXED LENGTH

RC=32

Section 7: Pormat and Usage Rules for CftS Commands

131

FILEDEF
FILEDEF

Use the FILEDEF command to define an as ddname and to relate that ddname
to a device on your virtual machine. If the device is a disk, FILED!F
assigns a C!S file identification (that is, fn ft fa) and, if the disk
is an as disk, an as data set name; or, if the disk is a DOS disk, a DOS
file-ide llso, using FILED!F, you can specify as DCB parameters that
describe the ddname just as they would on the as Job control Language
Data Definition statement. In general, FILEDEF is used to define ddnames
for programs written using the language processors supported by 'B/310.
You can find usage information on FILEDEF in "UsinG as Programs and
Macros Under CMS" in section 4.
The format of the FILEDEF co.mand is:

FIledef
l{ddname}
I nn
I *

Terainal

[(optionl optionD[) ]]

PRinter
PUnch
Reader

[ (optionD[) ]]

DISK

....

Ifn
ft
Ifal I [(optionB optionD[) ]]
I FI!!) gdn~~ 1111 I

, r

.. L

....

II DISK fn
ft
II filii {DSN 1
}
II
FILl ddna~~111111 DSN qual1 qua12 •••
[(optionB optionD[) ]]

DUM!Y

[ (optionD[) ]]

T1Pn

[(optionC optionD[) ]]

CLE1R

..I
opti~~:

~!i21!j:

l!lf~lSE

I
ILOWC1SEI

[KEILEI nn]
r

[LIBCT nn]
[OPTCD a]
[J)ISP BOD]
[BEBBER aeabernaae]
[ COICIT]
r

: DSORG
I
I
L'

132

11TRlCKI
19TRlCKI

IITEIT nnl
IITEIT ~.21
L

2E!iQ!!£:

[TRTCH a]
[DEN den]

.QptionD:
[PERB]
r

ICHINGE I
I NOCHINGEI
L

[RECFB a]
[LRECL nn]
r

IBLOCK nn I
IBLKSIZE nnl
L

{i~~~
Dl I
IS I
..

IBB 'B/310: Com.and Language Guide for General Users

FILEDEF

ddnalle
nn

is the naae by which the file is referred to in your
program. If a number nn is specified, it is translated to a
FORTR1NI data definition name of FTnnF001. If the CLE1R
operand is specified. ddnalle mav be specified as an asterisk
(*) to indicate that-all file definitions not entered with the
PER! option are to be relloved.

TERftIB1L

is your terllinal (terminal I/O should not be blocked).

PRINTER

is the spooled printer.

PUNCH

is the spooled punch.

REIDER

is the spooled card
blocked) •

DISK

specifies that the virtual I/O device is a disk. Is shown in
the foraat, you can choose one of two forms for specifying the
DISK operand.
Both forlls are described in the section that
follows, "Using the FILEDEF DISK Operand."

DUIU'Y

indicates that no
set.

T1Pn

is a magnetic tape. The symbolic number of the tape drive, nn,
can be 1, 2, 3, or~, representing virtual units 181, 182,
183, and 184 respectively.

CLE1R

reaoves any existing definition for the specified ddname.
Clearing a ddna.e before defining it ensures that a file
definition does not exist and that any options previously
defined with the ddname no longer have effect.

reader (card

real I/O is to

reader I/O

should not

take place for a

disk data

If no operands are entered with the cOllmand, a list of current filetypes
is displayed at the terainal including the ddname, device type, and, if
device type is DISK, the filename, filetype, and filemode. llso, if the
PILEDEP is for an as data set, the data set name is displayed; or, if
the FILEDEF is for a DOS file, the file-id is displayed.

Whenever an option is specified that is invalid for a particular
device type, an error message is issued. Figure 20 shows valid
options for each device type.

IThe FORTR1N processors are Prograll Products.
Section 7: Format and Usage Rules for CftS Commands

133

FILE.DEF

I Onit Record I
IREADEB, POICHI
I PRINTER
I TERKIIIL

option
BLOCK, BLKSIZE
CHANGE, NOCHANGB
COICAT
DBN
DISP ftOD
KElLEN
LlftCT
LOWCASE, OPCISE
LRBCL
KBftBER
OPTCD
PEBM
BECFM
TBTCH
ITBNT
7TBACK, 9TBACK

1
1

DISK
DOKftI I

TIPn

1
1
1

X
X

12
1
X
1

INo options may be necessary but all disk options are accepted.
2This option is used for BDAK files.
3This option is for 7-track tapes only.
Figure 20.

Valid File Characteristics
FILEDEF COllmand

for Bach

Device

Type for

the

.Y.fCI.§~

translates all terminal input data to uppercase •

LOWCISE

retains all terminal input data as typed in.

KElLEN nn

is the size (nn) of the key (in bytes).

ITENT nn

is the number of records (nn) in the extent for the file.
The default is 50.

LIMCT nn

is the maximull nuaber of extra tracks or blocks (nn) to
be searched. This option is used for BDIK files.

OPTCD a

is the direct access search processing desired.
The
variable ! may be any combination of up to three of the
following:
(A and B are mutually exclusive.)
Cod~

I
B

P
R

DISP MOD

DISD Search
Ictual device addressing
Extended search
Peed back addressing
Relative block addressing

positions the read/write pointer after the last record in
the disk file.

MEMBEB membernalle
allows you to specify the name of a member of an as
Partitioned Data Set; membername is the nalle of the PDS
lIellber.

134

IBft Vft/370: Command Language Guide for General Osers

PILEDEP
COBCAT

allows you to concatenate OS data sets with each other
and with CftS files. You must use the COBCAT option when
you are defining an OS data set referred to by a later
GLOBAL command (COBCAT is not necessary for CftS files
referred to in a later GLOBAL command.)
COBCAT should be used only for aacro libraries to be
specified in a later GLOBAL co.mand. You must specify
COBCAT with all of the OS data sets you define, including
the first.
wnen you use CONCiT in a FILEDEF coaaand, you can specify
more than one PILEDEP for a particular ddname.
llso, when you use COBCAT, the DCB paraaeters used are
those associated vith the first filename you specify in a
GLOB1L comaand for a macro library.

DSORG {~PIOS:} is the data set organization: physical sequential (PS),
partitioned (PO),
direct
access (Dl),
or
indexed
sequential (IS).
r

I 7TR1CK I
I 9TRACK I
L

TRTCH a

is the tape setting.

is the tape recording technique.
to determine the value of ~:
a

Parity

converter

odd
odd
odd
even
even

off
on
off
off
off

OC
OT
!

Use the following chart

Translator
I
I
I
I
I

off
off
on
off
on

DEB den

is tape density: den can be 200, 556, 800, 1600, or 6250
bpi (bits per inch). If 200 or 556 are specified, 7TR1CK
is assuaed. If 800, 1600, or 6250 are specified 9TR1CK is
assumed.

PERft

retains the current definition
until it either is
explicitly cleared or is changed with a new PILED!P
coalland with the
CH1BG! option.
is not
If PERft
specified, the definition is cleared when a PILED!P
*
CLE1R com.and is executed.
merges the file definitions whenever a file definition
exists for a ddname and a PILEDEP specifying the same
ddnalle is issued: the options associated with the two
definitions are merged.
Options
from the original
definition remain in effect unless duplicated in the new
definition. Rew options are added to the option list.

BOCHABGE

retains the current file definition, if one
the specified ddname.

exists, for

section 7: Pormat and Usage Rules for CftS Commands

135

FILBDBF
BBCFft a

is the record foraat
the following:
!

FB
V

VB
U

FS.FBS
VS.VBS
A
B

LBBCL

BLOCK nn
BLKSIZB nn

of the file. where! can

be one of

fteani.!!,g
fixed length
fixed blocked l
variable length
variable blocked l
undefined
fixed length. standard blocks
variable length. spanned records
ASA print control characters 2
aachine print control codes 2

is the logical record length (nn)
LBBCL should not exceed 32.767
restrictions.

of the file. in bytes.
bytes because of OS

is the logical block size (nn) of the file. in bytes.
BLOCK should not exceed 32.767 bytes because of OS
restrictions.
If a CftS file is fixed and has 80-byte CftS records. you
should specify BECPft PB BLOCK 800 LBBCL 80 and a fileaode
nuaber of 1. (BLOCK can also be expressed as 80*10.)
There can be significant perforaance improvement for CBS
fixed files if the block size is a au1tiple of 800.

Bates:
-l-.--There is an auxiliary processing option for PILBDBP that is only
valid when FILBDEP is executed by an internal prograa call: this
option cannot be entered on a terainal coaaand.
The option.
AUIPROC addr. allows an auxiliary processing routine to receive
control during I/O operations.
2.

DOS files do not contain BLKSIZE. LBECL. or BECPB specifications.
These options aust be specified by a PILEDBP coa.and or DCB
stateaent. Otherwise the defaults. BLKSIZE=32760 and RECPB=U. are
assumed. LBBCL ,is not used for BBCP!=U files.

If V or VS is specified for RECFft. LRECL must be at least 4 bytes
less than BLKSIZB.
BLKSIZE must
be specified if LBECL is
specified. The FILEDEF co.mand does not provide default values for
LBECL and BLOCKSIZB. However. the following chart describes the
results of specifying BLOCKSIZE and LBECL.

IPB and VB should not be used with TBBftIBAL or BEADBR devices.
2A and ft may be used in conjunction with any of the valid BBCFft settings
(for example. PA. PBA. VA. VBA. etc.)
136

IBft Vft/370: Comaand Language Guide for General Users

GC20-1804-3 Page Modified by TIL G120-2659
FILEDEF
r-------------------------------------------------~-~--~~

BLKSIZE

not
specified

LRECL

Results

not
IIf the input file exists on disk, the item
specified Ilength becomes the BLKSIZE (or BLKSIZE +4
Ifor variable length records) •
not
ILRECL~BLKSIZE (or LRECL=BLKSIZE-4,
specified Ivariable-length records).

.&:~
.LV.L

not
specified

specified IBLKSIZE=LRECL (or BLKSIZE=LRECL+4, for
Ivariable-length record) •

specified

specified IThe values specified are used.

L---------------------.----------------------------------------------------~

There are two general forms for specifying the FILEDEF DISK operand.
you specify the first form:

DISK fn ft [fm]
fn and ft
(filename and filetype) are assumed to be a CMS fileid. If
the filemode is for an OS disk, fn and ft are assumed to be the only two
qualifiers of an OS data set name. In this form, the filemode you
specify must always match the access mode of the disk on which the data
set resides. The default values for fn ft fm are FILE ddname A1.
You cannot use this form unless the OS data set. name or DOS file-id
conforms to the OS naming convention (one- to eight-byte qualifiers
separated by periods, to a maximum of 44 chracters, including periods) .
Also, the data set name can have only two qualifiers; otherwise, you
must use the DSN ? or DSN qua11 ••• form.
For example, if the data set
name or file-id is TEST.SAMPLE.MAY. you enter:
FILEDEF MINE B1 DSN TEST SAMPLE MAY
-- or -FILEDEF MINE B1 DSN ?
TEST. SAMPLE. MAY
If the data set name or file-id is TEST. SAMPLE, then you enter:
FILEDEF MINE DISK T!ST SAMPLE B1
The second form of the DISK operand is only for use with OS data sets
and DOS files:
,.

FILED!F ddname I DISK fn
ft
I I fm I {DSN ?
}
I
111~ QQ!!~!!!~ I IAll
DSN qua11 [qua12 ••• ]
L

This form allows you to specify a DSN operand that corresponds to the
DSN parameter on the DD card describing an OS data set or DOS file.
There are three ways you can specify this form:

Section 7: Format and Usage Rules for CMS Commands

137

GC20-1804-3 Page Modified by TNL GN20-2659
FILEDEF
1.

FILEDE' ddname DISK fn ft fm DSN quaIl [qua12 ••• ]
If you use this form, the FILEDEF command associates the filename
and filetype you specify with the OS data set name or DOS file-id
specified following the DSN operand.
Once it is defined, you can
refer to the OS data set name or DOS file-id by coding the filename
and filetype. If you omit DISK, filename, filetype, and filemode,
the default values are PILE ddname Al.

FILEDEP ddname DSN 1
This form of the PILEDEP command allows you to specify the DSN OS
data set name or DOS file-id interactively.
Using this form, you
can enter an OS data set name or DOS file-id containing embedded
special characters such as blanks and hyphens.
If you use this
form, the default filename and filetype for your file, FILE ddname,
is the filename and filetype associated with the OS data set name
or DOS file-ide
The filemode for this form is always the default,
Al.
The interactive DSN operand works this way: when you enter DSN 1,
CMS requests that you enter the OS data set name or DOS file-id
exactly as it appears in the data set or file.
Do not omit the
periods that separate the qualifiers of an OS data set name, but do
not insert periods where they do not appear.
quall[.qua12 ••• ]
where quall.qua12 ••• are the qualifiers of the as data set name or
DOS file-{d.
When you use this form,
you must code the periods
separating the qualifiers.

FILEDE' ddname Bl DSN quaIl [qua12 ••• ]
This form allows you to specify the OS data set name or DOS file-id
explicitly.
(This form can be used for DOS file-ids only if they
comply with the OS naming convention of one- to eight-byte
qualifiers separated by periods, to a maximum of 44 characters,
including periods.)
Again, the default value for the filename is
FILE and for filetype,
the default value is the name associated
with the OS data set name or DOS file-ide
The filemode for this
form is Bl as you specified it on the co •• and.
When you use this
form, you must omit the periods that separate the qualifiers of the
OS data set name.
For example, for an OS data set or DOS file
named MY.PILE.IN, you enter
FILEDEF ddname Bl DSN MY FILE IN

All of these forms
command format.

have many

variations, as

is apparent

from the

Note: When the FILEDEF command is used to define a ddname, that
defInition remains in effect until another PILEDEP command
(with the
CLEAR option) is issued or until the system clears the definition. The
system clears PILEDEF definitions if:
•

138

Any of the CMS language processors are executed. The language
processors always issue, at their completion, the command PILEDEF *
CLEAR. This command causes all FILEDEF definitions to be cleared,
except for those defined with the PERM option.

IBM VM/370: Command Language Guide for General Users

FILEDEF
If you want any FILEDEF definitions to remain in effect after
language processor has executed, define them with the PERM option.
•

An ABEND occurs.
When you enter your next co •• and, ABEND recovery
takes place. ABEND recovery clears all previously specified FILEDEF
definitions, including
those for which
the PERM
option was
specified. All the FILEDEF definitions must be respecified after
lRp.wn
---- -----

~~rh

r~rnv~rv
----.--~.

FILEDEF MACLIE DISK SYS1 MACLIB B1

(MEMBER ABEND)

When the CMS file SYS1 MACLIB or, if the B disk is an OS disk, the OS
data set SYS1.MACLIB is opened, the read/write pointer is set to the
start of the partitioned data set member ABEHD.
FILEDEF ASSEMBLE DISK TEST ASSEMBLE B1 DSN SAMPLE OS DATA
When an OS macro or a eMS command references the fileid TEST ASSEMBLE
B1, it gets information from the OS data set SAMPLE.OS.DATA.
For
example, the
command ASSEMBLE TEST
assembles the OS
data set
SAMPLE.OS.DATA.
FILEDEF SYSPRINT PHIlTER (PERM RECFM F BLOCK 132)
Whenever SYSPRINT is referred to in your program, the output written
is spooled to the virtual printer.
The file is fixed-format with a
logical block length of 132. The file definition is not removed by the
command FILEDEF * CLEAR.
FILEDEF PRINTOUT TERMINAL (UPCASE NOCHANGE
If a file definition for the ddname PRINTOUT does not exist, one is
established. Output written to PRINTOUT is displayed at the terminal in
uppercase.
FILEDEF DISK DISK HAME OLDFILE
All I/O for a file with a ddname of DISK is directed
with a file identifier of NAME OLDFILE.

to a disk file

FILEDEF DISKFILE DUMMY
When any I/O command is issued to a disk file with
DISKFILE, the real I/O operation is not performed.

a ddname

FILEDEF NEWMAST TAP2 (9TRACK DEH 1600 RECFM FB LRECL 050 BLOCK 3000
I/O commands issued to a file with ddname of NEWMAST are directed to
the tape located at logical unit TAP2.
The tape is 9-track, and
recording is done at 1600 bpi. The tape is in fixed-block format with a
logical record length of 50 and a physical blocksize of 3000.

Section 7: Format and Usage Rules for CMS Commands

139

GC20-1804-3 Page Modified by TNL GN20-2659
FILEDEF
FILEDEF CMSLIB DISK aSl MACLIB * DSN OS DATA 1 (LRECL 80 BLOCK 800 RECFM FB CON CAT)
FILEDEF CMSLIB DISK OS2 MACLIB * DSN OS DATA 2 (CONCAT)
FILEDEF CMSLIE DISK SYS1 MACLIB * (CONCAT)
GLOBAL MACLIB OSl OS2 SYS1 MYLIB

This example shows how you can use the CONCAT option to cause CMS to
search the as maclibs OS.DATA.1, OS.DATA.2 and SIS1.MACLIB and the CMS
maclib MILIB to resolve maclib references in assembling the CMS file
SAMPLE ASSEMBLE.
ACCESS 193 B
ACCESS 194 C
FILEDEF CMSLIB DISK ASPl MACLIB * DSN ASP1 MACROS RLl (RECFM FIXED BLOCK 3360 LRECL 80 CONCAT)
FILEDEF CMSLIB DISK ASP2 MACLIB * DSN ASP2 MACROS RL2 (CONCAT)
FILEDEF CMSLIB DISK SYS1 MACLIB * (CONCAT)
FILEDEF ASSEMBLE TEST SAMPLE B1 DSN TEST OS SAMPLE1
GLOBAL MACLIB ASP1 ASP2 SYSl CMSLIB
ASSEMBLE TEST

This example shows how you can use FILEDEF to override the default
FILEDEF commands CMS gives you for an assembly. The example also shows
how to point to an as disk containing as source for TEST.OS.SAMPLE1 and
the as macro libraries ASP.MACROS.RL1, ASP.MACROS.RL2, and SIS1.MACLIB.
The GLOBAL command accesses four macro libraries and the order of search
for the macros needed during assembly, that is, ASP1 first, ASP2 next,
and so on.
The first three libraries are as libraries and CMSLIB is a
CMS macro library.
!Qi~:

A disk does not have to be accessed at the time a FILEDEF is
issued; however, if this is the case, a warning message is issued to the
user informing him that the disk is not accessed.

ddname1

device1

[filename1

filetype1]

ddnameN

deviceN

[filenameN

filetypeN]

A list of current definitions is displayed if
is entered with no operands.

the FILEDEF command

DMSFLD220R ENTER DATA SET NAME:
A FILEDEF command with the DSN? operand was entered. Enter an OS
data set name the form quaI1.quaI2 •••• qualn;
where qual1,
qual2
through qualn are the qualifiers of an as data set name.
DMSFLD7041 INVALID CLEAR REQUEST
A CLEAR request was entered
exist; no action is taken.

140

for a

file definition that

IBM VM/370: Command Language Guide for General Users

does not

FILEDEF

DftSPLD003E
DftSPLD023E
DftSPLD027E
DftSPLD029E
DftSFLD035B
DftSPLD050E
DftSPLD065E
DftSPLD066E
DMSPLD070E
DMSFLD221E
DftSPLD224E

IBVALID OPTIOB 'option' RC=24
NO PILETYPE SPECIPIED RC=24
I!VllID DEVrCE 'device name' RC~24
INVALID PARAftETER 'param' IN THE OPTION 'option' FIBLD RC=24
INVALID TAPE ftODE RC=24
PARAftETER ftISSIIG AFTER DDNAftE RC=24
'option' OPTION SPECIFIED TWICE RC=24
'option' AID 'option' ARE COIFLICTING OPTIOIS RC=24
INVALID PARAftETER 'oaram' RC=24
INVALID DATA SBT IA!E 'data set name' RC=24
PILEID ALREADY IN USE RC=24

section 7: Format and Usage Rules for CftS Co •• aDds

141

PORftAT
FORMAT,

Use the PORftAT coamand to:
•

Initialize a virtual disk area in the CftS format.

•

count the nuaber of cylinders on a virtual disk.

•

write a label on a virtual disk.

•

Reset the number of cylinders on the virtual disk.

This co.mand can be used with a virtual 3340, 3330, 2314, or 2319
direct access storage device. The format of the PORltAT command is:

PORftAT

cuu lIode [nocyl] [ (options ••• [) ]]
.Qp ti.9J!§:
r

"'I

ILABEL I
IRECOftPI
L

!.!l~~:

cuu

is the virtual
foraatted.

device

address of

the

virtual

disk

Bote that 000 is not a valid address.
aode

is the fileaode letter to be assigned to the specified device
address. Valid fi1eaode letters are A, B, C, D, E, P, G, I, and
Z. This field must be specified.

nocy1

is the number of cylinders to be made available for use. All
available cylinders on the disk are used if the nu.ber specified
exceeds the actual number available.

LABEL

writes a label on the disk without foraatting the disk. A
six-character label is written on cylinder 0, track 0, record
3 of the virtual disk. A prompting message requests a
six-character disk label (less than six is left-justified,
blank padded).

BECOftP changes the nuaber of cylinders on the disk which are
available to the user to the actual number of ainidisk
cylinders or to the number specified by nocyl, whichever is
less. If nocyl is not specified, all cylinders are used.

lo!!: If neither RECOKP nor LABEL is specified, the disk area is
initialized by writing a device-dependent nuaber of records (containing
binary zeros) on each track. Any previous data on the disk is erased.
A read after write check is made as the disk is formatted.

142

IBK V6/310: Command Language Guide for General Users

FORftAT

FORftAT 191 A 25
Initializes 25 cylinders
CftS format.
POR!AT 192 B
Changes the number
cylinders.

of the disk located at virtual

address 191 in

25 (RECO!P)
of cylinders available at virtual address

192 to 25

FORBAT 193 C (LABEL)
writes a label on the disk at virtual address 193.
prompting message with a six-character label.

Respond to

DBSPOR603R POR!AT WILL ERASE ALL PILES ON DISK 'Ilode(cuu) '.
TO COITIIUE? (YESIIO):

the

DO YOU WISH

You have indicated that a disk area is to be initialized: any
existing files will be erased. This message gives you the option
of canceling the execution of the FORftAT command. Reply YES or
NO.
DftSPOR605R ENTER DISK LABEL:
You have requested that a label'be
one- to six-character label.

written on the disk.

Enter a

DftSPOR7051 DISK RE!AINS UNCHANGED
The response to message, D!SPOR603R, was '10'.
DftSPOR7321 'nnn' CYL POR!ATTED ON DISK 'mode (ccu) ,
A formatting operation has been done on nnn cylinders
at virtual address ccu.

of the disk

DftSFOR7331 FOR!ATTIIG DISK 'mode'
The disk represented by mode letter 'mode' is being formatted.
DI SK 'Ilode (cuu)':
('n' CYL)

'n' FILES, 'n' BLOCKS,

, n' LEFT (OF 'n'),

This message gives the extent and other information about
when a RECO!P operation has been done.

nnl FULL
a disk

Section 7: Pormat and Usage Rules for CftS Com.ands

143

PORftAT

DftSPOR003E
DftSPOR017E
DftSPOR028E
DftSFOR037E
DftSPOR048E
DftSPOR069E
DftSFOR070E
DftSPOR113S
DftSFOR114S
DftSPOR125S
DftSFOR126S
DftSFOR214W

144

IIVALID OPTIOI 'option' RC=24
INVALID DEVICE ADDRESS 'cuu' RC=24
10 DEVICE SPECIPIED RC=24
DISK '.ode[ (cuu)]' IS READ/OILY RC=36
IIVALID ftODE '.ode' RC=24
DISK '.ode' lOT ACCESSED RC=36
IIVALID PARAftETER 'para.' RC=24
cuu lOT ATTACHED RC=100
'cuu' IS AI UISUPPORTED DEVICE TYPE RC=88
PERftAIEIT UIIT CHECK 01 DISK ·.ode(cuu)' RC=100
ERROR {READIWRIT}IIG LABEL 01 DISK '.ode(cuu)' RC=100
CAIIOT RECOftPUTE WITHOUT LOSS OP DATA. 10 CHAIGE RC=8

IBft Vft/370: Command Language Guide for General Users

GBIDIRT
GENDIRT

Use the GBIDIRT co •• and to create a CftS auxiliary directory.
The
auxiliary directory contains the na.e and location of .odules which
would otherwise significantly increase the
size of the resident
directory, thus increasing search ti.e and storage require.ents.
By
using GBBDIRT to create an auxiliary directory, the file entries for the
given cOII.and are loaded only when the co._and is invoked. The for.at
of the GBIDIRT co_.and is:

GBIDIRT

directoryn aile

[target.ode]

!J!.!!:! :

directorynalle

is the entry point of

target.ode

is the file.ode letter of the disk containing the
.odules referred to in the directory. The letter is
the file.ode of the disk containing the .odules at
execution ti.e,not the file. ode of the disk at
creation of the directory.
The default value for
target.ode
is
S,
system disk.
It
is
your
responsibility to deter.ine the usefulness of this
operand at your installation, and to infor. all users
whose programs are in auxiliary directories exactly
what filellode to specify on the lCCBSS co ••and.

th~

auxiliary directory.

!2te:
See the Vft/370: Syste. Proqr.!~£..!! Gui,g.! for infor.ation on
creating auxiliary directories and for further require.ents for using
the target_ode option.

DftSGID002W
DftSGID021B
DftSGHD022B
DftSGID070B

FILB 'fn ft f.' lOT FOUID RC=4
IITRY POIIT 'na.e' BOT FOUID RC=28
10 DIRBCTORY IlftB SPBCIFIBD RC=24
IIVILID PIRlftlTBR 'para.' RC=24

Section 7: For.at and Usage Rules for CftS Co ••ands

145

GEHKOD
GENMOD

Use the GEIKOD co •• and to generate
format of the GEIKOD co •• and is:
Genllod

absolute

core-i.age files.

The

[fn [ft [fm]]] [ (options ••• [) ]]
.Q.E!io.!!§: [ PROK entry1 ]
[ TO entry2 ]
r

I !!E
I
I ROKAP I
L

I STR
I
I IOSTR I
[ SYSTEK ]

is the filename of the KODULE file being created. If fn is
not specified, the file created has a filename equal to that
of the first entry point in the LOAD KAP.

is the filetype of the KODULE
specified, ft .ust be KODULE.

is the file.ode of the KODULE file being created. If f. is
not specified, the file is written on the priaary read/write
disk.

file being

created.

If conflicting options are specified, the last one entered is used.
PROK entry1 specifies an entry point or a control section naae, which
is the starting virtual storage location froa which the
core-iaage copy is generated.
If PROK is not specified, the starting virtual storage
location of the module is eit_her t he address of fn (if it
is an external name), or the address of the first
external nalle encountered during the loading process •.
This is not necessarily the lowest address loaded. If
you have any external references before your START or
CSECT instructions, you aust specify PROK entry1 to load
your program properly.

146

TO entry2

specifies an entry point or a control section naae, which
is the ending virtual storage location fro a which the
core-image copy is generated.

KAP

includes a load map in the KODULE file.

IOftAP

specifies that a
ftODULE file.

load map is not to be

contained in the

IBK YK/370: COllmand Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659
GENMOD
~Q!~:

If a module is generated with the NOMAP option,
that module cannot later be loaded and started with the
CMS LCADMOD and START commands. When NOMAP is specified,
the information produced is not sufficient for the START
command to execute properly. However, a module generated
with the NOMAP option can later be invoked as a command,
that is, it can be invoked if its filename is entered.
STR

invokes the CMS storage initialization routine when the
MODULE is subsequently loaded (see the CMS LOADMOD
command). This routine frees any storage remaining from
a prevlous program. STR is the default setting if the
MODULE is to be loaded at the beginning of available user
storage.

NOSTR

indicates that, when the MODULE is loaded, free storage
pointers are not reset for any storage currently in use.
NOSTR is the default setting if the MODULE is to be
loaded at a location other
than the default load
address.

SYSTEM

indicates that when the MODULE is subsequently loaded, it
is to have a storage protect key of zero.

Notes:
-':--Before the file is written, undefined symbols are set to location
zero and the common reference control section is initialized. The
undefined symbols are not retained as unresolved symbols in the
MODULE file. Therefore, once the MODULE file is generated, those
references cannot be resolved and may cause unpredictable results
during execution.
2.

If you load a program into the transient area you should issue the
GENMOD command with the STR option. Be careful if the program
issues OS GETMAIN or FREEMAIN because your program, plus the amount
of storage obtained via GETMAIN, cannot exceed two pages (8192K).
It is recommended that you do not issue a GETMAIN from a transient
area.

DMSMCD001E
DMSMOD002E
DMSMOD003E
DMSMOD005E
DMSMCD021E
DMSMOD032E
DMSMOD037E
DMSMOD040E
DMSMOD070E
DMSMOD084E
DMSMOD105S
DMSMOD109S

NO FILENAME SPECIFIED RC=24
FILE 'fn ft' NOT FOUND RC=28
INVALID OPTION 'option' RC=24
NO (FROM TO) ENTRY SPECIFIED RC=24
ENTRY POINT 'name' NOT FOUND RC=40
INVALID FILETYPE 'ft' RC=24
DISK 'mode' IS READ/ONLY RC=36
NO FILES LOADED RC=40
INVALID PARAMETER ••••• RC=24
INVALID USE OF 'FROM' AND 'TO' OPTIONS RC=24
ERROR 'nn' WRITING FILE 'fn ft fm' ON DISK RC=100
VIRTUAL STORAGE CAPACITY EXCEEDED RC=104

Section 7: Format and Usage Rules for CMS Commands

147

GLOBAL

GLOBAL
Use the GLOBAL co •• and to specify which CMS libraries are to be searched
when processing subsequent CMS commands.
The GLOBAL command remains in
effect for an entire CMS session unless it is explicitly canceled or
until another GLOBAL command is
entered.
There are no default
libraries, so the command must be libraries if any libraries are to be
used. The GLOBAL command verifies the existence of the libraries and
issues a warning message if a specified library does not exist. The
format of the GLOBAL command is:

I GLobal
MACLIB } [libnamel ••• libname8]
IL-__________ { TXTLIB

I
I
J

MAClIB

allows the specification of the macro libraries that are
to be used during the execution of language processor
commands. The macro libraries may be CMS files or OS
data sets. If you specify an OS data set, FllEDEF must
be issued for the data set before you issue GLOBAL.
(See
the description of the FlLEDEF CONCAT option for more
information.)

TXTLlB

allows the specification of text libraries to be searched
for .issing subroutines when the lOAD or INCLUDE command
is issued, or when a dynamic load occurs
(that is, when
OS SVC 8 is issued).
Note: Subroutines that are called by dynamic load should
(1r-contain only VCOBs that are resolved within the same
text library member or
(2)
be resident in storage
throughout the processing of the original CMS LOAD or
INCLUDE
command.
Otherwise,
the
entry point
is
unpredictable.

libnamel •••

is the filename of up to eight libraries.
If the MAClIB
form of the GLOBAL command is used, the filetypes of all
files specified must be MAClIB.
If the TXTLIB form of
the oommand is used, the filetypes of all files specified
must be TXTLIB. The libraries are searched in the order
in which they are named. If no library names are
specified, the command cancels the effect of any previous
GLOBAL command.

If you want to use an OS library during the execution of a language
processor, you can issue a GLOBAL command to access the library, as long
as you have defined the library via the FILEDEF command. If you want to
use that library for more than one job, however, you must redefine it
{again, via FILEDEF), since the language processors clear your previous
definition of the library.
Another means for reusing a library is the PERM option of the FIlEDEF
command. If you use PERM, you must clear that FILEDEF before you issue
another GLOBAL for a different library.

148

IB" V"/370: Command Language Guide for General Users

GLOBAL

GLOBAL BICLIB ICCESS SYSftlC
The systeM searches ~ne iCCESS aiCLIB
aissing aacros during coapilations.

and

SISSie

BICL!B files

for

GLOBAL TITLIB COlVERT PLOAT
syste. searches the COlVERT TITLlE and PLOAT TITLIB files
aissing subroutines during subsequent LOID and IICLUDE operations.
ThA

&_-

.LU.L

GLOBAL BICLIB
Cancels the effect of any previous GLOBAL ftACLIB libname co •• and.

DftSGLB002i
DftSGLB014E
DftSGLB0471
DftSGLB108S

PILI 'fn ft' lOT POOID BC=28
IIVALID PUICTIOI 'function' RC=24
10 PUICTIOI SPICIPIED RC=24
ftORE TBAI 8 LIBRARIBS SPBCIPIED RC=88

Section 7: Pormat and Usage BuIes for CftS Com.ands

149

IBCLUDB
INCLUDE

Use the IBCLUDB co.aand to read one or aore TBXT files (containing
relocatable object code) fro. disk and to load thea into storage,
establishing the proper linkages between the files. IBCLUDB is noraally
used to resolve references left unresolved by a previous LOAD or INCLUDE
co •• and.
Refer to Pigure 21 for a description of the handling of
unresolved references. I LOID co ••and .ust have been previously issued
for the IBCLUDE co •• and to produce desirable results. The for.at of the
INCLUDE co •• and is:

INclude

fn...

[(options ••• [) ]]

QE~i.21!§ :

1CLEAR 1
IIOCLEI!1
.J

IftlP I
II0ftAPI

I~IB!

I
IIOLIBEI
L

ITYPE I
I!QTYPBI
L

[STIRT]

1
{ entrY}1 [ORIGII hexloc]
IRBSET
1
I
•
I
L

IRER I
INORBP I

II!! 1
IBOIIV I
L

[S.ftE]

IIUTO 1
INOAUTOI

IDUR I
INODUP 1

are the naaes of the files to be loaded into storage.
Piles aust have a filetype of TEXT and consist of
relocatable object code such as that produced by the
language processor coa.ands.

fn •••

If options were specified with a previous LOID or IICLUDE co •• and,
these options (with the exception of CLEAR and ORIGIN) re.ain set if
SAftB is specified when IICLUDE is issued. Otherwise, the options
assu.e their default settings. If conflicting options are specified,
the last one entered is in effect.
CLEAR

clears the load area in storage to binary zeros before
the files are loaded.

NOCLBIR

does not clear the load area before loading.

RESBT {en.try } resets the
execution
starting
point
previously
set by a LOAD or IICLUDE co •• and.
If entry is
specified, the starting execution address is reset to
the specified location.
If
an asterisk (.) is
specified, the starting point is reset to the location
of the first file or to the address specified as an
operand of an EID card, LDT card, or BITRY card.
ORIGII hexloc

150

begins loading the progra. at the location specified
by hexloc. The variable, hexloc, is a hexadeci.al
nu.ber of up to eight characters. If this option is

IBft Vft/370: Co•• and Language Guide for General Users

IICLUDB
not specified, loading begins at the next available
storage location.
IICLUD! does
not overlay any
previously loaded
files unless
this option
is
specified and the address given indicates a location
within a previously loaded object module:

1!ll

adds inforaation to the LOAD ftAP file.

IOftAP

does not add any inforaation to the LOAD ftAP file.

TYPE

displays the load aap of the files at the terminal, as
well as writing it on the primary disk. This option
is valid only if ftAP is specified or iaplied.

IOTYP!

dQes not display the LOAD ftAP file at the terminal.

1!!

prints invalid card images in the LOAD ftAP file.

10IIV

does not
file.

print invalid

card images

in the

LOAD ftAP

prints replace statement iaages in the LOAD ftAP file.
See the explanation of the CftS LOAD coamand for a
description of the replace (REP) statement.
10RBP

suppresses the
LOAD ftAP file.

printing of replace statements

searches your
disks
undefined references.
IOAUTO

for

TilT

files

in the
resolve

suppresses automatic searching for TBXT files.
searches the text libraries defined
co.mand for aissing subroutines.
any

text

by the

libraries for

GLOBAL

10LIBE

does not search
references.

unresolved

START

begins execution after loading is coapleted.

SAftB

retains the same options (except ORIGII and CLBAR)
that were used by a previous IICLUDB or LOAD coaaand.
Otherwise, the default setting of unspecified options
is assumed. If other options are specified with SAftE,
they override previously specified options.
See the
exaaples.
displays warning aessages at your virtual console when
a duplicate CSICT is encountered during processing.
The duplicate CSBCT is not loaded.

10DUP

does not display warning aessages at your virtual
console when duplicate CSBCTs are encountered during
processing. The duplicate CS!CT is not loaded.

Section 7: lor mat and Usage Rules for CftS Co.mands

151

IICLUDE

Use standard order of search to
locate the TEXT files specified
by fn •••
I
I

*
*

*
.unresolved
* Any *
references
?

·*·*

*
*

Search
terllinated

IYES

*
*

·Is* · *
*BOAUTO
specified
?

·*

*
*

YES

IBO
I

Use standard order of search to
locate files with a filetype of
TEXT and a filenalle corresponding to the unresolved reference
1<
I

*
*

·*·
.unresolved
* Any *
references
?

. *
*IYES

*
*

Search
complete

YES

Search
cOllplete

· *.

*
*

Is
*
*BOLIBE
specified
?

* .

*INO

*
*

*---

Search active text libraries
(those that were previously
specified by a GLOBAL com.and).
Piles are searched in the order I
they are entered in the cOlllland.1

Search terainated
Pigure 21.
152

Resolution of Unresolved References

IBM V8/370: COII.and Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659
INCLUDE

INCLUDE MAIN SUBI DATA (RESET MAIN MAP START)
Brings the files named MAIN TEXT, SUBI TEXT, and DATA TEXT into real
storage and appends the. to files which were previously loaded.
Information about these loaded files is added to the LOlD MAP file.
Execution begins at entry point MAIN.
LOAD MYPROG (NOMAP NOLI BE NOREP)

INCLUDE MYSUB (MAP SAME)
During execution of the LOAD command, the file named MYPROG TEXT is
brought into real storage. The following options are in effect: NOMAP,
NOLIBE, NOREP, NOTYPE, INV, AUTO. During execution of the INCLUDE
command, the file named MYSUB TEXT is appended to MYPROG TEXT. The
following options are in effect:
MAP, NOLIBE, NOREP, NOTYPE, INV, AUTO
!2!~:

After you IPL CMS, at least one LOAD command must be issued before
INCLUDE can be used with predictable results.

DMSLI07401 EXECUTION BEGINS •••
START was specified with INCLUDE and the loaded program has begun
execution. Any further responses are from the program.
INVALID CARD - XXX ••• XXX
INV was specified with LOAD and an invalid card has been found.
The message and the contents of the invalid card
(xxx ••• xxx) are
listed in the file LOAD MAP. The invalid card is ignored and
loading continues.
CONTROL CARD - •••
A loader or library-search control statement was encountered (that
is, ENTRY or LIBRARY). See the description of the LOAD command for
the use of ENTRY and LIBRARY control cards.
This response is
placed in the LOAD MAP file only.

DMSLI0001E
DMSLI0002E
DMSLI0003E
DMSLI0005E
DMSLI0021E
DMSLI0029E
DMSLI0055E
DMSLI0056E

NO FILENAME SPECIFIED RC=24
FILE 'fn ft' NOT FOUND RC=28
INVALID OPTION 'option' RC=24
NO option SPECIFIED RC=24
ENTRY POINT 'name' NOT FOUND RC=40
INVALID PARAMETER 'param' IN THE OPTION 'option' FIELD
NO ENTRY POINT DEFINED RC=40
FILE 'fn ft' CONTAINS INVALID RECORD FORMATS RC=32
Section 7: Format and Usage Rules for CMS Commands

RC=24

153

GC20-1804-3 Page Modified by TNL GN20-2659
INCLUDE
DM5LI01045
DM5LI01055
DM5LI01095
DM5LIOl165
DM5LI01685
DM5LI01695
DM5LI0201W
DM5LI0202W
DM5LI0203W
DM5LI0206W
DM5LI0907T

154

ERROR 'nn' READING FILE 'fn ft fm' FROM DI5K RC=100
ERROR 'nn' WRITING FILE 'fn ft fm' ON DI5K RC=100
VIRTUAL 5TORAGE CAPACITY EXCEEDED RC=104
LOADER TABLE OVERFLOW RC=104
P5EUDO REGI5TlR TABLE OVERFLOW RC=104
E5DID TABLE OVERFLOW RC=104
THE FOLLOWING NAME5 ARE UNDEFINED: RC=4
DUPLICATE IDENTIFIER 'identifier' RC=4
"5ET LOCATION COUNTER" NAME 'name' UNDEFINED RC=4
P5EUDO REGI5TER ALIGNMENT ERROR RC=4
I/O ERROR ON FILE 'fn ft fm'
RC=256

IBM VM/370: Command Language Guide for General Users

LISTDS
LlSTDS

Use the LISTDS command to list at your terminal information describing
the data sets residing on an OS disk, or the files on a DOS disk.
The format of the LISTDS command is:

LISTDS

I 1
I
I dsname I
L

( f m) [ ( 0 Pti 0 n s ••• [) ]]

l* J

[FORMAT]
[PDS

]

indicates that you want to enter the OS data set name or DOS
file-id from your terminal.
If you enter the question mark
(1), CMS requests that you enter the OS data set name or DOS
file-id exactly as it appears in the data set or file.
Do
not omit the periods that separate the qualifiers of an OS
data set name, but do not insert periods where they do not
appear.
quall[.quaI2.qualn]
where quaIl, qual2, through qualn are qualifiers for the data
set name or file-ide
Using this form, you can specify data
set names
or file-ids
that contain
embedded special
characters such as blanks and hyphens.
-

dsname

is the OS data set name or DOS file-id and takes the form:
quall[ qual2 qualn]
where quaIl, qual2, through qualn are the qualifiers for the
data set name or file-ide
Each qualifier must not exceed 8
characters and must be separated from other qualifiers by
blanks, not periods.
(This form can be used for DOS file-ids
only if they comply with the OS naming convention of one- to
eight-byte qualifiers separated by periods, to a maximum of
44 characters,
including periods.)
For example, for an OS
data set or DOS file named MY.FILE.IN, you enter:
LISTDS MY FILE IN

is the filemode of the data set or file being listed.

indicates that you want the data set name (or file-id) and
filemode listed for all of the data sets (or files) on all of
the OS or DOS disks currently accessed.

section 7: Format and Usage Rules for CMS Commands

155

GC20-1804-3 Page Modified by TNL GN20-2659
LISTDS

FORMAT
FO

displays the date, disk label, file.ode, and data set name for
the OS data set as well as the REeFM, LRECL, BLKSIZE, and
DSORG operands.
For a DOS file, LISTDS displays the date,
disk label, filemode, and file-id, but gives no information
about the RECFM, LRECL, and BLKSIZE operands (two blanks
appear for each); DSORG is always PS.

PDS

displays the member names of references
Access Method (PAM) data sets.

to OS

Partitioned

The following is an example of LISTDS with the FORMAT and
and the output resulting from the command.

PDS options

listds d (fo pds)
RECFM LRECL BLKSI
80
800
FB
MEMBER NAMES:
ABEND
ATTACH
FIND
PUT
RECFM LRECL BLKSI
80
80
F

DSORG
DATE
PO 01/31/75

LABEL
OSSYSl

FM
D

DATA SET NAME
SYS1.MACLIB

BLDL
BSP
READ
WRITE
DSORG
DATE
PS 01/10/75

DETACH
DCB
CLOSE
XDAP
LABEL
FM DATA SET NAME
SAMPLE
OSSYSl
D

DEVTYPE

DMSLDS220R ENTER DATA SET NAME:
The LISTDS command with the? operand was issued. Enter an OS data
set name in the form quall.quaI2.qualn; where quaIl, qual2, through
qualn are the qualifiers of the OS data set name.

DMSLDS002E
DMSLDS003E
DMSLDS048E
DMSLDS069E
DMSLDS221E
DMSLDS222E
DMSLDS223E
DMSLDS231E

156

DATA SET NOT FOUND RC=28
INVALID OPTION 'option' RC=24
INVALID MODE 'mode' RC=24
DISK 'mode' NOT ACCESSED RC=36
INVALID DATA SET NAME RC=24
I/O ERROR READING 'data set name' FROM OS DISK RC=28
NO FILENAME SPECIFIED RC=24
I/O ERROR READING VTOC FROM ••• -DISK (OS)
RC=28

IBM VM/370: Command Language Guide for General Users

LISTPILE
LISTFILE

Use the LISTPILE co.mand to obtain specified information about your CftS
files residing on accessed disks. The information mav be either
displayed at the terainal or used to create a special EIEC file on
disk. 111 operands are optional; if no operands are specified, a list
of default information about each file on your primary read/write disk
is displayed at the terminal. The format of the LISTPILE command is:

Listfile

~~~

Ifn 1ft Ifalll
1* I * I * III

option§:

[(options ••• [)]]

IHeader I
IIOHeaderl

IExec I
I APpend I

IPlame I
IPType I
I Pft 2 de I
IPOrmatl
IILloc I
I Date I
ILabel I
L

is the filename of the files
collected.
If an asterisk
filenaaes are used.

for which information is to be
is coded in this field, all

is the filetype of the files
collected.
If an asterisk
filetypes are used.

for which inforaation is to be
is coded in this field, all

is the filemode of the files for which information is to be
collected. If this field is oaitted, only the priaary disk is
searched. If an asterisk is coded, all disks are searched.

lote: An asterisk (*), iaaediately preceded by any nuaber of characters
for fn or ft, searches for the specified characters as the leading
characters for that identifier.
Por example, LISTPILE IBC* ISSE!BLE
prints the identifiers for all ISSE!BiE files with filenaaes beginning
with IBC.

BEIDER

includes coluan headings in the listing.
BEIDER is the
default if any of the "Suppleaental Information" options
are specified. The for.at of the heading is:
PILEII!E PILE TYPE Pft PORftAT RECS BLOCKS DITE TlftE LIBEL

SOHEIDER

does not include column headings in the list. IOHEIDER is
the default if only
filenaae, filetype, or fileaode
information is requested.

section 7: Poraat and Usage Rules for CftS Coaaands

157

LISTFILE

EXEC

creates a file of 80-character records (one record for each
of the files which satisfies the given file identifier) on
the priaary disk. The file that contains these records is
called CftS EXEC Al.
If a file with this name already
exists, the existing one is erased and a new one is created
(unless the APPEND option is specified, in which case the
existing file is retained and the new entries are appended
to it). The EXEC procedure thus created contains two
symbolic variables, &1 and &2. This CftS EXEC file is used
with the EXEC command, but it can also be processed as any
other file (that is, printed, displayed, edited, added to,
changed, and so forth). The header is not included in the
file.

APPEND

appends the EXEC list created to the existing CftS EXEC Al
file. If the EXEC option is specified instead of APPEND,
any existing CftS EXEC file is erased and replaced by the
file created by this LISTFILE command. If this option is
specified and no CftS EXEC file exists, one is created.

In!Q£~ati2~ Reque~!

gptions

Only one of these options need be specified. If one is specified,
any options with a higher priority are also in effect. If none of
the following options are specified, the default information request
options are in effect.

FNAftE

creates a
is 1.

list containing only filenames.

FTYPE

creates a list containing only
option priority is 6.

FftODE

creates a
list containing filenames,
filemodes. option priority is 5.

PORftAT

includes the record format and logical record length of the
of each file in the list. option priority is 4.

ALLOC

includes the amount of disk space that CftS has allocated to
the specified file in the list. The quantities given are
the number of 800-byte blocks and the number of logical
records in the file. Option priority is 3.

DATE

includes the date the file was
The fora of 'the date is:
month/day/year

Option priority

filenames and

filetypes.

filetypes,

last written in

and

the list.

hour:ainute

Option priority is 2.
LABEL

158

includes the label of the disk on which the file resides in
the list.
Option priority is 1.

IB! V!/310: Comaand Language Guide for General Users

LISTFILE

LISTPILE

ISSEftBLE

(LIBEL)

LABEL is the lowest priority option; therefore, all other options are
also in effect. III information about the files with a filetype of
ISSEftBLE is displayed at the ter.inal. The header is displayed because
LABEL is a supplemental information option.
The following is displayed at the terminal:
PILEllftE PILETYPE

Pft

PORftlT

RECS BLOCKS

DITE

TIftE

LIBEL

r ,

ISSEftBLE

IPI
fa IVI lrecl norecs noblks am/dd/yy hh:m .. volid
L

One entry is displayed for each file with a filetype of ASSEftBLE.

is the filename of the file.

ISSEftBLE

is the filetype specified in the command.

is the file.ode of the file.

r ,

IPI
IVI
L

is the file for.at: P
V

= fixed length
= variable length

record length of the largest

record in the

lrecl

is the logical
file.

norecs

is the nu.ber of logical records in the file.

Dobiks

is 1:ne Du.ber of physical blocks
disk •

• m/dd/yy

is the date (month/day/year) that the file was created.

hh:.m

is the tiae (hours:minutes) that the file was created.

volid

is the volume serial number of
the file resides.

If the EXEC option is not
displayed at the terminal.

specified,

the

that the file occupies on

the virtual disk

on which

requested information

section 7: Pormat and Usage Rules for CftS Com.ands

159

LISTFILE

DftSLST002E
DftSLST003E
DftSLST037E
DftSLST048E
DftSLST066E
DftSLST069B
DftSLST070E
DftSLST105S

FILE lOT POUID RC=28
IIVILID OPTIOI 'option' RC=24
DISK '.ode' IS REID/OILY RC=36
IIVILID ftODE '.ode' RC=24
'option' and 'option' IRE COIPLICTIIG OPTIOIS RC=24
DISK '.ode' lOT ICCBSSID BC=36
INVILID PIRlftETEB 'para.' RC=24
BRROR Inn' iRITIIG PILI 'fn ft f.' 01 DISK BC=100

lote: You can invoke the LISTPILE co •• and fro. the ter.inal, fro. an
iXIC file, or as a function fro. a progra •• If LISTPILI is invoked as a
function or fro. an EIIC file that has the SCOITROL IOftSG option in
effect, the DftSLST002E PILI lOT POUID error .essage is not issued.

160

IBft Vft/370: Co •• and Language Guide for General Users

lOAD
LOAD

Ose the lOAD com.and to read one or more TEXT files '(containing
relocatable object code) from disk and to load them into virtual
storage, establishing the proper linkages between the files.
!2te§:
1.
The lOAD
file.

command requires

a read/write A-disk

to contain

a work

If you are loading a program into the transient area see Note 2 for
the GENMOD co •• and.
The format of the lOAD command is:

.--

LOAD

fn •••

[ (options ••. [) ]]
r
,
r
,
y
Q£!~Q~§:
IClEAR
I
~RESET {en;r }:

I!Q£b~!RI

L
i

I~Jf
I
INOMAPI
L

I
.J

Ibl~~

I
IBOlIBEI

[START]

.J
L
L-____________________

fn •••

I!Ql!f~1
L

r
ITYPE

10RIGIN {heXlOC}1
I
TRANS
I
L

...
II!!
I
INOINVI

r
I!!~~

I
INOREPI

IJ!!l.Q
I
IBOAOTOI

r
I~!!f

INODOPI
L

specifies the names of the files to be loaded into storage. The
files must have a filetype of TEXT and consist of relocatable
object code such as that produced by the language processors.
!Q!~:

If you have a program that issues a dynamic load command
(OS SVC 8)
for a subroutine that (1)
is a CSECT in a CMS text
library member and (2) contains VCONs· for entry points not in
the same member, that subroutine must be explicitly loaded with
the program that uses it.
Otherwise, the entry point returned
by the CMS lOAD command is unpredictable.

If conflicting
effect.

options are

specified, the

last one

CLEAR

clears the load area in storage to binary
object files are loaded.

!Q~b~!!!

does not clear the load area before loading.

entered is

zeroes before the

RESET { en ;ry}
sets the starting location for the programs currently loaded.
The operand, entry, must be an external name
(for example,
section 7: Format and Osage Rules for CMS Commands

161

GC20-1804-3 Page Modified by TNL GN20-2659
LOAD
CSECT or ENTRY) in the loaded programs. If RESET is not
specified, the default entry point is either (1)
the entry
point of the first file loaded, (2)
the address on an END
card, (3) the location of a name occurring on an LOT card, or
(4) the location of the operand on an ENTRY statement. If
is entered the results are the same as if the RESET option
were omitted.

ORIGIN

hexloc }
{ TRANS
loads the program beginning at the location specified by
hexloc; this location must be in the CMS nucleus transient
area or in the user area.
The location, hexloc,
is a
hexadecimal number of up to eight characters. If TRANS is
specified, the file is loaded into the CMS nucleus transient
storage locations.
If this option is not specified, loading
begins at the first available user storage location.
!g!~:

Any program loaded into the
starting address of X'EOOO'.

~~R

creates the file LOAD MAP on the primary disk.

NOMAP

does not create the file LOAD MAP.

TYPE

displays the LOAD MAP file at the terminal.
valid only if the MAP option is in effect.

!Q1!f~

does not display the LOAD MAP file at the terminal.

l!Y

includes the invalid card images in the LOAD MAP file.

NCINV

does not
file.

B~R

includes the replace statements in the LOAD MAP file.

NCREP

does not include
file.

include the

invalid card

the

searches your virtual
undefined references.

162

transient area must have a

images in

replace statements

disks

for

This option is

TEXT

files

the LOAD

MAP

resolve

NOAUTO

suppresses automatic searching for TEXT files.

11]~

searches the text libraries for missing subroutines. If text
libraries are to be searched for TEXT files,
they must
previously have been defined by a GLOBAL command.

NCLIBE

does
not search
references.

START

executes the program l:eing loaded when loading is completed.
LOAD does not normally begin execution of the loaded files.
To begin execution immediately upon successful completion of

the

text

lil:raries

for

IBM VM/370: Command Language Guide for General Users

unresolved

LOID
loading, STIRT can be specified. LaID then transfers control
to an entry point in the program. The default entry point is
(1) the address. specified in the operand field of the first
EID statement containing a non-blank operand field,
(2) the
address of a name on an LDT statement, (3)
the beqinninq of
the first file loaded
(if all EID state.ents in-the TEXT
files contain blank operand fields), or
(4)
the EITRY
specified.
displays warning messages at your terminal when a duplicate
CSBCT is encountered during process~ng. The duplicate CSECT
is not loaded.

NODUP

does not display warning messages at your terminal
duplicate CSECTS are encountered during processing.
duplicate CSECT is not loaded.

PILES CREITED BY THE
temporary-Vorkfile:---

12!R

~Q~~!!R:

The

LOID command

produces

when

The
one

DMSLDR SYSUTl
This temporary work file is placed
be available.

on the read/write I-disk, which must

LOID MIP FILE: Unless the IOMIP option is specified, a load map is
created-on--the primary disk each time the LOID command is issued. I
load map is a file that contains the location of control sections and
entry points of files loaded into storage.
It may also contain messages
and card images for invalid cards or replace cards that exist in the
loaded files.
This load map is normally created as a file with the file
identification LOID MIP. Only one such file may exist on the primary
disk.
Each time LaID is issued, a new LOID MIP file replaces any
previous LaID MIP file.
If invalid card images exist in the file or files that are being
loaded, they are listed with the message INVILID CIRD in the LaID MIP
file. To suppress this listing in the load map, the BOIBV option must
be specified.
If replace (REP) statements exist in the file being loaded, they are
included in the LOID MIP file.
To suppress this listing of REP
statements, the IOREP option must be specified.
DUPLICITE CSECTS: Duplicate CSECTs (control sections) are bypassed by
the loader:--Cnly the first CSECT encountered is physically loaded. The
duplicates are not loaded. I
warning message is displayed at your
terminal if· you specified the DUP option.
1Q!R~~

CO!IjQl ~TITEM~!I2: .Five types of control statements can be added
to a TEXT file.
These are the set location counter
(SLC), the include
control section
(ICS), the replace (REP), the ENTRY, and the LIBRIRY
statements. These are used to set the virtual storage location where
the LaID command begins placing the file, to make corrections and
additions to the relocatable object code in virtual storage once the
file is loaded, to specify entry points, and to specify references that
are not to be resolved. These statements can be added to the TEXT files
already punched and can then be read back in, or they can be added using
the EDIT command.

section 7: Format and Usage Rules for CMS Commands

163

LOAD
set Location counter
(~1f)
~tgt~~~t: The
SLC statement sets the
Iocatlon-cQunter--used with the loader.
The file loaded after the SLC
statement is placed in virtual storage beginning at the address set by
this SLC statement. The SLC statement has the format shown in Figure
22.
It sets the location counter in one of three ways:
1.

with the absolute virtual address specified as a hexadecimal number
in columns 7-12.

with the symbolic address already defined as a
entry point. This is specified by a symbolic
columns 17-22.

If both a hexadecimal address and a symbolic name are specified,
the absolute virtual address is converted to binary and added to
the address assigned to the symbolic name; the resulting sum is
the address to which the loader's location counter is set. For
example, if 0000F8 was specified in columns 7-12 of the SLC card
image and GAMMA was specified in columns 17-22, where GAMMA has an
assigned address of 006100 (hexadecimal), the absolute address in
columns 7-12 is added to the address assigned to GAMMA g1v1ng a
total of 0061F8.
Thus, the location counter would be set to
0061F8.

program name
name punched

or
in

If there are blanks in both columns 7-12 and 17-22, or the symbolic
name has not yet been defined, the response INVALID CARD xxx ••• xxx
is displayed or, depending on the option (NOINV or INV) ~pecified,
is written in the LOAD MAP file.
If only the symbolic address is
to be used, columns 7-12 must be left blank or be all zeros. If
only the absolute address is to be used, columns 17-22 must be left
blank.

Column
1

contents
Load control statement identification (12-2-9 punch).
Identifies this as a statement acceptable to the loader.
SLC -- identifies the type of load statement.

Blank.

7-12

Hexadecimal address to be added to the value of the symbol,
if any, in columns 17-22. It must be right-justified in
these columns, with unused leading columns filled with
zeros.

13-16

Blank.

17-22

Symbolic name whose assigned location is used by the
loader. Must be left-justified 'in these columns. If blank,
the address in the absolute field is used.

Blank.

24-72

May be used for comments or left blank.

73-80

Not used by the loader. You may leave these columns
blank or insert program identification for your own
convenience.

Figure 22.

164

SLC Statement Format

IBM VM/370: Command Language Guide for General Users

LOAD
~~ader I~~miBg!~

(~RI) ~tal~~~~l: The LDT
statement is used in a text
library as the last record of a member.
It indicates to the loader that
all records for that meaber were processed. The LDT statement can
contain a name to be used as the entry point for the loaded member. The
LDT statement has the for.at shewn in Figure 23.

r------------------------------------------------------------------------,
Coluan
contents
1

Load control statement identication (12-2-9 punch) •
Identifies this as a statement acceptable to the loader.

2-4

LDT -- identifies type of statement.

5-16

Bot used.

11-24

Blank or entry name (left justified padded with blanks to
8 characters).

25-80

Not used.

Pigure 23.

LDT statement Poraat

!~~lud~ ~~B!~~l ~ect~~~

(!£~) ~ta!~B!: The ICS
state.ent changes the
length of a specified control section or defines a new control section.
It should be used only when REP statements cause a control section to be
increased in length. The format of an ICS state.ent is shown in Figure
24. An ICS statement must be placed at the front of the file or TEXT
file.

Column
1

contents
Load control statement identification (12-2-9 punch).
Identifies this as a statement acceptable to the loader.

2-4

ICS -- identifies the type of load statement.

5-16

Blank.

11-22

Control section name -- left-justified in these columns.

Blank.

25-28

(coama).

Bexadecima~ length in bytes of the control section. This
must not be less than the actual length of the previously
specified control section.
It must be right-justified in
these columns with unused leading columns filled with
zeros.

Blank.

30-12

Bay be used for comments or left blank.

13-80

Bot used by the loader. You may leave these columns blank
or insert prograa identification for your own convenience.

Pigure 24.

ICS statement Pormat
section 1: Format and Usage Rules for CftS Commands

165

LOAD
ReE!!£~
(!JR) ~tat~~!: A REP statement allows instructions and
constants to be changed and additions aade. The REP state.ent aust be
punched in hexadecimal code. The format of a REP statement is shown in
Figure 25.
The data in coluans 11-10 (excluding the comaas) replaces
what has already been loaded into virtual storage, beginning at the
address specified in coluans 1-12. REP stateaents are placed in the
file either (1) immediately preceding the last stateaent (EID stateaent)
if the text deck does not contain relocatable data such as address
constants, or (2) iaaediately preceding the first RLD (relocatable
dictionary) stateaent if there is relocatable data in the text deck. If
additions made by RBP statements increase the length of a control
section, an ICS statement, which defines the total length of the control
section, must be placed at the front of the deck.

Column

Contents
Load control statement identication (12-2-9 punch).
Identifies this as a stateaent acceptable to the loader.

2-4

REP -- identifies the type of load stateaent.

5-6

Blank.

1-12

Bexadeciaal starting address of the area to be replaced as
assigned by the assembler. It must be right-justified in
in these columns with unused leading columns filled with
zeros.

13-14

Blank.

15-16

BSID (Bxternal Symbol Identification) -- the hexadecimal
number assigned to the control section in which replacement
is to be made. The LISTING file produced by the compiler
or assembler indicates this number.

11-10

A aaximua of 11 four-digit hexadeciaal fields, separated by
coamas, each replacing one previously loaded halfword (two
bytes). The last field must not be followed by a coama.

11-12

Blank.

13-80

Not used by the loader. This field aay be left blank or
prograa identification may be inserted.

Figure 25.

REP Statement Format

ENTRY Statement: The BITRY statement specifies the first instruction to
be-executed:--It can be placed before, between, or after object modules
or other control stateaents. The foraat of the ENTRY statement is shown
in Figure 26. The external name is the name of a control section or an
entry name in the input deck. It must be the naae of an instruction,
not of data.

EBTRY
Figure 26.

166

external name

BBTRY Statement Format

IBM VM/310: Co.mand Language Guide for General Users

LOAD

The loader selects the entry point for the
to the following hierarchy:

loaded program according

From the parameter list on the START command.

Prom the
entered.

Prom the last EITRY statement in the input.

From the last LDT statement in the input.

Prom the first asseabler- or compiler-produced END statement that
specifies an entry point if no ENTRY statement is in the input.

Prom the first byte of the first control section of the loaded
program if there is no ENTRY statement and no assembler- or
compiler-produced EID statement specifying an entry point.
Por
example:

last

RESET

operand in

the

LOAD

INCLUDE

command

EITRY GO
where GO is defined as the external name of the first instruction
to be executed when the program is loaded.
The address of the
instruction, indicated by the symbolic name GO, is specified by the
loader as the starting point of the program when it is executed.
LIBRARY Statement: The LIBRARY statement can be used to specify the
never=calr-functIon. The never-call function (indicated by an asterisk,
*, as the first operand) specifies those external references that are
not to be resolved by the automatic library call during any loader step.
It is negated when a deck containing the external name referred to is
included as part of the input to the loader. The format of the LIBRARY
statement is shown in Pigure 27.
The external reference refers to an
external reference that may be unresolved after input processing. It is
not to be resolved. Multiple external references within the parentheses
aust be separated by commas. The LIBRARY statement can be placed
before, between, or after object decks or other control statements.

LIBRARY
Pigure 27.

LIBRARY

(external reference)

LIBRARY Statement Format

(SINE)

The * specifies the never-call function.
SINE is an external reference
in the output.
As a result, if SINE is unresolved after input
processing, no automatic library call is made.

section 7: Pormat and Usage Rules for CMS Commands

167

LOAD

DftSLI01401 EIECUTIOI BEGIIS •••
START was
execution.

specified with LOAD and the loaded progra.
Any further responses are fro. the progra ••

starts

IIVALID CARD - xxx ••• xxx
IIV
The
are
and

was specified with LOAD and an invalid state.ent was found.
aessage and the contents of the invalid state.ent (xxx ••• xxx)
listed in the file LOAD ftAP. The invalid state.ent is ignored
loading continues.

COITROL CARD A loader or library-search control state.ent (that is, IITRY or
LIBRARY) was encountered. This response is placed in the LOAD !AP
file.

D!SLI00011
D!SLI0002E
D!SLI0003E
D!SLI0004E
D!SLI0005E
D!SLI0021B
D!SLI0029E
D!SLI0055B
D!SLI0056E
D!SLI0104S
D!SLI0105S
D!SLI0109S
D!SLI0116S
D!SLI0168S
D!SLI0169S
D!SLI0201W
D!SLI0202W
D!SLI0203W
D!SLI0206i
D!SLI0901T

168

10 FILIIA!E SPBCIFIED RC=24
FILE 'fn ft' lOT FOUID RC=28
IIVALID OPTIOI 'option' RC=24
EITRY POIIT 'na.e' lOT FOUID RC=40
10 option SPECIFIED RC=24
BITRY POIIT 'na.e' lOT rOUID RC=40
IIVALID PARA!ETER 'para.' II THE OPTIOI 'option' FIBLD
10 BITRY POIIT DBFIIBD RC=40
rILE 'fn ft~ COITAIIS IIVALID RECORD rOR!ATS RC=32
BRROR Inn' RBADIIG FILB 'fn ft f.' rRO! DISK RC=100
ERROR Inn' WRITIIG FILl 'fn ft f.' 01 DISK RC=100
VIRTUAL STORAGB CAPACITY EICBBDED RC=104
LOADIR TABLE OVERPLOW RC=104
PSBUDO REGISTEB TABLB OVBRFLOW RC=104
ISDID TABLE OVBRFLOW RC=104
THI POLLOWIIG IA!BS IRI UIDBPIIBD: RC=4
DUPLICATE IDEITIFIBR 'identifier' RC=4
"SBT LOCITIOI COUlTER" II!B 'na.e' UIDBFIIBD RC=4
PSBUDO RBGISTBR ALIGI!EIT BRROR RC=4
I/O ERROR 01 PILB 'tn ft f.' RC=256

IB! V!/310: Co •• and Language Guide tor General Users

RC=24

GC20-1804-3 Page Modified by TNL GN20-2659
LOADMOD
LOADMOD

Use the LOADMOD command to bring a disk file into storage.
The file
must be in absolute core-image format as created by the GENMOD command.
The format of the LOADMOD command is:

LOADMod

fn [ft fm]

is the filename of the file to be loaded into storage.

is the filetype of the
filetype must be MODULE.

is the filemode of the module to be loaded.

file to

loaded.

If supplied,

the

If filetype and file mode are not supplied, the standard order of search
is used to locate a file with the specified filename and a filetype of
MODULE.

DMSMOD001E
DMSMOD002E
DMSMOD032E
DMSMOD037E
DMSMOD040E
DMSMOD070E
DMSMCD104S
DMSMOD109S
DMSMOD116S

NO FILENAME SPECIFIED RC=24
PILE 'fn ft' NOT FOUND RC=28
INVALID FILETYPE 'ft' RC=24
DISK 'mode' IS READ/ONLY RC=36
NO FILES LOADED RC=40
INVALID PARAMETER 'param' RC=24
ERROR Inn' READING FILE 'fn ft fm' FROM DISK
VIRTUAL STORAGE CAPACITY EXCEEDED RC=104
LOADER TABLE OVERFLOW RC=104

RC=100

Section 7: Format and Usage Rules for CMS Commands

169

81CLIB
MACLIB

Use the 81CLIB coaaand to create and aodify .acro libraries.
A .acro
library consists of aeabers (.aero definitions) and a dictionary which
contains the naae of the .aero (aeaber naae), its size, and its location
relative to the beginning of the library.
The B1CLIB coa.and checks
only the aacro definitions of B1CRO and 8BID state.ents for errors. The
for.at of the BACLIB co•• and is:

8AClib

GEl
ADD
REP

libnaae

fn1 [fn2 ••• ]

DEL

libnaae

.e.berna.e1 [.e.bernaae2 ••• ]

C08P

libna.e

81P

libnaae [ (options ••• [) ]]
option,!:
r

ITBR8 I
IDI.§! I
I PRIIT I
L

GEl

generates a C8S .acro library.

ADD

adds ae.bers to an existing .acro library.

RBP

replaces existing .e.bers in a .acro library.

DBL

deletes .e.bers fro. a .acro library.

C08P

co. pacts a .aero library.

8AP

lists certain infor.ation about the .e.bers in a .aero
library.
lvailable infor.ation includes .e.ber na.e,
size, and location relative to the beginning of the
library.

libna.e

is the filena.e of a .acro library. If the file already
exists, it .ust have a filetype of BACLIB; if it is being
created, it is given a filetype of 81CLIB.

fn1 [fn2 ••• ]

are the na.es of the .acro definition files to be used.
A .acro definition file .ust reside on a CBS disk and its
filetype .ust be either BACRO or COPY. Bach file .ay
contain one or .ore .acros and .ust contain fixed-length,
SO-character records.
In a 8ACRO file, the .acro na.e is taken fro. a prototype
state.ent within the .acro.
If the filetype is COpy and the file contains .ore than
one .acro, each .acro .ust be preceded by a control
stateaent of the following for.at:

170

IB8 Y8/370: Co•• and Language Guide for General Users

!ICLIB
*COPY membername
The name on the control statement is the name of the
macro when it is placed in the macro library. If there
is only one _acrQ in the COpy file and it is not preceded
by a COpy control statement, its name (in the macro
library) is the saae as fn. If there are several macro
definitions in a COpy file and the first one is not
preceded by a COpy control statement the entire file is
treated as one macro.
ae.berna.el ••• is the naae of a macro which exists in a macro library.

is the device to contain the output generated by the !IP
function. Yalid device names are DISK (disk file), PRINT
(virtual spooled printer), and TIR! (terminal).
If no
device is specified, DISK is assumed. Since these are
the only options allowed in the !ICLIB command, only the
first word after the left parenthesis is exaained. If
the DISK option is specified, the information is written
to a file named 'libname !IP 11'. If a file with that
name previously existed it is replaced by the new file.

TIR!
R~!

The following
coamand.

paragraphs describe each of

the functions of

the !ICLIB

The GEN (generate) function creates a new C!S macro library with the
filename and filetype you specify on the !ICLIB co.aand. If a macro
library with the saae filenaae already exists, it is erased and replaced
by the new macro library. The new file is created froa input files
specified by fni fn2 ••• For exaaple:
!ICLIB

Gil

OS!IC

lCCBSS

TI!!

PUT

R!GBOU

Creates a new aacro library with the file identification OS!IC !ICLIB
from macros existing in the files with the file identifiers:
lCCESS {!ICRO}, TI!I {,B1CRO}. PUT {!ICRO} and REGEOU {B1CRO}
COpy
COpy
COpy
COpy
If a file naaed OS!IC !ICLIB already exists, that file is erased.

Assume that the files ACCISS !ICRO, TIBI COPY, PUT B1CRO, and REGBOU
COpy exist and contain macros in the following fora.
ACCESS !ICRO

-----------GIT
PUT

TI!I COPY

----_ ...---

*COPY TTI!IR
TTI!BR
*COPY STI!ER
STI!BR

PUT B1CRO
-----~---

PUT

REGEOU COpy

----------IRBG
YRBG

Section 7: Por.at and Usage Rules for C!S Coa.ands

171

MICLIB

The resulting file OSftlC MICLIB contains the following members:
GET
PUT
TTIMER
STIMER
POT
REGEQU
Bote: The PUT macro, which appears twice in the input to the command,
also appears twice in the output. The MICLIB command does not check for
duplicate macro names. If, at a later time, the PUT macro is requested
from OSMIC MICLIB, the first PUT macro encountered in the dictionary is
used.

The IDD function appends the members described by
files (fnl fn2 ••• ) to an existing macro library.
MICLIB

IDD

Issume that
explana tion of'
follows.

OSMIC

the macro definition

DCB

OSMIC MICLIB was created
the GEl function and the

by the example in the
file DCB COpy exists as

*COPY DCB
DCB macro definition
*COPY DCBD
DCBD macro definition
The resulting OSMIC MICLIB contains the following members:
GET
PUT
TTIMER
STIftER
PUT
REGEQU
DCB
DCBD

REP (replace) is effectively a delete function followed by an IDD
function. REP deletes the dictionary entry for the macro definition in
the files specified by fnl fn2 •••
It then appends the new macro
definitions to the macro library and creates new dictionary entries.
Por example, assume that a macro library MYBIC BICLIB contains the
.embers I, B, and C, and that the following command is entered:
BICLIB

REP

BIBIC

The files represented by file identifiers I BICRO and C BICRO each have
one macro definition.
lfter execution of the command, BIBIC BICLIB
contains members with the same names as before, but the contents of 1
and C are different.
172

IBB VM/370: Command Language Guide for General Users

MACLIB

The DEt (delete) function reaoves the specified aacro name froa the
:acro library dictionary and compresses the dictionary so there are no
unused entries.
The macro definition still occup1es space in the
library, but since no dictionary entry exists it cannot be accessed or
retrieved.
If you attempt to delete a macro for which two macro
definitions exist in the macro library, only the first one encountered
is deleted. For example:
"ACLIB

DEL

OSMAC

GET

PUT

TTIMER

DCB

deletes macro naaes GET, PUT, TTIMER, and DCB from the dictionary of the
macro library named OSMAC MACLIE. Assuae that OSMAC exists as in the
ADD function example.
After the above com.and, OSMAC contains the
following members:
STIMER
PUT
REGEQU
DCBD

Execution of a MACLIB co.mand with the DEL or REP functions can result
in unused space within a aacro library. The COMP (compress) function is
used to compress a macro library (that is, remove any macros for which
there is no dictionary entry). This function uses a temporary data set
named MACLIE CMSUT1. For example, the command:
MACLIB

CaMP

MIMAC

Compresses the library MIMAC MACLIB.

The MAP function creates a list containing the name of each aacro in the
dictionary, the size of the macro, and its position within the macro
library.
Iou can specify the device to which the list is to be
written. Acceptable devices are:
the list is placed in a
'libnaae MAP Al'.

file with the

PRlaT

the list is spooled to the printer.

TERM

the list is displayed at the terainal.

file identification

section 7: Format and Usage Rules for CMS Co.mands

173

KACLIB

When the
is:

!AP operand is specified

on the KACLIB co •• and,

the response

.eaberna.e size location

D!SLB!001E NO FILENA!E SPECIFIED RC=24
DKSLB!002E FILE 'fn ft' lOT FOUND RC=28
D!SLB!002W FILE 'fn ft f.' NOT FOUND RC=4
DKSLB!003E IIVALID OPTIOI 'option'
RC=24
D! SLB!013 W !E!BER 'name' lOT FOUND IN LIBRARY 'fn ft f.' RC=4
RC=24
DKSLB!014E INVALID FUNCTION 'function'
DKSLB!037E DISK 'mode' IS READ/ONLY RC=36
DKSLB!046E NO LIBRARY NAME SPECIFIED RC=24
DMSLB!047E 10 FUICTION SPECIFIED RC=24
DMSLBK056E FILE 'fn ft f.' CONTAINS INVALID RECORD FOR!ATS RC=32
DMSLB!070E INVALID PARAMETER 'param'
RC=24
D!SLBM104S ERROR Inn' READING FILE 'fn ft f.' FRO! DISK RC=100
DMSLB!105S ERROR Inn' WRITING FILE 'fn ft f.' ON DISK' RC=100
D!SLBM109S VIRTUAL STORAGE CAPACITY EICEEDED RC=104
LIMIT EICEEDED[,
LAST MEMBER
NAME ADDED
D!SLB!157S !ACLIB
'.e.berna.e'] RC=88
D!SLB!167S PREVIOUS !ACLIB FUNCTION lOT FIIISHED RC=88
D!SLB!213W LIBRARY 'fn ft f.' NOT CREATED RC=4
DMSLB!907T I/O ERROR 01 FILE 'fn ft fa'
RC=256

174

IB! V!/370: Co •• and Language Guide for General Users

WAS

ftODftAP
MODMAP

Use the !ODftAP co •• and to display the load .ap associated with the
specified ftODULE file. Two types of modules contain no load map and
therefore produce an error .essage when they are specified in a ftODftAP
co •• and. They are (1) CftS transient area .odules and (2) ftODULE files
created with the GElftOD co ••and using the ROftAP option.
The for.at of
the ftODftAP co.mand is:

ftODmap

is the filename of the ftODULE file whose load .ap is to be
displayed. The filetype of the file .ust be ftODULE.

The load .ap associated with the file is displayed at the ter.inal.

DMSftDP001E
DftSftDP002E
DftSftDP018E
DftSftDP070E

10 PILEIAftE SPECIPIED RC=24
PILE 'fn ft' ROT FOUND RC=28
10 LOAD ftAP AVAILABLE RC=40
INVALID PARAftETER 'para.' RC=24

section 7: Por.at and Usage Rules for CftS Co ••ands

175

"OVEPILE
MOVEFILE

Use the "OVEPILE command to move data from any device supported by
V"/370 to any other device supported by V"1370. The com.and accepts two
ddnames as arguments.
The PILEDEF command must have specified devices
or disk files for these ddnames.
The command moves data records froll
the device, or file, specified by the first ddname to the device, or
file, specified by the second ddname.
The format of the "OVEPILE
cOllmand is:

"OVEfile

., .,

I!I"O.!~

I outputddnalle I I
I
I I
10UTMOV!
I I

linputddname

[ (PDS[) ]]

inputddname

is the ddname representing the input file definition. If
ddname is not specified, the default input filename,
INMOVE, is used.

outputddname

is the ddname representing
If ddnalle is not specified,
OUTMOVE, is used.

PDS

the output file definition.
the default output filename,

moves all of the members of the CMS "lCLIB or TXTLIB or
of an OS partitioned data set into separate C"S files,
each with a filename equal to the member name and a
filetype equal to the filetype of the output file
definition (PILEDEP).

!2te: Normally, the PILEDEP command is used to establish device
characteristics for the ddname specified with the co •• and. If the
PILEDEP command was not issued, the OS macro simulation routines supply
default characteristics.
Por example, if the ddname is X a default
PILEDEP X DISK FILE X 11 command is executed.

If a record format (RECFM), blocksize (BLOCK), and logical record length
(LRECL) are specified on the PILEDEP command, these values are used in
the data control block (DCB) defining the characteristics of the move
operation.
If the FILEDEP was issued without the record format
specification, that specification is taken from the default list shown
in Figure 28. If the blocksize was not specified, the default blocksize
is used.
If the logical record length was not specified, the default
logical record length is determined as follows: if the record format is
F or U, the logical record length equals the blocksize; if the record
format is V, the logical record length equals the blocksize minus 4.
176

IB" V"1370: Command Language Guide for General Users

MOVEFILE

Output ddname

Input ddname
Device

Blocksize

RECF!

RECFM
N12

Blocksize

Card Punch

112

Printer

112

132

Terminal

130

Tape l

3600

Blocksize of
RECFM of
input ddname
i!lput ddname

Blocksize of
file

RECFM of
Blocks ize of
input ddnalle input ddname

NI2

RECFM of
Blocksize of
input ddname input ddname

Card Reader

Disk file
Dummy

RECFM of
file
112

N!2

lIf the default record for.at and blocksize are used in a
tape-to-tape move operation and an input record is greater than 36001
bytes, it is truncated to 3600 bytes on the output tape.
1
210t applicable.
I
~------------------------------------------------------------------------~
Figure 28. Default Device Ittributes for MOVEFILE COllmand

The existing file whose file definition ddname is IEWMIST is
the file whose file definition ddname is OLDMIST.

moved to

MOVEFILE NEW!IST OLDMIST
The following sequence of CMS commands move an OS STOW macro file
from an OS partitioned data set SIS1.MACLIB or a CMS file SIS1 MICLIB to
the eMS file STOW BACRO.
ICCESS 195 B/A
FILEDEF TEST 1 DISK SIS 1 MICLIB B1
FILEDEF !ACRO DISK STOW MACRO
MOVEFILE TEST1 MACRO

(MEMBER STOW)

The following sequence of CMS commands moves all the members of an OS
partitioned data set SIS1.MACLIB or a C!S file SIS1 !ACLIB into separate
CMS files each with a filename equal to its member name and a filetype
of MICRO.
ACCESS 195 B
FILEDEF TEST2 DISK SIS1 MICLIB B1
FILEDEF MACRO DISK
MOVEFILE TEST2 MACRO (PDS)
For more examples of how to move as data sets and DOS files to CMS
files using MOVEFILE, see "Using as Programs and !acros under CMS" in
section 4.

section 7: Format and Usage Rules for CMS Commands

177

MOVEFILE

DftSMVE2251 PDS MEMBEB 'membername' MOVED
The specified .ember of an as
successfully to a CftS file.

partitioned

data

set was

.oved

DftSftVE2261 EID OF PDS ftOVE
The last member of the partitioned
to a CMS file.

data set was moved successfully

DftSftVE7061 TEBM IIPUT -- TYPE lULL LIIE FOB liD OF DATA
The input ddname in the MOVEFILE
This message requests the input
input.

command refers to a terminal.
data; a null line terminates

DftSftVE7081 DISK FILE 'FILE ddname Al' ASSUMED FOB DDIAftE 'ddname'
FILEDEF com.and was issued for a ddna.e specified on the
ftOVEFILE command.
As a result the MOVEFILE issues a FILEDEF for
that ddna.e.

If the input ddname is undefined, the file must
size and record format are taken from this file.

exist.

The block

If the output ddname is undefined, the disk file is created on the
A-disk with the same characteristics as those of the input file.

DftSMVE002E
DftSftVE003E
DftSMVE037E
DftSftVE041E
D!S!VE048E
DMS!VE070E
DMS!VE073E
DMSftVE075E
DMS!VE086E
DMSMVE127S
D!S!VE128S

FILE 'fn ft f.' lOT lOUID RC=28
IIVALID OPTIOI 'option' RC=24
OUTPUT DISK -mode' IS BEAD/ONLY BC=36
IIPUT AID OUTPUT FILES ABE THE SAME BC=40
INVALID !ODE -mode' BC=24
IIVALID PABAMETEB 'param' RC=24
UIABLE TO OPEl FILE ddname RC=28
DEVICE 'device name' ILLEGAL paR {IIPUTIOUTPUT} RC=40
IIVALID DDIAME 'ddname' RC=24
UISUPPOBTED DEVICE FOB ddname RC=100
I/O ERROR 01 IIPUT AFTER READIIG nnnn BECORDS: INPUT EBBOR
code 01 ddnaae BC=100
D!S!VE129S I/O ERROB 01 OUTPUT WBITING BECORD BUMBEB nnnn: OUTPUT EBROB
code 01 ddname BC=100
D!S!VE130S BLOCKSIZE ON V FOR!AT FILE ddname IS LESS THAI 8 BC=88

178

IB! V!/370: Com.and Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659
PRINT

PRINT
Use the PRINT command to print a CMS file on the spooled virtual 1403 or
3211 printer.
The file may contain carriage control characters and may
have either fixed- or variable-length records, but no record may exceed
132 characters for a
1403 or 150 characters for a 3211.
There are two
exceptions to this:
1•

If the CC option is in
character longer
(133 or
character.

effect, the record length can be one
151) to allow for the carriage control

If the HEX option is in effect, a record of any length
printed, up to the CMS file system maximum of 65,535 bytes.

can be

!Q!~:

An option may not be in effect, even though it is specified. See
the discussion of the PRINT options for information on overriding
options.
The format of the PRINT command is:

,.------PRint

fn ft Ifml
1* I
L

,
[ (options ••• [) ]]

.Q.E1,i.Q!!.§: ICC

l!g~~1
L

I
[UPCASE]

IMEMBER
{ m:mbername
I
L-______.____________________

, ,

ILInecoun Innl I
I
I~~I I

..J

[HEX]

I
I
I
I
I
I
I
I
I
I
I

is the filename of the file
must be specified.

to be printed.

This field

is the filetype of the file
must be specified.

to be printed.

This field

is the filemode of the file to be printed. If this field
is specified as an asterisk
(*), the standard order of
search is followed and the first file encountered, with
the given filename and filetype, is printed.
If fm is
not specified, the primary disk and its extensions are
searched.

interprets the first character of each record as a
carriage control character.
If
the filetype is
LISTING, the CC option is assumed.
If CC is in
effect, the PRINT command does not perform page ejects
or count the number of lines per page; these functions
are controlled by the carriage control characters in
the file.
The LINECOUN option has no effect if CC is
in effect.
section 7: Format and Usage Rules for CMS Commands

179

GC20-1804-3 Page Modified by TNL GN20-2659
PRINT
does not interpret the first character of each record
as a carriage control character.
In this case, the
PRINT command performs the necessary carriage control
to eject a new page and print a heading after the
number of lines specified by LINECOUN are printed. If
NOCC is specified, it is in effect even if CC was
specified previously or if the filetype is LISTING.
UPCASE
UP

translates the lowercase
uppercase for printing.

MEMBER { *
}
MEM
name

prints the members of macro or text libraries. This
option may be specified if the file is a simulated
partitioned data set (filetype MACLIB or TXTLIB). If
* is entered, all individual members of that library
are printed. If a membername is specified, only that
member is printed.

HEX

prints the file in graphic hexadecimal format.
If HEX
is specified, the options CC and UPCASE are not in
effect, even if specified, and even if the filetype is
LISTING.
r

I~~I

the

file

LINECOUN Innl
L

letters

allows you to set the number of lines to be printed
on each page. nn can be any decimal number from 0
through 99 and has a default value of 55. If nn is
set to zero, the effect is that of an infinite line
count and page ejection does not occur.
This option
has no effect if the CC option is also specified.

MYLIB

MACLIB

(MEMBER GET)

Spools the contents of the member GET in file MYLIB MACLIB to the
printer. The first character of each record in the file is not used for
carriage control.
PRINT

OLDMAST

NAME

(CC)

Spools the contents of the file OLDMAST NAME to the printer and uses the
first character of each record in the file for carriage control.

None.
The READY message indicates the command ccmpleted without error
(that is, the file is written to the spooled printer). The file is
now under the control of CP spooling functions.

DMSPRT002E FILE 'fn ft fm' NOT FOUND RC=28
DMSPRT003E INVALID OPTION 'option'
RC=24
DMSPRT008E DEVICE 'cuu' {INVALID OR NONEXISTENTIUNSUPPORTED DEVICE TYPE}
RC=36
DMSPRT013E MEMBER 'name' NOT FOUND IN LIBRARY RC=32
180

IBM VM/370: Command Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659
PRINT
DMSPRT029E
DMSPRT033E
DMSPRT039E
DMSPRT044E
DMSPRT048E
DMSPRT054E
DMSPRT062E
DMSPRT070E
DMSPRT104S
DMSPRT123S

INVALID PARAMETER 'param' IN THE OPTION 'option' FIELD
FILE 'fn ft fm' IS NOT A LIBRARY RC=32
NO ENTRIES IN LIBRARY 'fn ft fm'
RC=32
RECORD LENGTH EXCEEDS ALLOWABLE MAXIMUM RC=32
INVALID MODE 'fm'
RC=24
INCOMPLETE FILEID SPECIFIED RC=24
IN FILEID RC=20
INVALID
INVALID PARAMETER 'parmi
RC=24
ERROR Inn' READING FILE 'fn ft fm' FROM DISK RC=100
ERROR PRINTING FILE 'fn ft fm'
RC= 100

RC=24

Section 7: Format and Usage Rules for CMS Commands

180.1

PUBCH
PUNCH

Use the PUBCH command to spool a specified CMS disk file to the punch.
PUBCH accepts fixed- or variable-length records as long as no record
exceeds 80 characters. Records with less than 80 characters are padded
with blanks on the right.
Records longer than 80 characters are
rejected. The format of the PUBCH command is:

PUnch

fn ft Ifml
IL * JI

[ coptions ••• [) ] ]
r

IHE!~!!

I
I BOHEADERI
L

I MEMBER
I

{*aembername }II

is the filename of the file
be specified.

to be punched.

This field must

is the filetype
be specified.

of the file to be punched.

This file must

is the fileaode of the file to be punched. If this field is
specified as an asterisk C*), the standard order of search
is followed and the first acceptable file encountered is
punched. If fm is not specified, the primary disk and its
extensions are searched.

inserts a control card in the punched output preceding
the specified file. This control card identifies the file
for a subsequent RB1DCARD co.mand to restore the file to
a disk.
If the filetype is TITLIB and the MBMBBR
aembernaae option is specified, the header card contains
TBIT as the filetype. If the filetype is MACLIB and the
SEMBER aembername
option is specified,
the header
contains MEMBBR as the filetype.
A aacro library member
originates fro. a file with a filetype of either MACRO or
COPY. The control card format is shown in Pigure 29.
BOHEADER
IOH
MEMBER
MEM

does not
deck.

insert a

header control

card

in the

punched

{*meabername }

punches library members. If the filetype is MACLIB or
If * is entered, all
TITLIB, this option are specified.
section 7: Pormat and Usage Rules for CMS Co•• ands

181

PUNCH
individual aembers of that aacro or text library are
punched. If .emberna.e is specified, only that me.ber is
punched.

I Humber of I
I
ColumnlCharacterslContentsl
1

2-5

RElD

6-7

blank

8-15

fnalle

blank

17-24

ftype

blank

26-27

fmode

blank

29-34

volid

blank

36-43

44-45

46-50

51-80

Figure 29.

PUICH

I!eaning

IIdentifies card
I
IIdentifies card
I
I
I
IFilename of the
I
I
I
Filetype of the

as a control card.
as a READ control card.

file punched.

Filemode of the file punched.

Label of the disk froa which the file was
read.

Imll/dd/yy The date that the file vas last written.
I
Iblank
I
The time of day that the file was written
Ihh:am
to disk.
I
I
Iblank

Header Card Format

HEWI!lST

TRllS

(BOH)

spools the file IEW!lST TRAIS ta the punch.
preceding the output deck.

Ho header

card is punched

lone.
If the command completes without error (the file was successfully
spooled), the RElDY .essage appears. The file is now under control
of CP spooling functions.

182

IBI! 'I!/370: Co •• and Language Guide for General Users

PUNCH

DMSPUN002E FILE 'fn ft fa' NOT FOUND RC=28
DftSPUN003E INVALID OPTIOW 'option' Rr=?U
DMSPUN008E DEVICE 'cuu' {INVALID OR NONEXISTENTIUNSUPPORTED DEVICE TYPE}
RC=36
DMSPUN013E MEMBER 'naae' NOT FOUND IN LIBRARY RC=32
DMSPUN033E FILE 'fn ft fm' IS NOT A LIBRARY RC=32
DMSPUN039E NO EITRIES II LIBRARY 'fn ft fm' RC=32
DMSPUN044E RECORD LEIGTH EXCEEDS ALLOWABLE MAXIMUft RC=32
DftSPUN054E INCOftPLETE FILEID SPECIFIED RC=24
DftSPUN062E INVALID * IN FILEID RC=20
DftSPUN104S ERROR 'nne READING FILE 'fn ft fm' FROM DISK RC=100
DftSPUN118S ERROR PUNCHING FILE 'fn ft fm' RC=100

Section 7: Format and Usage Rules for CMS Commands

183

QUERY
QUERY

Use the QUERY co •• and to gather certain information about the CftS
virtual .achine
environment.
Information which .ay
be obtained
includes:

•

The state of any of the virtual aachine characteristics
controlled by the CftS SET co •• and.

•

File definitions (set with the PILEDEP co •• and) which are in effect.

•

The status of the disks attached to your virtual .achine.
The for.at of the QUERY co ••and is:
Query

BLIP
RDYftSG
LDRTBLS
RELPAGE
IftPCP
IftPEX
ABBREY
REDTYPE
PROTECT
IIPUT
OUTPUT
SEARCH

FILEDEF
ftACLIB
TXT LIB
LIBRARY

BLIP

displays the BLIP character(s).
!.!!!.E~ :

BDYftSG

BLI P = { xxxxxxxx }
OPP

displays the RDYftSG format.
~n~!!:

RDYftSG = { LftSG }
SftSG

!ll!!I!:

LBSG

is the standard CftS READY message:
R; T

SBSG

= 0.12/0.33

17:06:20

is the shortened CftS READY message:
H;

184

IBft Yft/370: Com.and Language Guide for General Users

which are

GC20-1804-3 Page Modified by TNL GN20-2659
QUERY
LDRTBLS

displays the number of loader tables.
~~§~2~§~:

RELPAGE

LDRTBLS = nn

indicates whether pages of storage are to be released
retained after certain commands complete execution.
~~'§~2~'§~: RELPAGE

OFF
IMPCP

= {ON

OFF

}

releases pages.
retains pages.

displays the status of implied CP com.and indicator.
j~'§EQ~§~: IftPCP

= {ON

}

OFF

ON
OFF
IMPEX

passes com.ands not recognized by CftS to CP.
flags co •• ands not recognized by CMS.

displays status of implied EXEC indicator.
= {ON}
OFl!'

ON
OFF

ABBREV

indicates that EXEC files can be executed by entering
the filename of the file.
indicates that the EXEC command must be explicitly
entered to execute EXEC files.

displays the status of the minimum truncation indicator.
~~'§~2~'§~: ABBR!V

ON
OFF
REDTYPE

= {ON

OFF

}

accepts minimum truncations for CMS commands.
does not accept minimum truncations.

displays the status of the REDTYPE indicator.
~~'§EQ~§~: REDTYPE

= {ON}
OFF

types CMS error messages in red, for certain terminals
equipped with the appropriate terminal feature and a
two-color ribbon. Supported terminals are documented in
the !~LllQ: I~~~iB~l g§~~~.§ gYig~·

OFF

does not type CMS error messages in red.
Section 7: Format and Usage Rules for CMS Commands

185

QUERY
PROTECT

displays the status of CMS nucleus protection.
]~§E2g§~:

ON
OFF
INPUT

PROTECT = {ON}
OFF

means CMS nucleus protection is in effect.
means CMS nucleus protection is not in effect.

displays the contents of your input
specified.

an
If you do not have
response is

translate table if one is

xxn
an input

translate table in

effect, the

NO USER DEFINED INPUT TRANSLATE TABLE IN USE
OUTPUT

displays the contents of your
have specified one.
~~§]Qg§~:

OUTPUT

If you do not
response is

xx1

xxn

have an

output translate table

output translate

if you

table defined,

the

NO USER DEFINED OUTPUT TRANSLATE TABLE IN USE

displays the
accessible.
~~§]Qg§~:

order

volid vaddr mode

all

CMS

disks

currently

{ R/O}
R/i

DISK mode displays the status of the single disk represented by 'mode'.
~~§]Qg§~:

mode (vaddr): nn FILES, nnnn REC IN USE, nnnn LEFT
(OF nnnn), nnl FULL (n CYL), type {R/O}
R/i

If the disk is an OS-formatted disk, the response is:
mode (vaddr):
186

(n CIL), R/O-OS

IBM VM/370: Command Language Guide for General Users

QUERY
If the disk
response is

with the

specified

mode is

not accessed,

the

DISK 'mode' NOT ACCESSED
DISK

displays the status of all CMS disks.
~~§EQ~§~:

same as for QUERY DISK mode; one
for each accessed disk.

line is displayed

SYNORYK SYSTEM
displays the CMS system synonyms in effect.
System
~QI!~g

command

Shortest
Porm
minliUi-truncation

If no system synonyms are in
displayed at the terminal:

effect, the following message is

NO SYSTEM SYNONYMS IN EFFECT
SYNONYM USER
displays user synonyms in effect.
Systell
User
Com.and .§I.!!ony!
coiliiind synonym

If no user synonyms are in
displayed at the terminal:

Shortest
~Q!:LJ!t_~~Il

minimum truncation

effect, the following

message is

NO USER SYBOBYMS IN EPFECT
SYNONYM ALL
displays all synonyms in effect.
~~§EQ~§~:

PILEDEP

Same as SYNONYM SYSTEK and SYNONYM USER.

displays all file definitions in effect.
R~§EQ~§~:

ddnalle device [fn [ft]]

If there are no user file definitions in effect, the following
message is displayed at the terminal:
NO USER DEFINED PILEDEP'S IN EFPECT

section 7: Pormat and Usage Rules for CMS Commands

187

QUERY
displays the names of all files with a filetype of
which are to be searched for macro definitions.

ftlCLIB

!~£2B2~:

ftlCLIB

ftlCLIB = libname •••

If no
macro libraries are
definitions, the response is:

searched

for

macro

IUCLIB = BOBE
displays the na.es of all files with a filetype of
which are to be searched for unresolved references.

TITLIB

TXTLIB

If no TITLIBs are to be searched for unresolved references,
the following message is displayed at the terminal:
TITLIB = RORE
displays the name of all macro and text library (files with
filetypes ftlCLIB and TITLIB) which are to be searched.

LIBR1RY

!~.2£2'!!§~:

ftlCLIB = {libnaIBe ••• }
NONE
TXTLIB = { libnaae ••• }
NOIE

DftSQRYOOSE
DftSQRY014E
DftSQRY026E
DftSQRY047E
DftSQRY070E

188

10 'option' SPECIFIED RC=24
INV1LID FUNCTION 'function' RC=24
IIV1LID P1RlftETER 'para.' FOR 'function' FURCTIOR
10 FUICTION SPECIFIED RC=24
IBV1LID P1RlftETEB 'paras' RC=24

IBft V8/370: Command Language Guide for General Users

RC=24

REAOCARO
READ CARD

Use the REAOCARO command to read data records from the virtual card
reader (spool input device) and to create files on disk containing the
data records. The data records must be fixed length and normally
contain 80 characters, although they may contain up to 151 characters.
Records less than 80 characters long cannot be read. If a file exists
on disk with the same identifiers as the one to be created, it is
erased.

Any number of files may be entered through the card reader, each
immediately preceded by a READ control card specifying the filename,
filetype, and optionally the filemode. The RlAO control card is shown
in Figure 30. The header card supplied when HEADER is specified with
the eMS PUNCH command is a valid READ control card.
All files that are logically grouped together must have the same
record length. The READ control cards are displayed at the terminal as
they are encountered, and interpreted just as if filename and filetype
had been entered from the terminal. Each READ control card ends the
preceding file, and the reader end-of-file indication ends the last
file.
Your files must be spooled to the virtual reader before a READCARD
command can be issued. You can send your real card deck to your virtual
card reader using the CP 10 card in front of your real card deck. This
card takes the form:
r

ID
} userid I CLASS c I NAME {fn ft }
{ USERID
I~LA~~ AI
dsname
L

keyword

is a

userid

is the user's identification (userid), liaited
characters.

CLASS c

is the optional class field.
class A is the default.

NAftE {fn ft }
dsname

is the name field.
If the first fora is specified, the
filename and
filetype are
each limited
to eight
characters. The filenaae and file type aust be separated
by a blank. If the second form is used, the dsnaae field
is liaited to 24 characters.

that

must

begin

column

ID
USERID

one.

to eight

If CLASS is not specified,

Note: Only the CLASS n operand is optional.
All fields must be
separated by at least one blank. The keyword 10 or USERID must start in
column one.
You need not be logged on at the tiae the decks are transferred to
your virtual reader.
If aore than one file is spooled to the virtual
reader, more than one READCARD comaand must be issued to process all the
logical files. If SPOOL RDR CO NT is issued, all the logical files in
the virtual reader are treated as a single file. Again, the files that
are treated as one must all have the saae record length. The format of
the READCARD command is:

section 7: Format and Usage Rules for CftS Commands

189

RE1DC1RD

RE1Dcard

fn ft I fm I
I A I
r

I
I
L

I fm II
11 II

is the filename of the file to
coded in this field.

be read.

In asterisk

may be

is the filetype of the file to be read. In asterisk
coded in this field if fn was coded as an asterisk.

may be

is the filemode of the file to be read.
If this field is
omitted or specified as an asterisk (*), 1 is assumed.
Whenever a mode number is specified on the command line, it is
used. Otherwise, the mode number on the REID control card is
used to create the disk file.

RE1DC1RD ftY1ILE lSSEftBLE
If filenaae and filetype are specified with the RE1DC1RD co •• and, only
one file is read. The REID control cards are ignored.
RE1DC1RD

If the file identification is to be entered in the card stream, a single
asterisk must be specified with the R!ADCARD command. If this for. of
the co.mand is specified, and the first card in the input stream is not
a valid REID control card, a file named RE1DCARD CftSUT1 11 is set up to
contain all data read until a valid REID control card is encountered.
If fn ft f. was specified, the file is written on the specified disk
with a mode number matching the file.ode number from the control card.
If the filemode number is specified, that number is used. If filemode
is omitted, 1 is assumed.
RE1DC1RD

Two asterisks accept the filename, filetype, and filemode
the REID control card, but use a file.ode letter of 1.
RE1DCARD

number from

Two asterisks with a mode specified accept the filename and filetype
identifiers from the REID control card, but use the filemode specified.
Whatever is specified on the RE1DC1RD command line is used. Whatever
is not specified is taken fro. the REID control card, except the
filemode letter, which defaults to A. If there is no REID control card,
a REID control card
:RB1D RE1DC1RD CftSUT1 11
is assumed.
190

IBft Yft/370: Command Language Guide for General Users

REIDCARD

INumber of I
I
Column ICharacters I Contents I
1

2-5

READ

6-7

blank

8-15

blank

17-24

blank

26-27

28-80

Meaning
Identifies card as a control card.
Identifies card as a READ control card.

Filename of the file.

Filetype of the file.

Filemode of the file.

anything

Figure 30. Format of the RBAD Control Card

After the comaand READCIRD * is issued, control cards encountered in the
input card stream are displayed at the terminal.
DMSRDC7011 NOLL PILB
The spooled card
card.

reader

DMSRDC7021 RBAD COITROL CIRD
REIDCIRD CftSOT1 A1

contains no

ftISSIIG.

records

after the

POLLOWIIG

control

ASSUftED:

The first card in the deck is not a READ control card.
the file RBADCIRD CftSUT1 A1 is created.

READ

Therefcre,

DftSRDC7381 RECORD LBIGTH IS 'nnn' BYTBS
The records
the length.

being read are not

80 bytes long; this

When a READCIRD control card is encountered, the first 72
card are displayed at the terminal.'

message gives
coluans of a

DftSRDC008E DBVICE 'cuu' {INVALID OR NONEXISTENTIUNSUPPORTED DEVICB TYPB}
RC=36
DftSRDC042E 10 FILEID SPECIFIED RC=24
DMSRDC054B IICORRECT FILBID SPBCIFIBD RC=24
DMSRDC062E INVILID * II FILBID RC=20
DMSRDC105S BRROR Inn' WRITIIG PILB 'fn ft f.' 01 DISK RC=100
DftSRDC124S BRROR RBIDING CARD FILE RC=100
DMSRDC205W RBADBR BftPTY OR lOT RIADY RC=8
Section 7: Format and Usage Rules for CftS Coa.ands

191

RELEASE
RELEASE

Use the RELEASE co •• and to free an active disk when it is no longer
needed. An ACCESS com.and must have been previously entered for the
specified disk. The for.at of the RELEASE command is:
I

I
II

RELease

cuu

I
,I

cuu }
{ mode

is the virtual
released.

device

address of

the disk

that

is to

Bote that 000 is not a valid address.
mode

is the .ode of the disk to be released.

Note: If a disk is accessed more than once, the RELEASE cuu co ••and
releases all instances of cuu. The system disk cannot be released.

DftSARE017E
DftS1RE028E
DftSARE048E
DftSARE069E
DftSARE070E

192

INVALID DEVICE ADDRESS 'cuu' RC=24
BO DEVICE SPECIPIED RC=24
INVALID ftODE '.ode' RC=24
DISK {'.ode'I'cuu'} NOT ACCESSED RC=36
INVALID PARAftETER 'param' RC=24

IB! V!/370: Co •• and Language Guide for General Users

REIA!E
RENAME
Use the REIA!! coa.and to change the file identification of one or aore
files. The REIA!E coamand may not be used for a file which is located
on a read-only disk. The foraat of the RENA!E coaaand is:

Rename

fileid1 fileid2 [(options ••• [)]]

ITYPE i
I!Ql!PEI
L

IUPDI!! I
INOUPDIRTI
L

fileid1

is the file identification of the original file whose naae
is to be changed.
All components of the file (filenaae,
filetype, and filemode) aust be coded, either with a name or
an asterisk. If an asterisk is coded in any field, any file
which satisfies the other qualifications is renaaed. Por
exaaple, if fileid1 is coded as A * A1, all files on the A
disk with a filename of A are renaaed.

fileid2

is the new file identification of the file. All components
of the file (filenaae, filetype, and filemode) aust be
coded, with either a name or an equal sign. If an equal
sign is
coded, the corresponding file
identifier is
unchanged.

TYPE
T

displays at
the
terainal
the
new
identifiers
of all files renaaed. The file identifiers are displayed
only when an * is specified for one or aore of the file
identifiers (fn, ft or fa) in fileid1.

NOTYPE
lOT

suppresses displaying at the terminal of
identifiers of all files renamed.

~!I

updates the !aster
this command.

NOUPDIRT
IOUP

suppresses the updating of the !aster pile Directory
upon coapletion of this coamand. Normally, !aster Pile
Directories are updated at the completion of each e!s
comaand that affects disk files.

Pile Directory

upon

the new
completion

section 1: Pormat and Usage Rules for C!S Comaands

file
of

193

RENAME

newfn newft nevfa
The new filenaae, filetype, and file.ode of each file altered is
displayed only when the TYPB option is specified and an asterisk
was specified for at least one of the file identifiers
(fn, ft or
fa) of the original file.
If fileid2 is
generated.

DMSRNM002E
DMSRBM003B
DMSRNM019E
DMSRBM024E
DMSRNM030E
DMSRBM037E
DMSRBM051E
DMSRBM054E
DMSRNM062E

the

naae

of an

existing

file,

an error

aessage

PILE 'fn ft fa' NOT POUND RC=28
IBVALID OPTIOB 'option'
RC=24
IDBNTICAL PILEIDS RC=24
PILE 'fn ft fa' ALREADY BXISTS RC=28
PILB 'fn ft fa' ALREADY ACTIVE RC=28
DISK 'aode(cuu), IS READ/ONLY RC=36
INVALID MODE CHANGE RC=24
IBCOMPLBTB PILEID SPECIFIED RC=24
INVALID
IN OUTPUT PILEID RC=20

Note: You can invoke the REBAME co •• and from the terainal, froa an EXEC
fIle, or as a function froa a program.
If RENAME is invoked as a
function or from an EXEC file that has the SCONTROL NO!SG option in
effect, the D!SRNM002E PILE fn ft fm NOT FOUID error message is not
issued.

194

IBM VM/370: Co.mand Language Guide for General Users

RUN

RUN
Use the RUN command to initiate an automated series of functions on a
file.
The RUN command can compile, load, and start execution of the
specified file, depending upon the filetype.
The acceptable filetypes
are: EXEC, MODULE, TEXT, and those required by the language processors.
The RUN command is an EXEC procedure: if it is executed from within an
EXEC file, it must be preceded by the EXEC command name.
The format of
the RUN command is:

-----------------,I

IL-_______
RUN
_ fn (ft (fm]] [(args ••• )]

____________________- - J

is the filename of the file to be manipulated. This field must
be entered.

is the filetype of the file to be manipulated. If filetype is
not specified, a search is made for a file with the specified
filename and the filetype of EXEC, MODULE, or TEXT (the search
is performed in that order).
If the filetype of an input file
for a language processor is specified, the language processor
is invoked to compile the source statements and produce a TEXT
file.
Then, LOAD and START are called to initiate program
execution.
The filetype must be specified if filemode is
specified. The valid filetypes and resulting action for this
command are:
lil~1YE~

EXEC

Action
The-EXEC processor is called to process the file.

MCDUlE

The LOADMOD

TEXT

The LOAD command brings the file into storage in an
executable format and the START command executes the
program beginning at the entry point named by fn.

FORTRAN

The FORTRAN processor module that is called is
or FORTHX,
FORTRAN, FORTGI,
GOFORT, TESTFORT,
whichever is found first.

FREEFORT

The GOFORT module is called to process the file.

COBOL

The COBOL processor module that is called
or TESTCOB, whichever is found first.

PLI
PLIOPT

The PLIOPT
the file.

command is issued to load the program
into storage and the START command begins execution
of the program at the entry point equal to fn.

processor module

called to

is COBOL
process

is the filemode of the file to be manipulated. If this field
is specified, a filetype must be specified.
If fm is not
specified, the default search order is used to search your
disks for the file.

Section 7: Format and Usage Rules for CMS Commands

195

GC20-1804-3 Page Kodified by TNL GN20-2659
RUN
args

are one or more user arguments to te used during execution.
If coapiling or loadig is to be performed, it is assumed that
the default options for those functions are in effect. You can
specify up to 13 arguments in the RUN command, provided they
fit on a single input line. These arguaents are used during
the operation of an EXEC file, or during execution of a "ODULE
or TEXT file. The arguments are set up as a string of
doublewords, one arguaent per doubleword. The address of this
string is passed to the specified file at execution time.
Each argument is left-justified, and any argument more than
eight characters long is truncated on the right. with an EXEC
file, any arguments specified in the RUN coaaand replace the
corresponding &n operands in the individual commands of the
EXEC file.
with a file whose filetype is other than EXEC, the arguments
are placed in a string as described above. The address of the
string is passed to the specified file at execution time. The
end of the arguaent list is denoted by a X'FF' in the first
byte of the argument field.

DKSRUN001E
DKSRUN002E
DKSRUN032E
DKSRUN048E
DKSRUN070E
DKSRUN999E

196

NO FILENAKE SPECIFIED RC=24
FILE 'fn ft fm' NOT FOUND RC=28
INVALID FILETYPE 'ft' RC=24
INVALID KODE 'fm' RC=24
INV.LID PARA"ETER 'param' RC=24
NO ft PROCESSOR FOUND RC=28

IB" V"1370: Command Language Guide for General Users

SET

SET
Use the SET co •• and to establish, turn off, or reset a particular
function in your CftS virtual machine.
Only one function may be
specified per SET command. The format of the SET command is:

SET

function

[ LDBTBLS nn]

IRD!1!~§ !!ftS§1

IRDYftSG SftSG I
.J

IRELPAGE OR I
IRELPAGE OFFI

---- --

iBLIP string[ (count) j I
IBLIP ON
I
IBLIP Oll
I

!.!U!£tioDs:

IINPUT I a xxi I
Ixx yyl I
I

Q! I
IIBBBEV OlPI

OR I
IREDTYPE OFFI

IIftPEX Olll

II~~BE!

IIftPCP ON I
IIftPCP Olll

----

IRE~TYPE

IPBQIECT Q! I
IPBOTECT Olll

[OUTPUT [xx a] ]

r
IIK~EX

Q! I
.J

IAUTOBEAD 01 I
IAUTOREAD OFFI

BLIP string[ (count)] defines the characters which are displayed at the
ter.inal to indicate every two CPU seconds of real
(or
virtual) execution
time.
Up to
eight
characters can be defined, and if trailing blanks
are desired, the count field must be used. ON and
O!! Bust not be used as BLIP characters.
BLIP OR

sets the BLIP character string to its default,
which is a string of nonprintable characters. ON
is the default for typewriter devices. The default
BLIP character provides no visual or audio-visual
signal for the 3767
terminal.
Thus, another
character .ust be defined as the BLIP character for
the 3767 if you want the BLIP function.

BLIP Oll

turns off
devices.

BLIP.

OFF is

the default

for graphics

indicates that the standard CftS Ready message,
including current and elapsed time, is used. The
format of the standard Ready message is:
B; T=s •••/s •• m hh:.m:ss
where the virtual CPU time,
clock time are listed.
BDYftSG SftSG

Real

CPU time,

and

indicates that a shortened for. of the CftS Beady
message (R;) which does not include the time, is
used.
Section 7: Format and Usage Rules for CftS Commands

197

SET
LDRTBLS nn

defines the number (nn) of pages of storage to be
used for loader tables.
By default, a virtual
machine having up to 384K of addressable real
storage has two pages of loader tables; a larger
virtual machine has three pages. This number can
be changed with the SET LDRTBLS nn com.and provided
that: (1) nn is a decimal number less than 128, (2)
the virtual machine has enough storage available to
allow nn pages to be' used for loader tables, and
(3) the system has not started using storage just
below the LDRTBLS. If these three conditions are
met, nn pages are set aside for loader tables. If
you plan to change the number of pages allocated
for loader tables, you should do so as soon after
IPL as possible.
releases page frames of storage and sets them to
binary zeros after the following commands complete
execution: ASSEMBLE,
COPYPILE, COMPARE,
EDIT,
MACLIB, SOBT, TXTLIB, UPDATE, and the Program
Product language processors supported by VM/370.
These processors
are listed
in the
VM/370:
!nt~ductiQ!!.

RELPAGE OPP

does not release pages
of storage after the
com.ands listed in the previous paragraph complete
execution. Use the SET RELPAGE OPP function when
debugging or analyzing a problem so that the
storage used is not released and can be examined.

IBPUT a

translates the
specified character a
to the
specified hexadecimal
code xx
for -characters
entered from the terminal.

IBPUT xx yy

allows you to reset the hexadecimal code xx to the
specified hexadecimal code yy in your translate
table.
Bo1~:
If you issue SET IBPUT and SET OUTPUT
commands for the same characters, the SET OUTPUT
command must be issued first.

characters

their

default

IBPUT

returns
all
translation.

OUTPUT xx a

translates the specified hexadecimal representation
xx to the specified character
!
for all xx
characters displayed at the terminal.

OUTPUT

returns
all
translation.

characters

their

default

allows the
system abbreviation
or your
own
abbreviation (if one is available) to invoke a
system com.and.
The SYBOBYM com.and .akes the
system and user abbreviations available.
ABBREV OPP

invokes a com.and only when the full system com.and
name or the full user synonym (if one is available)
is entered.
Por a discussion of the relationship
ABBiEV and SYBOIYM co •• ands, refer to
co •• and description.

198

IBM VM/370: Co •• and Language Guide for General Users

of the SET
the SYIOIYM

GC20-1804-3 Page Modified by TNL GN20-2659
SET
types CMS error me~sages
in red for certain
ter.inals equipped v1th ~ne appropriate terminal
feature
and
a two-color
ribbon.
Supported
terminals are documented in the !!LJ1~: I~~!i!!!!

!!se~~ Gu!g~.

REDTYPE OFF

suppresses red typing of error messages.
treats EXEC files as co.mands; an EXEC file
invoked when the filename of the EXEC file
entered.

IMPEX OFF

is
is

does not consider EXEC files as com.ands.
To
execute an EXEC file, the EXEC co.mand name must be
issued.
passes command names that CMS does not recognize to
CP; that is, unknown commands are considered to be
CP commands.

IMPCP OFF

generates an error message at the
command is not recognized by CMS.

terminal if

protects the CMS nucleus against writing within its
storage area.
PROTECT OFF

does not protect the
CMS nucleus.

AUTOREAD ON

specifies that a console READ is to be issued
immediately after com.and execution.
ON is the
default for non-display, non-buffered terminals.

AUTOREAD OFF

specifies that you do not want a console READ until
you depress the Enter key or its equivalent. OFF
is the default for display terminals because the
display terminal does not lock, even when there is
no READ active for it.

storage area

containing the

!Q!~:

If a user disconnects from one type of ter.inal and reconnects on
to another type, the AUTOREAD status will remain unchanged.

DMSSET014E
DMSSET026E
DMSSET031E
DMSSET047E
DMSSET061E
DMSSET070E

INVALID FUNCTION 'function'
RC=24
INVALID PARAMETER 'param' FOR 'function' FUNCTION
LOADER TABLES CANNOT BE MODIFIED RC=40
NO FUNCTION SPECIFIED RC=24
NO TRANSLATION CHARACTER SPECIFIED RC=24
INVALID PARAMETER 'param' RC=24

RC=24

Section 7: Format and Usage Rules for CMS Commands

199

SORT

SORT
Use the SORT command to read fixed-length records from a CMS input file,
arrange them in ascending EBCDIC order according to specified sort
fields, and create a new file containing the sorted records. The input
and output files must not have the same file identifiers, since SORT
cannot write the sorted output back into the space occupied by the input
file. If a file with the same name as the output file already exists,
the old file is erased. The format of the SORT command is:
r-

fileid1

SORT

fileid2

fileid1

is the file identification (filename, filetype,
the file containing the records to be sorted.

filemode)

fileid2

is the file identification (filename, filetype, filemode)
the new output file to contain the sorted records.

~g1~~!gg

Sort Control Fields: After the SORT command is
responds wIth the-followIng-message on the terminal:

entered, CMS

DMSSRT604R ENTER SORT FIELDS:
You should respond by entering one or more pairs of numbers of the form
"xx yy" separated by one or more blanks.
Each xx is the starti~g
character position of a sort field within each input record and yy 1S
the ending character position.
The leftmost pair of numbers denotes the
major sort field. The number of sort fields is limited to the number of
fields you can enter on one line. The records can be sorted on up to a
total of 253 positions.
!!!~Y~l ~~~f~~~

R~gY!f~!~E~~ !~f §Qf~!gg:
The sorting operation takes
place with two passes of the input file. Pass one creates an ordered
pointer table in virtual storage. Pass two uses the pointer table to
read the input file in a random manner and write the output file.
Therefore, the size of storage and the size and number of sort fields
are the limiting factors in determining the number of records that can
be sorted at anyone time. An estimate of the maximum number of records
that can be sorted is:

VMSIZE - 132K
------------14 + NC

where: NR is the estimated maximum number of input records; NC is
total number of characters in the defined sort fields;
VMSIZE is
storage size of the virtual machine; and 132K is the size of
resident CMS nucleus.
For example, enter the command and respond to
prompting message:

the
the
the
the

sort name address a1 sortedna address b1
DMSSRT604R ENTER SORT FIELDS:
1 10 25 28
The records in the file RAME ADDRESS are sorted on positions 1-10 and
25-28.
The sorted output is written into the newly created file
200

IBM VM/370: Command Language Guide for General Users

SORT
SORTEDNA ADDRESS. If you have a 320K
maximum of 6875 records.
VMSIZE-132K

320K-132K

188K

14 + 14

virtual machine, you can

sort a

192,512
6875

NR
14 + BC

DMSSRT604R ENTER SORT FIELDS:
You are requested to enter SORT control fields.
You should enter
them in the form described in "Entering Sort Control Fields."

DMSSRT002E
DMSSRT009E
DMSSRT019E
DMSSRT034E
DMSSRT037E
DMSSRT053E
DMSSRT054E
DMSSRT062E
DMSSRT063E
DMSSRT070E
DMSSRT104S
DMSSRT105S

FILE 'fm ft fa' NOT FOUND RC=28
COLUMB 'col' EXCEEDS RECORD LENGTH RC=24
IDENTICAL FILEIDS RC=24
FILE 'fn ft fm' IS NOT FIXED LENGTH RC=32
DISK '.ode' IS READ/OBLY RC=36
INVALID SORT FIELD DEFINED RC=24
INCOMPLETE FILEID SPECIFIED RC=24
INVALID * IN FILEID RC=20
NO LIST EBTERED RC=40
INVALID PARAMETER 'param'
RC=24
ERROR Inn' READING FILE 'fn ft fm' FROM DISK RC=100
ERROR Inn' WRITING FILE 'fn ft fm' ON DISK RC=100

Section 7: Format and Usage Rules for CMS Commands

201

GC20-1804-3 Page Modified by TNL GN20-2659
START
START
Use the START com.and to begin execution of progra.s that were
previously loaded, and to pass the address of a string of argu.ents to
that program. The for.at of the START command is:
r-

r
I
I START
I entry [args ••• ) I
I
I
I *
L
.J
~
IL-____________________________________________________________________________

entry

passes control to the control section name or entry point
name at execution time.
The operand, entry, may be a
filename only if the filena.e is identical to a control
section name or an entry point name.

passes control to the default entry point. The default
entry point is either the address specified in the operand
field of the first END control statement containing a
non-blank operand field, or the beginning of the first file
loaded if all END control statements in the TEXT files
contains blank operand fields.
The default entry point can
be changed by specifying the RESET option on the INCLUDE
command, when loading additional files.

args •••

are argu.ents to be passed to the started program. If user
arguments are specified, entry or * must be specified;
otherwise, the first argument is taken as the entry point.
Arguments are passed to the program via general register 1.
The entry operand and any argu.ents become a string of
doublewords, one argument per doubleword, and the address of
the list is placed in general register 1.

Notes:
l:---Any undefined names or references specified in the files loaded
into storage are defined as zero. Thus, if there is a call or
branch to a subroutine from a main program, and if the subroutine
has never been loaded, the call or branch transfers control to
location zero of the virtual machine at execution time.
2.

Do not use the START command for progra.s that are generated via
the GENMCD command with the NOMAP option. The START command does
not execute properly for such programs.

DMSLI00741 EXECUTION BEGINS •••
is displayed when the designated entry point is validated.

DMSLI0021E ENTRY POINT 'name' NOT FOUND RC=40
DMSLI0055E NO ENTRY POINT DEFINED RC=40
202

IBM VM/370: Co •• and Language Guide for General Users

STATE

Use the STATE command to verify the existence of a CMS file.
of the STATE command is:
STATE

The format

fn ft [fm]

is the filename of the file
This field must be specified.

whose existence

is to

be verified.

is the filetype of the file
This field must be specified.

whose existence

is to

be verified.

is the filemode of the file whose existence is to be verified. If
this field is omitted, all your disks are searched.

Note: If * is specified for fn, ft, and/or fm
satisfying the rest of the fileid is used.

the first

file found

If the filemode refers to an as or DOS disk, the STATE comaand assuaes
that the filename and filetype are related to an as data set name or DOS
file-id through a previous FILEDEF.
If an associated FILEDEF coaaand
was not issued, you receive a FILE NOT POUND message.

DMSSTT227I PROCESSING VOLUftE 'no' II DATA SET 'data set name'
The specified data set has aultiple volumes; the volume being
processing is shown in the message.
The STATE co.mand treats
end-of-volume as
end-of-file and there is
no end-of-voluae
switching.
DftSSTT228I USER LABELS BYPASSED ON DATA SET 'data set name'
The specified data
skipped.

DftSSTT002E
DftSSTT048E
DMSSTT054E
DftSSTT062E
DftSSTT069E
DftSSTT070E
DftSSTT229E

set has

disk

user labels;

these labels

are

FILE 'fn ft fm' lOT FOUND RC=28
IIVALID ftODE 'mode' RC=24
IICOftPLETE FILEID SPECIFIED RC=24
IIVALID 'char' II FILlID 'fn ft' RC=20
DISK 'mode' BOT ACCESSED RC=36
INVALID PARAftETER 'param' RC=24
UBSUPPORTED as DATA SET, ERROR 'code'

Bote: You can invoke the STATE command from the terminal, from an EXEC
file, or as a function fro. a program. If STATE is invoked as a function
or from an EXEC file that has the &COlTROL BOftSG option in effect, the
DMSSTT002E FILE fn ft fa NOT FOUND error message is not issued.

section 7: Format and Usage Rules for CftS Commands

203

SVCTR1CB

SVCTRACE
Use the SVCTR1CB co •• and to
trace and record
supervisor calls occurring in your virtual machine.

information

about

The information recorded includes the virtual storage location of the
calling SVC instruction and the name of the called program or routine,
the normal and error return addresses, the contents of the general and
floating-point registers before branching to the SVC-called program and
after returning from it, and 16 words of the parameter list which
existed when the SVC was issued.
To terminate tracing previously established by the SVCTR1CB co •• and,
issue the HO or SVCTR1CB OFF co.mands. Both SVCTR1CE OFF and HO cause
all trace information recorded up to the point they are issued to be
printed on the virtual spooled printer.
On typewriter terminals
SVCTR1CB OFF can be issued only when the keyboard is unlocked to accept
input to the C!S command environment. To terminate tracing at any other
point in syste. processing, HO .ust be issued.
To suspend tracing
temporarily during a session, interrupt processing and enter the
i •• ediate co.mand SO
(Suspend Tracing).
To resume tracing that was
suspended with the SO co.mand, enter the immediate com.and RO (Resume
Tracing) •
If you issue the CftS co.mand HI or log off the control program before
termination of tracing set by SVCTR1CB, the switches are cleared
automatically and all recorded trace information is printed on the
virtual spooled printer. The format of the SVCTR1CE command is:

SVCTrace

starts tracing all SVC instructions issued within C!S.

OFF

stops SVC tracing.

The printer trace output consists of the following:
•

The contents of the general registers both before the SVC-called
program is given control and after a return fro. that program.

•

The contents of the general registers when the
is finished with processing.

•

The contents of the floating-point registers before the SVC-called
program is given control and after a return from that program.

•

The contents of the floating-point
routine is finished processing.

•

The para.eter list passed to the SVC.

204

svc handling routine

registers when the

IB! V!/370: Co.mand Language Guide for General Users

SVC handling

SVCTBICB

variety of infor.ation is printed whenever the

SVCTBICE 01
command is issued.
The first line of trace output starts with
of the first line of trace output is:
{

a~,

+, or..

The foraat

BID = xxx/dd naae I'ROII loc OLDPSII = psv 1 GOPSII = psv2 [BC=rc]

indicates infor.ation recorded before processing the SVC.
+

indicates inforaation recorded after
• applies.

processing the SiC, unless

•

indicates infor.ation recorded after processing
had an error return.

liD

is an abbreviation for SVC lu.ber and Depth Cor level).

xxx

is the number of the SVC call Cthey are nu.bered sequentially).

is the nesting level of the SiC call.

na.e

is the macro or routine being called.

loc

is the progra. location froa which the SVC was issued.

psw1

is the PSi at the ti.e the SVC was called.

psw2

is the PSi with which the routine being called is invoked, if
the first character of this line is a ainus sign C-).
If the
first character of this line is a plus sign or asterisk C+ or
.), PSi2 represents the PSi which returns control to the user.

is the return code from the SiC handling routine in general
register 15.
This field is o.itted if the first character of
this line is a .inus sign C-), or if this is an as SVC call.
Por a CftS SVC, this field is 0 if the line begins with a plus
sign C+), and nonzero for an asterisk C.). Ilso, this field
equals the contents of Begister 15 in the "GPBS IPTEB" line.

a CftS SiC which

The next two lines of output are the contents of the general
This
registers when control is passed to the SVC handling routine.
output is identified at the left by ".GPBSB". The for.at of the output
is:
.GPBSB = h h h h h h h h .dddddddd.
= h h h h h h h h .dddddddd.
where h represents the contents of a general register in hexadeci.al
for.at and d represents the EBCDIC translation of the contents of a
general register.
The contents of general registers 0 through 1 are
printed on the first line, with the contents of registers 8 through P on
the second line. The hexadeci.al contents of the registers are printed
first, followed by the EBCDIC translation. The EBCDIC translation is
preceded and followed by an asteriskC.).
section 1: Por.at and Usage Rules for CftS Coaaands

205

SVCTRACE

The next line of output is the contents of general registers 0, 1,
and 15 when control 1S returned to your progra.. The output is
identified at the left by ".GPRS AlTER :". The format of the output is:
.GPRS AFTER: RO-R1 = h h *dd* R15 = h *d*
where ~ represents the hexadecimal contents of a general register and g
is the EBCDIC translation of the contents of a general register. The
only general registers that C!S routines alter are registers 0, 1, and
15 so only those registers are printed when control returns to your
program. The EBCDIC translation is preceded and followed by an asterisk
(*) •

The next two lines of output are the contents of the general
registers when the SVC handling routine is finished processing. This
output is identified at the left by ".GPRSS." The format of the output
is:
.GPRSS = h h h h h h h h *dddddddd*
= h h h h h h h h *dddddddd*
where h represents the hexadecimal contents of a general register and g
represents the EBCDIC translation of
the contents of a general
register. General registers 0 through 7 are printed on the first line
with registers 8 through F on the second line.
The EBCDIC translation
is preceded and followed by an asterisk (*).
The next line of output is the contents of the calling routine's
floating-point registers. The output is identified at the left by
".FPRS". The for.at of the output is:
.FPRS = f

*gggg*

where f represents the hexadecimal contents of a floating-point register
and g -is the EBCDIC translation of a floating-point register.
Each
floating point register is a doubleword; each f and g represents a
double word of data. The EBCDIC translation is preceded and followed by
an asterisk (*).
The next line of output is the contents of floating-point registers
when the SVC-handling routine is finished processing. The output is
identified by ".FPRSS" at the left. The format of the output is:
.FPRSS = f

*gggg*

where ! represents the hexadecimal contents of a floating-point register
and ~ is the EBCDIC translation.
Each floating-point register is a
doubleword and each f and g represents a doubleword of data. The EBCDIC
translation is preceded and followed by an asterisk (*).
The last two lines of output are only printed if the address in
Register 1 is a valid address for the virtual machine. If printed, the
output is the parameter list passed to the SVC.
The output is
identified by ".PAR!" at the left. The output format is:
.PAR! = h h h h h h h h *dddddddd*
h h h h h h h h *dddddddd*

where h represents a word of hexadecimal data and g is the EBCDIC
translation. The parameter list is found at the address contained in
Register 1 before control is passed to the SVC-handling program. The
EBCDIC translation is preceded and followed by an asterisk (*).
Figure 31 summarizes the types of SVC trace output.
206

IB! V!/370: Command Language Guide for General Users

SVCTB1CE

r--------------------------------.-----------------------------------Comments
Identification
The SVC and the routine which issued the SVC.

.GPRSB

Contents of general registers when control is passed
to the SVC handling routine.

.GPBS AFTEB

Contents of general registers 0, 1, and 15 when
control is returned to your progra~.

.GPBSS

Contents of the general registers when the SVC
handling routine is finished processing.

.FPBS

Contents of floating-point registers before the
SVC-called program is given control and after
returning from that program.

.FPBSS

contents of the floating-point registers when the
SVC handling routine is finished processing.

• PABM

The parameter list, when one is passed to the SVC •

L-

Figure 31.

DMSOVB014E
DMSOVB047E
DMSOVB104S
DMSOVB109S

Summary of SVC Trace Output Lines

INVALID FUNCTION 'function' BC=24
NO FUNCTION SPECIFIED BC=24
EBBOB Inn' BEADING FILE 'DMSOVR MODULE' ON DISK
VIBTUAL STOBAGE CAPACITY EXCEEDED BC=104

BC=100

Section 7: Format and Usage BuIes for CMS Commands

207

GC20-1804-3 Page Modified by TNL GN20-2659
SYNONYM
SYNONYM

Use the SYNONYM command to invoke a table of synonyms to be used with,
or in place of, the CMS command names. You create the table yourself
using the CMS Editor. The fora for specifying the entries for the table
is described under "The User Synonym Table."
The names you define can be used either instead of or in conjunction
with the
standard eMS command truncations.
However, no matter what
truncations, synonyms, or truncations of the synonyms are in effect, the
full real name of the command is always operative. The format of the
SYNONYM command is:

r------.
I
I

SYNonym

I
I
I
I
I
I

1ft

III

.J.J.J

I
I
I
I
I
I
I
I
I

Ifn 1'§!!Q!!1! Ifmlll [(options ••• [)]]
I
I
I!llil
r

Q~1!QB~:

I~~~

[£1!!~]

of the

INOSTD I

is the filename
synonyms.

file

you created

is the filetype of the file containing your synonyms. The
filetype must be SYNONYM; of omitted, SYNONYM is assumed.

is the filemode of the
omitted, A1 is assumed.

file containing your

to contain

synonyms.

the

.§112

specifies that standard CMS abbreviations are operative •

NOSTD

standard eMS abbreviations are not to be used.
(But the
full CMS command and the synonyms you defined can still
be used.)

CLEAR

removes any synonym table
SYNONYM command.

set by

a previously

entered

The SYNONYM command specified with no operands can be used to nullify
the synonyms invoked by a preceding SYNONYM command; that is, you can
"turn off" a table of synonyms.
Note: The SET ABBREV ON or OFF command, in conjunction with the SYNONYM
command, determines which
standard and user-defined forms
of a
particular eMS command are acceptable.

208

IBM VM/370: Command Language Guide for General Users

SYNONYft
THE USER SYNONYM TABLE

You create the synonym table using the CftS Editor. The table must be a
file with the
filetype SYNONYft.
The file
consists of 80-byte
fixed-length records in free-form format with columns 73-80 ignored.
The format for each record is:
----,

systemcommand
L______
_

usersynonym

systemcommand is the name of the CftS
a synonym.

count

command for which you are creating

usersynonym

is the synonym you are creating for a CftS command. When
you create the synonym, you must follow the same syntax
rules as for commands, that is, you must use the character
set used to create commands, the synonym may be no longer
than eight characters, and ~u on.
For more details on
syntax rules for commands, see "Section 2: Vft/370 CP and
CftS Command Languages."

count

is the minimum number of characters that must be entered
for the synonym to be accepted by CftS. If omitted, the
entire synonym
must be entered (see
the following
example) •

A table of command synonyms is built from the contents of this file.
You may have several SYNONYM files but only one may be active at a time.
For example, if the synonym file contains:
MOVEFILE

MVIT

The synonym ftVIT can be entered as a command name to execute the
MOVEFILE command. It cannot be truncated since no count is specified.
ACCESS GETDISK 3
The synonyms GET, GETD, GETDI, GETDIS, or GETDISK can
the command name instead of ACCESS.

be entered as

There is a system synonym abbreviation table for the FILEDEF command.
The default values of the SET and SYNONYM commands are such that the
system synonym
abbreviation table is available
unless otherwise
specified.
The system synonym abbreviation table for the FILEDEF command states
that FI
is the minimum
truncation.
Therefore,
the acceptable
abbreviations for FILEDEF are: FI, FIL, FILE, FILED, FILEDE, and
FILEDEF. The system synomym abbreviation table is available whenever
both SET ABBREV ON and SYNONYft (STD) are in effect.
Assume that the
USERTAB SYNONYM A.
following entry:

user-defined table has the file
Further assume that this synonym

identification
table has the

Section 7: Format and Usage Rules for CftS Commands

209

GC20-1804-3 Page Modified by TNL GN20-2659
SYNONYM
FILEDEF USENAME 3
Then, USENAME is a synonym for FILEDEF, and acceptable truncations of
USENAME are: USE, USEN, USENA, USENAM, and USENAME. The user synonym
abbreviation table is available whenever both SET ABBREV ON and SYNONYM
USERTAB are specified.
No matter what synonyms and truncations
name of the command is always in effect.

are defined, the

full real

Figure 32 lists the forms of the system command and user synonym
available for the various combinations of the SET ABBREV and SYNONYM
commands.

DM5SYN7121 NO SYNONYMS (DM5INA NOT IN NUCLEUS)
The system routine
system.

DMSSYN002E
DMS5YN003E
DMSSYN007E
DMSSYN032E
DMSSYN056E
DMSSYN104S

210

which handles SYNONYM processing is

not in the

FILE 'fn ft fm' NOT FOUND RC=28
INVALID OPTION 'option' RC=24
FILE 'fn ft fm' NOT FIXED, 80 CHAR RECORDS RC=32
INVALID FILETYPE eft' RC=24
FILE 'fn ft fm' CONTAINS INVALID RECORD FORMATS RC=32
ERROR Inn' READING FILE 'fn ft fm' FROM DISK RC=100

IBM V"/370: Command Language Guide for General Users

SYNONYM

Acceptable
Co •• and
lorms

options
SET ABBRB, 0.
SYI USBRTAB (STD

FI
lIL

lILBDBl
USE
USBR

Co.ments
Tne ABBREV ON option of the SET
command and the STD opticn of the
SYNONYM command make the system
table available. The user synonym,
USENA!E is available
because the synonym table
(USERTAS) is specified on the
SYROIY! command. The truncations
for USENA!E are available because
SET ABBRBV 01 was specified with
the USERTAS also available.

USBRA!B
SBT ABBREV 011
SYN USBRTAB (STD

lILEDEP
USBNA!E

IThe user-defined synonym, USBRA!B,
I is permitted because the user
I synonym table (USBRTAB) is speciI fied on the SYNONYM command. No
I system or user truncations are
I permitted.

SBT ABBRBV ON
;
SYN USERTAB (BOSTDI
I
I
I

PILBDBl
USB
USEN

IThe system synonym table is UnI available because the NOSTD option
lis specified on the SYNONYM comI mand. The user synonym, USBIA!B,
I is available because the user synoI nym table (USBRTAB) is specified on
I the SYIOIY! command and the trunI cations of USBNA!B are permitted
I because SET ABBREV ON is specified
I with USBRTAB also available.

I
I
I
I
I

USENA!E

SBT ABBRBV opp
I
SYN USERTAB (NOSTDI
I
I
I
I
I
I
I
I
I

PILBDBP
USBNA!B

IThe system synonym table is made
I unavailable either by the SET
I ABBRBV 011 command or by the SYN
I (NOSTD command. The synonym,
I USBNA!B, is permitted because the
I user-defined synonym table
I (USERTAB) is specified on the
I SYROIY! command. The truncations
I for USBNA!E are not permitted
I because the SBT ABBREV OPP option
I is in effect.

SET ABBRBY 01
SYN (CLBAR STD

PI
PIL

IThe user-defined table is nov unavailable. The system synonym
table is available because both
the ABBREV OR option of the SBT
com. and and the STD option of the
SYNONYM command are specified.

PILEDBP
SBT ABBRBY OPP
SYI (CLEAR STD

PILEDEP

SBT ABBRBY 01
SYI (CLBAR NOSTD
SBT ABBRBV OPl
SYI (CLBAR 10STD
Pigure 32.

IBecause CLEAR is specified on the
I SYROIY! co.mand, the synonym and
I its truncations are no longer
I available. Either the SBT ABBRBV
I OPP co.mand or the SYRORY! (ROSTD
I command make the system synonym
I table unavailable.
I

System and User Truncations
section 7: Pormat and Usage Rules for C!S Commands

211

TAPE
TAPE

Use the TAPE co •• and to dump CMS-formatted files from disk to tape, load
previously dumped files from tape to disk, and perform various control
operations on a specified tape drive. TAPE is used solely for CMS
files; therefore, the files on tape are in a unique CMS format. The
TAPE command does not process multivolume files. Disk files to be
dumped can contain either fixed- or variable-length records. The format
of the TAPE command is:

TAPE

DUMP

Ifml
{;n } { ;t} 1* I
r

LOAD

, ,

[ (optionB optionC optionD[) ]]

Ifml I
:{;n} {;t} 11 I I
L

SCAB

I
I { ;n} {;t}

I
I

SKIP

[(optionA optionB optionD[) ]]

[ (optionB optionC optionD[) ]]

[ (optionB optionC optionD[ ) ]]

{ ;n} {;t}

MODESET

[ (optionD[ ) ]]
r ,

tapcmd

[ (optionD[) ]]

Inl
111
L .J

optionA:

liTM I
I!Q!Tftl

optionB:

I ROPRint I
IPRint I
II~!!
I
IDISK
I
L

optionC:

IEOT I
lEap nl
IIOP 11

optionD:

IITAPi
IITAP1
IL
Ir
Ilcuu
IIll1
LL

II
II
.J I
, I
II
II

[DEB nnn]

[TRTCH xx]

.J.I

DO!P {;n}{;t}[;a]
dumps one
or more
identification must be
212

17TRACKI
19TRACKI

disk files
to tape.
The file
specified. If the asterisk or mode

IBM V!/370: Command Language Guide for General Users

TAPE
letter only is coded, all files that
file identification are dumped.

satisfy the resulting

The filename (fn)
and file type
(ft)
of the files to be
dumped must be specified. The filemode
(fm) of the files to
be dumped is optional. The filemode letter indicates the
source disk for dumping; the filemode number indicates that
only files with that number are to be dumped.
A blank
filemode number indicates that all files satisfying the fn
and ft specifications are to be dumped.
LOAD

}[im]]

[{;n}{;t
writes tape files to disk.
If file identification is
specified, only that
one file is loaded.
The file
identification is filename (fn), filetype (ft), and filemode
(fm) •
If the option EOF n is specified and no file
identification is entered, n tape files are written to
disk. If an asterisk (*)
is specified for fn or ft, all
files within EOl
n that satisfy the
resulting file
identification are loaded.
The files are written to the disk indicated by the file,ode
letter.
The filemode number, if entered, indicates that
only files with that filemode number are to be loaded. A
blank file.ode number indicates that all files satisfying
the fn and ft specifications are to be loaded.

SCAN

[{;n}{~t}J
displays at the terminal (unless NOPRINT, PRINT or DISK is
specified)
the names of the files on tape.
If DISK is
specified the list of file identifiers is written to a file
named TAPE eAP.
If file identification (filename, fn, and
filetype, ft) is specified, scanning stops upon encountering
that file.
If not specified, scanning occurs over n tape
marks as specified by the option EOF n.

SKIP

{;n}{;t}
positions ~ne tape at a specified point, depending upon
other options
and operands.
If file
identification
(filename, fn, and filetype, ft) is entered, the tape is
positioned after the specified file;
if EOF n is entered,
the tape is positioned after n tape marks.
sets the values specified by the DEN, TRACK, and TRTCH
options. These values remain in effect for the specified
tape until they are changed in a subsequent TAPE command.

eODESET

r ,
tapcmd I n I

111

specifies a tape control function (tapcmd)
to be executed
times (default is 1 if ~ is not specified):

19.EcJl~

BSF
BSR
ERG
FSF
FSR
REi
RUN
iTe

Action
backspace ~ tape marks
backspace ~ tape records
erase gap
forward space ~ tape marks
forward space ~ tape records
rewind tape to load point
rewind tape and unload
write ~ tape marks

section 1: Format and Usage Rules for ces Commands

213

TAPE

Rote: If conflicting
in effect.

214

options are specified, the last

one entered is

iTK

writes a tape mark on the tape after each file dumped.

!Q!!A

writes a tape mark after each file is dumped, then
backspaces over the tape mark so that subsequent files
written on the tape are not separated by tape marks.

HOPRIHT

does not spool the list of files dumped, loaded, scanned,
or skipped to the printer.

PRIHT

spools the list of files
skipped to the printer.

dumped,

loaded, scanned,

displays a list of files
skipped at the terminal.

dumped,

loaded, scanned,

DISK

creates a disk file containing the list of files dumped,
loaded, scanned, or skipped. The disk file has the file
identification of TAPE KAP.

EOT

reads the
received.

EOP n
jQ! 1

reads the tape through a maximum of
is EOP 1.

TAPi
cuu

specifies the symbolic tape identification or the actual
device address of the tape to be read from or written to.
The default is TAP1 or 181.
The unit specified by cuu
must previously have been attached to your CKS virtual
machine before any tape I/O operation can be attempted.
Only symbol names TAP1 through TAP4 and virtual device
addresses 181 through 184 are supported.

7TBACK

specifies a 7 track tape. Odd parity, data convert on,
and translate off are assumed unless TRTCB is specified.

9TRACK

specifies a 9 track tape.

DEB nnnn

is the tape density where nnnn is 200, 556, 800, 1600, or
6250. If 200 or 556 is specified, 7TBACK is assumed. If
1600 or 6250 is specified, 9TRACK is assumed; if 800 is
specified, 9TRACK is assumed unless 7TRACK is specified.
In the case of dual-density drives, 1600 is the default.

TRTCB xx

is the tape recording technique for 7 track tape. If
TBTCB is specified, 7TRACK is assumed.
One of the
following must be specified as xx:

tape

until

end-of-tape

indication

tape marks. Default

IBK VK/370: Command Language Guide for General Users

TAPE
~

!~~~ing

odd parity, data convert off, translate off
odd parity, data convert on, translate off
odd parity, data convert off, translate on
even parity, data convert off, translate off
even parity, data convert off, translate on

OC
OT
E
ET

Tape records written by the CMS TAPE DUMP co •• and are 805 bytes long.
The first character is a binary 2 (1'02'), followed by the characters
CMS and an EBCDIC blank (1'40'), followed by 800 bytes of file data
packed without regard for logical record length. In the final record,
the character I replaces the blank after eMS, and the data area contains
CMS file directory information.

If a tape contains large files that would not fit on disk, the tape load
operation is terminated. To prevent this, when you dump the files,
separate logical files by tape marks, then forward space to the
appropriate file.
Because the CMS file directory is the last record of the file, the
TAPE command creates a separate workfile so that backspacing and
rereading can be avoided when the disk file is built.
If the load
criteria is not satisfied the work file is erased; if it is satisfied the
workfile is rena.ed.
The ROB option (rewind and unload) indicates completion before the
physical operation is completed. Thus, a subsequent operation to the
same physical device may encounter a device busy situation.
The TAPE
command creates a work file TAPE CMSOT1 which may exist if a previous
TAPB co.mand
has abnormally terminated.
If the work
file 1S
accidentally du.ped to tape and subsequently loaded, it appears on your
disk as TAPE CftSUT2.

DMSTPE101I BOLL PILE
A final record was encountered and no prior records were read in a
TAPE LOAD operation. 10 file is created on disk.
If the TERM option is in effect, the following is
terminal depending on the operation specified:

displayed at

the

Section 1: Format and Osage Rules for CMS Commands

215

LOADING •••••
fn ft fm

SKIPPIIG •••••
fn ft fm

TAPE
DU!PING •••••
fn ft f.

SCAIIIIG •••••
fn ft fa

When a tape mark is encountered the following
terminal if the TER! option is specifiea:

displayed at

the

END-OF-FILE OR END-OF-TAPE
If a tape contains large files that would not fit on disk, the tape
load operation is terainated. To prevent this when you duap the files
separate logical files by tape marks, then forward space to the
appropriate file.

D!STPE002D
D!STPE003E
D!STPE010E
DMSTPE014E
D!STPE017E
D!STPB023E
D!STPE027E
D!STPE029E
D!STPE037E
D!STPB042E
D!STPE043E
D!STPB047B
D!STPE048E
D!STPEOS7E
D!STPEOS8E
D!STPE070E
D!STPE104S
D!STPE10SS
D!STPE110S
D!STPE111S
D!STPE113S
D!STPE11SS

216

PILE (S) 'fn ft fa' NOT FOUID RC=28
INVALID OPTION 'option' RC=24
PRE!ATURB EOP 01 PILE 'fn ft fm' RC=40
INVALID FUNCTION 'function' RC=24
INVALID DBVICE ADDRESS 'cuu' RC=24
10 PILBTYPB SPBCIPIED RC=24
INVALID DEVICE 'device name' RC=24
IIVALID PARA!ETBR 'param' IN THE OPTION 'option' PIELD RC=24
DISK '.ode' IS READ/ONLY RC=36
10 PILBID SPECIPIBD RC=24
'TAPn(cuu)' IS FILB PROTECTED RC=36
NO PUNCTION SPBCIFIED RC=24
INVALID !ODE '.ode' RC=24
IIVALID RECORD POR!AT RC=32
END-OF-FILE OR END-OF-TAPE RC=40
INVALID PARA!BTBR 'para.' RC=24
ERROR Inn' READING FILE 'fn ft f.' PRO! DISK RC=100
BRROR Inn' WRITIIG PILE 'fn ft f.' ON DISK RC=100
ERROR READING 'TAPn(cuu)' RC=100
BRROR WRITIIG 'TAPn(cuu), RC=100
TAPn(cuu) NOT ATTACHED RC=100
{COIVERSIOI17
TRACK}
FBATURE
NOT
SUPPORTBD
01
(TRANSLATIONIDUAL-DENSITY) DEVICE 'cuu' RC=88

IB! V!/370: Co •• and Language Guide for General Users

TAPPDS
TAPPDS

Use the TAPPDS command to create CMS disk files from either tapes in
unblocked card~i.age for.at that are produced by the as IEBPTPCB service
program or froa tapes in the os IBBUPDTE service program control file
format, either blocked or unblocked. using the TAPPDS command, you can
also read unloaded partitioned data sets (PDS) from a tape created by
the os IEBMOVE service program, and create a CMS disk file for each
aember of the data set. The tape can be unlabeled or it can contain os
standard labels~ The for.at of the TIPPDS command is:

TAPPDS

Ifn 1ft Ifmlll
I * I * IA1111
I
I
1* III

[ (options ••• [) ]]

.J.J.J

QEtiQ'!!§: I PD2
I
IlfOPDS I
IUPDATEI

IEBD I
IIOEI!U
L

ICOLl I
I!QCO!!.l1

ITAPnl
11 AP jl

I MAXTElf I
Il!QMAXY!1

is the filename of the disk file to be created. This
field has meaning only if the ROPDS option is selected
(that is, the tape does not contain members of a
partitioned data set). If the tape does contain members
of a partitioned data set
(PDS), an asterisk must be
specified; one file is created for each member with a
filename the same as the member name. If lfOPDS or UPDATE
is specified, the default filenaae is TAPPDS.
The
default is assumed if the filename is omitted or coded as

*.
ft

is the filetype of the newly created files. The default
filetypes are CMSUTl (for PDS or lfOPDS) and ASSEMBLE (for
UPDATB).
The defaults are used if ft is omitted or
specified as *.

is the mode of the disk to contain the new
default filemode is Al if this field is
specified as an asterisk (*).

files. The
omitted or

If conflicting options are specified, the last one entered is used.
111 options, except TAPn, are ignored when unloaded PDS tapes are
read.
indicates that the tape contains members of an os
partitioned data set, each preceded by a "MEMBER
section 7: Format and Usage Rules for CMS Co •• ands

217

TAPPDS
BAftE=naae" stateaent. The tape aust have been created
by the as I!BPTPCB service prograa if this option is
specified.
IOPDS

indicates that the tape contains one file.

UPDATE

provides the ".1 ADD" function of the as IEBUPDTE
service prograa in your C!S virtual aachine.
It
indicates that the optional aaterial which is in
I!BUPDTE control file format is to be loaded onto disk
as CftS files. The filename of the new disk file is
taken from the BA!!= parameter in the ".1 ADD"
record.
The tape input file can be blocked or
unblocked. All records are written onto the CftS disk
in fixed-length, 80-byte format.
The !ID option is disabled when UPDATE is specified.
The CaLl option should be used with UPDATE so that the
scanning of the data starts at column one. The ".1 "
aust appear in columns 1~3. All records that do not
contain "./" in columns 1-3 which TAPPDS encounters
after an initial "./ ADD" record, are written onto
disk. Conversely, if ".1 ADD" is not found, the file
is not created on disk. The "./ "records are not
written as part of the file on disk.
An "./ IIDUP" record causes TAPPDS to close the
current file and stop processing without repositioning
the tape; also, a single tape aark has the saae
effect.
The optional 'label' in columns 3-10 of a ".1 " record
in an IEBUPDTE control file is not recognized by
TAPPDS. The record is treated as a data record and
included in the CftS disk file.
lor the ".1 ADD" record, if the IAftE= parameter is
aissing or followed by a blank, TAPPDS uses the
default filename "TAPPDS" for the CftS disk file. If
tbis condition occurs more than once during coamand
execution, then upon coapletion of the TAPPDS co.mand
only the last aember "./ ADD" without a valid Blftl=
parameter is on your disk with the default filename.

COL1

takes data fro. coluans 1-80; column 1 contains data.
takes data from columns 2-80: column 1 contains
control character information.
This is the format
produced by the as IEBPTPCB service program.

TAPn

218

liE!

is the tape unit number. TAP1 is the default tape unit
nu.ber, which corresponds to the virtual address 181.
There are four possible values of n: TAP1 through
T1P4, indicating virtual tape drives 181 through 184.

liD

considers an EBD stateaent a delimiter for the current
member.

IBft 'ft/370: Command Language Guide for General Users

T1PPDS
specifies that liD statements are not to be treated as
member delimiters, but are to be processed as text.
BAIT!!

reads up to ten meabers.
PDS option is selected.

This

is valid only

if the

reads any number of members.

DftSTPD7031

PILI 'fn ft [fm]' COPIID

The named file is copied to disk.
DftSTPD7071

Til PILlS COPIID

ftlXT11 vas specified and ten members are copied.

If the tape being read contains
displayed at the terminal.

DftSTPD003E
DftSTPDOS8E
DftSTPD10SS
DftSTPD110S

standard OS labels, the

IIVILID OPTIOI 'option' RC=24
IID-OP-PILI OR BID-OP-TIPE RC=40
ERROR Inn' IRITIIG PILB 'fn ft fm' 01 DISK
ERROR Inn' RB1DIIG 'TIPn(cuu)' RC=100

labels are

RC=100

Section 7: Pormat and Usage Rules for CftS Commands

219

TITLIB
TXTLIB

Use the TITLIE command to update CftS text libraries. A text library is
one which is to be searched for missing subroutines in LOAD and IRCLUDE
commands.
(See lote 1.)
A text library is a file that has a filetype of TITLIB and contains a
dictionary and one or more relocatable object programs obtained from CftS
files having a filetype of TEIT.
The TITLIB command:
•

Generates a text library.

•

Adds to an existing text library.

•

Deletes from an existing text library.

•

Libts the na.es and aliases or entry points and control section names
and the location of the TEIT files included in the text library.
The format of the TITLIB command is:

TIT lib

GEN

libname

fn1 [fn2

ADD

libname

fn1 [fn2

DEL

libnalle

ftAP

... ]
... ]

membername 1 [llembername2 ••• ]
r

I (TE Rft)
I
libname I (PRINT) I
I (121.§D
I

GEN libname fn1 [fn2 ••• ]
generates a text library with the specified filename (libname)
and a filetype of TITLIB from the TEIT files specified by fn1
fn2... If a file exists with the identification libname TITLIB,
it is erased and a new one is created.
ADD libname fn1 [fn2 ••• ]
appends the contents of the files specified by fn1 fn2 ••• to the
end of the existing library with the file identification libname
TITLIB. Bo checking for duplicate names, aliases, entry points,
or CSECT names is performed.
DEL libname memberna.e1 [.embername2 ••• ]
removes
the text
decks with
lIember names
(membername1,
memberna.e2 ••• ) from the directory of the text library, libname
TITLIB. If two .embers exist with the specified .e.bername, only
the first one encountered is deleted (unless the membername is
given twice in the argument list).
Deletions must be performed on
Definition (SD) in the text deck.
220

the IAftE or first Section
1 deletion for an alias name

IBft 'ft/310: Co.mand Language Guide for General Users

TXTLIB
or subsequent entry point results in a not found message with no
change to the member. DEL removes the member and all references
to it.
The file is automatically compressed
the deleted members can be reused.
r

so that

occupied by

I (TERft)
ftAP libname I (PRIIT)
i (DISK)
L

I
I
I
.J

generates the file libname ftAP on the primary disk. If a file
already exists with the same identification, it is erased and the
new file is created.
The libnaae ftAP file contains the same
information as that in the dictionary of the specified text library
and is in the format of a list of entry points and control section
names that reside in the text library, and their location or index
in the file.
The options on the command line are examined to
determine if the ftAP is to be directed to the terminal (TERft), or
the printer (PRIIT), or is to remain on disk (DISK).
The ftAP operand of the TXTLIB command displays a statement
indicating the total number of entry points and control section
names that currently exist in the TXTLIB file.

The total number of members in the TXTLIB file cannot exceed 1000.
When this number is reached, an error message is displayed. The
text library created includes all the text files entered up to (but
not including) the one that caused the overflow.

as Linkage Editor EITRY, ALIAS, and IAftE control statement are
accepted. If a IAftE statement is detected, only ALIAS and IAftE
'names' are included in the dictionary for that text deck.
Deletions must be performed on the IAft! 'name'.
The total number
of ALIAS names cannot exceed sixteen names per text deck.

Unlike as STEPLIB entries, CftS TXTLIB members are not fully
link-edited. The loader, for either an explicit or dynamic load,
attempts to resolve all external references. Por a dynamic load,
if all VCOls cannot be resolved within a member, an incorrect entry
point might be returned.
You
should explicitly load those
subroutines by either CftS LOAD and IRCLUDE commands or by a VCOI in
the program.

Response
xxx EITRIBS II LIBRARY
When TXTLIB is issued,
specified t~xt library
number of entries in the
terminal when the TXTLIB

the contents of the dictionary of the
are displayed at the terminal.
The
text library (xxx) is displayed at the
ftAP command is issued.

Section 7: Pormat and Usage Rules for CftS Commands

221

TITLIB

DMSLBT001E
DMSLBT002E
DMSLBT002W
DMSLBT003E
DMSLBT013E
DMSLBT014E
DMSLBT046E
DMSLBT047E
DMSLBT056E
DMSLBT056W
DMSLBT104S
DMSLBT105S
DMSLBT106S
DMSLBT213W

222

10 FILENAME SPECIFIED RC=24
FILE 'fn ft' NOT FOUND RC=28
FILE 'fn ft' lOT FOUND RC=4
IIVALID OPTIOI 'option' RC=24
MEMBER 'na.e' NOT FOUND IN LIBRARY 'fn ft f.'
RC=32
IIVALID FUICTION 'function' RC=24
NO LIBRARY NAME SPECIFIED RC=24
10 FUICTION SPECIFIED RC=24
FILE 'fn ft f.'
CONTAINS [{NAMEIALIASIENTRYIESD)] INVALID
RECORD FOBMATS RC=32
FILE 'fn ft f.'
CONTAINS [{NAMEIALIASIENTRYIESD)] INVALID
RECORD FOBMATS RC=4
ERROR Inn' READING FILE 'fn ft fm' FROM DISK RC=100
ERROR Inn' WRITING FILE 'fn ft fm' OR DISK RC=100
NUMBER OF MEMBER RAMES EXCEEDS MAX 'nnnn'. FILE 'fn ft' ROT
ADDED RC=88
LIBRARY 'fn ft f.' NOT CREATED RC=4

IBM VM/370: Command Language Guide for General Users

TYPE

TYPE
Use the TYPE co •• and to display all or part of a specified file at the
terminal in either EBCDIC or the hexadecimal representation of
EBCDIC code. The format of the TYPE command is:

Type

fn ft [fa]

r
r"
I recl Irecnll [(options ••• [)] ]
I
I ! II
I .1
I
II

°Et!.Q.!!.§:

....

I
,xxxxx )
I "lYYYY I
II CO L<
1
>- I
I

I
I
I

)

l!f~cll

I
I MEMBER
I

I
I
I

[HEX]

is the filename of
must be specified.

the file to

be displayed.

This field

is the filetype of
must be specified.

the file to

be displayed.

This field

fll

is the filemode of the file to be displayed. If this field
is omitted, the A-disk and its extensions are searched to
locate the file.
In the case of files with duplicate
filena.e and filetype, only the
first file found is
n;
C:!n1 "" 'D~..:I
- .......
r ........ ~'I:;i .... •

recl

is the record number of the first record to be displayed.
This field cannot contain special characters. If recl is
greater than the number of records in the file, the file
length is assu.ed.
If this field is omitted or entered as
an asterisk, a record number of 1 is assumed.

recn

is the record number of the last record to be displayed.
This value cannot contain embedded commas. If this field is
not specified or is entered
as an asterisk, display
continues until end of file is reached.

section 7: Por.at and Usage Rules for CMS Commands

223

TYPE

COL xxxxx yyyyy
displays only certain positions of each record. xxxxx
specifies the beginning position and yyyyy the ending
position of the field within the record which is to be
displayed.
If a field is not specified, the entire
record is displayed unless the filetype is LISTING, in
which case the first position of each record is not
displayed, since it is assuaed to be a carriage control
character.
HEX

displays the file in hexadecimal format.

* } displays member (s) of a
{ name
is a library, a eEeBER

library. If the file specified
entry can be specified. If an
asterisk (*) is specified, all members of the library
are displayed. If a name is specified, only that
particular member is displayed.

The file is
displayed
specifications.

DeSTYP002E
DeSTYP003E
DMSTYP005E
DMSTYP009E
DMSTYP013E
DMSTYP029E
DMSTYP033E
DMSTYP039E
DMSTYP049E
DMSTYP054E
DMSTYP062E
DMSTYP104S

224

the

terminal

according

the

FILE 'fn ft fm' NOT FOUND RC=28
INVALID OPTION 'option' RC=24
INVALID 'option' SPECIFIED RC=24
COLueN 'col' EXCEEDS RECORD LENGTH RC=24
MEeBER 'name' NOT FOUND IN LIBRARY RC=32
INVALID PARAMETER 'para.' [IN THE OPTION 'option'
RC=24
FILE 'fn ft fm' IS NOT A LIBRARY RC=32
NO ENTRIES IN LIBRARY 'fn ft fm'
RC=32
INVALID LINE NUMBER 'line number'
RC=24
INCOMPLETE FILEID SPECIFIED RC=24
INVALID
IN FILEID RC=20
ERROR 'nne READING FILE 'fn ft fm' FROM DISK RC=100

IBM VM/370: Com.and Language Guide for General Users

given

FIELD]

GC20-1804-3 Page Modified by TNl GN20-2659
UPDATE
UPD~.TE

Use the UPDATE command to modify program source files. The source files
should be stored as 80-character card-image files with sequence fields
in record positions 73 to 80. The UPDATE command accepts a source input
file and one or more files containing update control statements and
update source records. ~n~ UPDATE command creates an updated source
output file,
an update log file indicating what changes, if any, were
made, and an update record file if more than a single update file is
applied to the input file.

Updates may be applied either permanently
output file replaces the source input file), or
case the updated output file has the name 'Sfn',
name of the input source file.
The format of the

(that is, the updated
temporarily, in which
where Ifni is the file
UPDATE command is:

._--,

r---- ,----------------------------------------------r
r
"

Update

fnl

Ift1
Ifml [fn2 [ft2 [fm2]]]l1 [(options ••• [)]]
IASSEMBlE IAl
II
L ---,..-----

QE1!Q!!~:

IREP
I
I!Q!!!fl
L

ISTK

I!Q~±~I
L

.J .J

I
I.§!H!!!
INOSEQ81

IINC

ITERM
I
INOTERM I
L

I!Q!!~I
.J

r
I~!.§~

I
tPRINT I

ICTl

,
I

I!Q~±~I
L

ISTOR I
tNOSTORI
L

fn 1 ft 1 f.l
is the filename, filetype, and filemode of the source input
file.
If the file mode or filetype is omitted, 'Al' and
'ASSEMBLE' are assumed, respectively.
fn2 ft2 fm2
is the filename,
filetype,
and
file.ode of the file
containing the update control statements and updated source
records, or, if the CTl option is specified, specifies the
filename, filetype, and filemode of the update control file
to be used for a multiple update. The defaults are fnl
UPDATE 11 if NOCTl is in effect, and fn1 CNTRl A1 if CTl is
specified.

REP

replaces with the
source file.

source input

file

with the

updated

retains the old file in its original form, and assigns a
different filename to the new file, consisting of a
dollar sign
(S) plus the first seven characters of the
input filename (fnl).

section 7: Format and Usage Rules for CftS Commands

225

GC20-1804-3 Page Modified by TNL GN20-2659
UPDATE
specifies that the entire sequence field (columns 73
through 80) contains an 8-digit sequence number on every
record of source input.
NOSEQ8

specifies that columns 73-75 contain a 3 character label
field, and that the sequence numter is a 5-digit value in
columns 76-80.

INC

puts sequence numbers in columns 73 through 80
updated record inserted from the update file.

of each

puts asterisks (********) in the sequence number field of
each updated record inserted from the update file.
CTL

specifies that fn2, ft2, and fm2 describe an update
control file for applying multiple update files to the
source input file (see the "Control statement Formats"
section that follows).
~2igl

The CTL option implies the INC option.

specifies that a single update file is to
the source input file.
STK

be applied to

stacks information resulting from a multiple update at
your CMS console.
This information can then be read by a
CMS EXEC procedure.
STK is used only with the CTL
option.
specifies that no external
update results is desired.

communication of the multiple

displays warning messages at the terminal whenever a
sequence or update control card error is discovered.
(Such warning messages appear in the update log, whether
they are displayed at the terminal or not.)
NOTERM

suppresses the displaying of warning messages at the
terminal. However, error messages which terminate the
entire update procedure are displayed at the terminal.
places the update log file on disk.
This file has a file
identification "fn UPDLOG", where "fn" is the filename of
the file being updated.

226

prints the
printer.

update

log file

directly

STOR

specifies that the source input file is to be read into
storage and the updates performed in storage prior to
placing the updated source file on disk.
This option is
meaningful only when used in conjunction with CTL option
since the benefit of increased processing speed is
realized when processing multiple updates.
STOR is the
default when CTL is specified.

NeSTOR

specifies that no updating is to take place in storage.
NOSTOR is the default when performing single updates or
when CTL is omitted from the command line.

IBM VM/370: Command Language Guide for General Users

the

virtual

GC20-1804-3 Page Modified by TNL GN20-2659
UPDATE

The UPDATE control statements let you insert, delete and replace source
records, as well as resequence the output file.
All UPDATE control
statements are identified by the characters '.j' in columns 1 and 2 of
the 80-byte record, followed by one or more blanks and a maximum of 6
additional, blank-delimited fields. Control statement data must not
extend beyond column 50. All references to the sequence field of an
input record refer to the numeric data in columns 73-80 of the source
record, or columns 76-80 if NOSEQ8 is specified. Leading zeros in
sequence fields are not required.
If no sequence numbers exist in an
input file, a preliminary UPDATE with only the ' . j S' control statement
can be used to establish file sequencing.

section 7: Format and Usage Rules for CMS Commands

226.1

UPDATE

Any sequence fields in the update control statements are ignored; if
the BOIBC option is specified, all sequence fields in the update file
are ignored, including those on inserted records. If the INC option is
specified, sequence fields for the inserted records are either generated
by UPDATE, if the dollar-sign
($) delimiter is used, or
are included
intact from the update file if the dollar sign ($) is not used.

Changes are made sequentially in a single pass through the input and
update files; an error condition results if any sequence errors occur in
the update control statements, and warnings are issued if an error is
detected in the sequencing of the input file. Any source input records
with a sequence field of eight blanks are skipped, without any
indication of a sequence error. Such records may be replaced or deleted
only if they occur within a range of records that are being replaced or
deleted entirely and if that range has limits with valid sequence
numbers. There is no means provided for specifying a sequence £ield of
blanks on an update control statement.

-- resequences the updated source output file
in columns 73-80
(if SEQ8 is specified), or in columns 76-80 with the
label placed in columns 73-75
(if NOSEQ8 is specified).
If this
statement is included in the update file, it must be the first control
statement. The for.at of the sequence control statement is:

~~~~~~ Co~!~~J Sta!~~~nt

[seqstrt

[seqincr

[label]]]

seqstrt

a one- to eight-digit numeric field specifying the
first decimal sequence number to be used. The default
value is 1000 if SEQ8 is specified and 10 if NOSEQ8 is
specified.

seqincr

a one- to eight-digit numeric field specifying the
decimal increment for resequencing the output file.
The default is the 'seqstrt' value.

label

a 3-character field to be duplicated in columns 73-75
of each source record if NOSEQ8 is specified.
The
default value is the first three characters of the
input filename (fnl).

An error is indicated if any valid control statement
precedes the
./ S state.ent in the update file, and the resequence operation is
suppressed.

Each source record is resequenced in columns 73-80 as it is written
onto the output file.
Both unchanged records from the input file and
records inserted from the update file are resequenced.

Section 7: Pormat and Usage Rules for CMS Commands

227

UPDATE
Insert control statement -- inserts all
next-controI-stateaent:-into the output
control statement is:

records following it, up to the
file. The for.at of the Insert

r----------------------------------------------,
.1 I seqno [$ [seqstrt [seqincr]]]
I

seqno

is the sequence nuaber of the source input
following which the insertion is to be made.

optional delimiter indicating that the inserted records
are to be sequenced incrementally.

seqstrt

a one- to eight-digit numeric field specifying
first deciaal number to be used for sequencing
inserted records.

seqincr

a one- to eight-digit numeric field specifying the
decimal increment for sequencing the inserted records.

record

the
the

All records following the ".1 I" statement, up to the next control
state.ent, are inserted in the output file following the record
identified by the "seqno" field.
If the BOIIC option is specified, each
inserted record is identified with asterisks (********) in coluans
73-80. If either the IIC or CTL option is specified, the records are
inserted unchanged in the output file, or they are sequenced according
to the "seqstrt" and "seqincr" fields, if the dollar sign ($)
key is
specified.

The default sequence increment, if the dollar sign is included, is
determined by using one tenth of the least significant, non-zero digit
in the seqno field, with a aaxiaum of 100. The default seqstrt is
computed as seqno plus the default seqincr. For exaaple, the control
statement:

.1 I

2600 $ 2610

causes the inserted records to be sequenced 11102610, 11102620, and so
forth (NOSEQ8 assumed here). For the control statement:
./

240000 $

the defaulted seqincr is the maxi.un, 100, and the starting sequence
number is 240100.
SEQ8 is assumed, so the inserted records are
sequenced 00240100, 00240200, and so forth.

If either INC or CTL is specified but the dollar sign is not
included, whatever sequence number appears on the inserted records in
the update file is included in the output file.

228

IB8 V8/370: Command

Languag~

Guide for General Users

UP£ATB
Delete Control statement -- deletes one or more records from the source
fIle:- The-format of-the Delete control statement is:

D seqnol

[seqn02]

[$]

seqnol

is the sequence number identifying
record to be deleted.

seqn02

is the sequence
deleted.

is an optional
control fields.

number

of the

the first
last

delimiter indicating

record
the

or only
to

end of

be
the

All records of the input file, beginning at seqnol, are deleted from
the output file, up to and including the seqn02 record. If the seqn02
field is oaitted, only a single record is deleted.
ReEl!£! £2n!I2! sta!~~nt -- replaces one or more input records with
updated records froa the update file. The format of the Replace control
statement is:

R seqnol [seqn02] [$ [seqstrt [seqincr]]]1
I

seqnol

is the sequence number of the
replaced.

seqn02

is the sequence
replaced.

is an optional delimiter key indicating that the
substituted records are to be sequenced incrementally.

seqstrt

a one- to eight-digit numeric field specifying
first deciaal nuaber to be used for sequencing
substituted records.

seqincr

a one- to eight-digit nuaeric field specifying the
deciaal increment
for sequencing
the substituted
records.

number

first input record to be

of the

last

record

the
the

All records of the input file, beginning with the seqnol record, up
to and including the seqn02 record, are replaced in the output file by
the records following the ".1 R" statement in the update file, up to the
next control statement. As with the ".1 D" (delete) function, if the
seqn02 field is omitted, only a single record is replaced, but it aay be
replaced by more than a single inserted record. The ".1 R" (replace)
function is perforaed as a delete followed by an insert, such that the
number of statements inserted need not match the number deleted. The
dollar sign ($), seqstrt, and seqincr processing is identical to that
for the insert function.

section 7: Poraat and Usage Rules for CftS Co.aands

229

UPDATE
Co~! ~ta!~~ent~

,I • /

--The for.at of the Comment statement is:

* [ co.ment ]

indicates that this
be ignored, except
file.

is a co •• ent state.ent, and is to
that it is copied into the log

The following sections describe the files used and created by the UPDATE
command, and the placement of the files created.
INPUT PILES WHEN ~ SINGLE UPDATE IS TO BE APPLIED: When the CTL option
Is-nQt-specifled 1n the-UPDiTi-com;and~ line;-only one update is applied
to the source file. The input files are:
•

The source file, which is to be updated. The filename of this file
must be specified in the co •• and line.
The filetype and file.ode
default to ASSE8BLE and A1, respectively, unless overridden by the
command line.

•

The update file, whose control statements have been described in the
preceding section.
The filename of this file defaults to the
filename of the source file, and the filetype and file.ode default to
UPDATE and A1, respectively.
All three may be overridden by the
command line.

OUTPUT PILES WHEN A SINGLE UPDATE IS APPLIED: When a single update is
applied-to-the-source-file, the-following-output files are created:
•

An updated source file is created.
"Sfn" becomes the nalle of this
file, where "fn" is the filename of the original source file, unless
the REP option is specified. When the REP option is specified, the
filename of this file becomes "fn".
(Por exceptions, see the
"Warning and Error Handling" section that follows.)

•

An update log, showing all transactions and errors, is created. The
filename of the file is the filename of the original source file, and
the filetype of this file is UPDLOG. Note, however, that if the
PRINT option is specified with the co.m~nd line, then the update log
is printed directly on the virtual spooled printer, and no disk file
is created.

INPUT PIl!ES WHI! 8U!!1!LEVEL ,!!PD!TE,§ A!!~ !~~LI~~: When the CTL option is
specified on the co.mand line, multilevel updates are applied to the
source file. In this case, the following files are input to the UPDATE
command:
•

230

A source file, specified
for a single update.

in exactly the salle way as

IB8 V8/370: Co •• and Language Guide for General Users

the source file

UPDATE
•

A control file that controls what updates are applied, and the order
in which they are to be applied.
The filename of this file defaults
to the filename of the source file, and the file type and filemode
default to CITBL and A1, respectively. All three may be overridden
by the command line. This file contains, in its control statements,
pointers to update files, PTP files, and auxiliary files (these are
described in "The CTL option" section).

•

One or more update files, as specified by the control
filename of these files is the same as the filename of
file. The filetype of these files is "UPDTxxxx".

•

Auxiliary files, as specified by the control file.
The filename of
these files is the same as the filename of the source file. The
filetype of these files is "AUXxxxx". The filetype can be specified
as either 'AUXnnnn l or 'nnnn AUX'. If you use the second fora, the
first three characters may not be 'lUX'. The auxiliary files contain
additional control statements pointing to PTP files.
The format of
the auxiliary files is described in a later section, "The CTL
Option."

•

PTP files, as specified by either the control file or the auxiliary
files. The filename of these files is the same as the filename of
the source file. The filetype is specified in full by the control
file or the auxiliary file. In format, these files are identical to
ordinary update files.

file. The
the source

OUIRYI l!11~ !~EI ~Y1I!11V!1 UPRATES !Il !PP1!J~: When the CTL option is
specified, the following output files are created by the UPDATE command:
•

An updated source file, as in the case of a single update.

•

An update log, as in the case of a single update.

•

An UPDATES file.
This file has the filename of the original source
file, and a file~ype of UPDATES.
It contains sum.ary information
about which updates were applied to the file, and is intended to be
concatenated onto the assembly text deck for documentation and
information purposes.

•

Although not a disk file, additional "output" is produced in the form
of lines placed in the terminal read stack, for interrogation by an
EXEC file which may have invoked the UPDATE co.mand. These lines are
placed there only if the STK option is specified.

AQRJ QI OUTPUT lItES: If. there are several read/write disks
accessed when the UPDATE command is invoked, the following steps are
taken to determine the disk upon which the output files are to be placed
(the search ~tops as soon as one of the following steps is successful):

~lSK

•

If the disk on which the original source file resides is read/write,
then the output files are placed on that disk.

•

If that disk is a read-only extension of a read/write disk, then the
output files are placed on that particular read/write disk.

•

Otherwise, the output files are place
(the A-disk) •

on the primary read/write disk

section 7: Format and Usage BuIes for eftS Commands

231

UPDATE

If the NOCTL option is specified or defaulted, UPDATE processes one
input file and one update file to produce an updated source output file
and an update log file containing a record of what changes were .ade.
This .ode of operation is suitable for testing modifications prior to
incorporating them in the base source code, providing that only one set
of changes has to be tested at a tiae. If, for any reason, more than
one set of changes is outstanding against a single source input file,
the difficulties in managing that base code can multiply very rapidly.
lor this reason, UPDATE provides the CTL option, which has a multilevel
update control and aanagement scheme developed for updating Y!/370
distributed source code, and may be used wherever its advantages are
felt.
The major components of the multilevel update scheme are:
•

A set of base source code which is not permanently changed.

•

A set of update files for each source
specific order.

•

One or more CNTRL files that describe the
updates to be applied to each source file.

•

Optionally, one or more auxiliary control files, each pertaining to a
specific source file.

file that must be applied in a
order

or priority

An integral part of the multilevel update scheae is a naming
convention for the update files themselves, and for any TEXT files
produced by assembling or compiling the updated output files. In normal
usage, any update file bas the filenaae of the source file to which it
applies and the filetype of UP£ATE. When the CTL option is used to
invoke the aultilevel update controls, the filenaae usage becomes a
requireaent, such that the update files must have the filename of the
source file to which they apply, but the filetypes are modified to
distinguish between separate update levels.
The filetype for an update
file is constructed froa UPDT plus a one- to four-character update
identifier. lor example, if the command
UPDATE D!SUPD ASSE!BLB Al 14 eNTRL 11 (CTL
is issued, the source file is D8SUPD ASSE!BL! Al and the control file is
X4 CNTRL Al. Assuae that the control file contains three update files,
naaed "D!SUPD UPDT750", "D8SUPD UPDTX4", and "D!SUPD UPDT009."
The
CNTRL file specifies which update files are to be applied to the source
file and in what order they are to be applied, on the basis of the
update identifier.
Another identification para.eter, the update level
identifier, is used when naaing a TEXT file produced from the updated
source file. The update level identifier is specified by the CNTRL file
and is associated with a specific update identifier, also in the CNTRL
file. Por exa.ple, a file naaed X4 CNTRL, to apply the above .entioned
updates to D!SUPD ASSB!BLE, aight appear as follows:
OOD
X4D
75X
009X

232

!ACS D8SLIB
UPDTX4
UPDT750
UPDT009

SYSLIB

IB! Y8/370: Coa.and Language Guide for General Users

UPDATE

This control file applies the updates DMSUPD UPDT009, DMSUPD UPDT750,
and DMSUPD UPDTX4, in that order, to the file DMSUPD ASSEMBLE. The
updates are applied in reverse order as they appear in the CHTRL file,
that is, the lowest level of update is at the bottom of the file, and
the highest level update is at the top. As the CBTRL file and update
files are processed, the UPDATE co.mand displays the following message
at the terminal:
DMSUPD178I UPDATING ['fn ft f.'] WITH 'fn ft fm'
for each update file which is applied to the source input during the
multilevel update; the bracketed expression is displayed only for the
first update.

In the above example, the fields X4D, 75X, and 009X are the update
level identifiers, associated with the UPDTX4, UPDT750, and UPDT009
update identifiers, respectively_ According to the naming convention
for VM/370 TEXT files, the result of assembling the updated $DMSUPD
ASSEMBLE file would be named DMSUPD TXTX4D, where the X4D is the update
level identifier of the highest-level update applied.
The TXT portion
of the filetype indicates that this is a TEXT file, but allows up to a
five-character update level identifier.

The STK option is provided for use with the multilevel update invoked
via the CTt option, primarily for communication with CMS EXEC procedures
which invoke UPDATE.
If the CTL and STK options are specified, UPDATE
places two lines of data in the CMS terminal read stack, as follows:
first line

second line =

*
*

update level identifier
library list from 'MACS' record

These lines are placed in the terminal read stack via the CMS ATTN
function, and are available to an invoking EXEC procedure via the EXEC
control words &READ ARGS or &R!AD VARS. The first line, the update
level identifier, ~s the level identifier of the highest level update
applied; this is the TEXT file filetype-modifier used by the VM/370
update procedures.
The second line consists of the list of libraries
specified on the MACS record in the CBTRL file. The library search
order for an assembly or compilation can be established by issuing the
GLOBAL com.and using the library list returned.

If the NOSTK option is used with the multilevel update, no data is
made available to external procedures and the update level identifier
has no meaning_

Section 7: Pormat and Usage Rules for CMS Commands

233

UPDATE

If the command
update proga assemble

proga cntrl

(ctl stk)

is issued and the contents of the PROGA CNTRL file are

THIS IS AN EIAftPLE OF A CONTROL FILE
OOD ftACs BILIB SIS LIB
* FII POR SAVING ALL REGISTERS
OOA UPDTLVL4
PTP A7300Dfts
* AUX FILE CONTAINING UPDATES POR B1 FEATURE
OOB AUILVL3

and the contents of the PROGA AUILVL3 file are

* PTF A2330Dfts
PTl A2330Dfts
* PTF A091SDBs

CONTAINS FUNCTIOIAL CODE FOR B1
COITAIls BRROR ftEssAGBs lOR B1

PTP A091SDfts

The files listed below are used to update PROGA AssEBBLE in the order
indicated.
!i!!1!~!§

PROGA
PROGA
PROGA
PROGA

!i!!iI~

A091SDBs
A2330Dfts
A7300Dfts
UPDTLVL4

The resultant output file SPROGA AssBBBLE contains the updates from
the four files listed. In addition, two lines are placed in front of
the CBS terminal read stack:

*
*

OOA
ftlLIB SIS LIB

If the UPDATB command shown
followed by the BIBC com.ands:

was issued

from an EXEC

procedure and

&RBAD VARs &11 &12
&RBAD VARs &13 &14 &15
then
&11
&12
&13
&14
&15

=*
= OOA
=*
= ftlLIB
= SIS LIB

In this example, the UPDATB command was entered from the terminal and
the stacked lines are ignored by Cfts.
234

IBB Vft/370: Command Language Guide for General Users

UPDATE

The UPDATE command detects a nuaber of invalid requests, and decides
whether they should be treated as warning situations or as errors. The
following is a general description of the handling of these situations,
and the return codes associated with each.

SE~YI!CI!2 !]~ UPDATE
~OIIj2~ ~!~ IB!OR~: These errors
are treated as
"Yarning situations. n That ~S, a warning .essage is generated, and
processing continues.
The warning messages are printed in the update
log, and are displayed on the terminal unless the IOTEBft option is
specified in the coamand line. The errors are:

•

Input sequencing errors (return code = 4).
The input source file
contains sequence errors (sequence numbers in nonascending order) •

•

Output sequencing errors (return code = 8). The updating procedure
introduces new sequencing errors into the output source file •

•

Invalid update control statements (return code = 12).
The update
file contains invalid control statements. Erroneous statements in
control files cause the update procedure to terminate.

If more than one such error is detected, the UPDATE co.mand returns
the highest return code (4, 8, or 12) encountered.
If any such error is detected, the REP option, if specified, is
ignored, and the update source file retains the filenaae "$fn", as if
IOBIP was in effect.

OTHER ERRORS: Other errors are invalid control file stateaents, invalid
file foriats, and disk input/output
errors.
The UPDATE comaand
processing is terainated as soon as the error is detected. The return
code is always 20 or greater.
If any such error is detected, the update file is left with the
filename UPDATE and the filetype CftSUT1, so that you may exaaine or
otherwise aake use of it. This file aust be erased before the UPDATE
co ••and can be invoked again.

PILE 'fn ft fa,' REC In = update control stateaent
This aessage is displayed when the TEB! option is specified and an
error is detected in an update file. It identifies the file and
record nuaber where the error is found.
DftSUPD177I WABIIIG
IGIOBED. ]

ftESSAGES

ISSUED

(SEVEBITY=nn).

['REP'

OPTIOI

updating process.
the 'nn' field is

The
the

Section 7: Poraat and Usage Rules for CftS Co •• ands

235

Warning aessages were issued
severity shown in the error

during the
message in

OPDATE
highest of the return codes associated with the warning aessages
which were generated during the updating process.
The warning return codes have the following meanings:
RC = 4; Sequence errors were
being updated.

detected in the original source file

RC = 8; Sequence errors which did not previously exist in the
source file being updated were introduced in the output file
during the updating process.
RC = 12; Any other nonfatal error detected during the updating
process has a return code of 12. Such errors include invalid
update file control statements, and missing PTF files.
The severity value is passed back as the return code fro. the
UPDATE command.
In addition, if the REP option is specified in
the co •• and line, then it is ignored, and the updated source file
has the fileid "Sfn1 ft1", as if the RBP option was not
specified.
DftSUPD1781

OPDATIIG ['fn ft fm'] WITH 'fn ft fa'

The specified update file is being applied to the source file.
This message appears only if the CTL option is specified in the
command line. The updating process continues.

DftSUPD001E
DftSOPD002E
DftSUPD003E
DftSUPD007E
DMSUPD010W
DftSUPD024E
DftSUPD037E
DftSUPD048E
DftSUPD065B
DftSUPD066B
DftSUPD069E
DftSUPD070E
DftSUPD104S
DftSUPD105S
DftSOPD174W
DftSOPD176W
DftSUPD179E
DftSUPD180W
DftSOPD181E
DftSUPD182W
DftSUPD183B
DftSUPD184W
DftSUPD185W
DftSOPD186W
DftSUPD187E
DftSOPD207W
DftSUPD210W

236

NO FILENAftE SPECIFIED RC=4
FILE 'fn ft fm' BOT FOOND RC=28
INVALID OPTIOB 'option' RC=24
FILB 'fn ft fa' IS BOT FIXBD, 80 CHAR. RECORDS RC=32
PREftATURE EOF OF FILE 'fn ft fa' --SEQ NUftBBR , ••••••••• NOT
FOUID RC=12
FILE 'UPDATE CftSOT1 f.' ALREADY EXISTS RC=24
DISK IA' IS READ/OBLY RC=36
INVALID ftODE ·.ode· RC=24
'option' OPTIOI SPECIFIBD TWICE RC=24
'option' AND 'option' ARE CONFLICTIBG OPTIONS RC=24
DISK 'A' BOT ACCESSED RC=36
INVALID PARAftETER ·para.· RC=24
ERROR 'nn' RBADIBG FILE 'fn ft fm' FROM DISK RC=100
BRROR 'nn' WRITING FILE 'fn ft fa' ON DISK RC=100
SEQUBICE BRROR IBTRODUCED IN OUTPUT FILE:
••••••••
TO
••••••••• RC=8
SEQOEICIIG OVERFLOW FOLLOWING SBQ BOMBER· •••••••• • RC=8
ftISSING OR DUPLICATE 'ftICS' CARD IN COBTROL FILB 'fn ft fa'
RC=32
ftISSING PTF FILE 'fn ft f.' RC=12
10 UPDATB PILBS WBRB POUID RC=40
SEQUENCE INCREftENT IS ZERO RC=8
IBVALID {COJTROLIAUX} FILE CONTROL CARD RC=32
'./S • NOT FIRST CARD IN INPOT PILE --IGNORED RC=12
IBVALID CHAR II SBQUEBCE FIBLD •••••••••• RC=12
SEQOENCE NOftBER •••••••••• NOT POOND RC=12
OPTION 'STK' INVALID WITHOUT 'CTL' RC=24
IIVALID UPDATB PILB CONTROL CARD RC=4
IBPUT FILE SEQUENCE ERROR: ••••••••••• TO ••••••••••
RC=4

IBft VM/370: Command Language Guide for General Osers

GC20-1804-3 Page Modified by THL GN20-2659
IMMEDIATE COMMANDS
IMMEDIATE COMMANDS

An IMMEDIATE command is issued after an Attention interrupt is given to
CMS by pressing the Attention key
(or its equivalent).
such commands
are processed immediately upon entry from the ter.inal or on being
'stacked' by an EIEC procedure. Any program execution in progress is
suspended until the immediate command is processed. The com~ands are HB
(hal t batch execution), HO
(halt SVC tracing), HT
(halt typing),
HI
(halt execution),
RO (resume tracing), RT
(resume typing), and SO
(suspend tracing temporarily).

I HB
Use the HB co •• and to stop the execution of a CMS Batch virtual machine
at the end of the current job. If the virtual machine is running in
disconnect mode, it must be reconnected. Press the Attention Key to stop
program execution and enter the command. CMS sets a flag such that at
the end of the current job, the batch processor generates accounting
information for the current job and then logs out the eMS Batch virtual
machine.

Hone.

HO
Use the HO co •• and during the execution of a command or one of your
programs to stop the recording of trace information. In order for the HO
co.mand to be recognized, it must be entered after you stop progra.
execution by an Attention interrupt. Program execution continues to its
normal completion, and all recorded trace information is spooled to the
printer.
The format of the HO command is:

r-------------------------------------------------------------------------,

IL---________
BO
• _______________________________________________________________

Hone.

Section 7: format and Usage Rules for eMS eom.ands

237

GC20-1804-3 Page Modified by TNL GN20-2659
IMMEDIATE

CO~MAIDS

HT
Use the HT command to suppress all terminal output generated by any C~S
command or your program that is currently executing.
In order for the
HT command to be recognized when entered, an Attention interrupt must be
simulated by pressing the Attention key or its equivalent.
Program
execution continues.
With typewriter terminals,
the Attention key
unlocks the keyboard to accept your HT command. with display terminals,
you enter the HT command in the input area and then press the Enter
key.
When the Ready message is displayed, normal terminal output
resumes.
The format of the HT command is:

L-_________________________________

_____________________-J

Bone.

HX
Use the HI command to stop the execution of any CMS command or
your programs under CMS, close any open files or I/O devices, and
to the CMS command environment. In order for the HI command
recognized, it must be issued after you stop program execution
Attention interrupt.
The HI command is executed when the next
I/O interrupt occurs.
All terminal output generated before
executed is displayed before the command is executed. The format
HI command is:

HI
-.I

L-

lone.

238

one of
return
to be
by an
SVC or
HI is
of the

IBM VM/370: Command Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659
IMMEDIATE COMMANDS
HO

Use the HO command, during the execution of a command or one of your
programs, to resume the recording of trace information that was
temporarily suspended by the SO command. In order for the HO command to
be recognized, it must be entered after you stop program execution with
an Attenion interruDt.
Proaram eye~ution ~ontinn~~ to its normal
completion, and all· reco~de~ ~tr~~~-i~i~~maii~~--i~- s~~oled to the
printer. The format of the HO command is:
---,

L-______

None.

HT
Use the HT command to restore terminal displaying from an executing CMS
command or one of your programs that was previously suppressed by the HT
command. In order for the HT command to be recognized when entered, an
Attention interrupt must be simulated by pressing the Attention key or
it equivalent.
Program execution continues, and displaying continues
from the current point of execution in the program. Any console output
that is generated after the HT command is issued and up to the time the
RT command is issued is lost. Execution continues to normal program
completion. The format of the RT command is:
r-

L-

Bone.

section 7: Format and Usage Rules for CMS Commands

239

GC20-1804-3 Page ftodified by TIL GR20-2659
IftftEDIATE COftftAIDS

so
Use the SO co •• and during the execution of a command or one of your
programs to temporarily suspend the recording of trace inforaation.
Tracing resumes if you issue the BO command at a later time. In order
for the SO co •• and to be recognized, it must be entered after you stop
program execution with an Attention interrupt.
Program execution
continues to its nor.al completion and all recorded trace inforaation is
spooled to the printer. The format of the SO command is:

r-------------------------'---------------------------------------------------,
I so

L-________________________

None.

240

IBM VM/370: Command Language Guide for General Users

Section 8: Format and Usage Rules for CP Commands

CP Command 'Privilege Classes

The CP co •• ands are divided into eight privilege classes, each class
representing a different type of user. Each user is assigned, as part
of his entry in the YK/310 directory, one or .ore privilege classes.
Pigure 33 shows the function of each class. The footnotes following the
privilege class indicate where the co ••ands of that particular privilege
class are described.
Pigure 34 shows which co •• ands (and which
operands, if the co •• and varies for different privilege classes) are
associated with each class.
only class G co •• aDds and class Any
co •• ands are included in this publication.

section 8: Por.at and Usage BuIes for CP Co •• ands

241

Class

User and Function
R~i!~~ ~I§!~ 0Eerato~:

The class A user controls the
VM/370 system. Class A is assigned to the user at the VM/370
system console at IPL time. The priaary system operator is
responsible for the availability of the VM/370 system and its
communication lines and resources. In addition, the class 1
user controls system accounting, broadcast messages, virtual
machine perforaance options and other coaaand operands that
affect the overall performance of VM/370.
!~!~: The class 1 system operator who is automatically logged
on during CP initialization is designated as the primary
System Operator.

aI§!~!

Cl,2

~I§!~ Pr~~~~~:

aEQQ!in~ Q~!£!to~:
The class D user controls spool data
files and specific functions of the system's unit record
equipment.

El,2

~~§!§!

Fl,3

a!Dice BeE~!§~~tiy!: The class F user obtains and
examines in detail, certain data about input and output
devices connected to the VM/370 system.

BesQ!!£! 0Ee£!!or: The class B user controls all the
real resources of the VM/370 system, except those controlled
by the primary system operator and spooling operator.

The class C user updates certain
functions of the V8/370 system.

Ana1I§!: The class E user exaaines and saves certain
data in the V8/370 storage area.

General User: The class G user controls functions associated
the-eiecution of his virtual machine.

with

Anyl,4

!~y y§!~:

The class Any user has limited use of VM/370 to
gain initial access to the V8/370 system.

Reserved for IBM use •

lDescribed
2Described
3Described
4Described
Figure 33.

242

in
in
in
in

the !AL~IQ: .QEe~ato.!..!.§ Guid!.
the llL37Q: ayst.!.! Prog!.!.!.!~!§ Gui~!.
the !lIL37Q: .QLTSB,R and jYQ! ~~~!J!.g ID!!g! •
this publication.

CP privilege Class Descriptions

IBM VM/370: Command Language Guide for General Users

I
I
I
I
I

GC20-1804-3 Page Modified by TNL GN20-2659

.,
Class
any

Commands

I Operands

I Class

*tcp
CP
DIAL
DISCONN
LOGOff
LOGON
MESSAGE
SLEEP

Commands

ACNT
DISABLE
ENABLE
fORCE
HALT
LOCK
MESSAGE
MCIHTOR

NETWORK

QUERY

SET

QUERY

ALL
DISPLAY
ENABLE
INTERVAL
START
STOP
DISABLE
DISPLAY
DUMP
ENABLE
HALT
LOAD
POLLDLAY
QUERY
SHUTDOWN
VARY
LOGMSG
NAMES
PRIORITY
SASS 1ST
userid
USERS
FAVORED
PRIORITY
RESERVE
SASSIST

SET

ATTACH
ATTACH
DETACH
DETACH
DISABLE
ENABLE
MESSAGE
NETWORK

LOGMSG

QUERY

LOGMSG
NAMES
userid
USERS

STCP
D

BACKSPAC
CHANGE
DRAIN
fLUSH
fREE
HOLD
LOADBUF
ORDER
PURGE
QUERY

CHANNEL

FILES
HOLD
LOGftSG
NAftES
PRINTER
PUNCH
READER
UR
use rid
USERS

REPEAT
SPACE
START
TRANSFER

CHANNEL
ALL
DISABLE
DISPLAY
DUMP
ENABLE
LOAD
POLLDLAY
QUERY

SHUTDOWN
VARY
ALL
DASD
DUMP
GRAF
LINES
LOGMSG
NAMES
raddr
SPOOL
STORAGE
SYSTEM
TAPES
TDSK
UR
userid
USERS
DUMP

VARY
WARNING

SHUTDOWN
UNLOCK
WARNING
B

Operands

DCP
DftCP
INDICATE

I/O
LOAD
PAGING
QUEUES
USER

Figure 34.

COllllands Accepted from Each User Class (Part 1 of 2)
Section 8: Forllat and Usage Rules for CP Commands

243

GC20-1804-3 Page Modified by TNL GN20-2659

.--

I Class

Commands
LOCATE
MONITOR

QUERY

SAVESYS
NETWORK
QUERY

SET
G

ADSTOP
ATTN
BEGIN
CHANGE
CLOSE
COUPLE
DEFINE
DETACH
DISPLAY
DUMP
ECHO
EXTERNAL
INDICATE
IPL
LINK
LCADVFCB
NOTREADY
ORDER
PURGE
QUERY

Operands

Class

Commands

LINKS
LOGMSG
NAMES
PFnn
PRINTER
PUNCH
READER
SET
TERMINAL
TIME
userid
USERS
VIRTUAL

DISPLAY
ENABLE
INTERVAL
START
STOP
LOGMSG
NAMES
PAGING
PRIORITY
SASS 1ST
userid
USERS
TRACE
LOGMSG
NAMES
userid
USERS
RECORD
MODE

LOAD
USER

Operands

READY
REQUEST
RESET
REWIND
SET

SPOOL
STORE
SYSTEM
TAG

ACNT
ASSIST
ECMODE
EMSG
IMSG
ISAM
LINEDIT
MSG
NOTRANS
PAGE X
PFnn
PFnn COpy
PFnn TAB
RUN
TIMER
WNG

DEV
FILE
QUERY

TERMINAL
TRACE
TRANSFER
CHANNELS
FILES

L--

Figure 34.

244

Commands Accepted from Each User Class (Part 2 of 2)

IBM VM/370: Command Language Guide for General Users

CP Command Summary

This section contains descriptions of the commands acceptable in the
control program environment. Figure 35 presents an alphabetical list of
the commands, the privilege classes which may execute the command, and a
brief statement about the use of each command.

------,

r------I
I Command

*
iCP
ACNT
ADSTOP
ATTACH

IPrivilegel
Usage
I Class I
I
any
IAnnotate the console sheet.
I
any
IExecute a CP command while remaining in the
I virtual machine environment.
I
ICreate accounting records for logged on users
A
I and reset accounting data.
I
IHalt execution at a specific virtual machine
G
I instruction address.
I
Attach a real device to a virtual machine.
B
Attach a DASD device for CP control.
Dedicate all devices on a particular channel
to a virtual machine.

ATTN

Make an attention interrupt pending for the
virtual machine console.

BACKSPAC

Restart or reposition the output of a unit
record spooling device.

BEGIN

Continue or resume execution of the virtual
machine at either a specific storage location
or at the address in the current PSi.

CHANGE

D,G

Alter one or more attributes of a closed spool
file.

Terminate spooling operations on a virtual card
reader, punch, printer, or console.

COUPLE

Connect channel-to-channel adapters.

any

Ignored.

DCP

Display real storage at terminal.

DEFINE

Reconfigure your virtual machine.

DETACH

B
B
B

Disconnect a real device from a virtual machine.
Detach a DASD device from CP.
Detach a channel from a specific user.
Detach a virtual device from a virtual machine.

DIAL

any

DISABLE

A,B

Figure 35.

IConnect a terminal or display device to the
I virtual machine's virtual communication line.
I
IDisable 2701/2702/2703 and 3270 communication
I lines.

CP Command Summary (Part 1 of 4)

section 8: Format and Usage Rules for CP Commands

245

GC20-1804-3 Page Modified by TNL GN20-2659

r-------------------------------------------------------------------------~

Command
DISCONN
DISPLAY

I Privilege I
I
I Class

----1---any
G

Usage

IDisconnect your terminal from your virtual
I machine.

IDisplay virtual storage on your terminal.

DMCP

DRAIN

Halt operations of specified spool devices upon
completion of current operation.

DUMP

Print on virtual printer: virtual PSi, general
registers, floating-point registers, storage
keys, and contents of specified virtual
storage locations.

ECHO

Test terminal hardware by redisplaying data
entered at the terminal.

ENABLE

A,B

EXTERNAL

FLUSH

FORCE

FREE

HALT

HOLD

Defer real spooled output of a particular user.

INDICATE

E,G

Indicate resource utilization and contention.

IPL

Simulate IPL for a virtual machine.

LINK

Provide access to a specific DASD device by a
virtual machine.

LOADBUF

Load real UCS/UCSB or FCB printer buffers.

LOADVFCB

Load virtual forms control buffer for a virtual
3211 printer.

LOCATE

Find CP control blocks.

LOCK

Bring virtual pages into real storage and lock
them; thus excluding them from future paging.

LOGOFF

any

LOGON
MESSAGE
Figure 35.

246

Dump the specified real storage location on your
virtual printer.

IEnable communication lines.
I
ISimulate an external interrupt for a virtual
I machine and return control to that machine.
I
ICancel the current file being printed or punched
I on a specific real unit record device.
I
ICause logoff of a specific user.
I
IRemove spool HOLD status.
I
Terminate the active channel program on
specified real device.

IDisable access to CP.
I
any
IProvide access to CP.
I
1,B,any ITransmit messages to other users.
CP Command Summary (Part 2 of 4)

IBM VM/370: Command Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659

Command

IPrivilegel
I Class I

Usage

MONITOR

A,E

Trace events of the real machine and record
system performance data.

NETWORK

A,B,P

Load, dump, trace and control the operation of
the 3704/3705 control program.

NOTREADY

simulate "not ready" for a device to a virtual
machine:

ORDER

D,G

Rearrange closed spool files in a specific
order.

PURGE

D,G

Remove closed spool file from system.

QUERY

A,B,C,D, Request information about machine configuration
E,F,G
and system status.

READY

Simulate device end interrupt for a virtual
device.

REPEAT

Repeat (a specified number of times) printing or
punching of a specific real spool output file.

REQUEST

Make an attention interrupt pending for the
virtual machine console.

RESET

Clear and reset all pending interrupts for a
specified virtual device and reset all error
conditions.

REWIND

Rewind (to load point) a tape and ready a tape
unit.

SAVESYS

Save virtual machine storage contents,
registers; and PSi:

SET

A,B,F,G

Operator--establish system parameters.
User--control various functions within the
virtual machine.

SHUTDOWN

Terminate all VM/370 functions and checkpoint CP
system for warm start.

SLEEP

any

Place virtual machine in dormant state.

SPACE

Force single spacing on printer.

SPOOL

Alter spooling control options; direct a file to
another virtual machine or to a remote
location via the RSCS virtual machine.

START

Start spooling device after draining or changing
output classes.

STCP

Change the contents of real storage.

STORE

Alter specified virtual storage and registers.

Figure 35.

CP Command Summary (Part 3 of 4)

Section 8: Format and Usage Rules for CP Commands

247

GC20-1804-3 Page Modified by TNL GN20-2659

r----------I
I Command

IPrivilegel
I Class I

Usage

SYSTEM

Simulates RESET, CLEAR STORAGE and RESTART
buttons on a real system console.

TAG

Specify variable information to be associated
with a spool file or output unit record
device.
Interrogate the current TAG text setting of a
given spool file or output unit record device.

TERMINAL

Define or redefine the input and attention
handling characteristics of your virtual
console.

TRACE

Trace specified virtual machine activity at your
terminal, spooled printer, or both.

TRANSFER

D,G

Transfer ihput files to or get input files from
a specified user's virtual card reader.

UNLOCK

Unlock previously locked page frames.

VARY

Mark a device unavailable or available.

WARNING

A,B

Transmit a high priority message to a specified
user or to all users.

L-

Figure 35.

248

CP Command Summary (Part 4 of 4)

IBM VM/370: Command Language Guide for General Users

Use * to annotate the terminal console sheet or terminal display screen
data with a co.ment.
This commentary also appears in the virtual
console spool file (if the console spooling function is invoked for the
virtual machine). The format of the * (coament) r.ommand is:

anycom.ent

lone.

section 8: Format and Usage Rules for CP Commands

249

ICP
#CP

Use the ICP command to execute a CP command while in a virtual console
read environment without first signalling attention to get to the CP
environment. The format of the ICP command is:

•
,I ICP

[comaandlinel [lcom.andline2 I ••• ]]

~!!!!:! :

comaandline

specifies the name, operands, and options for the CP
command or commands you want to issue. You must precede the
first commandline with at least one blank.

The pound sign (I) shown in the format above represents the logical
line end symbol currently in effect for your virtual machine.
If you
have redefined the logical line end symbol, ICP is an invalid command;
you must substitute your line end symbol for the pound sign when using
this command.
Usage:
Por the command to operate, the following conditions must be met:
I.

The virtual machine must be running with SET LIIEDIT OR (a default).

I.
I
I

The first three characters of the edited line must be ICP (upper or
lowercase) with the "I" representing the logical line end character
currently defined.

I •
I
I

At least one blank must separate the ICP from any com. and line. Do
not use attention interruption in any part of the line or to enter
the line.

You can enter multiple command lines as operands of the ICP command,
but you must separate each command line by the logical line end (I)
character. If you enter only ICP with no operands, the virtual machine
enters the CP environment.
CP cancels the virtual machine's console
READ by returning a unit exception status for the virtual console. The
virtual operating system then reissues the console READ to allow you to
key in the appropriate response to a previous aessage fro. that
machine's operating system.

250

IB! V!/370: Command Language Guide for General Users

ICP

The following examples show several ways to use ICP:

Command

system Action

ICP

Your virtual machine enters
CP environment.

tcp query files

QUERY command executed.

ICP query fileslquery users

Two separate QUERY co.mands
executed.

data entered¢ICP msg op is tape
available

"Data entered" is ignored. You
send a message to the
operator.

ICP data entered

You enter CP environment and
cp'interprets "data entered"
as an invalid operand.
"Data entered" is ignored. You
enter CP environment.

ICP query files¢data entered

QUERY command is not executed;
console input (data entered)
passes to the virtual machine.

If you enter ICP without a com.andline, you receive this message:
CP
If ion enter
ICP with cOaaandlines, lUU
receive
appropriate to the individual com.ands you entered.

the

responses

section 8: Pormat and Usage Rules for CP Commands

251

InSTOP
ADSTOP

Use the InSTOP co •• and to halt execution at a virtual instruction
address. Execution halts when the instruction at the specified address
is the next instruction to be executed.
When execution halts, the CP co •• and .ode is entered and a .essage is
displayed. It this point, you aay invoke other CP debugging co •• ands.
To resu.e operation of the virtual .achine, issue the BEGIN co •• and.
Once an InSTOP +ocation is set, it .ay be reaoved by one of the
following:

•
•
•
•

Beaching the virtual storage location specified in the InSTOP co.mand
Performing a virtual IPL or SYSTEft BESET
Issuing the InSTOP OPP co •• and
Specifying a different location with a new InSTOP hexloc com.and

The for.at of the IDS TOP co.mand is:

InSTOP

hexloc }
{ OPP

hexl'oc

is the hexadecimal representation of the virtual instruction
address where execution is to be halted.
The specified
address cannot be in a storage segaent shared with other
users, since the IDSTOP function aodifies storage.

OPP

cancels any previous IDSTOP setting.

Since the ADSTOP function .odifies storage (by placing a CP SVC
I'B3' at the specified location) your prograa should not exaaine
the two bytes at the instruction address. CP does not verify that
the location specified contains a valid CPU instruction.

Address stops may not be set in an OS/VS or DOS/VS virtual
aachine's virtual storage; address stops may only be set in the
virtual equals real partitions or
regions of those virtual
aachines.

252

IBft Vft/370: Co •• and Language Guide for General Users

ADSTOP
3.

If the SfC handling portion of the virtual .achine assist feature
is enabled on your virtual machine, CP turns it off when an address
stop is set. After the address stop is removed, CP returns the
assist feature SfC handling to its previous status.

ADSTOP AT xxxxxx
The instruction whose address is xxxxxx is the next instruction
scheduled for execution.
The virtual machine is in a stopped
state. Any CP co •• and (including an lDSTOP co •• and to set the next
address stop) can be issued. Bnter the CP co •• and BBGI. to resu.e
execution at the instruction location XXIIIX, or at any other
location desired.

Section 8: Por.at and Usage Rules for CP Co ••ands

253

ATTN
AITN

Use the ATTN command to make an "attention" interrupt pending
virtual console. The format of the ATTN command is:

at your

ATTN

The REQUEST command performs the same function
commands can be used interchangeably.

as ATTN

The BEGIN command is not required after you issue ATTN.

Bone.

254

IBft Vft/370: Co •• and Language Guide for General Users

and the

tvo

BEGIN

Use the BEGIN co.mand to continue or resume execution in the virtual
machine at either a specified storage location or the location pointed
to be the virtual machine's current PSW. The format of the BEGIN
co.mand is:

Begin

[hexloc]

L ______- - - -________________________________________________________________~

hexloc

is the hexadecimal storage location where execution is to
begin. When BEGIN is issued without hexloc, execution begins
at the storage address pointed to by the current virtual
machine PSW.
Unless the PSW has been altered since the CP
command mode was given control, the location stored in the PSW
is the location where the virtual machine stopped.
When BEGI) is issued with a storage location specified,
execution begins at the specified storage location.
The
specified address replaces the instruction address in the PSW,
then the PSW is loaded.

Bone.

The virtual machine begins execution.

section 8: Pormat and Usage Rules for CP Commands

255

CHARGE
CHANGE

Use the CHARGE command to alter one or aore of the eIternal attributes
of a closed spool file or files. Issue the QUERY coamand to deteraine
the current attributes of the file.
In order to change an output file,
the file aust have been closed but not yet selected for printing or
punching. An input (READER) file can be changed at any tiae before it
is opened, that is, before the first read is issued for the file. The
format of the CHARGE coamand is:

I
CHange I
I
I
I
I
I
I
I
I

Reader {CLaSS c11
Printer spoolid
PUnch
ALL

CLass c2
COpy nn
r
,
I HOld I
INOHold I
L

INAme {fn [ft]}1
I
dsname I
L

Dlst distcode

lOne of these options ~y~~ be chosen; however, aore than one may be
specified and they may be combined in any order. This is contrary to
the notation normally used in this publication.

READER
RDR

changes the reader spool file.

PRIRTER
PRT

changes the printer spool file.

PUNCH
PCH

changes the punch spool file.

CLASS cl

designates an
eIisting class.
The class,
cl, is
a
one-character alphameric field froa A to z or from 0-9. Refer
to the 'ftLl70: QE~ratg!~~ ~ui~~ for a detailed description of
spool classes.

spoolid

is the spoolid number of the file that is to be changed.
spool file has a unique spoolid.

ALL

changes all your spool files.

CLASS c2

changes the spool class of the file to c2.

COpy nn

specifies the nuaber of copies of the file to be spooled to
the virtual output device. This option is valid for printer
and punch files only. The value of nn (nuaber of copies) must
be a number from 1 through 99. lor nn less than 10, the
leading zero is optional.

HOLD

prevents the file froa be~ng printed, punched, or read until
it is released. The file 1S released when the CHANGE coaaand
is issued with the NOHOLD operand specified.

256

IB" '"/370: Comaand Language Guide for General Users

Each

CHANGE
NOHOLD

releases the specified file from user HOLD status.

DIST distcode
changes the
distribution code specified in
the Vft/370
directory to the distcode specified on the com.and line, for
the spe~ified file only. The distribution code appears on the
output separators of the printer and punch output; it has no
effect on reader files.
NAftE fn [ft]
assigns identification to the spool file in the CftS for.at
filena.e and filetype.
~u~
field, ~U, ~~
a one- to
eight-character alphameric filename assigned to the file for
identification. The field, ft, is a one- to eight-character
alphameric filetype assigned to the file for identification.
If ft is not specified, the filetype is set to blanks.
NAftE dsnalle
assigns identification to the spool file in a non-CftS for.at.
The field, dsnalle, is a 1- to 24-character field suitable for
specifying OS or DOS files [for exa.ple, SYS1.SYSLIB.ftYftAC).

{n:~n } FILES CHANGED

This is the response when you
indication of the nUllber of
individual alterations to a
appear if you have issued the

issue the CHANGE co.mand. This is an
files changed.
It does not reflect
given file. This .essage does not
CP SET IftSG Oll co •• and line.

section 8: For.at and Usage BuIes for CP COllllands

257

CLOSE
CLOSE

Use the CLOSE co.mand to terminate the spooling activity on any virtual
spooled record or console device.
If the file is an input reader file,
the file being processed is purged unless SPOOL READER BOLD was
previously specified
(see the SPOOL command). The effect of BOLD or
NOBOLD for a particular file established by the SPOOL command can be
overridden by specifying NOBOLD or BOLD, respectively, in the CLOSE
command.
If the file is an output file on a printer, punch, or console,
the file is either queued for output on a real unit record device, or,
if the virtual output device is transferred
(by use of the "SPOOL vaddr
TO userid" command), the file is queued for input to the receiving user.
you can specify a filename and filetype and an optional distribution
code to aid in later identification of the file and its contents. The
format of the CLOSE command is:

IReader r
Ivaddr IBOld
I
INOBoldl
I
L

ICONsole
IPrinter
I PUnch
Ivaddr

I
I
I

...

I PUrge
I
I r
r
I IBOld I [DIst distcode] INAme {fn [ft]}'
,dsname , I
I I BOBoldl
I

...

I
I
I
I

I
I
I

I I

... ... ...

READER
RDR

closes all reader spool files.

CONSOLE

closes your virtual machine's console spool file. Once a
virtual console spool file is closed, it becomes a printer
spool file and can be manipulated in the same way as any
printer spool file
(for example,
it can be purged or
changed).

PRINTER
PRT

closes all printer spool files.

PUNCH
PCB

closes all punch spool files.

vaddr

is the virtual address (cuu) of the device to be closed. The
address may represent a reader, console, printer, or punch.

BOLD

makes the spool file being closed unavailable for further
processing, until it is specifically requested or changed.
This option, specified in the CLOSE command, overrides any
previously specified BOLD or NOBOLD option for the files being
closed.

NOB OLD

makes the spool file being closed available for further
processing. Specify NOBOLD if a BOLD established by the SPOOL

258

IBft Vft/370: Com.and Language Guide for General Users

CLOSE
command is still in effect and
to be held.

the current active file is not

You can release one of your own output files in HOLD status by
using the CBAIG! command. If an output file is spooled for
another user (SPOOL FOR userid), only the receiving virtual
machine user can change the file status. The originator of
the file .ay reclaim the file by using the TRANSFBR co •• and
with the FROft option. If an output file is spooled to a user
as an input file (SPOOL TO userid), the HOLD option places the
input file in BOLD status. The file then cannot be read by
the virtual machine until it is changed to NOBOLD by the
receiving virtual machine user.
If an input file is closed with the BOLD option, the file is
saved and not purged trom the system. The saved file is
available for virtual machine and user processing and is not
placed in a user hold status.
Input spool files that are
closed are nor.ally purged from the virtual machine.
PURGB

closes and i •• ediately purges from the virtual machine
output spool files. No output file is produced.

the

DIST distcode
uses the one- to eight-character alphameric identification
(distcode) on the output separators of printer and punch
instead of
the identification specified in
the Vft/370
directory. The distribution code is changed for this file
only and does not affect other files or change the Vft/370
directory. If the file is transferred to another user, this
option has no effect.
BAftB fn [ft]
assigns identification to the spool file in the CftS for.at
filename and filetype.
The field, fn, is
a one- to
eight-character alphameric filename assigned to the file for
identification. The field, ft, is a one- to eight-character
alpha.eric filetype assigned to the file for identification.
If ft is not specified, the filetype is set to blanks.
11!E dsnaae
assigns identification to the spool file in a non-CftS format.
The dsna.e field is a 1- to 24-charact~r field suitable for
specifying OS or DOS files (for exa.ple, SYS1.SYSLIB.ftYftAC).
Only 20 characters of the 24-character dsname are displayed by
QUBRY, even though a name of up to 24 characters is valid.
The table that follows shows the result of the CLOSE co •• and, depending
on how you had previously specified the SPOOL co •• and options BOLD,
IOBOLD, COlT, and IOCOIT. The CLOSE com.and can result in a file being
held, saved, or purged.

section 8: Pormat and Usage BuIes for CP Co ••ands

259

virtual
Device
Sta tus
(CLOSE
Co •• and
Setting)

SPOOL Co •• and options Set for a Virtual Device
HOLD
ROCOBT

ROHOLD
ROCORT

ROHOLD
COBT

HOLD
COBT

Ror.al EOP
(default
CLOSE)

IPile releasedlPile saved
I for proces- I
I
I sing

IPile releasedlPile held
Ifor proces- I
Ising
I

IPile releasedlPile saved
Ifor proces- I
Ising
I

IPile releasedlPile held
Ifor proces- I
Ising
I

CLOSE HOLD

IPile saved

IPile held

CLOSE BOHOLD IPile releasedlPile releasedlPile releasedlPile released I
Ifor proces- Ifor proces- Ifor proces- Ifor proces- I
Ising
Ising
Ising
Ising
I

-------------------------------------------------------------------1
Bote, "saved" .eans that the file is not purged and does not have
I
HOLD. status.

A subsequent READ could read this file.

t PILE spoolid {~gR} userid
{:gi
COR}

COpy nn

•

{BO:~~~}

This response is received if aultiple copies of the file are being
processed, if the file is being transferred to another user, or if
the file is placed in a USER HOLD status.

260

IB8 V8/370: Co •• and Language Guide for General Users

COUPLE
COUPLE

Use the COUPLE
command to connect your
virtual (non-dedicated)
channel-to-channel adapter to another user's virtual channel-to-channel
adapter (or to another one of your own virtual channel-to-channel
adapters). The format of the COUPLE command is:

COUPLE

vaddr1

[To]

is the virtual
adapter.

userid

address

vaddr2

(cuu)

your

channel-to-channel

[TO] userid
is the user identification of the virtual machine to which
vaddr1 is to be connected. If vaddr1 is to be connected to
your own virtual machine, userid may be specified as an
asterisk (*). The user must be logged on and have a virtual
channel-to-channel adapter defined.
If the keyword TO is
omitted, the userid cannot be "T" or "TO".
vaddr2

is the virtual address (cuu) of the channel-to-channel adapter
to be connected to vaddr1.

CTCA vaddr1 COUPLE TO userid vaddr2
This is the response when you issue the COUPLE co •• and.
vaddr1

is the address of your channel-to-channel adapter.

userid

is the identification of the receiving virtual machine.

vaddr2

is the address of the channel-to-channel adapter of tb~
rece1v1ng user (or a different channel-to-channel adapter
in your own virtual machine).

CTCA vaddr2 COUPLE BY userid vaddr1
This is the response sent to the
COUPLE co.mand.

user specified by userid

vaddr1

is the address of the issuing
adapter.

userid

is the identification
co •• and.

vaddr2

is the address of the channel-to-channel adapter
receiving user.

in the

user's channel-to-channel

of the user who

issued the COUPLE
of the

section 8: Pormat and Usage Rules for CP Co ••ands

261

COUPLE
CTC! vaddrl DROP PROft userid vaddr
This response to the issuing user indicates that the virtual CTC!
vaddrl was already coupled when the COUPLE co •• and was issued. The
previous connection is co.pleted. This response is always followed
by the response:
CTC! vaddrl COUPLE TO userid vaddr2

262

IBft V8/370: Co •• and Language Guide for General Users

Use the CP command if you are a CftS user and do not
of which co.mand environment you are in.

want to keep aware

The CP command is treated as a "null" by the control program and
therefore can precede any other command if one or more blanks separate
CP from the other command. The CP command is useful because it lets the
CftS user enter commands without knowing which environment (CP or virtual
machine) he is in. The format of the CP command is:

,
I [command]
L
I ______
CP - - - -______________________________________________________________

command

is any CP command or string of CP commands that are separated
by the logical line end symbol (I) and are valid for your
privilege class.

CP QUERY FILES
or
QUERY FILES
can be entered from the CP or CftS command environment.

lone

Section 8: For.at and Usage Rules for CP Com.ands

263

DEFINE

Use the DEFINE co •• and to alter your virtual aachine configuration or
channel operating mode.
You can expand your configuration without
aaking permanent changes, because the definitions are in effect for the
current terminal session only.
If you redefine storage or define the
channel operating aode, the virtual machine is reset and IPL aust be
perfor.ed again. The format of the DEFIlE coaaand is:

DEFine

Reader
Printer
PUnch
[1s] vaddr
COlsole
CTCa
TIfter
1403
3211
CBAlnels [AS] { SEL }
Bft!
LIne

[As] vaddr 11Bft[!J 1
ITELE[ 2] 1
cuu

GRAF

[3270 ]
3158

vaddr1

[AS)

vaddr2

T2314
T2319
T3330
T3340
T2305

[AS 1 vaddr [CIL] nnn

I
I

STORage [As]

{nnnnnK}
nnft

READER [AS] vaddr
RDR

adds a spooling card reader with the
specified by vaddr to the virtual
configuration.

address
machine

PRINTER [AS] vaddr
PRT

adds a spooling
printer with
the
specified by vaddr to the virtual
configuration.

address
aachine

PUICB [AS] vaddr
PCB

adds a spooling card punch with the
specified by vaddr to the virtual
configuration.

address
aachine

CONSOLE [AS] vaddr

adds a virtual system console to the virtual
machine at the address specified by vaddr.

264

IBft VK/370: Coamand Language Guide for General Users

DEFINE
CTCA [AS] vaddr

adds a virtual channel-to-channel adapter with
the address specified by vaddr to the virtual
aachine
configuration.
The
control
unit
address must end in zero, and must not already
be in use.
Once the control unit is defined,
other virtual devices may not be defined for
the same CTCA.

TlftER [AS] vaddr

adds a pseudo timing device with the address
specified by vaddr to the virtual machine
configuration.

1403 [AS] vaddr

adds a spooling 1403 printer with the address
specified by vaddr to the virtual machine
configuration.

3211 [AS] vaddr

adds a spooling 3211 printer with the address
specified by vaddr to the virtual machine
configuration.
The virtual
3211
printer
supports LOADYFCB and the Index feature.

CBAIIELS [AS] {SEL}
BftX

redefines the
channel
mode
of
operation
for the virtual machine to either selector or
block multiplexer.
Use of the SEL (selector
channel) or BftX (block multiplexer channel)
operand sets the mode of operation for pll
channels except virtual channel O.
Channel 0
always operates in byte-multiplexer mode. The
real or virtual
channel-to-channel adapter
always operates in selector mode.
Block multiplexer mode may enhance the virtual
aachine's operating system by allowing the
overlap of 510 operations. This is done by
reflecting a channel condition code of 0 back
to the virtual machine rather than a channel
busy signal.
Note: The virtual machine is immediately reset
when this set of operands is executed.

LIBE [AS] vaddr IIBftl I
ITBLB21
L

adds a virtual 2701/2702/2703 communication
line with the address specified by vaddr to th~
virtual aachine configuration.
IBBl indicates that an IBB-type terminal (2741,
1050, or equivalent) is on the 2701/2702/2703
line. TELE2 indicates that a teletypewriter is
on the 2701/2702/2703' line.
GRAP cuu [3270
3158

vaddrl [AS] vaddr2

defines a temporary virtual 3270 or 3158 (the
systea console used on the system/370 Bodel
158) for the virtual machine. The cuu is the
hexadecimal address for the device.
redefines the device represented by vaddr1 as
vaddr2.
The virtual address, vaddr1, must
represent a defined device in the virtual
machine configuration.

Section 8: Pormat and Usage Rules for CP Com.ands

265

DBlIIB
T231" [lS] vaddr [CIL] nnn
adds a temporary virtual disk of the specified
T2319
type to the virtual
machine configuration.
T3330
The vaddr specifies the address of the disk,
T33"0
and must not be on a virtual control unit
T2305
already defined as a CTC1. CIL nn specifies
the
number of
cylinders
that the
disk
contains.
STOR1GE [lS] { nnnnnK }
nn8

redefines the size of the virtual storage for
the virtual
machine as
nnnnnK (where
K
represents 102"
bytes) or
nn8 (where
8
represents
1,0"8,576
bytes).
The
value
specified becomes the new virtual storage size.
Sizes aust be in "K increments and are limited
by the maximum value in the V8/310 directory
entry. The minimum size you can specify is 8K.
111 entries not specified in a "K increaent are
rounded up to the next "K boundary. Changing
the
virtual storage
size (increasing
or
decreasing) causes a virtual system reset and
clears all virtual storage to binary zeros.

Responses are generated to confirm that the desired configuration change
has taken place. These responses do not appear on your terminal if you
have issued the CP SET 18SG OPP coamand line.
type vaddr DElIIED
where the possible values for type have the following meanings:
IY~~

D1SD
T1PB
LIBE
RDR
PRT
PUB
GRll
COBS
CTCl

J1~~1!!1!g

Direct access storage device
8agnetic tape
Communication line
Card reader
Line printer
Card punch
Graphics device
Console
Channel-to-channel adapter

CH1IIELS = {SEL}
B81
is the channel aode of operation for the virtual machine. This
response applies to all channels except channel 0 (always a
byte-multiplexer channel) and any channel that has a virtual or
real channel-to-channel adapter (always a selector channel).
STOR1GB = nnnnnK
The minimum storage you may specify is 8K.

266

IB8 V8/370: Command Language Guide for General Users

DETACH

Use the DETACH co •• and to remove a virtual device from the virtual
machine. You can detach a previously attached device even if the device
is currently in use. You can also detach devices that were attached
because of V8/370 directory entries or during CP system initialization.
You cannot detach volu.es in the syste. SYSaWB list or devices
containing minidisks that are in use. ihen you detach a virtuai device,
it becomes inaccessible to your virtual .achine. If the device was
previously attached to your virtual machine by an ATTACH command, it is
released and beco.es available for attachment to your virtual machine,
another user, or the CP system.
Tape devices are automatically rewound
and unloaded when detached. If you detach a device that was previously
attached to your virtual machine by the operator, a message is sent to
the operator infor.ing him that the device is free. The format of the
DETACH command is:

DETach

I vaddr

is the virtual address (cuu) of the device to be detached fro.
your virtual .achine.

vaddr

~!sponses

8essages are sent to the user, the operator who issued the com.and, and
the primary system operator (if different from the operator who issued
the com.and), notifying them that the DETACH was successful.
type vaddr DETACHED
This is the response you receive the. you detach one of your own
devices. You do not receive this response if you have issued the
CP SET I8SG OFF co •• and.
type vaddr DETACHED BY operator
This is the response you
your devices.
r

typeraddr DETACHED

receive if

an operator detaches

one of

luseridl
ISYSTEftl
L

This is the response sent to the
previously attached device or if the
user or the syste ••

operator if you detach a
operator detaches it fro. a

section 8: Format and Usage Rules for CP Commands

267

DETACH
r

type raddr DETACHED

luseridl BY operator
ISISTEftl
L

This is the response sent to the primary syste. operator if he did
not issue the DETACH com. and and the device had been previously
attached.
In the above responses, type is one of the following:
lll!!

DASD
TAPE
LINE
RDR
PRT
PUN
GRIP
CONS
CTCI
D.r:V

fteaning
Direct access storage device
ftagnetic tape
co.munication line
Card reader
Line printer
Card punch
Graphics device
Console
Channel-to-channel adapter
Any other device

CTCA vaddr DROP PROft userid vaddr
This is the response if the device detached was a virtual CTCI
connected (via the COUPLE command) to another CTCI on the virtual
machine specified by the userid.
This response is always followed
by the response:
CTCA vaddr DETACHED
unless the SET IftSG OPP com.and was issued.

268

IB! Vft/310: Command Language Guide for General Users

DIAL
DIAL

Privilege

CI~22:

Any

Use the DIlL command to logically connect a switched line, leased line,
or locally attached terminal to a previously logged on multiple-access
virtual machine.
Once the connection is made, your terminal operates
entirely under the control of that virtual machine. The DIlL command
matches your
terminal to
the equivalent
type defined
in the
multiple-access virtual machine.
If no _atching terminal type exists,
the connection cannot be made and an error message is issued.
The
format of the DIlL command is:
DIlL

userid

[vaddr]

userid

is the identification
currently logged on.

vaddr

is the address of the virtual communication line to which
the connection is made.

of a

virtual

machine

that

lotes:
-':--1 DIlL command is accepted only at logon time, and only as a
substitute for a LOGOI command. The type of terminal used must be
supported by both Yft/370 and the multiple-access virtual machine.
The only
exception is
the 3277
Display Staticn
ftodel 1
(480-character screen).
This display terminal, if used, must ~e
supported by the multiple-access virtual machine.
Yft/370 support
of this model is limited to the DIlL facility only. See the
Yft/370: l~inal y§!!~§ Guid~ for details on running and gaining
access to multiple-access machines.
2.

If the DIlL co.mand is issued from a real 3277 terminal, the
virtual system must use the CP command BESET to drop the dialed
connection. DIlL is not supported for the 3066 system console.

The CP DIlL command is not supported for ter.inals
ICP lines in a 3704/3705 control unit.

that are using

DIILID TO userid vaddr
is the message sent to the
connection has been made.
GRIP raddr }
raddr DI1LID TO userid DIlLED
{ LIIE
DEY rid

user

indicating

that a

logical

= nnn

is the response to the primary system operator. It indicates a
successful connection to the virtual machine (userid) and the
total number of Yft/370 lines (nnn) currently connected to other
virtual machines. DEY rid indicates the resource identification
of a 3704/3705 line.
lote: The terminal remains connected to and under the control of
the-virtual machine until that virtual machine terminates the
section 8: Pormat and Usage Rules for CP Commands

269

DIAL
co.munication.
aessage:

At that

tiae the

user

receives the

following

DROP FRO! userid vaddr
this message is sent to the user when the line is disabled.
GRAF raddr }
LIIE raddr DROP FBO! userid DIALED = nnn
{ DEY rid
is the aessage sent to the primary system operator.

270

IB! Y!/370: Co•• and Language Guide for General Users

DISCOII
DISCONN

Use the DISCOII com. and to disconnect the terminal fro. the Vft/370
system: the virtual machine continues operation. When DISCOII is issued
from the virtual machine, a disconnect-time message is printed at the
virtual machine's terminal and at the priaary syste. operator's console.
The terminal remains disconnected until it is reconnected via a LOGOI
com.and. The virtual aachine is logged o~~ is minutes after an attempt
is made to read froa the terminal or if the virtual .achine goes into a
disabled WIlT state.
If your ter.inal connection is broken because of terainal, line, or
TP control unit errors, CP places the virtual machine in disconnect aode
for up to 15 ainutes and your virtual machine does not continue to run.
If you log on within 15 minutes, your virtual machine can continue
operating. If you do not log on within the 15-minute interval, the
virtual machine is logged off.
Unless the CP command, SPOOL CORSOLE STIRT, is issued to spool the
virtual console output, all ·writes" or output messages to the virtual
console are ignored. When the terminal is reconnected via the normal
LOGOI procedure, the terminal is placed in CP console function mode. To
resume execution of the virtual machine, enter the BEGIR cosmand. The
format of the DISCOII command is:

DISConn

BOLD

[BOld]

specifies that the communication line is not to be disabled.
This option allows you to disconnect your terminal, and, at
the same time, to avoid the process of telephone dialing into
the systea to access your virtual .achine again. If specified,
control returns to CP and the "V8/370 online" =essage, is
displayed.

When the DISCOII
issued.

command is

issued,

the disconnect

time message

DISCOIIBCT IT hh:mm:ss zone weekday mm/dd/yy
is the response to the user who issued the co.mand.
GRIP raddr}
raddr DISCOHBECT userid USERS = nnn
{ LIII
DBV rid
is the response to the primary system operator informing him
that the user represented by "userid" has been disconnected from
the Vft/370 system.
The "nnn" is the total number of users
reaaining in the system.
The response "rid" indicates the
resource identification.

Section 8: Por.at and Usage Rules for CP Commands

271

DISPLAY
DISPLAY

Use the DISPLAY
components:
•
•
•
•
•
•
•

com.and

to examine

the

following

virtual

machine

Virtual storage locations
General registers
Floating-point registers
Control registers
Program status word (PSW)
Channel addres~ word (CAW)
Channel status word (CSW)

If a command line with an invalid operand is entered, the DISPLAY
command terminates when it encounters the invalid operand; however, any
previous valid operands are
processed before termination occurs.
Storage locations, registers, and control words can be displayed using a
single command line. The format of the DISPLAY com.and is:

Display

1
D

1 hexloc 11
IKhexloc11
1Lhexloc11
IThexloc11
I
.2
I
L

I
I
I
L
J
I
I
r
, 1
I{. ]I bytecoun t I I
I
Ij!!~
I I
J

Greg1 I {- }lre g 2 1
Yreg1 I
: lIND I
L
J
Ireg1 I
1
r
I { • ]I regcount I
I EID
I
I
L

Ij!!~

l{-}l hexloc2 II
I :

I
I
I
I
I
I
J

Psw
CAW
CSW

hexloc1
Lhexloc1
Thexloc1
Khexloc1
.Q

is the first, or only, hexadecimal storage location
whose contents are to be displayed at the terminal. If
L is specified, the storage contents are displayed in
hexadecimal. If T is specified, the storage contents
are displayed in hexadecimal, with EBCDIC translation •
If K is specified, the storage keys are displayed in
hexadecimal.
If hexloc1 is followed by a period and is not
fullword boundary, it is rounded down to the
lowest fullword.

on a
next

If hexloc1 is not specified, the display begins at
storage location O.
If L, T, or K are entered either
272

IB" V"1370: Command Language Guide for General Users

DISPLAI
without any operands, or followed immediately by a
blank, the contents of all storage locations are
displayed. If L, T, or K are not specified and this is
the first operand, then the default value of zero is
assumed.
The address, hexlocl, may be one to six
hexadecimal digits, leading zeros are optional.
-}heXIOC2
{ : !1Q

is the last of the
range of hexadecimal storage
locations whose contents are to be displayed at the
terminal. Either - or: must be specified to display
the contents of more than one location by storage
address~
If hexloc2 is not specified. the contents of
all storage locations from hexlocl to the end of
virtual storage are displayed. If specified, hexloc2
must be equal to or greater than hexloc1 and within the
virtual storage size.
The address, hexloc2, may be
from one to six hexadecimal digits; leading zeros are
optional.

{ • }bytecount

is a hexadecimal integer designating the number of
bytes of storage (starting with the byte at hexloc1) to
be displayed at the terminal. The period, ., must be
specified to display the contents of more than one
storage location by byte count. The sum of hexloc1 and
bytecount must be an address that does not exceed the
virtual machine size.
If this address is not on a
fullword boundary, it is rounded up to the next highest
fullword. The value, bytecount, must have a value of
at least one and may be from one to six hexadecimal
digits; leading zeros are optional.

!!!!

Gregl

is a decimal number from 0-15 or a hexadecimal integer
from O-F representing the first, or only, general
register whose contents are to be displayed at the
terminal. If G is specified without a register number,
the contents of all the general registers are displayed
at the terminal.

Iregl

is an integer (0, 2, 4, or 6) representing the first,
or only, floating-point register whose contents are to
be displayed at the terminal.
If I is specified
without a register number, the contents of all of the
floating-point
registers
are
displayed
at
the
terminal.

Iregl

is a decimal number from 0-15 or a hexadecimal number
from O-F representing the first, or only, control
register whose contents are to be displayed at the
terminal. If I is specified without a register number,
the contents of all of the control registers are
displayed at the terminal. If Iregl is specified for a
virtual machine
without extended
mode operations
available, only control register 0 is displayed.

g2
{ -}re
: !BD

is a number representing the
last register whose
contents are to be displayed at the terminal. Either or : must be specified to display the contents of more
than one register by register number. If reg2 is not
specified, the contents of all registers from regl
through the last register of this type are displayed.
section 8: Format and Usage Rules for CP Commands

273

DISPLAY
The operand, reg2, must be equal to or greater than
reg1. If Gregl or Xreg1 are specified, reg2 may be a
decimal number from 0-15 or a hexadecimal number from
O-F. If Yreg1 is specified, reg2 may be 0, 2, 4, or
6. The contents of registers regl through reg2 are
displayed at the terminal.
{ • }regcount
EBD

is a decimal number from 1 to 16 or a hexadecimal
number from 1 to F specifying the number of registers
(starting with regl) whose contents are to be displayed
at the terminal. If the display type G or I
is
specified, regcount can be a decimal number from 1 to
16 or a hexadecimal number from 1 to F. If display type
Y is specified, regcount must be 1, 2, 3, or 4. The
sum of regl and regcount must be a number that does not
exceed the maximum register number for the type of
registers being displayed.

PSW

displays the current virtual machine
status word) as two hexadecimal words.

CAW

displays as one hexadecimal word the contents
hexadecimal location 48 (channel address word).

CSW

displays as two hexadecimal words the contents of the
channel status word (doub1eword at hexadecimal location
40).

PSW

(program

When multiple operands are entered on a line for location or register
displays, the default display type is the same as the previous explicit
display type. The explicit specification of a display type defines the
default for subsequent operands for the current display function.
Blanks are used to separate operands or sets of operands if more than
one operand is entered on the same command line. Blanks must not be
used to the right or left of range or length delimiters (:
.),
unless it is intended to take the default value of the missing operand
defined by the blank. For example:
display 10 20 T40 80 G12 5 L60-100
displays the following:
hexadecimal location 10
hexadecimal location 20
hexadecimal location 40 with EBCDIC translation
hexadecimal location 80 with EBCDIC translation
general register 12
general register 5
hexadecimal locations 60 through 100

One or more of the following
operands specified.

274

responses is displayed, depending upon the

IB" '"/370: Com.and Language Guide for General Users

DISPLAY

XXXIXX wordl word2 word3 word4 [key] *EBCDIC TRANSLATION*
Tn~s
is the response you
receive when you display storage
locations; xxxxxx is the hexadecimal storage location of wordl.
Wordl
is displayed
(word-aligned)
for
a single
location
specification. Up to four words are displayed on a line, followed,
optionally, by an EBCDIC translation of those four words.
Periods
are printed for unprintable characters. Multiple line are used (if
required) for a range of locations.
If translation to EBCDIC is
requested (Thexloc), alignment is made to the next lower 16-byte
boundary; otherwise, alignment is made to the next lower fullword
boundary. If the location is at a 2K page boundary, the key for
that page is also displayed.

XXXXXX TO xxxxxx

This is

KEY = kk

the response

you receive when

you display

storage keys;

XXXXXX is a storage location and kk is the associated storage key.

GPR n = genregl genreg2 genreg3 genreg4
This is the response you
receive when you display general
registers; n is the register whose contents are genregl.
The
contents of the following consecutive registers are genreg2 and so
on. The contents of the registers are displayed in hecadecimal.
Up to four registers per line are displayed for a range of
registers.
Multiple lines are displayed if required, with a
maximum of four lines needed to display all 16 general registers.

FPR n = xxxxxxxxxxxxxxxx

.xxxxxxxxxxxxxxxxx

E xx

This is the response you receive when you display floating-point
registers; n ~s the even-number floating-point register whose
contents are displayed on this line. The contents of the requested
floating-point registers are displayed
in both the internal
hexadecimal format and the E format. One register is displayed per
line.
eultiple lines are displayed for a range of registers.

Section 8: Format and Usage Rules for CP Commands

275

DISPLIY

HCR n = ctlreg1 ctlreg2 ctlreg3 ctlreg4
This is the response you
receive when you display control
registers; n is the register whose contents are ctlreg1.
The
contents of the following consecutive registers are ctlreg2 and so
on. The contents of the requested control registers are displayed
in hexadeci.al. Up to four registers per line are displayed.
!ultiple lines are displayed if required.

PSW = XXXXXXXI

XXXXXXXX

The contents of the PSW are displayed in hexadecimal.

Cl!

CIW = XXXXXXXX
The contents of the CIW (hexadecimal
hexadeci.al.

CSW = xxxxxxxx

location 48) are displayed in

xxxxxxxx

The contents of the CSW (hexadeci.al
hexadecimal.

location 40) are displayed in

Press the Attention key (or its equivalent) to ter.inate this
function while data is being displayed at the ter.inal. When the
display ter.inates, another co •• and may be entered.

276

IB! V!/370: Com.and Language Guide for General Users

DUMP
DUMP

Use the DUMP command to print the contents of various components of the
virtual machine on the virtual spooled printer. The following items are
printed:
•

virtual progra. status word (PSi)

•

General registers

•

Floating-point registers

•

control registers (if you have the
V"/370 directory entry)

•

Storage keys

•

virtual storage locations

ECMODE option specified

in your

The DUMP command prints the virtual PSi and the virtual registers
(general, floating-point, and control).
If only this information is
desired, at least one virtual address must be specified, such as:
DUMP 0
The output format for the virtual storage locations is eight words
per line with EBCDIC translation on the right.
Bach fullword consists
of eight hexadecimal characters. All the rest of the information (PSi,
general floating-point and storage keys) is printed in hexadecimal. If
you have the BCMOD! option in your VM/370 directory entry, the control
registers are also printed. To print the dump on the real printer, a
CLOSE command must be issued for the spooled virtual printer.
The
format of the DUMP com.and is:

DUMP

, r

, , \

I Lhexloc 11 I{ - }I hexloc2 I
IThexloc111 : II!~
I
L
~
I hexloc111
I
Q
II
r
L
~ I{ .} I bytecount I
liND
I
I

Lhexloc1
Thexloc1
hexloc1
.Q

I
I
I
I
I
I

[*d umpid]

is the first or only hexadecimal storage location to
be dumped. If you enter L or T without operands, the
contents of all virtual storage locations are dumped.
The address, hexloc1, may he one to six hexadecimal
digits; leading zeros are optional.
If hexloc1 is not
specified, the dump begins at storage location o.
If hexloc1 is followed by a period and is not on a
fullword boundary, it is rounded down to the next lowest
fullword.

section 8: Format and Usage Rules for CP Commands

277

DU"P
-}heXlOC2
{ : END

is the last hexadecimal storage location whose contents
are to be dumped to the printer. The operand, hexloc2,
must be equal to or greater than hexlocl and within the
virtual storage size. To dump to the end of storage, you
can specify END instead of hexloc2 or you can leave the
field blank, since the default is END. If you specify
:END or -END, the contents of storage froll hexlocl to END
are dumped.
The contents of storage locations hexlocl
through hexloc2 are printed with EBCDIC translation at
the printer. The operand, hexloc2, may be from one to six
hexadecimal digits; leading zeros are optional.

{ ·lbytecount

is a hexadecimal integer designating the number of bytes
of storage (starting with the byte at hexlocl) to be
dumped to the printer. The period,., must be specified
to dump the contents of more than one storage location by
byte count. The sum of hexlocl and bytecount must be an
address that does not exceed the virtual machine size.
If this address is not on a fullword boundary, it is
rounded up to the next highest fullword. The value,
bytecount, must be one or greater and can be no longer
than
six hexadecimal
digits.
Leading zeros
are
optional.

!!~

can be entered for descriptive purposes.
If specified,
it becomes the first line printed preceding the dump
data. Up to 100 characters, with or without blanks, may
be specified after the
asterisk prefix.
No error
messages are issued, but only 100 characters are used,
including asterisks and embedded blanks.

Normally, you should
following manner:

define beginning and ending dump

dump Lhexlocl-hexloc2
dump Lhexlocl.bytecount
dump Lhexloc1-hexloc2 hexlocl.bytecount

locations in the

dumpid

If, however, a blank follows the type character (L or T) or the
character and the hexloc, the default dump starting and ending locations
are assumed to be the beginning and/or end of virtual storage. Blanks
are used to separate operands or sets of operands if more than one
operand is entered on the same command line. Blanks must not be used to
the right or left of range or length delimiters
( : - • ), unless it is
intended to take the default value of the missing operand defined by the
blank. Thus, all of the following produce full storage dumps:
dump
dump
dump
dUllp
dump
dump
dump
dump

dump
dump
dump
dump
dump
dump
dump
dump

1
t

.
1t1:

t:
1.
t.

00:

I-end
t-end

dump
dump
dump
dump
dump
dump
dump

O-end
l:end
t:end
O:end
l.end
t.end
O.end

The following produces three full dumps:
dump 1
dump
278

.. t.

IBM V"/370: Command Language Guide for General Users

DUMP

DUMPING LOC hexloc
As the dump is processing, the following message is displayed at
the terminal indicating that the dump is continuing from the next
64K boundary: where hexloc is the segment (64K) boundary address
for the dump continuation, such as 020000, 030000, or 040000.
If you press the Attention key, or its equivalent, on the terminal
while the message is being displayed, the dump function is
terminated.
COMMAND COMPLETE
This response indicates normal completion of the dump function.

section 8: Pormat and Usage BuIes for CP Commands

279

ECBO
ECHO

Use the ECHO coaaand to place the terminal in the ECBO environment.
When in the ICBO environment, any input line entered is transmitted
unchanged back to the terainal a specified nuaber of tiaes.
To
terainate this transmission (for example, when you want to enter a
different data line), press the Attention key (or its equivalent). When
the specified nuaber of lines is displayed or the Attention key is
pressed, another read to the terminal is issued to accept another data
line. lote that no line editing is done; thus, the output line is the
saae as the input line and aay contain any of the logical line editing
syabols. The format of the ECHO co •• and is:

ECho

Innl

11 I

is the number of times the line is to be sent. The default is
1. An invalid entry (that is, one that is greater than 99 or
contains non-numeric characters) is treated as 1.

ECBO EITIRED;

TO TIR!IIATB TIST, TYPB BID

This message is displayed after the ECHO co.aand is invoked
indicate that the BCBO environment has been entered.

IITIR LIII
This message requests the input line to be entered.
returns the terminal to the CP command environment.

280

IB! '8/370: Command Language Guide tor General Users

A reply of liD

GC20-1804-3 Page Modified by TNL GN20-2659
EXTERNAL

EXTERNAL

Use the EXTERNAL command to simulate an external interrupt to the
virtual machine and return control to that machin€~ This simulates
pressing the interrupt key on the real computer console, or other
functions which cause an external interrupt.
Control is given to the
virtual machine immediately. The format of the EXTERNAL command is:
r--

EXTernal

,, ,

-----,

,,I

,codel
l

~.Q

L--

--'

code

is the interrupt code, a hexadecimal number to be associated
with the external interrupt. Valid codes are 1005
(CPU
Timer), 1004
(Clock Comparator) , and all codes less than or
equal to X'FF'. The default is the External Interrupt Button
on the system console, X'40'.

None. Since control is given to
from virtual machine processing.

the virtual machine, any

response is

section 8: Format and Usage Rules for CP Commands

281

GC20-1804-3 Page Modified by TNL GN20-2659
INDICATE

INDICATE

Use the INDICATE command to display at your terminal, the use of and
contention for major system resources.
Use INDICATE LOAD to display
system load conditions. Use INDICATE USER to display the total amount of
certain resources used by your virtual machine during the current
terminal session. Use the INDICATE USER command before and after the
execution of a program to indicate the execution characteristics of that
program in terms of the resources used.
The format of the INDICATE command is:
r-

I r
,
I
I INDicate I 11Q!~
I
I I USER * I
I
L
.J
__
IL----__________I .____________________________________

displays CPU use, CPU contention, main storage
storage contention.

LOAD
USER

CPU-nnnl

use, and main

displays the amounts of system resources used by your virtual
machine in the current terminal session.

Q1-nn

Q2-nn

STORAGE-nnnl

RATIO-n.n

I.
I
I
I

CPU-nnnl - is the percentage of total CPU usage.
The CPU figure is a
smoothed value of the percentage of time that the system is running.
The value
is smoothed
because instantaneous
values can
be
misleading.

I •
I
I

Q1-nn Q2-nn - represent the contention for the CPU in terms
smoothed number of users in queue 1 and queue 2 (maintained
scheduler).

I.
I
I

STORAGE-nnnl is the percentage of main storage usage. This is a
smoothed ratio of the sum of the estimated working sets of users in
queue 1 and queue 2 to the number of page able pages in the system.

I.
I

RATIO-n.n
represents the contention
for main storage. This
scheduler contention ratio is a smoothed value and is defined as:
E+M
RATIO
M

282

IBM VM/370: Command Language Guide for General Users

of the
by the

GC20-1804-3 Page Modified by TNL GN20-2659
INDICATE

the number of users waiting to be allocated main storage by the
scheduler and, therefore, temporarily resident in the scheduler's
eligible lists.

the number of users in queue 1 and queue 2.

Thus, RATIO is the ratio of users now active to users being serviced
and is 1.0 for optimum response. Optimum response occurs when enough
storage exists to accommodate all active users, assuming that the
system at this time is not CPU bound.
If E and M are both zero, the value of RATIO is set to 1.0.
When RATIO=1.5 and M=8, then 4 users are in the eligible lists
waiting to be allocated main storage space by the scheduler. While
1n the
eligible list,
the users
are subject
to scheduler
discrimination, as defined by the biased scheduler.

PAGES: RES-nnnn WS-nnnn READS=nnnnnn WRITES=nnnnnn DISK-nnnn DRUM-nnnn
VTIME=nnn:nn TTIME=nnn:nn SIO=nnnnnn RDR-nnnnnn PRT-nnnnnn PCH-nnnnnn

I •
I
I

RES-nnnn - is the current number of your virtual storage pages
resident in main storage. This number is taken at an instant of time
during the execution of the INDICATE command.

I.
I

WS-nnnn size.

I.
I

REIDS=nnnnnn - is the total number of page reads that have occurred
for you since you logged on or since the last ACNT command was issued
for your virtual machine.

I •
I
I

WRITES=nnnnnn - is the total number of pages written for you since
you have logged on or since the last ACNT command was issued for your
virtual machine.

I •
I
I

DISK-nnnn - is the current number of virtual pages allocated for you
on the system paging disk.
This number is taken at an instant of
time during the execution of the INDICATE command.

I.
I
I

DRUM-nnnn - is the current number of virtual pages allocated for you
on the system paging drum. This number is taken at an instant of time
during the execution of the INDICATE command.

I •
I

VTIME=nnn:nn - is your total virtual machine time since you logged on
or since the last ICNT command was issued for your virtual machine.

I •
I
I

TTIME=nnn:nn - is your total virtual machine time and total CPU time
(virtual and overhead) that you have used since you logged on or
since the last ICNT com.and was issued for your virtual machine.

I •
I

SIO=nnnnnn - is the total number of non-spooled I/O requests that you
have issued since you logged on or since the last ACNT command was

is the

most recent

system estimate

cf your

working set

section 8: Format and Usage Rules for CP Commands

282.1

GC20-1804-3 page Modified by TNL GN20-2659
INDICITE
issued for your virtual machine.

I.
I
I

RDR-nnnnnn - is the total number of virtual cards read since you
logged on or since the last leNT command vas issued for your virtual
machine.

I •
I
I

PRT-nnnnnn - is the total number of virtual lines printed since you
logged on or since the last ICNT command vas issued for your virtual
machine.

I.
I
I

PCH-nnnnnn - is the total number of virtual cards punched since you
logged on or since the last ICNT command vas issued for your virtual
machine.

282.2

IBM VMj370: Command Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659
IPL

IPL

Use the IPL command to simulate an initial program load function for a
virtual machine.
IPL simulates the LOAD button and the device address
switches on the real computer console.
The specified virtual address is
accessed and the required input/output operations are performed to
retrieve the IPL data.
optionally, the IPL procedure can be stopped
just before loading the virtual PSi except when initial program loading
a named system. Also, parameters can be passed to the virtual machine's
general registers.
When the simulated load function is complete, CP
initiates execution of the virtual machine by loading the IPL PSW which
was stored during the simulation process. The format of the IPL command
is:
Ipl

---,
vaddr [cylno 1

I CLear

IJ!Q~1~~~1
L

[STOP] ( [PARft {pl p2 ••• }

_______________-J

( systemname

vaddr [cylno] ICLEAR
I [STOP] [PARM {p1 p2 ••• }]
INOCLEARI
L

simulates the IPL function when loading by device address.
The address, vaddr, is the virtual address (cuu) of the device
that contains the nucleus to be loaded.
The number, cylno, is the cylinder containing the IPL data.
If this operand is specified, CP loads the IPL data from the
specified virtual cylinder instead of from the default,
virtual cylinder zero. This operand is valid only for virtual
direct storage devices.
The CLEAR operand clears the virtual storage space to binary
zeros before the operating system is loaded; NOCLEAR does not
clear storage.
Both of these operands are invalid if the user
specifies systemname in the IPL command line.
The STOP operand stops the virtual machine during the IPL
procedure just before the initial PSi is loaded.
The STOP
operand provides the virtual simulation of the IPL procedure
for a real machine in instruction step mode. The STOP operand
is invalid with the IPL systemname form of the command. When
the virtual machine stops, you can issue CP commands. For
example, if you are loading OS or OS/VS into your virtual
machine, you can use CP commands to store data into low
storage to load an alternate nucleus or to alter the size of
virtual storage.
To restart the virtual machine, issue the
BEGIN command.
The PARM p1 p2 ••• operand passes up to 64 bytes of data
(including embedded blanks) to your virtual machine's general
registers (four bytes per register), starting with the high
order byte of general register 0, whenever PARM is specified,
Section 8: Format and Usage Rules for CP Commands

282.3

IPL
the remaining characters in the command line are treated as
parameters to be passed to the virtual machine; therefcre,
PARM .ust be the last operand entered on the co.mand line.
systemname [PARM {p1 p2 ••• )]
simulates the IPL function when loading a named
was previously saved via the SAVESYS command.

syste. that

The systemna.e operand is the name of the previously saved
system.
It is loaded into virtual storage and given control.
For more information about saved systems, see the !]Lll~:
~12!~! Pr2gr~!!~I~2 ~Yig~·

The PARM p1 p2... operand passes up to 64 bytes of data
(including embedded blanks) to your virtual machine's general
registers (4 bytes per register), starting with the high order
byte of general register O.
Whenever P4RM is specified, the
remaining characters in the command line are treated as
para.eters to be passed to your virtual machine; therefore,
PARM must be the last operand entered on the command line.
!Q!~:

Care .ust be used when passing parameters to a named
system (systemname)~ Named systems expect certain registers to
be initialized when they are given control. Indiscriminate
use of the PARM option could overlay a previously initialized
register causing unpredictable results.

After a successful IPL, any responses you receive are those
operating system that was loaded and initialized.

from the

section 8: Format and Usage Rules for CP Commands

283

GC20-1804-3 Page Modified by TNL GN20-2659
LINK

LINK

Use the LINK co •• and to make a device that is associated with another
virtual machine available to your virtual machine configuration, based
upon information in that user's VM/370 directory entry.
The format of
the LINK command is:
r-

LINK

[TO] userid vaddrl [As] vaddr2 [mode] [[PASS=] password]

L-

where:
[TO]-userid

is the name of the user whose VM/370 directory is to be
searched for device vaddrl. An asterisk (*) is used to
specify that the Qevice is in your own VM/370 directory.
If the keyword TO is omitted, the userid may not be TO or
T.

vaddr 1

is the virtual device address
directory for that userid.

(cuu)

the

VM/370

[AS] vaddr2

is the virtual address (cuu) which is to be assigned to
the device for your virtual machine. If the keyword AS is
omitted, vaddr may not be A. If your virtual machine has
tbe ECMODE option, any address up to X'PPF' is valid;
otherwise, any address up to X'5FF' is valid.

mode

is the
access mode; the primary
access requested
(read-only, write, or multiple), and the alternate access
(read-only or write) desired if the primary access is not
available. Valid modes are:
~gg~ 1!~~.!!.!.!!g

Read-only access. The link is not done if any other
user has the disk in write status. R is the default
mode if the link is to another userid.

Read-only access. The link is established
another user has the disk in write status.

Write access. The link is not done if any other user
has the disk in read or write status.

Write and read access. If another user has the disk
in read or write status, an alternate access of
read-only is acceptable.

Multiple access. This means that a write-link is to
be given to the disk unless another user already has
write access to it, in which case no link is to be
done.

Write-link. If another user already has write access
to the disk, a read-link is to be done.

Write-link. This link is established in all cases.

even if

Multiple write access under CMS can produce
unpredictable results.

~~~1.!on:

If the mode is omitted, the default is R if the use rid is
another user; if you are linking to one of your own
284

IBM VM/370: Command Language Guide for General Users

LIIK
disks, the default is the "user access mode" of either R,
W, or ft as specified in the Vft/370 directory for your
disks.
PASS= password

18 a eneto eight-character string that must match the
access mode password for devicE vaddrl in the Yft/370
directory for the user (userid) specified. The password
should be specified only when the LIIK is executed by a
virtual machine (for example, from CftS), since the
password is not print suppressed when included with the
LIIK command~ The password cannot be the same as ani of
the access modes (R, RR, V, VR, ft, ftR, or ftV) if the
default mode is to be used.

lote: The access mode
with a user password.

password should

not be

confused

If you link to one of your own disks, no password is required. Also,
if the link is to a device whose password is ALL, meaning that the
device can be used by all users, the password is not required. However,
if the link is to any other userid, a password for the desired device
must be provided.
!2te: The access allowed by the LIIK command to the vaddrl device
belonging to userid is summarized below. Iou read the columns down to
determine the type of link that results. The first row indicates the
primary (and, optionally, the alternate) access mode requested.
The
second row indicates whether read, write, or multiple passwords exist in
the V8/370 directory for the disk being linked. The third row indicates
whether the disk is already being used, and if so, the mode of its
access.
The last row indicates the type of link established.
For
example, the third column is interpreted as follows: if you request a
read access link (R) to a disk that has a read password defined and that
already is accessed in read mode, you can establish a read link.
Primary access requested:
alternate access (if any) :

R R R R R VVVVV
R

ft ft ft 8 ft ft
R i

1
I

I I I I I I

1
I

-----------------------------------------------------------------1
Read password in directory:
I I I I I
I
write password in directory:
ftult. password in directory:

I I I I I I

-------------------------------------------------------------------1
Any existing links:
I R VV
I R R VV
I RVVV 1
======================================================================1
Access established:
I R R I R I WI R I R I V V I R V 1

------------------------------------------------------------------1
I=no or none; R=read; W=write; ft=aultiplei I=yes
I
!he~~:

EITER READ PASSWORD:

••••••••

Type the read password
desired disk.

over the mask to obtain read

access to the

EITER VRITE PASSWORD:

••••••••

Type the write password over the mask to obtain write access to the
desired disk.
Section 8: Format and Usage Rules for CP Commands

285

LIIK
EITER ftULT PASSVORD:

••••••••

Type the aUltiple password over the aask to obtain write access to
a disk for which other users aay already have access.

!2i!: If

LIIK is issued from a virtual aachine with the password
included on a co.aand line, and the password is incorrect, then CP
counts these incorrect passwords. If a total of ten such incorrect
passwords is entered, the LIIK co.aand froa a virtual aachine is
subsequently disallowed for that user for the re.ainder of the
session. LIII can still be issued directly froa the terainal (that
is, in CP co •• and mode), or the LIIK co •• and can be reinstated as a
valid co.aand from your virtual machine by logging off and logging
on again. (This procedure is designed to protect password security
if a virtual machine issues the LIIK comaand repeatedly with trial
passwords.)

D1SD vaddr2 LIIKED R/O
This response indicates that a read-only link to the given disk is
established, for a LIIK request with a mode of R or RR, and that no
other users are linked to the sa.e disk in read/write aode.
D1SD vaddr2 LIIKED R/i
This response indicates that a read/write link to the given disk is
established, for a LIIK request with a mode of V, VR, ft, ftR, or ftV,
and that no other users are linked to the same disk.
r

D1SD vaddr2 LIIKED R/O; R/V BY {nnn ~SERS}I; R/O BY {nnn USERS}I
user1d
I
userid
I
This response indicates that a read-only link to the given disk is
established for a LIII request with a aode of RR, but warns that
the disk is in read/write use by some users and possibly in read
use by some users. If only one user has access, the number of users
(nnn USERS) is replaced by userid.
D1SD vaddr2 LIIKED R/i; R/O BY {nnn ~SERS}
user1d
This response indicates that a read/write link to the given disk is
established for a LIII request with a mode of ft, ftR, or ftV, and
informs you that the disk is also in read-only use by userid or by
nnn users. (10 other users have a read/write link to the disk.)
r

D1SD vaddr2 LIIKED R/V; R/i BY {nn USERS} I; RIO BY {nnn USERS} I
userid
I
userid
I
L

This response indicates that a read/write link to the given disk is
established for a LIIK request with a .ode of Bi, but warns you
that the disk is also in read/write use by some users and possibly
in read use by soae users. If only one user has access, the number
of users (nnn USERS) is replaced by userid.
.

286

IBft Yft/370: Com.and Language Guide for General Users

LOADVFCB
LOADVFCB

Use the LOADVFCB co.mand to specify the forms
spooled 3211 printer. The format of the LOADVFCB
LCADVFCB

vaddr

FCB

name

L-_______________________________

control for
, . . " " . . . ""S .....

,"""" • • a.,uu

a virtual

..:._ ..

~~.

[Index [nn))

vaddr

is the virtual device
spooled printer.

FCB

is a required reserved word meaning Forms Control Buffer.

name

is a system-defined name for the 3211 FCB image which is to be
the controlling virtual FCB image.

address

(cuu)

of the

virtual

3211

There is only one VM/370 FCB image provided; its name is FCB1
and its format is as follows:
Space 6 lines/inch
Length of page 66 lines
Line
Represented
1
3

5
7
9

11
13

Channel Skip
Specification
1
2
3
4
5
6

7
8

15
19

21
23

INDEX [nn]
is the number of the print position that is the first print
position. The value, nn, must be a number from 1 through 31; a
leading zero need not be specified. If the keyword INDEX is
specified without a value, the index defaults to the value
specified in
the FCB macro.
See the
!~L37Q:
§I2!~~
~!£~!~~~~!~§ §~!g~ for a discussion of the FCB macro and forms
control images.
Note: The LOADVFCB command may be used with installations that do not
a 3211. The virtual machine's VM/370 directory entry must indicate
a 3211, even though the program and operating . system have a 1403
defined. Then the LOADVFCB command can be used to obtain a virtual
forms control image for 1403 printers so that programs that use printer
overflow sensing may be spooled to disk.

have

None.
Section 8: Format and Usage Rules for CP Commands

287

GC20-1804-3 Page Modified by TNL GN20-2659
LOGOFF
LOGOFF

Use the LOGOFF command to terminate virtual machine execution and
disconnect your virtual machine from the VM/370 system.
This command
causes all active spool files to be closed, temporary disks to be
relinquished, dedicated devices to be detached, and an accounting record
to be created for the user. The format of the LOGOFF command is:

,.-

LOGoff
I LCGout
L-_ _ _ __

HOLD

[HOld]

I
I

retains the connection for a switched communication line to
enable you to logon without redialing the VM/370 system.

You should always logoff and not only turn power off on
Terminal power off is not synonymous with logoff.

the terminal.

If you turn power off at the terminal instead of logging off, logoff
occurs by one of the following methods:

•

I •

~~~g~~

lI~~~~i!~~ ~g~!i~~l--Logoff
takes place after a 15-minute
interval has elapsed. This occurs if no attempt is made to power on
the terminal and re-establish communications with the still logged-on
virtual machine during this 15-minute period.
J~lQ

]!§E!~I %~f~!~~l--Logoff
only takes place 15 minutes after
VM/370 discovers that the terminal has been turned off (that is,
VM/370 attempts to send a message to the terminal, but gets back an
error code indicating that the terminal is turned off). Because many
hours may pass before VM/370 discovers that the terminal is turned
off, you run the risk of compromising the security of the virtual
machine and data files.
Anyone turning the 3270 power back on has
access to the virtual machine without logging on. This is because
the machine is still logged on, although inactive.

CONNECT= hh:mm:ss VIRTCPU= mmm:ss.hs TOTCPU= mmm:ss.hs

288

CONNECT

hh:mm:ss

is the actual clock time spent in the current
terminal session in hours:minutes:seconds.

VIRTCPU

mmm:ss.hs

is
the
virtual
CPU time
used in
current
terminal
session
minutes:seconds.hundredths of seconds.

IBM VM/370: Command Language Guide for General Users

the
in

LOGOll
TOTCPU

••• :ss.hs

These ti.es

is the total CPU time (including virtual and
overhead) used in the current terainal session
in ainutes:seconds.hundredths of seconds.

are either

the elapsed time

session or the elapsed time since
this user.

for the

entire ter:inal

the ICIT co •• and was entered for

LOGOll IT hh: •• :ss zone weekday .a/dd/yy
is the response for a logoff.
GRIl raddr}
raddr LOGOll IS userid USERS = nnn
{ LINE
DBY rid
is the noraal response to the priaary
specifies the resource identification.
GRIF raddr}
LIIE
r~ddr
LOGOll IS userid USERS
{ DEY r1d
.
-

= nnn

systea operator.

rORCED

is the response to the priaary system operator if the
forced by a line tiaeout or a terminal power-off.
DEV rid specifies the resource identification.
USER DSC

LOGOll IS userid

USERS

DEY rid

logoff is

= nnn

is the response to the primary systea operator when logoff occurs
for a user who had previously disconnected using the DISCOII
co.aand.

Section 8: loraat and Usage Rules for CP Co•• ands

289

LOGON
LOGON

Use the LOGON co •• and to identify yourself to the VB/310 syste. and to
access that syste.. Upon successful logon, VB/370 creates a virtual
machine configuration fro. infor.ation in the VB/310 directory.
The
LOGOI com.and name may not be entered using any line-editing sy.bo1s,
but the operands .ay use these symbols. See the !AL11Q: ~!iA!! User's
~~ide for a detailed description of
logon procedures. If you use LOGOI
because a teleprocessing line or terminal error disconnected you fro.
your virtual aachine, you have 15 minutes to logon again. If you do not
log on within 15 .inutes, your virtual aachine automatically logs off.
In this case, you .ay have to reconstruct files and restart jobs
interrupted by the teleprocessing line or ter.inal error. The format of
the LOGON command is:
Logon
Login

userid

[password]

[Bask]

[Noip1]

use rid

is the identifier assigned to you in the VB/370 system.

password

is your password.
Specify this field if
is, .asking characters) is desired.

BASK

types masking characters to cover the password on typewriter
terminals without the print inhibit feature. The mask types on
the line following a proapting message from VB/310 requesting
you to enter your password. Should you forget to ask for
masking when you type LOGOI, you can press the carriage return
after the prompt for the password types, and V!/310 then types
out the masking characters.

IOIPL

specifies that the IPL device or naae in the VB/370 directory
should not be used for an automatic IPL.

no protection (that

Responses
EITEB PASSWOBD:
indicates that the userid has been accepted. You should type in
the password, or signal a carriage return if a mask is desired for
the password, and BASK was not included on the com.and line.
LOGBSG- hh:.m:ss .m/dd/yy
indicates the ti.e and date at which the system log message was
generated or most recently revised. If you wish to see all of the
system log messages, you must issue the CP com.and QUERY LOGBSG.
Any lines of the log message for which the first character is an
asterisk are displayed at this point.

290

IB! VB/310: Com.and Language Guide for General Users

LOGOI

This

.essage is

indicates the

o.itted

if all

number of spool

counts

files that

are

zero, otherwise

exist for

JOU

at logon

tiae.
LOGOI IT hh: •• :ss zone weekday ••/dd/yy
-- or -RBCOIIBCTBD IT hh:.a:ss zone weekday .a/dd/yy
indicates the tiae, day of the week, and date at which the LOGOI or
RBCOIIECT is coaplete.
GRll raddr}
raddr LOGOI IS userid
{ LIIB
DEY rid

USBRS

= nnn

USBRS

= nnn

-- or -GRll raddr}
raddr > RECOIIBCT userid
\ DBV rid J

JJ LIIB

is the response to the pri.ary
the resource identification.

systea operator.

DEV rid specifies

Section 8: loraat and Usage Rules for CP Co •• ands

291

MESSAGE
MESSAGE

Use the !ESSAGE coaaand to transait aessage text to a specified userid
or to the priaary systea operator.
If the user designated to receive
the aessage is not logged on or has suppressed the receiving of
aessages, the aessage is not transaitted and the sender receives a
diagnostic aessage to this effect. A aessage which is not received by a
user is not saved and aust be sent at a later tiae when the user is
receiving aessages. The aessage is displayed at the terainal when the
terainal is ready to receive output. If a typewriter terainal (or a
display terainal h.aving AUTOREAD set 01) is entering data, the class Any
aessage is held until an end-of-line (carriage return or EITER) signal
is received. The foraat of the !ESSAGE co.aand is:
Message
!SG

:serid

} asgtext

{ OPerator

where:

userid

is the identification of the single user who is to receive the
aessage.

specifies that you are sending a message to yourself.

OPERATOR

sends the aessage to the priaary systea operator regardless of
his userid.

asgtext

is the text of the aessage which is to be transaitted. As
.any characters .ay be entered as will fit on the re.ainder of
the input line.

Responses
hh:aa:ss
!SG PROB OPBRATOR: asgtext
is the response received by the user fro. the syste. operator.
hh:.a:ss
BSG PRO!

{tOGO~XXX}:

user1d

asgtext

is the foraat of the aessage sent to another user or to the
syste. operator, where userid is the na.e of the sender. If the
user sending the aessage is not logged on to Y!/310, LOGOI and
the line nu.ber are displayed instead of userid.
hh:.a:ss
is the tiae in hours:.inutes:seconds when the
to the user.
If the user receiving the aessage is the pri.ary
alar. bell at the central coaputer console rings.

292

aessage was sent

systea operator, the

IBB YB/310: Co •• and Language Guide for General Users

HOTREADY
NOTREADY

Use the HOTREADY command to cause a virtual device to appear as if it
had changed from ready to not ready status. This co.mand is for Use with
spooled unit record devices and virtual consoles only. Any I/O operation
to the specified device, in progress at the time the command is issued,
is completed.
On the next start I/O (510) instruction, the not ready
condition is in effect. The format of the HOTREADY command is:

10TReady

vaddr

I
I

vaddr

is the virtual device address (cuu)
from ready status.

of the unit to

be removed

Response
INVALID DEVICE TYPE
This is the response if the device specified by
spooled unit record device or a virtual console.

vaddr is

section 8: Pormat and Usage Rules for CP Commands

not a

293

ORDER

Use the ORDER com.and to place your closed spool files, by device type,
in a specific order. you can deter.ine via the QUERY co.mand the
filename, filetype, originating userid, spoolid, and other attributes of
all of your files. The files are ordered as they are passed to your
spool device; you may order only your own files. The for.at of the ORDER
co.mand is:

ORDer

I {Reader }
I Printer
I PUnch

{CLaSS c 1 CLass C2 ••• }1
spoolidl spoolid2 •••

1Sequencing can be done with the ORDER co.mand using a combination of
CLASS and spoolid specifications. For example:
ORDER PRIITER CLASS A 1963 CLASS C
specifies that printer files are processed in the following order:
all class A files, the file with spoolid 1963, and then all class C
files.

REIDER
RDR

orders the reader spool files.

PRIITER
PRT

orders the printer spool files.

PUICH
PCH

orders the punch spool files.

CLASS c1 CLASS c2 •••
processes the input and output spool files in the order in
which their classes are specified. CLASS is a required
reserved word and cl, c2,... are one-character alphameric
fields (with values from A to z and from 0 to 9) representing
the spooling classes.
spoolid1 spoolid2 •••
processes the files represented by the spoolids
in which the spoolids are specified.

in the order

{:~nD } FILES ORDERED
This response indicates the number of files ordered.
displayed if you issued the CP SET IMSG OFF command.

294

IBM VM/310: Command Language Guide for General Users

is not

PURGE

Use the PURGE co •• and to remove your own closed spool files from the
system before they are printed or punched by the spooling devices, or
before they are read by a user. Any closed file may be purged regardless
of its status, as long as it has not been selected for processing. The
format of the PURGE co •• and is:
PURge

I Beader
I Printer
I ) PUnch
I \ ALL

,l~

ICLass.c1 CLass.c2 ••• I (
I spoo11d 1 spoo11d2... i )
IALL
I
J

lPurging may be done using a combination of CLASS and spoolid
specifications. Por exa.ple:
PURGE PRINTER CLASS A 1932 CLASS D 619
specifies that all Class A and Class D printer files and printer
files with spoolids 1932 and 619 are to be purged.

READER
RDR

purges all reader files.

PRIITER
PRT

purges all printer spool files.

PUICB
PCB

purges all punch spool files.

ALL

purges all spool files. When ALL is specified for device type,
all other operands are ignored~

CLASS c1 CLASS c2 •••
purges the files of the specified device type and class. CLASS
is a required reserved word and c1, c2, ••• are one-character
alpha.eric fields (with values from A to Z and 0 to 9) that
represent the spooling class.
spoolid1 spoolid2 •••
purges only the files for the specified spoolids.
ALL

purges all
punch) •

files of the

specified type (reader,

printer, or

{:~nn} PILES PURGED

This response indicates the nu.ber of files purged.
displayed if you issued the CP SET IftSG co ••and.

It is

not

Section 8: Pormat and Usage Rules for CP Co •• ands

295

QUBRY
QUERY

Privilege Cl!22: G and all classes except class Any
Use the class G QUERY command to
.achine configuration.
You can
information:

find the status of your
request
the following

•

Bow .uch ti.e you have used during a ter.inal session.

•

Bow many
.achine.

•
•

Bow you have set the functions of the SET command.

•

The status of all the devices on your virtual machine •

I.
I

input

and

output spool

files

reside

syste. and
types of

your

virtual

Bow you have set the options of the TERftINAL co •• and.

The channel
operating mode
block-multiplexer or selector.

your

•

All users, and their device addresses
linked to a given virtual address.

•

Various kinds of
reader.

• achine,

virtual
and access

information about your virtual

either

modes, who

are

printer, punch, and

There are other operands you can use with the QUBRY com.and if you
have the privilege class required to use them. These are described in
the !ftL31Q: QE~tor~~ §uide. Also, if you are a CftS user, you can use
the CftS QUBRY co •• and to query the status of your CftS virtual machine.
lor ease of use, the QUERY co.mand and operands described in this
section have been separated into the operands available for general
users (class G) and those available to all users except class Any.

296

IBft Vft/310: Co.mand Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659
QUERY
The QUERY Command lor Class G Users

The format of the Class G QUERY command is:

r------------------------------------------Time
Query

set
TERMinal
'
Files

[CLass c]
CHANnels \
GRAF
CONsole
Dasd
TApes
LINES
UR
STORage
ALL
vaddr

[ Virtual]

Links

vaddr
r

Reader
Printer
PUnch

1spoolid 1
IALL
1
ICLass c 1
L

PF[ nn ]

TIME

displays the current time, time zone, weekday,
and CPU time for the current terminal session.

date, connect

FILES [CLASS c]
displays the number of spooled input and output files for your
virtual machine. Files currently being processed are not
included in the totals.
If CLASS is specified, the number of
spooled input and output files of the class specified is
displayed.
SET

displays the status of the SET command functions.

TERMINAL

displays the current
console environment.

VIRTUAL

displays the status of all virtual devices.

options in

effect

fer

your

operation

virtual

CHANNELS

displays the channel mode
virtual machine.

GRAF

displays the status of all your virtual
devices that are locally attached.

CONSOLE

displays the status of your virtual consoles.

DASD

displays the status of all
access storage devices.

ycur

virtual

for

the

display

direct

Section 8: Format and Usage Rules for CP Commands

297

QUERY
TAPES

displays the status
tape devices.

LINES

displays
the
status
communication lines.

displays
devices.

STORAGE

displays the size of your virtual storage.

ALL

displays the status of all your virtual devices.

vaddr

displays the status of the virtual device at address
vaddr.

the

status

of all

your virtual

magnetic

your

virtual

of
of

all
all

your

unit

record

LINKS vaddr
displays the userid, device address, and access mode at the
terminal for all users linked to the specified v~rtual address
(vaddr) •
READER
RDR
PRINTER
PRT
PUNCH
PCH

displays the following information, pertaining to your virtual
reader, virtual printer, and virtual punch spool files:
•
•
•
•
•
•

Userid (of user who created the file)
Spool file identification (spoolid)
Class and originating device type
Number of logical records in the file
Number of copies specified for the file (has no effect for
reader files)
File hold status

One line of information is displayed for each spool file.
READER }
{ PRINTER spoolid
PUNCH
displays additional information for one spool file. The
spoolid operand must follow the READER, PRINTER, or PUNCH
operand. In addition to the information normally displayed for
reader, printer, or punch files, the following is also
displayed:
•
•
•

Date and time the file was created
Filename and filetype of file (if any)
Distribution code of the file
(PRINTER
only)

and PUNCH

Only one line of data is displayed (that data
the spool file specified by spoolid).

files

pertaining to

FILES }
READER
{ PRINTER ALL
PUNCH
displays additional information for spool files.
The ALL
operand must follow the READER, PRINTER, or PUNCH operand. In
addition to the information normally displayed for the reader,
printer, or punch files, the following is also displayed:

298

IB6 V6/370: Command Language Guide for General Users

QUERY
•
•
•

Date and time the file was created
Pilename and filetype of file (if any); if your file was
assigned a dsname and you later issue QUERY, only the first
20 characters of the 24-character field are displayed.
Distribution code of the file (PRINTER and PUNCH files
only)

One line of information is
the type specified.

iii
~nl ::1IVQ~
---';---41: - -

for each

file of

FILES }
READER
{ PRINTER CLASS c
PUNCH
displays the basic information for all speol files of the
class specified by c.
This operand must follow the FILES,
READER, PRINTER, or PUNCH operands.
One line of information is displayed
the specified class.
PF[ nn]

for each spool

file of

displays the 3270 Program Function key number specified, along
with its associated command lines. If nn is not specified, all
12 program function keys and their associated data lines are
displayed. The value, nn, is a number from 1 (or 01)
to 12.
See the CP SET command for an explanation of how to define and
use program function keys.

This section describes
command.

the

messages CP

prints

response to

your

TIME IS hh:mm:ss zone weekday mm/dd/yy
The current real clock time in hours:minutes:seconds, the time zone
(for example, EST), the day of the week and the calendar date
(month/day/year) are displayed.
CONNECT= hh:mm:ss VIBTCPU= mmm:ss.hs TOTCPU= mmm:ss.hs
The time spent in the current terminal session is displayed.

CONNECT= hh:mm:ss

is the actual clock time spent in the current
terminal session in hours: minutes: seconds.

VIRTCPU= mmm:ss.hs is the virtual CPU time used in the current
terminal session in minutes:seconds.hundredths
of seconds.
TOTCPU= mmm:ss.hs

is the total CPU time (virtual and overhead)
used in
the current
terminal session
in
minutes:seconds.hundredths of seconds.

section 8: Format and Usage Rules for CP Commands

299

GC20-1804-3 Page Modified by TNL GN20-2659
QUERY

~ ~hE}

ON }
{ON }
{ON }
{ON }
MSG { OFF, WNG OFF, EMSG {TEXT, ACNT OFF, RUN OFF
LINEDIT

{~~F ~,

ON
ASSIST { OFF
IMSG

TIMER

{~:F

}, ISAM

REAL

{;~~VC}},

PAGEX

{~:F}'

ECMODE

{~;F }

{ ON}
OFF

{~~F}
The settings of all functions controlled by the SET command and the
VM/370 directory ISAM and ECMODE options are displayed. Refer to
the discussion of the SET
command for explanations of the
functions.

LINEND

{~FF},

LINEDEL

LINESIZE nnn, MASK

{~FF},

{~:F},

APL

CHARDEL

{~:F},

{~FF}'
ATTN

ESCAPE

{~;F},

{~FF}

MODE

{~:}

The settings of all functions that are controlled by the TERMINAL
command are displayed. Refer to the discussicn of the TERMINAL
command for explanations of the functions.
If LINEDIT is turned
off, the logical editing symbols displayed are those that were in
effect before line editing was turned off.

FILES: {~~n} RDR, {:~n} PRT, {:~n} PUN
The total number of spool files in your system is displayed. If you
specify the CLASS option with QUERY FILES, only the totals for the
class you specify are indicated rather than for all classes on your
system.

CHANNELS= {SEL}
BMX
The operating mode of the virtual machine channels is displayed.
This reponse applies to all of the virtual machine channels except
channel 0, which is always a byte-multiplexer channel, and any
channels with virtual or real channel-to-channel adapters, which
are always selector channels.
300

IBM VM/370: Command Language Guide for General Users

QUIR!

vaddr ION DEY raddr}~

llOT RIID!
The status of all locally attached virtual display devices defined
to your virtual aachine is displayed.

vaddr

is the virtual address to which the device is attached.

raddr

is the real address of the device.

BOT BlIDY shows the status of a virtual display deyice that has not
been attached via the DIlL coaaand.

GRIP}
COIS vaddr 01 { LIII raddr

TER!} {STOP }
{ IOTIR!
STIRT

COlT} { HOLD}
{RBID! }
vaddr CL c { BOCOIT
JOHOLD COP! nn 10TRBID!
vadd r

{i~R } userid

DIST distcode

Por virtual aachine consoles, a three-line response is displayed.
The first line shows the console status and options and the next
two lines are the virtual console spooling status.

vaddr

is the virtual address of the virtual aachine console.

raddr

is the real address of the terainal
virtual console.

is the spooling class of the console.

is the nuaber of copies spooled.

userid

is the user identification.

distcode

is the distribution code.

The other fields indicate the setting
the SPOOL coaaand.

associated with the

of the respective options in

The default settings for a virtual console are:
COIS vaddr 01 DBV raddr TER! STOP
vaddr CL T 10COIT 10 HOLD COPY 01 RBIDY
vaddr paR userid DIST distcode

Section 8: Poraat and Usage Rules for CP Coaaands

301

QUERY

R/i}
DASD vaddr type volser { B/O

The status
displayed.

each

DDD

CYL

virtual disk

defined

for

your

syste.

the DASD

device

!lhe!:~:

vaddr

is the virtual address
attached.

type

is one of the following device types:

which

2311
2305
2314
3330
3340
231T (2311 at top of 2314)
231B (2311 at bottom of 2314)
volser

is the volu.e serial number of the system
this virtual disk resides.

R/i
R/O

indicates the read/write status of the disk.

nnn

is the number of cylinders on the virtual disk.

disk on which

TAPE vaddr ON DEV raddr
The status of each tape defined for your system is displayed.

vaddr

is the virtual address to which the tape is attached.

raddr

is the real address of the tape.

LINE vaddr ON DEV raddr
The status of all co.munication lines
.achine is displayed.

defined

in your

virtual

vaddr

is the virtual address to which the line is attached.

raddr

is the real address of the line.

:,ENABLED }
LINE vaddr { DISABLED
The status of virtual com.unication
is displayed.
302

lines at virtual address vaddr

IBft V8/370: Co •• and Language Guide for General Users

QUERY

CORT} { HOLD} { EOF} {
READY}
RDR vaddr CL c { BOCOBT .. BOHOLDNOEOF . ROTREADY _
The status of all the virtual
machine is displayed.
where:

vadci'r

readers attached

to your

virtual

is the virtual device address of the virtual reader.
is the spool file class which the device services. A
class of * indicates the device serves all classes of
spool files for input.

The other fields indicate the setting
the SPOOL command.

of the respective options in

The default settings for a reader are:
RDR vaddr Cl
PRT }
{ PUB vaddr Cl
vaddr

{

iTO

FOB

{
}

IOCONT NOHOlD READY EOF

~OCONT}

CORT} {

HOLD}
{REIDY}
.0HOl£ COpy nn NOTREADY

userid

DIST distcode

The status of all the virtual printers and punches attached to your
virtual machine is displayed.
where:
vaddr

is the virtual
punch.

device address of the

virtual printer or

is the output class assigned to spool files produced from
the device.

is the number of
produced.

copies

each

output file

TO userid indicates that the output from the device, when closed,
becomes a reader input spool file for the indicated
userid.
FOB userid

distcode

indicates the userid identification (spool file
assigned to spool files produced from the device.
is the distribution code assigned
produced from the device.

owner)

each spool

file

Bote: The distcode in this case indicates the FOR userid; however,
the-distcode produced on the output files when the file is closed
is the distcode assigned to the FOR userid as specified in the
V!/370 directory.
The other fields indicate the setting
the SPOOL co •• and.

of the respective options in

Section 8: Pormat and Usage Rules for CP Co •• ands

303

QUERY
The default settings are:
PRT}
{ PUN vaddr CL A ROCONT NOHOLD COPY READY 01
vaddr FOR userid DIST distcode
where:
userId and distcode are assigned for the virtual machine.

STORAGE = nnnnnK
The size of
displayed.

the virtual

.achine in

.ultiples of

1024 bytes

Has the same effect as if all the following com.ands were issued:
QUERY
QUERY
QUERY
QUERY
QUERY
QUERY
QUERY
QUERY

VIRTUAL
VIRTUAL
VIRTUAL
VIRTUAL
VIRTUAL
VIRTUAL
VIRTUAL
VIRTUAL

STORAGE
LINES
TAPE
UR
DASD
GRAF
CORSOLE
CHANNELS

The response is in the same form as QUERY VIRTUAL DASD, TAPES, LINES, or
UR, depending on virtual device type.

userid vaddr {R/O},
•
R/i

A list of users
is displayed.

304

who linked to the device at

userid

is the identification
link.

vaddr

is the virtual address by
to the device.

R/O
R/i

is the type
device.

of access

of the

user

virtual address vaddr

who originated

the

which the user (userid) refers
the

user

(userid) has

IB! V!/370: Co •• and Language Guide for General Users

the

QUERY

ORIGINID lILE CLASS RECDS CPY HOLD IDATE TIftE
NAftE TYPE DIST
I
userid spoolid c typ norecs nn stat Imm/dd hh:mm:ss fn
ft
distcodel
L

userid

is the user who originally created the file.

spoolid

is a unique, system-assigned number which is used by Vft/370 to
identify the file.

is the spool file class.

typ

is the originating device type (PRT, PUR, CON, or RDR) •

norecs

is the number of logical records contained in the file.

is the number of copies assigned to the file (it has no effect
for virtual reader files).

stat

is the file hold status: lONE (no hold), USER (user hold), SYS
(syste. hold), or USYS (syste. and user hold) •

mll/dd

is the date the file was created in month/day.

hh:II.:ss

is the time of file creation in hours:.inutes:seconds.

is the filename assigned to the file (if any) •

is the filetype assigned to the file (if any).

distcode

is the distribution code assigned to the file.

When you issue QUERY RBIDBR, QUERY PRINTER, or QUERY PUNCH cOllllands,
responds by listing (in the fora described) all the files associated
with your virtual reader, printer, or punch.
rD

The information listing DATE, TIME, RAftE, TYPB, and DIST (date of
file creation, time of file creation, nalle of file, filetype of file,
and file distribution code) is displayed only when you specify the ALL
or spoolid operands.

IftftBD}
Plnn { DELIY pfdatal •••
The program function defined for a program function key is
displayed.
If there is no function defined for the program
function key, this message is generated in the user input area of
the screen:
Plnn UIDBPIIBD
lot!: If the next com.and you enter is shorter than this message,
you .ust first clear the input area or enter enough blanks to
eliminate the message; otherwise, errors result.
Section 8: lorllat and Usage Rules for CP COllmands

305

QUERY
QUERY Command for All Classes of User:,; (Except Class Any)

Use tbis form of the QUERY command to:
I.
I.
I.

Display the log messages.
List all the users that are logged on.
Display the number of users that are logged on or dialed to 'ft/370.

This form of the QUERY command is for all classes of users except those
in the Any category. The format for this QUERY command is:
Query

LOGmsg
}
Haaes
[userid]
{ Users
L - - -______________________________________________________________________
userid

LOGftSG

displays the log messages of the day.

HAftES

displays a list of all the users logged on and the real
address of the line to which each is connected. If a user
is disconnected, DSC is printed instead of the line
address.

USERS

displays the number of logged on users and the number of
users logically connected to other virtual machines.

USERS use rid displays the user identification and the terminal device
userid
address of the specified user if he is logged on. If the
user is not logged on, a message to this effect is issued.
Use the QUERY USERS userid format if the userid is the same
as an operand of the QUERY command (for example, TAPESJ.

logmsg text line 1

logmsg text line n
All lines (both those with an
message file are displayed.

asterisk and

without) in

userid - {DSC }'
raddr
userid - { DSC }' •••
raddr
306

IBft '8/370: Command Language Guide for General Users

the log

QUERY
A list of all logged-on users is displayed; if the user is
currently connected, the real address to which he is connected is
displayed (raddr); if he is not connected to the system, DSC is
displayed.

nnn USERS, ••• DIALED
The number of users logged on and dialed to VM/310 is displayed.
!~!I!:

nnn

is the total number of logged-on users •

•• m is the

total number
machines.

of users

attached via

DIAL to

virtual

Note: DIALED means the line is not available to CP because it is
logIcally attached to a multiple-access virtual machine and is a
part of that user's virtual machine operation.

userid - raddr
The real address
is displayed.

(raddr) to which the specified

user is connected

section 8: For.at and Usage Rules for CP Com.ands

301

READY

Use the READY co •• and to set a device-end interrupt pending for the
specified virtual device.
The status of the virtual machine is
unchanged. Other than having a device-end interrupt pending, the virtual
device is unchanged.
The format of the READY com.and is:

READY

vaddr

is a virtual device address (cuu).

None.

308

IBM VM/370: Command Language Guide for General Users

REQUEST
REQUEST

Use the REQUEST command to make an attention interrupt
virtual console. The format of the REQUEST com.and is:

pending at your

REQuest

The ATTN command performs the same functions as
commands can be used interchangeably.

REQUEST and

the tva

lone.

Section 8: Por.at and Usage Rules for CP Co •• ands

309

RESET

BESET

Use the RESET co •• and to clear all pending interrupts fro. the specified
virtual device. In addition, all error conditions occurring as a result
of unit checks and virtual sense bytes are reset. Th~ for.at of the
RESET co •• and is:

RESET

vaddr

.!.h~:

vaddr

is a virtual device address (cuu) of the device to be reset.

DEVICE RESET

310

IB! V!/370: Co •• and Language Guide for General Users

REWIND
REWIND

Use the REWIND command to rewind (but not unload) a real tape unit
attached to your virtual machine at a specific virtual device address.
This accomplishes the manual operation of rewinding and making the tape
ready at the tape unit. The format of the REWIND command is:

r-------------------------------vaddr

IL-_REWind
__

vaddr

is the virtual device address
rewound.

(cuu) of

the tape unit

to be

REWIND COMPLETE
This is the normal response.
REWIND NOT PERFORMED
This is
ready.

the response

you receive

if the

real tape

unit is

not

section 8: Format and Usage Rules for CP Commands

311

GC20-1804-3 Page Modified by TNL GN20-2659
SET

SET

Use the
system.

SET command to control various functions within
The for.at of the SET command is:

,---SET

---,

ACNT
MSG
WIG
IMSG
RU I
LINEDit
ECmode
ISAM
NOTRans
PAGE X
EMSG
OFF
ON
CODE
\ TEXT
TIMER

your virtual

Q!
OFF }
{ REAL

ASsist

ISVC
r
,I \
I I NOSVC I

PFnn IIMMed
IQ~1~:I~g
L

,
I [pfdata1tpfdata2t ••• pfdatan]

PFnn [TAB n1 n2 •••

]

PFnn COpy [resid]

ACNT {ON }

controls whether accounting information is displayed at
the terminal or not (ON and OFF respectively)
when the
operator issues the CP ACNT command. When you log on
VM/370, ACNT is set on.

MSG {ON }

controls whether messages sent by the MSG command from
other users are to be received at the terminal. If ON is
specified, the messages are displayed.
OFF specifies
that no messages are received.
When you log on VM/370,
MSG is set on.

OFF

controls whether warning messages are displayed at the
terminal. If ON is specified, all warning messages sent
312

IBM VM/370: Command Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659
SET
via the CP WARNING command from the system operator are
received at the terminal. If OFF is specified, no
warning messages are received. When you log on VM/370,
WNG is set on.

IMSG faN l
tOFF f

controls whether certain informational responses issued
by the CP CHANGE, DEFINE, DETACH, ORDER, PURGE, and
TRANSFER commands are displayed at the terminal or not.
The descriptions
of these CP commands
tell which
responses are
affected.
If
ON is
specified the
informational responses
are displayed.
If OFF
is
specified, they are not. The SET IMSG ON or OFF command
line has no effect on the handling of error messages set
by the SET EMSG command. When you log cn VM/370, IMSG is
set on.

RUN {ON}
OFF

controls whether the virtual machine stops when the
Attention key is pressed. ON allows you to activate the
Attention key (causing a read of a CP command) without
stopping your virtual machine. When the CP command is
entered, it is immediately executed and the virtual
machine resumes execution.
OFF
places the virtual
machine in the normal CP environment, so that when the
Attention key is pressed, the virtual machine stops.
When you log on VM/370, RUN is set off.

LINEDIT {ON }
OFF

controls the line editing functions. ON specifies that
the line editing functions and the symbols of the VM/370
system are to be used to edit virtual CPU console input
requests. This establishes line editing features in
systems that do not normally provide them. OFF specifies
that no character or line editing is to be used for the
virtual machine operating system.
When you log on
VM/370, LINEDIT is set on.

ECMODE

controls whether
the
virtual
machine
operating
system may use system/370 extended control mode and
control registers 1 through 15. Control register zero may
be used with ECMOD! either ON or OFF. When you log on
VM/370, ECMODE is set according to the user's directory
option; ON if ECMODE was specified and OFF if not.

{

~~F }

Note: Execution of the SET ECMODE {ONIOFF} command always
causes a virtual system reset.
IS AM

controls whether
additional
checking
is
performed
on virtual I/O requests to DASD in order to support the
use of the as Indexed Sequential Access Method (ISAM).
When you log on VM/370, ISAM is set according to the
user's directory options; ON if ISAM was specified and
OFF if not.

NOTRANS {ON }
OFF

controls CCW
translation for
CP.
NOTRANS can
be
specified only by a virtual machine that occupies the
virtual=real space. It causes all virtual I/O from the
issuing
virtual
machine
to bypass
the
CP
CCW
translation.
To be in
effect in the virtual=real
section 8: Format and Usage Rules for CP Commands

313

GC20-1804-3 Page Modified by TNL GN20-2659
SET
environ.ent, SET NOTRANS ON must be issued after the
virtual=real machine is loaded via the IPL command.
(IPL
sets the NOTRANS option to an OFF condition.)
controls the
pseudo
page
fault
portion
of
the
VM/VS Handshaking feature. PAGEX ON or OFF should only be
issued for an OS/VS1 virtual machine that has the VM/VS
Handshaking feature active. It can only be specified for
a virtual machine that has the extended control mode
(ECMODE) option.
PAGEX ON sets on the pseudo page fault
portion of handshaking;
PAGEX OFF sets it off. When you
log on to VM/370, PAGEX is set OFF.

PAGEX {ON }
OFF

controls error message handling. OB specifies that both
the error code and text are displayed at the terminal.
TEXT specifies that
only text
is displayed.
CODE
specifies that only the error code be displayed. OFF
specifies that no error message is to be displayed.
When
you log on VM/370, EMSG is set to TEXT.

EMSG {ON
OFF }
CODE
TEXT

Note, CMS recognizes EMSG settings for all error
(E),
information (I), and warning
(W) messages, but ignores
the EMSG setting and displays the comFlete message (error
code and text) for all response (R), severe error (S),
and terminal (T) messages.
controls the virtual
timer. ON specifies
that the
virtual timer is to be updated only when the virtual CPU
is running. OFF specifies that the virtual timer is not
be updated. REAL specifies that the virtual timer is to
be updated during virtual CPU run time and also during
virtual wait time. If the REALTIMER option is specified
in your VM/370 directory entry, TIMER is set to REAL when
you leg on; otherwise it is set to ON when you log on.

TIMER { ON
}
OFF
REAL

ASSIST

r
L

lOB I ISVC I
I
I INOSVCI
J

OFF
controls the availability of the virtual machine assist
feature for your virtual· machine. The assist feature is
available to your virtual machine when you log on if (1)
the real CPU has the feature installed and (2) the system
operator has not turned the feature off. The SVC handling
portion of the assist feature is invoked when you log on
unless your VM/370 directory entry has the SVCOFF option.
Issue the QUERY SET command line to see if the assist
feature is activated and whether the assist feature or
VM/370 is handling SVC interrupts.
All svc 76 requests are passed to CP
regardless of the SVC and BOSVC operands.

for

handling,

If you issue the SET ASSIST command line and specify SVC
or BOSVC while the virtual machine assist feature is
turned off, the appropriate bits are set. Later, if the
feature is turned on again, the operand you specified
while it was off becomes effective.

314

IBM VM/370: Command Language Guide for General Users

GC20-1804-3 Page

~odified

by TRL GR20-2659
SET

OR sets the assist feature on for the virtual machine;
OFF turns it off. SVC specifies that the assist feature
handles all SVC interrupts except SVC 76 for the virtual
machine; ROSVC means V~/370 handles the SVC interrupts.
See the !~LJ1Q: §l§!g! ~!Qg~!!g!~§ g~!g~ for information
on how to use the assist feature.
r

PFnn

II~~ED

I [pfdata1'pfdata2' ••• pfdatan]
IDELAYED I

defines a program function for a program function key on
a 3277 Display station and indicates when that function
is to be executed. See the !~LllQ: I~!!!~gl Us~!~§ ~~!~~
for a description of how to use the 3277 program function
keys.
The value, nn, is a number from 1 Cor 01) to 12 that
corresponds to a key on a 3277. The program function is a
"function", or programming capability, you create by
defining a series of V~/370 commands or data you want
executed. This series of commands executes when you press
the appropriate program function key.
I~~ED
specifes that the program function is executed
immediately after you press the program function key.

DELAYED specifies that execution of the program function
is delayed for a display terminal. When the program
function is entered, it is displayed in the input area
and not executed until you press the Enter key. DELAYED
is the default value for display terminals.
pfdata1'pfdata21 ••• pfdatan defines the V~/370 command or
data lines that constitute the program function. If more
than one command line is to be entered, the pound sign
C') must separate the lines.
If you use the pound sign
(t) to separate commands that you want executed with the
designated PP key, you must precede the command line with
'CP, turn line editing off, or precede each pound sign
with the logical escape character
C"). For further
explanation, see
the "Examples of
Setting Program
Function Keys" section that follows.
If no command lines
are entered, PFnn is a null command. Program functions
cannot be embedded within one another.
PFnn TAB n1 n2
specifies a program function number to be associated with
tab settings on a terminal. The number of the PF key, nn,
can be a value from 1 Cor 01)
to 12. See the VMLllQ:
~~!1 §~!g~ for examples of how this feature is used.
TAB is a keyword identifying the tab setting function.
The tab settings may be entered in any order.
PFnn COPY [resid]
specifies that the program function key, numbered nn,
performs a COpy function for a remote 3270 terminal. nn
must be a value of 1 or 01 to 12. The COpy function
produces a printed output of the entire screen display at
the time the PF key is actuated. The output is printed on
an IB~ 3284,
3286 or 3288 printer connected to the same
control unit as your display terminal.
section 8: Format and Usage Rules for CP Commands

315

GC20-1804-3 Page Modified by TNL GN20-2659
SET
The resid operand may be specified if more than one
printer is connected to the same control unit as your
display terminal. It is a three-character hexadecimal
resource identification number assigned to a specific
printer.
If resid is entered, the printed copy is
directed to a specific printeri if not,
the copy is
printed on the printer with the lowest resid number. The
resid numbers of the printers available to your display
terminal can be obtained from your system operator. If
only one printer is available,
resid need not be
specified.
If the command is invalid or if the designated or default
printer is not free (other display terminals may be using
it) or is not connected to the same control unit as your
display terminal, a NOT ACCEPTED message appears on the
screen, If the printer was busy, retry the operation
until the printer honors your request.
You may include your own identification on the printed
output by entering the data into the user input area of
the
screen before
you
press
the PF
key.
The
identification appears in the lower left of the printed
copy.

This example shows you how the SET PFnn command is processed if you do
not turn line editing off or use the logical escape character.
Enter one of the following commands while in CMS mode:
SET PF02 IMMED Q RDR#Q PTRiQ PUN
or
CP SET PF02 IMMED Q RDRIQ PTR#Q PUN
Now press the ENTER key:
1.

The ENTER key causes immediate execution,

Only the Q PTR and Q PUN commands execute, and

Q PTR and Q PUN are stripped from the PF02 key assignment leaving Q
RDR, which was not executed.

The following examples
problem.

316

demonstrate

two

methods for

IBM VM/370: Command Language Guide for General Users

avoiding

the

GC20-1804-3 Page Modified by TNL GN20-2659
SET

Enter one of the following commands while in CMS mode:
tcp SET PP02 IMMED 0 RDRIO PTRIO PUN

-- or
CP SET PP02 IMMED 0 RDR"tQ PTR"IQ PUN
or
SET PP02 IMMED Q RDR"tQ PTR"tQ PUN
Now press the ENTER key.
CP assigns the three QUERY commands as functions of the
pressing the PP02 key executes the three QUERY commands.

PP02 key.

Enter the following command while in CMS mode:
SET LINEDIT OPP
and press the ENTER key.
Then enter:
SET PP02 IMMED Q RDRIO PTRtQ PUN
or
CP SET PP02 IMMED Q RDRtQ PTRtQ PUN
and press the ENTER key.
CP assigns the three QUERY commands as functions of the PP02 key.
Then enter:
SET LINEDIT ON
and press the ENTER key.
Pressing the PP02 key executes the three QUERY commands.

PPnn UNDEFINED
This response appears in the user area of the screen on
Display Station if a PP key that is undefined is pressed.

Section 8: Format and Usage Rules for CP Commands

a 3277

316.1

GC20-1804-3 Page Modified by TNL GN20-2659
SLEEP

SLEEP

Use the SLEEP command to place the virtual machine in a dormant state
but allow messages to be displayed.
IDe vlr~ual maChlne does not run
during this time, but connection time is still being counted. You can
specify a sleep interval in the command line and the virtual machine is
awakened automatically when the specified interval has elapsed. Awaken
the terminal at anytime by signalling attention. In either case, this
returns the virtual machine to the environment from which SLEEP was
issued.
If no ln~erval is specltled, the virtual machine remains
dormant until awakened by signalling attention. The format of the SLEEP
command is:
r-

I
I
I
i
I

I
ISEC II
I nn I~!1! II
I
IHRs II

SLeep

I ~h~!~:
I r
r
"
I I
ISECII
I Inn 1]!1!11
I I
I HRs II
ILL

I
I
I
I

indicates the actual number of seconds, minutes, or hours of actual
CPU time to sleep. The value nn can be any decimal number from 00
through 99. If you specify no time unit, the value of nn is taken
to be minutes.

If you issue the SLEEP command from a CP read or from a VM read using
the CP "escape" function (ICP SLEEP), the end of the time interval or
signalling attention returns you to the CP environment.
If you issue the SLEEP command while in virtual machine mode (for
example, CMS execution of the command line
CP SLEEP), the end of the
time interval or signalling attention returns your terminal to virtual
machine mode without entering the CP environment.
The SLEEP command, with the time interval, is a convenient way to
delay or schedule the execution of certain jobs that could be run more
efficiently at a later time; for example, second shift.

None.

section 8: Format and Usage Rules for CP commands

317

GC20-1804-3 Page Modified by TNL GN20-2659
SPOOL
SPOOL

Use the SPOOL co.mand to modify the spooling control options in effect
for a given virtual spooling device or for a group of devices. The
SPOOL command can also initialize or stop the spcoling of virtual
console input and output.
You can direct a file to a remote location by using the SPOOL command
in conjunction with the TAG command. The section "Transmitting Files to
Remote Locations" which follows discusses the form cf the SPOOL command
you use to spool files across the Remote Spooling Communications
Subsystem (RSCS).
Unless otherwise
spool files:

set, the following

options are default

values for

~EQQJ: liJ:~

.Q~!i.2.!!'§

Printer
Punch

OFF, NOHOLD, NOCONT, COpy 01,
in the VM/370 directory entry

Console

NOHOLD, NOCONT, TERM, OFF, CLASS T, COPY 01

Reader

NOHOLD, NOCONT, EOF, CLASS
VM/370 directory entry

* as

specified in
CLASS as

the

specified

The format of the SPOOL command is:

r----------------------------------------I

I I

SPool I{Reader}
rllCLass {c* }'II CONt
HOld
EOF
I vaddr
INOContl INOHoldl INOEofl
{
L
.J
L
.J
L
.J
L
.J
I
I
I
I

I{printer}
I PUnch
I vaddr

rr
, r
liTo II userid
IIForl1 *
IL
.J I SYSTEM
I
L
I
I OFP
L

, r

IllHOld I ICONt I
I IINOHoldl INOContl[CLass c] [COpy nn]
IlL
.J L
.J

I
I
I
.J

ICLOSE I
IPURGE I
L

{CONSOle}
vaddr
I
I
I
I
I

,
r
r
r
r
r
ISTArtl IHOld I ICONt I ITErm I I[ To] useridl
ISTOp I INOHoldl INOContl INOTErml I OFF
I
L
L
.J
L
.J
L
.J
L
.J
.J
,
[CLass c] [COpy nn]
r
ICLOSEI
IPURGEI
L
.J

lAt least one of the options within braces must be selected; however,
more than one may be specified, and they may be entered in any order.
~

318

IBM V8/370: Command Language Guide for General Users

SPOOL

READER
RDR

modifies the options for all reader spool files.

PHIlTER
PRT

modifies the options for all printer spool files.

puwell

!!odifies the

fer all

spool deY' ices.

PCB
CONSOLE

modifies the options for the virtual console spool file and/or
initiates or stops the spooling of virtual console input and
output, including CP input/output.

vaddr

is the device address (cuu) of the virtual unit record device
or console whose options are to be modified.

CLASS { c*} specifies the
spool
class
of
the
device.
is a one-character alphameric field whose values
through Z, 1 through 9, or * (asterisk) •

The
can be

Unless your virtual reader class is asterisk (*), you must
ensure that any files to be read by your virtual reader are of
the same spool class as your virtual reader. The * is the
universal class; if your virtual reader is class *, it can
read any file, regardless of class.
COlT

ignores
intermediate
end-of-file
indicators
or
CLOSE
requests. Por virtual readers, reading is continuous with all
end-of-file indicators ignored until all files spooled to the
virtual machine are read in. If this option is not in effect,
a unit exception is reflected to the virtual .achine at the
end of each spooled file. CaNT specified for the punch or
printer causes all CLOSE requests to be ignored until reset by
NOCOIT. If CaNT is specified, NOCONT cannot be specified.
COlT specifies that reading is to continue without intervening
end-of-file indications until all files .in the system that
belong to the user are read. If CaRT is not in effect or is
reset by specification of NOCOIT, an end-of-file indication is
reflected to the virtual machine at the end of each SPOOL file
in the syste.. The nature of the end-of-file indication to be
reflected is set by the EOP and NOEOP options. If the BOP
option is in effect, end-of-file is signaled by a unit
exception:
this corresponds to pressing the end-of-file
button on a real card reader. If NOEOP is in effect for a
virtual reader, end-of-file is signaled by the reflection of a
unit check/intervention required status.

IOCOIT

resets the continuous spooling option. If IOCORT is specified,
COlT cannot be specified.

BOLD

places all files created by the specified device in a user
BOLD status.
Par REIDER files, this option specifies that
input files for the specified reader are not deleted fro. the
system after they are read. The status of all files must be
changed by the CB1RG! co •• and. The status of output devices is
changed by the SPOOL command.
If BOLD is specified, ROBOLD
cannot be specified.
section 8: Pormat and Usage Hules for CP Commands

319

SPOOL
If the HOLD option is specified for a virtual printer or punch
that is transferred to a user for input (TO userid), that
virtual device places a user HOLD status on the reader file.
The user receiving the file cannot read its status until it is
changed by issuing the CHABGE command with the BOHOLD operand.
The spool file class of the virtual output device must match
the class of the receiver's virtual reader (or the virtual
reader aust have a class of *) in order for the spool file to
be processed. If these conditions are not satisfied, the
reader appears eapty to the virtual machine atteapting to read
a file, even though reader files do exist.
If a virtual reader is operating with COBT and HOLD, then
virtual reader files are saved and placed in a user HOLD
status. The file cannot be read until it is changed (using
the CHARG! co •• and) to a BOHOLD status.
BOHOLD

resets the HOLD operand. Future files are not held. BOHOLD
resets the HOLD operand in effect for the specified reader.
This operand can be overridden for an active file being closed
by the CLOSE command using the HOLD or ROHOLD operand. If
BOHOLD is specified, HOLD aay not be specified.

EOP

sets a virtual end-of-file condition on the specified reader,
thereby ensuring that a unit exception condition is reflected
on the read that follows the reading of the last card in a
file. If EOP is specified, BOEOFmay not be specified.

BOEOP

specifies that the reading continues to physical end-of-file.
The virtual reader stops when no cards are left in the reader
and when
a unit check/intervention required
status is
pending. If BOEOP is specified EOF may not be specified.

[TO] userid

*
SYSTEft
transfers the output of
reader of the specified
may not be TO or T. TO
transferred to your own
specified, neither OFF
co •• and line.

the virtual device to the virtual card
userid. If TO is omitted, the userid
* may be coded if the output is to be
virtual card reader. If TO userid is
nor FOR may be specified on the same

If you specify COpy with TO userid, the number of copies you
specify has no effect on the receiver of the spool file; he
receives only one copy. However, if OFF or FOR are specified
on a subsequent command, the receiver of your spool file
receives the number of copies you specify via COPY. For
example, if the following command is entered:
SPOOL PUB TO USERA COPY 3 CLASS B
the COpy operand has no
However, if the command:

effect on

the file going

to USERA.

SPOOL PUN OPP
is entered following the first co.mand, the COpy 3 specified
in the first statement effects the second co.mand.
TO SYSTE! is equivalent
transferred spool option.

320

to specifying

OFP

IBft Vft/370: Command Language Guide for General Users

and resets

the

GC20-1804-3 Page Modified by TNL GN20-2659
SPOOL
[FOR] userid
indicates the use rid under which printed or punched output is
produced. The userid becomes the owner of the output spool
file and the distcode on the file is the distcode for the user
that is specified in the VM/370 directory. The file is not
transferred to the user's reader input. The default setting is
for your own virtual machine identification. FOR *, or FOR
SYSTEM can be coded to specifv your own identification and is
equivalent to the OFF option.OPF

resets the transferred spool option.

COpy nn

is the number of copies that are to be printed or punched when
the file is spooled to the real unit record equipment. This
operand is valid only for output files; the number of copies,
nn must be between 1 and 99
(leading zeros need not be
specified).

closes the specified device regardless of the CONT setting for
the device.
If
CLOSE is specified, PURGE
may not be
specified. CLOSE does not affect the setting of any other
operand and is provided as a convenience to close a virtual
output device. As an example, this sequence of commands:
SPOOL PRT CORT
(print file)
(print file)
(print file)
SPOOL PRT ROCONT
CLOSE PRT
SPOOL PRT CORT
(print file)
(print file)

can be replaced with
desired result:

the following

sequence to

achieve the

SPOOL PRT CORT
(print file)
(print file)
(print file)
SPOOL PRT CLOSE
(print file)
(print file)

I PURGE

closes and purges the spool file fro. the specified virtual
output device regardless of the CONT setting for the device.
If PURGE is specified, CLOSE cannot be specified. PURGE does
not affect the setting of any other operand and is equivalent
to issuing the CLOSE command for a device (or type of device)
with the PURGE operand. This form of the SPOOL command is
provided for your convenience.

START

places all console input and output in a spool file. Until a
CLOSE is issued for the console, characteristics of the
console spool file may be changed by use of the SPOOL CONSOLE
command.
After the console is closed, the file becomes a
Section 8: Format and Usage Rules for CP Commands

321

GC20-1804-3 Page Modified by TNL GN20-2659
SPOOL
printer spool file whose characteristics can
issuing the CHllGE PRIITER com.and.

be changed

STOP

terminates the spooling of console input and output.
The
co.mand SPOOL COISOLE STOP does not close the console spool
file.

TERM

displays the virtual console input and output at the terminal
in addition to placing it in a spool file.
The TERM operand
has no effect until the START operand is specified.

NO TERM

suppresses the display of console input and output of a system
running in a virtual machine. The display cf console input and
output of CP console functions, entered from CP mode, are not
suppressed. The NOTERM operand has no effect until the START
operand is specified.

Once you close a spool file by issuing the CMS PRINT or PUNCH command or
the CP CLOSE co.mand, CP assigns the spool file a number between 1 and
9900. This number is called the spoolid (spool file identification) for
the file. It can be used as a convenient way to uniquely identify the
file. It can also be used when you are manipulating the file with VM/370
spooling commands such as ORDER, CHANGE or CLOSE.
spoolids are assigned to all your spool files sequentially. ihen the
maximum number (9900) is assigned, CP begins again with the number 1.
When you print or punch a file, CP displays at your terminal the
spoolid it assigned to your file. You can find out various kinds of
information about a file using the spoolid with the many forms of the
QUERY command.

To direct files to remote stations, use the CP TAG and SPOOL commands in
conjunction with a command that causes the file to be closed and sent to
a virtual device (for example, a virtual printer or punch). Use the TAG
command to specify the device to be spooled and to associate with that
device the location identifier for the destinaticn of the file:
TAG DEV device locid
where device is the virtual device type (for example, PRINTER or PUNCH)
or virtual device address
(vaddr)
and locid is the name of the
destination to which the file is to be transmitted.
Use the SPOOL command to specify that output to the device specified
in the command is to be sent to the RSCS virtual machine, which perfcrms
the actual transmission of the file:
SPOOL device TO userid
where device is the same virtual device type or virtual device address
specified in the TAG command and userid is the userid of the RSCS
virtual machine at your installation.
You can find out the userid of
your installation's RSCS virtual machine and the locid for the various
remote stations from your installations's system programmer.
322

IBM VM/370: Command Language Guide for General Users

SPOOL

After you issue the TAG and SPOOL commands, use a command
(such as
the C~S PRINT or PUICH command or the CP CLOSE command) to cause the
spool file to be generated, closed, and spooled to the specified virtual
~on;~~

y~.~~~.

The following example shows how to use
transmit a C~S file to a remote location:
TAG DEV PUNCH

these

three commands

CA~BRIDG

SPOOL PUICH TO NET
PUNCH

~YPROG

ASSE~BLE

The TAG command defines the type of file to be transmitted, a punch
file, and the remote station to which you want it transmitted,
Cl~BRIDG.
NET is the userid of the virtual machine controlling the RSCS
network: you direct your file to that virtual machine with the SPOOL
command.
The PUICH command causes the file ~YPROG ASSE~BLE to be
punched on your virtual machine card punch, closed, and then spooled to
the virtual reader of the RSCS virtual machine, which you specified in
the SPOOL command. The RSCS virtual machine then processes your file
(now a V~/370 spool file) and transmits it across the RSCS network.

If your virtual machine is logged on V~/370, RSCS notifies you of the
arrival of a file for your machine from the RSCS network by displaying a
aessage at your terminal. The file is sent to your virtual card reader.
V~/370 can accumulate
files from the RSCS network destined for your
virtual card reader, regardless of whether you are logged on your
virtual machine or not.
If you are logged on your virtual machine,
issue the QUERY command to see if you have any files in your virtual
reader.
When you log on your virtual machine, the logon process
transmits a message informing you of accumulated spool files residing in
your virtual reader (punch or printer) •

lone.

section 8: Pormat and Usage Rules for CP Commands

323

STORE
STORE

Use the STORE co •• and to alter the contents of specified registers and
locations of the virtual aachine. The contents of the following can be
altered:
•
•
•
•
•

virtual storage locations
General registers
Ploating-point registers
Control registers (if available)
Prograa status word
The STORE command can also save virtual machine data in low storage.

The operands aay be combined in any order desired, separated by one
or more blanks, for up to one full line of input. If an invalid operand
is encountered, an error message is issued and the store function is
ter.minated. However, all valid operands entered, before the invalid
one, are processed properly.
storage locations, registers, the PSi, and status can be stored using
a single command line. ihen you combine the operands for storing into
storage, registers, the PSi, or the status area on a single command
line, all operands must be specified; default values do not apply in
this case.
The format of the STORE command is:

STore

hexloc
Lhexloc

hexwordl [hexword2 ••• ]

Shexloc

hexdata •••

Greg}
{ Yreg
Ireg
Psw

hexwordl [hexword2 ••• ]
[bexwordl] hexword2

STATUS

hexloc
Lhexloc

hexwordl [hexword2 ••• ]
stores the
specified data
(hexword 1 [hexword2 ••• ])
in
successive full word
locations starting
at the
address
specified by hexloc. The smallest group of hexadecimal values
that can be stored using this form is one fullword. Alignment
is made to the nearest fullword boundary. Either for. (hexloc
or Lhexloc) can be used.
The operands (bexwordl hexword2 ••• ) each represent up to eight
hexadecimal digits. If the value being stored is less than a
fullword (eight hexadecimal digits) , it is right-adjusted in

324

IB~

V~/310:

Command Language Guide for General Users

STORE
the word and the high order bytes of the word are filled with
zeros. If two or more hexwords are specified, they must be
separated by one or more blanks.
Shexloc hexdata •••
stores the
data specified (hexdata ••• ) in
the address
specified by hexloc, without word alignment. The shortest
string that can be stored is one byte (two hexadecimal
digits). If the string contains an odd number of characters,
the last character is not stored, an error message is sent,
and the function is terminated.
The operand, hexdata, is a string of two
digits with no embedded blanks.

or more hexadecimal

Greg hexwordl [hexword2 ••• ]
stores the hexadecimal data
(hexword1 [hexword2 ••• ]) in
successive general
registers starting
at the
register
specified by reg. The reg operand must be either a decimal
number from 0-15 or a hexadecimal digit from O-F.
The operands (hexword1 [hexword2 ••• ]) each represent up to
eight hexadeciaal digits. If less than eight digits are
specified, the string is right justified in a fullword and
left-filled with zeros. If two or more hexwords are specified,
they must be separated by one or more blanks.
Yreg hexwordl [hexword2 ••• ]
stores the hexadecimal data
(hexwordl [hexword2 ••• ]) in
successive floating-point registers starting at the register
specified by reg.
The reg operand must be a digit from 0-6.
If reg is an odd number, it is adjusted to the preceding even
number.
The operands (hexword1 [hexword2 ••• ] each represent up to
eight hexadeciaal digits. If less than eight digits are
specified, the string is right justified in a fullword and
left-filled with zeros. If two or more hexwords are specified,
they must be separated by one or more blanks.
Xreg hexwordl [hexword2 ••• ]
stores the hexadecimal data
(hexword1 [hexword2 ••• ]) in
successive control
registers starting
at the
register
specified by reg. The reg operand must either be a decimal
number froa 0-15 or a hexadecimal digit from O-F. If the
virtual machine is in basic control mode, you can store dOata
in register 0 only.
The operands (hexwordl [hexword2 ••• ]) each represent up to
eight hexadeciaal digits. If less than eight digits are
specified, the string is right justified in a fullword and
left-filled with zeros. If two or more hexwords are specified,
they must be separated by one or more blanks.
PSi [hexwordl] hexword2
stores the hexadecimal data ([hexwordl] hexword2) in the first
and second words of the virtual machine's program status word
(PSW). If only hexword2 is specified, it is stored into the
second word of the PSi.
The operands hexwordl and hexword2
must be separated by one or more blanks. They represent up to
eight hexadecimal digits. If less than eight digits are
specified, the string is right justified and left-filled with
zeros.

section 8: Format and Usage Rules for CP Commands

325

STORE
STATUS

stores selected virtual aachine data in certain low storage
locations of the virtual machine, simulating the hardware
store status
facility. These locations
are per.anently
assigned locations in real storage.
To use the STATUS
operand, your virtual aachine aust be in the EItended control
ftode. The STATUS operand should not be issued for CftS virtual
aachines or for DOS virtual aachines generated for a CPU
saaller than a Systea/360 Bodel 40. The STATUS operand stores
the following data in low storage:
Deciaal
Address

-216--224
256
352
384
448

HeIadeciaal
199~§§§

D8
EO
100
160
180
1CO

___

Length
in Byt§.!
8
8
8

32
64
64

Data
CPUTiaer
Clock Coaparator
Current PSi
Floating-point registers 0-6
General registers 0-15
Control registers 0-15

STORE COftPLET!

326

IBft V8/370: Co •• and Language Guide for General Users

SISTE!
SYSTEM

Use the SISTE! command to simulate the action of the RESET and RESTART
buttons on the real computer console, and to clear storage. The RESET
function and the CLEAR function leave the virtual machine in a stopped
state. An IPL command must be issued after a SISTB! CLBAR command.
After a SISTE! RESTART, the virtual machine is automatically restarted
at the location loaded into the PSi from the doubleword at virtual
location zero. The format of the SISTE! command is:
r

SIStem

CLEAR }
RBSBT
{ RBSTART

CLEAR

clears
zeros.

virtual storage

and virtual

RESET

clears all
machine.

RESTART

simulates the hardware system RESTART function by storing the
current PSi at virtual location eight and loading, as the new
PSi, the doubleword from virtual location zero.
Interrupt
conditions and storage remain unaffected.

pending interrupts and

storage

keys to

conditions in

binary

the virtual

STORAGE CLEARED - SYSTEn RESET
This response is given if the co.mand SISTE! CLEAR is entered.
SISTB! RESET
This response is given if the command SISTB! RBSBT is entered.
If the command SISTB! RBSTART is entered, no response is given; the
virtual machine resumes execution at the address in the virtual PSi
loaded from virtual storage location zero.

Section 8: Pormat and Usage Rules for CP Commands

327

TAG
TAG

Use the TAG co •• and to associate infor.ation with a V8/370 spool file,
usually for use with a subsystem such as RSCS or a user-written
subsystea. The foraat of the TAG coaaand is:

TAG
DBV

rrinter}

PILB

PUnch
COlsole
vaddr

[text]

spoolid

[text]

DEV
QU!RY
PILE

DEY

\Printer}
PUnch
CONsole
vaddr

spoolid

PRIITBR [text]
PBT
PUNCH
PCH
COISOLE
vaddr
associates inforaation (via the text operand described further
on) with your virtual printer, punch, or console, or with the
device specified by vaddr.

PIL! spoolid [text]
replaces inforaation previously associated with the file via
the text operand with the current text (described further on).
This operand can be specified only for reader spool files
queued on your virtual machine.
The spoolid operand is the spool file identification, a number
between 1 and 9900 assigned by CP when the spool file was
closed.
text

defines a field (up to 136 characters long) that can contain
any inforaation you desire. Typically, this field contains
meaningful parameters you w~nt to associate with a spool file.
The field of data specified in the TAG text operand is made
available to virtual machines using the spool file, but is in
no way modified or interpreted by V8/370.
Certain control and addressing information meaningful to RSCS
can be specified in this field. Por details on how to use the
TAG text operand to transmit files across the RSCS network,
refer to the following section, "Using the TAG Text Operand to
Transait Piles to Bemote Locations."

328

IB8 V8/370: Co •• and Language Guide for General Users

I
\
(~ig::u))(

{

TAG

( PRIIITl!R

) DEV

QUERY

vaddr

(

FILE

spoolid

displays at your terminal the current setting of the TAG text
associated with a given spool file or virtual device. The
operands used with the TAG QUERY command correspond to the
operands used with TAG itself. Por example, you create a text
setting by issuing the com.and:
TAG DEV PUNCH text
To find out the setting of that text field, issue the co •• and:
TAG QUERY DEY PUNCH
If you know the spoolid of a file queued to your virtual
machine reader and you wish to know the text setting for that
file, use the co •• and:
TAG QUERY PILE spoolid
spool identification (spoolid) numbers can be obtained using
the CP QUERY command with the RIADER, PRIITER or PUNCH
operand.

The RSCS control program interprets the TAG text operand as addressing
and control para.eters. If you are spooling a file to the RSCS virtual
machine to be transmitted to a remote station, code the TAG text operand
as follows:
locid [userid] [priority]
wh~:

locid

is the location identifier (one to eight alphameric digits) of
the location to which the file is being transmitted. Your
system programmer can give you the locids of re.ote stations
attached to your virtual aachine.

use rid

is the userid of the V8/370 virtual machine (a one- to
eight-character user identification) to which a file is being
transmitted. This operand is used by re.ote stations when they
transmit files to the RSCS virtual aachine and want the files
sent to a particular V8/370 virtual aachine. You can ignore
this operand if you are not specifying a priority. However, if
you are specifying a priority, you aust code a userid operand,
even though it is ignored by RSCS.

priority

is the requested transaission priority, a deci.al nu.ber
between 0 and 99. The highest trans.ission priority is 0, next
highest is 1, and so on. If you wish to specify this operand,
you .ust also specify a userid operand.

Section 8: Por.at and Usage Rules for CP Co.aands

329

TAG

When a spool file you created is closed, it is enqueued on a virtual
aachine reader of the virtual machine you specified in the SPOOL
co •• and. You cannot change the TAG information associated with that
file unless the operator of the virtual machine to which the file was
spooled (the BSCS operator) transfers the file back to your virtual
machine.
To change the TAG information associated
reader, you can issue the TAG co •• and
specified:

with a file in your virtual
with the spoolid operand

TAG PILE spoolid new text information
This co.mand causes previous TAG text
replaced by the new text specified.

information

to be

When you enter the command with no new text specified:
TAG PILE spoolid
the text field associated with the file is set to all blanks.

330

IB! Y!/370: Com.and Language Guide for General Users

completely

TEBftIRAL
TERMINAL

Use the TERftIRAL coaaand to control the
with your virtual console:
•
•
•
•
•
•

following functions associated

Logical line-editing symbols
ftasking of password
The APL character set
signalling of an attention interrupt
Attention handling aode for your virtual console
Line length for output on your virtual console

The terainal settings you specify with the TERftINAL coa.and are in
effect for only the duration of that terainal session. Whenever you log
on, the systea defaults are in effect.
However, the settings you
specify for line-editing and ftODE are still in effect when you log on
after disconnecting. All the other operands (ftASK, APL, ATTN, and
LIIESIZE) are reset if you log on after disconnecting.
Although you can define line-editing syabols and status with the
TERftIBAL coaaand, the LIIEDIT operand of the SET coaaand deteraines
whether the Y8/370 line-editing functions are on or off.
If an error occurs during processing of the coaaand, all functions
preceding the one with the error are in effect. The foraat of the
TERftIIAL co.aand is:

TERftinal

CHardel
LIIEDel
LIIEld
EScape
tlask
APL
ATtn

{Ol
OFf }

tlODE

{~:

LIIESize
I

r1
l

OFF
char

}

nnn

tlore than one function can be specified in a single entry of the
TERtlIIAL coaaand. For exaaple:
TERtlIIAL CHARDEL OFF tlASK 01 LIIESIZE 90

.!J!Y!:
CHARDEL { 01 } defines the logical character delete syabol. If 01 is
OFF
is specified, the default syabol becoaes the logical
char character delete sy.bol. The default sy.bol is noraally
i, but depends on what is specified in your 'tl/370
directory entry.
If OFF
is specified, no logical
character delete syabol is allowed. If char is specified,
that character (which must be a special character)
becoaes the logical character delete sy.bol.
Unless
otherwise specified, CHAR DEL 01 is in effect.

section 8: Foraat and Usage Rules for CP Com.ands

331

GC20-1804-3 Page Modified by TNL GN20-2659
TERMINAL
LINEDEL

ON } defines t he logical
line delete symbol. If
ON is
OFF
specified, the default symbol becomes the logical line
{ char delete symbol.
The default symbol is nor.ally ¢, but
depends on what is specified in your VM/370 directory
entry.
If OFF is specified, no logical line delete
symbol is allowed. If char is specified, that character
(which must be a special character) becomes the logical
line delete symbol. Unless otherwise specified, LINEDEL
ON is in effect.

LINEND {ON
}
OFF
char

defines the
logical line
end
symbol.
If ON
is
specified, the default symbol becomes the logical line
end sy.bol.
The default symbol is normally I, but
depends on what is specified in your VM/370 directory
entry. If OFF is specified, no logical line end symbol
is allowed. If char is specified, that character (which
must be a special character) becomes the logical line end
character. Unless otherwise specified, LINEND ON is in
effect.

ESCAPE {ON
}
OFF
char

defines the logical escape character. If ON is specified,
the default symbol becomes the logical escape character.
The default symbol is normally", but depends on what is
specified in your VM/370 directory entry.
If OFF is
specified, no logical escape character is allowed. If
char is specified, that character
(which must be a
special character) becomes the logical escape character.
Unless otherwise specified, ESCAPE ON is in effect.

MASK {ON }
OFF

controls the typing of a mask line at a typewriter
terminal that is not equipped with the Print Inhibit
feature, when a password is to be entered. If MASK ON is
specified, VM/370 types the mask line. If MASK OFF is
specified, the mask line is not typed and it is up to
each user to preserve the security of his password. The
MASK operand does not apply to the IBM 3215 or to similar
system console or display terminals that do not have a
Print Inhibit feature. Unless otherwise specified, MASK
OFF is in effect.

APL {ON }
OFF

controls the use of APL character translation tables.
If APL ON is specified, CP uses the translation tables
for terminals equipped with the standard APL typing
element. If APL OFF is specified, CP uses the normal
translation tables
(that is,
BCD or correspondence
code).
If APL ON is specified, the LINESIZE value is
overridden. Unless otherwise specified, APL OFF is in
effect.
This operand cannot be changed for a 3704/3705 device in
NCP mode. If however, the terminal is connected to a
2701/2702/2703 line control unit, the operand is valid.
3704/3705 users cannot use this option in NCP mode.
The APL operand is not valid for display type terminals.
!g!~:

APL ON also applies to the 3767 terminal equipped
with the APL alternate character selection.

332

IBM VM/370: Co •• and Language Guide for General Users

GC20-1804-3 Page Modified by TBL GN20-2659
TBRMINAL
ATTN ~ ~!~J
t

U1' l' )

controls signalling of an attention interrupt. If ATTB
ON is specified, the exclamation poin~ ~s a~splayed when
an an
attention interrupt occurs. The
OFF option
suppresses the displaying of the exclamation point (I)
and carrier return for those systems that perform special
line editing using the Attention key.
Unless otherwise
specified, ATTB OB is in effect.
The ATTN
terminals.

operand

not

valid

for

display

type

MODE

controls the terminal attention environment. CP specifies
that one or more attentions force the virtual machine
into the CP environment. VM specifies that one attention
is reflected to your virtual machine and that more than
one attention forces your virtual machine into the CP
environment.
VM is the default for all VM/370 users
except the primary system operator.
For more information
see "Interrupting the Bxecution of a Command" in section
2.

LINESIZE nnn

specifies the maximum allowable line length for terminal
output. nnn can be a number from 1 through 255.
Note: If APL ON is specified, CP does not separate output
lines into LIBESIZE segments. Instead, an output length
of 1760 is allowed and CP assumes that the APL system has
inserted the appropriate carriage control characters.

Bone.

section 8: Format and Usage Rules for CP Commands

333

TRACE
TRACE

Use the TRACE command to trace specified virtual machine activity and to
record the results at the terminal, on a virtual spooled printer, or on
both ter.inal and printer. If trace output is being recorded at the
terminal, the virtual machine stops execution and CP co •• and .ode is
entered after each output .essage. This si.ulates the single cycle
function. To resume operation at the virtual machine, the BEGIN co •• and
aust be entered. If the RUN operand is specified, the virtual aachine is
not stopped after each output message.
If trace output is being
recorded on a virtual spooled printer, a CLOSE com.and aust be issued to
that printer in order for the trace output to be printed. Successful
branches to
the next
sequential instruction
and branch-to-self
instructions are not detected by TRACE. Instructions that modify or
examine the first two bytes of the next sequential instruction cause
erroneous processing for BRANCH and INSTRUCT tracing.
When tracing on a virtual machine with only one printer, the trace
data is inter.ixed with other data sent to the virtual printer. To
separate trace information from other data, define another printer with
a lower virtual address than the previously defined printer. lor
example, on a system with OOE defined as the only printer, define a
second printer as OOB. The regular output goes to OOE and the trace
output goes to OOB.
When operation of a
options cannot be used:

traced, the

following

I/O operations for virtual channel-to-channel adapters, with
connected to the same virtual .achine, cannot be traced.

both ends

•
•
•

shared system

is being

BRANCH
INSTRUCT
ALL

The format of the TRACE command is:

TRace

1 I Printer
SVC
I/O
I r
PROgram
I l~l!ll1inall
EXTernal
I IBOTH
I
.J
PRIV
I L
SIO
I
CCW
I Olf
L
BRanch
INSTruct
ALL
CSW

I NORu!!I
I RUN I

I
I
I
I
I
I
I
.J

END
180re than one of these activities may be traced by using a single
TRACE command. lor example:
TRACE SVC PROGRAft SIO PRINTER

334

IB! V8/370: Com.and Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659
TRACE

SVC

traces virtual machine SVC interrupts.

IIO

traces virtual machine IIO interrupts.

PROGRAM

traces virtual machine program interrupts.

EXTERNAL

traces virtual machine external interrupts.

PRIV

traces all virtual machine non-I/O privileged instructions.

SIO

traces TIO, CLRIO, HIO, HDV and TCH instructions to all
virtual devices9
Will also trace SIO and SIOF instructions
for non-console and non-spool devices only.

CCW

traces virtual and real CCWs for non-Spool/non-Console device
IIO operations. When CCW tracing is requested, SIO and TIO
instructions are also traced.

BRANCH

traces all virtual machine interrupts, all
and all successful branches.

INSTRUCT

traces all instructions,
successful branches.

ALL

traces all instructions, interrupts, successful branches,
privilege instructions, and virtual machine IIO operations.

CSW

provides contents of virtual and
IIO interrupt.

END

terminates
message.

PRINTER
PRT

directs tracing output to a virtual spooled printer.

!~~~!~A1

directs tracing
console) •

BOTH

directs tracing output
the terainal.

OFF

halts tracing of the specified
and terminal.

all

tracing

output

virtual

machine

interrupts

and

real channel status words at

activity and

PSW instructions,

the

prints

terminal

to both a virtual

termination

(virtual

machine

spooled printer and

activities on both the printer

stops program execution after the trace output to the terminal
and enters CP command mode.
Note: If a Diagnose code X'008' is being traced, NORUN has no
effect and prograa execution does not stop.
RUN

continues the program execution after the trace output to the
terminal has completed and does not enter CP command mode.

Notes:
-':--If your virtual machine has the virtual=real option and NOTRANS set
on, CP forces CCW translation while tracing either SIO or CCW. When
tracing is terminated with the TRACE END command, CCW translation
is bypassed again.
2.

If the virtual machine assist feature is enabled on your virtual
machine, CP turns it off while tracing SVC and program interrupts
Section 8: Format and Usage Rules for CP Commands

335

GC20-1804-3 Page Modified by TNL GN20-2659
TRICE
(SVC, PBIV, BRINCH, INSTRUCT, or ILL). Ifter the tracing is
terminated with the TRACE END command line, CP turns the assist
feature on again.

The following symbols are used in the responses received from TRACE:
~~!~Q!

vvvvvv
tttttt
rrrrrr
xxxxxxxx
yyyyyyyy
ss
ns

zz
zzzzzzzz
type
V vadd
R radd
mnem
int
code
CC n
IDIL

***
==)

~~!B!B9

virtual storage address
virtual transfer address or new PSW address
real storage address
virtual instruction, channel command word, CSW status
real instruction, CCW
argument byte (SSM-byte) for SSM instruction
new system mask after execution of STOSM/STNSM
low order byte of R1 register in an execute instruction
(not shown if R1 register is register 0)
referenced data
virtual device name (DISD, TAPE, LINE, CONS, RDR,
PRT, PUB, GRIP, DEV)
virtual device address
real device address
.nemonic for instruction
interrupt type (SVC, PROG, EXT, I/O)
interrupt code number (in hexadecimal)
condition-code number (0, 1, 2, or 3)
Indirect data address list
virtual machine interrupt
privileged operations
transfer of control

TRICE STIR TED
This response is issued when tracing is initiated.
TRACE ENDED
This response is issued when tracing is suspended.

I/O vvvvvv TCH xxxxxxxx type vadd CC n

I/O vvvvvv mnem xxxxxxxx type vadd CC n type radd CSW

XXXX

I/O vvvvvv mnem xxxxxxxx type vadd CC n type radd CSW xxxx CAW vvvvvvvv

CCW vvvvvv xxxxxxxx xxxxxxxx rrrrrr yyyyyyyy yyyyyyyy
CCW IDAL vvvvvvvv vvvvvvvv IDAL OOrrrrrr OOrrrrrr
CCW SEEK xxxxxxxx xxxxxx
SEEK yyyyyyyy yyyy
336

IBM VM/370: Command Language Guide for General Users

TRICB
The IDAL or SEEK line is included only if applicable. The virtual IDIL
is not printed if the real CCI opcode does not match the real CCI.
I!~lBQ£!!ON l~!£I!§:

f!:iv!legeg l!l§!.!:!!ct!gn:

··....
·..
··....
· ....
··..
·..

vvvvvv
vvvvvv
vvvvvv
vvvvvv
vvvvvv
vvvvvv
vvvvvv
vvvvvv
vvvvvv

SS!
SS!
STOS!
STOS!
STIS!
STBS!
LPSW
LPSI
ane.

xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx

ss
ss
ns
ns
ns
ns

(normal SSII)
(switch to/fro. translate mode)
(normal STOS!)
tttttt
(switch to translate mode)
(normal STIS!)
tttttt
(switch from translate mode)
tttttttt tttttttt
(lilT bit on)
(lilT bit not on)
==> tttttttt tttttttt
(all others)
tttttt

vvvvvv EI xxxxxxxx zz vvvvvv mne. xxxx xxxxxxxx
Por an executed instruction, where zz (see preceding explanation of
symbols) is nonzero, the mnemonic for the executed instruction is given
as if the zz byte had been put into the instruction with an OR
operation.

vvvvvv mnem xxxxxxxx xxxx

vvvvvv anea xxxxxxxx ==> tttttt

***

vvvvvv int code ==> tttttt

I/O IBTlliRURI (Pirst line given only if "CSI" was specified):
CSI V vadd xxxxxxxx xxxxxxxx R radd yyyyyyyy yyyyyyyy
*** vvvvvv I/O vadd ==> tttttt CSI xxxx
BR1BCH

TR1C~:

(ILL option selected)

Bntry for 'branch from' instruction
vvvvvv mne. xxxxxxxx

tttttt

Bntry for 'branch to' instruction

==> vvvvvv mnem xxxxxxxxxxxx

Section 8: Por.at and Usage Rules for CP Commands

337

TRANSFER
TRANSFER

Use the TRANSFER comaand to direct your input file to a specified reader
or to reclaim virtual reader files that you spooled to another user.
The TRANSFER coaaand does not transfer any active spool files.
The
format of the TRABSFER command is:
r

TRANsfer

SPOOlid}
CLass c
{ ALL

ITo userid
I
Ir
, I
II Froll { USerid} II
II
ALL
II
IL
~ I
L

spoolid

is the input file to be directed to
the nailed userid.

or retrieved froll

CLASS c

transfers all input files of the specified class (c).
The c is a one-character alphameric field with values
from A to Z and from 0 to 9.

ALL

transfers all input spool files.

[TO] userid

is the user to whom the files are to be directed. If
the optional keyword TO is ollitted, the userid aay not
be TO or T. The file is deleted from your reader if you
use this option.

[ FROB] {userid}
ALL

is the user from whom input spool files are to be
reclaimed. ALL aay be specified to reclaim input spool
files that were originated by your virtual machine froll
all users.

!!~~on~§

RDi FILE spoolid TRAN SFERRED {TO } use rid
PROB
.!he£!:
spoolid

is the spool file identification nuaber of the file
that is spooled. The number does not change.

TO userid

is the response to the user who currently owns the
file and userid is the recipient of the file.

FROB userid

is the response to the user who receives
transferred file and userid is the sender.

the

{ ~~nn} FILES TRANSFERRED
This is the response you receive when you issue the
command. It is not displayed if you issued the CP SET
command line.
338

IBB VB/310: COllmand Language Guide for General Users

TRABSPER
IBSG OPP

Appendixes

A. punctions of Yft/370 COllmands
B. Debugging a problea program with Yft/370
C. Using the CftS Batch Pacility
D. CftS ftacro Instructions
E. Disk Deteraination
P. Reserved Piletype Descriptions

Appendixes

339

GC20-1804-3 Page Modified by TNL GN20-2659

Figures
36 through
44 present a functional summary of commands available
'L._
___ .. __
..: _

.L.

~u~

1rM

~~..,n

Yn/~'v

~1~~~W.

r-----I
I
Function

Command

I
I Subcommand I
I
or
,
I option IType I

----I--

Begin terminal session (identify
user to VM/370 system) •

LOGON

End terminal session.

LOGOFF

Communicate with other VM/370 users
and with the system operator.

MESSAGE

Connect a terminal to a multi-access
virtual machine.

DIAL

Disconnect a user's terminal from a
virtual machine.

DISCONN

Test terminal hardware.

ECHO

Start or stop console spooling.

SPOOL

Control terminal input and output.
• Indicate if accounting data is to be
SET
received at the terminal.
• Indicate if messages from other users
SET
are to be received at the terminal.
SET
• Control output of certain informational SET
responses.
• Control line editing functions.
SET
• Control format of messages received at
SET
the terminal.
SET
• Set up program function key cataloged
SET
procedures.
• Print the current screen display on thel SET
printer (remote display units only) •
,
• Get information about terminal control , QUERY
parameters.
I QUERY
, QUERY
• Set attention handling mode.
, TERMINAL
• Specify method of password entry.
I TERMINAL
• Specify use of additional translation I TERMINAL
tables.
I
• Specify terminal line size.
, TERMINAL
• Specify ATTN key handling procedures. ,TERMINAL
• Specify that ATTN key will not stop the, SET
virtual machine.
I
• Specify characters to indicate CPU
,SET
time interval reporting.
I
• Specify format of CMS READY message.
,SET
• Indicate character translations to be I SET
done during terminal input and output. , SET
L-_ _ _ _ __
Figure 36.

I CP

I
I
I CP

,
,

I CP

CONSOLE

ACNT

MSG
WNG
IMSG

CP
CP
CP

LINEDIT
RED TYPE
EMSG
PFnn

CP
CMS
CP
CP

PFnn COpy

APL

CP
CP
CP
CP
CMS
CP
CP
CP

LINESIZE
ATTN
RUN

CP
CP
CP

BLIP

CMS

RDYMSG
INPUT
OUTPUT

CMS
CMS
CMS

TERMINAL
PFnn
REDTYPE
MODE
IUSK

Commands to control a Terminal Session
Appendix A: Functions of VM/370 Commands

341

Function

Co •• and

Subcom.andl
or
I
Option
Type

Change attributes of a spooled file.

CHAIGE

Create a source progra. file from the
terminal.

EDIT

CMS

Invoke the System Assembler to assemble
a source program.

ASSEMBLE

CMS

Invoke the VS BASIC Compiler.

VSBASIC

CMS

Invoke the PL/I optimizing Compiler.

PLIOPT

CMS

Invoke the PL/I Checkout Compiler.

PLIC

CMS

Invoke the PL/I Checkout Compiler and
Execute a Program.

PLICR

CMS

Invoke the FORTRAN Code and Go Compiler.

TESTFORT

CMS

Invoke the FORTRAN G Compiler.

FORTGI

CMS

Invoke the FORTRAN H Complier.

FORTHI

CMS

Create or list macro libraries to be used
during assemblies or compilations.

MACLIB

CMS

Create or list subroutine libraries.

TITLIB

CMS

specify macro libraries to be searched
during assemblies or compliations.

GLOBAL

MACLIB

CMS

Specify subroutine libraries to be
searched during LOAD and INCLUDE
function.

GLOBAL

TITLIB

CMS

Bring object code into main storage.

LOAD
INCLUDE

CMS
CMS

Create a MODULE (core-image) file.

GENMOD

CMS

Bring MODULE files into storage.

LOAD MOD

CMS

Print a storage map of a MODULE file.

MOD MAP

CMS

Build auxiliary

GENDIRT

CMS

START

CMS

module directories.

Begin execution of programs which were
previously loaded into main storage.
L-

Figure 37.

342

Commands to Develop Programs and Process Data (Part 1 of 2)

IBM VM/370: Command Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659

Function

Command

simulate os Data Definition (DO) JCL
cards during program execution.

FILEDEF

1Subcommand 1
1
or
1
I Option IType I

----1--1 CMS
1

List information about os data sets or
DOS files.

LISTDS

Load and execute object (TEXT) files.

RUN

eMS

Compile, load, and execute source files.

RUN

CMS

Load and execute core-image (MODULE)

RUN

CMS

I CMS

files.
L-_____________________________
___
Figure 37.

Commands to Develop Programs and Process Data (Part 2 of 2)

------------------------,
ISubcommand
Command

Function

-------- ----------

1
I

or
Option

Type I

stop execution at a specified virtual
machine location.

ADSTOP
DEBUG

BREAK

CP
CMS

Resume execution of a stopped
virtual machine.

BEGIN
DEBUG

CP
CMS

Display virtual storage, registers,
PSi, and so on.

DISPLAY
DEBUG
DEBUG
DEBUG

GPR
PSi
X

CP
CMS
CMS
CMS

Print the contents of virtual storage
locations on the spooled printer.

DUMP
DEBUG

DUMP

CMS
CMS

Change the contents of registers and
storage locations.

STORE
DEBUG
DEBUG

STORE
SET

CP
CMS
CMS

Trace virtual machine SVC calls.

SVCTRACE

CMS

Trace virtual machine instructions, I/O
operations, SVC calls, and so on.

TRACE

convert system ABEND dumps to printed
output.

VMFDUMP

CMS

Trace events that occur on the real
machine.

MONITOR
MONITOR

L-______________________________________________________

Figure 38.

START
CP TRACE
STOP
CP TRACE

CP
CP

Co.mands to Test and Debug a Program

Appendix A: Functions of VM/370 Commands

343

r---------------------------------------------------

I
I
I

Punction

Co •• and

create a file from ter.inal input.

EDIT

create a file from card input.

READCARD
DISK

Verify the existence of a file on disk.

STATE

Erase a file

ERASE
ACCESS

(or files)

from disk.

I Subcommand I
I
or
I
I Option IType
CMS
LOAD

CMS
CMS
CMS

ERASE

CMS
CMS

List names of files on disk and their
attributes.

LISTPILE

CMS

Display the contents of a file at the
terminal.

TYPE

CMS

print the contents of a file or a member
of a library on a spooled printer.

CMS

Punch the contents of a disk file on a
spooled punch.

PUNCH
DISK

Sort the records of a file into ascending
order based on specified sort fields.

SORT

CMS

Copy one disk file to another disk file.

MOVEFILE
COPYPILE

CMS
CMS

Combine several files into one file.

COPYPILE

CMS

Copy data from one device type to
another device type.

MOVEPILE

CMS

Change the name of a CMS file.

RENAME

CMS

Compress a file by encoding multiple
contiguous occurrences of a single
character.

COPYPILE

Rearrange the contents of records in a
disk file.

COPY PILE

Perform character translations on
specified characters in a disk file.

COPYPILE

TRANS

CMS

Append one file to the end of another
file.

COPY PILE

APPEND

CMS

Remove trailing blanks from records in a
file.

COPYPILE

TRUNC

CMS

Compare the contents of two disk files.

COMPARE

CMS

Change records in a file based on
record sequence numbers.

UPDATE

CMS

DUMP

PACK

344

CMS

L--

Pigure 39.

CMS
CMS

Commands to Update Data Piles (Part 1 of 2)

IBM VM/370: Command Language Guide for General Users

COllmand

Punction

Subcollllandl
or
I
Option IType I
--I
CP

Terminate spooling operations on a
virtual unit record device or console.

Load the virtual forms control buffer
(PCB) •

LOADVPCB

Indicate order of processing for spooled
files.

ORDER

Remove spooled files from the system.

PURGE

print documents according to the control
words in the document file.

SCRIPT

CftS

Change options in effect for spooling
opera tions.

SPOOL

Spool input files to or from another
user.

TRANSPER

copy data from tape to disk.

TAPE

LOAD

CftS

copy data from disk to tape.

TAPE

DUftP

CftS

Convert OS partitioned data set (PDS)
files or card-image files on tape to
format on disk.

TAPPDS

Pigure 39.

CftS

Commands to Update Data Files (Part 2 of 2)

Command

Punction

Subcommand
or
Option
Type

Logically connect a disk to a virtual
machine.

LINK

Logically disconnect a device from a
virtual machine.

DETACH

ftake files on a disk a.ailable to a user.

ACCESS

CftS

Remove accessibility to files.

RELEASE

CftS

Dump a disk to tape.

DDR

DUftP

CftS

Restore a disk from tape.

DDR

RESTORE

CftS

Format disk space in CftS format.

PORftAT

Pigure 40.

CftS

Commands to Control Disks

Appendix A: Functions of Vft/370 Commands

345

Function

Command

ISubcollaandl
I
or
I
I Option
Type

Load a virtual aachine operating system.

IPL

Alter the virtual machine configuration.

DEFINE

Disconnect the user's terminal from the
Vft/370 systea.

DISCOBB

Enter control prograa commands froa a
CftS virtual machine.

CftS

Coaaunicate with other virtual machine
users or with the system operator.

ftSG

Simulate an external interrupt for a
virtual machine.

BITERBAL

Simulate 'not ready' for a virtual
device.

NOTREADY

Simulate functions of buttons on the
real CPU console.

SYSTEK

place virtual machine console in dormant
state with keyboard locked.

SLEEP

Perform tape rewind action.

RBWIND
TAPE

REi

CP
CftS

Establish Vft/370 directory entries.

DIRECT

efts

Simulate device end interrupt to a
virtual machine device.

READY

Simulate console interrupt.

ATTIf
REQUEST

CP
CP

Reset pending interrupts for virtual
devices.

RESET

Invoke table of synonyms for CftS comaand
names.

SYlfOBYft

CftS

Set the functions controlling forms for
command operand, options, names.

SET

Pigure 41.

346

ABBREV
IKPBI
IftPCP

Coamands for Virtual ftachine Control (Part 1 of 2)

IBK Vft/370: COlllland Language Guide for General Users

CftS
CKS
CKS

GC20-1804-3 Page Modified by TNL GN20-2659

Function

Command

ISubcommandl
I
or
I
I Option IType

Indicate if I/O is to be done as
specified by the virtual machine with no
ccw translation by CPo

SET

NOTRANS

control timer updating.

SET

TIMER

Change or set the number of loader
tatles for a CMS virtual machine.

SET

LDRTELS

eMS

Indicate if pages of storage are to be
released after the execution of certain
CMS commands.

SET

RELPAGE

CMS

Get information about virtual machine
status.

QUERY

set Virtual Machine Assist feature
on or off.

SET

ASSIST

Set the pseudo page fault portion of
VH/VS Handshaking feature on or off.
L-_ _ __

SET

PAGEX

Figure 41.

Commands for Virtual Machine Control (Part 2 of 2)

Appendix A: Functions of VM/370 Commands

347

GC20-1804-3 Page Modified by TNL GN20-2659

,,.-,

Function

Command

,Subcommand,
,
or
I
, Option
IType

Create accounting records for logged on
users and reset accounting data.

ACNT

Logically connect or dedicate devices
to a virtual machine or to CPo

ATTACH

Logically disconnect devices from
a virtual machine or from CPo

DETACH

Disable communication lines.

DISABLE

Enable communication lines.

ENABLE

Force a specific user to log off CPo

FORCE

Terminate active channel CP program on a
specific device.

HALT

Control paging activity.

LOCK
UNLOCK

CP
CP

Request information about real and
virtual machine characteristics.

QUERY

Establish system parameters.

SET

Terminate functions and checkpoint
system.

SHUTDOWN

Transmit high priority messages to users.

WARNING

Control 3704/3705 control program
functions.

NETWORK

LOAD
DUMP
ENABLE
DISABLE
TRACE
HALT
SHUTDOWN
POLLDLAY
QUERY
VARY
DISPLAY

'----Figure 42.

348

Commands to Control VM/370

IBM VM/370: Command Language Guide for General Users

Function

Command

Restart or reposition the current output
of an output spooling device.

-----

BACKS PAC

1Subcommand 1
1
or
1
1 Option
IType 1
1--

1 CP
1

Change attributes of a closed spool file.

CHANGE

Terminate spooling activity on a virtual
spooled unit record device or console.

Halt operations of specified spooling
devices following co.pletion of current
activity.

DRAIN

Cancel current output on a real unit
record device.

FLUSH

Cancel spool HOLD status.

FREE

Defer spooled output of a particular
user.

HOLD

Load printer UCS or FCE buffer.

LOADBUF

Cause spooled files to be processed in a
specific order.

ORDER

Remove closed spool files from the
system.

PURGE

Request information about spool files.

QUERY

Repeat printing or punching of current
file on a specific output device.

REPEAT

Force a printer to single space output.

SPACE

Modify spooling'options for reader,
printer, punch, and console spool files.
Initiates and terminates virtual console
spooling.

SPOOL

start spooling device after draining or
changing output class.

START

Spool files to or from a user's card
reader.

TRANSFER

Direct a file to a remote location.

SPOOL
TAG

CP
CP

Assign attributes and/or characteristics
to a spool file.

TAG
SPOOL

CP
CP

TAG

Request display of the attributes and
characteristics associated with a spool
file.
L-____________________________
___
Figure 43.

Commands for Spooling Control

Appendix A: Functions of VM/370 Commands

349

GC20-1804-3 Page Modified by TNL GN20-2659

,.
Function

COlllland

Subcommand
or
Option
Type

Display real storage at terminal.

DCP

Dump real storage to virtual spooled
printer.

DMCP

Display conditions that may affect system
loading.

INDICATE

Find locaticns of control blocks.

LOCATE

Record samples of system data for
performance analysis.

MONITOR

Save virtual lIachine storage space
on disk.

SAVESYS

Perform intensive recording of device
activity information.

SET

RECORD

Set the error recording mode for soft
machine checks.

SET

MODE

Dump error information which has been
recorded by error recording routines.

CPEREP

LOAD
USER
QUEUES
I/O
PAGING

CP
DISPLAY
ENAELE
INTERVAL
START
STOP

350

L--

Figure 44.

Co •• ands for System and Hardware Analysis

IBM VM/370: Command Language Guide for General Users

CMS

Appendix B: Debugging a Problem Program with VM/370

How To Start Debugging

Before you can correct any problem, you must recognize that one exists.
Next, you aust identify the problem, collect information and determine
the cause so that the problem can be fixed. When running V~/370r you
aust also decide whether the problem is in CP, the virtual machine, or
the problem program.
Once you determine that the problem is in CP or
the virtual machine, refer to !~L37Q: System Pr~~~~~~ Guide.
A good approach to debugging is:
1.

Recognize that a problem exists.

Identify the problem type and the area affected.

Analyze the data you have available, collect more data if you need
it, then isolate the data that pertains to your problem.

Pinally, determine the cause of the problem and correct it.

DOES A PROBLE! EXIST?
There are four types of problems:
1.
2.
3.
4.

Loop
wait state
ABEND (Abnoraal End)
Incorrect results

The most obvious indication of a problem is the abnormal termination
of a program. Whenever a program abnormally terminates, a message is
issued.
Another obvious indication of a problem is unexpected output. If your
output is missing, incorrect, or in a different format than expected,
some problem exists.
Unproductive processing tiae is another symptom of a problem. This
problem is not as easily recognized, especially in a time- sharing
environment.

IDENTIPYING THE PROBLE!
Two types of probleas are easily identified: abnormal termination is
indicated by an error message, and unexpected results become apparent
once the output is exaained. The looping and wait state conditions are
not as easily identified.

Appendix B: Debugging a Problea Prograa with ,"/370

351

ihen using '!/370, you are normally sitting at a terminal and do not
have the lights of the CPU control panel to help you. You .ay have a
looping condition if your program takes longer to execute than you
anticipated. Also, check your output. If the number of output records or
print lines is greater than expected, the output may really be the sa.e
infor.ation repeated .any ti.es. Repetitive output usually indicates a
program loop.
Another way to identify a loop is to periodically exa.ine the current
PSi. If the PSi instruction address always has the same value, or if the
instruction address has a series of repeating values, the program
probably is looping.
The wait state is also difficult to recognize when at the terminal.
Again, the console lights are unavailable. If your program is taking
longer than expected to execute, the virtual machine may be in a wait
state. Display the current PSi on the terminal. periodically, issue the
CP co.mand
QUERY TI!E
and compare the elapsed processing time. ihen the elapsed processing
time does not increase, the wait state probably exists.

ANALYZING TBE PROBLE!
Once the type of problem is identified, the cause of it must be
determined.
There
are recommended procedures to
follow.
These
procedures are helpful, but they do not identify the cause of the
problem in every case. Be resourceful. Use whatever data you have
available.
If the cause of the problem is not found after the
recommended debugging procedures are followed, it may be necessary to
undertake the tedious job of desk-checking.
The section, "Bow To Use '!/370 Facilities To Debug," describes
procedures to follow in determining the cause of various problems that
can occur in the Control Program, in the virtual machine, or in the
problem program. If you determine that there is a problem in CP or the
virtual machine operating system, refer to VM/370: ~l§~ Program.er·s
2~id~ for debugging procedures.

How To Use VM/370 Facilities To Debug
Once the problem, and the area where it occurs, are identified, you can
gather the information needed to determine the cause of the proble•• The
type of information you want to look at varies with the type of proble ••
The tools used to gather the information vary depending upon the area in
which the problem occurs. For example, if the problem is looping, you
will want to exa.ine the PSi via the CP DISPLAY co.mand.
The following sections describe specific debugging procedures for the
various error conditions. The procedures tell you what to do and what
debug tool to use.
For example, the procedure may say dump storage
using the CP DUMP co.mand. The procedure will not tell you how to use
the debug tool. Refer to sections 7 and 8 for a detailed description of
each debug tool, including how to invoke it.

352

IBM VM/370: Co.mand Language Guide for General Users

PROBLEM PROGRAK ABEND
When an operating system or program does
abnormally terainates.

not know how to

continue, it

If a dump was taken, it was sent to the virtual printer.
Issue a
CLOSE command to the virtual printer to have the dump print on the real
printer.
If the prob1ea can be reproduced, it may be helpful to trace the
processing using the CP TRACE command. Also, you can set address stops,
and display and alter registers, control words (such as the PSW), and
data areas. The CP commands can be very helpful in debugging because you
can gather information at various stages in processing. A dump is static
and represents the system at only one particular time. Debugging on a
virtual machine can often be more flexible than debugging on a real
machine.
VM/370 may terminate or reset a virtual machine if a nonrecoverable
channel check or machine check occurs in that virtual machine. Hardware
errors usually cause this type of virtual machine termination. One of
the following messages:
DKKKCB6161 KACHINE CHECK; USER userid TERKINATED
DKKCCH6041 CHANNEL ERROR: DEV xxx; USER userid; KACHIIE RESET
appears on the CPU console.
The address of the
problem program area.

instruction causing

the ABEND

is found

in the

Use the PSW and program listing to determine the cause of the ABEND.
If the problem is not readily detected, use the CP debugging facilities
to monitor the progress and status of the program as it executes. If
the program is running under the control of CKS, you can use the CKS
debug facilities as well.

UNEXPECTED RESULTS IN A PROBLEK PROGRAK
If a program has inaccurate, missing, or redundant output, a problem
exists. Instead of taking dumps of storage and output and dOing a lot
of desk-checking, you can use the interactive facilities of the virtual
aachine environment to debug. Using the CP ADSTOP command, you can set
an address stop. set the address stop at a strategic point in the
processing, such as before a data transfer or computation. When
execution stops, you can display or alter storage and set the next
address stop. Also, consider using the CP TRACE command. You can often
debug a problem program directly from the terminal.
Both the CP and CKS commands can
control of CKS.

be used to debug prograas under the

PROBLE! PROGRAK DISABLED LOOP
When a disabled loop in a problem program exists, you cannot communicate
with the virtual machine's operating system. That means that signalling
attention once does not cause an interrupt.

Appendix B: Debugging a Problem Program with VK/370

353

Enter CP mode.
1.

Use the CP TRACB command to trace the entire loop. Display general
and extended control registers via the CP DISPLAY command.

Take a dump via the CP DUMP command.

IPL the virtual machine again.

Use the information just gathered, along with
find the entry into the loop.

listings, to

try to

PROBLEM PROGRAM ENABLED LOOP
should perform the following sequence
cause of an enabled loop:

yOU

when attempting to

find the

Use the CP TRACE command to trace the entire loop. CMS users can
use the CP TRACE command or the CMS SVCTRACE command. Display the
PSW and the general registers.

Use the CP DUMP command to dump your virtual storage.
CMS users
can use the debug DUMP subcolmand.
A standalone dump may be used,
but be aware that such a dump destroys the contents of some areas
of storage.

Consult the source code to search for the faulty instructions,
examining previously executed subroutines if necessary. Begin by
scanning for instructions that set the condition code or branch on
it.

If the lanner of loop entry is still undetermined, assume
wild branch has occurred and begin a search for its origin.

that a

PROBLEM PROGRAM DISABLED WAIT
The VM/370 Control Program does not allow the virtual machine to enter a
disabled wait state or certain interrupt loops. Instead, CP notifies
you of the condition with one of the following messages:
DMKDSP450W
DMKDSP451W
DMKDSP452W
DMKDSP453W

CP
CP
CP
CP

ENTERED;
ENTERBD;
ENTERED;
ENTERED;

DISABLED WAIT PSW
INVALID PSW
EXTERNAL INTERRUPT LOOP
PROGRAM INTERRUPT LOOP

and enters the CP mode. Use the CP
information on the terminal.
•
•
•
•

commands to display

the following

PSW
CSW
General registers
Control registers
Then use the CP DUMP co •• and to take a dump.

If you cannot find the cause of the wait or loop from the information
just gathered, try to reproduce the problem, this time tracing the
processing via the CP TRACE co •• and.

354

IBM VM/370: Command Language Guide for General Users

If CMS is running in the virtual machine, the C"S debugging
facilities may also be used to display information, take a dump, or
trace the processing. The CMS SVCTRAC! and the CP TRACE commands record
different information. Figure 45 compares the two.

PROBLEM PROGRAM ENABLED WAIT
If the virtual .achine is in an enabled wait state; try to find out ¥hy
no I/O interrupt has occurred to allow processing to resume.
The Control Program treats one case of an enabled wait in a virtual
machine the saae as a disabled wait. If the virtual machine does not
have the "real tiaer" option and loads a PSW enabled only for external
interrupts, CP issues the aessage
DMKDSP450W CP ENTERED; DISABLED WAIT STATE
Since the virtual timer is not decremented while the virtual machine
is in a wait state, it cannot cause the external interrupt.
A "real
tiaer" runs in both the problem state and wait state and can cause an
external interrupt which allows processing to resume.

Appendix B: Debugging a Problem Program with V"/370

355

Comparison of CP and CMS Facilities for Debugging

If you are debugging problems while running CMS, you can choose the CP or CMS debugging
tools.
Refer to Figure 45 for a comparison of the CP and CMS debugging tools.

I Function

CMS

IIsetting
---------------------------------------------------------------------------1
Can set only one address stop at a time.
Can set up to 16 address stopsl
laddress
I stops.
I
IDumping
Icontents
I
lof storagel
Ito the
I
I printer.
I
I
I
I
I
I
I

at a time.

I
I
I
The dump is printed in hexa- I
decimal format. The storage
I
address of the first byte of I
each line is identified at thel
left. The contents of general I
and floating-point registers I
are printed at the beginning
I
of the dump.
I

The dumF is printed in hexadecimal format
with EBCDIC translation. The storage address of the first byte of each line is
identified at the left. The control blocks
are formatted..

-------------------------------------------------------------------------1
The display is typed in hexa- I

Displaying I
the conI
tents of
I
storage
I
and
I
control
I
registers I
at the
I
terminal. I

The display is typed in hexadecimal format
with EBCDIC translation. The CP command
I
displays storage keys, floating-point regi-I
sters and control registers.
I
I
I
I
I

storing
information.

The amount of information stored by the CP
command is limited only by the length of
the input line. The information can be
fullword aligned when stored. CP stores
data in floating-point and control registers, as well as in general registers. CP
stores data in the PSW, but not in the CAW
or CSW. However, data can be stored in the
CSW or CAW by specifying the hardware address in the STORE command.

decimal format. The CMS com- I
mands gQ nQ~ display storage I
keys, floating-point registers
or control registers as the CP
command does.

1
The CMS command stores up to
12 bytes of information. CMS
stores data in the general
registers but not in the
floating-point or control registers. CMS stores data in thel
PSW, CAW, and CSW.
1
I
I

---------------------------------------------------------------------------------1
Tracing
CP traces:
CMS traces all SVC interrupts. 1
information.

• All interrupts, instructions, and
branches
• SVC interrupts
• I/O interrupts
• Program interrupts
• External interrupts
• Privileged instructions
• All user I/O operations
• Virtual and real CCWts
• All instructions

CMS displays the contents
I
of general and floating-point I
registers before and after
1
a routine is called. The parameter list is recorded before
a routine is called.

The CP trace is interactive. You can stop
it and display other fields.
Figure 45.

356

Comparison of CP and CMS Facilities for Debugging

IBM VM/370: Command Language Guide for General Users

Appendix C: Using the CMS Batch Facility

The C8S Batch Facility is a V8/370 programming facility that runs under
C8S. It allows a V8/370 user to run jobs in batch mode by queuing jobs
from either his own virtual .achine or the real card reader to a virtual
machine dedicated to running batch jobs under the Batch Facility. The
Batch Facility machine then executes these jobs, freeing the user's

machine for other uses.

The accounting routines charge the time used in

the batch machine to the originating user.
The Batch Facility virtual machine is generated and controlled at a
terminal console under a userid dedicated to execution of jobs in batch
mode. The system operator generates a batch machine by performing an
IPt of C8S, then entering a command (C8SBATCB), which specifies that the
machine is to execute jobs in batch mode. After each job is executed,
the Batch Facility reloads itself, thereby providing a continuously
running batch machine.
Jobs are queued to the batch machine's virtual
card reader from either user terminals or the system card reader and
executed sequentially. When its virtual reader is empty, the Batch
Facility waits for more input.
The Batch Facility is designed for the non-CMS user who requires a
system for compiling or executing batch jobs loaded from the real system
card reader. The Batch Fac"ili ty is also useful for the interactive user
who has compute-bound jobs such as assemblies and compilations, and for
execution of large user programs.
This allows interactive users to
continue work at their terminals while their time-consuming jobs are run
in another virtual machine.
Execution time for CP and C8S
equivalent to that of co.mands
interactive CP/C8S session.

commands under the Batch Facility is
typed in at a terminal during an

Using the Batch Facility Virtual Machine
The Batch Facility is generated on any ter.inal attached to the V8/370
system. The userid used to run the Batch Facility should be known by
all users in the installation.
The interactive users of the Batch Facility must spool their batch
jobs to the virtual reader of the batch userid and the non-interactive
users must precede the real deck of batch jobs with a CP ID card
specifying the userid of the Batch Facility virtual machine.
The ID
card takes the form:

userid

where ID must begin in card column one and be separated from userid (the
Batch Facility virtual machine userid) by one or more blanks.

Appendix C: Using the C8S Batch Facility

357

INPUT TO THE BATCH PACILITY VIRTUAL MACHINE
Any user application or development program written in a language
supported by VM/370 may be executed on the Batch Pacility virtual
aachine. However, there are restrictions on programs using certain CP
and CMS commands, as described later in this section.
Programs to be executed under the Batch Pacility must be delimited by
IJOB, and 1* control cards. Another control card, the ISET card, may
also be used with an input program to set certain, limits on the
execution of the prograa.
Input records for the Batch facility must be in
Any record not in card-iaage for.at is flushed.

card-image format.

The IJOB card identifies the name and userid of a job and provides
accounting inforaation for the system. A IJOB card must precede each
job to be executed under the Batch Pacility. It takes the fora:

IJOB

userid accntnum [jobname] [coaments]

.!!!~:

userid

specifies the user identification of the user who sent the job
to the batch aachine.
This userid is charged by the CP
accounting routines for the systea resources used during a
job.

accntnum

is the user's account number.
This account number appears in
the accounting data that is generated at the end of a user's
job. This account number will override the account number in
the CP directory entry for that userid.

jobname

is an optional parameter that specifies
being run.

comments

may be any information the user wishes.

the name of

the job

The use rid and jobname parameters are used by the Batch Pacility for
printing of distribution codes for spooled output and for directing job
status messages to the interactive user's terminal.
The 1* card indicates the
takes the form:

end of a job

to the Batch

Pacility.

1*
The Batch Pacility treats all 1* cards after the first as null cards.
Therefore, if you want to ensure against the previous job not having a
1* end-of-job indicator, you should precede your IJOB card with a 1*
card.
The only exception to the way the Batch Pacility handles the 1* cards
is in the case of the CMS MOVEPILE command.
When the input PILBDEP
specifies a terainal read, for example PILEDEF INFILE TERM, a 1* card
must be supplied by the user to delimit that file.
358

IBM VM/370: Command Language Guide for General Users

The ISET card sets limits on a system's time, printing, and punching
resources during the execution of a job. It takes the form:

/SET

[TIME seconds] [PRINT lines] [PUNCH cards]

seconds

is a decimal value that specifies the maximum
seconds of virtual CPU time a job can use.

lines

is a decimal value that specifies
a job can print.

cards

is a decimal number that specifies the maximum number of cards
a job can punch.

number

the maximum number of lines

The default values for the Batch Facility are set at 32,767 seconds,
printed lines, and punched cards per job. Any new limits defined using
the ISET card must be less than these maximum settings.
The system
resources can be set at lesser values than the default values by an
installation's system programmer;
be sure you know
the maximum
installation values for batch resource limits before you use the /SET
card.

EXEC files can be used as input to the Batch Facility virtual machine,
providing a greater level of programming flexibility for Batch Facility
users. The following list shows a few of the uses for EXEC files in
manipulating the batch machine.
EXEC files can be used:
To store control statements
execution of queued jobs.

•

To sUbstitute keyword values into a program so that
be given variable input.

•

To skip over
statements.

•

To identify other EXEC files to be used during program execution.

•

To integrate many files into a
Batch Facility.

portions of

(/JOB,

/*,

•

programs using

and

/SET)

required

for

the program can

conditional EXEC

single file for execution

control

under the

The uses of EXEC files in manipulating the input to the Batch
Facility virtual
machine are limited
only by
the programmer's
imagination and the rules for writing EXEC files.
For rules for writing
EXEC files and how they can be used, see the !AtJIQ: !!EC US~~!2 Guid~.

Appendix C: Using the CMS Batch Facility

359

The Batch Facility permits the use of most
exceptions are noted in the follcwing lists.
only the following
virtual machine:
CBAIGE'
CLOSE'
DETACH2
DUftP
DISPLAY
LIIK3

CP co •• ands

are

CP and CftS

allowed to

commands.

control the

The
Batch

ftSG
QUERY
BEIIID
SPOOL'
STORE
TAG

The following CMS commands are disabled under the Batch Facility:
SET
READCARD
DISK LOAD
The FILEDEF com.and is also disabled
card reader.

for use in defining the virtual

BATCH PACILITY OUTPUT
The Batch Facility's virtual machine runs with its output spooled to the
terminal console and to the printer. If the batch machine's virtual
console is connected, CP messages are also printed at the console. The
printed copy resulting from execution of a program is printed at the
real printer under the su~.itting userid, with the user's distribution
code and a spool file name and type of CftSBATCH JOB (unless a job name
was specified on the /JOB card). CftS console output is spooled to a
file that is printed followipg the user's program execution output at
the real system printer, with the submitting user's distribution code, a
spool filename of BITCH, and a spool filetype of COl SOLE.
since all the closed printer files are queued for system output under
the submitting userid, the submitting user can control (CHAIGE, PUBGE,
or ORDER) these files before processing on the system printer.
At job termination, all spooling devices are closed and all files are
released. If the CP TAG command was used to identify spool files or to
direct these files to other virtual machines or remote work stations,
the Batch Pacility resets the spooling devices for the next job. If
disk devices were linked to during the job, they are detached by the
Batch Pacility at job termination time.
The Batch Pacility eMS system is then reloaded,
nucleus data areas and work areas in storage.

reinitializing all

Ilso at the end of the job, accounting information is punched to the
system card punch. This accounting information is in the same format as
CP/CMS accounting information.

'May not be used to affect the virtual card reader.
2ftay not be used to affect spooling devices or the system or IPL disks.
3ftust be in the following format:
CP LIIK userid vaddr vaddr mode password
360

IBM Vft/370: Command Language Guide for General Users

When a user job terminates abnormally, the Batch Pacility sends an ABEID
aessage in the appropriate userid terminal console. types the message to
the BATCH CONSOLE file, and spools a CP dump of the virtual machine
(with a heading of userid and jobname) to the printer. The Batch
Facility then performs the normal cleanup tasks and starts the next
job.
Since the Batch Facility reloads itself (via IPL) after each job,
that portion of a job following an ABEID is treated as a new job, which
is subsequently flushed.

Appendix C: Using the CftS Batch Facility

361

Appendix D: eMS Macro Instructions

The macro definitions that are used by the Conversational ftonitor System
(CftS) are contained in the files CftSLIB ftlCLIB and OS!lCRO !ICLIB, which
reside on the system disk. CftSLIB !lCLIB contains the macros which
provide linkages to the CBS function routines, and OS!lCRO !ICLIB
contains Operating System macros which are simulated by CftS. Only the
CftS macros are discussed in this section. To obtain a iist of the names
and locations of macro definitions in a macro library called libname
ftlCLIB, the command ftlCLIB !IP libname may be issued.
The macros described in this section deal primarily with linkage to
the disk and terminal handling routines.
WRTER! and RDTBR! handle
terminal input/output, and PSCB, PSST1TE, PSOPBI, PSRB1D, PSWRITB,
PSER1SE, and PSCLOSE handle I/O to disk.
The offline unit record
devices may be accessed from an lssembler Language program by using
RDC1RD, PRIITL, and PUICHC.
The iRTER! and RDTERft macros each set up a parameter list inline, and
issue a CBS supervisor call. Por disk I/O, the parameter list is set up
in a constant area by the PSCB (Pile system Control Block) macro, or
generated inline if the PSCB option is not specified. The label of that
macro is used as a parameter of the PSiRITB, PSRB1D, PSOPBI, and PSSTITE
macros. The example in Pigure 46 shows a typical sequence for writing
and readi~g disk files.
The program example in Pigure 46 shows the use of I/O macros. The
program copies a file, the "input file," to a new file, the "output
file~"
If the program were processed by GBI!OD into a module named
BBGII, it would be invoked with a command line of the form: "BBGII PILB1
BIBC 11 PILB2 BIBC 11," which would copy PILB1 BIEC (input file) to
PILI2111C (output file).
The PSST1TB macro determines the existence of the input file. The
error branch will be taken if it does not exist. This is not needed for
the output file, since, if it didn't exist, it would be created. If the
output file already existed, the new records would be appended to it.
The program then alternates between reading and writing records,
until PSREID returns an error code. Control then goes to BOP, which
tests whether end-of-file or some other error occurred.
If it was
end-of-file, a return code of zero is passed back to the command level
in register 15.
If an error occurs, an appropriate response is typed using the iRTBR!
or LIIBDIT macros. Use of the LIREDIT macro at !RR2 and IRR3 causes the
value of the return code from PSRBAD ~r PSiRITI to be substituted, in
decimal, for the dots in the text of the message to be typed.
lote that, if desired, the PSOPIR and PSCLOSI macros could have been
used to open and close the files. It was not necessary to do so in this
program because the 'SRIAD and 'SiRITI macros open the file to be read
or written. The CftS system automatically closes all files at the end of
each command execution.
Appendix D: CftS !acro Instructions

363

STftT

SOURCB ST1TBBENT
CSECT
PRINT NOGEN
SlYB (14,12) ,,*
B1LR 12,0
EST1BLISH lDDRESS1BILITY
USIIG *,12
Ll
2,8(,1) R2=lDDR OP INPUT PILEID IN PLIST
Ll
3,32(,1) R3=lDDR Ol OUTPUT lILEID II PLIST
DETERftINE IP INPUT PILE EXISTS
PSST1TE (2) ,BRROR=ERRl

1 BEGIN
2
3
8
9

10
11
12
13

28 * REID 1 RBCORD PROft IIPUT lILE liD WRITE ON OUTPUT PILE
29 RD
FSREAD (2) ,ERROR=EOP,BUPPER=BUPP1,BSIZE=80
52
PSWRITE (3) ,BRROR=ERR2,BUllER=BUlll,BSIZE=80
75
B
RD
LOOP B1CK POR IEXT RECORD
77 * COBE HERB IF ERROR RE1DING IIPUT PILB
78 EOP
C
15,=F I 12 1
END OF PILE 1
79
BIB
BRR3
BRROR IP NOT
81
RETURN (14,12) ,RC=O
85 * IP INPUT PILE DOES lOT EXIST
86 ERR1
WRTERft IPILB lOT POUNDI,BDIT=YBS
96
B
ERRET
98 * IP ERROR WRITING PILB
99 ERR2
LR
10,15
SlYE RBT CODE IN RBG 10
100
LINEDIT TEXT='ERROR CODE ••••• II WRITING PILE',sUB=(DEC, (10»
115
B
BRRBT
117 * IP RB1DING ERROR Wls lOT NORB1L BND Ol PILB
118 BRR3
LR
10,15
slYE RET CODE IN REG 10
119
LIIBDIT TEXT=IBRROR CODE ••••• II RE1DIIG PILBI,SUB=(DEC,(10»
135 ERRET

RETURI (14,12),RC=1 RETURI TO C1LLBR

141 BUPF1
142
143
144
145
146
147

DS
BID

Pigure 46.

364

CL80
=CL8 I RDBUl'
=CL8 I WRBUP'
=1 (BUll1)
=F 1 80 1
=P'12 1

1 sa.ple Listing of a Progra. that Uses CBS Bacros

IBB Yft/370: Co •• and Language Guide for General Users

COftPSWT !ACBO
COMPSWT Macro
PU~POS!:

The COftPSWT macro causes the COftPSWT flag in the OSSPLAGS byte
lucleus constant Area to be turned on or off.

of the

[label] I COftPSWT I OllOPP

USAG!:
The co.piler switch flag COftPSWT in the lucleus Constant Area determines
whether the OS .acros LIII, LOAD, ICTL, and ATTACH will use the CftS
IICLUDB co •• and or the CftS LOADftOD co.jand. With COftPSWT off, the
progra. called by LIII, LOAD, ICTL, or ATTiCH .ust be a relocatable
object module residing in a file with the filetype TBIT or TITLIB. It
is called via the IICLUDB com.and.
with CO!~SWT on, the program called
by LIBI, LOAD, ICTL, or ATTACH must be an absolute core-image module in
a file with the filetype ftODULB. It is called via the LOADftOD co •• and.

Appendix D: CftS ftacro Instructions

365

FSCB MACRO
FSCBMacro

The FSCB macro creates a File system control Block, which is used as the
parameter list to the file system routines.

[label]

FSCB

[fileid] [,RECFft=format]
[,BUFFER=buffer] [,BSIZE=size]
[,RECRO=number] [,NOREC=numrec]

label

is an optional statement label.

fileid

specifies the file identifier enclosed in
separated by blanks ('filename
filetype
file mode is omitted, "Al" is assumed.

format

F indicates fixed-length records (default).
V indicates the variable-length records.

buffer

specifies the address of the I/O buffer.

size

specifies the size of the buffer in bytes.

number

specifies the relative record number of
accessed (default = 0).

numrec

specifies the number of records to be read (default = 1).

!g!~:

quote marks
filemode') •

the next record to be

The above options must be specified as self-defining teras.

The FSCB macro generates a File system Control Block
file.
It may be used as the parameter list to
routines.

for the specified
the file system

Errors in macro operand coding will cause Assembler errors.

366

and
If

IBft Vft/370: Command Language Guide for General Users

FSCLOSE MACRO

FSCLOSE Macro

The FSCLOSE macro causes
status saved on the disk.

an open

file to

be closed

and its

current

l[label]1
L-__________________________________________________________
FSeLOSE I [fileid] [,FSCB=fscb] [,ERROR=erraddr]

label

is an optional statement label.

fileid

specifies the file identifier.
'fileid'
FSCB= is also specified.
It may be:
'fn ft f.'
(reg)

fscb

erraddr

fileid enclosed in quote marks and separated by
blanks.
If fm is omitted, "Al" is assumed.
a register from 2 to 15 containing the address of
the fileid (18 characters).

specifies the address of an FSCB.
label
(reg)

may be coded even if

It may be:

the label on the FSCB macro.
a register containing the address of an FSCB.

specifies the address of an error routine to be given control
if an error is encountered. If ERROR= is not coded, control
returns to the next sequential instruction in the calling
program if an error occurs, as it does if no error occurs.

lSCLOSE should be used within EXEC procedures to close files tha~ are no
longer needed for processing. The FSCLOSE macro causes the specified
file to be closed. Either a fileid or FSCB must be specified.

If an error occurs, processing terminates, and control is passed to
erraddr (if one was provided) or back to the calling program's next
sequential instruction. Register 15 contains the following error code:
fte~!!!g

File not· open

Appendix D: CftS Macro Instructions

367

F SERA SE f'-ACRO
FSERASE Macro

The PSERASE macro causes one or more files to be deleted from the user's
disk.

l[labe1]1 PSERASE l[fi1eid][,PSCB=fscb][ ,ERROR=erraddr]

label

is an optional statement label.

fi1eid

specifies the file identifier. 'fi1eid'
PSCB= is also specified. It may be:
'fn ft fm'
(reg)

fscb

fi1eid enclosed in quote marks and separated by
blanks. If fm is omitted, "Al" is assumed.
a register other than 0 or 1 containing the
address of the fi1eid (18 characters).

specifies the address of an PSCB.
label
(reg)

erraddr

may be coded even if

It may be:

the label of an PSCB macro.
a register containing the address of an PSCB.

The PSERASE macro causes the specified file to be deleted from
user's disk. Either a fi1eid or PSCB must be specified.

the

If an error occurs, register 1 points to the PSCB for the file having
the error and register 15 contains one of the following error codes:
~!~!'!!.9

Parameter list error
Pile not found

368

IBft Vft/370: Command Language Guide for General Users

FSOPEN MACRO
FSOPEN Macro

The FSOPER macro
output.

[label]

causes the file to

FSOPER

be made ready for

[fileid] [,lSCB=fscb] [,options]
[,ERROR=erraddr]

label

is an optional statement label.

fileid

specifies the file identifier.
'fileid'
PSCB= is also specified.
It may be:
'fn ft f.'
(reg)

fscb

may be coded even if

the fileid enclosed in quote marks and separated
by blanks.
If fm is omitted, "Al" is assumed.
a register other than 0 or 1 containing the
address of the fileid (18 characters)

specifies the address of an FSCB.
label
(reg)

either input or

It may be:

the label on an lSCB macro.
a register containing the address of an FSCB. If
FSCB= is not coded,
an fscb is created inline,
pointed to by register 1, upon return from the
macro call.

options

any of the options of the FSCB macro instruction may be
specified here. Only the BUPFER, RECNO, NOREC, and BSIZE
(variable file only) options have any effect for an already
existing file.
These options may be specified as either a
self-defining term or a register enclosed in parentheses.

erraddr

specifies the address of an error routine to be given control
if an error is encountered. If ERROR- is not coded, control
returns to the next sequential instruction in the calling
prograa if an error occurs, as it does if no error occurs.

The FSOPER macro causes the FSCB to be filled in from the file status
table for an already existing file.
A file status table entry is
created for a new file.
Either a fileid or FSCB must be specified. On
return, register 1 points to the FSCB for the file.
FSOPEN is used mainly to determine the existence of the file about to be
processed.

If an error occurs, processing terminates, and control is passed to
erraddr (if one was provided) or back to the calling program's next
sequential instruction.
Register 15 contains one of the following error
codes:
MeaniBg
File does not exist
Invalid file identifier

Appendix D: CMS Macro Instructions

369

PSREAD ftACRO

FSREAD Macro

The PSREAD macro causes a record to be read from disk.
~Q!Hl!I:

[label]

FSREAD

[fileid] [,FSCB=fscb] [,options]
[ , ERROR=erraddr]

label

is an optional statement label.

fileid

specifies the file identifier. 'fileid'
FSCB= is also specified. It may be:
'fn ft f.'
(reg)

fscb

the fileid enclosed in quote marks and separated
by blanks. If f. is o.itted, "Al" is assu.ed.
a register other than 0 or 1 containing the
address of the fileid (18 characters).

specifies the address of an FSCB.
label
(reg)

may be coded even if

It may be:

the label of an FSCB macro.
a register containing the address of an PSCB.

options

the BUFFER, NOREC, BSIZE, and RECNO options of the FSCB .acro
instruction may be specified here. If the PSCB parameter is
omitted, the BUPPER and BSIZE options must be specified.
These options may be specified as either a self-defining term
or a register ~nclosed in parentheses.

erraddr

specifies the address of an error routine to be given control
if an error is encountered. If ERROR= is not coded, control
returns to the next sequential instruction in the calling
prograa if an error occurs, as it does if no error occurs.

The PSREAD macro reads one record into the user's buffer. If the RECNO
option is specified, that specified record is read. otherwise, the next
record in the file is read. If RECNO is specified, it must be reset to
zero by the next ~SREAD in order to read the file sequentially from the
originally specified record number.
lither a fileid or PSCB must be
specified. On return, register 0 contains the number of bytes read.
Register 1 points to the PSCB.

If an error occurs, processing terminates, and control is passed to
erraddr (if one vas provided) or back to the calling program's next
sequential instruction. Register 15 contains one of the following error
codes:
.§.!.!ni.!!.9
File not found
Invalid buffer address
Per.anent I/O error

370

IBft Vft/370: Co.mand Language Guide for General Users

FSREAD MACRO
~!!~!Bg

7
8
9

11
12
13
14
15

Number of records is less than or equal to zero, or
greater than 32768
Invalid record format (only checked for at the first read
after finis or iplj
Incorrect length
File open for output
Nu.ber of records greater than 1 for variable length file
End of file
Variable length file has invalid displacement in active
file table
Invalid character in filename
Invalid character in filetype

Appendix D: CMS Macro Instructions

371

F SSTATE MACRO

FSSTATE Macro

The FSSTATE macro returns
specified file.

the

user

the

current status

the

1.Q~:

•l[labe1]1

FSSTATE I [fi1eid] [,FSCB=fscb] [,ERROR=erraddr]

label

is an optional statement label.

fi1eid

specifies the file identifier.
Ifi1eid'
FSCB= is also specified. It may be:
Ifn ft fm'
(reg)

fscb

the fi1eid enclosed in quote marks and separated
by blanks. If f. is oaitted, "A1" is assumed.
a register other than 0 or 1 containing the
address of the fi1eid (18 characters).

specifies the address of an FSCB.
label
(reg)

erraddr

may be coded even if

It may be:

the label on an FSCB macro.
a register containing the address of an FSCB.

specifies the address of an error routine to be given control
if an error is encountered.
If ERROR= is not coded, control
returns to the next sequential instruction in the calling
program if an error occurs, as it does if no error occurs.

The FSSTATE .acro causes the existence of the specified file to be
verified. Begister 1 points to a copy of the Pile status Table (PST)
for the specified file. Either a fileid or FSCB must be specified.

If an error occurs, processing terminates,
and control is passed to
erraddr (if one was provided) or back to the calling progra.'s next
sequential instruction.
Register 15 contains one of the following error
codes:
Code
-2024
28
36

312

fteaniBg
Invalid character in fi1eid
Invalid fi1e.ode
Pile not found
Disk not accessed

IBft Vft/310: Co •• and Language Guide for General Users

FSWRITE MACRO

fST,VRITE lr1acl'o

The FSWRITE macro causes a record to be written to the disk.

,.-------I [label]
I

FSWRITE

------,

[fileid] [,FSCB=fscb] [,options]
[,ERROR=erraddr]

L-

label

is an optional statement label.

fileid

specifies the file identifier.
'fileid'
FSCB= is also specified.
It may be:
'fn ft fm'
(reg)

fscb

i
I

the fileid enclosed in quote marks and separated
by blanks.
If fm is omitted, "A 1" is assumed.
a register other than 0 or 1 containing the
address of the fileid (18 characters) •

specifies the address of an FSCB.
label
(reg)

may be coded even if

It may be:

the label on an FSCB macro.
a register containing the address
FSCB= is not coded, BUFFER= and
coded.

of an FSCB.
BSIZE= must

If
be

options

any of the options of the FSCB macro instruction may be
specified here.
Only the BUFFER, RECNO, and BSIZE options
have any effect on an already existing file.
These options
may be specified as either a self-defining term or a register
enclosed in parentheses.

erraddr

specifies the address of an error routine to be g1ven centrel
if an error is encountered.
If ERROR= is not ceded, centrol
returns to the next sequential instruction in the calling
program if an error occurs, as it does if no error occurs.

The FSWRITE macro writes one record onto the user's disk.
If the RECNO
option is specified, that specified record is written. Otherwise, the
next sequential record in the file is written.
To write a file beginning with a specific record in the file,
two
FSWRITE statements must be issued: the first to specify the record
number where the writing is to begin, for example, RECNO=5 begins the
write operation at record number 5 in the specified file.
The second
FSWRITE statement must set the RECNO option to zero, which will cause
the remaining records in the file to be written sequentially.
Either a
fileid or FSCB must be specified. On return, register 1 points to the
FSCB for the file.
Using the BSIZE option of the FSCB macro, you can write multiple records
in a single FSWRITE statement. For example, if you wish to write 20
records at once, you code BSIZE=1600 (the length of the record times the
number of records). Variable length records cannot be written like this,
however. They must be written sequentially each with its own length
specified.
Appendix D: CMS Macro Instructions

373

GC20-1804-3 Page Modified by TIL GN20-2659
FSWRITE MACRO

--"24

5
6
7
8
9

10
11
12
13
15
16
17
18
19
20
21

374

~~g!!!!!g

Invalid buffer address
First character of filemode is illegal
Second character of filemode is illegal
Itea number too large
Attempt to skip over unwritten variable length item
Buffer size not specified
Pile open for input
Maximum number files reached
Record format not P or V
Attempt to write on read-only disk
Disk is full
Length of fixed length item not the same as previous item
Record format specified not the same as file
Variable length item greater than 65K bytes
Number of records greater than 1 for variable length file
Maxiaua number of data blocks per file reached (16060)
Invalid character detected in filename
Invalid character detected in filetype

IBM VM/370: Command Language Guide for General Users

HNDEX~

!!ACRO

HNDEXT Macro

The HNDEXT macro causes external interrupts to be passed
routine for processing.

[label]

HRDEXT

to the user's

function[,address]

label

is an optional statement label.

function

specifies whether
cleared (CLR).

address

specifies the
address of the
routine to
process
interrupts. This parameter is required only when the
function is specified.

the interrupts are

to be trapped

(SET) or
the
SET

The BNDEXT macro causes C!!S to pass control to the user's routine when
an external interrupt occurs.
When the user is given control, all
virtual interrupts except multiplexer are disabled. On entry to the
user's routine, register 1 points to a save area used for saving the
registers and PSW at the time of the external interrupt, starting at
label GRS, as shown below.
Register 13 points to an 18-fullword save
area starting at label UAREA, shown below.
Register 14 contains the
address the user's routine must return to when this processing is
complete, and register 1S contains the address of the user's processing
routine. After HRDEXT CLR is issued,
an external interrupt other than a
timer interrupt will cause DEBUG to be entered.

l!gbe!
GRS
FRS
PSW
UAREA
END

Displacement
_!!!!.£- -!!~o
0
64
40
96
60
108
68
180
B4

None.

Appendix D: C!!S !!acro Instructions

315

BNDINT KACRO

HNDINT Macro

The BNDINT macro causes interrupts for the specified
passed to the user's routine for processing.

[label]

BNDINT

devices to

function, (devname[ ,address,devaddr,when]) •••
[ ,ERROR=erraddr]

label

is an optional statement label.

function

specifies whether
cleared (CLR).

devname

specifies a four character symbolic name for the device.

address

specifies the
address of the
routine to
process the
interrupts. An address of zero indicates interrupts for the
device are to be ignored.

devaddr

specifies the device address, in hexadecimal, of
whose interrupts are to be trapped.

when

specifies that the interrupts are to be reflected immediately
(ASAP) or only after the WAITD macro is issued (WAIT).

erraddr

specifies the address of an error routine to be given centrol
if an error is encountered. If ERROR= is not coded, control
returns to the next sequential instruction in the calling
program if an error occurs, as it does if no error occurs.

Note: address, devaddr,
specified.

and

the interrupts are

when

need not

be trapped (SET) or

specified

the device

if CLR

The BNDINT macro causes CKS ta pass control to the user's routine when
an interrupt is received from one of the specified deviGes.
The user
routine will be entered immediately if ASAP is specified or a WAITD
macro has been issued for the device.
If neither condition exists, the
interrupt will be stacked, until a WAITD macro is issued for the
device.
When the user is given control, all I/O interrupts and external
interrupts are disabled. On entry to the user's routine, registers 0 and
1 contain the I/O old PSW, registers 2 and 3 contain the CSW, register 4
contains the interrupting device address, register 14 contains the
address that the user's routine must return to when his processing is
complete, and register 15 contains the address of the user's processing
routine.
When processing is complete, the user must return to CKS via
register 14 and indicate in register 15 whether processing is complete.
A zero in register 15 indicates that the user has completed handling the
interrupt and a nonzero register 15 indicates that another interrupt is
expected. The CLR function indicates
that the user is finished
processiing interrupts for this device.
Por additional information, see
the documentation for WAITD.

If an error is detected, register 15 contains a 1,
devaddr or address is invalid.
376

indicating that the

IBK VK/370: Command Language Guide for General Users

HNDSVC ftACRO
HNDSVC Macro

The HNDSVC macro causes interrupts for the specified supervisor call
(SVC) numbers to be passed to the user's routine for processing.

[label]

HNDSVC

{set I clr},{ (svcnum ,address) I svcnum}
[ , { (svcnum,address) I svcnum}] •••
[ , ERROR=erraddr ]

label

is an optional statement label.

svcnum

specifies a number from 0 to 200 or 206 to 255 that
corresponds to the SVC number to be handled by the user
routine.
(SVC's 204 and 205 are reserved for future use.)

address

specifies the address
of
interrupt. This field need
function.

erraddr

the routine to
process the
not be specified with the eLR

The HNDSVC macro causes CftS to pass control to the user's routine when
one of the specified SVC instructions is issued. On entry to the user's
routine the following conditions exist:
Register
__
__
0-11 and 15
J!.Q~

12
13

,..,..., .....

~_---..L

~~!!~~!!.~~

As they were when the SVC was executed.
Address of user SVC handler routine.
Address of an 18-fullword save area for use
user's SVC handler routine.
Return address in Cfts.

by the

The user must return to CftS via register 14 when he has completed
processing the interrupt. The CLR function indicates that the user is
finished handling interrupts for the specified SVC number.

If an error occurs, p~ocessing terminates, and control is passed to
erraddr (if one was provided) or back to the calling program's next
sequential instruction. Register 15 contains one of the following error
codes:
fte~.!!.!.!!.9

Invalid SVC number or address
SVC number set replaced previously set number
SVC number cleared was not set

Appendix D: CMS ftacro Instructions

377

LINEDIT ftACRO

LINEDIT Macro

The LINEDIT macro provides a aethod for performing conversions
EBCDIC, and, optionally, typing the results at the terminal.

[label]

LIHEDIT

into

[ftF='!ILI (E,addr) I (B, (reg»]
[,TEXT='message-text']
[,TEXTA=address I (reg) ]
[,COftP=!~~INO]

[ ,DOT=YB21 NO]
[,SUB=(type,value[ ,type,value] •• )]
[,DISP=1 rP !INONBISIO IPRINTICPCOftft]
[ , BUFF A= address I (reg) ]
[ , RENT=!ES I NO ]
[,ftIXSUBS=number]
where the option list
(described in greater
Parameters") :

consists of
detail in

ftF='!ILI (E,addr) I (E, (reg»

the
the

following keyword parameters
section
on "LINEDIT ftacro

to specify macro form

TEXT= , message-text , to spec1fy message text
TEXTA=addressl (reg) to specify message text address
COftP=!l~IBO

to suppress multiple blank compression
to suppress final period on message text

DOT=YE~INO

SUB=(type,value[,type,value] ••• ) to specify a substitution list where:
type =
=
=
=
=
=
=

HEX
HEXA
DEC
DECI
HEX'll
CHARA
CHAR81

value= expression
= (reg)
= address
= (address, length) length being equal either
to number or (reg)
DISP=lYPEIBOBEISIOIPRINTICPCOftft to specify
lIessage text.

the action to be

taken with

BUFFI=address I (reg) to specify return buffer address
RENT=I~§lno

to specify whether reentrant code must be generated.

MIXSUBS=number to specify
MP=L.

the

maxillull

number of

sUbstitutions

!2~:

with

Registers 1 and 15 should not be used as argument registers to the
LINEDIT macro; they are used as work registers by the macro.
378

IBft VM/370: Comlland Language Guide for General Users

LINEDIT ftieBO
LINEDIT ftieBO PABAftETEBS

The

ftP parameter specifies whether the form of the macro is to
!i§!, or ~~~£Yte. This parameter is coded as follows:

st~~g~~,

ftl=!

IL I (E, addr) I (E, (reg»

with the following meanings:
ftP=l (Standard form)
This is the most usual form, and the default. It generates an inline
PLIST, and generates a call to the LINEDIT routine so that the
message will be typed at the terminal.
The standard form will generate only reentrant code, and may be used
under all circumstances except the following:
•

If more than one substitution is made.

•

If TEITI=(reg) is used. Bote that
the standard form, with the address
address constant.

•

If the BUF1A parameter is used.

ftl=(E,addr) or ftl=(E,(reg»

TEITA=address can be used in
referenced in the PLIST by an

(Execute fora)

If used in this form, the macro will generate code to construct a
PLIST at the specified address, rather than using an inline PLIST.
The code will then call LINEDIT, passing the address of the newly
constructed PLIST.
The address of the construction area for the PLIST is given by
"addr," to specify an address which can be obtained by a Load Address
(L~ instruction, or by "(reg),"
where the register specified points
to the area.
In either case, the specified area must be large enough to construct
a PLIST. The size of a PLIST is variable, depending upon the number
of substitutions made, and whether BU1PA was specified.
The list
form of the LIBBDIT macro is used to reserve space for the PLIST.
ftl=L

(List fora)

This fora generates a PLIST only.
It does not generate any
executable code.
It is used to reserve space for a PLIST to be
constructed using the ftl= (E, •••• ) execute form. ' The size of the area
reserved depends upon the number of sUbstitutions to be made, as
specified with the ftAISUBS parameter.
lor example,
LINEDIT ftl=L,ftAISUBS=5
reserves space
parameters.

for a PLIST

which may

hold up to

five sUbstitution

Appendix D: eftS ftacro Instructions

379

LIIBDIT !ACRO
TBXT Paraaete£
This paraaeter specifies the aessage text as a character string between
single quotes. single quotes appearing in the aessage text should be
coded as two single quotes. This paraaeter is coded as follows:
TBXT=lmessage-textl
If the TEXT
coded.

Paraaeter is

coded, the

TEXTA parameter

must not

This parameter is an alternative to the TEXT parameter.
It specifies
the address of the message text. The aessage text consists of a
one-byte length field, followed by the actual text of the message. The
parameter is coded as follows:
TBXTA=ad4ressl (reg)
If used in the standard or list for. of the aacro, the "address" is
used in an address constant. The "(reg)" form then may not be used. If
used in the execute fora, the "address" is obtained by a Load Address
(LA) instruction. If the "(reg)" form is used, then the specified
register (other than registers 1 and 15) contains the address of the
message text area. If the TBXTA parameter is coded, the TEXT parameter
aust not be coded.

This parameter specifies how multiple blanks in the message are to be
handled. With CO!P=YBS, the default, the LIIEDIT routine compresses all
aultiple blanks in the message into a single blank.
If CO!P=IO is
coded, this coapression is not done.

The DOT paraaeter indicates whether the end of the message will have a
period. with DOT=YES, the default, the LIIEDIT routine places a period
(dot) at the end of the message. If DOT=IO is coded, this is not done.

This paraaeter is used to specify a sUbstitution list that allows a
message to have a value substituted into it at execution time. Whenever
the LIIEDIT scanning routine discovers two or more consecutive periods
in the message text, it assumes that a substitution is to be made.
380

IS! '!/370: Co •• and Language Guide for General Users

LIBEDIT ftACBO
The number of consecutive periods indicates the length (or
length) of the substituted field, after conversion, if any.
parameter is coded as follows:

maximull
The SUB

where each "type,value" pair specifies the type and value
SUbstitution. possible "type,value" substitutions are:

the

HBI, (reg)
The value in the specified register (other than registers 1 and 15)
is to be converted to graphic hexadecillal form. If fewer than eight
consecutive periods are coded in the message text, then leading
digits will be truncated. Leading zeros are not automatically
truncated.
HBI,expression
The given expression, which will be evaluated by means of a Load
Address (LA) instruction, is converted as indicated above into
graphic hexadecimal form.
HBIA ,address
The "address" specifies a fullword that is to be converted to graphic
hexadecimal, as above.
HEIA, (reg)
The register (other than registers 1 and 15) points to a fullword
that is to be converted to graphic hexadecimal form, as above.
DEC, (reg)
The value in the specified register (other than registers 1 and 15)
is to be converted to graphic decimal form and inserted into the
aessage text.
Leading zeros will be suppressed. If the nUllber is
negative, then a leading minus sign will be inserted.
DEC, expression
The given expression, which will be evaluated by means of a Load
Address (LA) instruction, is converted as indicated above into
graphic decillal.
DECA,address
The "address" specifies a
graphic d~cimal, as above.

fullword which

be converted

nBCA, (reg)
The specified register (other than registers 1 and 15) contains the
address of ~ fullword that is to be converted to graphic decimal, as
above.
HBl4A,address or HBI4A,(reg)
Is used for graphic hexadeciaml dumps of other than fullwords. The
"a4dress" (or a register other than 1 or 15) points to the first byte
to be converted to graphic hexadecimal for..
A blank is inserted
into the message text after each four characters of input (eight
characters of output) have been coverted. Thus, if an 8-byte input
field (16 hexadecimal digits) is to be converted, 17 periods should
be coded.
The output field length is deterllined by the number of
periods in the message text. The length, in bytes, of the field to
be converted may be specified as follows:
HBI4A, (address I (reg) ,length I (reg»
Appendix D: CftS ftacro Instructions

381

LINEDIT !!ACBO
CBlBl,address or CBlRl,(reg) The "address" (or a register other than 1
or 15) points to the first byte of a field that is to be substituted
as a character string. The output field length is deterained by the
number of consecutive periods in the message text. The length, in
bytes, of the field to be substituted .ay be specified as follows:
CBlBl, (address I (reg) , length I (reg»
CBAB8A,address or CBlR8l, (reg) Is useful if a string of PLIST arguaents
(for exallple, a fileid) is to be substituted into the message text.
LIIEDIT will insert a blank after
each 8 characters of the
substitution string. Thus, to substitute an 18-byte fileid, code 20
periods in the message text, to allow for the inserted blanks. The
"address" (or a register other than 1 or 15) points to the first byte
of the input substitution string. The length, in bytes, of the input
string may be specified as follows:
CBAB8A,(addressl (reg),lengthl (reg»
Note that registers 1
length specification.

and 15

may not

be used

for the

address or

This option specifies what LINEDIT is to do with the message
has created. Specifications for the DISP parameter are:

which it.

DISP=TYPE (the default) specifies that the message is to be typed on the
terminal using TYPLIN.
DISP=SIO specifies that the message is to be typed at the terainal using
SIO. This option is necessary if, for example, free storage pointers
are destroyed. No CONWAIT function is performed.
DISP=NONE specifies that no output whatsoever is to occur.
is useful with the BUPPA parameter, described below.
DISP=PRINT specifies that
printer.

the line

is to

be printed

This option

on the

virtual

DISP=CPCO!!!! specifies that the line is to be passed to CP to be executed
as a CP console co.mand.
DISP=ERR!!SG specifies that the line is to be checked to see if it
qualifies for "error message editing". If it does it is displayed as
an error aessage rather than a regular line.
The first ten characters of the line are the "code" and the rest of
the line is the "text" of an error aessage. In a standard V!!/370
error message, the code of an error message is in the following
format:
mmmmllllnnnt
where amll •• a is the nalle of the 1I0dule issuing the lIessage, nnn is
the lIessage number, and t is the lIessage type. With LIIEDIT, you can
code error messages for your own programs. You need not follow the
V!!/370 conventions for the first nine characters of the code, but the
tenth character must specify a recognized V!!/370 aessage type if
error message editing is to occur. The recognized types are:
382

IB!! V!!/370: Com.and Language Guide for General Users

LINBDIT MACRO
Tenth Character of
.§!§§~L1ine
I
Ii

Me~g~L1IE!

IIPORMATION
liARNIIG
BRROR

If one of these letters is the tenth character in the line, the line
will be typed in accordance with the current BMSG conditions that are
controlled by the CP SET EMSG command. If the tenth character is
anything else, the entire line will be typed as a regular line, with
no distinction aade between code and text.

This parameter specifies
follows:

the

address of

a buffer.

is coded

BUPPA=address I (reg)
If a register is specified, it must not be register 1 or 15.
If this option is specified, then, in addition to the action
specified by the DISP paraaeter, the message text is copied into the
buffer at the specified address.
The length of the text is inserted
into the first byte of the buffer, and the message text into subsequent
bytes.

The "standard" fora of the LIIBDIT macro generates reentrant code unless
one of the following is true:
•
•
•

TBITA=(reg) is specified.
BUPPA=(req) is specified.
More than one substitution pair is specified.

If reentrant code is not generated, and REIT=YES (the default) is in
effect, the LIIEDIT macro expansion contains an MNOTE stateaent warning
the user that nonreentrant code is being generated. If the user does
not object to nonreentrant code, and does not wish to have the MIOTE
appear, he should code REIT=BO.
The REIT=IO coding aerely suppresses
the BIOTE statement; it has no effect on the expansion of the LIBEDIT
aacro.

T~is paraaeter is used only in the
list fora (BP=L) of the macro, which
is used to reserve space.
It
specifies the maximum nuaber of
substitutions to be aade, so that enough space for those sUbstitutions
can be reserved. It is coded:

ftAISUBS=nuaber
Appendix D: CftS ftacro Instructions

383

tIIEDIT !ACBO
tIIEDIT CODIIG EXA!PLES
The following exaaples illustrate some options of the tIIEDIT aacro.
Because of the liaitations of space, soae of the longer coding exaaples
appear on
two lines.
However, normal
coding conventions
for
continuation stateaents should be used in actual coding.

Bxaaple 1
The siaplest use of the tIIEDIT aacro is to type
substitutions whatsover.
LIIEDIT TBIT='THIS
causes the following
executed:

IS
be

a aessage without any

LIIE'

typed out

the

terminal when

THIS IS ALliE.
lote that aultiple blanks are reaoved
is placed at the end of the line.

from the message, and a period

Exa.pl!·~

The real pover of the LIIBDIT aacro is in the capability of making
substitutions.
Whenever the LIIEDIT processor finds two or aore
consecutive periods in the aessage text, it aakes a substitution fro.
the 'SUB' list provided in the aacro call.
To illustrate the siaplest type of substitution, using
option, suppose the following is executed:
LIIBDIT TEXT='TBB VALUB IS
SUB=(DEC,VALUE+5)

the

DEC

....... •,

If the Asseabler language program contains a stateaent of
"VALUE EQU 2003", then when this aacro is executed, the line,

the fora

THB VALUB IS 2008.
is typed at the terainal.

Usually soae value coaputed during
execution of the program is
requested. To type out the contents of a register, the following can be
used:
LIIEDIT TEXT='VALUE = •••••• ·,SUB=(DEC,(3»
If, when this macro is executed, register 3 contains the
value 10345, then the following line is typed out:
VALUB = 10345.

384

IB! V!/310: Coaaand Language Guide for General Users

decimal

LIIEDIT "ACBO
!.!aIBP1! ~

The DECA option is used to specify the address of a fullword in storage
which contains the value to be typed out. The address of evaluated by
'means of a Load Address (Ll) instruction. Execution of:
LIIEDIT TEXT='VALUE = •••••• ·,SUB=(DECA,LOC)
would cause the value in the fullword at location LOC to be typed out in
decimal format.
Similarly, the macro call
LINEDIT TEXT='VALUE = •••••• ·,SUB=(DECA,(3»
would cause the value in the fullword
be typed out in decimal.

whose address is in register 3 to

lote: AS the exaaples given show, when the keyword (such as DEC) does
D2i--end in an '1', then a y~ is being specified as the next
argument. When the keyword (such as DECA) ~ end in '1', then the
~gg~~~~
of a value is being specified. When the next argument is
enclosed in parentheses, the value or address is to be found in the
register, other than 1 or 15, that vas specified.

The number of consecutive periods appearing in the message text is
usually significant. In DEC and DECA, it indicates the maximum number
of characters (including the minus sign) which will appear in the
number. If the number is too large to fit in the field, then high-order
digits will be truncated.
To be certain that high-order digits will never be truncated, code
ten periods in the message text for DEC and DECA, as in:
LIIEDIT TEXT='VALUE = ••••••••••• ,
SUB= (DEC, (3»

I!Yl!le ~

The HEX option is similar in use to the DEC option, except that the
substituted values are typed out in hexadecimal rather than in decimal.
Execution of:
LIIEDIT TEXT="'LOC"
SUB=(HEX,LOC)

IS LOCATED AT

......

would cause the value of LOC to be substituted in hexadecimal format, so
that the following might be typed out:
'LOC' IS LOCATED AT 0201AC.
lote that the leading zeros are not removed.

Appendix D: C"S "acro Instructions

385

LINEDIT ftACRO

Parentheses are used to type out the current value of a register in
hexadecimal. Par example, if register 3 contained the value C0031PC8,
then the macro
LINEDIT TEXT='VALUE = ••• ·,SUB=(HEX,(3»
would cause the line,
VALUE = PC8.
to be typed out. Notice that since three periods were specified, just
the last three hexadecimal digits of the register contents were typed
out.

The HEXA option is used if the address of a fullword
containing the desired value is specified. Execution of:

storage

LINEDIT TEXT='HEI VAL = ••••• ·,SUB=(HEIA,VAL)
will cause the last five hexadecimal digits of the fullword at VAL to be
substituted into the message text.
And if
LINEDIT TEXT='HEI VAL = •••••• ·,SUB(HEXA,(5»
is executed, then the last six hexadecimal digits of the fullword whose
address is in register 5 will be substituted.
I~ampl~ ~

The BEX4A option is used for dumping a variable number
storage on the terminal. The dump has the format:

of bytes

hhhhhhhh hhhhhhhh hhhhhhhh hhhhhhhh ••••
where each "h" stands for a hexadecimal digit. The number of periods in
the message text specifies the size of the output fieid and, hence,
indirectly specifies the number of bytes of "input" data to be
converted.
Each byte of input data is converted into two hexadecimal digits for
substitution. After each four bytes of input (eight bytes of output), a
blank is inserted. Thus, if a dump of seven bytes of data in this
format is requested, 15 periods must be coded. The extra period is for
the blank to be inserted. The macro,
LINEDIT TEIT='VALUES ARE ••••••••••••••••• ,
SUB=(BEI4A,(6»
would cause a line to be displayed as follows:
VALUES ARE OA23P115 78ACPE.
where the values being dumped start at
register 6.

386

the address that is specified in

IBft V8/370: Command Language Guide for General Users

LINEDIT MACRO
~.!amp!!

'!'Q

The CHARA option is used to .ake a straight character substitution. The
number of 'periods indicates the nu.ber of characters to be substituted:
LINEDIT TEXT=!NA~E IS
SUB=(CHARA,LOC)

!! •••••••••• ,

would cause the seven characters starting at location
substituted into the text, to produce a message such as:

LOC

NAME IS 'LUCIIDA'.
Multiple blanks in the sUbstituted string will be removed.

!~ID!E!!

The CHIR8A option is siailar to the CHARA option, except that a blank is
inserted into the output text after each group of eight characters.
This is particularly useful for dumping PLISTs, since a blank is
inserted after each doubleword in the PLIST. Por example,
LIIEDIT TEXT='PILE •••••••••••••••••••• lOT
POUID',SUB=(CBAR8A,PLIST+8)
could cause the following output:
PILE X ASSE8BLE A1 lOT POUID.
Note that 20 periods were coded, to include space for the two
inserted blanks. In the final edited line, multiple blanks are reduced
to a single blank.
If the CHARA option had been used, with 18 periods
specified, then the same message would have appeared as:
PILE X ISSE8BLEA1 lOT POUND.

To make several sUbstitutions in a given line, it is necessary only to
code several groups of periods in the message text, and several pairs of
substitution values in the SUB parameter list.
The following macro:
LIIEDIT TEXT='VALUES ARE ••••• AND
SUB=(DEC,(3) ,HEXI,LOC)

...... , ,

would generate a line like the following:
VALUES ARE -45 AND PPE3C2.
Each group of periods represents one substitution, and
SUB arguments represents one value to be substituted.

each pair of

Appendix D: CMS Macro Instructions

387

LI NEDIT "ICRO

To reserve space in a work area for a LINEDIT PLIST, the "list" form of
the LIBEDIT macro (ftl=L) must be used. Specifying
LINLIST LINEDIT ftl=L,ftAXSUBS=6
will reserve space for a LIBEDIT PLIST, and give that space the label
ILINLISTI. The parameter IftAXSUBS=6 1 indicates that enough space is to
be reserved so that a PLIST with space for six or fewer sUbstitution
pairs can be built.
If a larger ftlXSUBS value is specified, then a larger amount of space
is reserved for PLIST contruction.

The execute form of the LIBEDIT macro does not generate a PLIST as part
of its expansion, as does the standard form.
(Examples 1 through 12 use
the standard form of the macro.) Instead, the execute form expands to
create a PLIST in a work area. The space for the PLIST should have been
reserved using ftl=L as indicated in Example 13. To call LIBEDIT after
creating a PLIST in the work area reserved by the LINEDIT macro in the
last example, the following form could be used:
LINEDIT Ml=(E,LIBLIST),other options •••
The "other options" may be any of the options discussed in preceding
examples, including TEXT and SUB parameters.

!~~E!~

~~~i!Ii~g §Y~§~itu~!g~ J~ngth

-- In all the examples shown, the length
of the argument being substituted was determined by the number of
periods in the message text. The number of periods indicated the size
of the output field, and indirectly determined the exact size of the
input data area. sometimes it is desirable to determine at execution
time the size of the input data area.
These sizes can
conversion types.

specified with

the

CBIRA,

CBAR81, and

BEX41

The following substitution list might appear in a LINEDIT macro:
SUB=(CBIRA,LOC,BEX4A, (3»
When specified in this manner, the lengths of the input data fields
are determined by the number of periods in the message text. To specify
the length of the input data field, the following alternative form may
be used:
SUB=(CBARA, (LaC, (4» ,BEX41, «3), (5»)
In the latter format, where each substitution pair has the form
"type, (address,lengt~", register 4 is specified as containing the
length of the data area at location LaC, and register 5 is specified as
containing the length of the data area pointed to by register 3.
388

IBM Vft/370: Command Language Guide for General Users

LIIEDIT !tACBO
~!~E!! 1~

specifying a length is particularly useful in the special case where
only one character is to be changed in a CHABA substitution.
To do
this, two periods aust be coded into the message, and a length of one
aust be specified, as in the exaaple:
LIIBDIT TBIT=IILLEGAL !tODB LETTEB
SOB=(CBABA,(PLIST+24,1»

Th~ single letter (length=l) at location PLIST+24
the field consisting of two periods.

sUbstituted into

lote: 10 matter what input length is specified, the final substituted
result cannot be longer than the nuaber of periods in the aessage text.
If the input field length and the output length (specified by the nuaber
of consecutive periods) conflict, the output length will govern, and the
input length will be truncated accordingly.

Appendix D: C!tS !tacro Instructions

389

PRINTL "ACRO

PBINTL Macro

The PRINTL macro causes a line to be written to a virtual printer.
I.QR"AT:
1

[label] I PRIITL I line [,length] [,ERROR=erraddr] I

label

is an optional statement label.

line

specifies the line to
forms:

length

erraddr

be printed.

It may be in

one of three

'linetext'

text enclosed in quote marks.

lineaddr

the sy.bolic address of the line.

(reg)

a register containing the address of the line.

specifies the length of the line to be printed. If omitted,
133 is assumed unless the text is enclosed in quotes. In this
case, the number of characters between the quotes is used.
The length may be specified in two ways:
(reg)

a register containing the length.

a self-defining term indicating the length.

The PRINTL macro causes the specified line to be written to the printer.
The maximum length allowed is 151 characters if printing on a virtual
3211 or 133 characters if printing on a virtual 1403. The first
character in the line is used as the carriage control character. It
must be ASCII control character code or a machine carriage control code
other than I'Cl' or I'C3'.
Since I'Cl' and I'C3' are valid for both
ASCII control character and machine carriage control code, if coded,
they are interpreted as ASCII control character codes.
If a valid
control character is not specified, a write command with a carriage
control character to space one line after printing is used.
The valid ASCII control characters are as follows:
1!!!!_~Qg.!

40
PO

390

60
41

"eani.!!,9
Space 1 line before printing
Space 2 lines before printing
Space 3 lines before printing
Suppress space before printing

IB" VM/370: Co •• and Language Guide for General Users

GC20-1804-3 Page Modified by TNL GN20-2659
PRINTL MACRO
fh~X2£1~I

~~!_fQ~g

1
2

F1
F2

3
4
5

6
7
8
9
A

F3
F4
F5
F6
F7
F8
F9
Cl

B
C

C2
C3

Mc~n;nrr

Skip
Skip
Skip
Skip
Skip
Skip
Skip
Skip
Skip
Skip
Skip
Skip

.:.:~..::::.:.:=!!~

to
to
to
to
to
to
to
to
to
to
to
to

channel 1
channel 2
channel 3
channel 4
channel 5
channel 6
channel 7
channel 8
channel 9
channel 10
channel 11
channel 12

1
2
3
4

100

11~g!!!!!g

Line too long.
Channel 12 punch sensed (virtual 3211 only).
Channel 9 punch sensed (virtual 3211 only).
Intervention required.
Unknown error.
Printer not attached.

Note: If the error was a result of sensing a channel 9 or 12 punch while
writing to a virtual 3211 using ASA control characters, the operation
terminated after the carriage movement but before writing the line. In
order to avoid an extra blank line, the print buffer should be rewritten
using the 01 channel command code (write without spacing).

Appendix D: CMS Macro Instructions

391

PUNCHC MACRO
PUNCHC Macro

The PUNCHC macro causes a line to be written to a virtual card punch.
XQ!Ht!~

r-----------------------------------------,
I [label] I PUNCHC I line [, ERROR=erraddr] I
----------'

'--

label

is an optional statement label.

line

specifies the line to
forms:

erraddr

be punched.

It may be in

one of three

'linetext'

text enclosed in quote marks.

lineaddr

the symbolic address of the line.

(reg)

a register containing the address of the line.

specifies the address of an error routine to be given control
if an error is encountered.
If ERROR= is not coded, control
returns to the next sequential instruction in the calling
program if an error occurs, as it does if no error occurs.

!!.§!g~:

The PUNCHC macro causes the specified line to
punch. No stacker selecting is allowed.
The
characters.

be written to the card
line length must be 80

If an error occurs,
processing terminates, and control is passed to
erraddr (if one was provided) or back to the calling program's next
sequential instruction. Register 15 contains one of the following error
codes:
£2g~

2
3

100

392

~~~!!'!!!.9

Unit check.
Unknown error.
Punch not attached.

IBM VM/370: Command Language Guide for General Users

RDCARD l!ACRO
RDCARD Macro

The RDC1RD macro causes a line to be read from a virtual card reader.

I [label]

RDCARD I buffer [, length] [, ERROR = erraddr]

label

is an optional statement label.

buffer

specifies the buffer address into which
read. It may be either of two forms:
bufaddr
(reg)

length

to be

the symbolic address of the buffer.
a register containing the address of the buffer.

specifies the length of the card to be read. If omitted, 80
is assumed. The length may be specified in one of two ways:
n

(reg)
erraddr

the card is

a self defining term indicating the length.
a register containing the length.

specifies the address of an error routine to be given
control if an error is encountered. If EBBOR= is not coded,
control returns to the next sequential instruction in the
calling program when an error occurs, as it does if no error
occurs.

The RDCARD macro causes a line to be read from the card reader. No
stacker selecting is allowed. On return register 0 contains the length
of the card read.

3
5
100

~~~.!!ing

End of file.
unit check.
Unknown error.
Length not equal to requested length.
Device not attached.

Appendix D: Cl!S l!acro Instructions

393

RDTAPE !ACRO
RDTAPE Macro

The RDTAPE
drive.

aacro causes

[label]

a record to

be read

froa the

specified tape

buffer,length [,device] [,80DE=aode]
[ , ERROR=erradr ]

RDTAPE

label

is an optional statement label.

buffer

specifies the buffer address into which the record is
read. It aay be specified in either of two ways:

length

device

aode

to be

lineaddr

the symbolic address of the buffer.

(reg)

a register containing the address of the buffer.

specifies the length of the record to be read. A 65,535-byte
record is the largest record that can be read. It may be
specified in either of two ways:
n

a self-defining tera indicating the length.

(reg)

a register containing the length.

specifies the
oaitted, TAP 1
two forms:

device from which the line is to be
is assumed. It may be specified in

TAPn

cuu

indicates the virtual device address.

read. If
either of

indicates the symbolic tape number.

specifies the number of tracks, density, and tape recording
technique options. It must be in the following form:
([ track], [ density], [trtch])
track

1
9

indicates a 1-track tape (implies density=800 and
trtch=O) •
indicates a 9-track tape (implies density=800) •

density

200, 556, or 800 for a 1-track tape.
800 or 1600 for a 9-track tape.

trtch

indicates the
1-track tape.
specified:

OC
OT
E
IT

394

tape recording
technique for
One of the following must be

odd parity, converter off, translator off.
odd parity, converter on, translator off.
odd parity, converter off, translator on.
even parity, converter off, translator off.
even parity, converter off, translator on.

IB! V8/310: Coaaand Language Guide for General Users

RDTAPE MACRO
!Q~~:

Mode need not be specified for a read
operation to a 9-track tape or to an 800 BPI odd
parity 7-track tape with the Data Converter and
the Translator off.

erraddr

specifies the address of an error routine to be given control
if an error is encountered. If ERROR= is not coded, control
returns to ~ne next sequent1ai instruction in the calling
program if an error occurs, as it does if no error occurs.

The RDTAPE macro causes a record to
drive. On return, register 0 and the
contain the number of bytes read.

be read from the specified tape
eighth word of the parameter list

2
3

4
5

~~!~!~~

Invalid function or parameter list.
End-of-file or End-of-tape.
Permanent I/O error.
Invalid device ide
Tape not attached.

Appendix D: CMS Macro Instructions

395

GC20-1804-3 Page Modified by TNL GN20-2659
RDTERM MACRO

RDTERM Macro

The RDTERM macro causes a line to be read from the user's terminal.

-------------------------,

.-I
I [label]
I
I

RDTERM

buffer [,EDIT=codeJ

[LENGTH=lengthJIATTREST=ll~21

I
II

INO III

L
________________________________________________________

L ____
.J.J J
__

L-

label

is an optional statement label.

buffer

specifies the address of a 130-character buffer into which the
line is to be read.
It may be either of two forms:
lineaddr

the symbolic address of the buffer.

(reg)

a register containing the address of the buffer.

specifies the type of editing, if any, to be performed on the
input line.
If this is not coded, YES is assumed.

code

indicates that a logical line is to be
editing is to be done.

read and no

PAD

requests that the input line be padded
to the length specified.

with blanks

UPCASE

requests that the line be translated to upper case.

YES

indicates PAt+UPCASE.

PHYS

indicates that a physical line is to be read.
When
PHYS is specified, the LENGTH and ATTREST operands
may also be entered.

length

specifies the length of the caller's buffer area.
specified, 130 is assumed. When EDIT=PHYS, as many
bytes may be read.

If not
as 2030

ATTREST=

specifies the handling of an attention signal during a read
operation.
The normal handling
(ATTREST=X]2) is to restart
the operation.
If EDIT=PHYS and an explicit LENGTH is given,
NO may be specified.
In these cases, an attention signal is
treated as a normal end of the operation.

The RDTERM macro causes a line to be read from the user's terminal.
return, register 0 contains the number of characters read.

When an
codes:

396

error occurs, register 15

contains one of the

IBM VM/370: Command Language Guide for General Users

following error

GC20-1804-3 Page Modified by TNL GN20-2659
RDTERM MACRO

An invalid parameter was given.

The read was terminated by an attention signal.
when ATTREST=NO

possible only

Appendix D: CMS Macro Instructions

396.1

REGEOU ftACRO
REGEQU Macro

The REGBOU macro equates symbolic
names to
floating-point, and extended-control registers.

the

general-purpose,

!.Qnll:
RBGEOU

The RBGBOU macro causes the following equate statements to be generated.
The symbolic names may be used as register specifications in assembly
language stateaents. The register usage will then appear in the cross
reference listing.
General Registers:
RO
Rl
R2
R3
R4
R5
R6
R1
R8
R9
Rl0
Rl1
R12
R13
R14
R15

EQU
BQU
EQU
BOU
BQU
EOU
BOU
EQU
BQU
EOU
EQU
BOU
BOU
BQU
BOU
EOU

Bxtended-Control Registers:
0
1
2
3
4
5
6
1
8
9
10
11
12
13
14
15

CO
Cl
C2
C3
C4
C5
C6
C1
C8
C9
Cl0
Cll
C12
C13
C14
C15

EQU
BQU
EOU
BOU
BQU
EQU
EQU
EOU
BOU
EOU
BOU
EOU
EOU
EOU
EQU
BOU

0
1
2
3
4
5
6
1
8
9
10
11
12
13
14
15

Floating=point Registers;
FO
12
14
16

EQU
BOU
EOU
BQU

0
2
4
6

Appendix D: CftS ftacro Instructions

391

T1PECTL !ICRO
TAPECTL Macro

The TIPECTL macro causes the specified tape to
to the specified function code.

be positioned according

l[label]ITIPECTLlfunction [,device][ ,!ODE=mode][,ERROR=erraddr]1
,

label

is an optional statement label.

function

specifies the control function to
one of the following codes:
~Qg~

must be

A£!i2!

Rewind the tape.
Rewind and unload the tape.
Erase a gap.
Backspace one record.
Backspace one file.
Forward space one record.
Forward space one file.
write a tape mark.

REW
RUB
ERG
BSR
BSF
FSR
FSF
WT!
device

be performed.

specifies the tape on which the control
performed. If omitted, TAP1 is assumed.
of two foras:

operation is to be
It may be in either

indicates the symbolic tape number.

TAPn

cuu

indicates the virtual device address.

specifies the number of tracks, density, and tape recording
technique options. It must be in the following form:

mode

([ tr ack], [ density], [trtch])
track

7
9

indicates a 7-track tape (implies density=800 and
trtch=O).
indicates a 9-track tape (implies density=800).

density

200, 556, or 800 for a 7-track tape.
800 or 1600 for a 9-track tape.

trtch

indicates the
7-track tape.
specified:
a
OC
aT
E
ET

erraddr

398

tape recording
technique for
One of the following must be

specifies the address of an error routine to be given control
if an error is encountered. If ERROR= is not coded, control
returns to the next sequential instruction' in the calling
program if an error occurs, as it does if no error occurs.

IBK VK/370: Co •• and Language Guide for General Users

TAPECTL BACRO

The TAPECTL macro causes the control
specified tape drive.

operation to be performed

on the

If an error occurs, processing terminates, and control is passed to
erraddr (if one was provided) or back to the calling progra.'s next
sequential instruction. Register 15 contains one of the following error
codes:
~~g~

2
3
4

5
6

~~~~i~

Invalid function or parameter list.
End-of-file or End-of-tape.
Permanent I/O error.
Invalid device ide
Tape is not attached.
Tape is file protected.

Appendix D: CftS Bacro Instructions

399

iAITD IUCRO

WAITDMacro

The iAITD macro causes the program
occurs for the specified device.

to wait

until the

next interrupt

I [label]

WAITD I device ••• [,devicen] [,Error=erraddr]

label

is an optional statement label.

devicen

specifies the device(s) to
following may be specified:
symn

indicates
where:

the

symbolic

waited
device

for.
name

One

the

and

number,

sym is COB, DSK, PRT, PUB, RDR, or TAP.
n
user
erraddr

indicates the device number.

a name of up to four
previous HBDIBT macro.

characters

specified in

The WAITD macro causes the program to wait for an interrupt from one of
the specified devices.
It should be issued to ensure completion of an
I/O operation. If an interrupt has been received and not processed from
a device specified in the WAITD macro (the when parameter in the HBDIBT
macro had to be WAIT) the interrupt for the device will be entered.
When the interrupt has been completely processed, control will be
returned to the caller with the name of the interrupting device in
Register 1.
If an interrupt has been received and processed from a
device specified in the WAITD macro (the when parameter in the HBDINT
macro has to be ASAP)
the wait condition is considered satisfied and
return to the caller is made as previously described.
An interrupt received from a device specified ASAP in an HBDINT macro
will be handled. Processing this interrupt will satisfy a WAITD issued
later for that device.
The interrupt routine determines if an interrupt is considered
"processed" or if more interrupts are necessary to satisfy the wait
condition.
Por
additional
information see
the
HNDIBT
macro
documentation.

When an error is detected, register 15
invalid device number was specified.

qOO

contains a 1 to indicate that an

IBM VM/370: Command Language Guide for General Users

WAT'I'T MACRO
WAITT Macro

The WAITT macro causes the program to wait until all of the pending I/O
operations to the user's terminal are completed.

I [label]

•

label

WAITT
is an optional statement label.

The WAITT macro is used to synchronize terminal I/O operations.

lone.

Appendix D: CMS Macro Instructions

401

WRTlPB BlCBO
WRTAPE Macro

The iBTlPB
drive.

macro causes a

[label]

record to be

written on the

buffer,length [,device]
[,BODE=aode) [,BRROR=ERRlDDR]

iRTlPB

label

is an optional statement label.

buffer

specifies the address of the record
in either of two foras:

length

It may be

the symbolic address of the line.

(reg)

a register containing the address of the line.

specifies the length of the line to
specified in either of two ways:

be written.

.ay be

a self-defining term indicating the length.

(reg)

.ode

to be written.

lineaddr

device

specified tape

a register containing the length.

specifies the device to which the record is to be written. If
omitted, TlPl is assumed. It may be in either of tvo forms:
indicates the symbolic tape number.

TlPn

cuu

indicates the virtual device address.

specifies the number of tracks, density, and tape recording
technique options. It must be in the following form:
([track], [density], [trtch])
track

7
9

indicates a 7-track tape (implies density=800 and
trtch=O).
indicates a 9-track tape (implies density=800).

density

200, 556, or 800 for a 7-track tape
800 or 1600 for a 9-track tape.

trtch

indicates the
7-track tape.

tape recording
technique for
One of the following must be

~pecified:

OC
OT
I
ET

erraddr

402

specifies the address of an error routine to be given control
if an error is encountered. If ERROR= is not coded control
returns to the next sequential instruction in the calling
program if an error occurs, as it does if no error occurs.

IBft Yft/310: Co •• and Language Guide for General Users

WRTAPE MACRO

The WRTAPE
drive.

macro causes a

record to be

written to the

specified tape

If an error occurs,
processing terminates,
and control is passed to
erraddr (if one was provided) or back to the calling program's next
sequential instruction. Register 15 contains one of the following error
codes:
Code
--1-

2
3

4
5
6

~~g~i~g

Invalid function or parameter list.
End-of-tape or End-of-file.
Permanent I/O error.
Illegal device ide
Tape not attached.
Tape is file protected.

Appendix D: CMS Macro Instructions

403

GC20-1804-3 Page Modified by TNL GN20-2659
WRTERM MACRO

WRTERM Macro

The WRTERM macro causes a line to be displayed at the user's terminal.

I [label]
I

WRTERM

line [,length] [,EDIT=code ]
[ ,COLOR=color ]

L-

label

is an optional statement label.

line

specifies the
forms:

length

code

line to be displayed.

It may be one

of three

'linetext·

text enclosed in quote marks.

lineaddr

the label on the statement containing the line.

(reg)

a register containing the address of the line.

specifies the length of the line.
If the line is specified
within quote marks in the macro, the length parameter may be
omitted. The length may be specified in either of two ways:
n

a self defining term indicating the length.

(reg)

a register containing the length.

specifies whether the line is to be edited:
YES

indicates that trailing blanks are to be removed
carriage return added to the end of the line.

indicates that trailing blanks are
no carriage return is to be added.

and a

net to be removed and

LONG indicates the line may exceed 130 bytes, and is to be
transmitted from the caller's buffer area. No editing is
performed.
color

404

indicates in which color the line is to
typewriter terminal has a two-color ribbon:

typed if

indicates that the line is to be typed in black.

indicates that the line is to be typed in red.

IBM VM/370: Command Language Guide for General Users

the

GC20-1804-3 Page Modified by TNL GN20-2659
WRTERM MACRO

The WRTERM macro causes the specified line to be displayed at the user's
terminal. The maxi.um line length is 130 characters for a black line
and 126 characters for a red line.
If EDIT=LONG, COLOR must be given as
'B'. In this case, as .any as 1760 bytes may be sent with a single
WRTERM macro. The caller is responsible for properly embedding terminal
control characters in the data, and for the inteqritv of the data from
issuance of WRTERM until the data has been sent.-The-WAITT macro may be
used to ensure that I/O is complete before the buffer is modified.

None.

Appendix D: CMS Macro Instructions

404.1

Appendix E: Disk Determination (Filemode Management)

Figure 47 relates CMS commands, method of
specifying filemode, and the criteria used
in choosing a disk directory for reading
and writing. Symbols used in the table
are:
~yllbo1

command
fm

11.§~.!!.!.!!.9

Command
ACCESS

N/A
N/A

ASM3705

R,1W,*W

Explicit mode
specified

letter

can

ASSEMBLE

R,1W,*W

BASIC

R,1W

COBOLI

R,1W,*W
N/A
N/A

Refer to all
search order

disks

Default
mode:
let
determine the mode

set

system

fm
*R

CONVERTI

COPYFILE

fm
N/A
*R

N/A

DEBUG

N/A

fm
*R
1R
N/A

N/A
N/A
N/A
1W

fm
*R
1R

N/A
N/A
N/A

fa
*w
1W

N/A

fm
1R
*R
N/A

fm
1W
N/A
fm

COMPARE

The criteria for choosing
disk from which to read

N/A

Not applicable, co.mand does not
cause any reading to be done

DIRECT

Read from the specified disk

DISK DUMP

Refer
to all
disks
standard search order

the

*
d

the

Read only from the primary disk

Reading

mode
d

DISK LOAD
EDIT

*
d

*cuu

All occurrences of the address

writing

Indicates criteria for selecting
the disk to write onto

N/A

Not applicable, command does not
cause any writing to be done

EXEC

Write onto the specified disk

FILEDEF

ERASE

fm
d

write onto the disk from which a
file was read (or its parent)

Writing

fm
1R

Null mode; unable to specify mode
letter in this command

Filemodel Reading

CMS command name

write disk to Read disk

r------------------------------------------~

FORMAT

*
mode

N/A

R
R

FORTGII

FORTHXI

FORTRANI

write to the specified address

GBN3705

*WS

First read/write disk with enough
space

GENDIRT

N/A

First disk where file is found if
disk is in read/write status

Choose any read/write disk in the
standard search pattern

Attempt to write onto the primary
disk

cuu

IIBM Program Products
Figure 47. Disk Determination (Part 1 of 3)

Appendix E: Disk Determination (Filemode Management)

405

I Command

Filemodel Reading

writing

Comlland

N/l
N/l
N/l

fll
1W
1W

REN1ME

GLOBIL

N/l

RUN

GOFORTl

R,*W

INCL UDE

GENMOD

fll
*
d

LISTDS

Writing

fm
*R
N/l

fll
N/l
R

fm
*
d

fm
*R
1R

N/l
N/l
N/l

SlVENCP

N/l

SCRIPT2

SET

N/l

fm
.R

fm
R,1W

N/l

N/l
N/l
N/l

N/l

fll
*

fm
*R
1R

1W
1W
1W

LKED

R,1W,*W

LOID

LOIDMOD

*R
fm

N/l
N/l

MICLIB

R, 1 W

SVCTR1CE

MODM1P

N/l

SYNONYM

MOVEFILE

N/l

fm
*
d

fll
*R
1R

N/l
N/i
N/l

NCPDUMP

T1PE DUMP

PLICl

R,1W,*W

PLICRl

R, 1W, *W

fm
*
d
fm
d

PLIOPTl

R,1W,*W

fm
*R
1R
N/l
N/l
N/l
N/l

N/l
N/l
N/l
fm
1W
N/l
N/l

fm
d

N/l
N/l

fm
1W

TESTCOBl
TESTFORTl

*R
*R

R,1W,*W
*L,*WS

TITLIB

R,1 W

fm
*
d

fm
*R
1R

N/l
N/l
N/l

fm
d
*

*R
fm
1R
*R
*R

R,1 W
fm,R,1W
1W
R,1W
R,1 W

LISTFILE

fm
*
d

Filemodel Reading

SORT
ST1RT
STITE

T1PE LOID

fm
d
*

fm
1R
*R

N/l
N/l
N/l

PUNCH

fll
d
*

fm
1R
*R

N/l
N/l
N/l

N/l

TYPE

fm
d
*

N/l
N/l
N/l

fm
1W
1W

UPDITE

mode

*cuu
fm

REIDC1RD

RELE1SE

fm
*
d

TIPE SC1N
TIPE SKIP

QUERY

fm
*

T1PPDS

cuu
fm
VSB1SICl

lIEM Program Products
ZAP
Figure 47. Disk Deterllination (Part 2 of 3)

lIBM Program Products
2IBM User Installed Program
Figure 47. Disk Determination (Part 3 of 3)

406

IBM VM/370: Command Language Guide for General Users

Appendix F: Reserved Filetype Descriptions

Figure 48 shows filetypes that have special uses in CMS.
Format
Filetype

Command

ASSEMBLE

ASM3705

Filename

RECFM

input

Assembler language
source statements i

ASM3705
GEN3705

input
output

fn
fn (nn)

F
F

80
80

3704/3705 assembler
source statements

AUIxxxx

UPDATE

input

Auxiliary update
file

BASIC

input

~256

BASIC language
source statements

~3440

User input and
output files

BASDATA

BASIC
execution

Usage

executiontime files

LRECL

Con tents

CMSUT1

READC1RD
COPYFILE
DISK
TAPE
UPDATE
INCLUDE
LOAD
MACLIB

intermediate
work
file

READ
COPYFILE
DISKLOAI:
TAPELOAD
fn
DMSLDR
DMSLDR
DMSLBM

CNTRL

UPDATE

input

Control file updatel

COBOL

COBOLl

input

COBOL source statements

COpy

MACLIB

input

COpy control cards
and macro
definitions

DIRECT

input

User Directory
entries

EIEC

EIEC
LISTFILE
GEN3705

input
output
output

fn
CMS
fn

EXEC statements

FREEFORT

GOFORTl

input

~81

FREEFORM FORTRAN
source statements

FORTRAN

FORTGIl
FORTHIl
GOFORTl
TESTFORTl

input

FORTRAN source
sta tements

input/
output

FTnnF001

FORTRAN
lexecution

User input and
output files

lIBM Program Products
Figure 48.

Reserved Filetypes (Part 1 of 3)

Appendix F: Reserved Filetype Descriptions

407

Pormat
Filename

RECFM

LRECL

output
output

fn
fn

121

Processor printed
output

output

output
input

fn
fn

121

COEOL processor
output used as
input to SOURCE
subcommand of
TESTCOB

LKED

output

121

Listing

LOADLIB

LKED
ZAP

output
input

fn
fn

V
V

5260
5260

3704/3705 control
program load
modules

MACLIB

GLOBAL
MACLIB

library
MAC LIB

fn
fn

MACRO

MACLIB

input

MAP

INCLUDE
LOAD
MACLIB
TXTLIB

output
output
output
output

LOAD

Piletype

COlllland

LISTING

ASSEMBLE
ASM 3705
GOFORTI
FORTGll
FORTHXl
COBOL 1
PLICI
PLICRI
PLIOPTI
TESTCOBI

LK!DIT

Usage

MEMO

Library contains
dictionary and
members
P

Content s

Macro definitions
Macro definit ions
Macro definitions
Module map
Module map
Library map
Library map

L01D

fn
fn
fn

MODULE

GENMOD
LOADMOD
MODMAP

output
input
input

fn
fn
fn

Non-relocatable
object file

PLI or
PLIOPT

PLIOPTI
PLIC
PLICR

input
input
input

fn
fn
fn

PL/I source
statements

SCRIPT

SCRIPT2

input

5133

SYNONYM

reference

SYSUT1,2,3

ASM3705
ASSEMBLE
COBOLI
LKED
PLIOPTI

work
work
work
work
work

fn
fn
fn
fn
fn

lIEM Program Products
2IBM Installed User Program
igure 48.

408

Reserved Filetypes (Part 2 of 3)

IBft Vft/370: Command Language Guide for General Users

Input to SCRIPT
processor
Command name
synonyms

r-------------.------------------------------------------------------------------------~

Format

"----

Filetype

RECPM

U;;)C1Y-=

LRECL

Contents

COBOLl
LKED
PLIC
PLICR
TESTCOBl

input

TESTFORT

TESTFORTl

output

TEXT

ASSEMBLE
ASM3105

output
output

fn
fn

COBOLl
GEN 3705

output
output

fn
fn (Ln)

INCLUDE
LKED

input
input

fn
fn

LOAD
PLIOPTl
TITLIB
GOFORTl
FORTGIl
FORTHll
TESTFORTl

input
output
input
output
output
output
input

fn
fn
fn
fn

TXTLIB

GLOBAL
TITLIB

library
output

fn
fn

UPDATE

input

UPDLOG

UPDATE

output

UPDATE

input

VSBASIC

input

~256

VSBASIC language
source statements

VSBDATA

execution
time files

~140

VSBASIC user input/I
output files
1

SY SUT4

work

512

Used as input to
TESTCOB

125

Processor printed
output

F
F

80
80

Object code
3704/3705 source
code and job
control language
statements
Object code
Linkage editor
control statementsl
for 3704/3705
1
control programs 1
Object code
1
Object code and
1
LKED control cards
Object code
Object code
Object code
Object file

Library contains
dictionary and
members
80

Object decks

UPDA TE cont rol
cards
UPDATE log
Local updates

----------------------------------1I

lIBM Program Products

Figure 48.

Reserved Filetypes (Part 3 of 3)

Appendix F:

Reser~ed

Filetype Descriptions

409

Index

¢, line delete logical editing symbol

&ARGS control statement, of EXEC command
128
&BEGPUNCH control statement, of EXEC
command 128
&BEGSTACK control statement, of EXEC
command 128
&BEGTYPE control statement, of EXEC command
128
&CONCAT built-in function, of EXEC command
130
&CONTINUE control statement, of EXEC
cOllmand 128
&CONTROL control statement, of EXEC command
128
&DATATYPE built-in function, of EXEC
cOBlmand 130
&END control statement, of EXEC command
128
&ERROR control statement, of EXEC command
128
&EXIT control stateBlent, of EXEC command
129
&GOTO control statement, of EXEC command
129
&IF control statellent, of EXEC command 129
&LENGTH built-in function, of EXEC command
130
&LITERAL built-in function, of EXEC command
130
&LOOP control stateBlent, of EXEC comBland
129
&PUNCH control statement, of EXEC comlland
129
&READ control statement, of EXEC command
129
&SKIP control statement, of EXEC command
129
&SPACE control statement, of EXEC command
129
&STACK control statement, of EXEC comlland
129
&SUBSTR built-in function, of EXEC command
130
&TIME control statellent, of EXEC command
130
&TYPE control statment, of EXEC command
130
&variable control statement, of EXEC
command 128

$DUP subcommand, of EDIT command 123
$MOVE subcommand, of EDIT command 123

command 17
described 249
summary 245

/* control card, for the CMS batch facility
358
/JOB control card, for the eMS batch
facility 358
/SET control card, for the CMS batch
facility 359

1 subcommand, of EDIT command 123
1, use of with the FILEDEF DISK operand
138

I, line end logical editing symbol
ICP command
described 250
summary 245

symbol delete logical editing symbol

", escape symbol logical editing symbol

ABBREV operand
of CMS QUERY command 185
of CMS SET command 198
abbreviations for commands 19
controlling 198
ABEND, problem program 353
ACCESS command 29
CMS responses to 81
described 78
ERASE option 79
examples of 80
NODISK option 79
NOPROF option 79
summary 73
to access a disk you defined via DEFINE
29
used after linking to a virtual disk 29
used to alter the search order for
virtual disks 30
used to change read/write status of a
virtual disk 31
used with OS data sets and DOS files 40
access mode of virtual disks 29
accessing a read-only OS disk 80
accessing CMS with no virtual disks
attached to your virtual machine 79
Index

411

accessing virtual disks 29
access1ng your virtual machine 29
accounting information
displaying 312
for the CMS batch facility 358
ACNT cOllmand, summary 245
ACNT operand, of CP SET command 312
acquiring disk space 78
ADD operand
of the MACLIB command 170
of TITLIB co.mand 220
adding records to a file 118
adding to a file, using EDIT command in
INPUT mode 16
adding to a macro library 170
adding to a TEIT library 220
adding to the EIEC file created using
LISTFILE command output 158
A-disk 27
accessed after IPL CMS 80
ADS TOP command
described 252
OFF operand 252
summary 245
ALIGN option, of ASSEMBLE command 85
alignment of boundaries in assembler
program statements 85
ALL operand
of (CP) QUERY command 298,298
of CHANGE command 256
of PURGE command 295
of the TRANSFER command 338
of TRACE command 335
ALLOC option, of LISTFILE command 158
ALOGIC option, of the ASSEMBLE command 82
ALTER subcommand of EDIT command 119
altering characters in a record 119
altering constants using LOAD command 166
altering instructions using LOAD command
166
altering read/write status of virtual disks
30
altering records of a file 119
altering the attributes of a virtual
printer file 256
altering the attributes of a virtual punch
file 256
altering the attributes of a virtual reader
file 256
altering the logical editing symbols 331
altering the search order of virtual disks
30
altering your virtual machine environment
264
alternating operating system execution 65
OS job stream 66
VM/370 directory 67
analysis, system and hardware, commands
used for 350
annotating your console sheet 249
Any user, described 242
APL character translation tables,
controlling 331
APL operand, of TERMINAL command 332
APPEND option
of COPYFILE command 96
of LISTFILE command 158
appending one file to another 91
412

ASM3705 command, summary 73
ASSEMBLE command 13
ALIGN option 85
ALOGIC option 82
BU!'SIZE option 85
DECK option 84
described 82
DISK option 84
ESD option 83
example of 57
FLAG option 83
LIBMAC option 83
LINECOUN option 83
LIST option 83
listing control options for 82
MCALL option 83
MLOGIC option 83
NOALIGN option 85
NOALOGIC option 83
NODECK option 84
NOESD option 83
NOLIBMAC option 84
NOLIST option 83
NOMCALL option 83
NOMLOGIC option 83
NONUMBER option 85
NOOBJECT option 84
NOPRINT option 84
NORENT option 86
NORLD option 83
NOSTMT option 85
NOTERM option 85
NOXREF option 84
NUMBER option 85
OBJECT option 84
PRINT option 84
RENT option 86
RLD option 83
STMT option 85
summary 73
SYSPARM option 86
SYSTERM listing 85
TERMINAL option option 85
TEST option 84
used with OS data sets and DOS files 40
IRE!' option 84
ASSEMBLE filetype 36
assembler diagnostic messages, controlling
the listing of 83
assembler inner macro instructions,
controlling the listing of 83
assembler listing, controlling the
production ~f 83
assembler macro instructions, controlling
the listing of 83
assembler relocation dictionary,
controlling the listing of 83
assembler
conditional assembly statements,
controlling the listing of 82
controlling number of lines printed by
83
controlling the listing of the External
Symbol Dictionary (ESD)
83
output control options for 83
overriding CMS file defaults 86
under CMS 13
using under CMS 82

IBM VM/370: Command Language Guide for General Users

assembling a program file, example of 57
assembling a program using OS macros 39
ASSIST o·perand, of CP SET command 314
asterisk (*), used in the file.ode field
44
ATTACH command, summary 245
attaching devices to virtual machine 59
attention handling, terminal control of
331
attention interrupt
effect On virtual console in CP mode 25
effect on virtual console in VM mode 24
entering from your virtual console 254
for a virtual machine 309
Attention key
how to use 22
used to interrupt execution of a command
22
used to switch command environments 22
ATTN command
described 254
summary 245
ATTN operand, of TERMINAL command 333
attributes of a spool file, changing 256
attributes of virtual devices, modifying
318
AUTO option
of INCLUDE command 151
of LOAD command 162
AUTOREAD option, of CMS SET command 199
AUTOSAVE subcommand, of EDIT command 119
auxiliary directory, creation of 145

BACKSPAC command, summary 245
BACKWARD subcommand, of EDIT command 119
batch facility ID card 357
batch facility
CMS, using 357
command restrictions for 360
described 357
input to 358
output 360
BCD characters, converting to EBCDIC 95
BDAM OS access method 41
B--disk 27
BEGIN command
described 255
summary 245
used with the DISCONN command 271
beginning execution with an INCLUDE command
151
blanks, as delimiters 16
blip characters
for your virtual machine 197
displaying 184
BLIP option
for CMS QUERY command 184
for CMS SET command 197
BLKSIZE option, of PILEDEP command 136
BLOCK option, of PILEDEP command 136
blocksize, for CMS files 137
BOTH operand, OP TRACE command 335
BOTTOM subcommand, of EDIT command 53,119
boundary alignment, of statements in an
assembler program 85

BRANCH operand, of TRACE command 335
branches, tracing 334
BREAK subcommand, of DEBUG command 115

...... ,..."'''''''lr..,. . . . . ..:_.

u .... "'QJ\.!:'V.4u..

111:

1 1..1

buffer size, assembler, controlling size of
85
BUFSIZE option, of ASSEMBLE command 85

Cancel key 59
carriage control characters for PRINT
command, specifying 179
CASE subcommand, of EDIT command 119
CAW (Channel Address Word)
114
CAW operand, of DISPLAY command 274
CAW subcommand, of DEBUG command 115
CC option, of PRINT command 179
CCW operand, of TRACE command 335
CCW translation, controlling 313
C-disk 27
CHANGE command
ALL operand 256
CLASS operand 256
COpy operand 256
described 256
DIST operand 257
HOLD operand 256,258
NAME operand 257
NOHOLD operand 257
PRINTER operand 256
PUNCH operand 256
READER operand 256
summary 245
CHANGE option, of PILEDEP command 135
CHANGE subcommand, of EDIT command 54,120
changing extended control registers in your
virtual machine 325
changing floating-point registers in your
virtual machine 325
changing general registers 1n your virtual
machine 325
changing records in files 118
changing the attributes of a spool file
256
changing the contents of a record 54
changing the contents of control words 114
changing the filename of a spool file 257
changing the Program Status Word (PSW) in
your virtual machine 325
changing the spool class of a file 256
changing the spoolid of a file 256
changing virtual storage locations in your
virtual machine 324
Channel Address Word (Cl W)
114
displaying 272
Channel Status Word (CSW)
114
displaying 272
CHANNELS operand
of (CP) QUERY command 297
of DEFINE command 265
channel-to-channel adapters, virtual,
connecting 261
character delete logical editing symbol 49
character set 17
character string translation 120
character strings, replacemen~ of 54
Index

413

character translation 91
character translation tables, APL,
controlling 331
characters of a record, moving to different
positions 91
CBARDEL operand, of TERKINAL command 331
CLASS operand
of (CP) QUERY command 299
of CBANGE command 256
of PURGE command 295
of SPOOL command 319
of the TRANSFER command 338
class
privilege
for CP commands 13
for CP commands 243
spool, changing for a file 256
virtual device spool, modifying 318
CLEAR operand
of FILEDEF command 133
of IPL command 282
of the SYSTEK command 327
CLEAR option
of INCLUDE command 150
of LOAD command 161
of SYNONYK command 208
clearing a file definition set by FILEDEF
138
clearing interrupts from a virtual machine
310
clearing storage to zeros 150,161,282,327
clearing synonyms from a synonym table 208
CLOSE command
CONSOLE operand 258
described 258
DIST operand 259
NAKE operand 259
ROBOLD operand 258
PRINTER operand 258
PUNCB operand 258
PURGE operand 259
READER operand 258
summary 245
CLOSE operand, of SPOOL command 321
closing a virtual device 318
closing files 258
CKS (§~g Conversational Konitor System)
CKS assemble file defaults 86
CKS command language, basic description of
13
CKS commands
immediate 77
summary of 73
using READCARD command 46,62
using TAPE command 45
using TAPPDS command 45
CKS Editor
described 52
used to create files 33
CKS files
relationship to DOS files 132
relationship to OS data sets 132
CKS libraries 18
CKS subcommand, of EDIT command 120
CKSBATCB command
described 88
summary 73
COBOL command, summary 73
414

COL option, of TYPE command 224
COL1 option, of TAPPDS command 218
command environment
CP 15
defined 15
switching 15
VK 15
command execution, halting 238
command language
CKS, basic description of 13
CP, basic description of 13
command name 16
com.and operands 16
com.and options 17
defined 17
command search order
CKS
for filetype EXEC 20
for filetype KODULE 20
levels of search in 21
nucleus resident commands 20
transient area com.ands 20
command, mode, EDIT 52
commands
abbreviation of 19,69
CKS
search order for 20
summarized 73
CP, privilege classes for 13
interrupting the execution of 22
minimum truncation for 19,69
notational conventions for 69
summary of use 341
system-defined 15
truncation of 19
used for debugging, summary of 343
used for disk control, summary of 345
used for testing, summary of 343
used to control a terminal session,
summary of 341
used to control a virtual machine,
summary of 346
used to develop programs, summarized
342
used to update files, summary of 344
user-defined 15
comments control statement, for UPDATE
command 230
comments, how to write 17
COKP operand, of KACLIB co •• and 170
compacting members in a macro library 170
COKPARE command
described 89
summary 73
comparison of CP and CKS debugging
facilities 356
compiling, loading, and starting execution
of a file 195
compressing a file 91
COKPSWT, CKS macro instruction 365
CONCAT option, of FILEDEF command 135
concatenating data sets 135
concatenating files 135
conditional assembly statements, assembler,
controlling the listing of 82
configurating virtual machines
addresses 67
device types 67

IBK VK/370: Command Language Guide for General Users

connecting
a remote terminal to a virtual machine
269
virtual channel-to-channel adapters 261
console input/output, terminating- 318
CONSOLE operand
of (CP) QUERY command 297
of CLOSE command 258
of DEFINE command 264
of SPOOL command 319
console
sheet, annotation of 249
spool file 12
modifying 318
spooling, controllinq 318
virtual~ what you should know before
using 48
constants, altering using LOAD command 166
CONT operand, of SPOOL command 319
continuation mark, example of entering 56
continuous reading of an entire file 318
control card
/*, for the CMS batch facility 358
/SET for the CMS batch facility 359
control functions
for tapes 213
setting for your virtual machine 312
Control Program, basic description of 11
control statements
for DDR command 104
for the UPDATE command 226
control words, changing and examining the
contents of 114
controlling
a terminal session, summary of commands
used 341
devices on your virtual machine 13
listing of conditional assembly
statements 82
number of lines printed by the assembler
83
program development, summary of commands
used for 342
the listing of assembler diagnostics
messages 83
the listing of inner macro instructions
83
the production of the assembler listing
83
Conversational Monitor System
basic description of 11
card reader 46
tape handling 45
transferring reader files 46
unit record support 46
CONVERT command, summary 73
converting
BCD characters to EBCDIC characters 95
key punch characters 91
COpy function control statement, of DDR
cOllmand 107
COpy operand
of CHANGE command 256
of SPOOL command 321
COPYFILE command
APPEND option 96
described 91
EBCDIC option 95

examples of 99
FILL option 96
FOR option 93
FRLABRL option 93
FROM option 93
incompatible options listed 99
LOWCASE option 95
LRECL option 93
NEWDATE option 93
NEWFILE option 95
ROPROMPT option 93
NOSPECS option 98
NOTRUNC option 94
NOTYPE option 93
OLDATE option ql
OVLY option 96
PACK option 94
PROMPT option 93
RECFM option 93
REPLACE option 95
responses 101
specification list 97
SPECS option 96
summary 73
TOLABEL option 93
TRANS option 98
TRUNC option 93
TYPE option 93
UNPACK option 95
UPCASE option 95
copying
data from one file to another 91
files from one device to another 104
correcting errors on an input line 48
COUNT option, of DDR command TYPE/PRINT
function control statement 110
COUPLE command
described 261
summary 245
CP
(§gg Control Program)
CP and CMS commands, entering 16
CP command
described 263
description of 103
entering from the VM environment 263
environment 15
privilege classes for 13,241
privilege classes, described 243
summary 73,245
CP mode, on virtual console 59
CP/CMS, as an integrated command language
15
CPEREP command, summary 73
creating
a file 52
using the Editor in INPUT mode 16
a load map of a file 162
a map of a load module 151
a map of files in a TEXT library 221
a program file, example of 56
a SYNONYM file 20
an auxiliary directory 145
an EXEC file containing of output froll
the LISTFILE command 158
files 33,118
files on disk 189
macro libraries 170

Index

415

reference information about members of
macro library 170
user file directory (ACCESS com.and)
78
cross-reference table, assembler,
controlling the listing of 84
CSECTs, duplicate, for the LOAD command
163
CSW (Channel Status Word)
114
csw operand
of DISPLAY command 274
of TRACE command 335
CSW subcommand, of DEBUG command 115
CTCA operand, of DEFINE co •• and 265
CTL option
of UPDATE co •• and 226
detailed description of 232
current line pointer 119
described 53
moving down in a file 54
moving up in a file 54
cylinders, counting number of on a virtual
disk 142
D

DAM DOS access method 41
DASD Dump Restore program, invoking via the
DDR command 104
DASD operand, of (CP) QUERY com.and 297
data extents for DOS files 41
data·set keys 41
data set labels 41
data sets, concatenating 135
data, overlaying in a file 91
DATE option, of LISTFILE command 158
DCP command, summary 245
D-disk 27
accessed after IPL CMS 80
DnR command
COpy function control statement 107
COUNT option of TYPE/PRINT function
control statement 110
description of 104
DUMP function control statement 107
example of TYPE/PRINT output 111
GRAPHIC option of TYPE/PRIBT function
control statement 110
HEX option of TYPE/PRINT function
control statement 110
IBPUT control statement 105
PRINT function control statement 109
responses 110
RESTORE function control statement 107
summary 73
SYSPRINT control statement 106
TYPE function control statement 109
used with OS data sets and DOS files 40
DDR control statements 104
DEBUG command 13
described 114
sumllary 73
DEBUG subcommand environment 16
DEBUG subcomllands, listed 115
debugging
a program using VM/370 351
facilities of CP and CMS, compared 356
programs using the DEBUG com.and 114
summary of commands used for 343
416

DECK option, of the ASSEMBLE command 84
default file attributes, summarized 405
DEFINE command 29
adding temporary disks 31
CHANNELS operand 265
CONSOLE operand 264
CTCA operand 265
described 264
GRAF operand 265
LINE operand 265
PRINTER operand 264
PUNCH operand 264
READER operand 264
STORAGE operand 266
summary 245
TIMER operand 265
T2305 operand 266
T2314 operand 266
T2319 operand 266
T3330 operand 266
T3340 operand 266
use 59
used to define a temporary virtual disk
27
1403 operand 265
3211 operand 265
DEFINE subcommand, of DEBUG command 115
defining
a virtual device 264
a virtual I/O device for your virtual
machine 265
DOS files under CMS 132
OS data sets under CMS 132
temporary virtual disks 29
virtual disk addresses 28
DEL operand
of MACLIB command 170
of TXTLIB command 220
delete control statement, for UPDATE
command 229
DELETE subcommand, of EDIT command 120
deleting
a line from a file 54
files from virtual disk 125
from a TEXT library 220
members of a macro library 170
records from a file 118,229
delimiting fields of command line 17
DEN option
of FILEDEF command 135
TAPE command 214
density of tapes, specifying 214
description of OS data sets, listing of
155
DETACH command
described 267
summary 245
detaching a device from your virtual
machine 267
determining the status of devices on your
virtual machine 297
developing program files, summary of
commands used for 342
device-end interrupt pending for a virtual
device, specifying 308
devices
attaching to virtual machine 59
defining for virtual machine 59

IBM VM/370: Command Language Guide for General Users

linking to 59
linking to a virtual machine 284
making ready 59
tape devices for virtual machine 60
virtual
purging from your system 295
simulating not ready status for 293
DIAL command
described 269
summary 245
dictionary: for a TEXT library 221
DIRECT command, summary 73
directory, VM/370 user 11
DISABLE command, su.mary 245
disabled loop, in a problem program 353
disabled wait, for a problem program 354
DISCOII command 64
described 271
HOLD operand 271
summary 246
disconnecting
the terminal 64
your virtual console 271
your virtual machine 288
disk addresses, for virtual disks 27
DISK command
described 116
DUMP operand 116
LOAD operand 116
summary 73
disk control, summary of commands used for
345
disk files
comparison of formats for 89
created from OS tapes 217
punching to a virtual card punch 116
disk identifier, for a virtual disk 27
disk letter, of filemode field 43
DISK operand
of CMS QUERY command 186
of FILEDEF command 133
interactive use of 138
DISK option
of MICLIB command 171
of QUERY command 32
of TAPE command 214
of the ASSEMBLE command 84
of UPDITE command 226
disk space, acquiring 78
disk storage capacity, displaying status of
186
disks
determining status of 184
OS, reading as data sets on 40
releasing from your virtual machine 192
virtual
deleting files from 125
formatting 51
initializing 142
DISP option, of FILEDEP command 134
DISPLAY command
CAW operand 274
CSW operand 274
described 272
PSW operand 274
summary 246
displaying
accounting information 312

BLIP characters for your virtual machine
184
Channel Address Word (CAW)
274
Channel status Word (CSW)
274
extended control registers 273
filenames on a tape disk 213
first record of a file 53
floating-point registers 273
general registers 273
last record of a file 53

load map at your terminal

162

map of a load module 151
names of members of a library 224
Program Status Word (PSW)
274
records in a file 54
selected positions of a record 224
virtual storage locations 272
DIST.operand
of CHANGE command 257
of CLOSE command 259
distribution code, for an output file 257
DMCP command, summary 246
DOS disks
accessing 80
formatting of 28
reading DOS files on 40
DOS files
file-id 41
handled via PILEDEP and MOVBPILE
commands 42
listing of 155
multivolumes 41
reading 40
restrictions for reading 41
under CMS 132
user labels and data extents 41
with security indicator on 41
DOS libraries 41
DOS POWER, spooling in a virtual machine
63
DOWN subcommand, of EDIT command 54,120
DRAIN command, summary 246
DUMMY operand, of PILEDEP com.and 133
DUMP command
described 277
summary 246
DUMP function control statement, of DDR
command 107
DUMP operand
of DISK command 116
of TIPE command 212
format of tape created by 215
DUMP subcommand, of DEBUG command 115
dumping
disk files to tape 104
files from disk to tape 212
DUP option
of INCLUDE command 151
of LOAD command 163
duplicate CSECTs, for the LOID command 163

EBCDIC option, of COPYPILE command 95
EBCDIC representation of a file, displaying
223
Index

417

ECHO command
described 280
summary 246
E-disk 27
EDIT command 13,15
SOUP subcommand 123
SMOVE subcommand 123
1 subcommand
123
ALTER subcommand 119
AUTOSAVE subcommand 119
BACKWARD subcommand 119
BOTTOM subcommand 53,119
CASE subcommand 119
CHANGE subcommand 120
CMS subcommand 120
DELETE subcommand 120
described 118
DOWN subcommand 54,120
EDIT mode 52
example of 52
FILE subcommand 55,120
FIND subcommand 120
FMODE subcommand 120
FNAME subcommand 120
FORWARD subcommand 120
GETFILE subcommand 120
IMAGE subcommand 120
INPUT mode 52
INPUT subcommand 120
LINEMODE subcommand 120
LOCATE subcommand 121
LONG subcommand 121
LRECL option 119
NEXT subcommand 121
nnnnn subcommand 123
OVERLAY subcommand 121
PRESERVE subcommand 121
PROMPT subcommand 121
QUIT subcommand 121
RECFM subcommand 121
RENUM subcommand 121
REPEAT subcommand 121
REPLACE subcommand 121
RESTORE subcommand 121
RETURN subcommand 121
REUSE subcommand 121
SAVE subcommand 122
SCROLL subcommand 122
SERIAL subcommand 122
SHORT subcommand 122
STACK subcommand 122
summary 74
TABSET subcommand 122
TOP subcommand 53,122
TRUNC subcommand 122
TYPE subcommand 54,54,122
UP subcommand 54,122
used to create a SYNONYM file
VERIFY subcommand 122
X subcommand 122
Y subcommand 122
ZONE subcommand 122
EDIT INPUT mode 16
EDIT mode 16
of EDIT command 52
EDIT subcommand environment 16
EDIT subcommands, listed 119

418

editing symbols
controlling 331
logical, controlling use of 313
Editor
described 52
invoking 52
EMSG operand, of CP SET command 313
ENABLE command, summary 246
enabled loop, in a problem program 354
enabled wait, for a problem program 355
END operand, of TRACE command 335
END option, of TAPPDS command 218
entering
a CP command from a CMS virtual machine
103
a CP command from the VM environment
250,263
CP and CMS commands 16
the DEBUG environment 114
ENTRY control card, for the loader 166
EOF operand, of SPOOL command 320
EOF option, of TAPE command 214
EOT option, of TAPE command 214
equal sign (=), used in the filemode field
44
ERASE command
described 125
NOTYPE option 125
summary 74
TYPE option 125
ERASE option, of ACCESS command 79
erasing
old files 79
the contents of a virtual disk 28
error message handling, controlling 313
error recovery, in batch mode 361
errors, on an input line, correcting 49
escape logical editing symbol 49
ESCAPE operand, of TERMINAL command 332
ESD option, of the ASSEMBLE command 83
examining the contents of control words
114
EXEC command 13,15,15
&ARGS control statement 128
&BEGPUNCH control statement 128
&BEGSTACK control statement 128
&BEGTYPE control statement 128
&CONCAT built-in function 130
&CONTINUE control statement 128
&CONTROL control statement 128
&DATATYPE built-in function 130
&END control statement 128
&ERROR control statement 128
&EXIT control statement 129
&GOTO control statement 129
&IF control statement 129
&LENGTH built-in function 130
&LITERAL built-in function
130
&LOOP control statement 129
&PUNCH control statement 129
&READ control statement 129
&SKIP control statement 129
&SPACE control statement 129
&STACK control statement 129
&SUBSTR built-in function 130
&TIME control statement 130
&TYPE control statement 130
&variable control statement 128

IBM VM/370: Command Language Guide for General Users

described 127
summary 74
used to invoke a user-defined command
18
EXEC control statements

listed 127
EXEC files
as input to the CMS batch facility 359
created by LISTFILE command, adding to
158
created from output of the LISTPILE
cOiimand

158

EXEC filetype 36
EXEC option, of LISTFILE command 158
EXEC procedure
as a user-defined command 18
explicit specification of 18
EXEC procedures 36
EXEC subcommand environment 15
EXEC, PROFILE 18
executing
a procedure by invoking its filename
127
a program using OS macros 39
a program using the LOAD command 162
a program, example of 58
a user-defined command 127
files 195
operating systems 65
programs 202
programs in a virtual machine, passing
arguments 68
execution
beginning with an INCLUDE command 151
halting at an instruction address 252
of a CMS command, halting 238
of a module, setting the starting point
for 161
of a virtual machine, resuming 255
starting point
resetting 150
setting 150
extended control registers
changing your virtual machine 325
displaying 272
printing 277
extending one virtual disk from another
30,78
extensions, of virtual disks 30
EXTERNAL command
described 281
summary 246
external interrupt, simulated 281
EXTERNAL operand, of TRACE command 335
External Symbol Dictionary (ESD)
83
F

PCB operand, of LOADVPCB command 287
F-disk 27
PILE subcommand, of EDIT command 55,120
file
access mode 28
definition, determining status of 184
entering continuation mark 56
example of entering at terminal 56
groups created by language processors
37

identifier (§~~ ~!§Q
filemode field of
filename field of
filetype field of
for eMS files

fileid)
33
33
33

search order, specifying 44
FILEDEF command
BLKSIZE option 136
BLOCK option 136
CHANGE option 135
CLEAR operand 133
CONCAT option 135
DEN option 135
described 132
DISK operand 133
DISP option 134
DUMMY operand 133
examples of 139
KEYLEN option 134
LIMCT option 134
LOWCASE option 134
LRECL option 136
MEMBER option 134
NOCHANGE option 135
OPTCD option 134
PERM option 135
PRINTER operand 133
PUNCH operand 133
READER operand 133
RECFH option 136
responses 140
summary 74
TAPEn operand 133
TERMINAL operand 133
TRTCH option 135
UPCASE option 134
used to define OS data sets 33
used with MOVEPILE to handle OS data
sets and DOS files 42
used with OS data sets and DOS files
XTENT option 134
7TRACK option 135
9TR!CK option

135

PILEDEF definitions
clearing of 138
displayed 187
FILEDEF operand, CMS QUERY command 187
fileid 33
filemode field, of the file identifier 33
filemode number, of file mode field 43
filemode numbers
defined 35
described 35
filemode
described 34
explicit specification of 44
implicit specification of 44
filename field, of the file identifier 33
filename, described 33
FILES operand, of (CP) QUERY command 297
files
adding records to 118
adding to 16
assembling, example of 57
changing records in 118
changing the spool class of 256
changing the spoolid for 256
closing 258
Index

419

CMS
calculating blocksize 137
calculating logical record length 137
co.mands used to update, summary of 344
concatenating 135
copying 104
creating 16
example of 56
creation of 33,52,118
defined 12,33
definitions for, displayed 187
deleting from virtual disk 125
deleting lines from 54
deleting records from 118,229
disk, punching to a virtual card punch
116
displaying 223
displaying records in 54
displaying the first record of 53
displaying the last record of 53
distribution code for 257
executing, example of 58
external references for 19
holding before output processing 256
holding from further processing 258,318
input, for the UPDATE command 230
inserting records in 228
listing information on 157
loading, example of 58
modification of 33
modifying 16
moving from device to device 176
multiple
linking of 150
used to update a file 226
numbering records on 226
on disk, dumping to tape devices 104
on tape, restored to disk 104
output, for the UPDATE command 230
overlaying 96
printing a hexadecimal listing of 180
printing of 179
processed by TAPE command, listed 214
punched, restoring to disk 116
punching on a virtual card punch 181
purging 258,318
relating to OS ddname 132
relocatable 19
renaming 193
displaying new names for 193
reordering closed spool files 294
replacing records in 229
saving on disk, via AUTOSAVE 119
sorting records in 200
source
modifying 225
replacing 225
spool, changing filename for 257
starting execution of 195
storing 55
tape
updating 218
writing to disk 213
terminating processing of 258
transferring to another user 318
transmitted, reclaiming 338
transmitting to a virtual reader 338

420

verifying the existence of 203
with reserved filetypes 407
filetype EXEC, in CMS command search order
20
filetype field, of the file identifier 33
filetype MODULE, in CMS command search
order 20
filetype
ASSEMBLE 36
described 34
EXEC 36
for files containing a listing 36
for object files 36
LISTING 36
MODULE 19,36
reserved by CMS 407
rules for usage 35
SYNONYM 20
TEIT 19,36
PILL option, of COPYPILE com.and 96
PIND subcommand, of EDIT co.mand 120
PLAG option, of the ASSEMBLE command 83
floating-point registers
changing your virtual machine 325
displaying 272
printing 277
PLUSH command, summary 246
PMODE option, of LISTPILE command 158
PMODE subcommand, of EDIT co.mand 120
PNAME option, of LISTPILE co.mand 158
PNAME subcommand, of EDIT command 120
POR option, of COpy PILE command 93
PORCE command, summary 246
PORMAT command 28,29
description of 142
examples of 143
initializing a temporary disk 31
LABEL option 142
RECOMP option 142
response 143
summary 74
PORMAT option
of LISTDS command 156
of LISTPILE command 158
formatting
a CMS virtual disk 28,142
a disk in your virtual machine 51
forms controls for a 3211 printer,
specifying 287
PORTGI command, summary 74
PORTHI command, summary 74
PORWARD subcommand, of EDIT command 120
PREE command, summary 246
PRLABEL option, of COPY PILE co.mand 93
PROM operand, of the TRANSPER command 338
PROM option
of COPY PILE command 93
of GENMOD command 146
PSCB, CMS macro instruction 366
PSCLOSE, macro instruction 367
PSERASE, CMS macro instruction 368
PSOPEN, CMS macro instruction 369
PSREAD, CMS macro instruction 370
PSSTATE, CMS macro instruction 372
PSWRITE, CMS macro instruction 373
PTYPE option, of LIST PILE command 158
functions, tape control 213

IBM VM/370: Command Language Guide for General Users

gaining access to your virtual machine 290
gaining the attention of the virtual
machine 309
G-disk 27
GEN operand
of MACLIB command 170
of TXTLIB command 220
GENDIRT command
description of 145
summary 74
general registers
changing in your virtual machine 325
displaying 272
printing 277
general user, described 242
generating
a heading for LISTFILE command output
157
a macro library 170
a module file 146
a TEIT library 220
generation of a module, initializing
storage for
147
GENMOD command 19,36
description of 146
FROM option 146
MAP option 146
NOMAP option 146
NOSTR option 147
STR option 147
summary 74
SYSTEM option 147
TO option 146
GEN3705 command, summary 74
GETFILE subcommand, of EDIT command 120
GLOBAL command
18
described 148
example of 57,149
MACLIB operand 148
summary 74
TITLIB operand 148
used with OS data sets and DOS files 40
GO subcommand, of DEBUG command 115
GOFORT command, summary 74
GPR subcommand, of DEBUG command 115
GRAF operand
of (CP) QUERY command 297
of DEFINE command 265
GRAPHIC option, of DDR command TYPE/PRINT
function control statement 110

HALT command, summary 246
halting
execution at an instruction address 252
execution of a CMS command 238
recording of trace information 237
terminal output 237
hardware analysis, summary of commands used
for 350
HEADER card format, for punch files
182
header card, inserting in a punch file 181
HEADER option
of LISTFILE command 157
of PUNCH command 181

heading, generating for output of the
LISTFILE command 157
HEI option
of DDR command TYPE/PRINT function
control statement 110
of PRINT command 180
of TYPE command 224
hexadecimal representation of a file,
displaying 223
hiding your password 290
HNDEXT. eMS macro instruction 375
HNDINT, CMS macro instruction 376
HNDSVC, CMS macro instruction 377
HO command, summary 77
HO immediate command 237
HOLD command, summary 246
HOLD operand
of CHANGE command 256,258
of DISCONN command 271
of LOGOFF cQmmand 288
of SPOOL command 319
holding
a file before output processing 256
files from further processing 258,318
HT command, summary 77
HT immediate command 237
HI command, summary 77
HI immediate command 238
HI subcommand, of DEBUG command 115

IBCDASDI disk initialization program 28
ICS (Include Control Section) control card,
for the loader 165
ID card
CP, described 189
of the batch facility 357
identifier, virtual disk 27
IEBPTPCH utility, as 217
IEBUPDTE utility, OS 217
IEHMOVE utility, as 217
IMAGE subcommand, of EDIT command
120
immediate commands, described 237
IMPCP operand
of CMS QUERY command 185
of CMS SET command 199
IMPEl operand
of CMS QUERY command 185
of CMS SET command 199
implied CP status
displaying 185
setting 199
implied EXEC status
displaying 185
setting 199
IMSG operand, of CP SET command 313
INC option, of UPDATE command 226
INCLUDE command 19
AUTO option
151
CLEAR option 150
description of 150
DUP option 151
examples of 153
INV option 151
LIBE option 151
MAP option 151
Index

421

NOAUTO option 151
NOCLEAR option 150
NODUP option 151
NOLIBE option 151
NOREP option 151
NOTYPE option 151
ORIGIN option 150
REP option 151
RESET option 150
SAME option 151
START option 151
summary 74
TYPE option 151
Include Control section (ICs) card, for the
loader 165
incompatible options for the COPYFILE
command 99
INDEX operand, for LOADVFCB command 287
initial program load (IPL)
automatic, suppression of 290
of a virtual machine operating system
282
initializing
a virtual disk 142
storage for generation of a module 147
inner macro instructions, assembler,
controlling the listing of 83
INPUT control statement, for DDR command
105
input files for the UPDATE command,
described 230
input for the CMs batch facility, EXEC
files as 359
input lines
correcting errors on 48
entering 53
INPUT mode, of EDIT command 52
INPUT operand
of CMs QUERY command 186
of CMs SET command 198
INPUT subcommand, of EDIT command 120
input to the CMs batch facility 358
input/output operations, tracing 334
insert control statement, for UPDATE
command 228
inserting
a header card in a punch file
181
records in a file 228
INSTRUCT operand, of TRACE command 335
instructions, altering using LOAD command
166
interactive entering of FILEDEF DISK
operand 138
interrupting execution of a command 22
interrupts
clearing from a virtual machine 310
device-end, specifying for a virtual
device 308
external, simulating 281
for a virtual machine 309
handling using the DEBUG command 114
tracing 334
INV option
of INCLUDE command 151
of LOAD command 162
invoking a synonym table 208
invoking libraries for use during
processing 148
422

invoking macro libraries 148
invoking TEXT libraries 148
invoking the Editor 52
I/O devices
virtual
defining for your virtual machine
265
spooling to 12
I/O operand, of TRACE command 335
IPL command
CLEAR operand 282
described 282
example of 50
for named systems 283
NOCLEAR operand 282
PARM operand 282
STOP operand 282
summary 246
IPL procedure, stopping 282
IsAM DOS access method 41
IsAM 05 access method 41

KEYLEN option, of FILEDEF command 134
keypunch characters, converting 91
keys
for data sets 41
program function, controlling 314
storage, printing of 277

LABEL option
of FORMAT command 142
of LIsTFILE command 158
label
for data sets 41
writing on a virtual disk 142
language processors
file groups created by 37
files created by
permanent 37
temporary 37
filetypes for 35,36
under CMs 13
LDRTBLs operand
of CMs QUERY command 185
of CMs SET command 198
LEAVE option, of DDR command INPUT/OUTPUT
control statement 106
LIBE option
of INCLUDE command 151
of LOAD command 162
LIBMAC option, of the ASSEMBLE command 83
libraries
CMs macros 45
displaying the filenames of members in
224
displaying those to be searched during
processing 188
invoking for use during processing 148
MACLIB 44
macro, displaying the members of 188
making available 45
05 macros 44

IBM VM/370: Command Language Guide for General Users

punching member files in 181
releasing 45
TEXT
adding to 220
creating a map of files in 221
deleting from 220
dictionary 221
displaying members of 188
generating 220
listing filenames of members 220
TSO macros 45
TXTLIB 44
used under CMS 18
used when processing CMS commands 148
LIBRARY control card, for the CMS loader
161
library member, printing 180
LIBRARY operand, of CMS QUERY command 188
LIMCT option, of FILEDEF command 134
line delete logical editing symbol 49
line editing symbols, controlling 313
line end logical editing symbol 49
line length, controlling at your terminal
333
line number generation for assembler
SYSTERM listing 85
LINE operand, of DEFINE command 265
line pointer
current 119
described 53
LINECOUN option, of the ASSEMBLE command
83
LINEDEL operand, of TERMINAL command 332
LINEDIT operand, of CP SET command 313
LINEDIT, CMS macro instruction 378
LINEMODE subcommand, of EDIT command 120
LINEND operand, of TERMINAL command 332
LINES operand, of (CP) QUERY command 298
lines, controlling number of printed by
assembler 83
LINESIZE operand, of TERMINAL command 333
LINK command
adding temporary disks 31
described 284
passwords 285
summary 246
use 59
linking
a device to your virtual machine 284
multiple files 150
TEXT files in storage 161
to another user's virtual disk 29
LINKS operand, of (CP) QUERY command 298
LIST option, of the ASSEMBLE command 83
LISTDS command
description of 155
example of 156
FORMAT option 156
PDS option 156
summary 74
used with OS data sets and DOS files 40
LISTFILE command
ALLOC option 158
APPEND option 158
DATE option 158
described 157
example of 159
EXEC option 158

FMODE option 158
FNAME option 158
FORMAT option 158
FTYPE option 158
HEADER option 157
LABEL option 158
NOHEADER option 157
summary 74
LISTING filetype 35,36
listing
controlling production of by the
assembler 83
descriptions of OS data sets and DOS
files 155
hexadecimal, printing 180
information about CMS files 157
of files processed by the TAPE command
214
of format information describing an OS
data set or DOS file 156
the assembler External Symbol Dictionary
(ESD)
83
the filenames of members of a TEXT
library 220
the members of an OS Partitioned Data
Set 156
LKED command, summary 74
LOAD and GENMOD commands, used to generate
a module 15
LOAD command 19,36
AUTO option 162
CLEAR option 161
described 161
DUP option 163
duplicate CSECTs 163
example of 58
executing a program using 162
INV option 162
MAP option 162
NOAUTO option 162
NOCLEAR option 161
NODUP option 163
NOINV option 162
NOLI BE option 162
NOMAP option 162
NOREP option 162
NOTYPE option 162
ORIGIN option 162
REP option 162
RESET option 161
START option 162
summary 74
TYPE option 162
LOAD control cards
described 163
ENTRY card 166
Include Control Section (ICS) card 165
LIBRARY card 167
Loader Terminate Card (LDT)
165
Replace (REP) card 166
Set Location Counter (SLC)
164
LOAD key, simulation of via IPL command
282
load map file
creation of 163
definition of 163
load map of a file, creation of 162

Index

423

load map
creating for a module file 175
displaying at your terminal 162
generated by the GENMOD command 146
replace card image in
151
load module
creating a map of 151
displaying the map of 151
lOAD operand
of DISK command 116
of TAPE command 213
load tables, displaying the number of 185
lOADBUF command, summary 246
loader Terminate Card (lDT) control card,
for the loader 165
loading a module file 169
loading a program, example of 58
loading an operating system in a virtual
machine 50,60
loading multiple TEXT libraries 150
loading point for a file, specifying 162
loading TEXT files into virtual storage
161
lOADMOD command
described 169
summary 74
lOADVFCB command
described 287
FCB operand 287
INDEX operand 287
summary 246
lOCATE command, summary 246
lOCATE subcommand, of EDIT command 121
location counter, setting for the LOAD
Command 164
lOCK command, summary 246
logging off of your virtual machine 58,288
logging on your virtual machine 50,290
logical editing symbols
altering 331
character delete 48
controlling 331
controlling use of 313
escape 48
line delete 48
line end 48
used to alter a file being edited 53
logical record length
changing 91
for CMS files 137
logically connected terminal 269
lOGMSG operand, of (CP) QUERY command 306
lOGOFF command
described 288
HOLD operand 288
summary 246
lOGON command
described 290
MASK operand 290
NOIPl operand 290
summary 246
logon procedure, hiding your password
during 290
lONG subcommand, of EDIT command 121
loop
disabled, in a problem program 353
enabled, in a problem program 354

424

lOWClSE option
of COPYFIlE command 95
of FIlEDEF command 134
lowercase letters
converting to uppercase 91
translating to uppercase 119
using PRINT command 180
lowercase records, translating to uppercase
118
lRECL option
of COPYFIlE command 93
of EDIT command 119
of FIlEDEF command 136
M

machine, determining the status of virtual
devices on 297
MlClIB command
lDD operand 170
COMP operand 170
DEL operand 170
described 170
DISK option 171
GEN operand 170
MlP operand 170
PRINT option 171
REP operand 170
summary 74
TERM option 171
MlClIB libraries 44
MlClIB operand
of CMS QUERY command 188
of GLOBAL command 148
macro definitions, controlling the listing
of 83
macro libraries
adding to 170,172
compacting 173
compacting members of 170
creating and updating 170
creating information about members in
170
creation of 148
deleting members of 170
displaying members of 188
generating 170,171
invocation of 148
replacing 172
replacing members of 170
macros
CMS 363
COMPSWT 365
FSCB 366
FSCLOSE 367
FSERlSE 368
FSOPEN 369
FSRElD 370
FSSTlTE 372
FSWRITE 373
HNDEXT 375
HNDINT 376
HNDSVC 377
lINEDIT 378
PRINTl 390
PUNCHC 392
RDClRD 393
RDTlPE 394

IBM VM/370: Command Language Guide for General Users

RDTERM 396
REGEQU 397
TAPECTL 398
WAITD 400
WAITT 401
WRTAPE 402
WRTERM 404
OS
assembling a program using 39
executing a program using 39
simulated by eMS 38
using under CMS 37
manipulating the translate table 198
MAP operand
of MACLIB command 170
of TITLIB command 221
KAP option
of GENMOD command 146
of INCLUDE command 151
of LOAD command 162
map
of a load module, displaying 151
of files in a TEIT library, creating
221
MA SK operand
of LOGON command 290
of TERMINAL command 332
lIasking
of passwords, controlling 331
your password during the logon procedure
290
master file directory 12
of a virtual disk 27
searching 78
updating entries in 193
MAITEN option, TAPPDS command 219
MCALL option, of the ASSEMBLE command 83
MEMBER option
of FILEDEF command 134
of PRINT command 180
of PUNCH command 181
of TYPE command 224
MESSAGE command
described 292
summary 247
message handling, error, handling 313
MESSAGE operand, OPERATOR command 292
messages
controlling transmission of 312
replying to 59
sending to other users 292
Mini disks
(§~g virtual disks)
minimum abbreviation for commands,
controlling 185,198
minimum truncation of commands 19
MLOGIC option, of the ASSEMBLE command 83
MODE operand, of TERMINAL co~and 23,333
MODE option, of DDR command INPUT/OUTPUT
control statement 106
mode setting of virtual console 22
MODESET operand, of TAPE command 213
modifying
files 33
using the Editor in EDIT mode 16
source files 225
spooling control options 318
storage, using ADSTOP command 252
virtual device attributes 318

MODMAP command
described 175
summary 75
module file
creating a load map for 175
generation of 146
MODULE filetype 19,35,36
module
generation of by LOAD and GENMOD
loading in storage 1n169

",...,,~

"""It.

_ _ ....... _ _

u~cu

~VWWQUU

MONITOR command, summary 247
MOVEFILE command
default device attributes 176
described 176
example of 177
PDS option 176
summary 75
used with FILEDEF to handle OS data sets
and DOS files 42
used with OS data sets and DOS files 40
moving
files from device to device 176
strings of characters 91
MSG operand, of CP SET command 312
multilevel updates using the UPDATE
command, examples of 234
multiple files
linking of 150
used to update a file 226
multiple input lines, entering 53
multivolume DOS files 41
N

NAME operand
of CHANGE command 257
of CLOSE command 259
named systems, IPL command for 283
NAMES operand, of (CP) QUERY command 306
naming files 33
NCPDUMP command, summary 75
NETWORK command, summary 247
NEWDATE option, of COPYFILE command 93
NEWFILE option, of COPYFILE co~mand 95
NEIT subcommand, of EDIT command 121
nnnnn subcommand, of EDIT command 123
NOALIGN option, of ASSEMBLE command 85
NOALOGIC option, of the ASSEMBLE command
83
NOAUTO option
LOAD command 162
of INCLUDE command 151
NOCC option, of PRINT command 180
NOCHANGE option, of FILEDEF command 135
NOCLEAR operand, of IPL command 282
NOCLEAR option
of INCLUDE command 150
of LOAD command 161
NOCOLl option, of TAPPDS command 218
NOCONT operand, of SPOOL command 319
NOCTL option, of UPDATE command 226
NODECK option, of the ASSEMBLE command 84
NODISK option, of ACCESS command 79
NODUP option
of INCLUDE command 151
of LOAD command 163
NOEND option, of TAPPDS command 219
Index

425

IOEOF operand, of SPOOL command 320
IOESD option, of the ASSEMBLE command 83
MOBElDER option
of LISTFILE command 157
of PUNCH command 181
MOBOLD operand
of CHANGE command 257
of CLOSE command 258
of SPOOL command 320
MOIMC option, of UPDATE com.and 226
MOINV option, of LOlD command 162
NOIPL operand, of LOGON command 290
MOLIBE option
of INCLUDE command 151
of LOAD command 162
NOLIBMAC option, of the ASSEMBLE command
84
NOLIST option, of the ASSEMBLE command 83
MOMAP option
GENMOD command 146
of LOAD command 162
NOMAXTEN option, of TAPPDS command 219
NOMCALL option, of the ASSEMBLE command 83
NOMLOGIC option, of the ASSEMBLE command
83
NONUMBER option, of ASSEMBLE command 85
NOOBJECT option, of the ASSEMBLE command
84
NOPDS option, of TAPPDS command 218
NOPRINT option
of TAPE command 214
of the ASSEMBLE command 84
NOPROF option, of ACCESS command 79
NOPROMPT option, of COPYFILE command 93
NORENT option, ASSEMBLE command 86
NOREP option
of INCLUDE command 151
of LOAD command 162
of UPDATE command 225
NORLD option, of ASSEMBLE command 83
NORUN operand, of TRACE command 335
NOSEQ8 option, of UPDATE command 226
NOSPECS option, of COPY FILE command 98
NOSTD option, of SYNONYM command 208
NOSTK option
of UPDATE command 226
detailed description of 233
NOSTMT option, of ASSEMBLE command 85
NOSTR option, of GENMOD command 147
notational conventions 69
NOTERM operand, of SPOOL command 322
NOTERM option
of ASSEMBLE command 85
of UPDATE command 226
NOTRANS operand, of CP SET command 313
NOTREADY command
described 293
summary 247
NOTRUNC option, of COPYFILE command 94
MOTYPE option
of COPYFILE command 93
of ERASE command 125
of INCLUDE command 151
of LOAD command 162
of RENAME command 193
NOUPDIRT option, of the RENAME command 193
NOWTM option, of the TAPE command 214
NOXREF option, of the ASSEMBLE command 84
426

nucleus
protection against writing over 199
protection feature, displaying status of
186
number of cylinders on a virtual disk,
resetting 142
NUMBER option, of ASSEMBLE command 85
numbering records of your file 226

o
object data, generated by language
processors 37
object deck, assembler, controllin'g the
generation of 84
OBJECT option, of the ASSEMBLE command 84
OFF operand
of SPOOL command 321
of the ADSTOP command 252
of TRACE command 335
OLDATE option, of COPYFILE co •• and 93
operands, command 17
operating system
for a virtual machine, passing
parameters to 282
initial program load for 282
loading in your virtual machine 50
OPERATOR operand, of MESSAGE command 292
operator, sending messages to 292
OPTCD option, of FILEDEF command 134
options, command 17
ORDER command
described 294
summary 247
ORIGIN option
of INCLUDE command 150
of LOAD command 162
ORIGIN subcommand, of DEBUG command 115
OS
cards, contained in a TEXT library 221
da ta sets
handled via FILEDEF and MOVEFILE
commands 42
reading 40
restrictions for reading 41
under CMS 132
disks
accessing 80
formatting of 28
reading OS data sets on '40
job stream, for alternating operating
system execution 66
macros
assembling a program using 39
executing a program using 39
simulated by CMS 33
simulated by CMS 38
using under CMS 37
Partitioned Data Sets, specifying via
FILEDEF 135
programs, using under CMS 37
spooling in a virtual machine 63
tapes
containing Partitioned Dats Sets 217
used to create CMS disk files 217
utility
IEBPTPCB 217

IBM VM/370: Command Language Guide for General Users

IEBUPDTE 217
IEHMOVE 217
OUTPUT control statement, for DDR command
105
OUTPUT operand
of CMS QUERY command 186
of CMS SET command 198
output
control options for the assembler 83
files for the UPDATE command, described
230
from the batch facility 360
OVERLAY subcommand, of EDIT command 121
overlaying
data in a file 91
files 96
OVLY option, of COpy FILE command 96

PACK option, of COPYFILE command 94
parameters, passing to a virtual machine
operating system 282
PARM operand, of IPL command 282
Partitioned Data Sets
generating a listing of members
156
OS tapes containing 217
passing parameters to your virtual machine
operating system 282
password
controlling masking of 331
entering at your virtual console 48
hiding during logon procedure 290
with the LINK command 285
PDS option
of LISTDS command 156
of MOVEFILE command 176
of TAPPDS command 217
PERM option, of FILEDEF command 135
permanent
files created by language processors 37
virtual disks, defined in the VM/370
directory 28
PFnn operand
of (CP) QUERY command 299
of CP SET command 314
PLIC command, summary 75
PLICR command, summary 75
PLIOPT command, summary 75
pointer
current line
119
to the current line, described 53
positioning of tapes 213
PRESERVE subcommand, of EDIT comamnd 121
primary user disk 27
PRINT command
CC option 179
described
179
HEX option 180
MEMBER option 180
NOCC option 180
summary 75
PRINT function control statement, of DDR
command 109
PRINT option
of MACLIB command 171
of TAPE command 214

of the ASSEMBLE command 84
of UPDATE command 226
printer (3211), virtual, specifying forms

controls for

287

printer files, virtual, altering the
attributes of 256
PRINTER operand
of (CP) QUERY command 298
of CHANGE command 256
of CLOSE command 258
of DEFINE command 264
of FILEDEF command 133
of PURGE command 295
of SPOOL command 319
of TRACE command 335
printer, virtual, spooling to 214
printing
a CMS file
179
a hexadecimal listing of a file 180
a member of a library 180
records
at the printer 104
at the terminal 104
the contents of virtual machine
components 277
the Program status Word (PSW;
277
virtual storage keys 277
virtual storage locations 277
PRINTL, CMS macro instruction 390
PRIV operand, of TRACE command 335
privilege classes
for CP commands 13
defined 243
summarized 243
privileged instructions, tracing 334
problem analysis 352
problem determination, description of
process for 351
problem program
ABEND 353
disabled wait 354
enabled wait 355
PROFILE EXEC 18,79
definition of 79
execution of 79
for reconnected virtual machine 65
program ABEND 353
program function keys, controlling 314
PROGRAM operand, of TRACE command 335
program products, using under CMS 43
Program Status Word (P SW)
114
changing your virtual machine 325
displaying 272
printing 277
programs, beginning execution of 202
PROMPT option, of COPYFILE command 93
PROMPT subcommand, of EDIT command
121
PROTECT operand
of CMS QUERY command 186
of CMS SET command 199
protecting against writing on nucleus 199
PSW (Program Status Word)
114
PSi operand, of DISPLAY command 274
PSi subcommand, of DEBUG command 115
PUNCH command
description 181
HEADER card format 182
HEADER option 181
Index

427

MEMBER option 181
NOHEADER option 181
sUllllary 75
punch files, virtual, altering the
attributes of 256
PUNCH operand
of (CP) QUERY command 298
of CHANGE com.and 256
of CLOSE command 258
of DEFINE com.and 264
of FILEDEF command 133
of PURGE command 295
of SPOOL command 319
PUNCHC, CMS macro instruction 392
punched files, restoring to disk 116
punching
a file on a virtual card punch 181
a member of a library file 181
disk files to a virtual card punch 116
PURGE command
ALL operand 295
CLASS operand 295
described 295
PRINTER operand 295
PUNCH operand 295
READER operand 295
summary 247
PURGE operand
of CLOSE command 259
of SPOOL command 321
purging
files 258,318
virtual devices from your system 295

QUERY command (CMS)
ABBREV operand 185
BLIP operand 184
described 184
DISK operand 186
FILEDEF operand 187
IMPCP operand 185
IMPEX operand 185
INPUT operand 186
LDRTBLS operand 185
LIBRARY operand 188
MACLIB operand 188
OUTPUT operand 186
PROTECT operand 186
RDYMSG operand 184
REDTYPE operand 185
RELPAGE operand 185
SEARCH operand 186
summary 75
SYNONYM SYSTEM operand 187
TXTLIB operand 188
used to find the read/write status of a
virtual disk 32
used with OS data sets and DOS files 40
QUERY command (CP)
ALL operand 298,298
CHANNELS operand 297
CLASS operand 299
CONSOLE operand 297
DASD operand 297
described 297
428

FILES operand 297
GRAF operand 297
LINES operand 298
LINKS operand 298
LOGMSG operand 306
NAMES operand 306
PFnn operand 299
PRINTER operand 298
PUNCH operand 298
READER operand 298
SET operand 297
STORAGE operand 298
summary 247
TAPES operand 298
TERMINAL operand 297
TIME operand 297
UR operand 298
USERS operand 306
VIRTUAL operand 297
QUIT subcommand, of EDIT command

121

RDCARD, CMS macro instruction 393
RDTAPE, CMS macro instruction 394
RDTERM, CMS macro instruction 396
RDYMSG operand
CMS SET command 197
of CMS QUERY cOllmand 184
READ control card format 191
READCARD command 46,62
described 189
format of operands 190
summary 75
reader files, virtual, altering the
attributes of 256
READER operand
of (CP) QUERY command 298
of CHANGE cOllmand 256
of CLOSE command 258
of DEFINE command 264
of FILEDEF command 133
of PURGE command 295
of SPOOL command 319
reading
an entire file continuously 318
cards from a remote station 62
cards from a virtual card reader 116
cards in a virtual machine 62
DOS files
on DOS disks 40
restrictions for 41
OS data sets
on OS disks 40
restrictions for 41
records from a virtual card reader 189
read/only status of virtual disks 31
read/write access, with LINK command 285
read/write status of virtual disks 31
alteration of 30
READY command
described 308
summary 247
use 59
Ready Message
CMS, described 51
displaying 184
setting 197

IBM VM/370: Command Language Guide for General Users

real computer
RESET button, simulating 327
RESTART button, simulating 327
RECFM option
of COPYFILE command 93
of FILED!F command 136
RECFM subcommand, of EDIT command 121
reclaiming transmitted files 338
RECOMP option, of FORMAT command 142
record format, changing 91
recording technique taper specifying 214
recording trace information for SVC
instructions 204
records
changing the contents of 54
displaying selected positions of 224
in a file, numbering 226
REDTYPE operand, of CMS QUERY command 185
REDTYPE option, of CMS SET command 199
references, undefined, resolving via LOAD
command 162
REGEQU, CMS macro instruction 397
registers
extended control
displaying 273
printing 277
floating-point
displaying 273
printing 277
general
displaying 273
printing 277
relating an OS ddname to a CMS file 132
RELEASE command 29
described 192
summary 75
used with OS data sets and DOS files 40
releasing
a disk from your virtual machine 192
pages of storage after command execution
185,198
virtual disks 29
RELPAGE operand
of CMS QUERY command 185
of CMS SET command 198
Remote Spooling Communications Subsystem
11
receiving files 323
spooling to remote locations 12
TAG command 328
transmitting files 323
remote terminal, connecting to a virtual
machine 269
re.oving a virtual device from your virtual
machine 267
RENAME command
described 193
NOTYPE option 193
NOUPDIRT option 193
summary 75
TYPE option 193
UPDIRT option 193
renamed file, displaying new name for 193
renaming your files 193
RENT option, ASSEMBLE command 86
RENUM subcommand, of EDIT command 121
REP (Replace) control card, for the loader
166

REP operand, of MACLIB command 170
REP option
of INCLUDE command 151
of LOAD command 162
of UPDATE command 225
REPEAT command, summary 247
REPEAT subcommand, of EDIT com.and 121
replace control statement
for UPDATE command 229
image of in a load map 151
REPLACE option r of COPYFILE command 95
REPLACE subcommand, of EDIT command 121
replacing
a source file 225
an input file with an output file 95
character strings 54
members in macro libraries 170
records in a file 229
replying to messages on virtual system
console 59
REQUEST command
described 309
summary 247
Request key 59
reserved filetypes, in CMS 407
RESET button, simulating 327
RESET command
described 310
summary 247
RESET operand, of the SYSTEM command 327
RESET option
of INCLUDE command '150
of LOAD command 161
resetting
execution starting point 150
the number of cylinders on a virtual
disk 142
resolving
external references for a file 19
referenced TEXT files via the LOAD
command 162
undefined references
by INCLUDE command 152
via LOAD command 162
RESTART button, simulating 327
RESTART operand, of the SYSTEM command 327
RESTORE function control statement, of DDR
command 107
RESTORE subcommand, of EDIT command 121
restoring
dumped files on disk 212
files to disk from tape 104
punched files to disk 116
terminal output 239
restrictions
for reading DOS files 41
for reading OS data sets 41
for use of CP and CMS commands in batch
mode 360
results, unexpected in a problem program
353
resume
execution of your virtual machine 255
tracing 238
use of your virtual machine after
disconnecting it 271
retaining options set by an INCLUDE or LOAD
command 151
Index

429

RETURN subcommand
of DEBUG command 115
of EDIT co.mand 121
REUSE subcommand, of EDIT command 121
REWIND command
described 311
summary 247
REWIND option, of DDR command INPUT/OUTPUT
control statement 106
rewinding a real tape 311
ribbon, two-color, controlling use of 185
RLD option, of the ASSEMBLE command 83
RO command, summary 77
RO immediate command 238
RSCS
(2~~ Remote Spooling Communications
Subsystem)
RT command, summary 77
RT immediate command 239
RUN command
described 195
summary 75
RUN operand
of CP SET command 313
of TRACE command 335

SAME option, of INCLUDE command 151
sample program 55
SAVE subcommand, of EDIT command
122
saved systems, IPL command for 283
SAVENCP command, summary 75
S!VESYS command, summary 247
saving
a file on disk 119
disk files on tape 104
virtual machine data 324
SCAN operand, of TAPE command 213
SCRIPT command, summary 75
SCROLL subcommand, of EDIT command 122
S-disk 28
accessed after IP CMS 80
SEARCH operand, of CMS QUERY command 186
search order
for CMS commands 20
for files 44
of virtual disks 30
searching
master file directory (ACCESS command)
78
TITLIB files for unresolved references
151
selected positions of a record, displaying
224
sending messages
to other users 292
to the operator 292
sequence control statement, for UPDATE
command 227
sequence numbers 226
SEQ8 option, of UPDATE command 226
SERIAL subcommand, of EDIT command 122
service representative, described 242
SET command (CMS)
ABBREV option 198
AUTO READ option 199
BLIP option 197
430

described
197
determining status of SET operands for
your virtual machine environment
184
IMPCP option 199
IMPEl option 199
INPUT option 198
LDRTBLS option
198
OUTPUT option 198
PROTECT option 199
RDYMSG option 197
REDTYPE option 199
RELPAGE option 198
summary 76
SET command (CP)
ACNT operand 312
ASSIST operand 314
described 312
EMSG operand 313
IMSG operand 313
LINEDIT oeprand 313
MSG operand 312
NOTRANS operand 313
PFnn operand 314
RUN operand 313
summary 247
TIMER operand 314
WNG operand 312
set Location Counter (SLC) control card,
for the loader 164
SET operand, of (CP) QUERY command 297
SET subcommand, of DEBUG command 115
setting
CMS functions for your virtual machine
environment 197
control functions for your virtual
machine 312
the blip characters for your virtual
machine 197
the number of loader tables 198
the starting point for execution
150,161
SHORT subcommand, of EDIT command 122
SHUTDOWN command, summary 247
simulating
not ready status for a virtual device
293
the IEBUPDTE OS utility under CMS 218
the RESET button on a real computer 327
the RESTART button on a real computer
327
single line of input, entering 53
SIO operand, of TRACE command 335
SKIP operand, of TAPE command 213
SKIP option, of DDR command INPUT/OUTPUT
control statement 106
SLEEP command
described 317
summary 247
SO command, summary 77
SO immediate command 239
SORT command
described 200
storage requirements 200
summary 76
sorting records in a file 200
source files
modifying 225
replacing 225

IBM VM/370: Command Language Guide for General Users

source symbol table, assembler, generation
of 84
SPACE command, summary 247
specification list for COPYPILE command 97
specifying
a device-end interrupt for a virtual
device 308
carriage control characters, for PRINT
command 179
first instruction to be executed in a
file 101
the file mode field 43
the loading point for a file 162
SPECS option, of COPYFILE command 96
spool class
for a file, changing 256
modifying 318
SPOOL command 62
CLASS operand 319
CLOSE operand 321
CONSOLE operand 319
CONT operand 319
COpy operand 321
described 318
EOP operand 320
HOLD operand 319
NOCONT operand 319
NOEOF operand 320
NOHOLD operand 320
BOTER! operand 322
OPP operand 321
PRINTER operand 319
PUNCH operand 319
PURGE operand 321
READER operand 319
START operand 321
STOP operand 322
sum.ary 247
SYSTE! operand 320
TER! operand 322
TO operand 320
use with TAG command 322
spool file 12
altering TAG information 330
changing filename for 257
changing the attributes of 256
console 12
reordering 294
spoolid 322
TAG co.mand 328
transmitting to remote locations 322
spool files, transmitting to remote
location 329
spoolid number 322
spooling
across a teleprocessing network 12
control
options, modifying 318
summary of commands used 349
defined 12
disconnected terminal 64
DOS POWER spooling in a virtual machine
63

in a virtual machine 63
operator, described 242
OS spooling in a virtual machine
to a virtual printer 214
to virtual I/O devices 12

virtual console I/O 61
with RSCS 12
STACK subcommand, of EDIT command 122
START command
described 202
example of 58
summary 76,247
START operand, of SPOOL command 321
START option
of IBCLUDE command 151
of LOAD command 162
starting point for execution of a module,
setting 161
STATE command
described 203
summary 76
used with OS data sets and DOS files 40
statement number generation, for assembler
SYSTER! listing 85
status of virtual machine environment 184
status
of your virtual machine, determining
general information on 297
words, tracing 334
STCP command, summary 247
STD option, of SYNONY! command 208
STK option
of UPDATE command 226
detailed description of 233
ST!T option, of ASSEMBLE command 85
STOP operand
of IPL com.and 282
of SPOOL command 322
stopping the intial program load (IPL)
procedure 282
STORAGE operand
of (CP) QUERY command 298
of DEFINE command 266
storage
clearing to zeros 161,282
keys, printing 277
locations, virtual, displaying 272
modification of 252
releasing pages of after command
execution 185,198
STORE command
described 324
summary 247
STORE subcommand, of DEBUG command 115
storing
CPU status for virtual machine 326
files, using the EDIT FILE subcommand
55

virtual machine data 324
STR option, of GENMOD command 147
string translation, character 120
strings of characters, moving 91
subcommand environments, defined 15
sutcommands
DEBUG
BREAK 115
CAW 115
CSW 115
DEFINE 115
DU!P 115
GO 115
GPR 115
HIllS
Index

431

listed 115
ORGIN 115
PSW 115
RETURN 115
SET 115
STORE 115
X 115
summary
of CMS commands 73
of commands used for debugging 343
of commands used for disk control 345
of commands used for system and hardware
analysis 350
of commands used for testing 343
of commands used to control a terminal
session 341
of commands used to control a virtual
machine 346
of commands used to control spooling
349
of commands used to develop programs
342
of commands used to update files 344
of CP commands 245
suppressing
automatic IPL of a virtual machine
operating system 290
the PROFILE EXEC 79
suspending trace recording 239
SVC instructions, tracing 204
SVC operand, of TRACE command 335
SVCTRACE command
described 204
responses 205
summary 76
switching command environments 15
using the Attention key 22
SYNONYM and SET ABBREV commands,
relationship between 209
SYNONYM command 20
CLEAR option 208
described 208
example of 211
NOSTD option 208
STD option 208
summary 76
SYNONYM operand, of CMS QUERY command 187
SYNONYM SYSTEM operand, of CMS QUERY
command 187
synonym table
clearing 208
creating 208
described 209
entries in 209
format for entries in 209
invoking 208
use of with SYNONYM command 20
SYNONYM, filetype 20
synonyms
displaying user-defined 187
for commands 20
system, displaying 187
SYSPARM option, ASSEMBLE command 86
SYSPRINT control statement of DDR command
106
system analysis, summary of commands used
for 350
system analyst, described 242
432

SYSTEM command
CLEAR operand 327
described 327
RESET operand 327
RESTART operand 327
summary 248
system disk 28
SYSTEM operand, of SPOOL command 320
system operator, primary, described 242
SYSTEM option, GENMOD command 147
system programmer, described 242
system resource operator, described 242
system synonyms, displaying 187
system-defined commands 15
SYSTERM data set, assembler, writing of 85
SYSTERM listing
assembler
controlling line number generation
85
controlling statement number
generation 85
SYSTERM options, assembler 85

tab settings 118
TABSET subcommand, of EDIT command 122
TAG command
altering TAG information 330
described 328
summary 248
transmitting files to remote location
329
use with SPOOL command 322
TAPCMD operand, of the TAPE command 213
TAPE command 45
DEN option 214
described 212
DISK option 214
DUMP operand 212
EOF option 214
EOT option 214
LOAD operand 213
MODESET operand 213
NOPRINT option 214
NOWTM option 214
PRINT option 214
SCAN operand 213
SKIP operand 213
summary 76
TAPCMD operand 213
TAPn option 214
TERM option 214
TRTCH option 214
WTM option 214
7TRACK option, 214
9TRACK option 214
tape control functions 213
restrictions when using 215
tape devices, dumping disk files to 104
tape files
restoring to disk 104
updating 218
writing to disk 213
tape handling commands
CMS 45
for virtual machine 60

IBM VM/370: Command Language Guide for General Users

TAPE MAP
described 214
generated by the TAPE command DISK
option 214
tape marks, writing on tape 214
tape recording technique, specifying 214
TAPECTL, CMS macro instruction 398
TAPEn operand, of FILEDEF command 133
TAPES operand, of (CP) QUERY command 298
tapes
density of, specifying 214
displaying the filenames on 213
positioning to a specified point 213
rewinding 311
writing tape marks on 214
7-track, specifying 214
9-track, specifying 214
TAPn option
of TAPE command 214
TAPPDS command 218
TAPPDS command 45
COLl option 218
described 217
EID option 218
MAXTEI option 219
10COLl option 218
ROEID option 219
10MAXTEN option 219
10PDS option 218
PDS option 217
summary 76
TAPn option 218
UPDATE option 218
temporary disks
adding 31
initializing 31
temporary files created by language
processors 37
temporary virtual disks, defining via the
DEFIlE command 29
TERM operand, of SPOOL command 322
TERM option
of MACLIB command 171
of TAPE command 214
of UPDATE command 226
TERMINAL command
APL operand 332
ATTI operand 333
CHARDEL operand 331
described 331
ESCAPE operand 332
LINEDEL operand 332
LINEND operand 332
LIIESIZE operand 333
MASK operand 332
MODE operand 23,333
summary 248
used to set the mode of your virtual
console 23
TERMINAL operand
of (CP) QUERY command 297
of FILEDEF command 133
of TRACE command 335
TERMINAL option, of ASSEMBLE command 85
terminal
console, disconnecting from your virtual
machine 271
control of attention handling 331

disconnected, log off 64
input/output processing, controlling
331
line length, controllinq 331
operating 47
output
halting 237
restoring 239
remote, connecting to a virtual machine
269
session
commands used to control, summary of
341
determining the length of time of
297
testing using the ECHO command 280
termina ting
console input/output 318
processing of files 258
TEST option, of the ASSEMBLE command 84
TESTCOB command, summary 76
TESTFORT command, summary 76
testing
summary of commands used for 343
your terminal 280
TEXT files
linking in storage 161
loading into virtual storage 161
resolution of via the LOAD command 162
TEXT filetype 35,36
TEXT libraries
adding to 220
deleting from 220
dictionary 221
displaying members of 188
generation of 220
invocation of 148
listing filenames of members 220
multiple, loading for execution 150
used to contain OS cards 221
TEXT, filetype 19
TIME operand, of (CP) QUERY command 297
time, determining length for a terminal
session 297
TIMER operand
of CP SET command 314
of DEFINE command 265
timer, virtual, controlling 314
TO operand
of SPOOL command 320
of the TRANSFER command 338
TO option, of GENMOD command 146
tokens, in an EXEC control statement 127
TOLABEL option, of COPYFILE command 93
TOP subcommand, of EDIT command 53,122
TRACE command
ALL operand 335
BOTH operand 335
BRANCH operand 335
CCW operand 335
CSW operand 335
described 334
END operand 335
EXTERNAL operand 335
INSTRUCT operand 335
I/O operand 335
NORUN operand 335
OFF operand 335
Index

433

PRINTER operand 335
PRIV operand 335
PROGRAM operand 335
RUN operand 335
SIO operand 335
summary 248
SVC operand 335
TERMINAL operand 335
trace information, halting recording of
237
tracing
resuming after temporarily halting 238
suspending recording temporarily 239
SVC instructions 204
virtual machine activity 334
trailing fill characters, removing from
records 91
TRANS option, of COpy FILE command 98
TRANSFER command 62
ALL operand 338
CLASS operand 338
described 338
FROM operand 338
summary 248
TO operand 338
transferring
files to a virtual reader 338
files to another user 318
output of virtual machine 65
translate table
displaying 186
manipulation of 198
translating
character strings 120
characters 91
from lowercase to uppercase 119
from uppercase to lowercase 119
lowercase letters to upper letters,
using PRINT command 180
records
from lowercase to uppercase 118
from uppercase to lowercase 118
translation of CCW, controlling 313
TRTCB option
of FILEDEF command 135
of TAPE command 214
TRUNC option, of COPYFILE command 93
TRUNC subcommand, of EDIT command 122
truncating commands 19,69
two-color ribbon, controlling use of
185,199
TITLIB command
ADD operand 220
DEL operand 220
described 220
GEN operand 220
MAP operand 221
summary 76
TITLIB libraries 44
TITLIB operand
of CMS QUERY command 188
of GLOBAL command 148
TYPE command
COL option 224
described 223
BEl option 224
MEMBER option 224
summary 76
434

TYPE function control statement, of DDR
command 109
TYPE option
of COPYFILE command 93
of ERASE command 125
of INCLUDE command 151
of LOAD command 162
of RENAME command 193
TYPE subcommand, of EDIT command 54,122
TYPE/PRINT output of DDR command 111
T2305 operand, of DEFINE command 266
T2314 operand, of DEFINE command 266
T2319 operand, of DEFINE command 266
T3330 operand, of DEFINE command 266
T3340 operand, of DEFINE command 266

undefined references
in an INCLUDE command, resolution of
152
resolving via LOAD command 162
unit record devices, CMS 46
UNLOAD option, of DDR command INPUT/OUTPUT
control statement 106
UNLOCK command, summary 248
UNPACK option, of COPY FILE command 95
unresolved references, in an INCLUDE
command
151
unresolved TEIT files, resolved via the
LOAD command 162
UP subcommand, of EDIT command 54,122
UPCASE option
of COPY FILE command 95
of FILEDEF command 134
of PRINT command 180
UPDATE command
control statements 226
CTL option 226
detailed description of 232
described 225
description of input files for 230
description of output files for 231
DISK option 226
error handling for 235
errors that can occur using 235
INC option 226
multilevel updates, examples of 234
NOCTL option 226
NOINC option 226
NOREP option 225
NOSEQ8 option 226
NOSTK option 226
detailed description of 233
NOTERM option 226
PRINT option 226
REP option 225
SEQ8 option 226
STK option 226
detailed description of 233
summary 76
TERM option 226
warnings by 235
UPDATE control statement
comments 230
delete 229

IBM VM/370: Command Language Guide for General Users

insert 228
replace 229
227
--_.::1-sequence
.... _ , __
U}lUdl.t: ..Lvy
for UPDATE command operations
generating at your terminal 226
generating on disk 226
UPDATE option, of the TAPPDS command 218
updating
files
summary of commands used for 344
using multiple files 226
macro libraries 170
tape files 218
UPDIRT option, of RENAME command 193
uppercase character, translated to
lowercase 119
uppercase letters, converting to lowercase
91
uppercase records, translating to lowercase
118
UR operand, of (CP) QUERY command 298
user file directory, creating 78
user label for DOS files 41
USER operand, of (CP) QUERY command 306
user-defined commands 15
how to write 18
user-defined synonyms, displaying 187
userid, entering at your virtual console
48
using OS macros under CMS 37
using OS programs under CMS 37
using program products under CMS 43

VARY command, summary 248
VERIFY subcommand, of EDIT command 122
verifying the existence of a file 203
virtual console
disconnecting from your virtual machine
271
mode setting 22
spooling 61,319
what you should know before using 48
virtual dev ices
closing 318
defining 264
detaching from your virtual machine 267
determining number of for your virtual
machine 297
determining the status of 297
purging from your system 295
removing from your virtual machine 267
simulating not ready status for 293
specifying a device-end interrupt for
308
virtual disk addresses, defining 28
virtual disk cylinders, counting number of
142
virtual disks
access mode of 29
accessing 29
CMS disks 78
adding temporary disks 31
addresses of 27

allocating cylinders for 27
altering the search order of 30
CMS 12
eMS standard search order 30
CP and CMS access 31
defined 27
defining the size of 12
deleting files from 125
description of 11
erasing the contents of 28
extensions of ~V,~I
finding the read/write status of 32
formatting 28,51
identifier 27
initialization of 142
linking to another user's 29
master file directory 27
maximum number allowed 27
read-only status of 30
read/write status of 30,31
releasing 29
resetting the number of cylinders on
142
search order for 30
temporary, defining 29
writing a label on 142
virtual I/O devices
defining for your virtual machine 265
spooling to 12
Virtual Machine (VM) environment, entering
CP commands from 250
virtual machine environment, determining
the status of 184
Virtual Machine Facility/370, basic
description of 11
virtual machine
activity, tracing 334
alternating execution of operating
systems 65
attaching devices 59
batch facility, described 357
components of 11
configuration, altering 264
configurations 67
controlling the devices on 13
defined 11
determining general information on the
status of 297
device, linking to 284
disconnecting 288
disconnecting the terminal 64
execution 68
resuming 255
gaining access to 290
loading with operating system 50,60
logging off of 58,288
logging on 50,290
operating system, passing parameters to
282
placing in a dormant state 317
printing and punching 63
reading cards into 62
setting control functions for 312
spooling 63
storing information from 324
summary of commands used to control 346
transferring output 65
VIRTUAL operand, of (CP) QUERY command 297
Index

435

virtual printer (3211), specifying forms
controls for 287
virtual printer, spooling to 214
virtual storage locations
changing in your virtual machine 325
printing 277
virtual system console
differences from real console 59
replying to messages 59
virtual timer, controlling 314
VM environment 15
entering a CP command from 263
VMFDUMP command, summary 76
VM/370
(§gg Virtual Machine Facility/370)
VM/370 directory
11,28
entry, description of 29
for alternating operating system
execution 67
VSAM DOS access method 41
VSAM OS access method 41
VSBASIC command, summary 76
VSBUTIL command, summary 76

W
wait
disabled, for a problem program 354
enabled, for a problem program 355
WAITD, CMS macro instruction 400
WAITT, CMS macro instruction 401
WARNING command, summary 248
warning messages, generation of for errors
in UPDATE command execution 226
WNG operand, of CP SET command 312
writing
cards to a virtual disk from a virtual
card reader
116
comments in VM/370 17
tape files to disk 213
user-defined commands 18
WRTAPE, CMS macro instruction 402
WRTERM, CMS macro instruction 404
WTM option, of TAPE command 214

Y subcommand, of EDIT command
Y-disk 27
accessed after IPL CMS 80

X subcommand
of DEBUG command 115
of EDIT command 122

122

ZAP command, summary 76
Z-disk 27
zeros, clearing storage to 282,327
ZONE subcommand, of EDIT command 122

1403 operand, of DEFINE command
19E virtual disk address 28
accessed as Y-disk 80
190 virtual disk address 28
accessed as S-disk 80
191 virtual disk address 27
accessed as A-disk 80
192 virtual disk address 27
accessed as D-disk 80

265

3211 operand, of DEFINE command 265
3211 printer, virtual, specifying forms
controls for 287
7
7TRACK option
of FILEDEF command 135
of TAPE command 214
7-track tapes, specifying 214

436

XREF option, of the ASSEMBLE command 84
XTENT option, of FILEDEF command 134

9TRACK option
of FILEDEF command 135
of the TAPE command 214
9-track tapes, specifying 214

IBM VM/370: Command Language Guide for General Users

READER'S COMMENTS

Title:

IBM Virtual Machine
Facility /370:
Command Language Guide
for General Users

Order No.

GC20-1804-3

Please check or fill in the items; adding explanations/comments in the space provided.
Which of the following terms best describes your job?

o Customer Engineer
o
o

Engineer
Instructor

o
o
o

Manager
Mathematician
Operator

Programmer

o Sales Representative

Student/Trainee

o
o
o

Systems Analyst
Systems Engineer
Other (explain below)

How did you use this publication?
o Introductory text
o Reference manual
o Student/D Instructor text
o Other (explain) _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __

.! •
&.

Did you find the material easy to read and understand?

0 Yes

No ( explain below)

Did you find the material organized for convenient use?

0 Yes

No (explain below)

ClIo

c:
0

({

0
0

:
~:

Specific criticisms (explain below)
Clarifications on pages
Additions on pages
Deletions on pages
Errors on pages
Explanations and other comments:

Thank you for your cooperation. No postage necessary if mailed in tht:; U.S.A.

'-1

GC20-1804-3

: l;-

'0
• :J
·cc

:-1
.~

• U)'

YOUR COMMENTS PLEASE ...
Your views about this publication may help improve its usefulness: this form
will be sent to the author's department for appropriate action. Using this
form to request system assistance and/or additional publications or to suggest
programming changes will delay response, however. For more direct handling
of such requests, please contact your IBM representative or the IBM Branch
Office serving your locality. Your comments will be carefully reviewed by
the person or persons responsible for writing and publishing this material. All
comments or suggestions become the property of 18M.

FOLD

FIRST CLASS
PERMIT NO. 172
BURLINGTON, MASS.

BUSINESS REPLY MAIL
co

NO POSTAGE STAMP NECESSARY IF MAILED IN U.S.A.

s:
s:

POSTAGE WILL BE PAID BY

·'W
'"
:0

IBM CORPORATION

:()
.0
'3
: 3

VM/370 PUBLICATIONS

24 NEW ENGLAND EXECUTIVE PARK

':::1

:a.
:r

BURLINGTON, MASS. 01803

•

• :::I

• to

'G)

: CD

·:Q

'G)

'CD
••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• :::I

FOLD

: -

·c
:~
.~

•

ell

:"'0

~.
':::1
• r-+

'CD

:a.
: 3'

·c

:c.n
:~

International BUllnell Machlnel Corporation
Data Proceiling Dlvllion
1133 Weltchelter Avenue, White Plalnl, New York 10604
(U.S.A. only)

'G)
:()
• !'oJ

· .....
• (X)

IBM World Trade Corporation
821 United Natlonl Plaza, New York, New York 10017
(International)

:w
'';:'

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.3
Linearized                      : No
XMP Toolkit                     : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37
Producer                        : Adobe Acrobat 9.13 Paper Capture Plug-in
Modify Date                     : 2009:09:09 17:44:47-07:00
Create Date                     : 2009:09:09 17:44:47-07:00
Metadata Date                   : 2009:09:09 17:44:47-07:00
Format                          : application/pdf
Document ID                     : uuid:37406bbb-b15b-478c-83b6-8fb713612b72
Instance ID                     : uuid:c4f8815a-839f-40e9-a523-63a0f6fa37af
Page Layout                     : SinglePage
Page Mode                       : UseOutlines
Page Count                      : 458

EXIF Metadata provided by EXIF.tools

GC20 1804 3_VM370_Command_Language_Rel_2_Jan75 3 VM370 Command Language Rel 2 Jan75

Navigation menu

Versions of this User Manual:

Views

Navigation