GC20 1819 2_IBM_Virtual_Machine_Facility_370_CMS_Users_Guide_Rel_6_PLC_1_Mar79 2 IBM Virtual Machine Facility 370 CMS Users Guide Rel 6 PLC 1 Mar79
User Manual: GC20-1819-2_IBM_Virtual_Machine_Facility_370_CMS_Users_Guide_Rel_6_PLC_1_Mar79
Open the PDF directly: View PDF 
.
Page Count: 492
| Download | |
| Open PDF In Browser | View PDF |
File No. S370-39
Order No. GC20-1819- 2
I BM Virtual Machine
Facility /370:
Systems
eMS User's Guide
Release 6 PLC 1
Contains general information and examples for
using the Conversational Monitor System (CMS)
component of I BM Virtual Machine Facility/370
(VM/370).
This publication is written for applications
programmers who want to learn how to use
CMS to create and modify data files (including
VSAM data sets) and programs, and to
compile, test, and debug OS or DOS programs
under CMS.
The CMS Editor and EXEC facilities are described
with usage information and examples.
Prerequisite Publications
IBM Virtual Machine Facility/370: Terminal
User's Guide, Order No. GC20-1810
IBM Virtual Machine Facility/370: Introduction,
Order No. GC20-1800
--..---- -......----. _
-==-='='=
- - -----~
)
®
/
TlIis is a major revision of, and obsoletes, GC20-1819-1 with Technical
Newsletter GN25-0411. This edition applies to Release 6 PtC 1 (Program
Level Change) of IBM Virtual Machine Facility/37C, and to all sutsequent
releases unless otherwise indicated in new editions or Technical
Newsletters.
Technical changes and additions to text and illustrations are indicated
ty a vertical bar to the left of the change~
Changes are periodically made to the information herein; before using
this publication in connection with the operation of IBft systems,
consult the latest !~~ ~l§!~!LJl~ ~i~liQg£!Ehl, Order No. GC20-0001, for
the editions that are aIplicable and current.
Publications are not stocked at the address given below; requests for
copies of IBft publications should be made to your IBft representative cr
to the IBM tranch office serving your locality.
A form for readers' comments is
provided at the back of this
pablication. If .the form has been relloved, comments may be addressed to
lEI! Corporaticn, Vft/370 Publications, Dept. D58, Bldg. 706-2, P.O. Box
390, poughkeepsie, New York 12602. IBI! may use or distribute any of the
information you supply in any way it believes appropriate without
incurring any obligation whatever. You may, of course, continue to use
the informaticn you supply.
©
Copyright International
1979
Business Machines Corporation
1976, 1977,
(
Pg. of GC20-1819-2 Rev Barch 30, 1979 by Supp. SD23-9024-1 for 5748-118
Preface
This publication
is intended
for the
general CMS user.
It contains information
describing the interactive facilities of
CMS, and includes examples shoving you how
to use CftS.
"Part 1. Understanding CMS" contains
sections that describe, in general terms,
the CftS facilities and the CMS and CP
com.ands that you can use to control your
virtual aachine. If you are an experienced
programmer
who
has
used
interactive
terminal systems before, you may be able to
refer directly to the VM/JIQ: ~~~ COm!~~g
~D~ A§££g
R~!~!~£~ publication
to find
specific details about CMS co.mands that
are summarized in this part.
Otherwise,
you .ay need to refer to later sections of
this
publication
to gain
a
broader
background in
using CMS.
The topics
discussed in Part 1 are:
•
What It Means
Machine
•
VM/370-CMS
Switching
•
•
•
What You Can Do with VM/370-CMS COllmands
The CMS File System
•
•
To
Have
a CMS
Environllents
Virtual
Bode
and
procedures to use with
discussed in Part 3 are:
•
•
•
•
CBS.
The
topics
Building EXEC Procedures
Using EXECs with CBS Co.mands
Refining Your EXEC Procedures
Writing Edit Bacros
"Part 4. Learning To
Use the HELP
Facility"
contains
descriptions
and
examples of the use of HELP facility format
words in creating HELP description files.
"Appendix A: Summary of CftS Co.mands"
lists the commands available in the CftS
co •• and environment.
"Appendix B: Summary of CP Commands"
lists the CP command privilege classes- and
summarizes the co.mands available in the CP
cOllmand environment.
"Appendix C: Considerations for 3270
Display Terminal Users" discusses aspects
of V!/370 and CftS that are different or
unique when
you use
a 3270
display
terminal.
1\
"Appendix D: Sample Terminal Sessions"
shows sample terminal sessions for:
•
Using the CBS editor and CftS file system
commands
Introduction to the EXEC Processor
•
Using line-number
editor
Using Real
and Tapes
•
creating, assembling,
as program in CBS
•
Creating, assembling, and
DOS program in CBS/DOS
•
Using access method services in CBS
The CMS Editor
Printers, Punches,
Readers,
"Part 2. Program Development Using CBS"
is primarily for applications progra •• ers
who want to use CMS to develop and test os
and DOS programs under CMS. The topics
discussed in Part 2 are:
editing with
the CftS
and executing
an
executing
a
•
Developing OS programs Under eMS
•
Developing DOS Programs Under CMS
•
Using Access Method Services and
Under CMS and CMS/DOS
VSAM
Some of the following terms are used, for
convenience, throughout this publication:
•
How VM/370
Progralls
Your
•
•
Using the CMS Batch Facility
•
programming for the eMS Environment
Can
Help
You
Debug
The
term "CBS/DOS"
refers to
the
functions of CBS that become available
when you issue the command
set dos on
"Part
detailed
3. Learning
information
To Use EXEC"
on creating
gives
EXEC
CBS/DOS is a part of the normal CBS
system, and is not a separate system.
Users who
do not use
CBS/DOS are
Preface
iii
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
sometimes referred to as OS users, since I •
they use the as simulation functions of I
CMS.
•
For a glossary of
The term "CMS files" refers exclusivelY
to files that are in the fixed block
format used by CMS file system commands.
VSAM and as data sets and DOS files are
not compatible with the CMS file format,
and cannot be manipulated using CMS file
system cemmands.
The terms "disk" and "virtual disk" are
used interchangeably to indicate disks
that are in your CMS virtual machine
configuration.
Where
necessary,
a
distinction
is
made
between
CMS-formatted disks and disks in as or
DOS format.
•
"FB-512" refers to the IBM 3310 and 3310
Direct Access Storage Devices.
"3270" refers to a series of display
devices,
namely,
the IBM 3215, 3216
Controller Display Station, and 3211 and
3218 Display
Stations.
A
specific
device type
is used
only when
a
distinction is required between device
types.
Information about display terminal
usage also applies to the IBM 3138,
3148, and 3158 Display Consoles when
used in display mode, unless otherwise
noted.
Any inf~rmation pertaining to the IBM
3284 or 3286 Printer also pertains to
the IBM 3287, 3288, and 3289 printers,
unless otherwise noted.
•
"3330" refers to the IBM 3330 Disk
Storage Models 1, 2, and 11, the IBM
3333 Disk Storage and Control Models 1
and 11, and the IBM 3350 Direct Access
Storage in 3330 compatibility mode.
•
"2305" refers to the IBM 2305 Fixed Head
Storage, Models 1 and 2.
!!!~ Vi!:1Y~! 11~£!!in~
~~~ ~~2!g£ I~gg!,
VM/310 terms, see the
!~£!li1Ul10:
GI222~!:I
GC20-1813.
PREREQUISITE PUBLICATIONS
If this is the first time you
computer terminal, you should
have used a
consult the
!~Ll1Q
Ig£~i~~~ Q2g£~2
2~!g~,
GC20-l8l0,
for information on using your terminal.
terminal
is
a
3161
Terminal, then
!BM ~1~1
is
a
Q~!de,
GA18-2000,
If
your
Communications
Q~g£at2£~2
prerequisite.
The IEM Virtual Machine !~£!!i!IL~lQ:
In troductlon;---GC2 0-1800;-- contains
an
overviev--of the V8/310 system and its
components, and lists the programs and
products that are supported in CMS.
COREQUISITE PUBLICATIONS
The IBM
!!£!Y~! 11~ch!~~
£Qm!~n~ ~¥g 112££2
!~Cil!1YL31Q: ~MS
S~!g£~ll£~, GC20-18l8, is
a compan1on to this user's guide.
It
contains complete format descriptions of
the CMS commands; EDIT subcommands; EXEC
control statements, built-in functions, and
special variables; DEBUG subcommands; and
CMS assembler language macros that are
discussed or used in examples in this book.
IBM !!£!~! 11g£l!ine !gci!!!IL11Q: ~~!~!
GC20-1808,
contains
the
responses, error messages, and return codes
issued by the CMS commands, and EDIT and
DEBUG
subcommands referenced
in
this
publication, as well as a complete list of
the error messages issued by the EXEC
processor.
A~22~g~§,
•
"3340" refers to the IBM 3340 Direct
Access Storage Facility and the IBM 3344
Direct Access Storage.
•
"3350" refers to the IBM 3350 Direct
Access Storage device
when used in
native mode.
•
Any information pertaining to the IBM
2141 terminal also applies to the IBM
3767 terminal, unless otherwise noted.
•
To use CMS, you should be familiar with
the control program
(CP) component of
V8/310. The
CP commands
available to
general users are described in !~11 !i£!Y~!
370x
refers
to
the
Communications Controllers.
!1~£l!i~ !2£il!ilfllQ:~:g
I
I
•
"3310" refers to the
Access Storage Device.
IBM 3310
Direct
I
I
•
"3310" refers to the
Access Storage Device.
IBM 3310
Direct
iv
IBM VM/370: CMS User's Guide
3104/3105
fQ~ ~~!lg£2!
Y2~£§'
~2n.mlg ~ef~£~!l£~
GC20-l820. If you are
using CMS to develop programs to run under
other operating systems, see !~A !!£1Y2!
!1~£!!!!l~ !g£!l!!IfllQ: QE~!:~!!~g ~Ist~m§ in
~ !!£!Yg! !1ac!!!~~, GC20-1821.
RELATED VM/370 PUBLICATIONS
If
you
use
the
Bemote
Coamunications sutsystea,
see
Additional descriptions of
various CftS
functions and commands that are normally
used by
system support
personnel are
described in
l]~ !!!!Y~l ~g£h!~~ 19£ili~ILJ1~:
~l§!~~ ~!Bg!g~~~!~§ 2y!g~,
Q]§!AtO!~§
GC20-1807
!!!~yg!
~E22!iDg
~~!!~
!!~!1!!IL37Q:
£gmmYn!£~tiBD§ ~YRsys!~
~§§!~2 QY!E~,
IPCS CMS
!!LJ1~:
1!~!!
(RS~a)
GC20-1816.
Asseabler language programmers may find
information atout the V!/370 asseabler in
Q~L!~,
!Q~!~,
A!E
!!LJIQ A§§embl~!
~gngygg~, GC33-4010,
and ~~!§ !A~ !BL370
A§§~!~!~! ~!Bg!~Am~!~§ §y!g~, GC33-4021.
Qy!g§, GC20-1806
BELATED PUBLICATIONS FOB
METHOD SEBVICES USERS
ll~
Spooling
the
lEB
commands are described
lnt§!g£~i!~
~!B~!e~
VSA~
AND
ACCESS
in the
£B~~!2!
~Ist§! (IP£E) ~§§!~§ Qyig~, GC20-1823, and
not in this publication.
Information describing the CMS coamand
CPEREP, a command used to generate output
reports from
VM/370's error
recording
records, is contained in the:
Details on
the use of
OS/VS EREP
operands, required to aake use of CPEREP,
are contained in:
CMS support of access method services is
based on DOS/VS access method services. The
control statements that you can use are
described in DO~L.!~ AC£!§.§ Be.!1!.2g ~!vi.E~.§
y§~!~§
~yide, GC33-5382.
Error .ess~ges
produced by the access method serV1ces
program, and return codes and reason codes,
are listed in RQ~!~ ~§§§age§, GC33-5379.
For a detailed description of DOS/VS
VSAB macros and macro parameters, refer to
the RQ~L!~ ~YE§!~iso!
!nd lL~ ~!£!B'§,
GC33-5373. For information on OS/VS VSAM
macros, refer to ~~!a !irtu!l ~!.2!!~
j££~§§
~~!hOE (VSAM)
1!.2~!!A~!~§
~uig!,
GC26-3818.
BELATED PUBLICATIONS FOR CMS/DOS OSERS
There are three publications available
as ready reference material when you use
VM/370 and CMS. They are:
l]~ !!~~y~l ~g£h!~ 19£!!i!IL~l~:
2Y!£! Gu!g§ !B! ~§~!§, GX20-1926
~B~~~~g§
(Q§~§!g! ~§~!),
GX20-1961.
The CftS !SERV command invokes the DOS/VS
ES!BV program, and uses, as input, the
control statements that you vould use in
DOS/VS.
These
control statements
are
described in ~y!de to'!!§ ~CSL!~ A§§~~R!!!,
GC33-4024.
Linkage editor control statements, used
when invoking the DOS/'S linka~e editor
under CftS/DOS, are described 1n DO~!~
~I§!~! ~Bn!!B! ~!!!~~ent§, GC33-5376.
preface
v
\
(
vi
IBK VK/310: eKS User's Guide
Pg. of GC20-1819-2 Rev 8arch 30, 1979 by Supp. SD23-9024-1 for 5748-118
RBLATED '8/370 PUBLICATIONS
Additional descriptions of
various C8S
functions and co.mands that are norDally
used by
system support
personnel are
described in
!!A Virtual
SIS!!!
A~£hiD!
lA£il!!IL11Q:
f!2g!~!!!!~§ Gu!g~,
QE§Iator~ ~uide,
GC20-1807
If
you
use
the
Remote
Spooling
Communications Subsystem,
see the
!~~
Ii!!!!!
~~£hi~~
f~£!!!1IL37~:
]~~g1~
~E~2li~g
~2mmy~ic~ti2~§
Y§~~~ ~~~g~,
~Y~§I§i~!
GC20-1816.
Assembler language programmers may find
information about the V!/370 assembler in
Q~L!~,
QQ~L!~,
!!lg
!!Ll1Q
!§§~!~!~!
Lgllg~g~, GC33-4010,
and £~L12 ~ll~ !~Ll1Q
!§§~~~!!! f!QgI~~!~§ ~y!g~, GC33-4021.
GC20-1806
RELATED PUBLICATIONS FOR
8ETHOD SERVICES USERS
IPCS eftS
.!nt§!A£!!~!
(IP~~)
~§!~§
in the
Con!!Q!
GC20-1823, and
VSA! AND
ACCESS
comaands are described
1M !U370:
~Iste.
(~~£~)
~2~!~!
~uig~,
not in this publication.
Inforaation describing the CMS command
CPEREP, a command used to generate output
reports froa
V8/370's error
recording
records, is contained in the:
Details on
the use of
OS/'S EREP
operands, required to aake use of CPEREP,
are contained in:
CMS support of access method services is
based on DOS/VSE and VSE/VSAM. The control
state.ents that you can use are described
in Y2!llg !~~L!2!~
~2~m~nd ~B~ ~~£!2§,
SC24-5144. Error messages produced by the
access method services program, and return
codes and reason codes, are listed in
QQ~!~! ~~~g!§, GC33-5379.
For a detailed description of VSE/VSAM
macros and macro parameters, refer to the
QQ2L!SE ~~£!Q Y§~~ GuiQ~, GC24-5139. For
inforDation on OS/VS VSA! macros, refer to
Q~L!~ !!Iiyal ~iQr~~ !££!§§ ~~iAQ~ (!~!~)
prQg~A!~~~ Qy!de, GC26-3818.
RELATED PUBLICATIONS FOR CMS/DOS USERS
For information on OS/VS tape label
processing,
discussed
with
"Label
Processing in
OS Simulation"
in this
publication, refer to:
The CMS ESERV command invokes the DOS/VSE
ESERV program, and uses, as input, the
control statements that you would use in
DOS/VSE.
These control
statements are
described
in
§Y!Q!
1Q
th!
QQ2L!~~
!§§~Dble!, GC33-4024.
Linkage editor control statements, used
when inVOking the DOS/VSE linkage editor
under CMS/DOS, are described in ~~~!§~
§I§!~ £~B!!~! Statements, GC33-5376.
There are three publications available
as ready reference material when you use
V8/370 and C8S. They are:
ill !irtual
!1~£hine
For information on DOS/VSE and CMS/DOS
tape
label processing,
refer to
the
following publications:
~Q~!§! TaE~
Labels, GC33-5374
Fa£!!itIfllQ:
~OSL!~~ LI~~~,
gYi£~ ~!g!
CO.lAnds
(~~!ra!
~2.!!ands
(Qthy
GX20-1995.
!olum!
~,
SY33-8560
fo! Y§!!§, GI20-1926
y§!!), G12o-1961.
!A!!l
Preface
v
March 30, 1919
vi
IBK YK/310: eMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1919 by Supp. SD23-9024-1 for 5148-118
Contents
The entries in this Table of Contents are accumulative and reflect the
VM/370 Basic System Extensions Program Product, Program Number 5748-118.
Summary of Amendments. • •
xiii
PART 1. UNDERSTANDING CMS ••
• .1
SECTION 1. WHAT IT MEANS TO HAVE A CMS
VIRTUAL MACHINE • • • • • • _ • • • • • • 3
How You Communicate With VM/310.
• .3
Getting Commands Into the System
•• 5
Loading CMS in the Virtual Machine: The
IPt Command • • • • • • • • • • • • • • 6
Logical Line Editing Symbols • • • • • • • 6
How VM/370 Responds to Your Commands •• 8
Getting Acquainted With CMS • • • • • • • 10
Virtual Disks and How They Are Defined. 11
Permanent Virtual Disks. •
• • • 11
Defining Temporary Virtual Disks • • • 12
Formatting Virtual Disks • • • • • • • 12
Sharing Virtual Disks: Linking • • • • • 13
Identifying Your Disk To CMS: Accessing. 14
Releasing Virtual Disks • • • • • • • • 14
Releasing Virtual Disks (21~~=!!~) • 14.1
SECTION 2. VM/370 ENVIRONMENTS AND MODE
SWITCHING • • • • • •
• 17
• 11
The CP Environment • • • • • • •
The CMS Environment • • • • •
18
• 19
EDIT, INPUT, and CMS Subset.
DEBUG. _ • • • • • • • • • • •
• 20
CMS/DOS. • • • • • • • • • • • • • • • 21
Interrupting Program Execution • •
• 21
Virtual Machine Interruptions. •
• 22
Control Program Interruptions. •
• 23
Address Stops and Breakpoints. •
• 23
4
•
SECTION 3. WHAT YOU CAN DO WITH
VM/370-CMS COMMANDS • • • •
• 25
Command Defaults • • • • • •
• 25
Commands to Control Terminal
Communications. • • • • • •
• 25
Establishing and Terminating
Communications with VM/370~
• 25
Controlling Terminal Output ••
• 26
Commands to Control How VM/370
Processes Input Lines • • • • •
• 28
Commands to Control How VM/310
Processes Input Lines (5148-IX8). • 28.1
Controlling Keyboard-dependent-Com munica tions. • • • • • • • • • • • 30
Commands to Create, Modify, and Move
Data Files and Programs • • • • •
• 31
Commands that Create Files • • • • • • 31
Commands that Modify Disk Files.
• 33
Commands to Move Files • • • • •
• 33
Commands to Print and Punch Files •• • 34
Commands to Develop and Test OS and CMS
Progr ams. • • • • • • • • •
'. 35
Commands to Develop and Test DOS
Programs. • • • • • • • • •
• 36
addition of the
Commands Used in Debugging Programs. • _
Commands to Request Information~ • • • •
Commands to Request Information About
Terminal Characteristics. • _ _ • • •
Commands to Request Inforaation About
Data Files • • • • • • • • • • • • • •
Commands to Request Information About
Your Virtual Disks. • • • • • • • • •
Commands to Request Information About
Your Virtual ftachine. • • • • •
37
38
38
39
40
40
SECTION 4. THE CftS FILE SYSTEM. _
• 43
CMS File Formats • • • • • • • • ~ _
43
How CMS Files Get Their Names. • • • • _ 43
How CMS Files Get Their Names
(~1!H!=1!!H· • • '. '. • • • • • • • • • ,. 44
Duplicating Filenames and Filetypes. • 44
What Are Reserved FiletYFes? • • _
45
Filetypes for CftS Commands • • •
• 46
Output Files: TEXT and LISTING •
• 48
Filetypes for Temporary Files. •
50
Filetypes for Documentation. _ _
50
Filemode Letters and Numbers • •
• 51
When to Specify Filemode Letters:
Reading Files • • • • • • • _ • •
52
When to Specify File.ode Letters:
Writing Files • • • _ •
• 54
How Filemode Numbers are Used. •
• 54
Managing Your CftS Disks.
56
CMS File Directories • • • • • • • • • ,. 56
CMS Command Search Order •
• •• 57
SECTION 5. THE CftS EDITOR.
• • • '. 61
The EDIT Command • • • • •
61
Writing a File Onto Disk •
62
EDIT Subcommands • • • • • • • _ •
63
The Current Line Pointer • • • • • •
65
68
Verification and Search Columns.
Changing, Deleting, and Adding Lines. '. 69
Describing Data File Characteristics • • 73
Record Length. • • • • • •
73
Record Format. • • • • • •
• 75
Using Special Characters • •
76
Setting Truncation Limits.
18
Entering a Continuation Character in
Column 72 • • • • • •
79
Serializing Records. • • • • • • •
80
Line-Number Editing • • • • • • • • • • 81
Renumbering Lines. • •
• • _ _ • • 82
Controlling the Editor • • • • • •
84
Communicating with CMS and CP. •
84
Changing File Identifiers.
• 85
Controlling the Editor's Displays~ • • 86
preserving and Restoring Editor
Settings. • • • • • • • • • • _
• 86
preserving and Restoring Editor
Settings (~1!~=1~~) .
. 86.1
X. Y, =, ? Subcommands • • • • • • • • 87
Contents
vii
Pg. of
GC20~1819-2
Rev March 30, 1979 by Supp •. SD23-9024-1 for 5748-XX8
What To Do When You Run O~t of Space • 88
Summary of EDIT Subcommands. • • • • • • 91
SECTION 6. INTRODUCTION TO THE EXEC
PROCESSOR • • • • • •
• • • • 95
Creating EXEC Files.
• • • 95
Invoking EXEC Files.
• 96
PROFILE EXECs. • • • •
• 97
Executing Your PROFILE EXEC. • • • • • 98
CMS EXECs and How To Use Them.
• 98
Modifying CMS EXECs. •
• • • • • 100
Summary of the EXEC Language Facilities.100
Arguments and Variables. • • • •
.101
Assignment Sta temen ts. • • • •
.102
Built-in Functions and Special
Variables. • • • • • • •
.103
Plow Control in an EXEC. •
.103
Comparing Variable Symbols and
constants • • • • • • • • • • • • • • 105
Doing I/O With an EXEC. •
.106
Monitoring EXEC Procedures
.107
Summary of EXEC Control Statements and
Special Variables • • • • • • • •
.109
SECTION 7. USING REAL PRINTERS,
PUNCHES, READERS, A~D TAPES •
.113
CMS Unit Record Device Support • •
.113
Using the CP Spooling System • •
.113
Altering Spool Files • • • • •
.115
Using Your Card Punch and Card Reader
~n CMS • • • • • • • • • • • • • • • • 116
Handling Tape Files in CMS • • • • • • • 118
Using the CMS TAPE Command • • • • • • 119
Tape Labels, in CMS • • • • • • •
.121
Tape Labels in eMS (11~~-!!~).
• •• 121
User Responsibilities (~1~§-!!§)
• .122
Label Processing in OS Simulation
(~I~§- !!!D. • • • • • • • • • • • • • • 1 22
Label Processing in CMS/DOS
• • 122.7
(~1~§- .!.!§J.. • • • • • • • • •
CMS TAESL Macro (5748-XX8) • •
122.10
Tape Label ProcessIng by-CMS
122.10
Commands (~1!.H~.-.!.!§.) • • ••
122.12
LABELDEF Command (~1!§'-.!!§') ••
End-of-Volume and End-of-Tape
Processing (21!&-.!.!!!> • • • .'. • • 122. 13
Error Processing (~1!§'-.!.!§'). •
122.14
The MOVEFILE Command • • • • • • • • • 122
The MOVEFILE Command (~1.!!~-!!§) •• 122.14
Tapes Created by OS Utility
Programs • • • • • • • • • • • • • • ~122
Tapes Created by OS Utility
Programs (~1!§-.!!§) • • • • • • • 122.15
Specifying Special Tape Handling
Options • • • • • • • • • • • •
.123
Using the Remote Spooling
Communications Subsystem (RSeS)
.123
PART 2. PROGRAM DEVELOPMENT USING CMS • • 125
SECTION 8. DEVELOPING OS PROGRAMS UNDER
CMS • • • • • • • • • • • • • • •
.127
Using OS Data Sets in CMS • • • • •
.129
Access Methods Supported by CMS.
.130
Using the FILEDEF Command.
.131
.131
Specifying the ddname • • • • • •
Specifying the Device Type • • •
.132
Entering File Identifications.
.132
viii
IBM VM/370: CMS User's Guide
Specifying CMS Tape Label processing
(5748-XX8) . . . . . . . . . . . . . . . . 133
specffyIng Options • • • • • • .• • • • 133
Creating CMS Files From CS Data sets • • 134
Creating CMS Files From OS Data Sets
(5748-XX8). • • • •
• •••
• 134. 1
usI~~-ci~-Libraries. • • •
.• 136
'Ihe MACLIB Command • • • • • .• ,. '. • • 137
Using OS Macro Libraries •
• .140
Using OS Macros Under CMS • • • • •
.141
Assembling Programs in CMS • •
.143
Executing programs • • • • •
.144
Executing TEXT Files • •
• • • 144
'TEXT LIERARIES (TXTLIBS) • • • • • • • 145
Resolving External References~ •
.146
Controlling the CMS Loader •
.147
Creating Program Modules • • • •
.149
Using EXEC Procedures. • • • • • • • .149
SECTION 9. DEVELOPING DOS PROGRAMS
UNDER CMS • • • • • • • • • • • • • • • 151
The CMS/DOS Environment • • • • • • • • • 151
DL/I in the CMS/DOS Environment. •
.152
Using DOS Files on DOS Disks • • • • • • 154
Reading DOS Files • • • • • • • • • • • 154
Creating CMS Files from DOS Libraries. 155
Using the ASSGN Command • • • • • • • • • 156
Using the ASSGN Command (~1!§=.!!§') •• 156.1
Manipulating Device Assignments.
.157
Virtual Machine Assignments. •
• .158
Using the DLBL Command. • • • • •
.159
Entering File Identifications • • • • • 159
Using DOS Libraries in CMS/DOS
.160
The SSERV Command.
• • • • •
.161
The RSERV Command.
• ••• _
.162
The PSERV Command.
• .162
The ESERV Command.
• • • •
• .163
The DSERV Command.
.163
Using DOS Core Image Libraries.
.164
Using Macro Libraries. • • • • • •
.164
eMS MACLIBs.. • • • •
• .165
Creating a CMS MACLIB. •
• .165
The MACLIB Command • • • • • • _
.166
DOS Assembler Language Macros Supported. 169
Assembling Source Programs • • • • • • • 171
Link-editing Programs in CMS/DOS • • • • 172
Linkage Editor Input • • • • • • • • • 173
Linkage Editor Output: CMS DOSLIEs • • 174
Executing programs in CMS/DOS. _ • • • • 175
Executina DOS Phases • • • • • • • • • 175
Search Oider for Executable Phases • • 176
Making I/O Device Assignments.
• .177
Specifying a Virtual Partition Size • • 177
Setting the UPSI Byte. • • • • •
.178
Debugging Programs in CMS/DOS • • _ • • 178
Using EXEC Procedures in eMS/DOS • • • 179
SECTION 10. USING ACCESS METHOD
SERVICES AND VSAM UNDER CMS AND
CMS/DOS • • • • • • • • • • • •
• .181
Executing VSAM Programs Under CMS • • • 181
Using the AMSERV Command • • • • _ • • • 182
AMSERV Output Listings • • • • • • • • 183
Controlling AMSERV Command Listings • • 184
Manipulating OS and DOS Disks for Use
with AMSERV • • • • • • • • • • _ • • • 185
Data and Mastercatalog Sharing.
.185
Disk Compatibility • • • • • • • • • • 186
Pg. of GC20-1819-2 Rev March 30, 1979 by SUppa SD23-9024-1 for 5748-XX8
Using VM/370 Minidisks • •
.187
Using The LISTDS Command
.187
Using Temporary Disks. •
• • • • • 188
Defining DOS Input and Output Files • • • 190
Using VSAM Catalogs • • • • • • • • • • 190
Defining and Allocating Space for
VSAM files • • • • • • • • • • • • • • 194
Using Tape Input and Output • • • • • • 196
Defining OS Input and Output Files • • • 197
Allocating Extents on OS Disks and
Minidisks • • • • • • • • • • • • • • 198
Using VSAM Catalogs • • • • • • • • • • 199
Defining and Allocating Space for
VSAM files. • •
• • • •
.202
Using Tape Input and Output • • • • • • 204
Using AMSERV Under CMS • • • • • • • • • 205
Using the DEFINE and DELETE Functions.205
Using the REPRO, IMPORT, and EXPORT
(or EXPORTRA/IMPORTRA) functions • • • 207
Writing EXECs for AMSERV and VSAM • • • 209
SECTION 11. HOW VM/370 CAN HELP YOU
.211
DEBUG YOUR PROGRAMS •
.211
Preparing to Debug • •
.211
When a Program Abends.
Resuming Execution After a Program
.212
Check • • • • • • • • • •
Using DEBUG Subcommands to Monitor
Program Execution. • • • • • • •
.213
Using Symbols with DEBUG • • • • • • • 214
What To Do When Your Program Loops • • • 216
Tracing Program Activity • • • • • • • • 216
Using the CP TRACE Command •
• .217
Using the SVCTRACE command.
.219
Using CP Debugging Commands. •
.219
Debugging with CP After a Program
Check. • • • • • • • • •
• .220
Program Dumps. • • •
• • • • • • • • 221
Debugging Modules. •
• • • • • • • .221
Comparison Of CP And CMS Facilities For
Debugging. • • • •
• • • • • • ~ .222
What Your Virtual Machine Storage Looks
Like. •
•• • • • • • • •
• .223
Shared and Nonshared Systems • • • • • 223
SECTION 12. USING THE CMS BATCH
.227
FACILITY • • • • •
Submitting Jobs to the CMS Batch
Facility. • • • • • • • • • • •
• .227
Input to the Batch Machine • •
• .227
How the Batch Facility Works.
• .230
Preparing Jobs for Batch Execution • • • 231
Restrictions on CP and CMS Commands
in Batch Jobs • • • • • • • • • • • • 232
Batch Facility output • • • • • • • • • 232
purging, Reordering, and Restarting
Batch Jobs. •
• • • • • • • 233
Using EXEC Files for Input to the Batch
Facility • • _ • • • • • •
• .234
Sample System Procedures for Batch
Execution _
• • • • • • • 235
A Batch EXEC for a Non-CMS User • • • • 236
SECTION 13. PROGRAMMING FOR THE CMS
ENVIRONMENT • • • • •
Program Linkage. • • •
Return Code Handling
Parameter Lists. • •
.239
• • 239
• • 240
.240
Calling a CMS Command from a Program • • 241
Execut ing Progr am Modu les _ •
.242
The Transient program Area" • _ • • • 243
eMS Macro Instructions • • • • • • • ~ .243
Macros for Disk File Manipulation • • • 244
CMS Macros for Terminal
.250
Communi cat ions. • • • • •
CMS Macros for unit Record and Tape
.250
I/O • • • • • • • • '. • •
Interruption Handling Macros
• • • 251
Updating Source Programs Using CMS • • • 251
.252
The UPDATE Philosophy • • •
Update Files • • • • • • • •
.252
• • • 254
sequencing Ontput Records. •
.257
Multiple Updates • • • • •
The VMFASM EXEC Procedure.
.262
• _ 265
PART 3. LEARNING TO USE EXEC
SECTION 14. BUILDING EXEC PROCEDURES _ .267
What is a Token? •
• _ .267
Variables • • • • • • • • • _ • • • • • • 268
Arguments • • • • _ •
~ • • • • • • 272
Using the &INDEX Special Variable • • • 273
Checking Arguments. • • • • • •
.274
Execution Paths in an EXEC
• • 275
Labels in an EXEC Procedure. •
• .275
Conditional Execution with the &IP
Statement • •
• ••
• .276
Eranching with the &GOTO Statement • • 277
Eranching with the &SKIP Statement • • 279
Using Counters for Loop Control • • • • 280
Loop Control with the BLOOP Statement.280
Nesting EXEC Procedures • • • • • • • • 282
Exiting From EXEC Procedures • • • _ .283
Terminal Communications • • • • • • __ .284
Reading CMS Commands and EXEC Control
statements from the Terminal. _ • _ .285
Displaying Data at a Terminal • • • _ .286
Reading from the Console Stack _ _
.289
Stacking CMS Commands. • •
.291
Stacking Lines for EXEC to Read.
.292
Clearing the Console Stack
_ .293
File Manipulation with EXECs.
• • • 294
Stacking EXEC Files. • • • • • • • • .294
SECTION 15. USING EXECS WITH CMS
COMMANDS. • • • • • •
• .299
Monitoring CMS Command Execution
• • 299
Handling Error Returns Prom CMS
Commands. • • • • • • • • • • •
_ .300
Using the &ERROR Control Statement • • 300
Using the &RETCODE Special variable • • 301
Tailoring CMS Commands fer Your Own Use.302
Creating Your Own Default Filetypes • • 303
SECTION 16. REFINING YOUR EXEC
PROCEDURES • • • • • • • •
Annotating EXEC Procedures • • • • _
Error Situations • • • • •
Writing Error Messages •
Debugging EXEC Procedures.
Using CMS Subset • • • • • • • • •
Summary of EXEC Interpreter Logic.
•
•
•
•
•
•
•
.305
,.305
.306
.306
.308
.308
.309
SECTION 17. WRITING EDIT MACROS.
• .311
Creating Edit Macro Files • • • • ~ • • • 311
How Edit Macros Work • • • • • _ • • • • 311
Contents
ix
Pg. of GC20-1819-2 Rev March 30, 1979 by SUppa SD23-9024-1 for 5748-XX8
The Console Stack. • • • • • • •
.313
Notes on Using EDIT Subcommands. •
.314
The STACK Subcommand • •
• • • • .317
An Annotated Edit Macro. •
.318
User-Written Edit Macros •
.320
SMACROS. •
.320
SMARK. • • •
.321
SPOINT • •
.323
SCOL • • •
.324
PART 4. LEARNING TO USE THE HELP
FACILITY (21~~=!X8) • • • •
.324.1
SECTION 18. HELP FILE NAMING CONVENTIONS
AND CREATION (2148=!!~) • '.
• .324.3
Naming Conventions (21~8-!!~) • • • • • 324.3
HELP File Creation (.21~8-!!~) • • • • • 324.4
Enclosing Text (.BX Format Word)
(.21.L!!l=!!~). • • • • • • • • • • .• • 3 24 • 6
Placing Comments in HELP Files (.CM
Format Word) (57~~=!X8) • • • • • .324.7
Conditional Display of Text (.CS
Format Word) (21!!§'=!!~) • • • • • .324.8
Use of Format Mode (.FO Format
Wor d) (.21.L!l!=!!l!). • • '. • • • • • • 324 .8
Indenting Text (.IN and .IL Format
Words) (21.L!~=!X8) • • • • • • • • .324.8
Use of Offsets (.OF Format Word)
(.21.L!!l=!!!!). • • • • • • • • • • • 324. 1 0
Spacing between Lines of Text (.SP
Format Word) (57!!~=!X8) • • • • • 324.11
Translating Output Characters (.TR
Format Word) (57.L!~=!!~)
• • 324.13
APPENDIX B: SUMMARY OF CP COMMANDS • • • 333
APPENDIX C: CONSIDERATIONS FOR 3270
DISPLAY TERMINAL USERS • • • • • _ • • • 339
Entering Commands. • • • • • • • • • • .339
Setting Program Function Keys. •
• .339
Controlling the Display Screen
• • • 340
Console Output • • • • •
.342
Signaling Interruptions. • • •
• • • 343
Halting Screen Displays • • • • • • • • 344
Using the CMS Editor with a 3270 • • • • 344
Entering EDIT Subcommands • • • • • • • 344
Controlling the Display Screen • • • • 346
The Current Line Pointer • • • • • • • 347
Using Program Function Keys. • •
.348
Using the Editor in Line Mode. •
.348
Using Special Characters on a 3270 • • 349
Using APt with a 3270. • • • •
• • • 350
Error Situations. _ • • • • • _
.351
Leaving the APL Environment. _ •
.351
Using the 3277 Text Feature. •
• • • 352
Error Situations • • _ • • •
• • • 352
Leaving the Text Envircnment
• • • 352
.325
APPENDIX D: SAMPLE TERMINAL SESSIONS • • 353
Sample Terminal Session Using the
Editor and CMS File System Commands • • 354
Sample Terminal Session Using
Line-Number Editing • • • • • • • • • • 362
Sample Terminal Session For OS
Programmers. • • • • • • • • • •
.365
Sample Terminal Session for DOS
Programmmers. • • • • • • • • • •
.369
Sample Terminal Session Using Access
Method Services. •
• • • 375
APPENDIX A: SUMMARY OF CMS COMMANDS • • • 327
INtEX • • • • • • • • • • • • • • • • • • 383
APPENDIXES • • • • • •
x
IBft Vft/370: CftS User's Guide
Figure
1.
Figure
2.
Figure
Figure
3.
4.
Figure
5.
Figure
6.
Figure
7.
VM/370 Environments and Mode
sw itching •••••••••.•••••.••••.••• 24
Filetypes Used by CMS
Figure 15.
Co.mands •••••••••••••••••••••• 47
Figure 16.
Filetypes Used in CMS/DOS ••••• 50
How CMS Searches for the
Command to Execute~ ••• _ ••••••• 59
Positioning the Current Line
Pointer •••••• _•••••••••••••••• 68
Bumber of Records Handled by
the Editor •••••• ~ ••••••• _ •• ~ •• 75
Summary of EDIT Subcommands
CHS •••••••••••••••••••••••••• 110
Figure 17.
Figure 18.
Figure 19.
Figure 20.
Figure 21.
ftacros •••••••••••••••• ~.~ •••• 91
Figure
8.
Figure
9.
Figure 10.
Figure 11.
Figure 12.
Figure 13.
Figure 14.
Su.mary of EXEC Built~In
Functions •••••••••••••••••••• 103
Summary of EXEC Control
State.ents •••••••••••• ~ •••••• 109
EXEC Special Variables ••••••• 112
OS Terms and CMS Equivalents.128
CMS Co •• ands That Recognize
OS Data Sets and OS Disks •••• 129
creating CMS Files From OS
Data Sets ••••• ~_ ••••••••••••• 136
OS Macros Simulated by CMS ••• 142
CMS/DOS Commands and CMS
Commands with Special
Operands for CMS/DOS •••••••• ~153
DOS/VS Macros Supported by
Figure 22.
Figure 23.
Figure 24.
Figure 25.
Figure 26.
Figure 27.
Figure 28.
Figure 29.
Summary of DEBUG Subcoamands.215
Comparison of CP and CMS
Facilities for Debugging ••••• 222
Siaplified CMS Storage Map ••• 22Q
Sample C~S Assembler Program
Entry and Exit Linkage ••••••• 240
A Sample Listing of a
Program ~hat Uses CMS Macros.249
Updating Source Files with the
UPDATE Command ••••••••••••••• 255
An Update with a Control
File •••• ~ •••••••• ~ ••• _~._~._.261
CMS Command Summary ••• ~ •••••• 328
CMS Commands for system
program.ers •••••••••••••••••• 332
CP privilege Class
Descriptions ••••••••••••••• ~.333
CP Command Sumaary •••.•••••••• 334
3270 Screen Display •••••••••• 343
How the eMS Editor Formats
a 3270 Screen •••••••••••••••• 345
)
Contents
xi
(
~
(
xii
IBM VM/370 eMS User's Guide
Sum.ary of Amendments
for GC20-1819-2
Vft/370 Release 6 PLC 1
SUPPRESSION
LINE
OF
PASSWORDS ON
THE
COMMAND
SPECIAL ftESSAGE FACILITY
!~!:
!§!: Program Feature
V8/370 supports a
system generation
option that prevents
passwords from
being entered on the same line as LOGON,
AUTOLOG,
and
LINK
commands. .
The
passwords must be entered so that they
are not displayed or are masked. This
support is mentioned where there are
examples showing the
password being
entered on the same line.
program Feature
The special message facility is a method
of transferring messagEs from a user to
a specially programmec receiving virtual
machine for processing. Tbis support is
reflected in "Section 3. What You Can Dc
With Vft/370-CftS Commands."
MISCELLANEOUS
!~! ~B~ Cb~Bged:
3218 KODEL 2A DISPLAY STATION
Documentation
Technical and editorial changes have
been made throughout tbis Fublication.
!§!: Program Feature
CP and CMS editor support the 3278 Kodel
2A Display Station. This is a 20-line
display console.
Support is reflected
in "Appendix C. Considerations for 3270
Display Terminal Users."
)
summary of Amendments
xiii
Su.mary of Amendments
for ~C20-1819-1
as updated by TNL GN25-0411
V!/370 Release 5 PLe 1
DOS/VS RELEASE 34 SUPPORTED
!~!:
Program Feature
CMS/DOS supports DOS/VS
Release 34.
This sup Fort includes a new operand of
the SET ccmmand, DOSLBCNT, and a new
operand of the QUERY command, DOSLBCBT.
SET DOSLBCNT allows a user to establish
the number of SYSLST lines per page.
QUERY DOSLNCBT displays
the current
number
of
SYSLST lines
per
page
established by the SET DOSLBCIT.
This release also contains support for
the 3330 !odel 11 and 3350 DASD devices
as attached devices. DOS/VOS Release 34
information is contained in "Section 9.
Developing DOS Programs under C!S."
I
\
(
xiv
IB8 V8/370: CftS User's Guide
Summary of Amendments
for GC20-1819-1
V8/370 Release 4 PtC 1
NEW DEVICES SUPPORTED
!~!:
Programming and Documentation
VM/370
supports
the
3270
display
devices.
The "Preface" is updated to
indicate
that
information
about
operating 3210 disflay
terminals is
applicable
to the
the 3215,
3216
Controller Display Station,
3211, and
3278 Display Stations.
It is also
applicable to 3138,
3148, and 3158
Display Ccnsoles when used in display
mode. Any information pertaining to the
IBM 3284 or 3286 Printer, also pertains
to the 3281, 3288, and 3289 Printers.
The
"Preface" is
also
indicate
that
the
Communications Controllers
to as 310x.
upda ted
to
3704/3705
are referred
]n~!IQn~~ntal
~~!~!
1~!1!~, s~~ !!i~S~D~
.
~~£2!~!~g,
(lRE~) R!~g!~m
12g!£, Order No. SY25-7101
In order to make use of the CPEREP command,
both of the following publications are
required. The first publication provides
general information on the usage of the
command and detailed information on ccmmand
~perands
applicable only to VM/310.
The
second
publication
Frovides
detailed
information on the operands tbat are common
to both VM/310 and OS/VS.
DOCUMENTATION UPDATE
~~s~g~~:
Documentation only
"Section 8.
Developing
OS Programs
Under CMS" now includes a description of
the AUXPROC option
that allows the
FILEDEF command to use an auxiliary
processing routine to receive control
during I/O processing.
"Section
10.
Using
Access
Method
Services and VSAM" has been rewritten to
include a
description of
Data and
Master-catalog
Sharing,
Disk
Compatibility, and VSAM Allocation.
In
addition,
minor
technical
and
editorial corrections have been made.
Program logic information describing the
interface between CMS and CS/VS EREP, and
describing OS/VS EBEP, is contained in:
The following areas in this publication
reflect CPEREP documentation changes:
Preface
Appendix A
1M/370 SUPPORTS OS/VS EREP (IFCEREP1)
~hsD~~~:
Program and Documentation
The CPEREP command now uses all edit and
format operands that are available to
OS/VS
EREP.
Because
of
VI1/310s·
compatibility with OS/VS EREP VM/310
relies
cn
existing
OS/VS
EREP
documentation.
Therefore,
VM/310 no
longer publishes the following:
)
Summary of Amendments
xv
(
\
(
xvi
IBM VM/3l0: eMS User's Guide
Part 1. Understanding eMS
Learning how to use CMS is not an end in itself: you have a specific
task or tasks to do, and you need to use the computer to perform them.
CMS has been designed to make these tasks easier, but if you are
unfamiliar with CMS, then the tasks may seem more difficult.
The
informativn contained in Part 1 of the user's guide is organized to help
you make tbe acquaintance of CMS quickly, so that it enhances, rather
than impedes, the performance of your tasks.
"Section 1. What It Means To Have a CMS Virtual Machine" introduces
you to VM/310 and its,conversational component, CMS. It should help you
to get a picture of how you, at a terminal, use and interact with the
system.
During a terminal session, commands and requests that you enter are
processed by different parts of the system. How and when you can
communicate with these different programs, is described in "Section 2.
VM/310 Environments and Mode Switching."
There are almost two hundred commands and subcommands comprising the
VM/310 language. There are some that you may never need to use; there
are others that you will use over and over again. "Section 3. What You
Can bo With VM/310-CMS Commands" contains a sampling of commands in
various functional areas, to give you a general idea of the kinds of
things you can do. and the commands available to help you do them.
Almost every CMS command that you enter results in some kind of
activity with a direct access storage device (DASD), known in CMS simply
as a disk, or minidisk. Data and programs a~e stored on disks in what
are called "files." "Section 4. The eMS File System" introauces you to
the creation and handling of CMS files.
~Section 5.
The CMS Editor" contains all the basic information you
need to create and write a disk file directly from your terminal, or to
correct or modify an existing CMS file.
Just as important as the CMS editor is another CMS facility, called
the EXEC processor or interpreter. Using EXEC files, you can execute
many commands and programs by entering a single command line from your
terminal, or you can write your own eMS commands.
"Section 6.
Introduction to the EXEC Processor" presents a survey of the basic
characteristics and functions of EXEC.
"Section 1. Using Real Printers, Punches, Readers, and Tapes"
discusses how to use punched cards and tapes in CMS, and how to use your
virtual printer and punch to get real output.
»
Part 1. Understanding CMS
1
I
~
2
IBM VM/310 eMS User's Guide
March 30, 1979
Section 1. What It Means To Have a eMS
Virtual Machine
Virtual Machine Facility/370 (VM/370) is a system control program that
controls "virtual machines."
A virtual machine is the functional
equivalent of a real computer, but where the computer has 'lights,
buttons, and switches on the real console to control it, you control
your virtual machine from your terminal, using a command language of
active verbs and nouns. There are actually three command languages, CP,
CMS, and RSCS.
The command languages correspond roughly to the four components of
VM/370: the Control Program (CP), the Conversational Monitor System
(CMS), the Remote Spooling Communications Subsystem
(RSCS), and the
Interactive Problem Control System (IPCS). CP controls the resources of
the real machine; that is, the physical machine in your computer room;
it also manages the communications among virtual machines, and between a
virtual machine and the real system.
CMS is the conversational
operating system designed specifically to run under CP; it can simulate
many of the functions of the OS and DOS operating systems, so that you
can run many OS and DOS programs in a conversational environment. RSCS
is a subsystem designed to supervise transmission of files across a
teleprocessing network
controlled by
CP.
IPCS
provides system
programmers and installation support personnel with problem reporting
and analysis functions.
Its commands execute in the CMS command
environment.
Although this publication is concerned primarily with using C8S, it
also contains examples of CP commands that you, as a C8S user, should be
familiar with.
How You Communicate with VM/370
When you are running your virtual machine under V8/370, each command, or
request for work, that you enter on your terminal is processed as it is
entered; usually, you enter one command at a time and commands are
processed in the order that you enter them.
You can enter CP commands from either the CP or CMS environment; but
you cannot enter CMS commands while in the CP environment. The concept
of "environments" in VM/370 is discussed in "Section 2.
VM/370
Environments and Mode switching."
After you have typed or keyed in the line you wish to enter, you
press the Return or Enter key on the keyboard. When you press this key,
the line you have entered is passed to the command environment you want
to have process it. If you press this key without entering any data,
you have entered a "null line."
Null lines sometimes have special
meanings in VM/370.
If you make a mistake entering a command line, V8/370 tells you what
your mistake was, and you must re-enter the entire command line. The
examples in this publication assume that the command lines are correctly
entered.
You can enter commands using any combination of uppercase and
lowercase characters; VM/370 translates
your input to ·uppercase.
Examples in this publication show all user-entered input lines in
lowercase characters and system responses in uppercase characters.
Section 1. What it Means to Have a C8S Virtual Machine
3
March 30, 1979
You use CP commands to communicate with the control program. CP commands
control the devices attached to
your virtual machine and their
characteristics.
For example, if you want to allocate additional disk space ,for a work
area or if you want to increase the virtual address space assigned to
your virtual machine, use the CP com~and DEFINE. cp takes care of the
space allocation for you and then allows your virtual machine to use ~t.
Or if, for example, you are receiving printed output at your terminal
and do not want to be interrupted by messages from other VM/370 users,
yau can use the CP command SET MSG OFF to refuse messages, since it is
CP that handles communication among virtual machines.
Using CP commands, you can also send messages to the VM/370 system
operator and to other users, modify the configuration of devices in your
virtual machine, and use the virtual machine input/output devices. CP
commands are available to all virtual machines using VM/370.
You can
invoke these commands when you are in the virtual machine environment
using CMS (or some other operating system) in your virtual machine.
The CP commands and command privilege classes are listed in "Appendix
B: Summary of CP Commands". The CP Commands applicable to the average
user are discussed in detail in the !!1Ld1.Q £1: £Q!!!!!!gl1£ !!~'!~~1!£~ .!.2!:
§~~!:g1 !!§~!:§.
The rest of the CP commands are discussed in !!1Ld1.Q
QEgEg12E~§ Qy!gg.
However, since many CP commands are used with CftS
commands, some of the CP commands you will use most frequently are
discussed in this publication, in the context of their usefulness for a
CMSapplication. To aid you in distinguishing between CMS commands and
CP commands, all CP commands used in examples in this publication are
prefaced with "CPU.
The CMS command language allows you to create, modify, and debug problem
or application programs and, in general, to manipulate data files.
Many as language processors can be executed onder CMS: the assembler,
VS BASIC, OS FORTRAN IV, OS COBOL, and OS PL/I Optimizing and Checkout
Compilers.
In addition, the DOS/VS COBOL and DOS/VS PL/I Program
Products are supported. You can find a comprehensive list of language
processors that can be executed under CMS and relevant publications in
the !HLdlQ !111!:QgUC!!Q~.
CMS executes the assembler and the compilers
when you invoke them with eMS commands. The ASSEMBLE command is used to
present examples in this publication; the supported compiler commands
are described
in the
appropriate 'DOS
and OS
program product
documentation.
The EDIT command invokes the CMS editor so that you can create and
modify files.
The EXEC facilities allow you to execute procedures
consisting of CP and CMS commands; they also provide the conditional
execution capability of a macro language. The DEBUG command gives you
several program debugging subcommands.
Other CMS commands allow you to read cards from a virtual card
reader, punch cards to a virtual card punch, and print records on a
virtual printer. Many commands are provided to help you manipulate your
virtual disks and file·s.
4
IBM VM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
You use the HELP command
how to use CP commands and
explanations of CP and CMS
when a brief explanation
sufficient, thereby avoiding
to a manual.
to display at your terminal information on
CMS commands_ subcommands, and EXECs, and
messages. You can issue the HELP command
of syntax,
a parameter, or function is
interrupting your terminal session to refer
Section 1. What it Means to Have a CMS Virtual Machine
4.1
March 30, 1979
4.2
IBM VM/370CMS User's Guide
Since you can invoke CP commands from within the CMS virtual machine
environment, the CP and CMS command languages are, for practical
purposes, a single, integrated command language for CMS users.
GETTING COMMANDS INTO THE SYSTEM
Before you can use CP and CMS, you should know {1}
how to operate your
terminal and {2} your userid (user identification) and password.
There are many types of terminals you can use as a V8/370 virtual
console.
Before you can conveniently use any of the commands and
facilities described in this publication, you have to familiarize
yourself with the terminal you are uS1ng. Generally, you can find
information about the type of terminal you are using and how to use it
with VM/370 in the !~L170 Ig£~ingl Q§g£~§ Qyigg. If your terminal is a
3767, you also need the I~~ 11£1 QEg!g!Q!~§ Qyig~·
In this publication, examples and usage notes assume that you are
using a typewriter-style terminal (such as a 2741). If you are using a
display terminal (such as a 3270), consult "Appendix c: Considerations
for 3270 Display Terminal Users" for a discussion of special techniques
that you can use to communicate with VM/370.
your userid is a symbol that identifies your virtual machine to VM/370
and allows you to gain access to the VM/37D system. Your password is a
symbol that functions as a protective device ensuring that only those
authorized to use your virtual machine can leg on.
The userid and
password are usually defined by
the system programmer for your
installation.
To establish contact with VM/370, you switch the terminal device on and
VM/370 responds with some form of the message
vm/37'0 online
to let you know that VM/370 is running and that you can use it.
If you
do not receive the "vm/370 online" message, see the !~L]lQ l~£~in~l
Q§~E~§ Q~ig~ for
specific directions. You can now press the Attention
key (or equivalent) on your terminal and issue the LOGON command to
identify yourself to the system:
cp logon smith
where SMITH represents a userid. The LOGON command is entered by
pressing the Return
(or Enter) key. If VM/370 accepts your userid, it
responds by asking you for your password:
ENTER PASSWORD:
)
You then enter your password,
terminal.
which may
be hidden, depending
on your
Section 1. What it Means to Have a CMS Virtual Machine
5
LOADING CMS IN THE VIRTUAL
~ACHINE:THE
IPt COMMAND
You load CMS in your virtual machine using the IPL command:
cp ipl cms
where "cms" is
assumed to be the saved system
name for your
installation's CMS.
You could also load CMS by referring to it using
its virtual device address, such as 190:
cp ipl 190
VM/370 responds by displaying a message such as:
eMS VERSION v.3 - 02/28/76
12:02
to indicate that the IPL command executed successfully and
loaded into your virtual machine.
C~S
that
is
Your userid may be set up for an automatic IPL, so that you receive
this message, indicating that you are in the CMS command environment,
without having to issue the IPL command.
Now you
operation.
can
enter
a
null line
to
begin
!2te: If this is the first time you are
assigned to you, you receive the message!
your
using a
virtual
machine
new virtual
disk
DMSACC112S DISK'A(191)' DEVICE ERROR
and you must "format" the disk, that is, prepare
files.
See "Formatting Virtual Disks" below.
it for use
with CMS
Logical Line Editing Symbols
To aid you in entering command or data lines from your terminal, VM/370
provides a set of logical line editing symbols, which you can use to
correct mistakes as you enter lines. Each symbol has been assigned a
default character value. These normally are:
~I.!!tQ2!
Logical
Logical
Logical
Logical
character delete
line end
line delete
escape
Character
--j-----I
¢
"
The logical character delete symbol (~) allows you to delete one or more
of the previous characters entered. The m deletes one character per a
entered, including the ¢ and I logical editing characters. For example:
ABC#WW results in AB
ABCWD results in~ABD
¢WDEF results in DEF
ABCmmm deletes the entire string
6
IBM VM/370
C~S
User's Guide
)
The logical line end symbol (I)
allows you to key in more than one
command on the same line, and thus minimizes the amount of time you have
to wait between entering commands. You type the t at the end of each
logical command line, and follow it with the next logical command line.
VM/370 stacks the commands and executes them in sequence. For example,
the entry:
query bliplquery rdymsglquery search
is executed in the same way as the entries:
query blip
query rdymsg
query search
The logical line end symbol also has special significance for the
function. Beginning any physical line with #CP indicates that you
entering a command that is to be processed by CP immediately.
If
have set a character other than I as your logical line end symbol,
should use that character instead of a t.
1Qg1fs!
ICP
are
you
you
~!n~ ~~!~te
The logical line delete symbol
(¢) (or ( for Teletype 1 Model 33/35
terminals)
deletes the entire previous physical line, or the last
logical line back to (and including)
the previous logical line end (').
You can use it to cancel a line containing many or serious errors. If a
• immediately precedes the ¢ sign, only the I sign is deleted, since the
I indicates the beginning of a new line, and the ¢ cancels the current
line. For example:
)
•
Logical Line Delete:
ABC#DEF¢ deletes the IDEF and results in ABC
ABCI¢ results in ABC
ABCIDEF¢iGHI results in ABCIGHI
ABCIDEF¢GHI results in ABCGHI
•
Physical Line Delete:
ABC¢ deletes the whole line
Note that when you cancel a line by using the ¢ logical line delete
symbol, you do not need to press a carriage return; you can continue
entering data on the same line.
The logical escape symbol
(")
causes VM/370 to consider the next
character entered to be a data character, even if it is normally one of
the logical line editing symbols (W, ¢, ", or #). For example:
ABC"¢D results in ABC¢D
""ABC"" results in "ABC"
)
lTrademark of the Teletype corporation, Skokie, Illinois.
Section 1. What it Means to Have a CMS Virtual Machine
7
If you enter a single logical escape symbol (") as the last character
on a line, or on a line by itself, it is ignored.
When you enter logical escape characters in conjunction with other
logical editing characters, the results may be difficult to predict.
For example, the lines:
AEC""mDEF
AEC""m~DEF
both result in the line:
ABCDEF
The logical line editing symbols are defined for each virtual machine
during VM/370 system generation. If your terminal's keyboard lacks any
of these special characters, your installation can define other special
characters for logical line editing. You can find out what logical line
editing symbols. are in effect for your virtual machine by entering the
command:
cp query terminal
The response might be something like:
LINEND t , LIHEDEL ¢ , CHARDEL m , ESCAPE "
LINESIZE 130, MASK OFF, APL OFF, ATTN OFF, MODE VM
You can use the CP TERMINAL command to change the logical line
editing characters for your virtual machine. For example, if you enter:
cp terminal linend /
Then, the line:
input t line /
input /
t
would be interpreted:
input # line
input
#
The terminal characteristics listed in the response to the CP QUERY
TERMINAL command are all controlled by operands of the CP TERMINAL
command.
HOW VM/370 RESPONDS TO YOUR COMMANDS
CP and CMS respond differently to different types of requests. All CMS
command responses
(and all responses to CP commands that are entered
from the CMS environment) are followed by the CMS ready message. The
form of the ready message can vary, since it can be changed using the
SET command. The long form of the ready message is:
R; T=7.36/19.89 09:26:11
8
IBM VM/370 CMS User's Guide
(
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-X18
If you have issued the command:
set rdymsg smsg
the ready message looks like:
R;
When you enter a command line incorrectly, you receive an error
message, describing the error. The ready message contains a return code
from the command; for example:
R (00028) ;
indicates that the return code from the command was 28.
If you enter a CP or CMS command that requests inforaation about your
virtual machine, the response should be the information requested. For
example, if you issue the command:
cp display g
CP responds by showing you the
general registers, for example:
GPR 0
GPR 4
GPR 8
GPR 12
=
=
=
=
00000003
00000848
00000008
00003238
00003340
C4404040
000132F8
FFFFFFFD
contents
00000710
00000040
00002B10
50013386
of
your virtual
aachine's
00000003
00002DFO
00002230
00000000
Similarly, if you issue the CMS command:
listfile
*
assemble c
you might receive the following information:
JUNK
MYPROG
ASSEMBLE C1
ASSEMBLE C1
If you enter a CP command to alter your virtual machine configuration
or the status of your spool files, CP responds by telling you that the
task is accomplished. The response to:
cp purge reader all
might be:
0004
~ILES
PURGED
Some CP commands, those that alter some of the characteristics of
your virtual machine, give you no response at all. If you enter:
cp spool e class x hold
you receive no response from CP.
Certain CMS commands may issue prompting messages, to request you to
enter more information.
The SORT command, which sorts CMS disk files,
is an example. If you enter:
sort in file a1 out file a1
Section 1. What it Means to Have a CMS Virtual Machine
9
March 30, 1979
you are prompted with the message:
DMSSRT604R ENTER SORT FIELDS:
and you can then
sorted on.
specify which fields you wish the
input records to be
Getting Acquainted with eMS
If you have just logged on for the first time, and you want to try a few
eMS commands, enter:
query disk a
The response should tell you that
191; it also provides information
disk and how much of it is used.
that indicates the disk may not
Disks."
you have an A-disk at virtual address
such as how much room there is on the
Again, if you receive an error message
be formatted, see "Formatting Virtual
Your A-disk is the disk you use most often in eftS, to contain your
eMS files.
Files are collections of data, and may have many purposes.
For this exercise, the data is meaningless. Enter:
edit junk file
You should receive the response:
NEW FILE:
EDIT:
which indicates
Enter:
that this file does
not already exist on
your A-disk.
input
You should receive the response:
INPUT:
and you can start to create the file, that is, write input records that
are eventually going to be written onto your A-disk. Enter 5 or 6 data
lines, such as:
hickory dickory dock
the mouse ran up the clock
the clock struck one
and down he run
dickory hickory dock
Now,
enter a
message:
null line
(one with
EDIT:
Enter:
file
You should see the message:
R; T=O.01/0.02 19:31:29
10
IBM VM/370 eMS User's Guide
no
data). You
should receive
the
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
You have just written a CMS file onto your A-disk. If you enter:
type junk file a
you should see the following:
HICKORY DICKORY DOCK
THE MOUSE RAN UP THE CLOCK
THE CLOCK STRUCK ONE
AND DOWN HE RUN
DICKORY HICKORY DOCK
The CMS command, TYPE,
on your A-disk.
requested a display of the disk
file JUNK FILE,
To erase the file, enter:
erase junk file
NOW, if you re-enter the TYPE command, you should receive the message:
FILE NOT FOUND
Most CMS commands create or reference disk files, and are as easy to
use as the commands shown above. Your CMS disks are among the most
important features in your VM/370 virtual machine.
Virtual Disks and How They Are Defined
Under VM/370, a real direct access storage device
(DASD) unit
(disk
pack) or an FB-512 device can be divided into many small areas, called
minidisks. Minidisks
(also called virtual disks because they are not
equivalent to an entire real disk)
are defined in the VM/370 directory,
as extents on real disks. For CMS applications, you never have to be
concerned with the extents on your minidisks; when you use C~S-formatted
minidisks, they are, for practical purposes, functionally the same as
real disks.
Minidisks can also be formatted for use with OS or DOS data
sets or VSAM files.
You can have both permanent and temporary disks attached to your
machine during a terminal session. Permanent disks are defined in the
VM/370 directory entry for your virtual machine. TemForary disks are
those you define for your own virtual machine using the CP DEFINE
command, or those attached to your virtual machine by the system
operator.
PERMANENT VIRTUAL DISKS
The VM/370 directory entry for your userid defines your permanent
virtual disks.
Each disk has associated with it an access mode
specifying whether you can read and write on the disk or only read from
it
(its read/write status).
Virtual disk entries in the VM/370
directory may look like the following:
MDISK
MDISK
MDISK
MDISK
MDISK
MDISK
190
191
194
195
198
19E
2314
3330
3330
FB-512
3330
3330
000
010
010
1000
050
010
050
005
020
500
010
050
CMS190
BDISKE
CMS001
FBDISK
CMS192
CMS19E
R
W
W
W
W
R
Section 1. What it Means to Have a CMS Virtual Machine
11
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp_ SD23-9024-1 for 5748-IX8
The first two fields describe the device, minidisk in this example,
and the virtual address of the devic~.
Virtual addresses (shown above
as 190, 191, and so on), are the names by which you and VM/370 identify
the disk. Each device in your virtual machine has an address which may
or may not correspond to the actual location of the device on the VM/370
system.
The third field specifies the device type of your virtual disk. For
count-key-data devices, the fourth and fifth fields specify the starting
real cylinder at which your virtual disk logically begins and the number
of cylinders allocated to your virtual disk, respectively. For FB-512
devices, the fourth field specifies the starting real block numbers
where your virtual disk begins, and the fifth field is the number of
blocks allocated to your virtual disk. The sixth field is the label ef
the real disk on which the virtual disk is defined and the seventh field
is a letter specifying the read/write mode of the disk; "R" indicates
that the disk is a read-only disk, and "W" indicates that you have
read/write privileges.
The MDISK control statement of the Directory
Service Program is described in the !~LJIQ QE~~!Q£~§ §y!g~.
DEFINING TEMPORARY VIRTUAL DISKS
Using the CP DEFINE
virtual machine for
command allocates a
assigns it a virtual
command, you can attach a temporary disk to your
the duration of a terminal session. The following
10-cylinder temporary disk from a 3330 device and
address of 291:
cp define t3330 as 291 cyl 10
When you define a minidisk, you can choose any valid address that is not
already assigned to a device in your virtual machine. Valid addresses
for minidisks range from 001 through 5FF, for a virtual machine in basic
control mode.
FORMATTING VIRTUAL DISKS
Before you can use any new virtual disk, you must format it.
This
applies to new disks that have been assigned to you and to temporary
disks that you have allocated with the CP DEFINE command.
When yeu
issue the FORMAT command you must use the virtual address you have
defined for the disk and assign a CMS mode letter, for example:
format 291 c
eMS then prompts you with the following message:
DMSFOR603R FORMAT WILL ERASE ALL FILES
WISH TO CONTINUE? (YESINO):
ON DISK 'C(291)'.
DO YOU
You respond:
yes
CMS then asks you to assign a label for the disk, which may be anything
you choose. Labels can have a maximum of 6 characters. When the
message:
DMSFOR605R ENTER DISK LABEL:
12
IBM VM/370 CMS User's Guide
?g. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-118
is issued, you respond by supplying a disk label. For
is a temporary disk, you might enter:
example, if this
scrtch
Section 1. What it Means to Have a eftS Virtual ftachine
12.1
March 30, 1979
12.2
IBM VM/370 eMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-118
CMS then erases all the files on that disk, if any existed, and formats
the disk for your use.
When you enter the label, CMS responds by
telling you:
FORMATTING DISK 'C'
'10' CYLINDERS FORMATTED ON 'C(291)'.
R; T=0.15/1.60
11:26:03
The FORMAT command should only be used to format CMS disks, that is,
disks you are going to use to contain CMS files. If you want to format
count-key-data disks for OS, DOS, or VSAM applications, the disks should
be formatted using the IBCDASDI program.
The FORMAT command allows a choice of physical disk block size as an
option. See the !~LJ12 ~~~ £om!g~~ gn~ ~g££Q ~~!~£~n£~ for details. To
format FB-512 disks for as, DOS, or VSAM applications, the disks can be
formatted using the INTDK stand-alone utility program.
See !~LJIQ
Q~~g!Q£~ ~y!g~ for details.
Sharing Virtual Disks: Linking
Since only one user can own a virtual disk, and there are many occasions
that require users to share data or programs, VM/370 allows you to share
virtual disks, on either a permanent or temporary basis, by "linking."
Permanent links can be established for you in your V8/370 directory
entry.
These
disks are then a
part of your
virtual machine
configuration every time you log on.
You can also have another user's disk temporarily added to your
configuration by using the CP LINK command.
For eXample, if you have a
program that uses data that resides on a disk identified in userid
DATA's configuration as a 194, and you know that the password assigned
to this disk is GO, you could issue the command:
cp link to data 194 as 198 r pass= gol
DATA's 194 disk is then added to your virtual
virtual address 198.
machine configuration at
The "R" in the command line indicates the access mode; in this case,
it tells CP that you wish only to read files from this disk. VM/370
will not allow you to write on it.
If you try to issue this command
when someone is logged on to the userid DATA, you will not be able to
establish the link. If you want to link to DATA in any event, you can
reissue the LINK command using the access mode RR:
cp link data 194 198 rr gol
The keywords TO, AS, and PASS= are
theIR.
optional; you do not have to specify
You can also use the CP LINK command to link to your own disks. For
example, if you log on and discover that another user has access to one
of your disks,
you may be given read-only access, even if it is a
read/write disk.
you can request the other user to detach your disk
1Note that the password cannot be entered on the command line
password suppression facility was specified at sysgen.
if the
Section 1. What it Means to Have a CMS Virtual Machine
13
Pg. of GC20-1819-2 Rev M,arcb 30, 1979 by Supp. SD23-9024-1 for 5748-11,8
from his virtual
the link:
cp link
*
machine, and after he
has. done so, you
can establish
191 191
When you link to your own disks, you can specify the userid as
do not need to specify the access mode or a password.
*
and you
You can find more information about the CP LINK command and CP access
modes in !~LJIQ ~f £2mmgDQ R~!~f~D£~ f2£ ~~D~£~! ~§~£§.
Identifying Your Disk to eMS: Accessing
LINK and DEFINE are CP commands: they tell CP to add DASD devices to
your virtual machine configuration. CMS must also know about these
disks,
and you must use the ACCESS command to estatlish a filemode
letter for them:
access 194 b
CMS uses filemode letters to manage your files during a
session. By using the ACCESS command you can control:
•
Whether you can write on a disk
status)
•
The library search
machine
•
Which disks are to contain the new files that you create
If you want to
the command:
order
terminal
or only read from it (its read/write
for programs
executing
know which disks you currently have
in your
virtual
access to, issue
query search
You might see the following display:
PER191
DAT194
CMS190
CMS19E
191
198
190
19E
A
B
S
Y
R/W
R/O
R/O
R/O
The first column indicates the label on the disk (assigned when the disk
is formatted), and the second column shows the virtual address assigned
to it.
The third column contains thefilemode
alphabet are valid file mode letters.
letter.
All letters
of the
The fourth column indicates the read/write status of the disk. The
190 and 19E disks in this example are read-only disks that contain the
CMS nucleus and disk-resident commands for the CMS system.
You will
probably use your 191 (A) disk as your primary read/write work disk.
14
IBM VM/370 eMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
RELEASING VIRTUAL DISKS
When you no longer need a disk during a terminal session, or if you want
to assign a currently active filemode letter to another disk, use the
CMS command RELEASE:
release c
Then, you can issue
to another disk.
the ACCESS command to assign the
filemode letter C
Section 1. What it Means to Have a CMS virtual Machine
14.1
March 30, 1919
14.2
IBM VM/310 eMS User's Guide
When you no longer need disks in your virtual .achine configuration,
use the CP command DETACH to disconnect them from your virtual machine:
cp detach 194
cp detach 291
If you are going to release and detach the disk at the same time, you
can use the DET option of the RELEASE command:
release 194 (det
For more information on controlling disks in CMS, see "section 4. The
CMS File System."
)
Section 1. What it Means to Have a CMS Virtual Machine
15
(
16
IBM VM/370 eMS User's Guide
Section 2. VM/370 Environments and Mode
Switching
When you are using VM/370, your virtual machine can be in one of two
possible "environments": the CP, or control program environment, or the
virtual machine environment, which may be CMS. The CMS environment has
several subenvironments, sometimes called "modes." Each environment or
subenvironment accepts particular commands or subcommands, and each
environment has its own entry and exit paths, responses and error
messages.
If you have a good
understanding of how the VM/370
environments are related, you can learn to change environments quickly
and use your virtual machine efficiently.
This section introduces the CP and
describes:
•
•
CMS environments that you use and
Entry and exit paths
Command subsets that are valid as input
Figure 1, at the end of this section, summarizes the VM/370 command
environments and lists the commands and terminal paths that allow you to
go from one environment to another.
with the exception of input mode in the edit environment, you can
always determine which environment your virtual machine is in by
pressing the Return or Enter key on a null line. The responses you
receive and the environments they indicate, are:
].§§EQ1!§.§
CP
CMS
CMS (DOS ON)
EDIT:
CMS SUBSET
DEBUG
~1!'!!!:Q1!!~1!j:
CP
CMS
CMS/DOS
Edit
CMS Subset
Debug
The CP Environment
When you log on to VM/370, your virtual machine is in the CP
environment. In this environment, you can enter any CP command that is
valid for your privilege class. This publication assumes that you are a
general, or class G, user. You can find information about the commands
that you can use in the Y~L1IQ ~g ~2~~~1!g ~~!~~gy£~ !Q~ 2~1!~~~! Q§.§E§·
Only CP commands are valid terminal input in the CP environment. You
can, however,
preface a CP command line with the characters "CPU or
"tcP", followed by one or more blanks, although it is not necessary.
These functions are described under "The CMS Environment."
you can enter CP commands from other VM/370 environments. There may
be times during your terminal session when you want to enter the CP
environment to issue one or more CP commands. You can do this from any
other environment by doing either of two things:
1.
Issue the command:
#cp
)
Section 2. VM/370 Environments and Mode switching
17
2.
Use your terminal's Attention key (or equivalent).
On a 2141
terminal, you must normally press the Attention key twice, quickly,
to enter the CP environment.
The following message
environment:
indicates that your virtual machine is
in the CP
CP
After entering whatever CP commands you need to use, you return your
virtual machine to the environment or mode that it came from by using
the CP command:
cp begin
which, literally, begins execution of your virtual machine.
The eMS Environment
You enter the CMS environment from CP by issuing the IPL command, which
loads CMS into your virtual storage area.
If you are planning to use
CMS for your entire terminal session, you should not have to IPt again
unless a program failure forces you into the'CP environment.
When you issue the IPt command, you can specify either the named
system CMS at your installation or you can load CMS by specifying the
virtual address of the disk on which the CMS system resides.
For
example:
cp ipl ems
-- or -/
\
cp ipl 190
''II
When your virtual machine is in the CMS environment, you can issue
any CMS command and any of the CP commands that are valid for your user
privilege class. You can also execute many of your own as or DOS
programs; the ways you can execute programs are discussed in "Section 8.
Developing as Programs Under CMS" and "Section 9. Developing DOS
Programs Under CMS."
You can enter CP commands from CMS in any of the following ways:
•
•
•
Using the implied CP function of CMS (See
With the CP command
With the ICP function
!21~.)
!21~:
For the m'ost part, you may enter any CP command directly from
the CMS environment. This implied CP function is controlled by an
operand of the CMS SET command, IMPCP. You can determine whether the
implied CP function is in effect for your virtual machine by entering
the command:
query impcp
If the response is:
IMPCP
= OPF
you can change it by entering:
set impcp on
18
IBM VM/310 CMS User's Guide
(
)
When the implied CP function is set off, you must use either the
CP command or the ICP function to enter CP commands from the CMS
environment. CP commands that you execute in EXEC procedures must
always be prefaced by the CP command, regardless of the implied CP
setting. An example of using the CP command is:
cp close punch
When you issue CP commands from the CMS environment either
implicitly or with the CP command, you receive, in addition to the CP
response
(if any), the CMS ready message.
If you use the tcp
function, discussed next, you do not receive the ready message.
You can preface any CP command line with the characters "#CP",
followed by one or more blanks. When you enter a CP command this
way, the command is processed by CP immediately; it is as if your
virtual machine were actually in the CP environment.
EDIT, INPUT, AND CMS SUBSET
The CMS editor is a VM/370 facility that allows you to create and
modify data files that reside on CMS disks. The editor environment,
more commonly called the edit environment, is entered when you issue
the CMS command EDIT, specifying the identification of a data file
you want to create or modify.
edit myfile assemble
)
is an example of how you would enter the edit environment to either
create a file called MY FILE ASSEMBLE or to make changes to a disk
file that already exists under that name.
When you enter the edit environment your virtual machine is
automatically in edit mode, where you can only issue EDIT subcommands
or CP commands prefaced by "tcP." EDIT subcommands tell the editor
what you wish to do with the data you have accessed. After you enter
the EDIT subcommand:
input
data lines that you enter are considered input to
return to edit mode, you must enter a null line.
the file.
To
If you issue the EDIT subcommand:
cms
the editor responds:
CMS SUBSET
and your virtual machine is in CMS subset mode, where you can issue
any valid CMS subset command, that is, a CMS command that is allow~1
in CMS subset mode. These include:
)
ACCESS
CP
DISK
ERASE
EXEC
HT
LISTFILE
PRINT
PUNCH
QUERY
READCARD
RT
SET
STATE
STATEW
TYPE
Section 2. VM/370 Environments and Mode Switching
19
You can also issue CP commands. To return to edit mode, you use
the special CMS subset command, RETURN. If you enter the Immediate
command HX, your editing session is terminated abnormally and your
virtual machine is returned to the CMS environment.
When you are finished with an edit session, you retrirn to the CMS
environment by issuing the FILE subcommand. which indicates that all
modifications or data insertions that you have m.de should be written
onto a CMS disk, or by issuing the subcommand QUIT, which tells the
editor not to save any modifications or insertions made since the
last time the file was written.
More detailed information about EDIT subcommands and how to use
the CMS editor is contained in this publication in "Section 5. The
CMS Editor" and in the !~LJ.IQ £!12 £Q!!~!!g ~!!g 1!~££2 !!~f~!:~!!£~.
DEBUG
CMS DEBUG is a special CMS facility that provides subcommandsto help
you debug programs at your terminal. Your virtual machine enters the
debug environment when you issue the CMS command:
debug
You may want to enter this command after you have loaded a program
into storage and before you begin executing it. At this time you can
set "breakpoints," or address stops, where you wish to halt your
program's execution so that you can examirieand change the contents
of general registers and storage areas. When these breakpoints are
encountered, your vir.tual machine is placed in the debug environment.
You can also enter the debug environment by issuing the CP EXTERNAL
command, which causes an external interrupt to your virtual machine.
Valid DEBUG
are:
subcommands that
BREAK
CAW
CSW
DEFINE
DUMP
you can
GO
GPR
HX
ORIGIN
PSW
You can also use
CP commands.
enter in. this environment
RETURN
SET
STORE
X
the ICP function in the debug
environment to enter
you leave the debug environment in any of the following ways:
completes
exe~ution,
•
If the program you are running
to the CMS environment.
you are returned
•
If your virtual machine entered the debug environment after a
breakpoint was encountered, it" returns to CMS when you issue the
DEBUG subcommand:
hx
To continue
subcommand:
the
execution
of your
program,
you
use
~he
DEBUG
go
(
20
IBM VM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1919 by Supp. SD23-9024-1 for 5148-X18
•
If your virtual machine is in the debug
executing a program, the DEBUG subcommand:
environment
and is
not
return
returns it to the CMS environment.
CMS/DOS
If you are a DOS/VSE user, the CMS/DOS environment provides you with all
the CMS interactive functions and facilities, as well as special CMS/DOS
commands which simulate DOS functions.
The CMS/DOS environment becomes
active when you issue the command:
set dos on
When your virtual machine is in the CMS/DOS environment you can issue
any command line that would be valid in the CMS environment, including
the facilities of EDIT, DEBUG, and EXEC, but excluding CMS commands or
program modules that load and/or execute programs that use OS macros or
functions.
The following commands are provided in CMS/DOS to test
DOS programs, and to provide access to DOS/VS libraries:
ASSGN
DLBL
DOSLIB
DOSLKED
DOSPLI
DSERV
ESERV
FETCH
FCOBOL
LISTIO
Your virtual machine
command:
and develop
OPTION
PSERV
RSERV
SSERV
leaves the CMS/DOS environment when
you issue the
set dos off
If you reload CMS
(with an IPL command) during a
must also reissue the SET DOS ON command.
terminal session, you
Interrupting Program Execution
When you are executing a program under CMS or executing a CMS command,
your virtual machine is not available for you to enter commands. There
are, however,
ways in which you can interrupt a program and halt its
execution, either temporarily, in which case you can resume its
execution, or permanently, in which case your virtual machine returns to
the eMS environment. In both cases, you interrupt execution by creating
an "attention interruption," which may take two forms:
•
•
An attention interruption to your virtual machine operating system
An attention interruption to the control program
These situaticns result in what are known as virtual machine
(VM) or
control program
(CP) "reads" being presented tc your virtual console.
On a typewriter terminal, the keyboard unlocks when a read occurs.
section 2. VM/310 Environments and Mode Switching
21
March 30, 1979
Whether you have to press the Attention key once or twice depends on
the terminal mode setting in effect for your virtual machine.
This
setting is controlled by the CP TERMINAL command:
cp terminal mode vm
The setting VM is the default for virtual machines; you do not need to
specify it. The VM setting indicates that one depression of the
Attention key sends an interruption to your virtual machine, and that
two depressions results in an interruption to the control program (CP).
The £P setting for terminal mode, which is the default for the system
operator, indicates that one depression of the Attention key results in
an interruption to the control program (CP)~ If you are using your
virtual machine to run an operating system other than CMS, you might
wish to use this setting. Issue the command:
cp terminal mode cp
VIRTUAL MACHINE INTERRUPTIONS
While a command or program is executing, if you press the Attention key
once on a 2741 (or the Enter key on a 3270), you have created a virtual
machine interruption. The program halts execution, your terminal will
accept an input line, and y~u may:
•
Terminate the execution of
command to halt execution:
the
program
by issuing
an
Immediate
hx
The HX command causes the program to abnormally terminate (abend).
•
Enter a eMS command. The command is stacked in a console buffer and
is processed by CMS when your program is finished executing and the
next virtual machine read occurs. For example:
print abc listing
After you enter this line, the program resumes execution.
•
If the program is directing output to your terminal and you wish only
to halt the terminal display, use the Immediate command:
ht
The program resumes
execution.
Terminal output can
also be
suppressed immediately when you enter a command by placing tHT at the
end of the command line. The logical line end character (I) allows
the Immediate command HT to be accepted; program execution proceeds
without typing.
You can,
if you want, cause another interruption and request that
typing be resumed by entering the RT (resume typing) command:
rt
•
22
Enter a null line; your program continues execution. The null line is
stacked in the console stack and read by CMS as a stacked command
line.
IBM VM/370 eMS User's Guide
HX, HT, and RT are three of the CMS Immediate commands. They are
"immediate" because they are executed as soon as they are entered.
Unlike other commands, they are not stacked in the console buffer. You
can only enter an Immediate command following an attention interruption.
CONTROL PROGRAM INTERRUPTIONS
You can interrupt a program and enter the CP environment directly by
pressing the Attention key twice quickly, on a 2741, or pressing the PAl
key on a 3270.
Then, you can enter any CP command. To resume the
program's execution, issue the CP command:
cp begin
If your terminal is operating with the terminal mode set to CP, pressing
the Attention key
once places your virtual machine
in the CP
environment.
ADDRESS STOPS AND BREAKPOINTS
A program may also be interrupted by an instruction address stop, which
For example, if you
you specifically set by the CP command ADSTOP.
issue the command:
cp adstop 201ea
an address stop is set at virtual storage location X'201EA'. When your
program reaches this address during its execution, it is interrupted and
your virtual machine is placed in the CP environment, where you can
issue any CP command, including another ADSTOP command, before resumitig
your program's execution with the CP command BEGIN.
Breakpoints, similar to address stops, are set using the DEBUG
subcommand BREAK, which you issue in the debug environment before
executing a program. For example, if you issue:
break 1 201ae
Your program's execution is interrupted at this address and your virtual
machine is placed in the debug environment. You can then enter any
DEBUG subcommand. To resume program execution, use the DEBUG subcommand
GO. If you want to halt execution of the program entirely, use the
DEBUG subcommand HX, which returns your virtual machine to the C~S
environment. You can find more information about setting address stops
and breakpoints in "section 11. How VM/370 Can Help You Debug Your
Programs."
)
Section 2. VM/370 Environments and Mode Switching
23
Any "Class Any"
CP Command
EDIT Environment
INPUT MODE
Any CMS Command
Any CMS/DOS Command
Any CP Command
Execute any DOS Program
#CP Command Line
Any Input Line
Carrier retu rn on a
null line
#CP Command Line
DEBUG EnvironmE!nt
CMS Subset
Any CMS Subset Command
Any CP Command
~------~RETURN
'"-------------1 HX
#CP Command Line
Notes:
1 The
CP environment may be entered from any other environment either by using
your terminal's Attention key or equivalent, or by entering the command #CP.
Any CPcommand is any CP command that is valid for your user privilege class.
Any time that a CP command can be entered, it may be prefaced with #CP.
3The BEGIN command returns your virtual machine to the environment it was in
when CP was entered:
2
°If you were in edit or input mode, the current line pointer remains unchanged.
°If you were executing a program, execution resumes at the instruction address
indicated in the PSW.
Figure 1. VM/310 Environments and Mode switching
24
IBM VM/310 eMS User's Guide
(
\
Section 3. What You Can Do with
VM/370-CMS Commands
This section provides an overview of the CMS and CP command languages,
and describes the various commands within functional areas, with
examples. The commands are not presented in their entirety, nor is a
complete selection of commands represented.
When you finish reading this section you should have an understanding
of the kinds of commands available to you, so that when you need to
perform a particular task using CMS you may have an idea of whether it
can be done,
and know what command to reference for details.
For
complete lists of the CP and CMS commands available, see "Appendix A:
Summary of CMS Commands" and "Appendix B: Summary of CP Commands."
Command Defaults
Many of the characteristics of your CMS virtual machine are already
established when you log on, but there are commands available so you can
change them. In the case of many CMS commands, there are implied values
for operands, so that when you enter a command line without certain
operands, values are assumed for them.
In both of these instances, the
values set or jmpliedare considered default values. As you learn CP
and CMS commands, you also should become familiar with the default
values or settings for each.
Commands to Control Terminal Communications
Using VM/370, you control your virtual machine directly from your
of
commands
for
terminal
terminal.
VM/370
provides
a set
cOllmunications.
ESTABLISHING AND TERMINATING COMMUNICATIONS WITH VM/370
To initiate your communication with VM/370, use the CP LOGON command:
cp logon sam
optionally, you may enter your password on the same line 1 :
cp logon sam 123456
When you are sure that your communication line is all right and you have
difficulty logging on (for example, someone else has logged on under
your userid), you can use the CP MESSAGE command:
cp message sam
)
this is sam ••• pls log off
1Note that the password cannot be entered on the command line
password suppression facility was specified at sysgen.
if the
Section 3. What You Can Do With VM/370-CMS Commands
25
Another way
DIAL:
to access
the VM/370 system
is to
use the
CP command
cp dial tsosys
In this example, TSOSYS is the userid of a virtual machine running a TSO
system.
After this DIAL command is successful, you can use your
terminal as if you were actually connected to a TSO system, and you can
begin TSO logon procedures.
To end your terminal session, use the CP command LOGOFF:
cp logoff
If you have used a
VM/370 computer and
enter:
switched (or dial-up) communication path to
you want the line to remain available, you
the
can
cp logoff hold
At times, you might be running a long program under one userid and wish
to use your terminal for some other work. Then, you can disconnect your
terminal:
cp disconn
-- or -cp disconn hold
Your virtual machine continues to run, and is logged off the system when
your program has finished executing. If you want to regain terminal
control of your virtual machine after disconnecting, log on as you would
to initiate your terminal session. Your virtual machine is placed in
the CP environment, and to resume its execution, you use the CP command
BEGIN.
You should not disconnect your virtual machine if a program requires
an operator response, since the
console read request cannot be
satisfied.
CONTROLLING TERMINAL OUTPUT
During the course of a terminal session, you can receive many kinds of
messages from VM/370, from the system operator, from other users, or
from your own programs. You can decide whether or not you want these
messages to actually reach you. For example, if you use the command:
cp set msg off
no one will be able to send messages to you with the CP MESSAGE command;
if another virtual machine user tries to send you a message, he receives
the message:
userid NOT RECEIVING, MSG OFF
If your virtual machine handles special messages and you do not want to
receive special messages at this time, you can issue:
cp set smsg off
26
IBM VM/370 CMS User's Guide
March 30, 1979
No one will be able to send special messages to you with the CP SMSG
command; if another virtual machine user attempts to do so, he receives
a message:
userid NOT RECEIVING, SMSG OFF
Similarly, you can use:
cp set wng off
to prevent warning messages
(which usually come from the system
operator) from coming to you. You would probably do this, however, only
in cases where you were typing some output at your terminal and did not
want the copy ruined.
VM/370 issues error messages whenever you issue a command incorrectly
or if a command or program fails.
These messages have a long form,
consisting of the error message code and number, followed by text
describing the error.
If you wish to receive only the text portion of
messages with severity codes I, E, and W (for informational, error, and
warning, respectively), you can issue the command:
cp set emsg text
If you want to receive only the message code and number (from which you
can locate an explanation of the error in !~Ll1~ ~y§!~~ !~§§gg~§), you
specify:
cp set emsg code
You can also cancel error messages completely:
cp set emsg off
To restore the EMSG
enter:
setting to its default, which is
the message text,
cp set emsg text
Some CP commands issue informational messages telling you that CP has
performed a particular function. You can prevent the reception of these
messages with the command:
cp set imsg off
or restore the default by issuing:
cp set imsg on
The setting of EMSG applies to eMS commands as well as to CP commands.
You can
enter:
also control
the format of
the CMS
ready message.
If you
set rdymsg smsg
you receive only the
"R;" or shortened form of the ready message after
the completion of CMS commands.
If you are not receiving error messages
(as described above)
and an error occurs, the return code from the
command still appears in parentheses following the "R".
Section 3. What You Can Do With VM/370-CMS Commands
27
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-118
An additional feature exists for CMS.
If you
terminal with a two-color ribbon, you can s~ecify:
have a
typewriter
set redtype on
so that CMS error messages are typed in red.
Some commands or messages result in displays of lines that are very
long.
If you want to limit the width of lines that are received at your
terminal (for example, if you are using terminal paper that is only
eight inches wide), you can specify:
cp terminal linesize 80
so that all lines received at your
an 80-character display.
terminal are formatted to fit within
You can also control two special characters in VM/370. One is the
exclamation point (!) t~at types when the Attention key is pressed. If
you do not want this character to type when you press the Attention key,
use the command:
cp terminal attn off
CMS allows you to specify a "blip" character: this character is typed
or displayed whenever two seconds of processor time are used by your
virtual machine. If you enter:
set blip
*
then,
during program
seconds of CPU time.
execution, this character types
can cancel the function:
for every
two
Y~u
set blip off
or set it to nonprintable characters:
set blip on
When this command has been entered on a typewriter terminal, the
Selectric type ball tilts and rotates whenever a blip character is
received.
Note: Issuance of the
of~blips.
STIMER macro for more than two
seconds will mask
On a display terminal, you can control the intensity of the redisplay
of user input. If you enter:
cp terminal hilight on
the redisplay of user input is highlighted.
If you enter:
cp terminal hilight off
the redisplay of
default.
28
user
input
IBMVM/370 CMS User's Guide
is at
normal
intensity.
This is
the
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-118
COMMANDS TO CONTROL HOW VM/370 PROCESSES INPUT LINES
You can manipulate VM/370's logical line editing function to suit your
own needs. In addition to using the CP TERMINAL command to change the
default logical line editing symbols, you can issue:
cp set linedit off
Section 3. What You Can Do With
VM/370~CMS
Co •• ands
28.1
March 30,
28,.2
IBM VM/310 eftS US,er's Guide
1919
so that none of the symbols are
your input lines~
recognized by VM/370 when it interprets
When you are in the CMS environment, there are a number of commands
that you can use to control how CMS validates a command line. The SET
command functions IMPCP (implied CP)
and IMPEX (implied EXEC) control
the recognition of CP commands and CMS EXEC procedures. For example, if
you issue:
set impcp off • set impex off
then, when you enter CP commands in CMS or try
procedures, you must preface the name of the command
CP (or tcP), or EXEC, respectively.
to execute EXEC
or procedure with
By using the SYNONYM and the SET ABBREV commands, you can control
what command names, synonyms, or truncations are valid in CMS.
For
example, you could set up a file named MYSYN SYNONYM which contains the
following records:
PRINT
RELEASE
ACCESS
DOSLKED
PRT
LET GOOF
GET
LNKEDT
1
5
1
3
The first column specifies an existing CMS command, module, or EXEC
name; the second column specifies the alternate name, or synonym, you
want to use;
and the. third column is a count field that indicates the
minimum number of characters of the synonym that can be used to truncate
the name. Using this file, after you enter the command:
synonym mysyn
)
you can use PRT, LETGOOF, GET, and LNKEDT in place of the corresponding
CMS command names.
Also, if the AEBREV function is in effect,
(it is
the default; you can make sure it is in effect by issuing the command
SET ABBREV ON), you can truncate any of your synonyms to the minimum
number of characters specified in the count field of the record (that
is, you could enter "pH for PRINT, "letgo" for RELEASE, and so on) •
You can set up EXEC files with the same names as CMS commands, that
mayor may not perform the same function as the CMS names they
duplicate. For example, if every time you used the GLOBAL command you
used the same operands, you could have an EXEC file, named GLOBAL, that
contained a single record:
global maclib cmslib os macro
Then, every time you entered the command name:
global
the command GLOBAL MACLIB CMSLIB OSMACRO would execute.
As another example, suppose you had
contained the following records:
an EXEC
file named
'T', that
&CONTROL OFF
CP QUERY TIME
Then, whenever you entered:
)
t
Section 3. What You Can Do with VM/370-CMS Commands
29
you would receive the CP time-of-day message, and you could no longer
use the truncation "T" for the CMS command TYPE. In order to see the
contents of a CMS file displayed at your terminal you would have to
enter at least "TY" as a truncation.
CONTROLLING KEYBOARD-DEPENDENT COMMUNICATIONS
You are dependent on your terminal for communication with VM/370: when
your virtual machine is waiting for a read either from the control
program or from your virtual machine operating system, you can not
receive messages until you press the Return key to enter a command or a
null line. If you are in a situation where you must wait for a message
before continuing your work, for example, if you are waiting for a tape
device to be attached to your virtual machine, you can use the CP
command SLEEP to lock your keyboard:
cp sleep
You must then press the Attention key to get out of sleep and unlock the
keyboard so you can enter a command.
If your virtual machine is in the CP environment when you issue the
SLEEP command, or if you issue the SLEEP command from the CMS
environment using the tcp function, your virtual machine is in the CP
environment after you press the Attention key. If your virtual machine
is in the CMS environment when you enter the SLEEP command
(or if you
enter CP SLEEP), your virtual machine is in the CMS environment when you
press the Attention key once.
You can control the effect of pressing the Attention key
terminal with the CP TERMINAL command. If you specify:
on your
cp terminal mode cp
then, whenever
environment.
you
press
the
Attention
key,
you
are
in
the
CP
If you use the default terminal mode setting, which is VM, and then
you press the Attention key once, you cause a read to your virtual
machine; if you press the Attention key twice you cause a CP read, and
you are in the CP environment.
The effect of pressing the Attention key is also important when you
are executing a program. At times, you may wish to enter some CP
commands while your program executes, but you do-not want to interrupt
the execution of the program.
If, before you begin your program you
issue the command:
cp set run on
and then use the Attention key to get to the CP environment While your
program executes, the program continues executing While you communicate
with CP. The default setting for the RUN operand of the SET command is
off; usually, when you press the Attention key (twice)
during program
execution, your program is interrupted.
SPECIAL CHARACTER SETS: If you are using a Frogramming language or
enterIng data-that requires you to use characters that are not on your
keyboard, you can select some characters that you do not use very often
and establish a translate table with the SET command.
For example, if
your terminal does not have the special characters [and ] (which have
30
IBM VM/370 CMS User's Guide
(
the hexadecimal
commands:
values AD
and BD, respectively),
you could
issue the
set input %ad
set input $ bd
Then, when you are entering data lines at your terminal, whenever you
enter the characters "%" or "$", they are translated and written into
your file as fI(fI and "]". When you display these lines, the character
positions occupied by the special characters appear to be blanks,
because they are not available on your keyboard.
If you want these
special characters to appear on your terminal in symbolic form, you
should issue the commands:
set output ad %
set output bd $
so that when you are displaying lines that contain these characters,
they will appear translated as % and $ on your terminal. If you are
going to use the input and output functions together, you must set the
output character first; if you set the input character first, then you
are unable to set the output function.
If you are an APL user and have the special APL type font or the APL
3270 feature and keyboard, you can tell VM/370 to use APL translation
tables with the command:
cp terminal apl on
)
Commands to Create, Modify, and Move Data Files
and Programs
The CMS command language proviaes you with many different ways of
manipulating files.
A file, in eMS, is any collection of data; it is
most often a disk file, but it may also be contained on cards or tape,
or it may be a printed or punched output file.
COMMANDS THAT CREATE FILES
you create files in CMS by several methods; either specifically or by
default. The EDIT command invokes the CMS editor to allow you to create
a file directly at your terminal.
You must specify a file identifier
when you are creating a new file:
edit mother goose
In this example, the file has an identifier, or fileid, of MOTHER GOOSE.
The EDIT subcommand INPUT allows you to begin inserting lines of data or
source code into this file. When you issue the sUbcommands FILE or
SAVE, the lines that you have entered are written into a CMS disk file.
Files are created, and
following types of commands:
•
)
sometimes
named,
by
default,
Commands that invoke programming language processors
For example, if you issue the command:
with
the
or compilers.
assemble myfile
Section 3. What You Can Do With VM/370-CMS Commands
31
the assembler assembles source statements from an existing CftS file
named MYFILE ASSEMBLE and produces an output file containing object
code, as well as a listing. The files that are created are named:
MYFILE TEXT
MYFILE LISTING
•
Commands that load CMS files onto a disk from cards or tapes.
commands are READCARD, TAPE LOAD, and DISK LOAD.
These
•
The LISTFILE and LISTIO commands with the EXEC option create files
named CMS EXEC and $LISTIO EXEC which you can execute as EXEC
procedures.
•
The TAPPDS and TAPEMAC commands create CMS disk files from OS data
sets on tape. If the data set is a partitioned data set, the TAPPDS
command creates individual CMS files from each of the members; the
TAPEMAC command creates a CMS macro library, called a ftACLIB, from an
OS macro library.
.
•
The MOVEFILE and FILEDEF commands, used together, can copy OS or DOS
data sets or files into CMS files;
they can also copy files from
cards or tapes.
•
CMS/DOS commands SSERV, ESERV, RSERV, and PSERV copy DOS files from
source statement,
relocatable, and procedure libraries into CftS
files.
•
Some CMS commands produce maps, or lists of files, data sets, or
program entry points. For example, if you issue the command:
tape scan (disk
a CMS disk file named TAPE MAP is created that contains a list of the
CMS files that exist on a tape attached to your virtual machine at
virtual address 181.
Some commands create new files from files that already exist on your
virtual disks. The creation may involve a simple copy operation, or it
may be a combining of many files of one type into a larger file of the
same or a different type:
•
The COPYFILE command, in its simplest
virtual disk to another:
form, copies a file
from one
copyfile yourprog assemble b myprog assemble a
•
The MACLIB and TXTLIB commands create
files, or from TEXT (object) files.
libraries from MACRO
or COpy
•
The SORT command rearranges (in alphameric sequence) the records in a
file and creates a new file to contain the result.
You have to
specify the name of the new file:
sort nonseq recs a seq recs a
•
The GENMOD command creates nonrelocatable modules from object modules
that you have loaded into your virtual storage area.
For example,
the commands:
load test
genmod payroll
create a file named PAYROLL MODULE, which you can then
user-written CMS command.
32
IBM VM/370 CMS User's Guide
execute as a
«
•
The DOSLKED command creates or adds members to DOSLIBs,
libraries containing link-edited CMS/DOS program phases.
which are
•
The UPDATE command creates an updated source file and special update
files when you use it to apply updates to your source programs.
COMMANDS THAT MODIFY DISK FILES
You can use the CMS editor to modify existing files on your virtual
disks. You issue the EDIT command, giving the file identifier:
edit old file
CMS editor subcommands allow you to make minor specific changes
global changes, which can affect many lines in a file at one time.
or
The MACLIB and TXTLIB commands also allow you to modify CMS macro and
text libraries. You can add, delete, or replace members in these
libraries using these commands.
The COPYFILE command has some options that allow you to change a file
without creating a new output file. For example, if you enter the
command:
copyfile my file a (lowcase
then all of the uppercase characters in
to lowercase.
You can change
command:
the
file
the file MY FILE are translated
identifier of
a
file
using the
RENAME
rename test file a1 good file a1
The ERASE command deletes files from your virtual disks:
erase temporary file b1
For additional examples of CMS file
Sample Terminal Sessions."
system commands, see
"Appendix D:
COMMANDS TO MOVE FILES
You can use CMS commands to transfer a data file from one device or
medium to another device of the same or of a different type. The types
of movement and the commands to use are described briefly here and in
detail in "Section 1. Using Real printers, Punches, Readers, and Tapes."
If you need to trarisfer files between virtual machines, you can use
the PUNCH or DISK DUMP commands to punch virtual card image records.
These are then placed in the virtual card reader of the receiving
virtual machine.
Before you use either of these commands, you must indicate the output
disposition of the files.
You do this with the CP SPOOL command:
)
cp spool OOd to mickey
Section 3. What You Can Do
~ith
VM/370-CMS Commands
33
Then, you can use the PUNCH command to punch virtual card images:
punch acct records
The file ACCT RECORDS is spooled to the userid MICKEY's virtual card
reader.
If the CMS file you are transferring does not have fixedlength, SO-character (card image) records, you can use the command:
disk dump acct records
The CMS TAPE command allows you to
restorQ previously dumped files:
dump CMS files onto
tape, or to
tape dump archive file
tape load archive file
. VM/370 also provides a special utility program, DASD Dump Restore,
that allows you to dump the entire contents of your virtual disk onto a
tape and then later restore it to a disk. You might use this program,
invoked by the DDR command in CMS, to back up your data files before
using them to test a new program.
COMMANDS TO PRINT AND PUNCH FILES
The commands that you use most often to print and punch
the commands PRINT and PUNCH. For example:
CMS files are
print myprog listing
prints the contents of the LISTING file on the system printer, and:
punch myprog assemble
punches the assembler language source statement file onto
can also punch members of MACLIBs and TXTLIBs:
cards.
You
punch cmslib maclib (member fscb
Some CMS commands have a PRINT option, so that instead of having some
kinds of output displayed at your terminal or placed in a disk file, you
can request to have it printed on the real system printer. For example,
if you want a list of the contents of a macro library to print, you
could issue the command:
maclib map mylib (print
You can see the contents of a
using the TYPE command:
file displayed
at your
terminal by
type week3 report
You can specify, on the TYPE command, that you
specific records in this file:
type week3 report a 1 20
34
IBM VM/370 CMS User's Guide
want to see
only some
March 30,1979
Commands to Deyelop and Test OS and CMS
Programs
Use CMS to prepare programs: you can create them with the CBS editor~ or
write them cnto your CMS disks using any of the methods discussed above.
You can also assemble or compile source programs directly from cards,
tapes, or as data sets. If your source program is in a CMS disk file,
then during the development process you can use the editor to make
corrections and updates.
To compile your programs, use the assembler or any of the language
processors available at your installation. If your program uses macros
that are contained in either system or private program libraries, you
must make these libraries known to CMS by using the GLOBAL command:
global maclib cmslib asmlib
In this example, you are using two libraries: the CftS macro library,
CMSLIB MACLIB, and a private library, named ASMLIB MACLIB.
The output from the compilers, in relocatable object fora, is stored
on a CMS disk as a file with the filetype of TEXT. To load TEXT files
into virtual storage to execute them, use the LOAD comBand:
load myprog
The LOAD command performs the linkage editor function in CMS~ If
MYPROG contains references to external routines, and these routines are
the names of CMS TEXT files, those TEXT files are automatically included
in the load. If you receive a message telling you that there is an
undefined name
(which might happen if you have a CSECT name or entry
point that is not the same as the name of the TEXT file that contains
it), you can then use the INCLUDE command to load this TEXT file:
include scanrtn
When you have loaded the object modules into storage,
program execution with the START command:
you can begin
start
If you want to begin execution at a specified entry point, enter:
start scan1
where SCAN1 is the name of a control section, entry point, or procedure.
If you are testing a program that either reads or writes files or
data sets using as macros, you must use the FILEDEF command to supply a
file definition to correspond to the ddname you specify in your program.
The command:
filedef indd reader
indicates that the input file is to be
reader. A disk file might be defined:
read from
your virtual
card
filedef outdd disk out file a1
The FILEDEF command in CMS
definition (DD) card in as.
performs
the
same
function as
The commands to load and execute as programs are
"Section 8. Developing as Programs Under CMS."
Section 3. What You Can Do With
VM/370-C~S
a
data
discussed
in
Commands
35
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
The RUN command,
which is actually an EXEC procedure, combines many
of these commands for you,
so that if you want to compile, load, and
execute a single source file, or load and execute a TEXT or MODULE file,
you can use the RUN command instead of issuing a series of commands. See
the discussion of the RUN command in Y~Ll1Q ~~~ £2mms~Q ~Q ~s£!~
~~!~!~n£~ for a list of the as language processors available.
Commands to Develop and Test DOS Programs
CMS simulates many functions of DOS/VSE in the CMS/DOS environment.
CMS/DOS is not a separate system, but is part of CMS. When you enter the
command:
set dos on
you are in the CMS/DOS environment.
If you want to use the libraries on
the DOS/VSE system residence volume, you should access the disk on which
it resides and specify the mode letter on the SET DOS ON command line:
access 132 c
set dos on c
Using commands that are available only in the CMS/DOS environment,
you can assign system and programmer logical units with the ASSGN
command:
assgn sys200 reader
If the device is a disk device, you
the DLBL command:
assgn sys100 b
dlbl infile b dsn myinput file
can set up a
data definition with
(sys100
You can find out the current logical unit assignments and active file
definitions with the LISTIO and QUERY DLBL commands, respectively:
listio a
query dlbl
If you are an asseBbler language
source file with the ASSEMBLE command:
programmer, you
can assemble
a
assemble myprog
A CMS file with a filetype of DOSLIB simulates a DOS cor~ image
library; you can link-edit TEXT files or relocatable modules from a Des
relocatable library and place the link-edited phase in a DOSLIB using
the DOSLKED command:
doslked myprog new lib
Then, use the GLOBAL command to identify the phase library and issue the
FETCH command to bring the phase into virtual storage:
global doslib newlib
fetch myprog
The START command begins program execution:
start
36
IBM VM/370 CMS User's Guide
During program development with CMS, you can use DOS/VS system or
private libraries. You can use files on these libraries or you can copy
them into CMS files. The DSERV command displays the directories of
DOS/VS libraries. The command:
dserv cd
produces a copy of the directory for the core image library. To copy
phases from relocatable libraries into CMS TEXT files, you could use the
RSERV command:
rserv oldprog
The SSERV and ESERV commands are available for you to copy files from
source statement libraries,
or copy and de-edit
macros from E
sublibraries. Also, the PSERV command copies procedures from the
procedure library.
The CMS/DOS commands are described
Developing DOS Programs Under CMS."
in
detail
in
"Section
9.
Commands Used in Debugging Programs
When you execute your programs under eMS, you can debug them as they
execute, by forcing execution to halt at specific instruction addresses.
You do this by entering the debug environment before you issue the START
command. You enter the debug environment with the DEBUG command:
debug
To specify that execution be stopped at a particular virtual address,
you can use the BREAK subcommand to set a breakpoint. For example:
break 1 20adO
Then, when this virtual address is encountered during the execution of
the program, the debug environment is entered and you can examine
registers or specific storage locations, or print a dump of your virtual
storage.
Subcommands that do these
things might look like the
following:
gpr 0 15
x 20c12 8
dump 20000
*
Instead of using the CMS DEBUG subcommands, you can use the CP ADSTOP
command to set address stops. For example:
cp adstop 20adO
Then, in the CP environment, you can
things. For example:
use CP commands
to do
the same
cp display g
cp display 20c12.8
cp dump 20000
)
Both sets of commands shown in these examples result in displays of (1)
the contents of your virtual machine's general purpose registers, (2) a
display of eight bytes of storage beginning at lccation X'20C12' and (3)
a dump of virtual storage from location X'20000' to the end.
Section 3. What You Can Do With VM/370-CMS Commands
37
You can also use the CMS SVCTRACE command and the CP TRACE commands
to see a record of interruption activity in your virtual machine.
The DEBUG subcommands and the CMS and CP debugging
described in more detail in "Section 11. How VM/370 Can
Your Programs."
facilities are
Help You Debug
Commands to Request Information
All of the CP and CMS commands discussed in this section have required
some action on your part: you set your terminal characteristics,
manipulate disk files, develop, compile, and test programs, and control
your virtual machine devices and spool files. During a terminal session
you can change the status of many of your devices and virtual machine
characteristics, modify the files on your disks and create spool files.
VM/370 provides many commands to help you find out what is and what is
not currently defined in your virtual machine.
COMMANDS TO REQUEST INFORMATION ABOUT TERMINAL CHARACTERISTICS
You can find out ~he status of your terminal characteristics by using
the CP command QUERY with the TERMINAL or SET operands. If you issue the
command:
cp query terminal
you can see the settings for all of the functions controlled by the CP
TERMINAL command, including the current line size and line editing
symbols.
Similarly, the command:
cp query set
tells you the settings for the functions controlled by the CP
command, such as error message display, and the MSG and WNG flags.
SET
For most of the functions controlled by the CMS SET command, there
are corresponding CMS QUERY command operands; to find out a particular
setting, you must specify the function in the QUERY command. For
example:
query input
lists the current settings in effect for input
Other functions that you can query this way are:
BLIP
IMPCP
IMPEX
38
INPUT
OUTPUT
RDYMSG
IBM VM/370 CMS User's Guide
REDTYPE
SYNONYM
character translation.
COMMANDS TO REQUEST INFORMATION ABOUT DATA FILES
Use the LISTFILE command to get information about CMS files.
information you can obtain from the LISTFILE command includes:
•
The
The names of all the files on your A-disk:
listfile
•
The names of all the files on any other accessed disk:
list file
•
**
b
The names of all files that have the same filename:
listfile myprog
•
The names of all files with the same filetype:
listfile
•
*
*
assemble
The record length and format, blocksize, creation date and disk label
for a particular file:
listfile records saved a2 (label
Use the STATE command to find out whether a certain file exists:
state sales list c
If you want to know if the file is on a read/write disk, you can use the
STATEW command.
To find out what CMS libraries have
the commands:
query
query
query
query
been made available, you can use
doslib
maclib
txt lib
library
To find out what members are contained
library use the commands:
in a particular macro or text
maclib map mylib (term
txt lib map proglib (term
The MODMAP command displays a load map of a ftODULE file:
modmap payroll
To examine load
command:
maps
created by
the LOAD
command,
use the
TYPE
type load map as
The TYPE command can also be used to display the contents of any CftS
file. To examine large files, you can use the PRINT command to spool a
copy to the high-speed printer.
)
To compare the contents of two files
use the COMPARE command:
to see if they
are identical,
compare labor stat a1 labor stat b1
Section 3. What You CanDo With VM/370-CMS Commands
39
Any records
terminal.
in these
files that
do not
match are
displayed at
your
If you have OS or DOS disks attached to your virtual machine, you can
display a list of OS data sets or DOS files by using the LISTDS command;
for example:
listds d
displays a list of the data sets or files on the OS or DOS disk accessed
as your D-disk.
COMMANDS TO REQUEST INFORMATION ABOUT YOUR VIRTUAL DISKS
Use the CP QUERY command to find out:
•
What virtual disks are currently part of your configuration:
cp query virtual dasd
•
Whether a particular virtual disk address is in use:
cp query virtual 291
•
What users might be linked to one of your disks:
cp query links 330
The CMS QUERY command can tell you about your accessed disks.
enter:
If you
query disk a
you can find out the number of files on your A-disk, the amount of space
that is being used, and its percentage of the total disk space, and the
read/write status. To get this information for all of your accessed
disks, issue the command:
query disk *
To obtain information about the extents occupied
disks, enter the command:
listds
*
by files on OS and DOS
(extent
If you want to know the current order in which
searched for data files or programs, issue the command:
your disks
are
query search
You could also use this command to find out what disks you have
accessed, what filemode letters you have assigned to them, whether they
are read/write or read-only, and whether they are CMS, OS, or DOS disks.
COMMANDS TO REQUEST INFORMATION ABOUT YOUR VIRTUAL MACHINE
If you issue the command:
cp query virtual
40
IBM VM/370 CMS User's Guide
(
you can find out the status of your virtual machine configuration. You
can also request specific information; for example, the command:
cp query storage
gives you the amount of virtual storage you have available.
To find out the current spooling
punch, or reader, issue the commands:
characteristics of
your printer,
cp query OOe
cp query OOd
cp query OOc
To see information about all three at once, use:
cp query ur
For the
commands:
status of
spool files on
any of
these devices,
issue the
cp query printer
cp query punch
cp query reader
Using these commands, you can request the status of particular spool
files by referring to the spoolid number; for example:
cp query printer 4181
You can also request additional information about
file identification and creation time:
the files, including
cp query reader all
If you want to know the total number of spool
your virtual machine, you can use the command:
files associated with
cp query files
The response to this message is the same as the
you have spool files when you log on.
message you receive if
)
Section 3. What You Can Do With VM/310-CMS Commands
41
(
~
(
42
IBM VM/370 eMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
Section 4. The eMS File System
The file is the essential unit of data in the CMS system.
CMS disk
files are unique to the CMS system and cannot be read or written using
other operating systems. When you create a file in eMS, you name it
using a file identifier. The file identifier consists of three fields:
•
•
•
Filename (fn)
Filetype (ft)
Filemode (fm)
When you use CMS commands and programs to modify, update, or
reference files, you must identify the file by using these fields. Some
CMS commands require you to enter only the filename, or the filename and
filetype; others require you to enter the filemode field as well. This
section contains information about the things you must consider when you
give your CMS files their identifiers, notes on the file system commands
that create and modify CMS files,
and additional notes on using CMS
disks.
eMS File Formats
The eMS file management routines write eMS files on disk in fixed
physical
blocks, regardless
of
whether
they have
fixedor
variable-length records. For most of your eMS applications, you never
need to specify either a logical record length and record format or
block size when you create a CMS file.
When you create a file with the CMS editor, the file has certain
default characteristics, based on its filetype. The special filetypes
recognized by the editor, and their applications, are discussed under
"What are Reserved Filetypes?"
VSAM files written by CMS are in the same format as VSAM files
written by OS/VS or DOS/VS and are recognized by those operating
systems. You cannot, however, use any CMS file system commands to read
and write VSAM files,
because VSAM file formats are unique to the
virtual storage access method.
For a minidisk formatted in 800-byte physical blocks, a single CMS
file can contain up to 12,848,000 bytes of data grouped into as many as
65,533 logical records, all of which must be on the same minidisk. If
the file is a source program, the file size limit may be smaller. The
maximum number of files per real disk in the 800-byte physical block
format is 3400 for a 3330, 3333, 3340, or 3350 disk, or 3500 for a 2314
or 2319.
For a minidisk formatted in 1024-, 2048-, or 4096-byte logical
blocks, a single CMS file can contain up to about
(2 31 - 132,000) disk
blocks of data,
grouped into as many as 2 31 -1 logical records, all of
which must be on the same minidisk.
The approximate limits to the
number of files per disk, expressed in thousands, are:
)
Section 4. The CMSFile System
43
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for
5748~XX8
DISK LOGICAL BLOCK SIZE
~.!n~!£~ !1~~
lQ~~=.Ql!~
~Q~'§::Ql!~
2314
3330-11
3340
3350
3310
3370
21
149
50
45
55
216
11
86
26
25
29
114
~.Q.2'§=Ql!~
5
44
11
13
15
59
How eMS Files Get Their Names
When you create a eMS file, you can give it any filename and filetype
you wish. The rules for forming filenames and filetypes are:
•
•
The filename and filetype can each be from one to eight characters.
The valid characters are A-Z, 0-9, and $, #, a.
When you enter a command line into the VM/370 system, VM/370 always
translates your input line into uppercase characters. So, when you
specify a file identifier, you can enter it in lowercase.
Remember that, by default, the t
and ~ characters are line editing
symbols in VM/370;
when you use them to identify a file, you must
precede them with the logical escape symbol (").
The third field in the file identifier, the filemode, indicates the
mode letter
(A-Z) currently assigned to the virtual disk on which you
want the file to reside. When you use theCMS editor to create a file,
and you do not specify this field, the file you create is written on
your A-disk, and has a filemode letter of A.
The filemode letter, for any file,
can change during a terminal
session. For example, when you log on,
your virtual disk at address 191
is accessed as your A-disk, so a file on that disk named SPECIAL EVENTS
has a file identifier of:
SPECIAL EVENTS A
If, however, you later access another disk as your A-disk, and access
your 191 as your B-disk, then this file has a file identifier of:
SPECIAL EVENTS B
DUPLICATING FILENAMES AND FILETYPES
You can give the same filename to as many files on a given disk as you
want, as long as you assign them different filetypes. Oryoti can creite
many files with the same filetype but different filenames.
For the most part,
filenames that you choose for your files have no
special significance to CMS. If, however, you choose a name that is the
same as the name of a eMS command, and the file that you assign this
name to is an executable module or EXEC procedure, then you may
encounter difficulty if you try to execute the CMS command whose name
you duplicated.
44
IBM VM/370 eMS User's Guide
(
Pg. of GC20-1819-2 Rev March 30,
197~
by SUppa SD23-9024-1 for 5748-XX8
For an explanation of how CMS identifies
Command Search Order" later in this section.
a command name,
see "CMS
Many CMS commands allow you to specify one or more of the fields in a
file identifier as an asterisk
(*) or equal sign (=), which identify
files with similar fileids.
Some CMS commands that manipulate disk files allow you to enter the
filename and/or filetype fields as an asterisk (*), indicating that all
files of the specified filename/filetype are to be modified.
These
commands are:
COPY FILE
ERASE
RENAME
TAPE DUMP
For example, if you specify:
erase
*
test a
all files with a filetype of TEST on your A-disk are erased.
section 4. TheCMS File System
4~.1
March 30, 1979
44.2
IBM VM/370 eMS User's Guide
The LISTFILE command allows you to request similar lists.
If you
specify an asterisk for a filename or filetype, all of the files of that
filename or filetype are listed. There is an additional feature that you
can use with the LISTFILE command, to obtain a list of all the files
that have a filename or filetype that begin with the same character
string. For example:
listfile t* assemble
produces a list of all files on your A-disk whose
the letter T. The command:
filenames begin with
listfile tr* a*
produces a list of all files on your A-disk whose filenames begin with
the letters TR and whose filetypes begin with the letter A.
The COPIFILE, RENAME,
and SORT commands allow you to enter output file
identifiers as equal signs
(=), to indicate that it is the same as the
corresponding input file identifier. For example:
copy file myprog assemble b =
=a
copies the file MIPROG ASSEMBLE from your B-disk to your A-disk, and
uses the same filename and filetype as specified in the input fileid for
those positions in the output fileid.
Similarly, if you enter the command:
rename temp * b perm - all files with a filename of TEMP are renamed to have filenames of PERM;
the existing filetypes of the files remain unchanged.
What Are Reserved Filetypes?
For the purposes of most CMS commands, the filetype field is used merely
as an identifier. Some filetypes, though, have special uses in CMS;
these are known as "reserved filetypes."
Nothing prevents you from assigning any of the reserved filetypes to
files that are not being used for the specific CMS function normally
associated with that filetype.
Some reserved filetypes also have special significance to the CMS
editor. When you use the EDIT command to create a file with a reserved
filetype, the editor assumes various default characteristics for the
file, such as record length and format,
tab settings, translation to
uppercase, truncation column, and so on.
)
section 4. The CMS File System
45
FILETYPES FOR CMS COMMANDS
Reserved filetypes sometimes indicate how the file is used in the CMS
system: the filetype ASSEMBLE, for example, indicates that the file is
to be used as input to the assembler; the filetype TEXT indicates that
the file is in relocatable object form, and so on. Many CMS commands
assume input files of particular filetypes, and require you to enter
only tbe filename on the command line. For example, if you enter:
synonym test
CMS searches for a file with a filetype of SYNONYM and a filename of
TEST. A file named TEST that has any other filetype is ignored.
Some CMS commands create files of particular filetypes, using the
filename you enter on the command line. The language processors do this
as well; if you are recompiling a source file, but wish to save previous
output files, you should rename them before executing the command.
Figure 2 lists the filetypes used by CMS commands and describes how
they are used. Figure 3 lists the file types used by CMS/DOS commands.
In addition to these eMS filetypes,
there are special filetypes
reserved for use by the language processors, which are IBM program
products. These filetypes, and the commands that use them, are:
f!lg1IE~§
COBOL, SYMDMP, TESTCOB
FORTRAN, FREEFORT,
FTnn001, TESTFORT
PLI, PLIOPT
VSBASIC, VSBDATA
£Q~m~llg§
COBOL, FeOBOL, TESTCOB
FORTRAN, FORTGI, FORTH X
GOFORT, TESTFORT
DOSPLI, PLIC, PLleR, PLIOPT
VSBASIC
For details on how to use these filetypes,
program product documentation.
consult the
appropriate
{
46
IBM VM/370 eMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
Piletype
Command
Comments
AMSERV
AMSERV
Contains VSAM access method services control
statements to be executed with the AMSERV
command.
ASM3705
ASM3705
GEN 3705
Used by system programmers to generate the
3704/3705 control program.
ASSEMBLE
ASSEMBLE
AUXxxxx
UPDATE
Points to files that contain UPDATE control
statements for multiple updates.
CNTRL
UPDATE
Lists files that either contain UPDATE control
statements or point to additional files.
COpy
MAC LIB
Can contain COpy control statements and macros
or copy files to be added to MACLIBs.
DIRECT
DIRECT
Contains entries for the VM/370 user directory
file. The system operator controls this file.
EXEC
EXEC
GEN3705
LISTFILE
Can contain sequences of CMS or user-written
commands, with execution control statements.
HELPCMS
HELPCP
HELPDEBU
HELPEDIT
HELPMENU
HELPMSG
HELP
Contains descriptive information for CP and
CMS commands, messages, and menu lists.
LISTING
AMSERV
ASSEMBLE
ASM3705
Listings are produced by the assembler and
the language processors as well as the AMSERV
command.
LKEDIT
LKED
Contains the listing created during the
generation of the 3704/3705 control program.
LOADLIB
LKED
Is a library of 3704/3705 control program
load modules created during 3704/3705 control
program generation.
MACLIB
GLOBAL
MACLIB
Library members contain macro definitions or
copy files; the MACLIB command creates the
library, and lists, adds, deletes, or replaces
members. The GLOBAL command identifies which
macro libraries should be searched during an
assembly or compilation.
MACRO
MACLIB
Contains macro definitions to be added to a
CMS macro library (MACLIB).
MAP
INCLUDE
LOAD
MACLIB
TAPE
TXTLIB
Maps created by the LOAD and INCLUDE commands
indicate entry point locations; the MACLIB,
TXTLIB, and TAPE commands produce MAP files.
Contains source statements for assembler
language programs.
~----------------.------.---------------------------------------------------~
Figure 2. Filetypes Used by CMS Commands (Part 1 of 2)
Section 4. The CMS File System
47
March 30, 1979
Filetype
COllmand
Comments
MODULE
GEHMOn
LOADKOD
MODMAP
MODULE files created by the GEHMOD command are
nonrelocatable executable programs.
The LOADMOD commands loads a MODULE file for
execution; the MODMAP command displays a map
of entry point locations.
SYNONYM
SYNONYM
Contains a table of synonyms for CMS commands
and user-written EXEC and MODULE files.
SCRIPTl
SCRIPT
SCRIPT text processor input includes data and
SCRIPT control words.
TEXT
ASSEMBLE
INCLUDE
LOAD
TXTLIB
TEXT files contain relocatable object code
created by the assembler and compilers. The
LOAD and INCLUDE commands load them into
storage for execution. The TXTLIB command
lIanipulates libraries of TEXT files.
TXTLIB
GLOBAL
TXTLIB
Library members contain relocatable object
code. The TXTLIB command creates the library,
and lists or deletes existing members. The
GLOBAL command identifies TXTLIBs to search.
UPDATE
UPDATE
Contains UPDATE control statements for single
updates applied to source programs.
UPDLOG
UPDATE
Contains a record of additions, deletions, or
changes made with the UPDATE command.
UPDTxxxx
ZAP
UPDATE
ZAP
Contains UPDATE control statements for
multilevel updates.
Contains control records for the ZAP command,
which is used by system support personnel.
'SCRIPT is an IBM Installed User program (IUP).
Figure 2. Piletypes Used by CMS Commands (Part 2 of 2)
OUTPUT PILES: TEXT AND LISTING
Output files from the assembler and the language processors are
logically related to the source programs by their filenames.
Some of
these files are permanent and sOlie are temporary. For example, if you
issue the command:
assemble myfile
CMS locates a file named MYPILE with a filetype of ASSEMBLE and the
systea assembler assembles it. If the file is on your A-disk, then when
the assembler completes execution, the permanent files you have are:
MYPILE ASSEMBLE A1
MYPILE TEXT
A1
MYPILE LISTING 11
48
IBM VM/370 CMS User's Guide
r
-------,
Filetype
Command
Comments
COpy
MACLIB
SSERV
When the SSERV command copies books or macros
from DOS source statement libraries, the output
is written to CMS COpy files, which can be added
to CMS macro libraries with the MACLIB command.
DOSLIB
DOSLIB
DOSLNK
FETCH
GLOBAL
DOS core image phases are placed in a DOS LIB by
linkage editor, invoked with the DOSLNK command.
The GLOBAL command identifies DOSLIBs to be
searched when the FETCH command is executed.
DOSLNK
DOSLKED
Contains linkage editor control statements for
input to the CMS/DOS linkage editor.
ESERV
ESERV
Contains input control statements for the ESERV
utility program.
EXEC
LISTIO
The LISTIO command with the EXEC option creates
the $LISTIO EXEC that lists system and
programmer logical unit assignments.
LISTING
ASSEMBLE
ESERV
Listings contain processor output from the ESERV
command, and compiler output from the assembler
and language processors.
MACRO
ESERV
MACLIB
Contains SYSPCH output from the ESERV program,
suitable for addition to a CMS MACLIB file.
MAP
DOSLIB
DOSLKED
DSERV
The DSERV command creates listings of the
directories of DOS libraries. The DOSLIB command
with the MAP option produces a list of DOSLIB
members. The linkage editor map from the DOSLKED
command is written into a MAP file.
PROC
PSERV
The PSERV command copies procedures from DOS
procedure libraries into CMS PROC files.
TEXT
ASSEMBLE
DOSLKED
RSERV
Object decks created by the assembler or
compilers are written into TEXT files. The RSERV
command creates TEXT files from modules in DOS
relocatable libraries. TEXT files can also be
used as input to the linkage editor.
Figure 3. Filetypes Used in CMS/DOS
where the TEXT file contains the object code resulting from the
assembly, and the LISTING file contains the program listing generated by
the assembly. If any TEXT or LISTING file with the same name previously
existed, it is erased. The source input file, MYFILE ASSEMBLE Al, is
neither erased nor changed.
The characteristics of the TEXT and LISTING files produced by the
assembler are the same as those created by other processors and programs
in CMS.
Because these files are CMS files, you can use the CMS editor to
examine or modify their contents. If you want a printed copy of a
LISTING file, you can use the PRIN~ command to print it. If you want to
examine a TEXT file, you can use the TYPE or PRINT command specifying
the HEX option.
Section 4. The CMS File System
49
Note that if a TEXT file contains control ~hanges for the terminal,
the edit lines may not be displayed in their true form. Therefore, it
is suggested you do not use the editor for TEXT files, because the
results are unpredictable~ Instead, use the TYPE and/or PRINT commands
with the HEX option to display TEXT decks. Put TEXT decks into a TXTLIB
and ZAP the TXTLIB to modify the TEXT deck.
FILETYPES FOR TEMPORARY FILES
The filetypes of files created by the assembler and language processors
for use as temporary workfiles are:
SISUT1
SYSUT2
SISUT3
SYSUT4
SYS001
SYS002
SIS003
SYS004
5YS005
SYS006
CMS handles all SYSUTX and SYSOOx files as temporary files.
The CMS AMSERV command, executing VSAM utility functions,
work files that have filetypes of LDTFDl1 and LDTFDI2.
uses two
Disk space is allocated for temporary files on an as-needed basis.
They are erased when processing is complete.
If a program you are
executing is terminated before completion, these workfiles may remain on
your disk. you can erase them.
The CMSUT1 filetype is used by CMS commands that create files on your
CMS disks. The CMSUT1 file is used as a workfile and is erased when the
file is created.
When a command fails to complete execution properly,
the CMSUT1 file may not be erased. The commands, and the filenames they
assign to files they create, are listed below.
~2~~gBg
COPYFILE
DISK LOAD
EDIT
INCLUDE
LOAD
MACLIB
READCARD
TAPE LOAD
UPDATE
~il~n!~~
COPYFILE
DISK
EDIT
DMSLDR
DMSLDR
DMSLBM
READCARD
TAPE
fn (the filename of the UPDATE file)
FILETIPES FOR DOCUMENTATION
There are two CMS reserved filetypes that accept uppercase and lowercase
input data. These are MEMO and SCRIPT.
Iou can use MEMO files to
document program notes or to write reports. The SCRIPT filetype is used
by the SCRIPT command, which invokes a text
processor that is an IBM
Installed User Program (IUP).
(
50
IBM VM/310 eMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1919 by Supp. SD23-9024-1 for 5148-118
Filemode Letters and Numbers
The filemode field of a CMS file identifier has two characters: the
filemode letter and the filemode number.
The filemode letter is
established by the ACCESS command and specifies the virtual disk on
which a file resides: A through Z. The filemode number is a number from
o to 5, which you can assign to the file when you create it or rename
it; if you do not specify it, the value defaults to 1. How you access
your disks and what filemode letters you give them with the ACCESS
command depends on how you want to use the files that are on them.
For most of the reading and writing you do of files, you use your
A-disk, which is also known as your primary disk. This is a read/write
disk.
You may access other disks in your configuration, or access
linked-to disks, in read-only or read/write status, depending on whether
you have a read-only or read/write link.
When you load CMS
(with the IPt command), your virtual disk at
address 191 is accessed for you as your A-disk. Your virtual disk at
address 190 (the system disk) is accessed as your S-disk; and the disk
at 19E is accessed as an extension of your S-disk, with a mode letter of
Y.
In addition, if you have a disk defined at address 192, it is
accessed for you as your D-disk.
If the 192 disk has not been
formatted, CMS will do it automatically and label the minidisk 'SCRTCH'.
If ACCESS is the first command issued after an IPL of the CMS system,
only the A-disk is not automatically defined. Another ACCESS command
must be issued to define the A-disk.
The actual letters you assign to any other disks
(and you may
reassign the letters A,
D, and Y), is arbitrary; but it does determine
the CMS search order, which is the order in which CMS searches your
disks when it is looking for a file. The order of search (when all disks
are being searched) is alphabetical: A through Z. If you have duplicate
file identifiers on different disks, you should check your disk search
order before issuing commands against that filename to be sure that you
will get the file you want. You can find out the current search order
for your virtual disks by issuing the command:
query search
You can also
example:
access disks as logical extensions of
other disks, for
access 235 b/a
The "/A" indicates that the B-disk is to be a read-only extension of the
A-disk, and the A-disk is considered the "parent" of the B-disk. A disk
may have many extensions, but only one level of extension is allowed.
If you have a disk accessed as an extension of another disk, the
extension disk is automatically read-only, and you cannot write on it.
You might access a disk as its own extension, therefore, to protect the
files on it, so that you do not accidentally write on it. For example:
access 235 bib
Section 4. The CftS File Systea
51
March 30, 1979
Another use of extensions is to extend the CMS search order.
issue a command requesting to read a file, for example:
If you
type alpha plan
CMS searches your A-disk for the file named ALPHA PLAN and if it does
not find it, searches any extensions that your A-disk may have. If you
have a file named ALPHA PLAN on your B-disk but have not accessed it as
an extension of your A-disk, CMS will not find the file, and you will
have to reenter the command:
type alpha plan b
Additionally, if you issue a CMS command that reads and writes a
file, and the file to be read is on an extension of a read/write disk,
the output file is written to the parent read/write disk. The EDIT
command is a 'good example of this type of command. If you have a file
named FINAL LIST on a B-disk extension of a read/write A~disk, and if
you invoke the editor to modify the file with the command:
edit final list
after you have made modifications to the file, the changed file
written onto your A-disk. The file on the B-disk remains unchanged~
is
When you access a disk as a read-only extension, it remains an extension
of the parent disk as long as both disks are still accessed. If either
disk is released,
the relationship of parent
disk/extension is
terminated.
If the parent disk is released, the extension remains accessed and
you may still read files on it. If you access anothe~ disk at the mode
letter of the original parent disk, the parent/extension relationship
remains in effect.
If you release a read~only extension and access another disk with the
same mode letter, it is not an extension of the original parent disk
unless you access it as such. For example, if you enter:
access 198 cia
release c
access 199 c
the C-disk at virtual address 199 is not an extension of your A-disk.
WBEN TO SPECIFY FILEMODE LETTERS: READING FILES
When you request CMS to access a file, you have to identify it so that
CMS can locate it for you. The commands that expect files of particular
filetypes (reserved filetypes)
allow you to enter only the filename of
the file when you issue the command. When you execute any of th~se
commands or execute a MODULE or EXEC file, CMS searches all of your
accessed disks
(using the standard search order)
to locate the file.
The CMS commands that perform this type of search are:
AMSERV
ASSEMBLE
DOSLIB
EXEC
52
GLOBAL
LOAD
LOADMOD
MACLIB
IBM VM/370 CMS User's Guide
MODMAP
RUN
TXTLIB
Some CMS commands require you to enter the filename and filetype to
identify a file. You may specify the filemode letter; if you do not
specify the filemode, CMS searches only your A-disk and its extensions
when it looks for the file. If you do specify a filemode letter, the
disk you specify and its extensions are searched for the file. The
commands you use this way are:
EDIT
ERASE
FILEDEF
PRINT
PUNCH
STATE
SYNONYM
TAPE DUMP
TYPE
UPDATE
There are two CMS commands that do
when looking for files. They are:
not search extensions
of disks
DISK DUMP
LISTFILE
You must explicitly enter the filemode if you want to use these commands
to list or dump files that are on extensions.
For some CMS commands, if you specify the file.ode of a file as an
asterisk, it indicates that you either do not know or do not care what
disk the file is on and you want CMS to locate it for you. For example,
if you enter:
listfile myfile test
)
*
the LISTFILE command responds by listing all files on your accessed
disks named MYFILE TEST. When you specify an asterisk for the file.ode
of the COPYFILE~ ERASE, or RENAME commands, CMS locates all copies of
the specified file. For example:
rename temp sort
*
good sort =
renames all "files named TEMP SORT to GOOD SORT on all of your accessed
read/write disks. An equal sign (=) is valid in output fileids for the
RENAME and COPYFILE commands.
For some commands, when you specify an asterisk for the filemode of a
file, CMS stops searching as soon as it finds the first copy of the
file. For example:
type m1file assemble
*
If there are files named MYFILE ASSEMBLE on your A-disk and C-disk, then
only the copy on your A-disk is displayed. The commands that perform
this type of search are:
COMPARE
DISK DUMP
EDIT
FILEDEF
PRINT
PUNCH
RUN
SORT
STATE
SYNONYM
TAPE DUMP
TYPE
For the COMPARE, COPYFILE, RENAME, and SORT commands, you must always
specify afilemode letter, even if it is specified as an asterisk.
)
Section 4. The CMS File System
53
WHEN TO SPECIFY FILEMODE LETTERS: WRITING FILES
When you issue a CMS command that writes a file onto one of your virtual
disks, and you specify the output filemode, CMS writes the file onto
that disk. The commands that require you to specify the output filemode
are:
COPYFILE
RENAME
SORT
The commands that allow you to
not require it, are:
FILEDEF
GENMOD
READCARD
specify the output filemode,
but do
TAPE LOAD
TAPPDS
UPDATE
When you do not specify the filemode on these commands,
output files onto your A-disk.
CMS writes the
Some CMS commands that create files always write them onto your
A-disk. The LOAD and INCLUDE commands write a file named LOAD MAP AS.
The LISTFILE command creates a file named CMS EXEC, on your A-disk. The
CMS/DOS commands DSERV, ESERV, SSERV, PSERV, and RSERV also write files
onto your A-disk.
Other commands that
output files either:
•
•
do not allow you to specify
the filemode, write
To the disk from which the input file was read, or
To your A-disk, if the file was read from a read-only disk
These commands are:
AMSERV
MACLIB
TXTLIB
UPDATE
The SORT command also functions this
filemode as an asterisk (*).
way if you specify
the output
In addition, many of the language processors,
when creating work
files and permanent files, write onto the first read/write disk in your
search order, if they cannot write on the source file's disk or its
parent.
HOW FILEMODE NUMBERS ARE USED
Whenever you specify a file mode letter to reference a file, you can also
specify a filemode number. Since a filemode number for most of your
files is 1, you do not need to specify it.
The filemode numbers 0, 2,
3, 4, and 5 are discussed below. Filemode numbers 6 through 9 are
reserved for IBM use.
!!le~2g~ 0:
private.
to your
requests
of 0 are
54
A filemode number of 0 assigned to a file makes that file
No other user may access it unless they have read/write access
disk. If someone links to your disk in read-only mode and
a list of all the files on your disk, the files with a filemode
not listed.
IBM VM/370 CMS User's Guide
(
March 30, 1979
File.ode 2: Filemode 2 is essentially the same, for the purposes of
readIng-and writing files, as filemode 1. Usually a file.ode of 2 is
assigned to files that are shared by users who link to a common disk,
like the system disk. Since you can access a disk and specify which
files on that disk you want to access, files with a file.ode of 2
provide a convenient subset of all files on a disk. For exa~ple, if you
issue the command:
access 489 e/a
**
you can only read files
address 489.
e2
with a filemode
of 2
on the disk
at virtual
Filemode 3: Files with a filemode of 3 are erased after they are read.
If-You-create a file with a filemode of 3 and then request that it be
printed, the file is printed, and then erased. You can use this file.ode
if you write a program or EXEC procedure that creates files that you do
not want to maintain copies of on your virtual disks. You can create the
file, print it, and not have to worry about erasing it later.
The language processors and some CMS commands create
give these work files a filemode of 3.
work files and
Note: A filemode of 3 should not be used with EXECs. Depending on what
commands are issued within it, an EXEC with a filemode of 3 may be
erased before it completes execution.
!ile~2g~~:
Files with a filemode of 4 are in OS simulated data set
format. These files are created by OS macros in progr~.s running in
CMS.
You specify that a file created by a program 1S to have OS
simulated data set format by specifying a filemode of 4 when you issue
the FILEDEF command for the output file.
If you do not specify a
filemode of 4, the output file is created in CftS format.
You can find more details about OS simulated data sets in "section 8.
Developing OS Programs Under CMS."
!~te:
There are no filemode numbers reserved for DOS or VSAM data sets,
since CMS does not simulate these file organizations.
Filemode 5: This filemode number is the same, for purposes of reading
ana-wrIting, as filemode 1. You can assign a filemode of 5 to files that
you want to maintain as logical groups, so that you can manipulate thea
in groups. For example, you can reserve the filemode of 5 for all files
that you are retaining for a certain period of time; then, when you want
to erase them, you could issue the command:
erase
* *
as
You can assign filemode numbers when you use the following commands:
COPYFILE: You can assign a filemode number when you create a new file
wIth-the COPYFILE command. To change only the filemode number of an
existing file, you must use the REPLACE option. For exaaple:
copyfile test module al
changes the
fil~m?de
= = a2
(replace
number of the file TEST MODULE A frOB 1 to 2.
)
section 4. The CMS File system
55
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
~~IT:
You can assign a filemode number when you create a file with the
CMS editor. To change thefilemode number of an existing file, use the
RENAME or COPYFILE commands, or use the FMODE subcommand when you are in
the edit environment.
f!1!Q!f: When you assign file definitions to disk files for
programs or CMS command functions, you can specify a filemode number.
~1~1,
§~!~QQ:
You can specify a filemode number on the GENMeD command line.
To change the filemode number of an existing MODULE file, use the RENA~E
or COPYFILE commands.
READCARD: You can assign a filemode number ~hen you specify a
IdentIfIer on the READCARD command line or on a READ control card.
RENAME: Wh~n you specify the fileids on the RENAME command,
specIfy the filemode numbers for the input and/or output files.
~QRT:
You can specify filemode numbers
fileids on the SORT command line.
for the
file
you can
input and/or
output
Managing Your CMS Disks
The number of files you can write on a CMS disk depends on both the size
of the disk and the size of the files that it contains.
You can find
out how much space is being used on a disk by using the QUERY DISK
command. For example, to see how much space is on your A-disk, you would
enter:
query disk a
The response maybe something like this:
LABEL
~YDISK
M
191 A
CUll
STAT eYL TYPE BLKSIZE
R/W
5 3330
1024
FILES
171
ELKS USED-(%) ELKS LEFT
1221-92
107
ELK TOTAL
1328
When a disk is becoming full, you should erase whatever files you no
longer need. Or dump to tape files that you need to keep but do not need
to keep active on disk.
When you are executing a command or program that writes a file to
disk, and the disk becomes full in the process, you receive an error
message, and you have to try to clear some space on the disk before you
can attempt to execute the command or program again.
To avoid the
delays that such situations cause, you should try to maintain an
awareness of the usage of your disks.
If you cannot erase any more
files from your disks, you should contact installation support personnel
about obtaining additional read/write CMS disk space.
CMS File Directories
Each CMS disk has a master file directory that contains entries for each
of the CMS files on the disk.
When you access a disk, information frem
the master file directory is brought into virtual storage and written
into a user file directory. The user file directory has an entry for
each file that you may access. If you have accessed a disk specifying
only particular files, then the user file directory contains entries
only for those files.
56
IBM VM/370 eMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1919 by Supp. SD23-9024-1 for 5148-118
If you have read/write access to a disk, then each time you write the
file onto disk the user file directory and master file directory are
updated to reflect the current status of the disk. If you have read-only
access to a disk, then you cannot update the master file directory or
user file directory. If you access a read-only disk while another user
is writing files onto it,
you may need to periodically reissue the
ACCESS command for the disk, to obtain a fresh copy of the master file
directory.
!Q~:
You should
another user.
never attempt to write on
a disk at the
saae time as
The user file directory remains in virtual storage until you issue
the RELEASE command specifying the mode letter or virtual address of the
disk. If you detach a virtual disk
(with the CP DETACH command) without
releasing it, CMS does not know that the disk is no longer part of your
virtual machine. When you attempt to read or write a file on the disk
CftS assumes that the disk is still active
(because the user file
directory is still in storage) and encounters an error when it tries to
read or write the file.
A similar situation occurs if you detach a disk and then add a new
disk to your virtual machine using the same virtual address as the disk
you detached. For example, if you enter the following sequence of
commands:
cp link user1 191 195 rr rpass l
access 195 d
cp detach 195
cp link user2 193 195 rr rpass2 1
1istfi1e * * d
the LISTFILE command produces a list of the files on OSER1's 191 disk;
if you attempt to read one of these files, you receive an error message.
You must issue the ACCESS command to obtain a copy of the master file
directory for USER2's 193 disk.
The entries in the master file directory are sorted a1phamerica11y by
filename and fi1etype,
to facilitate the CftS search for particular
files. When you are updating disk files, the entries in the user file
directory and master file directory tend to become unsorted as files are
created, updated, and erased. When you use the RELEASE co ••and to
release a read/write disk, the entries are sorted and the master file
directory is rewritten. If you or any other user subsequently access
the disk, the file search may be aore efficient.
CMS Command Search Order
When you enter a command line in the CftS environment, CftS has to locate
the command to execute. If you have EXEC or MODOLE files on any of your
accessed disks, CMS treats them as commands; also, they are known as
user-written commands.
As soon as the command name is found.
command is executed. The search order is:
1.
EXEC file on any currently accessed
search order (1 through Z.)
the search
disk.
CftS uses
stops and
the
the standard
IBote that the password cannot be entered on the command line
password suppression facility was specified at sysgen.
if the
Section 4. The CftS File Systea
51
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp.
SD23~9024-1
for 5748-XX8
2.
Valid abbreviation or truncation for an . EXEC file on any currently
accessed disk, according to current SYNONYM file definitions in
effect.
.
3.
A command that has already been loaded
The transient area commands are:
ACCESS
ASSGN
COMPARE
DISK
DLBL
FILEDEF
GENDIRT
GLOBAL
4.
HELP
LISTFILE
MODMAP
OPTION
PRINT
PUNCH
QUERY
READCARD
A nucleus-resident command.
CP
DEBUG
ERASE
FETCH
into the
transient area.
RELEASE
RENAME
SET
SVCTRACE
SYNONYM
TAPE
TYPE
The nucleus-resident CMS commands are:
GENMOD
INCLUDE
LOAD
LOADMOD
START
STATE
STATEW
5.
Command module on any currently accessed disk.
(All the remaining
CMS commands are disk resident and execute in the user area.)
6.
Valid abbreviation or truncation
area command module.
7.
Valid abbreviation or truncation for disk-resident command.
for nucleus-resident or transient
For example, if you create a command module that has the same name as
a CMS nucleus-resident command, your command module cannot be executed,
since CMS locates the nucleus-resident command first, and executes it.
When a user-written command has the same name as a CMS command module
abbreviation, certain error messages may indicate the CMS command name,
rather than the program name.
Figure 4 shows more details of the command search order.
58
IBM VM/370 eMS User's Guide
KEY IN A
COMMAND NAME
YES
EXECUTE
THE FILE
AND RETURN
CONTROL TO
CMS.
CMS
EXEC
SEARCH
L
YES
YES
EXPAND THE
NAME TOTHE
FULL REAL
NAME, EXECUTE
IT, AND RETURN
CONTROL TO CMS.
EXECUTE THE
FILE AND
RETURN CONTROL
TO CMS.
CMS
MODULE
SEARCH
YES
)
YES
CP
SEARCH
b
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
Figure
4.
How CMS Searches for the Command to Execute
Section 4. The CMS File system
59
(
60
IBM V!/370 eMS User's Guide
Section 5. The eMS Editor
In CMS usage, the term edit is used in a variety of ways, all of which
refer, ultimately, to the functions of the CMS editor, which is invoked
when you issue the EDIT command.
To edit a file means to make changes, additions, or deletions to a
CMS file that is on a disk, and to make these changes interactively: you
instruct the editor to make a change, the editor does it, and then you
request another change.
You can edit a file that does not exist; when you
the file online, and can modify it as you enter it.
do so, you create
To file a file means to write a file you are editing back onto a
disk, incorporating any changes you made during the editing session.
When you issue the FILE subcommand to write a file, you are no longer in
the environment of the CMS editor, but are returned to the CMS
environment. You can, however, write a file to disk and then continue
editing it, by using the SAVE subcommand.
An editing session is the period of time during which a file is in
your virtual storage area, from the moment you issue the EDIT command
and the editor responds EDIT: until you issue the FILE or QUIT
subcommands to return to the CMS command environment.
)
The EDIT Command
When you issue the EDIT command you must specify
filetype of the file you want to edit. If you issue:
the filename
and
edit test file
CMS searches your A-disk and its extensions for a file with the
identification TEST FILE. If the file is not found, CMS assumes that you
want to create the file and issues the message:
NEW FILE:
EDIT:
to inform you that the file does not already exist.
If the file exists on a disk other than your A-disk and its
extensions, or if you want to create a file to write on a read/write
disk other than your A-disk, you must specify the filemode of the file:
edit test file b
In this example, your B-disk
file TEST FILE.
and its
extensions are searched
for the
After you issue the EDIT command, you are in edit mode, or the
environment of the CMS editor. If you have specified the filename and
filetype of a file that already exists, you can now use EDIT subcommands
to make changes or corrections to lines in that file. If you want to
Section 5. The CMS Editor
61
add records to the file, as you would
issue the EDIT subcommand:
if you are creating
a new file,
input
to enter input mode. Every line that you enter is considered a data line
to be written into the disk file.
For most filetipes, the editor
translates all of your input data to uppercase characte~s, regardless of
how you enter it. For example, if you create a file and enter input
mode as follows:
.
edit myfile test
NEW FILE:
EDIT:
input
INPUT:
This is a file I am
learning to create with the CMS
editor~
the lines are written into the file as:
THIS IS A FILE I AM
LEARNING TO CREATE WITH THE CMS EDITOR.
You can use the VM/370 logical
lines as you enter them.
line editing symbols to
modify data
To return to edit mode to modify a £ile or to terminate the edit
session, you must press the Return key on a null line. If you have just
entered a data line, for example, and your terminal's typing element or
cursor is positioned at the last character you entered, you must press
the Return key once to enter the data line, and a second time to enter a
null line.
You may also
for example:
use the logical line
end symbol to enter
a null line;
last line of input.
#
Both of these lines cause you to return to edit mode from input mode.
If you do not enter a null line, but enter an EDIT subcommand or CftS
command, the command line is written into your file as input. The only
exception to this is a line that begins with the characters tcP. These
characters indicate that the command is to be passed immediately to CP
for processing.
WRITING A FILE ONTO DISK
A file you create and the modifications that you make to it during an
edit session are not automatically written to a disk file.
To save the
results, you can do the following:
•
Periodically issue the subcommand:
save
to write onto disk the contents of the file as it exists when you
issue the subcommand.
Periodically issuing this EDIT subcommand
protects your data against a system failure; you can be sure that
changes you make are not lost.
62
IBM VM/370 CMS User's Guide
(
•
At the beginning of the edit
with a number:
session, issue the AUTOSAVE subcommand,
autosave 10
Then, for every tenth change or addition to the file, the editor
issues an automatic save request, which writes the file onto disk.
•
At the end of the edit session, issue the subcommand:
file
This subcommand terminates the edit session, writes the file onto
disk, replacing a previous file by that name (if one existed), and
returns you to the CMS environment. You can return to the edit
environment by issuing the EDIT command, specifying a different file
or the same file.
The editor decides which disk to write the file onto according to the
following hierarchy:
\
)
•
If you specify a filemode on the FILE or SAVE subcommand
file is written onto the specified disk.
•
If the current filemode of the file is the mode of a read/write disk,
the file is written onto that disk.
(If you have not specified a
filemode letter, it defaults to your A-disk.)
•
If the filemode is the mode of a read-only extension of a read/write
disk, the file is written onto the read/write parent disk.
•
If the filemode is the mode of a read-only disk that is not an
extension of a read/write disk, the editor cannot write the file and
issues an error message.
See "Changing File Identifiers" for information on how
the editor what disk to use when writing a file.
line, the
you can tell
If you are editing a file and decide, after making several changes,
that you do not wish to save the changes, you can use the subcommand:
quit
No changes that you made since you last used the SAVE subcommand (or the
editor last issued an automatic save for you) are retained. If you have
just begun an edit session, and have made no changes at all to a file,
and for some reason you do not want to edit it at all (for example, you
misspelled the name, or want to change a CMS setting before editing the
file), you can use the QUIT subcommand instead of the FILE subcommand to
terminate the edit session and return to CMS.
A file must have at least one line of data in order to be written.
EDIT SUBCOMMANDS
While you are in the edit environment, you can issue any EDIT subcommand
or macro. An edit macro is an EXEC file that contains a sequence of EDIT
subcommands that execute as a unit. You can create your own EDIT
subcommands with the CMS EXEC facility.
EDIT subcommands provide a
varietyaf functions. You can:
.
)
•
position the current line pointer at a particular line, or record, in
a file.
Section 5. The CMS Editor
63
•
Control which columns
editing session.
of a file are displayed or
•
Modify data lines.
•
Describe the characteristics
will have.
•
Automatically
records.
•
Edit files by line number.
•
Control the editing session.
write and
that a file and
update
sequence
searched during an
its individual records
numbers for
fixed-length
Like CMS commands, EDIT subcommands have a subcommand name and some have
operands. In most cases, a subcommand name (or its truncation) can be
separated from its operands by one or more blanks, or no blanks. Por
example, the subcommand lines:
type 5
ty
5
tS
are equivalent.
Several subcommands also use delimiters,
which enclose a character
string that you want the editor to operate on. For example, the CHANGE
subcommand can be entered:
change/apple/pearl
The dia10nal (/) delimits the character strings APPLE and PEAR. Por the
subcommands CHANGE, LOCATE, and DSTRING, the first nonblank character
following the subcommand name (or its truncation)
is considered the
delimiter. No blank is required following the subcommand name. In the
subcommand:
locate $vm/$
the dollar sign ($)
is the delimiter. You cannot use a / in this case,
since the diagonal is part of the character string you want to locate.
When you enter
for example:
these subcommands, you may omit
the final delimiter;
dstring/csect
You must enter the final delimiter, however, when you
change with the CHANGE subcommand.
specify a global
Por the FIND and OVERLAY subcommands, additional blanks following the
subcommand names are interpreted as arguments. The subcommand:
find
Pudding
requests the editor to locate the line that has" Pudding" in columns 1
through 9. Initial blanks are considered part of the character string.
64
IBM VM/370 CMS User's Guide
(
-
Pg. of GC20-1819-2 Rev March 30, 1919 by Supp. SD23-9024-1 for 5748-X18
An asterisk, when used with an EDIT subcommand, may mean "to the end
of the file" or "to the record length." For example:
delete*
deletes all of the lines in a file, beginning with the current line.
verify *
indicates that the editor should display the entire length of records.
When you make an error entering
the message:
?EDIT:
an EDIT subcommand, the editor displays
line •••
where line ••• is the
understand.
line, as you entered it, that
the editor does not
The Current Line Pointer
When you begin an editing session, a file is copied into virtual
storage; in the case of a new file, virtual storage is acquired for the
file you are creating. In either case, you can picture the file as a
series of records, or· lines; these lines are available to you, one at a
time, for you to modify or delete. You can also insert new lines or
records following any line that is already in the file.
The line that you are currently editing is pointed to by the current
line pointer.
On a display terminal,
this line is highlighted. What
you do during an editing session is:
•
position the
edit.
current line
pointer to
access the
line you
•
Edit the line: change character strings
new records following it.
•
position the line pointer at the next line you want to edit.
in it, delete it
want to
or insert
When you are editing a file and you issue an EDIT subcommand that
either changes the position of the line pointer or that changes a line,
the current line or the changed line
(or lines) is displayed. You can
also display the current line by using the TYPE subcommand:
type
If you want to examine more than one line in your file, you can use the
TYPE subcommand with a numeric parameter. If you enter:
type 10
the current line and the nine lines that follow it are displayed; the
line pointer then stays positioned at the last line that was displayed.
You can move the line pointer up or down in your file. "Up" indicates
a location toward the beginning. of the file (the first record) ;."down"
Section 5. The CMS Editor
65
ftarch 30, 1979
indicates a location toward the end of the file (the last record). You
use the EDIT subcomaands UP and DOWN to move the line pointer up or down
one or more lines. For example:
up 5
moves the current line pointer
beginning of the file, and:
to a
line
five lines
closer to
the
down
moves the pointer to point at the next sequential record in the file.
You can also request that the line
beginning, or top of the file, or at the
When you issue the subcommand:
pointer be placed at the
end, or bottom of the file.
top
you receive the message:
TOF:
and the line pointer is positioned at a null line that is always at the
top of the file. This null line exists only during your editing session;
it is not filed on disk when you end the editing session.
When you issue the subcommand:
bottom
the current line pointer is positioned at the last record in the file.
If you now enter input mode, all lines that you enter are appended to
the end of the file.
If the current line pointer is at the bottom of
issue the DOWN subcommand, you receive the message:
the file
and you
EOF:
and the current- line pointer is positioned at the end of file, following
the last record.
When you are adding records to your file, the current line pointer is
always pOinting at the line you last entered. When you delete a line
from a file, the line pointer moves down to point to the next line down
in the file.
Going from edit mode to input mode does not change the current line
pointer. If you are creating a new file and, every 30 lines or so, you
move the current line pointer to make corrections to the lines th~t you
have entered, you must issue the BOTTOft subcommand to begin entering
more lines at the end of the file.
The current line pointer is also moved as the result of the· LOCATE
and FIND subcommands. You use the FIND subcommand to get to a line when
you know the characters at the beginning of the line. For example, if
you want to change the line:
BAXTER
J.F.
065941
ACCNTNT
you could first locate it by using the subcommand:
find baxter
66
IBft Vft/370 CftS User's Guide
If you do not know the
LOCATE subcommand:
first characters on
a line, you can
issue the
locate laccntntl
Both of these subcommands work only in a top-to-bottom direction: you
cannot use them to position the line pointer above the current line. If
you use the FIND or LOCATE subcommands and the target
(the character
string you seek)
is not found, the editor displays a message, and
positions the line pointer at the end of the file. Subsequently, if you
reissue the subcommand, the editor starts searching at the top of the
file.
In a situation like that above, or in a case where you are
repetitively entering the same LOCATE or FIND subcommand (if, for
example, there are many occurrences of the same character string, but
you seek a particular occurrence) you can use the = (REUSE) subcommand.
To use the example above, you are looking for a line that contains the
string ONCE UPON A TIME, but you do not know that it is above the
current line. When you issue the subcommand:
locate lonce upon a time/
the editor does not locate the line, and responds:
NOT FOUND
EOF:
If you enter:
=
)
the editor searches again for the same string, beginning this
the top of the file, and locates the line:
time at
"ONCE UPON A TIME" IS A COMMON
This may
enter:
still not
be the line
you are looking
for. You
can, again,
=
The LOCATE subcommand is executed again.
locate the line:
This time, the
editor might
A STORY THAT STARTED ONCE UPON A TIME
Figure 5 illustrates a simple CMS file, and indicates how the current
line pointer would
be positioned following a
sequence of EDIT
subcommands.
11NE=!Q~~~~ ~~lI1NG:
Some fixed-length files are suitable for editing by
referencing line numbers instead of
character strings. The EDIT
subcommands that allow you to change the line pointer position by line
number are discussed under "Line-Number Editing."
Section 5. The CMS Editor
61
EDIT PPRINT EXEC
CLP
---)
o
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
TOF:
(null line)
&CONTROL OFF
&P =
&IF .&1 EQ • &EXIT 100
&FN = &1
&IF &1 EQ ? &GOTO -TELL
&NFB = &CONCAT $ &1
&IF .&2 EQ • &EXIT 200
&FT = &2
&FM = &3
&IF .&3 NE • &SKIP 2
&FM = A
&SKIP 3
&IF &3 NE ( &SKIP 2
&FM = A
&P = (
&CONTROL ALL
COpy &FN &FT &FM &NFN &FT A ( UNPACK
PRINT &HFN &FT A &P &4 &5 &6 &7 &8 &9 &10 &11 &12 &13 &14
ERASE &NFN &FT A
&EXIT
-TELL
&TIPE THIS EXEC PRINTS A LISTING FROM PACKED FORMAT
EOF:
The line numbers represented are symbolic: they are not an actual
part of the file, but are used below to indicate at which line the
current line pointer is positioned after execution of the EDIT
subcommand indicated.
Subcommand
DOWN 5
UP
LOCATE JUNP/
TYPE 3
BOTTOM
DOWN
FIND TOP
CHANGE /EQ/EQ/ 6
DELETE 2
INPUT
*
CLP position
---) 0
---) 5
---) 4
---) 17
---) 19
---) 21
---) EOF:
---) 21
---) 0
---) 5
---) 7 (lines numbered 5 and 6 are deleted)
---) the line just entered (between 7 and 8)
Figure 5. Positioning the Current Line Pointer
Verification and Search Columns
There are two EDIT subcommands you can use to control what you and the
editor "see" in a file.
The VERIFY subcommand controls what you see
displayed; the ZONE subcommand controls
what columns the editor
searches. Normally, when you edit a file, every request that you make
of the editor results in the display of one or more lines at your
terminal. If you do not want to see the lines, you can specify:
verify off
68
IBM VM/370 CMS User's Guide
(
Alternatively, if you want to see only particular columns in a file, you
can specify the columns you wish to have displayed:
verify 1 30
Some filetypes have default values set for verification, which
usually include those columns in the file that contain text or data, and
exclude columns that contain sequence numbers. If a verification column
is less than the record length, you can specify:
verify
*
to indicate that you want to see all columns displayed.
In conjunction with the VERIFY subcommand, you can use the ZONE
subcommand to tell the editor within which columns it can search or
modify data. When you issue the subcommand:
zone 20 30
The editor ignores all text in columns 1-19 and 31 to the end of the
record when it searches lines for LOCATE, CHANGE, ALTER, and FIND
subcommands. You cannot unintentionally modify data outside of these
fields; you must change the zones in order to operate on any other data.
The zone setting also controls the truncation column for records when
you are using the CHANGE subcommand; for more details, see "Setting
Truncation Limits."
Changing, Deleting, and Adding Lines
)
You can change character strings in individual lines of data with the
CHANGE subcommand. A character string may be any length, or it may be a
null string. Any of the characters on your terminal keyboard, including
blanks, are valid characters. The following example shows a simple data
line and the cumulative effect of CHANGE subcommands.
ABC ABC ABC
is the initial data line.
CHANGE IABC/XYZI
changes the first
string "XYZ".
occurrence of the character string
"ABC" to the
XYZ ABC ABC
CHANGE IABCI/
deletes the character string "ABC"
on each side of it.
XYZ
and concatenates the characters
ABC
CHANGE IIABC/
inserts the string "ABC" at the beginning of the line.
ABCXYZ
)
ABC
CHANGE /XYZ /XYZ/
deletes one blank character following "XYZ".
ABCXYZ ABC
Section 5. The CMS Editor
69
CHANGE /C/C /
adds a blank following the first occurrence of the character "Cu.
ABC XYZ ABC
is the final line.
THE ALTER SUBCOMMAND: You can use the ALTER subcommand to change a
siiigle--character;--the ALTER subcommand
allows you to specify a
hexadecimal value so that you can include characters in your files for
which there are no keyboard equivalents.
Once in your file, these
characters appear during editing as nonprintable blanks.
For example,
if you input the line:
IF A = BTHEN
in edit mode and then issue the subcommand:
alter = 8e
the line is displayed:
IF A
B THEN
If you subsequently print the file containing this line on
equipped to handle special characters, the line appears as:
IF A
~
a printer
B THEN
since X'8C' is the hexadecimal value of the special character
Either or both of the operands on the ALTER
hexadecimal or character values. To change the
character, for example <, you could issue either:
~.
subcommand can be
X'8C' to another
alter 8c ae
-- or
alter 8c
<
!~~ Q!~~1!!
~Q~~OM~!!~: The
OVERLAY subcommand allows you to replace
characters in a line by spacing the terminal's typing element or cursor
to a particular character position to make character-for-character
replacements, or overlays. For example, given the line:
ABCDEF
the subcommand:
overlay xyz
results in the line:
XYZDEF
A blank entered on an OVERLAY line indicates that the corresponding
character is not to be changed; to replace a character with a blank, use
an underscore character (_). Given
the above line, XYZDEF, the
subcommand:
overlay
3
results in:
DE3 (The "D" is preceded by blanks in columns 1, 2, and 3.)
70
IBM VM/370 CMS User's Guide
(
You can make global or repetitive changes with the CHANGE and ALTER
subcommands. On these subcommand lines, you can include operands that
indicate:
•
The number of lines to be searched for a character or character
string. An asterisk (*) indicates that all lines, from the current
line to the end of the file, are to be searched.
•
Whether only the first occurrence or all occurrences on each line are
to be modified. An asterisk (*) indicates all occurrences. If you do
not specify an asterisk, only the first occurrence on any line is
changed.
For example, if you are creating a file that uses the
(.) special
character (X'lF') and you do not want to use the ALTER subcommand each
time you need to enter the.,
you could use the character ~ as a
substitute each time you need to enter a e. When you are finished
entering input, move the current line pointer to the top of the file,
and issue the global ALTER subcommand:
toplalter
~
af
**
All occurrences of the character ~ are changed to X'AF'.
line pointer is positioned at the end of the file.
The current
When you use a global CHANGE subcommand, you must be sure to use the
final delimiter On the subcommand line. For examFle:
change /hannible/hannibal/ 5
)
This subcommand changes the first occurrence of the string "HANNIBLE" on
the current line and the four lines immediately following it.
You can also make global changes with the OVERLAY subcommand, by
issuing a REPEAT subcommand just prior to the OVERLAY subcommand. Use
the REPEAT subcommand to indicate how many lines you want to be
affected. For example, if you are editing a file containing the three
lines:
A
B
C
with the current line pointer at line "A", issuing the subcommands:
repeat 3
overlay
results in:
A
B
C
The current line pointer is now
the character "Cu.
positioned at the line
beginning with
)
Section 5. The CMS Editor
71
~
You delete lines from a file with the DELETE subcommand; to delete more
than one line, specify the number of lines:
delete 6
or, if you want to delete all the lines from the current line to the end
of the file, use an asterisk (*):
*
delete
If you want to delete an undetermined number of lines, up to
particular character string, you can use the DSTRING subcommand:
a
dstring /weather/
When this subcommand is entered, all the lines from and including the
current line down to and including the line just above the line
containing the character string "WEATHER" are deleted. The current line
pointer is positioned at the line that has "WEATHER" on it.
If you want to replace a line
REPLACE subcommand:
replace
with another line,
you can
use the
*******
The current line is deleted and the line "*******" is inserted
place. The current line pointer is not moved.
To replace an existing line with many
REPLACE subcommand with no new data line:
new lines, you can
in its
issue the
replace
The editor deletes the current line and enters input mode.
You can insert a single line of data between existing lines using the
INPUT subcommand followed by the line of data you want inserted. For
example:
input
*
this subroutine is for testing only
inserts a single line following the current line. If you want to insert
many lines, you can issue the INPUT subcommand to enter input mode.
You can also add new lines to a file by using the GETFILE subcommand.
This allows you to copy lines from other files to include in the file
you are editing or creating. For example:
getfile single items c
inserts all the lines in the file SINGLE ITEMS C immediately following
the current line pointer. The line pointer is positioned at the last
line that was read in.
72
IBM VM/370 CMS User's Guide
(
You could also specify:
getfile double items c 10 25
to copy 25
ITEMS C.
lines, beginning with the
tenth line, from the
file DOUBLE
The $MOVE and $DUP EDIT macros provide two additional ways of adding
lines into a file in a particular position. The $MOVE macro moves lines
from one place in a file to another, and deletes them from their former
position. For example, if you want to move 10 lines, beginning with the
current line, to follow a line 9 lines above the current line, you can
enter:
$move 10
~p
8
The $OUP macro duplicates the current line a specified number of
times, and inserts the new lines immediately following the current line.
For example:
$dup 3
creates 3 copies of the current line, and
pointer positioned at the last copy.
leaves
the current
line
Describing Data File Characteristics
When you issue the EDIT command to create a new file, the editor checks
the filetype.
If it is one of the reserved filetypes, the editor may
assign particular attributes to it, which can simplify the editing
process for you. The default attributes assigned to most filetypes are
as follows:
•
Fixed-length, 80-character records
•
All alphabetic characters are translated
how they are entered
•
Input lines are truncated in column 80
•
Tab settings are in columns 1, 6, 11,
16, 21, ••• 51, 61, and so on,
and the tab characters are expanded to blanks
•
Records are not serialized
to uppercase, regardless of
The filetypes for some CMS commands and for the language processors
deviate from these default values. Some of the attributes assigned to
files and how you can adjust them to suit your needs are discussed
below.
RECORD LENGTH
You can specify the logical record length
the EDIT command line:
)
of a file you are creating on
edit new file (lrecl 130
Section 5. The CMS Editor
13
If you do not specify
following defaults:
•
•
a record
length,
the
editor assumes
the
For editing old files, the existing record length is used.
For creating new files, the following default values are in effect:
l!l~~YE~
EXEC
FREEFORT
LISTING
SCRIPT
VSBDATA
All others
R~£Q£g 1~ng~h
SO
Sl
121
132
132
SO
characters
characters
characters
characters
characters
Format
VarIable
Variable
Variable
Variable
Variable
Fixed
If you edit a variable-length file and the existing record length is
less than the default for the filetype,
the record length is taken from
the default value.
When you use the LRECL option of the EDIT command you can override
these default record lengths; you can also change the record lengths of
existing files to make them larger, but not smaller.
If you try to override the record length of an existing file and make
it smaller, the editor displays an error message, and you must issue the
EDIT command again with a larger record length. For example, suppose
you have on your B-disk a file named MYFILE FREEFORT, which was created
with the default record length of Sl. If you try to edit that file by
issuing:
edit myfile freefort b (lrecl 72
the editor displays the message:
GIVE A LARGER RECORD LENGTH.
You must then issue the EDIT command again and either
of 81 or more, or allow it to default to the current
the file.
specify a length
record length of
You can use the COPYFILE command to increase or decrease the record
length of a file before you edit it.
For example, if you have
fixed-length, 132-character records in a file, and you want to truncate
all the records at column 80 and create a file with SO-character
records, you could issue the command:
copyfile extra funds a (lrecl 80
The largest record you can edit with the editor is 160 characters. A
file with record length up to 160 bytes
(for example, a listing file
created by a DOS program) can be displayed and edited.
The largest record you can create with the CMS editor, however, is
130 characters using a 3270 display terminal and 134 characters using a
typewriter terminal such as. a 2741 or 1050. If you enter more than 130
characters on a 3270, the record is truncated to 130 characters when you
press the Enter key.
Note that as the line is truncated to 130
characters, the CMS editor will not know the actual line length entered,
and will not issue the "TRUNCATED" messgae. If you type more than 134
characters on a line using a typewriter terminal,' CP generates an
attention interruption to your virtual machine and the input line is
lost when you press the Return key.
74
IBM VM/370 CMS User's Guide
(
For most purposes, you will not need to create records longer than
130 characters.
If it is necessary, however, you can expand a record
that you have entered. You do this by issuing the CHANGE subcommand
with operands, to add more characters to the record (for example, by
changing a 1-character string to a 31-character string).
You cannot create a record that
the file. For example, if the file
length of 80, or if you specified
the editor truncates all records to
is longer than the record length of
you are editing has a default record
LRECL 80 when you created the file~
80 characters.
There is a relationship between the record length of a file and the
maximum number of records it can
contain.
Figure 6 shows the
approximate number of records, rounded to the nearest hundred, that the
editor can handle in a virtual machine with different amounts of virtual
storage.
----,
Virtual Machine Size
Record
Length
)
320K
512K
768K 11024K
80 Characters
1700
3800
6800
9800
120 Characters
1100
2600
4700
6800
132 Characters
1100
2400
4300
6200
160 Characters
900
2000
3600
5100
I
I
I
I
I
I
I
I
I
I
I
----J
Figure 6. Number of Records Handled by the Editor
RECORD FORMAT
with the CMS editor, you can create either fixed- or variable-length
files. Except for the filetypes EXEC, LISTING, FREEFORT, SCRIPT, and
VSBDATA, all the files you create have fixed-length records, by default.
You can change the format of a file at any time during an editing
session by using the RECFM subcommand:
recfm v
This changes the record format to variable-length. This does not change
the record length; in order to add new records with a greater length,
you must write the file onto disk and then reissue the EDIT command
using the LRECL option.
The COPYFILE command also has an RECFM option, so that you can change
the record format of a file without editing it. The command:
copyfile * requests a1 (recfm v trunc
)
changes the record formats of all the files with a filetype of REQUESTS
on your A-disk to variable-length. The TRUNe option specifies that you
want trailing blanks removed from each of the records. When you are
editing a file with variable-length records, trailing blanks are
truncated when you write the file onto disk with the FILE or SAVE
subcommand.
(In VSBDATA files, however, blanks are not truncated.)
Section 5. The CMS Editor
75
USING SPECIAL CHARACTERS
The IMAGE and CASE subcoamands control how data, once entered on an
input line, is going to be represented in a file. The specific
characters
affected,
and
the subcommands
that
control
their
rep~esentation, are:
•
•
•
Alphabetic characters: CASE subcommand
Tab characters (X'05'): IMAGE subcommand (ON and OFF operands)
Backspaces (X'16'): IMAGE subcommand (CANON operand)
If you are using a terminal that has only uppercase characters, you do
not need to use the CASE sUbcommand; all of the alphabetic characters
you enter are uppercase. On terminals equipped with both uppercase and
lowercase letters, all lowercase alphabetic characters are converted to
uppercase in your file, regardless of how you enter them. If you are
creating a file and you want it to contain both uppercase and lowercase
letters you can use the subcommand:
case m
The "M" stands for "mixed." This attribute is not stored with the file
on disk. If you create a new file, and you issue the CASE M subcommand,
all the lowercase characters you enter remain in lowercase. If you
subsequently file the file and later edit it again, you must issue the
CASE M subcommand again to locate or enter lowercase data.
There are two reserved filetypes for which uppercase and lowercase is
the default. These are SCRIPT and MEMO, both of which are text or
document-oriented filetypes. For most programming applications, you do
not need to use lowercase letters.
Logical tab settings indicate the column positions where fields within a
record begin. These logical tab settings do not necessarily correspond
to the physical tab settings on a typewriter terminal.
What happens
when you press the Tab key on a typewriter terminal depends on whether
the image setting is on or off. The default for all filetypes except
SCRIPT is IMAGE ON.
you can change the default by issuing the
subcommand:
image off
If the image setting is on, when you press the Tab key the editor
replaces the tab characters with blanks, starting at the co·lumn where
you pressed the Tab key, and ending at the last column before the next
logical tab setting.
The next character entered after the tab becomes
the first character of the next field. For example, if you enter:
tabset 1 15
and then enter a line that begins with a tab character, the first data
character following the tab is written into the file in column 15,
regardless of the tah stop o~ your terminal.
76
IBM VM/370 CMS User's Guide
(
If the image setting is off, the tab character, X'05', is inserted in
the record, just as any other data character is inserted. No blanks are
inserted.
If you want to insert a tab character (X'05') into
image setting is on, you can do one of the following:
a record and the
1.
Set IMAGE OFF before you enter or edit the record, and then use the
Tab key as a character key.
2.
Enter some other character at the appropriate place in the record,
and then use the ALTER subcommand to alter that character to a
X'05'.
~~TT!!§ !!~~:
When you create a file,
effect, so that you do not need to set
language processors correspond to the
If you want to change them, or if
nonreserved filetype, you may want to
subcommand, for example:
.
there are logical tab settings in
them. The default values for the
columns used by those processors.
you are creating a file with a
set thea yourself. Use the TABSET
tabset 1 12 20 28 72
Then, regardless of what physical tab stops are in effect for your
terminal, when you press the Tab key with image setting ON, the data you
enter is spaced to the appropriate columns.
The default tab settings used by the editor follow.
)
!.!le!y~~
~~!g~!t_!~Q_~~!!!Bg§
AMSERV
2, 6, 11, 16, 21, 26, 31, 36, 41, 46, 51, 61, 71, 80
FORTRAN
1, 7, 10, 15, 20, 25, 30, 80
FREEFORT
9, 15, 18, 23, 28, 33, 38, 81
BASIC, VSBASIC
7, 10, 15, 20, 25, 30, 80
PLIOPT, PLI
2, 4, 7, 10,
79, 80
COBOL
1, 8, 12, 20, 28, 36, 44, 68, 72, 80
All Others
1, 6, 11, 16, 21, 26, 31,
91, 101, 111, 121, 131
ASSEMBLE, MACRO, 1, 10, 16, 31, 36, 41, 46, 69, 72, 80,
UPDATE, UPDTxxxx,
ASM3705
13, 16, 19, 22, 25, 31,
37, 43, 49, 55,
36, 41, 46, 51, 61, 71, 81,
!gl~:
When you are specifying tab settings for files, the first ~ab
setting you specify should be the column in which you want your data to
begin. The editor will not allow you to place data in a column preceding
this one. For example, if you issue:
tabset 5 10 15 20
and then enter an input line:
input This is a line
Columns 1, 2, 3, and 4 contain blanks; text begins in· column 5.
)
Section 5. The CMS Editor
77
For most of your applications, you do not need to underscore or
overstrike characters or character strings.
If you are using a
typewriter terminal and are typing files that use backspaces and
underscores, you should use either the IMAGE OFF or IMAGE CANON
subcommands so that the editor handles the backspaces properly. IMAGE
CANON is the default value for SCRIPT files.
CANON means that regardless of how the characters are keyed in
(characters, backspaces, underscores), the editor orders, or canonizes,
the
characters in
the
file as:
character-backspace-underscore,
character-backspace-underscore, and so on. If, for example, you want an
input line to look like:
You could enter it as:
ABC, 3 backspaces, 3 underscores
- or 3 underscores, 3 backspaces, ABC
A typewriter types out the line in the following order:
A backspace, underscore
B backspace, underscore
C backspace, underscore, which results in:
!~£
If you need to modify a line that has backspaces, and you do not want
to rekey all of the characters, backspaces, and overstrike characters in
a CHANGE or REPLACE subcommand, you can use the ALTER subcommand to
alter all of the backspaces to some other character and use a global
CHANGE command. For example, the following sequences shows how to
delete all of the backspace characters on a line:
AAAAA
alter
16 + 1 *
+A_+A_+A_+A_+A
change /_+// 1 *
AAAAA
This technique may also be useful on a display terminal.
SETTING TRUNCATION LIMITS
Every CMS file that you edit has a truncation column setting: this
column represents the last character position in a record into which you
can ~nter data. When you try to input a record that is longer than the
truncation column, the record is truncated, and the editor sends you a
message telling you that it has been truncated.
You Gan change the truncation
column setting with the TRUNC
subcommand. For example, if you are creating a file with a record length
of 80 and wish to insert some records that do not extend beyond column
20, you could issue the subcommand:
trunc 20
78
IBM VM/310 CMS User's Guide
(
Then, when you enter data lines, any line that is longer than 20
characters is truncated and the editor sends you a message. If you are
entering data in input mode, your virtual machine remains in input mode.
When you use the CHANGE subcommand to modify records, the column at
which truncation occurs is determined by the current zone setting. If
you change a character string in a line to a longer string, and the
resultant line extends beyond the current end zone, you receive the
message:
TRUNCATED.
If you need to create a line longer than the current end zone setting,
use the ZONE subcommand to increase the setting. The subcommand:
zone
1
*
extends the zone to the record length of the file.
If the end zone
already equals the record length, you have to write the file onto disk
and reissue the EDIT subcommand specifying a longer record length.
For most filetypes, the truncation and end'zone columns are the same
as the record length. For some filetypes, however, data is truncated
short of the record length. The default truncation and end zone columns
are:
!il~lI.E~
Column
ASSEMBLE, MACRO
UPDATE,
UPDTxxxx
AMSERV, COBOL,
DIRECT, FORTRAN
PLI, PLIOPT
--~r1--
72
All other filetypes are truncated at their record length.
You can, when creating files for your own uses, set truncation
columns so that data does not extend beyond particular columns.
ENTERING A CONTINUATION CHARACTER IN COLUMN 72
When you are using the editor to enter source records for an assembler
language program
and you need to enter a continuation character in
column 72, or whenever you want to enter data outside a particular
truncation setting, you can use the following technique. Note that this
technique will not work if CANON is specified on the IMAGE subcommand.
1.
Change the truncation setting to 72,
truncate the continuation character:
so that the editor
does not
trunc 72
2.
Use the TABSET subcommand to set the left margin at column 72:
ta-b-s-et 72
3.
Use the OVERLlY subcommand to overlay an asterisk in column 72:
overlay
)
*
Since the left margin is set at 72, the OVERLlY subcommand line
results in the character * being placed in column 72.
Section 5. The CMS Editor'
79
4.
Restore the editor truncation and tab settings:
trunc 71
tabset 1 10 16 31 36 41 51 61 71 81
Note:
If you issue the PRESERVE subcommand before you change the
truncation and tab
settings, then after you
enter the OVERLAY
subcommand, you can restore them with the RESTORE subcommand. See
"Preserving and Restoring Editor Settings."
Use the $MARK Ig!~ ~g£E~: Another way to insert a continuation character
Is-t6-use-the $MARK edit macro. You can find out if the $MARK edit macro
is available on your system by entering, in the CMS or CMS subset
environment:
listfile $mark exec
*
If it is not available on your system, you can create the $MARK edit
macro for your own use. See "Section 17. Writing Edit Macros" in "Part
3. Learriing to Use EXEC."
If you have the $MARK macro, then when you need to enter a
continuation character, you can enter a null line to get into edit mode,
issue the command:
$mark
and then return to input mode to continue entering text.
SERIALIZING RECORDS
Some CMS files that you create are automatically serialized for you.
This means that columns 73 to 80 of each record contain an identifier in
the form:
cccxxxxx
where ccc are the first three characters of the filename and xxxxx is a
sequence number. Sequence numbers begin at 00010 and are incremented by
10.
The filetypes that
are:
ASSEMBLE
DIRECT
MACRO
are automatically serialized in columns
FORTRAN
COBOL
PLI
73 to 80
PLIOPT
UPDATE
UPDTxxxx
You can serialize any file that has
records by using the SERIAL subcom~and:
fixed-length,
80-character
serial on
The SERIAL subccmmand can also be used to:
•
Assign a particular three-character identifier:
serial abc
(
80
IBM VM/370 CMS User's Guide
•
Specify that all eight bytes of the sequence field be used to contain
numbers:
serial all
•
Specify a sequence increment other than 10:
serial on 100
-- or -serial ccc 100
•
Indicate that no
being inserted:
sequence numbers are to be assigned
to new records
serial off
When you create a file or edit a file with sequence numbers, the
sequence numbers are not written or updated until you issue a FILE or
SAVE subcommand. Because the end verification columns for the filetypes
that are automatically serialized are the same as their truncation
columns, you do not see the serial numbers unless you specify:
verify
*
-- or -verify 80
Although the serial numbers are not displayed while you
they do appear on your output listings or printer files.
edit the file,
If you are editing files with the following filetypes:
BASIC
VSBASIC
FREEFORT
the sequence numbers are on the left. For BASIC and VSBASIC files,
columns 1-5 are used; numbers are blank-padded to the left.
For
FREEFORT files, the
sequence numbers use columns
l-S, and are
zero-padded to the left. To edit these files, you should use line-number
editing, which is discussed next.
LINE-NUMBER EDITING
To edit a file by line numbers means that when you are adding new lines
to a file or referencing lines that you wish to change, you refer to
them by their line, or sequence numbers, rather than by character
strings.
You can use right line-number editing only on files with
fixed-length, SO-character records.
If you want to edit by line numbers, issue the subcommand:
linemode right
-- or -linemode left
)
Section 5. The eMS Editor
81
where "right" indicates that the sequence numbers are on the right, in
columns 76-80, and "left" indicates you want sequence numbers on the
left in columns 1-5. LINEMODE LEFT is the default for BASIC, VSBASIC,
and FREEFORT files.
You do not have to specify it. You must· specify
LINEMODE for files with other filetypes.
If you specify LINEMODE RIGHT to use line-number editing on a
typewriter terminal, the line numbers are displayed on the left, as a
conve~ience, while you edit the file.
When you are using line-number editing in input mode, you are
prompted to enter lines; the line numbers are in increments of 10. For
example,.when you are creating a new file, you are prompted for the
first 11ne number as'follows:
10
On a typewriter terminal, you enter your input line following
When you press the carriage return, you are prompted again:
the 10.
20
and you continue
line.
entering lines in this
Yo~ can change the prompting increment
with the PROMPT subcommand:
manner until you enter
a null
to a larger or smaller number
prompt 100
When you are
number:
in edit mode you can
locate a line by
giving its line
7'00
This is the nnnnn subcommand. In line-number editing, you use it instead
of the INPUT subcommand to insert a single line of t~xt. For example:
905 x = a
*
b
inseris the text line "X = A * B" in the proper sequence in the file.
If you use "nnnnn text" specifyin~ the number of a line that already
exist~, that
line is replaced; the current line pointer is mbved to
point to it.
The EDIT subcommands that you normally us~ for context editing, such
as CHANGE, ALTER, LOCATE, UP, DOWN, and so forth, can also be used when
you are line-number editing; their ope~ation does not change.
RENUM~IRING
LINES
When you are using line-number editing, the editor uses the prompting
increment set by the PROMPT subcommand. However, when you begin adding
lines Of data between existing lines, the editor uses an algorithm to
s~lect ~ line number
between the current line number and the next line
number. If a prompting number cannot be generated becaus~ the current
line number and the next line number differ only by one, the editor
displays the message:
RENUMBER LINES
and you must resequence the line numbers
continue line-number editing.
82
I·Bli VM/370 CMS User's Guide
in the
file before
you can
(
You can resequence the line nu.bers in one of three ways:
1.
If you are
subcommand:
a VSBASIC
or FREEFORT
user,
you may
references
to
use the
RERUM
renum
This subcommand
renumbered.
2.
all
resolves
lines
that
are
If you are using right-handed line-number editing, you must:
a. Turn off line-number editing:
linemode off
b. If you want to change the three-character identifier or specify
eight-character sequence numbers, issue the SERIAL subcommand,
for example:
serial all
If you want to use the default serialization setting, you do not
need to issue the SERIAL subcommand.
c. Issue the SAVE subcommand:
save
d. Reissue the
editing:
)
LINE MODE
subcommand
and
continue
line-number
linemode right
3.
If you are using left-handed ~ine-number editing for a filetype
other than VSBlSIC or FREEFORT, you must manually change individual
line numbers using EDIT subcommands. In order to modify the line
numbers, you must change the zone setting and the tab setting:
*
zone 1
tabset 1 6
so that you can place data in columns 1 through 6.
When you are using right-handed line-number editing, and a FILE,
SAVE, or automatic save request is issued, the editor does not
resequence the serial numbers, but displays the message:
RESERIALIZATION SUPPRESSED
so that the lines numbers that are currently saved on disk match the
line numbers in the file. You must cancel line-number editing (using the
LINEMODE OFF subcommand) before you can issue a FILE or SAVE subcommand
if you want to update the sequence numbers.
)
Section 5. The CMS Editor
83
Controlling the Editor
There; are a number of EDIT subcommands that you can use to maximize the
use of the editor in CMS. A few techniques are suggested here; as you
becomecmore familiar with VM/370 and C!S you will develop additional
techniques for your own applications.
COMMUNICATING WITH CMS AND CP
Often during a terminal session, you may need to issue a CMS command or
a CP command. You can issue certain CMS commands and most CP commands
without terminating the edit session.
The EDIT subcommand CMS places
your virtual machine in the CMS subset mode of the editor, where you can
issue CMS commands that do not modify your virtual storage. Remember
that the editor is using your virtual storage; if you overlay it with
any other command or program, you will not be able to finish your
editing.
One occasion when you may want to enter CMS subset is when you want
to issue a GET FILE subcommand for a file on one of your virtual disks
and you have not accessed the disk. You can enter:
cms
The editor responds:
CMS SUBSET
Then you can enter:
access 193 b/a
return
get setup script b
The special
edit mode.
CMS SUBSET command RETURN
returns your virtual
machine to
You can enter CP commands from CMS subset, or you can issue them
directly from edit mode or input mode with the ICP function. Fer
example, if you are inputting lines into a file and another user sends
yeu a me~sage, you can reply without leaving input mode:
#cp m oph i will call you later
If you enter
message:
tcp without specifying a command line,
you receive the
CP
which indicates that your virtual machine is in the CP command
enviranment, and you can issue CP cammands.
You would nat, hawever,
want to issue any CP command that would modify your virtual storage er
alter the status of the disk on which you ~ant to. write the file.
To return to edit or input mode from CP, use the CP cammand, BEGIN.
If you are working at a display terminal and the screen image does net
reappear, enter the TYPE command to. cause the editor to redisplay the
screen:. '
c
84
l'BM VM/370 CMS User's Guide
March 30, 1919
CHANGING FILE IDENTIFIERS
There are several methods you can use to change a file identifier before
writing the file onto disk. You can use the FNAHE and FMODE subcommands
to change the filename or filemode, or you can issue a FILE or SAVE
subcommand specifying a new file identifier~
For example, if you want to create several cOfies of a file while you
are using the editor, you can issue a series of FNAME subcommands,
followed by SAVE subcommands, as follows:
edit test file
EDIT:
fn test11save
fn test21save
fn test3ifile
Or, you could issue the SAVE and FILE subcommands as follows:
edit test file
save test1
save test2
file test3
In both of the preceding examples, when the FILE subcommand is executed,
there are files named TEST FILE, TEST1 FILE, TESi2 FILE, and TEST3 FILE.
The original TEST FILE is unchanged.
To change the filemode letter of a disk, use the FMODE subcommand.
You can do this in cases where you have begun editing a file that is on
a read-only disk, and want to write it. Since you cannot write a file
onto a read-only disk, you can issue the FMODE subcommand to change the
mode before filing it:
fmode a
file
Or, you can use the FILE (or SAVE) subcommand specifying a complete file
identifier:
file test file a
You should remember, however, that when you write a file onto disk,
it replaces any existing file that has the same identifier.
The editor
does not issue any warning or informational messages.
If you are
changing a file identifier while you are editing the file,
you must be
Section 5. The CMS Editor
85
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
careful that you do not unintentionally overlay
verify the existence of a file, you can enter ces
STATE or LISTFILE commands.
existing files.
To
subset and issue the
CONTROLLING THE EDITOR'S DISPLAYS
When you are using a typewriter terminal, you may not always want to see
the editor verify the results of each of your subcommands. Particularly
when you are making global changes, you may not want to see each line
displayed as it is changed. You can issue the VERIFY suhcommand with
the OFF operand to instruct the editor not to display anything unless
specifically requested. After you issue:
verify off
lines that are normally displayed as a result of a subcommand that moves
the current line pointer (UP, DOWN, TOP, BOTTOM, and so forth), or that
changes a line (CHANGE, ALTER, and so forth), are not displayed. If the
current line pointer moves to the end of the file, however, the editor
always displays the EOF: message.
If you are editing with verification
off, then you must be
particularly careful to stay aware of the position of your current line
pointer. You can display the current line at any time using the TYPE
subcommand:
type
~~Dg g~g
~h~~! ~~!g~
~~§§ag~§:
while you are using the editor,
error message:
When you enter an invalid subcommand
the editor normally responds with the
?EDIT: line •••
displaying the line that it did not recognize. If you prefer, you can
issue the SHORT subcommand so that instead of receiving the long form of
the error, you receive the short form, which is:
When you issue an invalid edit macro
a $), you receive the message:
request (any line that begins with
To resume receiving the long form of
subcommand:
the error message, use the LONG
long
LONG and SHORT control the display of the error message regardless of
whether you are editing with verification on or off~
On a display terminal, all EDIT messages that are displayed at the
top of the screen, including error messages and '?EDIT:' messages, are
highlighted.
86
IBM VM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-IX8
PRESERVING AND RESTORING EDITOR SETTINGS
The PRESERVE and RESTORE subcommands are used together; the PRESERVE
subcommand saves the settings of the EDIT subcommands that control the
file format, message and verification display, and file identifier. If
you are editing a file and you want to temporarily change some of these
settings, issue the PRESERVE subcommand to save their current status.
When you have finished your temForary edit project, issue the RESTORE
subcommand to restore the settings.
Section 5. The eMS Editor
86.1
March 30, 1979
86.2
IBM VM/370 eMS User's Guide
For example, if you are editing a SCRIPT file and want to change the
image setting to create a particular format, you can enter:
preserve
image on
tabset 1 15 40 60 72
zone 1 72
trunc 72
When you have finished entering data using these settings, you can issue
the subcommand:
restore
to restore the default settings for SCRIPT filetypes.
x,
I, =, ? SUBCOMMANDS
The X, I, =, and 1 subcomaands all perform very simple
can help you to extend the language of the CMS editor.
to manipulate, reuse, or interrogate EDIT subcommands.
functions that
They allow you
If you have an editing project in which you have to execute the same
subcommand a number of times, you can assign it to the X or Y
subcommands, as follows:
x locate /insert here/
y getfile insert file c
Each time that you enter the X subcoamand:
)
x
the command line LOCATE IINSERT HERE/
enter the Y subcommand:
is executed, and every
time you
y
the GETFILE subcommand is executed.
When you specify a number following an X or I subcommand, the
subcommand assigned to X or Y is executed the specified number of times;
for example:
x locate
x 10
laal
the LOCATE subcommand line is
another EDIT subcommand.
=
executed 10
times before you
can enter
Another method of re-executing a particular subcommand is to use the
(REUSE) subcommand. For example, if you enter:
locate lardl
AARDVARK
=======
the LOCATE subcommand is re-executed seven times.
What the = (REUSE)
subcommand actually does is to stack the
subcommand in the console stack. Since CMS, and the editor, read from
the console stack before reading from the terminal, the lines .in the
Section 5. The CMS Editor
81
stack execute before a read request is presented to the terminal. When
you enter multiple equal signs, the subcommand is stacked once for each
equal sign you enter.
You can also stack an additional EDIT subcommand
following an equal
sign. The subcommand line is also stacked, but it is stacked LIFO
(last-in, first-out) so that it executes before the stacked subcommand.
For example, if you enter:
delete
= next
a DELETE subcommand is executed, then a DELETE subcommand is stacked,
and a NEXT subcommand is stacked in front of it. Then the stacked lines
are read in and executed. The above sequence has the same effect as if
you enter:
delete
next
delete
In addition to stacking the last
find out what it was, using the?
enter:
subcommand executed, you can also
subcommand. For example, if you
next 10
?
the editor displays:
NEXT 10
since the subcommand line NEXT 10 was the last subcommand entered, if
you enter an = subcommand, it is executed again. You cannot stack a ?
subcommand.
!Qte: The ? subcommand, on a display terminal,
subcommand into the user input are~, where you
re-entering it.
copies the
may modify
last EDIT
it before
WHAT TO DO WHEN YOU RUN OUT OF SPACE
There are two situations that may prevent you from continuing an edit
session or from writing a file onto disk. You should be aware of these
situations, know how to avoid them, and how to recover from them, should
they occur.
When you issue the EDIT command to edit a file, the editor copies the
file into virtual storage. If it is a large file, or you have made many
additions to it, the editor may run ont of storage space. If it does, it
issues the message:
AVAILABLE STORAGE IS NOW FULL
When this happens, you cannot make any changes or additions to the file
unless you first delete some lines. If you attempt to add a line, the
editor issues the message:
NO ROOM
If you were entering data in input mode, your virtual machine
returned to edit mode, and you may receive the message:
88
IBM VM/370 CMS User's Guide
is
(
STACKED LINES CLEARED
which indicates that any a~ditional lines
will not be processed.
you entered are
cleared and
You should use the FILE subcommand to write the file onto disk. If
you want to continue editing, you should see that the editor has more
storage space to work with. To do this, you can find out how large your
virtual machine is and then inctease its size. To find out the size,
issue the CP QUERY command:
cp query virtual storage
If the response is:
STORAGE =
256K
You might want to redefine your storage
DEFINE, as follows:
to 512K.
Use the
CP command
cp define storage 512k
This command resets your virtual machine, and you must issue the CP IPL
command to reload the CMS system before you can continue editing.
If a file is very large, the editor may not have enough
allow you to edit it using the EDIT command. The message:
space to
DMSEDI132S FILE 'fn ft £m' TOO LARGE
)
indicates that you must obtain more storage space before you can edit
the file. If this is the case, or if you are editing large files, you
should" redefine your storage before beginning the terminal session. If
this happens consistently, you should see your installation support
personnel about having the directory entry for your userid updated so
that you have a large storage size to begin with.
If the file you are editing is too large, and the data it contains does
not have to be in one file, you can split the file into smaller files,
so that it is easier to work with. Two of the methods you can use to do
this are described below.
~2~
1h~ ~QR!~!1~
Command: You can use the COpy FILE command to copy
portions of a file Into-s~parate files, and then delete the copied lines
from the original file. For example, if you have a file named TEST FILE
that has 1000 records, and you want to split it into four files, you
could enter:
copyfile
copy file
copyfile
copy file
test
test
test
test
file
file
file
file
a
a
a
a
test1
test2
test3
test4
file
file
file
file
a
a
a
a
(from
(from
(from
(from
1 for 250
251 for 250
501 for 250
751 for 250
When these COPYFILE commands are
complete, you have four files
containing the information from the original TEST FILE, which you can
erase:
erase test file
o
Q2~ 1h~
Ed!12f: If you use the editor to create smaller files, you can
edit them as you copy them, that is, if you have other changes that you
Section 5. The CMS Editor
89
want to make to the data. To copy files with the editor, you use the
GETFILE subcommand. Using the file TEST FILE as an example, you might
enter:
edit test1 file
get file test file a 1 250
file
edit test2 file
~~tfile test file a 251 250
Again, you could erase the original TEST
your edit session.
FILE when you are through with
When you enter a FILE or SAVE subcommand or when an automatic save
request is issued, the editor writes a copy of the file you are editing
onto disk, and names it EDIT CMSUT1. If this causes the disk to become
full, you receive the message:
DMSBWR170S DISK 'mode (cuu) , IS FULL
The edi'tor erases the workfile, and issues the message:
SET NEW FILEMODE, OR ENTER CMS SUBSET AND CLEAR SOME SPACE
The original file (as last written onto disk) remains unchanged. You
can tis~ the CMS subcommand to enter CMS subset, and erase any files that
you do not need. You can use the LISTFILE command to list the files on
the disk, then the ERASE command to erase the unwanted files.
If you cannot erase any of the files on the
alternate recovery paths you can take:
disk, there are several
1.
If you have another read/write disk accessed, you can use the FMODE
subcommand to change the filemode of the file, so that when you
file it, it is written to the other disk. If you have a read/write
disk that is not accessed, you can access it in CMS subset. After
filing the file on the second disk, erase the original copy, and
then use the COPYFILE command to transfer the file back to its
original disk.
2.
If you do not have any other read/write disk in your virtual
machine, you may be able to transfer some of your files to another
user, using the PUNCH or DISK DUMP commands in CMS subset. When the
files have been read onto the other user's disk, you can erase them
from your disk.
Then, return to edit mode and issue the FILE
subcommand.
3.
In CMS subset, erase the original
return to edit mode and file the
should not use this method unless
unexpected problems may result in
and the copy.
disk file (if it existed), then
copy that you are editing. You
absolutely necessary, since any
the loss of both the disk file
After you use the FILE subcommand to write the file onto
should continue erasing any files you no longer need.
90
l~~ VM/370 CMS User's Guide
disk, you
(
Summary of EDIT Subcommands
The EDIT subcommands, and their formats, are shown in Figure 7. Refer to
the !!1L.lIQ ~!t~~g.!!1!!~!!g ~!!g ~~£!:.Q !!~!~!:!H!£~ for complete details.
Function
Subcommand Format
r
ALter char1 char2
L
r
,
L
.J
,
I n r
,
I
I * I G I I
I 1 I * I I
.J
L
IAutomatically saves the file
Ion disk after the indicated
Inumber of lines have been
I processed •
AUTOsave In I
IOFFI
r
,
L
.J
IPoints the current line
Ipointer to a line above the
Iline currently pointed to.
BAckward I nl
I 11
I
Bottom
IMakes the last line of the
Ifile the current line.
r
,
L
.J
IIndicates whether translation
Ito uppercase is to be done, or
Idisplays the current status.
I
CASE 1 M I
I U I
)
Change
r "
I Changes string 1 to string2 for
In IGII ]]]I!! records or to EOF, either
Ifor the first occurrence in
11 1*11
L
L .J.J
I each line or for all
I occurrences.
r
[/string~/string2[1
CMS
IEnters CMS subset command
Imode.
r
,
DELete 1 n I
1
*
I
I 1 1
L
r
.J
,
DOwn I n 1
I 1 I
L
)
.J
IScans the next n records of
Ithe file, alterIng the speciIfied character, either once in
leach line or for all occurIrences in the line.
.J
IDeletes n lines or to the end
lof the file (*).
I
I
1
IPoints to the nth line from
Ithe current line.
I
I
DString I[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.
Figure 7.
Summary of EDIT Subcommands and Macros (Part 1 of 4)
Section 5. The CMS Editor
91
--------------------------------------------------,
Function
I
Subcommand Format
~--~~----------------------------------------------------------------------I
Find I line]
ISearches the file for the
Igiven line.
I
I
FMode [fm]
IResets or displays the
Ifilemode.
I
----------------------1I
IResets or displays the
Ifilename.
FName [fn]
ISwitches the 3270 terminal
Ibetween display mode and line
Imode. (3270 only)
r
,
L
~
IPoints to the nth line after
Ithe current line.
FOrward I n I
I 1 I
I
I
r
r
r
r
, , ,,
L
L
L
L
~
Getfile fn I ft I fm I m I n I I I I
I
I
I 1 I -* I I I I
,
r
I
IInserts a line in the file or
lenters input mode.
Inpu,t [line]
,
LINEmode ILEFT I
IRIGHTI
IOPF I
~
L
.J
I
I
I
.J
r
~
IExpands text into line images
lor displays current settings.
IMAG'E ION
I
IOPF I
ICANONI
L
~
IInserts a portion or all of
Ithe specified file after the
Icurrent line.
ISets or displays current
Isetting of line-number
lediting.
I
I
[Locate]/[string [I]]
IScans file from next line for
Ifirst occurrence of 'string'.
LONG
IEnters long error message
Imode.
r
IRoints to the nth line down
Ifrom the current line.
,
Next I n I
I 1 I
L
I
I
.J
Over-lay [line]
IReplaces all or part of the
Icurrent line.
PREserve
ISaves current mode settings.
r
,
PROMPT In I
11QI
L
Figure 7.
.J
ISets or displays line number
lincrement. Initial setting is
110.
I
Summary of EDIT Subcommands and Macros (Part 2 of 4)
(
92
IBM VM/370 CMS User's Guide
r
Subcommand Format
QUIT
Function
ITerminates edit session with
Ino updates incorporated since
Ilast save request.
r
,
L
.J
ISets or displays record format
Ifor subsequent files.
RECfm I F I
I V I
I
I
r
r
L
L
RENum Istrtno I incrno "II
11Q
1§!f!!tQ II
r
.J.J
*
L
I
I Executes the following OVE:a. LAY
Isubcommand n times.
,
REPEAT I n I
I
I
IRecomputes line numbers for
IVSBASIC and FREEFORT source
Ifiles.
I
I
I
I
1 I
.J
Replace [line]
IReplaces the current line or
Ideletes the current line and
lenters input mode.
REStore
,Restores editor settings to
Ivalues last preserved.
RETURN
IReturns to edit environment
Ifrom CMS subset.
.~
[ subcommand]
)
IStacks (LIFO) the last EDIT
Isubcommand that does not start
Iwith REUSE or the question
Imark (1) and then execute~ any
Igiven EDIT subcommand.
SAVE [fn eft [fm]]]
r
ISaves the file on disk and
Istays in edit environment_
IDisplays a number of screens
lof data above or below the
Icurrent line (3270 only) •
,
SCroll
} 1n I
{ S[ croll ]U[ p] 1* I
11 1
L
SERial { OFF r
,
ON liner,
ALL I 10 I
seq L
.J
SHORT
J
ITurns serialization on or off
lin columns 73 through 80.
I
I
IEnters short error message
Imode.
r
,
STACK I
n
I
I
1
I
101
Isubcommandl
L
)
I
I
.J
Figure 7.
.J
IStacks data lines or EDIT
Isubcommands in the console
linput stack.
I
I
I
Summary of EDIT Subcommands and Macros (Part 3 of 4)
Section 5. The CMS Edit 3
PRINT PILE&X TEST
SX = SX + 1
-ENDPRT
In both of these examples, a loop is established to print the files
FILE1 TEST, FILE2 TEST, and PILE3 TEST..
SX is initialized with a value
of 1 and then incremented within the loop. The loop executes until the
value of SX is greater than 3. As soon as this condition is met, control
is passed to the label -ENDPRT.
COMPARING VARIABLE SYMBOLS AND CONSTANTS
In an EXEC, you can test whether a certain condition is true, and then
perform some function based on the decision. Some examples have already
appeared in this section, such as:
)
SLOOP 3 SX EQ SY
In this example, the value of the variable SX is tested for an equal
comparison with the value of the variable SY. The loop is executed until
the condition (SX equal to SY) is true.
The logical comparisons you can make are:
Condition
equiI---not equal
greater than
less than
greater than
or equal to
less than or
equal to
~!l~!.Q!l!£
2I!12~!
GE
>=
LE
<=
EQ
NE
GT
LT
=
... =
>
<
a
When you are testing
condition in an EXEC file, you can use either the
mnemonic or the symbol to represent the condition:
SIF SA LT SB SGOTO -NEXT
is the same as:
SIP &A < SB SGOTO -NEXT
)
section 6. Introduction to the EXEC Processor
105
DOING I/O WITH AN EXEC
You can communicate with your terminal using the STYPE and SREAD control
statements. Use STYPE to display a line at your terminal:
STYPE ASMBLNG Sl ASSEMBLE
When this line is processed, if the
the line is displayed as:
variable Sl has a
value of PROG1,
ASMBLNG PROGl ASSEMBLE
Use the SREAD control statement when you want to be able to enter
data, variables, or control statements into your EXEC file while it is
executing. If you use it with an STYPE statement, for exa~ple:
STYPE DO YOU WANT TO CONTINUE ?
SREAD VARS SANS
you could test the variable SANS in your EXEC to find out how processing
is to continue.
The SBEGTYPE control statement can be followed by a sequence of lines
you want to be displayed at the terminal. For example, if you want to
display ten lines of data, instead
of using ten STYPE control
statements, you could use:
SBEGTYPE
linel
line2
linel0
SEND
The SEND control state.ent indicates the end of the lines to be typed.
You can also use the SBEGTYPE control statement when you want to type a
line that contains a word with more than eight characters in it; for
example:
SBEGTYPE
TODAY IS WEDNESDAY
SEND
The EXEC interpreter, however, does not perform
entered this way_ The lines:
substitutions on lines
SA = DOG
SBEGTYPE
MY SA IS NAMED FIDDLEFADDLE
SEND
result in the display:
MY SA IS NAMED FIDDLEFADDLE
You must use the STYPE statement when you want to display variable data;
you must use the SBEGTYPE control statement to display words with more
than eight characters.
To type null or blank lines at your terminal (to make output
readable, for example), you can use the SSPACE control statement:
SSPACE 5
106
IBM VM/370 CMS User's Guide
(
You can punch lines of tokens into
&PUNCH control statement:
your virtual
card punch
with the
&PUNCH &NAME &TOTAL
When you want to punch more than one line of data, or a line that
contains a word of more than eight characters in it, you should use the
&EEGPUNCH control statement preceding the lines you want to punch, and
follow them with an &END statement~
The EXEC processor does not
interpret these lines, however, so any variable symbols you enter on
these lines are not substituted.
When you punch lines from an EXEC procedure what you are actually
doing is creating a file in your virtual card punch. To release the
file for processing, you must close the punch:
cp close punch
The destination of the file depends on how you have spooled your punch.
If you have spooled it to yourself, the file is placed in your virtual
card reader, and you can read it onto a virtual disk using the READCARD
command.
)
The EXEC control statements &STACK and &BEGSTACK allow you to stack
lines in your terminal console, to be executed as soon as a read occurs
in your virtual machine. Stacking is useful when you use commands that
require responses, for example, the SORT command:
&STACK 1 20
SORT INFILE FILE A OUTFILE FILE A
-
When the SORT command is executed, a prompting message is issued, the
virtual machine read occurs, and the response that you have stacked is
read.
If you do not stack a response to this command, your EXEC does
not continue processing until you enter the response from your terminal.
In the above example of the SORT command, you can suppress the
prompting message by issuing the &STACK HT command immediately before
the SORT command.
Restore normal terminal operations by placing an
&STACK RT command after the SORT command.
Stacking is useful
EXEC procedures.
in creating edit macros or in
editing files from
MONITORING EXEC PROCEDURES
Two EXEC control statements, &CONTROL and &TIME, centrol how much
information is displayed at your terminal while your EXEC file is
executing. This display is called an execution summary.
)
Since you do not usually receive a C8S ready message after the
execution of each CMS command in an EXEC, you do not receive the timing
Section 6. Introduction to the EXEC Processor
107
information that is provided with the ready message. If you
timing information to appear, you can specify:
want this
STIME ON
or you can type the CPU times at particular places by using:
STIME TYPE
The SCONTROL control statement allows you to specify whether certain
lines or types of information are displayed during execution.
By
default, CP and CMS commands are displayed before they are executed. If
you do not wish to see them displayed, you can sFecify:
SCONTROL OFF
You might find it useful, when you are debugging your EXECs, to use:
SCONTROL ALL
When you use this fora, all EXEC statements, as well as all CP and CMS
commands, are displayed and you can see the variable substitutions being
performed and the branches being taken in a procedure.
(
108
IBM VM/370 CMS User's Guide
Summary of EXEC Control Statements and Special
Variables
Figures 9
variables.
and
10
summarize
EXEC
control
Control Statement
statements
and
special
,
Function
I
~------------------------------------------------~--------------------I
&variable
IAssigns a value to the symbol I
Ispecified by &variable; the
I
lequal sign must be preceded
I
land followed by a blank.
xxxxxx)
I
------------------------------------------~------------------~----I
= ~i::::~oJ
{X'
&ARGS [arg1 [arg2 ••• [arg30]]]
IRedefines the variable symbolsl
1&1, &2~ •• with the values of I
l'arg1', 'arg2', ••• , and re- I
Isets the variable &INDEX.
I
--------------------------------------------------------------------1
, SBEGEMSG [ALL]
IDisplaysthe following lines I
line1
line2
)
las CMS error messages, without
Iscanning them.
SEND
I
I
I
SBEGPUNCH [ ALL]
line1
line2
IPunches the following lines
lin the virtual card punch,
Iwithout scanning them.
SEND
I
I
I
&BEGSTACK
line1
line2
r
,
L
.J
r
,
111lQI IALLI
.J
ILIFOI L
IStacks the following lines
lin the console input buffer,
Iwithout scanning them.
SEND
I
I
I
I
&BEGTYPE [ALL]
line1
line2
IDisplays the following lines
lat the console, without
Iscanning them.
&END
I
I
I
SCONTINUE
Figure 9.
IProvides a branch address for
ISERROR, SGOTO, and other conIditional branching statements.
Summary of EXEC Control Statements (Part 1 of 3)
)
Section 6. Introduction to the EXEC Processor
109
r
I
Control Statement
Punction
I--~-------------------------------------------------------------------I &CONTROL
ISets, until further notice,
Ithe characteristics of the
I
r
,r
,r
,r
,
10 PP 1 111~~ I I TIM E I I PA£! I
IERRORI INOMSGI I!QI!11! 1 INOPACKI
I £11~
IALL
I
I
L
.I
L
.I
L
L
..
lexecution summary of the EXEC,
Iwhich is displayed at the
Iconsole.
I
I
.I
&EMSG mmmnnns [tok1 [ ••• tokn]]
IDisplays a line of tokens
las a CMS error message.
&END
ITerminates a series of lines
Ifollowing an SEEGEMSG,
'SBEGPUNCB, &BEGSTACK, or
ISBEGTYPE control statement.
r
,
SERROR I executable-statement I
I!£Q!!!!UE
I
L
.I
r
,
&EIIT I return-code I
I
~
I
.I
L
&GOTO {TOP
}
linenumber
-label
&HEI {ON}
IExecutes the specified
Istatement whenever a. CMS
Icommand returns a nonzero
Ireturn code.
IExits fro. the EIEC file with
Ithe given return code.
I
I
ITransfers control to the top
lof the EIEC file, to the given
Iline, or to the line starting
Iwith the given label.
ITurns on or off hexadecimal
I conversion.
{OPI}
tok2 } executable&$
statement
{ &*
Executes the specified
statement if the condition is
satisfied.
=
<
<=
>
>=
&LOOP { n
}{ m
}
-label
condition
ILoops through the following ~
Ilines, or down to (and includ-I
ling) the line at label, for
I
1m times, or until the
I
Icondition is satisfied.
I
--------------------------------------------------------------------1
&PUNCH [tok1 [ ••• tokn]]
IPunches the specified tokens I
Ito your virtual card punch.
I
J
Figure 9.
Summary of EIEC Control Statements (Part 2 of 3)
(
110
IBM YM/370 CMS User's Guide
Control Statement
Function
,
r
&READ In
I
I
11
IARGS
I
IVARS [ &var1 ( ••• &var11])1
L
&SKIP
.J
r
,
L
.J
r
,
L
.J
ITransfers control forward or
Ibackward a specified number
lof lines.
I n I
I 1 I
I
IDisplays blank lines at the
Iterminal.
&SPACE I n I
I 1 I
r
I
I
,
r
&STACK II!IQI Itok1 (
ILIFOI IHT
.J
L
IRT
...
L
r
)
,
,
IStacks a line in the terminal
linput stack.
I
I
I
IDisplays timing information
Ifollowing the execution of
ICMS commands.
I
I
I
.J
&TYPE [ tok 1 ( ••• tokn ] ]
Figure 9.
,
tokn] I
I
I
.J
&TII! ION
IQII I
,RESETI
ITYPE I
L
IReads lines from the terminal
lor from the console stack.
IARGS assigns the tokens read
Ito the variables &1, &2 •••
IVARS assigns the tokens read
Ito the specified variable
Isymbols.
IDisplays a line at the
Iterminal.
Su •• ary of EXEC Control Statements (Part 3 of 3)
)
Section 6. Introduction to the EXEC Processor
111
Usage
Variable
Set By
&n
Arguments passed to an EXEC are assigned to
the variables &1 through &30~
User
&*
&$
Test whether all (&*) or any (&$) of the
arguments passed to EXEC have a particular
value.
EXEC
&DISKx
Indicates whether the disk access at mode 'x'
is a CMS OS, or DOS disk, or not accessed
(CMS, OS, DOS, or NA).
User
&DISK*
Contains the mode letter of the first read/write
disk in the CMS search order, or NONE if no
read/write disk is accessed.
User
&DISK?
Contains the mode letter of the read/write disk
with the most available space or NONE, if no
read/write disk is accessed.
User
&DOS
Indicates whether or not the CMS/DOS environment
is active (ON or OFF).
User
&EXEC
Contains the filename of the EXEC file currently I
being executed.
EXEC
&GLOBAL
Bas a value ranging from 1 to 19, to indicate
the recursion (nesting) level of the EXEC that
is currently executing.
EXEC
&GLOBALn
The variables &GLOBAL1 through &GLOBAL9 can
contain integral numeric values, and can be
passed among different recursion levels. If
not explicitly set, the variable will have a
value of 1,.
User
&INDEX
Contains the number of arguments passed to
the EXEC on the command line or the number of
arguments entered as a result of an &ARGS or
&READ ARGS control statement.
EXEC
&LINENUM
Contains the current line number in the EXEC.
EXEC
&READFLAG
Indicates whether (STACK)
or not (CONSOLE)
there are lines stacked in the terminal input
buffer (console stack).
EXEC
&RETCODE
Contains the return code from the most recently
executed CMS command.
CftS
&TYPEFLAG
Indicates whether (RT) or not (BT) output is
being displayed at the console.
EXEC
Contains the name of the EXEC file.
User
I
I &0
"1
1----------------------------------------------------------------------I!!U:
IUser: Variables are assigned values by EXEC but you may modify them.
IJ;XEC: You may not modify these variables.
You may assign a value to this variable but it is reset at the
I~MS:
completion of each CMS command.
I
I
Figure 10. EXEC
112
~pecial
Variables
IBMVM/370 CMS User's Guide
(
Section 7. Using Real Printers, Punches,
Readers, and Tapes
eMS Unit Record Device Support
CMS supports one virtual card reader at address OOC, one virtual card
punch at address OOD, and one virtual printer at address OOE. When you
invoke a CMS command or execute a program that uses one of these unit
record devices, the device must be attached at the virtual address
indicated.
USING THE CP SPOOLING SYSTEM
Any output that you direct to your virtual card Frinter or punch, or any
output you receive through your card reader, is controlled by the
spooling facilities of the control program
(CP). Each output unit is
known to CP as a spool file, and is queued for processing with the spool
files of other users on the VM/370 system.
Ultimately, a spooled
printer file or a spooled punch file may be released to a real printer
or card punch for printing or punching.
The final disposition of a unit record spool file depends on the
spooling characteristics of your virtual unit record devices, which you
can alter with the CP command
SPOOL. To find out the current
characteristics of your unit record devices you can issue the command:
cp query ur
You might see, as a response to this, the display:
RDR
PUN
PRT
OOC
OOD
OOD
OOE
OOE
CL A NOCONT
CL A NOCONT
FOR CMSGDE
CL A
CONT
FOR CMSGDE
NOHOLD
EOF
NOHOLD COpy 01
DIST 13SCRIPT
HOLD COpy 01
DIST 13SCRIPT
READY
REAtY
READY
Some of these characteristics, and the ways you can modify them, are
discussed below.
When you use the SPOOL command to control a virtual
unit record device, you do not change the status of spool files that
already exist, but rather set the characteristics for subsequent output.
For information on modifying existing spool files, see "Altering Spool
Files," below.
£1AS~
(CL): Spool files,
in the CP spool file queue, are grouped
according to class, and all files of a particular class may be processed
together, or directed to the same real output device. The default
values for your virtual machine are set in your VM/370 directory entry,
and are probably the standard classe$ for your installation.
You may need, however, to change the class of a device if you want a
particular type of output, or some special handling for a spool file.
For example, if you are printing an output file that requires special
forms, and your installation expects that output to be spooled class Y,
issue the command:
cp spool printer class y
)
Section 7. Using Real printers, Punches, Readers, and Tapes
113
All subsequent printed output directed to yeur printer
address OOE (all CMS output) is processed as class Y.
at
virtual
If you place a HOLD on your printer or punch, any files that you
print or punch are not released to the control program's spooling queue
until you specifically alter the hold status. By placing your output
spool files in a hold status, you can select which files you print or
punch, and you can purge duplicate or unwanted files. To place printer
~nd punch output files in a hold status issue the commands:
~QLD:
cp spool printer hold
cp spool punch hold
When you issue a SPOOL command for a unit record device, you can
refer to it by its virtual address, as well as by its generic device
typ~ (for example, CP SPOOL E HOLD)~
B~te:
When you have placed a hold st~tus on printer or punch files and you
produce an output file for one of these devices, CP sends you a message
to remind you that you have placed the file in a hold:
PRT PILE xxxx POR'userid COpy xx HOLD
If, however, you have issued the command:
cp set msg off
then you do not receive the message.
When you place a r.eader file in a hold status, then the file remains
in the card reader until you remove the hold ,status and read it, or you
purge it.
COPY: If you want multiple copies of
COpy operand of the SPOOL command:
a spool file, you
should use the
cp spool printer copy 10
If you enter this command, then all subsequent printer files that you
produce are each printed 10 times, until you cha~ge the COpy attribute
of your printer.
POR: You can spool printed or punched output 'under another userid's name
Ei-using the POR operand of the SPOOL command. For example, if you
enter:
cp spool printer for charlie
Then, all subsequent printer files that you produce have, on the output
separator page, the userid CHARLIE and the distribution code for that
user. The spool file is then under the control of that user, and you
cannot alter it further.
!Q~Q!I:
You can print or punch many spool files, but have them
print or punch as one continuous spool file if you use the CONT operand
on the SPOOL command. Por example, if you issue the following sequence
of commands:
~QNT,
cp spool punch cont to brown
punch asm1 assemble
punch asm2 assemble
punch asm3 assemble
cp spool punch nocont
cp close punch
114
IBM VM/370 CMS User's Guide
(
Then, the three files ASK1 ASSEMBLE, ASM2 ASSEMELE, and ASM3 ASSEMBLE,
are punched to user BROWN as a single spool file. When user BROWN reads
this file onto a disk, however, CMS creates separate disk files.
~g:
When you spool your printer or punch to another userid, all output
from that device is transferred to the virtual card reader of the userid
you specify. When you are punching a CMS disk file, as in the example
above, you should use the TO operand of the SPOOL command to specify the
destination of the punch file.
You can also use this operand to place
card reader by using the * operand:
cp spool printer to
outFut in your
own virtual
*
After you enter this command, subsequent printed output is placed in
your virtual card reader. You might use this technique as an alternative
way of preventing a printer file from printing, or, if you choose to
read the file onto disk from your reader, of creating a disk file fro.
printer output.
Similarly, if you are creating punched output in a program
want to examine the output during testing, you could enter:
cp spool punch to
and you
*
so that you do not punch any real cards or transfer a virtual punch file
to another user.
ALTERING SPOOL FILES
)
After you have requested that VM/310 print or punch a file, or after you
have received a file in your virtual card reader and before the file is
actually printed, punched, or read, you
can alter some of its
characteristics, change its destination, or delete it altogether.
Every spool file in the VM/310 system has a unique four-digit number
from 0 to 9900 assigned to it, called a spoolid. You can use the spoolid
of a file to identify it when you want to do something to it. You can
also change a group of files, by specifying that all files of a
particular class be altered in some way, or you can manipulate all of
your spool files for a certain device at the same time.
The CP commands that allow you to manipulate spool files are CHANGE,
ORDER, PURGE, and TRANSFER. In addition, you can use the CP QUERY
command to list the status and characteristics of spool files associated
with your userid.
When you use .ny of these commands to reference spool files of a
particular device, you have the choice of referring to the files by
class or by spoolid.
You can also specify ALL. For example, if you
enter the command:
cp query printer all
you might see the display:
)
ORIGINID FILE CLASS RECDS CPY HOLD DATE TIM!
NAME
SCARLET 0211 D PRT 000140 01 USER 01/09 10:25:23 TARA
SCARLET 0245 A PRT 000026 01 NONE 01/09 10:25:41 CMSLIB
TYPE
DIST
FILE
BIN015
MACLTB BIN015
Section 1. Using Real Printers, Punches, Readers, and Tapes
115
until any of these files are processed, or in the case of files in the
hold status, until they are released, you can change the spool file name
and spool file type (this information appears on the first page or first
card of output), the distribution code, the number of copies, the class,
or the hold status, using the CP CHANGE command. For example:
cp change printer all nohold
changes all printer files that are in a hold status to a nohold status.
The CP CHANGE command can also change the spooling class, distribution
code, and so on.
If you d~cide that you do not w~nt to print a
file, you can delete it with the CP PURGE command:
particular printer
cp purge printer 7615
After you have punched a file to some other user, you cannot change
its characteristics or delete it unless you restore it to your own
virtual reader. You can do this with the TRANSFER command:
cp transfer all from usera
This command returns to your virtual card reader all punch
you spooled to USERA's virtual card reader.
files that
You can determine, for your reader or printer files, in
they should be read or printed. If you issue the command:
what order
cp order printer 8195 6547
Then, the file with spoolid of 8195
spoo1id of 6547.
is printed before the
file with a
The CP spooling system is very flexible, and can be a useful tool, if
you understand and use it properly. The !~LJ1Q ~g ~Q!!g~g R~!g£~~£~ !Q£
~~~~~g! Q2~~2 contains complete format
and operand descriptions for the
CP commands you can use to modify spool files.
USING YOUR CARD PUNCH AND CARD READER IN CMS
The CMS READCARD command reads cards from your virtual card reader at
address OOC. Cards can be placed in the reader in 9ne of two ways:
•
By reading real punched cards into the system card reader. A
card tells the CP spooling system which virtual card reader
receive the card images.
CP ID
is to
•
By transferring a file from another virtual machine. Cards are
transferred as a result of a virtual punch or printer being spooled
with the TO operand, or as a result of the TRANSFER command. Virtual
card images are created with the CMS PUNCH command, or from user
programs or EXEC procedures.
If you have a deck of punched cards that you want read into your virtual
machine card reader, you should punch, preceding the deck, a CP ID card:
ID HAPPY
116
IBM VM/370 CMS User's Guide
(
If you plan to use the READCARD command to read this file onto a CMS
disk, you can also punch a READ control card that specifies the filename
and fi1etype you want to have assigned to the file:
:READ PROG6 ASSEMBLE
Then, to read this file onto your CMS A-disk, you can enter the command:
readcard
*
If a file named PROG6 ASSEMBLE already exists, it is reF1aced.
If you do not punch a READ control card, you
and fi1etype on the READCARD command:
can specify a filename
readcard prog6 assemble
If this spool file contained a BEAD control card, the card is not read,
but remains in the file; if you edit the file, you can use the DELETE
subcommand to delete it.
If a file does not have a READ control card, and if you do not
specify a filename and fi1etype-when you read the file, CMS names the
file READCARD CMSUT1.
If you are reading many files into the real system card reader, and
you want to read the. in as separate spool files (or you want to spool
them to different userids), you must separate the cards and read the
decks onto disk individually. The CP system, after reading an ID card,
continues reading until it reaches a physical end of file.
When you use the CMS PUNCH command to punch a spool file, a READ control
card is punched to precede the deck, so that it can be read with the
READCARD command. If you do not wish to punch a READ control card (also
referred to as a header card), you can use the MOHEADER option on the
PUNCH command:
punch prog8 assemble
* (
noheader
You should use the NOHEADER option whenever you punch a file that is not
going to be read by the READCABD command.
The PUNCH co •• and can only punch records of up to .80 characters in
length. If you need to punch or to transfer to another user a file that
has records greater than 80 characters in length, you can use the DISK
DUMP command:
disk dump prog9 data
If your virtual card punch has been spooled to another
can read this file using the DISK LOAD command:
user, that user
disk load
Unlike the READCARD command, DISK LOAD does not allow you to specify a
file identification for a file you are reading; the filename and
fi1etype are always the same as those specified by the DISK DUMP command
that created the spool file.
A card file created by the DISK
disk by the DISK LOAD command.
DUMP co.mand Gan only
be read onto
Section 7. Using Real Printers, Punches, Readers, and Tapes
117
You can use the MOVEFILE command, in
command, to place a file in your virtual
from your card reader to another device.
conjunction with the FILEDEF
card reader, or to copy a file
For example:
*
cp spool punch to
filedef punch punch
filedef input disk coffee exec a1
movefile input punch
the file COFFEE EXEC A1 is punched to your virtual card punch
card-image format) and spooled to your own virtual reader.
Apart from
one or two
using your
punch one
command to
(in
the procedures shown above,
that transfer whole files with
commands, there are other methods you can use to create files
virtual card punch. From a program or an EXEC file, you can
line at a time to your virtual punch.
Then use the CLOSE
close the spool file:
cp close punch
Depending on how the punch was spooled
(the TO setting), the virtual
punch file is either punched or transferred to a virtual card reader.
UQ ~!~.ROS: If you write an OS, DOS, or ces program
that produces punched card output, you should make an appropriate file
definition. If you are an OS user, you should nse the FILEDEF command
to define the punch as .an output data device; if you are a DOS user, you
must use the AS5GN command. If you are using the CMS PUNCHC macro, the
punch is assigned for you. The spooling characteristics of your virtual
punch control the destination of the punched output,.
R..QNC.!!l!~ ~!1!12~ ~INQ
R..QNC.!!l!Q ~!1!12~ ~.RQ~ AI ~!!~: The EXEC facilities provide two control
statements for punching cards: &PUNCH, which punches a single line to
the virtual card punch, and &BEGPUNCH, which precedes a number of lines
to be punched. You can also, in an EXEC, use the commands PUNCH and
DI5K DUMP to punch CMS files.
Handling Tape Files in eMS
There are a variety of tape functions that you can perform in ces, and a
number of commands that you can use to control tape operations or to
read or write tape files.
One of the advantages of placing files on
tapes is portability: it is a convenient method of transferring data
from one real computing system to another. In CMS, you can use tapes
created under other operating systems. There are also two ces commands,
TAPE and DDR, that create tape files in formats unique to CMS, that you
can use to back up minidisks or to archive or transfer CMS files.
Under VM/370, virtual addresses 181 through 184 are usually reserved
for tape devices. In most cases, you can refer to these tapes in CMS by
using the symbolic names TAP1 through TAP4. In any event, before you
can use a tape, you must have it mounted and attached to your virtual
118
IBM VM/370 CMS User's Guide
(
machine by the system operator. When the tape is attached, you receive
a message. For example, if the operator attaches a tape to your virtual
machine at virtual address 181, you receive the message:
TAPE 181 ATTACHED
The various types of tape files,
can use to read or write them are:
and the commands and
programs you
TAPE Command: The CMS TAPE command creates taFe files from CMS disk
1Iles:--They are in a special format, and should only be read by the CftS
TAPE LOAD command.
For examples of TAPE command operands and options,
see "Using the CMS TAPE Command."
TAPPDS Command: The TAPPDS command creates CKS disk files from OS or DOS
sequentIal-tape files, or from OS partitioned data sets.
TAPEMAC Command: The TAPEMAC com.and creates CMS KACLIB files from OS
iaero-librarIes that were unloaded onto tape with the lEHKOVE utility
program.
MOVEFILE Command: The MOVEFlLE command can copy a sequential tape file
onto-aIsk--or-i-disk file onto tape. or, it can move files from your
card reader to tape or from tape to your card punch.
y§~ g~Qg~g!§:
You can write programs that read or write sequential tape
files using OS, DOS, or CMS macros.
!~~~§§ ~~!A~g ~~~vi£~§:
Tapes created by the EXPORT function of access
method services can be read only using the access method services IMPORT
function. Both the IMPORT and EXPORT functions can be accomplished in
CMS using the AMSERV command. The access method services REPRO funCtion
can also be used to copy sequential tape files.
~~B PrQg~~!:
The DDR program, invoked with the CMS command DDR, dumps
the contents of a virtual disk onto tape, and should be used to restore
such files to disk.
USING THE CMS TAPE COMMAND
The CMS TAPE command provides a variety of tape handling functions.
It
allows you to selectively dump or load CMS files to and from tapes, as
well as to position, rewind, and scan the contents of tapes.
You can
use the TAPE command to save the contents of CMS disk files, or to
,transfer them from one VM/370 system to another. The following example
shows how to create a CMS tape with three tape files on it, each
containing one or more CMS files, and then shews how you, or another
user, might use the tape at a later time.
The example is in the form of a terminal session and shows, in the
"Terminal Display" column, the commands and responses you might see.
System messages and responses are in uppercase, and user-entered
commands are in lowercase. The "Comments" column provides explanations
of the commands and responses.
)
Section 7. Using Real printers, Punches, Readers, and Tapes
119
!~~!~~l ~!§Bl~Y
TAPE 181 ATTACHED
list file * assemble a (exec
R;
cms tape dump
TAPE DUMP PROG1 ASSEMBLE A1
DUMPING •••••
PROG1
ASSEMBLE A1
TAPE DUMP PROG2 ASSEMBLE A1
DUMPING •••••
PROG2
ASSEMBLE A1
TAPE DUMP PROG3 ASSEMBLE A1
TAPE DUMP PROG9 ASSEMBLE A1
DUMPING •••••
PROG9
ASSEMBLE A1
R;
tape wtm
R;
tape dump mylib maclib a
DUMPING •••••
MYLIB
MACLIB
A1
R;
tape dump clRslib maclib *
DUMPING •••••
CMSLIB
MACLIB
S2
R;
tape wtm
R;
tape dump mylib txtlib a
DUMPING •••••
MYLIB
TXTLIB
A1
R;
tape wtll 2
R;
tape rew
R;
tape scan (eof 4
SCANNING •.•••
PROG1
ASSEMBLE A1
PROG2
ASSEMBLE A1
PROG3
ASSEMBLE A1
PROG4
ASSEMBLE A1
PROGS
ASSEMBLE A1
PROG6
ASSEMBLE A1
PROG7
ASSE!BLE A1
PROG8
ASSEMBLE A1
PROG9
ASSEMBLE A1
END-OF-FILE OR END-OF-TAPE
MYLIB
MACLIB
A1
CMSLIB
MACLIB
S2
END-OF-FILE OR END-OF-TAPE
MYLIB
TXTLIB
A1
END-OF-FILE OR END-OF-TAPE
END-OF-FILE OR END-OF-TAPE
R;
Icp det 181
TAPE 181 DETACHED
COllments
Message-indicates that the tape is
attached,.
Prepare to dump all ASSEMBLE files
by using the LISTFILE command EXEC
option; then execute the CMS EXEC
using TAPE and DUMP as arguments~
The TAPE command responds' to each
TAPE DUMP by printing the file
identification of the file being
dumped.
The last file, PROG9 ASSEMBLE, is
dumped.
The TAPE command writes a tape mark
to indicate an end of file.
Two macro libraries are dUllped,
by specifying the file identifiers.
Another tape mark is written.
A TEXT library is dumped.
Two tape marks are written to
indicate the end of the tape.
The tape is rewound.
The tape is scanned to verify
that all of the files are on it.
Tape mark indication.
Two tape marks indicate the end
of tbe tape .•
The CP DETACH command rewinds
and detaches the tape.
(
March 30, 1979
*
*
The tape created above is going to be read.
**********
TAPE 181 ATTACHED
tape load prog4 assemble
LOADING •••••
PROG4
ASSEMBLE A1
R;
tape scan
SCANNING ••••
PROGS
ASSEMBLE A1
PROG6
ASSEMBLE A1
PROG7
ASSEMBLE A1
PROG8
ASSEMBLE A1
END-OF-FILE OR END-OF-TAPE
Message indicating the tape is
attached.
One file is to be read onto disk.
The TAPE command displays the
name of the file loaded. Any
existing file with the same
filename and fi1etype is erased.
The remainder of the first tape
file is scanned.
Indication of end of first tape file.
R;
tape scan
SCANNING ••••
MILIB
MACLIB
A1
CMSLIB
MACLIB
S2
END-OF-FILE OR END-OF-TAPE
The second tape file is scanned.
R;
tape bsf 2
R;
tape fsf
R;
tape load (eof 2
LOADING •••••
MILIB
MACLIB
A1
CMSLIB
MACLIB
A2
END-OF-FILE OR END-OF-TAPE
MILIB
TITLIB
11
END-OF-FILE OR END-OF-TAPE
The tape is backed up and
postioned in front of the
last tape file.
The tape is forward spaced past
the tape mark.
The next two tape files are
going to be read.
R;
Icp detach 181
TAPE 181 DETACHED
The tape is detached.
Tape Labels in eMS
Support in the eMS component of
includes the following features:
VM/370
to process
labelled
tapes
•
Checks IBM standard labels on input
•
Writes IBM standard labels on output
•
Allows you to specify routines to process standard user labels during
DOS and OS macro simulation under CMS
•
Allows you to specify exits for processing tapes with nonstandard
labels during execution of CMS macro simulations and some CMS tape
operation commands
Section 7. Using Real Printers, Punches, Readers, and Tapes
121
March 30, 1979
CMS processes all tape labels; CP does not process tape labels.
CMS tape label processing does not include:
•
Label processing for tapes that are read backwards
•
processing of multivolume files on tapes
•
Support for ANSI tapes or ASCII labels
•
Label processing for any functions of the CMS TAPE command except the
two functions DVOL1 and VVOLl that' process VOLl labels
USER RESPONSIBILITIES
You must initiate all your own tape label processing.
To specify that
you have a labelled tape, use the FILEDEF command for an OS simulaticn
program, or
a DOS DTFMT macro for a CMS/DOS program. You can also
use the TAPESL macro to process standard HDRl and EOFl labels and the
CMS TAPE co"mmand to write and display standard VOLl labels.
You can
provide IBM;,'standard label description details with the LABELDEF command
for all t~pes of label processing.
After label processing has been
requested,/it occurs automatically and there is no interaction between
you and cMs unless an error occurs. See the "Error processing" section
later in this publication for a discussion of error processing.
Jse
LABEL PROCESSING IN OS SIMULATION
If you are running an OS simulation program and using OPEN and CLOSE
macros, you specify the type of label processing you want in a FILEDEF
command for a g~ven file.
Detailed information about the FILEDEF
command is found in the !~JIQ ~~~ ~Q~~~g ~ng !~~£Q ~~!~£~~~~. You may
specify that you want standard label processing (with SL) or nonstandard
label processing
(wi th NSL).
If
you choose
'nonstandard label
processing, you must already have
written a routine to process
nonstandard labels. The name of this routine must be specified by the
filename in the NSL parameter on FILEDEF.
An example of nonstandard
label processing is given in the section "NSL Processing".
To be sure
that the tape you are using contains no IBM labels, you may specify no
label processing (NL) in the FILEDEF command. When NL is specified, C!S
does not open files on a tape containing a VOLl label as its first
record. You also can specify bypass tape label processing (BLP)
on a
FILEDEF command.
BLP tells CMS to bypass tape label processing for a
file, anc instead, to position the tape at a particular file before
processing the data records in the file.
If you specify LABOFF for a
FILEDEF tape file, label processing is turned off and there is no tape
positioning or label checking.
LABOFF is the default, so you do not receive any processing or tape
positioning for a tape file unless you specifically request it. If you
specify BLP, NL, SL, or SUL processing but omit a positional parameter.
the position defaults to 1 and the tape is positioned at the first file.
Examples of NL, BLP, and LABOFF processing are given in the sections "No
Label (NL) Processing", "Bypass Label
(BL~ processing"~ and "Label Off
(LABOFF) processing".
122
IBM VM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1919 by Supp. SD23-9024-1 for 5148-118
For IBM standard labels, you specify, SL or SUL, and optional positional
and VOLID parameters. On a FILEDEF command, SUL means standard user
labels. Everything you do for SL files, you must also do for SUL files.
The positional parameter for standard label files works the same way it
does in OS/VS. If you specify:
filedef filex tap1 sl 2
the tape is spaced to what is physically the fourth file on the tape
before processing begins. The reason for this spacing is that a
standard labelled tape has one header file, one data file, and one
trailer file for each data file.
If you leave off the positional
parameter:
filedef filey tap3 suI
you get the first file on the tape.
The optional VaLID parameter on the FILEDEF command allows you to
specify the volume serial number in the VaLl label of a tape in case you
want only the VOL1 label checked on the tape. If you want to specify
other fields in IBM standard labels, you must also provide a LABELDEF
statement for the tape file.
The LABELDEF statement allows you to
assign values to all fields in a standard HERl or EOF1 label.
A
complete description of how the LABELDEF command works may be found in
the "LABELDEF Command" section later in this publication.
The followihg command defines filez as a standard labelled tape file
on a tape with a VOL1 label and a volume serial number of DEPT78:
filedef filez tap1 51 volid dept78
If you also wish to specify a data set identifier for filez, you must
furnish a LABELDEF command for filez as well as the FILEDEF command.
Data set name may not be specified on the FILEDEF command. The LABELDEF
statement below assigns a data set name of payroll to filez.
labeldef filez fid payroll
You can also specify file sequence number, volume sequence number,
expiration date and other fields on a LABELDEF command. However, if yeu
are using as simulation macros (OPEN, CLOSE, READ, WRITE~ GET, PUT,
etc.) to process your tape file,
the only LABELDEF parameter that has
meaning for input files is fid (data set identifier). This is the only
field that is checked on input by as simulation. The other LABELDEF
fields are used to specify values to be written in output labels. They
are also used by other types of tape label processing (CMS/DOS and CMS)
to check input labels. If no LABELDEF command has been supplied fer
output files, default values are used to write out labels (see the
section on the LABELDEF command for the default values).
After you have set up your descriptive information for a standard
labelled tape file in FILEDEF and LABELDEF statements, you run a regular
as simulation program under CMS. During prog~am execution, HDRl and
HDR2 labels are written or checked at OPEN time. EOF1 and EOF2 labels
are written or checked at CLOSE time. To have EOP labels processed, yeu
must issue a CLOSE macro. The VOL1 label on a tape is checked whenever
a file on that tape is opened if the user has specified a VOLID
parameter on his FILEDEF statement or LABELDEF statement for the file.
If the volid is specified on both LABELDEF and FILEDEF, the more recent
specification is used. If no valid is specified, it is not checked.
After checking the volid, the tape is positioned and the HDR label is
Section 7. Using Real printers, Punches, Readers, and Tapes
122.1
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. St23-9024-1 for 5748-XX8
processed. For processing multifile volumes, you may wish to use t.he
LEAVE option on the FILEDEF command. This option prevents a tape from
being rewound and positioned before each tape file is processed. The
LEAVE option does not exist on an OS DD statement.
For input files, HDR2 and EOF2 labels are skipped. There is no merge
of information from a HDR2 label with information in the DCB as there is
under an OS/VS operating system. Output HDR2/EOF2 records are written
from information in the DCB and the CMSCB (FCBSEeT). Note that the tape
density and TRTCH fields in HDR2/EOF2 records are taken from what the
user specifies in his FILEDEF command for the tape file.
They may not
correspond to the actual density and TRTCH fields used to write the
tape.
TO process
following:
standard user labels
in OS
simulation, you must
1..
Specify the file as SUL in a FILEDEF command.
2.
Provide a routine
program.
3.
Put the address of
the DCB for the
4.
to process
the
user standard
labels in
do the
your
the user label routine in the DCB EXIT list of
file.
See the IBM publication Q2L!~1 Q~l~
!g~gg~~~~l ~~!!£g§ 2y!£g or Q~L!~~ ~!~ ]~1~ ~~~~~~~~1 2~£!1£~§
Guide, for instructions on how to establish a DCB EXIT list, and
the-exact linkage for communication between user label routines and
the operating system. This exact linkage should be used under CMS
with the following exceptions:
a.
There is no support for code x'06' EOV EXIT routine.
b.
For input labels, return codes 8 and 12 from the user routine
are not supporteg.
If an input return code is not 0, it is
treated as if it were 4.
Note that your standard user label routines do not perform any
input/output. They set up an output label for writing, but the CMS
tape label processing routines actually write out the label. For
input, the CMS label processing routines read in your user standard
label but then give control to your routine to check the label.
You should specify NL in the FILEDEF command when you expect a tape does
not contain any IBM standard tape labels~
eMS reads your tape at the
time a file is opened and does not open the file if the tape contains a
VOL1 label as its first record. If the tape does not contain a VOL1
label, a file is opened and the tape is positioned by using the position
parameter (n). For example, if you specify:
filedef fileg tap1 n1 2
fileg is not opened if the tape on tap1 (181) has a VOL1 label. If the
tape does not have a VOLl label, fileg is opened and the tape is
positioned at the second file.
If you do not specify a position
parameter, the tape is positioned at the first file, (that is, the load
point).
122.2
IBM VM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. 5D23-9024-1 for 5748-118
You should specify BLP in the FILEDEF command to bypass tape label
processing.
CMS does not check your tape for an IBM standard tape
label. It uses the position parameter you specified to position the
tape during open processing.
If you do not specify a position
parameter, the default is 1. For example:
filedef fileabc tape1 blp 4
positions the tape at the fourth file when it opens fileabc. Because
CMS does not know whether files on the tape are label files or data
files, the tape is positioned at what is physically the fourth file,
regardless of file content. Any label files on the tape are included in
counting files.
You should specify LABOFF in the FILEDEF command if you want no
positioning or label processing to occur during open processing. The
position parameter is not valid for LABOFF~ If you specify LABOFF, and
your tape is positioned at record.6 in the third file before you issue
an OPEN macro, the tape is positioned at exactly the same record after
open processing
(record 6 in the third file). The following FILED!F
command does not move tape2 (182) before processing the data in fileb:
filedef fileb tap2 lab off
In order to process nonstandard labels, you must write your own routine
to read, write, and check the labels. If you have such a routine as a
CMS TEXT or MODULE file, you put the filename of the routine after the
NSL keyword parameter in the FILEDEF command for the file. The filenaae
must be the name of the first CSECT in the program. It is to this point
that control is transferred when the NSL routine gets control. If you
do not have a TEXT or MODULE file with the NSL filename you specify, you
get an error message. The OPEN and CLOSE routines will load your module
if it is not already in storage and will pass control to it at the tiae
they are oFening or closing the file.
Your routines will then be
responsible for processing the tape labels. Nonstandard label routines
must do the actual reading and writing of tape labels as well as
checking and setting up the label.
This is one of several ways
nonstandard label processing is different from standard user label
processing. Because the CMS label processing routines do not know the
size or format of your nonstandard labels, they cannot read or write the
labels.
)
If you use a MODULE file for an NSL routine, it is important that you
create the MODULE file so that it starts at an address that will not
allow it to overlay the program or command you are executing at the time
the NSL routine is invoked. The reason for this restriction is that the
NSL routine is dynamically loaded while your program is executing. For
the TAPEMAC and TAPPDS commands, starting the NSL routine at an address
above X'21000' prevents such an overlay.
If the NSL routine is invoked
from your own program which is running in the user area, you must
determine how big your program is and where the NSL MODULE file should
be located to prevent overlay. Note that you do not have to specify a
Section 7. Using Real Printers, Punches l
Readers, and Tapes
122.3
GC20~1819-2Rev
Pg. of
March 30# 1979 by Supp. SD23-9024-1 for 5748-XX8
starting address for NSL routines that are TEXT files.
The CMS loader
loads such files for you at an address that does not cause an overlay.
Although any user may write his own NSL routine, it is expected that
a system programmer will usually write such routines and then other
programmers in the installation will use them. Before writing an NSL
routine, read the Introduction to CMS,
Interrupt Handling, and CMS
Functional Information sections in Part 3 of the !~Ll1~
ay§l~~
g!gg!~~ID~!§ ~yig~.
In order to ensure proper communication with the CMS
system routines, you must use the linkage described below when you write
nonstandard label routines.
When an NSL tape label processing routine gets control, register 1
points to a 16-byte parameter list with the following format:
r
byte
0
byte
4 I
I
I
I
1
Type
call
Caller
id
Tape ModeSet Byte
Reserved
I
TAPID
I
I -, ID parameter
I
byte
I
I
FCBSECT address
8
I
I
byte 12 I
I
~
I
DCB address
for
TAPEMAC and
I TAPPDS
I
I
-J
The Type call
being done:
x·OO'
x'04 1
x'08'
x'OC'
x'10'
field is a code
is
is
is
is
is
telling the type of
label processing
OPEN input
OPEN output
CLOSE input
CLOSE output
End of Tape output
The Caller id is a one-byte code which is one of the following:
x'80'
x'20'
Call byOS simulation
Call by CMS TAPEMAC or TAPPDS commands
Tape modeset byte is used to communicate with the CMS tape I/O
routines.
It is a one byte hexadecimal code that depends on the type of
tape (7 or 9 track), tape density, etc. For further information on the
Mode Set, see the TAPE command description in the !~Lll~
£~~ £g~~~~g
~BgA~fI2 Rg!gIgB£~.
(You probably will pass this byte to the CMS tape
controlling module to read and write your tape labels and will never
need. to know what its codes mean.)
FCBSECT address is the address of
file you a~e· processing.
DCB address
processing.
is the
address of
the CMSCB (FCBSECT)
the DCB
for the
for
tape file
the tape
you are
Note that for the TAPEMAC and TAPPDS commands, the same interface is
used, except that instead of the FCBSECT and ICB address fields, the
eight character identifier specified in the ID=identifier field in the
command is, pa~sed.
This identifier enables you to identify which file
you are precessing since the TAPEMAC and TAPPIS commatlds do not work
with CMSCBs or DCBs.
122.4
IBM VM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
Control is passed to your NSL routine by a BALR ·14,15 instruction so
register 15 contains the address of your routine when you receive
control. Register 14 contains the address you should return to when you
are finished processing the nonstandard labels. You can return with a
BR 14 instruction. When you receive control, register 13 points to a
save area in which to store the callers register. The save area linkage
is standard OS/VS linkage.
You receive control with a PSi key of X'E'
which allows you to modify only user storage. When you are finished
processing, place a code in register 15 to the CMS label processing
routine that called your routine. Place the value 0 (zero) in register
15 if there have been no errors and you want processing to continue
normally and the data set to be opened. If you return a nonzero value
in register 15, a message is issued to your terminal and the data set is
not opened.
If you write the following FILEDEF statement:
filedef tapf1 tap1 nsl readlab
and have a program called READLAB as a MODULE or TEXT file, your program
will receive control when the data set called tapf1 is opened. When
your program gets control, register 1 contains the address of the
parameter list described above. Using the data in this parameter list,
you are able to read or write your own tape header labels.
When the
same data set is closed, your program again receives control and you can
read or write your qwn trailer labels. Your program can test whether it
is getting control for OPEN or CLOSE by examining the type call byte in
the parameter list passed to you. If the type call byte is x'10', your
NSL routine is being invoked While you are writing an output data set
and you have reached the reflective mark that indicates end of tape.
You may wish to do special processing in this case. See the "End of
Tape" and "End of Volume" section in this publication for further
information on end of tape processing.
There are a few minor differences in the way CMS os simulation processes
tapes and the way OS/VS processes them. These differences are listed
below.
•
If you are using as/vs and you do not specify any label parameter on
your JCL statement, the default is SL or standard labels. When you
use as simulation under CMS and do not specify any label information
on a FILEDEF statement, the default is LABOFF..
LABOFF turns off
label processing and nothing is done to position the tape or process
labels. Thus, if you specify no label information on FILEDEF, the
system will process your tape files exactly the same way they are
processed on a CMS system that has no tape label processing
facilities.
•
You must specify CLOSE to process all trailer labels. No automatic
CLOSE occurs at end of data or after reading a tape mark.
There is
no EOV monitor to process labels before a data set is closed. If an
input tape is positioned at an EOF1 or EOV1 record when CLOSE is
issued, the label is processed. If a tape file is closed before all
data records are read, the trailer label is not processed. Output
tapes have EOF records written only at CLOSE time.
•
There is no deferred label processing under OS simulation in CMS.
Section 7. Using Real printers, Punches, Readers, and Tapes
122.5
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SB23-9024-1 for 5748-XX8
•
When the user has not specified a block count routine in his DCB EXIT
list und~r OS/VS,the program abends when a block count error occurs.
Under CMS, this condition produces a message that asks whether or not
to abend the operation.
•
Certain fields in HDR1 and EOF1 labels default to values different
from those under OS/VS. These values can always be specified in a
LABELDEF command if the user does not like the default values. For
example, the default for data set name in an output label under as
simulation is DDNAME and not DSNAME. The default data set sequence
number is always one even when the data set is not the first data set
on the tape.
The default volume sequence number is always one. Read
the section on the L!BELDEF command ~n this manual to learn what the
default values are under CMS. You can find what default values are
in OS/VS by reading the IBM publication Q~!~ 1~~ 1s£~1§. Note that
you can always get exactly what you want written on a tape label by
explicitly specifying the field on a LABELDEP command. For example,
you can specify DSNAME as FID on such a command and have it written
in the label instead of DDNAME.
•
Default volids (when you do not specify a volid in a
PILEDEF statement) in output HDR1 and EOF1 records under
CMS001 and will not be the actual volume serial in the
already cn the tape. It is recommended that you always
volid in FILEDEP or LABELDEF to be sure the information
correct.
•
Expiration date specification is always done in absolute form rather
than by retention period. You must always use the form yyddd where
lY is the year (0-9~ and ddd the day (0-366).
CMS does not handle
expiration dates specified by retention periods.
•
When CMS reads a HDR1 label and finds an unexpired file, it always
issues a message allowing you to enter 'IGNORE' or 'ERROR'.
'ERROR'
prevents opening the file but 'IGNORE' lets you ignore the error and
write over the unexpired file.
•
The NSL routine linkage is quite d~ferent under CMS
(See the section "NSL Processing" fdrI details.)
•
Volume serial number verification occurs every time a file on a tape
is opened under OS simulation unless the PILEDEF LEAVE option is used
for multifile tapes.
•
Existing VOL1 labels are not automatically
incompatibility in CMS as they are in OS/VS.
•
HDR2 records are skipped for input under CMS for os simulation. They
are not checked and information in them is not merged with DCB
information.
HDR2 records are written
(with information obtained
from the DCB) on output.
•
Blank tapes used for output in CMS cause the tape to run off the reel
if you define the tape file as SL or NL.
The tape label processing
routines try to read an existing VOL1 or HDR1 label before writing on
the tape. Therefore, you should always use the CMS TAPE command to
write at least one tape mark (for NL tapes) or a VOL1 label (for SL
or SUL tapes) before using the tape to write an output data set.
•
If you specify a position parameter that is too big
(that is, there
are not that many files on the tape), the tape will run off the reel
in CMS.
122.6
IBM VM/370 CMS User's Guide
LABELDEP or
CMS will be
VOL1 record
specify the
written is
than in OS/VS.
rewritten for
density
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
•
There are no user
processing in CMS.
exits for
user standard
labels
for EOV
label
•
CMS does not support user return codes of 8 and 12 for input
user labels.
If the return code from a user routine is
after input label processing, CMS treats it as if the return
4.
(See the IBM publication Q~L!~l ~~1~ ~~n~g~~~n1 ~~£~~£~2
Q~L!~~ H!~ Q~1~ ~~ngg~m~n1 ~~~!!£~2 Q~!£~ for details).
standard
not zero
code was
§Y1£~ or
•
No count is kept of user standard labels read or bypassed in
more than eight such labels exist, the fact is not detected.
CMS~
•
User label processing routines do not receive control under CMS when
an abend or a permanent I/O error occurs.
•
If a CMS output tape is not positioned at a HDR1 label or a tape mark
when label processing begins, error message 422 is issued. Under
OS/VS such conditions cause an abend.
•
TCLOSE with the REREAD option causes a tape to be rewound under CMS
and then forward spaced one file if the tape has standard labels.
Under OS/VS, the tape is backspaced four files and forward spaced ODe
file. REREAD for unlabelled tapes in CMS always causes a rewind.
If
For further information on OS/VS tape label processing, refer to the
following IBM publications: Q~L!~l Q~1~ ~gn~g~!~n1 ~~£!1£~2 §y!g~,
Q~L!~l ~!~ Q~1~ H~ngg~m~n1 ~~!!i£~2 Q~iQ~,
and
Q~LVS I~E~ 1ab~1§.
For details on end-of-tape/end-of-volume processing under CMS, see
the "End-of-Volume" and "End-of-Tape Processing" section later in this
publication.
LABEL PROCESSING IN CMS/DOS
You specify the type of label processing you want in CMS/DOS on a DTFMT
macro in exactly the same way you specify it when you want to run your
program under DOS/VSE. See the !~Ll1Q ~I§1~~ g£Qg£~~me£~2 §y1de for
details on CMS support for the DTFMT macro.
Labelled tapes are only supported if you use the DTFMT macro. There
is no support for labelled tapes in , CMS/DOS for any other type. If yeu
try to read labelled tapes with a DTFCP or DTFDI macro, input standard
IBM header labels are skipped, but no other input labels are processed.
Output tapes with standard labels have these labels overwritten with a
tape mark. All tape work files are treated as output unlabelled files
in CMS/DOS although they are defined by a DTFMT. Tapes used for such
files have a tape mark written as the first record when the file is
opened.
You define an unlabelled tape with the DTFftT
tape file is processed as having no labels.
parameter FILABL=NO.
The
You define a nonstandard labelled tape with the DTFMT parameter
FILABL=NSTD.
You also
must provide a routine
to process your
nonstandard labels in the LABADDR=parameter
of the DTFMT.
Tape
processing in CMS for these files is the same as it is under DOS/VSE.
Section 7. U$in9 Real Printers, Punches, Readers, and Tapes
122.7
Pg. of
GC20~1819-2
Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
You define a standard label tape with the DTF~T parameter FILABL=STD.
You also must supply a LABELDEF command to specify label descripticn
information.
This command replaces the DOS/VSE TLBL card and is
required for standard label processing under eMS/DOS. The LABELDEF
command is discussed in detail in the "LABELDEF Command" section later
in this publication.
In order to connect the LABELDEF command for a file with the DTFftT
for the same file, you must use the same name to label your DTFMT as you
use for a filename in your LABELDEF command. If you code a DTFMT macro
in your program as:
liT1 DTFMT
••• FILABL=STD
you must then supply the following type of LABELtEF command:
labeldef mtl fid yourfile fseq •••
You can put any description parameters you want on your LABELDEP
command but the filename for it must be mt1 if you coded MT1 as the
label on the DTFMT.
After you have set up your DTFMT and LABELDEF, you execute your
CMS/DOS program. HDR1 labels are checked or written when an OPEN macro
is issued.
EOFl labels are checked or written when a CLOSE macro is
issued. A VOL1 label volume serial number is checked only if the tape
is positioned at load point when the label processing hegins and if you
have specified a VOLID parameter on a LABELDEF statement for the file.
Note, if NOREWIND is not specified in the DTFftT macro for the file, the
tape is rewound so it is positioned at load point for label processing.
If you want to process user standard labels as well as standard
labels in CMS/DOS, you specify FILAaL=STD and also supply a LABADER
parameter in the DTFMT for the file~
Control is then transferred to
your label processing routines after standard labels are processed. The
linkage to user standard label routines is exactly the same as in
DOS/VSE.
There are minor differences in the way tapes are processed by CMS/DOS
and the way they are processed by DOS/VSE. These differences are:
I •
I
The tape error messages are CMS error messages and not DOS/VSE error
aessages. In some cases DOS/VSE allows the system operator to reply
NEWTAP to an error message. The system then waits for the operator
to mount a new tape and continues processing with this new tape.
Such a reply is never possible under CMS/DOS.
In CMS/DOS I
you
usually can reply IGNORE to ignore a tape label error condition or
CANCEL to cancel a job. NEWTAP is never allowed. In a few cases,
CMS/DOS allows an IGNORE reply where DOS/VSE does not.
•
You must specify CLOSE to process all trailer labels. No automatic
CLOSE occurs at end of data or after reading a tape mark.
If an
input tape is positioned at an EOF1 or EOV1 record when CLOSE is
issued, the label is processed. If a tape file is closed before all
data records are read, the trailer label is not processed. Output
122.8
IBM VM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
tapes have EOF records written only at CLOSE time. For nonstandard
labelled tapes, your own routines do not receive control on input
when a tape mark is read.
You must issue a CLOSE macro in your
EOFADDR routine in order to have the trailer labels processed.
•
Certain fields in HDRl and EOF1 labels default to values different
from those in DOS/VSE. For example, the default volume serial number
written in a HDRl label is CMS001 and not the actual volume serial
number (volid)
in the VaLl label already on the tape.
The default
file sequence and volume sequence numbers are always one even when
the file is not the first file on the tape.
You should read the
section on the LABELDEF command in this publication to learn what the
default values are in CMS/DOS. You also can read the IBM publication
QQEL!~~ !gR§ ~g~§l§ to find what
the default values are for DOS/VSE.
If you do not like the default values, you can always specify the
exact values you want in label fields in a LAEELDEF command.
•
Expiration date specification is always done in absolute form rather
than by retention period. You must always use the form yyddd where
yy is the year (0-99) and the ddd the day
(0-366). CMS does not
handle expiration dates specified by retention periods.
•
VOL1 labels written
in the wrong density
automatically by CMS/DOS as they are by DOS/VSE.
•
Blank taFes should not be used for tape files specified as FILABL=STD
in CMS/DOS; they will run off the reel. Use the CMS TAPE command to
write a VOLl label or a tape mark on a blank tape before using it fer
a STD file.
I •
I
Not all tape movement and label checking that occurs in DOS/VSE
occurs under CMS.
For example, when opening an output file, a
DOS/VSE system expects the tape to be positioned at a HDRl label or a
tape mark. It then backspaces the tape to read the last EOFl label
on the tape. If it does not find the label it expects, it issues an
error message. This check is not performed by CMS/DOS. If the tape
is not positioned at a HDR1 label or a tape mark when output open
processing begins, error message 422 is issued.
•
After an EOVl label is written
(see "End-of-Tape/End-of-Volume
Processing" later in this publication), the tape is always rewound
and unloaded under CMS/DOS. DOS/VSE lets a DTFMT parameter control
whether or not the tape is rewound.
•
User label processing routines
error occurs under CMS/DOS.
•
Control is not passed to user standard label routines in CMS/DOS when
EOT has been sensed on output and an EOVl label has been written by
the system routines.
•
Work -tapes are not checked for an expiration date when they contain
standard labels under CMS/DOS.
If a tape is to be opened as a work
tape, CMS/DOS tests to see if it contains a VOLl label. If it does,
a dummy HDRl label and a tape mark are immediately written on the
tape after the VOLl label. If the tape does not contain a VOLl
label, a tape mark is written at the beginning of the tape. DOS/VSE
checks expiration dates on previously labelled tapes used as work
tapes and gives the operator a chance to reject the tapes if the
expiration date has not expired.
do not receive
are
not
rewritten
control when
Section 7. Using Real Printers, Punches, Readers, and Tapes
an I/O
122.9
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-118
For further information on DOS/VSE and CftS/DOS tape label processing,
refer to the following IBM publications:
DOS/VSE Tape Labels
DOS/VSE Macro User's Guide
DOS/VSE LIOCS Vol 2
CMS TAPESL MACRO
The TAPESL macro is provided for use in CMS programs that do not use OS
and DOS simulation features.
You can use the CftS T1PESL macro to
process IBM standard HDR1 and EOFl labels without using DOS or as OPEN
and CLOSE macros. You will probably use TAPESL with the RDT1PE, WRTAPE,
and TAPECTL macros.
TAPESL processes only HDR1 and EOF1 labels. It does not perform any
functions of opening a tape file other than label checking or writing.
The TAPESL macro generates linkage to the CMS tape label processing
routine that actually processes the label.
The macro generates a block
of data
(32 bytes long) in order to communicate with the tape label
processing routines.
TAPESL is used both to check and to write tape
labels. A LABELDEF command must be issued prior to running the program
that contains this macro. The LABID parameter of the TAPESL macro is
used to specify the name of the LABELDEF to be used.
For example, if
you use the macro:
TAPESL HOUT,181,LABID=GOODLAB
in your assembly language program, you
for GOODLAB:
must supply a
LABELDEF command
labedef goodlab fid file10 fseq 4 exdte 78235
The tape must be positioned correctly (at the label to be checked or at
the place where the label is to be written), before you issue the macro.
TAPECTL may be used to position the tape. TAPESL reads or writes only
one tape record unless you specify SPACE=YES for input. Then it spaces
the tape to beyond the tape mark that ends the label file. T1PESL reads
and checks a tape VOL1 label provided the tape is positioned at load
point and the user has specified a volid in his LABELDEF command.
TAPE LABEL PROCESSING BY CMS COMMANDS
There are three types of CMS commands
processing. They are:
•
•
•
that do some type
of tape label
TAPEMAC and TAPPDS commands
TAPE command
MOVEFILE command
TAPEMAC and TAPPDS have operands where you can indicate the type of
label processing you want. The tape must be positioned properly (at the
data file or label file you wan~ before you issue the command~ The
TAPE command may be used for positioning. A separate LABELDEF command
122.10
IBM VM/370 eMS User's Guide
Pg. of GC20-l819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
is required for these commands if IBM standard latel checking is
desired. If S1 label type is specified without a labdefid, standard
header labels are displayed on the terminal but not checked by the CMS
label processing routines. The command:
tapemac macfile S1 (tap2
displays any standard
series of commands:
labels that
exist
on your
terminal while
the
labeldef mac lab fid macro volseq 2 crdte 77102
tapemac macfile sl mac lab (tap2
invokes the CMS tape label processing routines. These routines check to
see that your tape has a HDRl label that has a file identifier of macro,
a volume sequence number 2, and a creation date of 77102. VOLl labels
are not checked during' label processing by TAPEMAC and TAPPDS unless the
tape is positioned at load point and you have specified a volid on your
lABE1DEF command~
The DVOLl function of the TAPE command can be used
for volume verification before positioning the tape if the user does not
want to start at the first file.
These commands process only HDRl
labels; they skip HDR2, UHL, and all trailer labels without processing
them.
To process nonstandard tape labels with TAPE MAC and TAPPDS, you use
the same interface described in the section "NSL Processing under OS
Simulation." The only difference is that instead of putting the CMSCB
and DCB addresses in the parameter list, the ID parameter you placed in
the command line is passed to your NSl routine.
tappds pdsfile cmsutl
*
nsl superck id XYZ12345
passes the EBCDIC identifier XYZ12345 to your nonstandard label checking
routine called SUPERCK.
This identifier may be up to eight characters
long and is left justified in bytes 8-15 of the parameter list. You can
use the identifier to inform your NSL routine of what file you are
processing.
Use the DVOll function of the CMSTAPE command to display the VOLl label
of a tape on your terminal. You may use this command to ensure the
system operator has mounted the correct tape before you begin processing
the tape.
If the tape does not have a VOLl label and you issue the
CMSTAPE command, you are informed that the VOLl label is missing. Do
not use TAPE DVOLl if you have a blank tape. If TAPE DVOLl is issued
and a blank tape is used, CMS will search the entire tape to find the
label record; since the tape is void of any records, the tape will run
off the end of the reel.
Use the WVOLl function on the TAPE command to write a VOLl label on a
tape. You can specify a one- to six-character volume serial number
(volid) through this command and also a one- to eight-character owner
field_
You can use the MOVEFILE command to move labelled tape files if these
files are defined as lahelled by the FILEDEF command. The MOVEFILE
command supports only SL, NS1, B1P, NL, and LABOFF processing.
SUL
files are processed as S1 files and no user exits are taken.
Section 7. Using Real Printers, Punches, Readers, and Tapes
122.11
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
You can also use the MOVEFILE command to display tape labels on your
terminal if you want to see what these l~bels leok like. The following
sequence displays the VOL1 and first HDRl labels on tap4 if the tape bas
standard labels:
filedef in tap4
filedef out term
tape rew (tap4
move in out
LABELDEF COMMAND
The LABELDEF command is used to specify the exact data you want written
in certain fields of a HDR1 or EOFl tape label for output. It can also
be used to specify fields in the same labels that you want checked en
input. If you do not explicitly specify a field for output, a default
value is used. If you do not explicitly specify a field for input, the
field is not checked. For example:
labe1def abc fid master vo1seq 1 exdte 77364
used for input tells CMS to check the file identifier volume sequence
number and expiration date in an input HDR1 label. No other fields in
the label are checked. The same specification used for output causes
the HDR1 label to have MASTER written in the file identifier field, 1
written in the volume sequence number field and 77364 written in the
expiration date field. Default values are written in the HDR1 fields
that are not specified.
Default values for HDR1 labels are as follows:
FID
for OS simulation, the DDNAME (Specified on FILEDEF)
for CMS/DOS, the DTFMT symbolic name
for CMS TAPESL macro, the LABELDEF id
(LABID=labe1defid)
parameter
VOLID
CMSOOl
VOLSEQ
0001
FSEQ
0001
GENN
blanks
GENV
blanks
CRDTE
current date that label is written
EXDTE
current date that label is written
SEC
o
The filename on the LABELDEF command is used to connect your label
definition to a file defined elsewhere.
This is why you specify
different data for file name depending on the type of tape label
processing you are doing. Filename is DDNAME for OS simulation, DTFMT
symbolic name for CMS/DOS and labeldefid for TAPESL.
The LABELDEF
for CMS/DOS.
122.12
I
command takes the place
IBM VM/370 eMS User's Guiqe
of the DOS/VSE
TLBL statement
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
END-OF-VOLUME AND END-OF-TAPE PROCESSING
There is no true end-of-volume support available with CMS tape label
processing. FEOV instructions are not supported under OS simulation and
there is no automatic volume switching.
Multivolume files are not
supported. The follcwing features exist to aid the IBM standard label
tape user when he reaches end-of-tape on output or an EOV label in
input. These are the only ways in which CMS sUFPorts EOV processing.
•
Input - When a CLOSE macro is issued or when a TAPESL macro processes
an input trailer label, a message is issued if the label read is an
EOV1 label instead of an EOF1 label.
The EOV1 label is then
processed exactly as if it were an EOF1 label. You must request that
the operator mount a new tape and reopen a file if you want to
continue processing the data.
•
Output Under CMS/DOS and OS simulation processing only
(that is,
the processing does not occur for TAPESL or CMS commands), the
following limited EOV processing occurs:
a.
If you specify that you have an IBM standard label tape file, a
single tape mark is written to end your data.
This occurs when
end-of-tape is sensed on output while you are using regular access
method macros to write the file.
The tape mark is written
immediately after the record that caused the EOT to be sensed.
Following this tape mark, CMS writes an EOV1 label and a single tape
mark. It then rewinds and unloads your tape. A message is issued
telling you that an EOV1 label was written. If you specified
nonstandard labels instead of writing the EOV1 label, an exit to the
nonstandard label routine you specified for the file is taken after
the end-of-data tape mark is written. For BLP or NL files, only the
ending tape mark is written.
b.
CMS/DOS jobs are always canceled after an EOT condition is
detected on output. In order to continue processing the tape, you
must have a new tape mounted, run the same job over again or run a
new job and reopen the file.
c. OS simulation programs that use QSAM ar contain a BSAM CHECK
macro cause an abend when EOT is detected, with code 001 after an
error message. A BSAM program that does not use a CHECK macro has no
way of detecting the EOT condition.
Such a Frogram continues to try
to write on the tape after it is rewound and unloaded. The program
enters a wait state rather than continue running to a normal or
abnormal completion.
Therefore, you should always include a BSIM
CHECK macro after the WRITE if you expect your program to reach
end-of-tape. OS simulation users are also responsible for completing
processing on a new tape with the same or a new job after an EOT is
detected.
d.
If you are a CMS/DOS user you always get the automatic output
end-of-tape processing described above. However, if you are an OS
simulation user and do not want CMS to do any special end-of-tape
processing, you can suppress it by using the NOEOV option on your
FILEDEF command for the file. If you enter:
fi1edef dd1 tap3 s1 (noeov
no tape marks or EOV1 labels are written when EOT is sensed on
output. Your tape is not rewound and unloaded. However, the program
causes an abend if you use QS1M or include a BS1M CHECK macro after
your WRITE macro. Without a CHECK macro, a BSAM program runs the
tape off the reel when EOT is sensed and NOEO~ is specified.
Section 7. Using Real Printers, Punches, Readers, and Tapes
122.13
Pg. of GC20-1819-2 Rev March 30, 1919 by Supp. SD23-9024-1 for 5748-118
ERROR PROCESSING
When the standard label processing routines find errors or discrepancies
on tape labels, they send a message to the CMS terminal user who is
processing the tape. After an error message is issued, the user can ask
the system operator to mount a new tape, use the CMS TAPE command to
position the tape at a different
file, or respecify his label
description information.
If you are a terminal user and want another
tape mounted, you send the system operator a message telling him what
tape to mount.
Some errors cause program termination and others do not. The effect
of tape label processing errors depends on both the type of error and
the type of program (that is, CMS/DOS, OS simulation, CMS command, etc.)
that invokes the label processing. The following are general guidelines
on error handling:
•
Messages identifying the error are always issued.
•
Under OS simulation, tape label errors result in open errors. These
errors prevent a tape file from
being opened.
They do not
necessarily end a job. Errors in trailer labels (except block count
errors) have no effect on processing.
•
In CMS/DOS, the terminal user is generally given two choices: ignore
the error or cancel the job. The new-tape option is not allowed.
•
The CMS commands TAPEMAC and TAPPDS terminates with a non-zero return
code after a tape label error.
•
Certain error situations such as unexpired files and block count
errors for OS simulation allow the user to ignore the error and do
not cause open errors. In these cases, the user enters his decision
at the terminal after he is notified of the error.
•
Errors that occur during the loading of an NSL routine cause an abend
(code 155 or 15A). A block count abend gives an error code of 500.
In all cases, after an error has been detected and diagnosed, you
aust decide what to do. you may wish to have a new tape mounted and
then re-execute the command or you may want to respecify your LABELDEF
description if it was incorrect. You can also use the TAPE command to
space the tape to a new file if it was positioned incorrectly.
THE MOVEFILE COMMAND
The MOVEFILE command can copy sequential tape files into disk files, or
sequential disk files onto tape. It can be particularly useful when you
need to copy a file from a tape and you do not know the format of the
tape.
To use the MOVEFILE command, you must first define the input and
output files using the FILEDEF command. For example, to copy a file from
a tape attached to your virtual machine at virtual address 181 to a CMS
disk, you would enter:
filedef input tapl
filedef output disk tape file a
movefile input output
122.14
IBM VM/310 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1919 by Supp. SD23-9024-1 for 5748-118
This sequence of co •• ands creates a file naaed TAPE FILE Al. Then use
CMS commands to aanipulate and examine the contents of the file.
MOVEFILE can also be used to display tape labels and/or'.ove labelled
tape files.
See "Tape Labels in CMS" for details.
TAPES CREATED BY OS UTILITY PROGRAMS
The CMS command TAPPDS can read OS partitioned and sequential data sets
from tapes created by the IEBPTPCH, IEBUPDT!, and IEHMOVE utility
programs. When you use the TAPPDS command~ the OS data set is copied
into a CMS disk file, or in the case of partitioned data sets, into
.ultiple disk files.
l~BP!f£~:
Sequential or partitioned data sets created by IEBPTPCB must
be unblocked for CMS to read them. If you have a tape created by this
utility, each member (if the data set is partitioned) is preceded with a
card that contains "MEMBER=membernaae". If you read this tape with the
command:
tappds
*
then, CMS creates a disk file fro. each member, using the aeabername for
the filename and assigning a filetype of CMSUT1. If you want to assign a
particular filetype, for example TEST, you could enter the coamand as
follows:
tappds
*
test
If the file you are reading is a sequential data set, you should use the
NOPDS option of the TAPPDS co •• and:
tappds test file (nopds
The above command reads a sequential data set and assigns it a file
identifier of TEST FILE. If you do not specify a filename or filetype,
the default file identifier is TAPPDS CftSUT1.
l~BUf~!~:
Tapes in control file format created by the IEBUPDTE utility
program can be read by CMS. Data sets may be blocked or unblocked, and
may be either sequential or partitioned.
Since files created by
IEBUPDTE contain ./ADD control cards to signal the addition of me.bers
to partitioned data sets, you must use the COL1 option of the TAPPDS
command. Also, you must indicate to CftS that the tape was created by
IEBUPDTE. For example, to read a partitioned data set, you vould enter
the command:
tappds
*
test (update co11
Section 1. Using Real Printers, Punches, Readers, and Tapes
122.15
March 30, 1979
122.16
IBM 'M/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-X18
The CMS disk files created are always in unblocked, 80-character format.
IEHMOVE: OS unloaded partitioned data sets on tapes created by the
llHMOii utility program can be read either by the TAPPDS command or by
the TAPEMAC command. The TAPPDS command creates an individual CMS file
from each member of the PDS.
If the PDS is a macro library, you can use the TAPEMAC command to
copy it into a CMS MACLIB. A MACLIB, a CMS macro library, has a special
format and can usually be created only by using the CMS MACLIB command.
If you use the TAPPDS command, you have to use the MACLIB command to
create the macro library fro.
individual files containing macro
definitions.
SPECIFYING SPECIAL TAPE HANDLING OPTIONS
For most of the tape handling that you do in CMS, you do not have to be
concerned with the density or recording format of the magnetic tapes
that you use.
There are, however, some instances when it may be
important and there are command options that you can use with the TAPE
command MODESET operand and with ASSGN and FILEDEF command options.
The specific
listed below.
situations and the command
options you should
use are
•
If you are reading or writing a 7-track tape and the density of the
tape is either 200 or 556 bpi, you must specify DEN 200 or DEN 556.
•
If you are reading or writing a
bpi, you must specify 1TRACK.
7-track tape with a
density of 800
•
If you are reading or writing a 7-track tape without
convert feature, you must use the TRTCH option.
using the data
•
If you are writing a
with the 9TRACK option
(on an 800/1600 drive)
specify DEN 800 or DEN
I •
I
I
I
tape using a 9-track dual density tape drive
specified, and you want the density to be 800
or 6250 (on a 1600/6250 drive), then you must
6250.
I
If you are writing a tape, the default tape block size is 4096 bytes
plus a 5-byte header. This format is not compatible with previous
VM/310 systems.
Therefore, if you want to write a tape compatible
with previous VM/370 systems, you must use the 'BLK 800' option of
the TAPE command. The TAPE command is described in detail in !~Ll1Q
I
~~~ ~g~~~~B g~B ~g£!g R~f~£~~£~·
Using the Remote Spooling Communications
Subsystem (RSCS)
If your VM/370 installation is on a Remote Spooling Communications
Subsystem (RSCS) network, you can send printer, punch, or reader spool
files to users at remote locations. To send a spool file, you must know
the userid of the virtual machine at your location that is running RSCS
and the location identification (locid) of the remote location. If you
are sending a spool file to a particular user at the remote location,
you should also know that userid of the user.
The CP commands that you can use to transmit files across the network
are TAG and SPOOL. The TAG command allows you to specify the locid and
userid that are to receive a spool file, or, in the case of tagging a
Section 1. Using Real Printers, Punches, Readers, and Tapes
123
March 30, 1979
printer or punch, of any spool files produced by that device.
With the
SPOOL command, you spool your virtual device to the RSCS virtual
machine. You can also use the TRANSFER command to transfer files frcm
your own virtual card reader.
The CP commands TAG, SPOOL, and TRANSFER are discussed in detail in
the publication !~JIQ ~f ~Qmm!ng RgtgE~n£g tQE §~ngE!! Y§gE§·
124
IB" VM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev ftarch 30, 1979 by Supp. SD23-9024-1 for 5748-118
Part 2. Program Development Using eMS
You can use CMS to write, develop, update, and test:
•
as programs to execute either in the
simulation) or in an as virtual machine
CftS
environment (using
os
•
DOS programs to execute in either the CftS/DOS environment or in a DOS
virtual machine
•
CftS programs to execute in the CftS environment
The as and DOS simulation capabilities of CftS allow you to develop OS
and DOS programs interactively in a time-sharing environment. When your
programs are thoroughly tested, you can execute them in an as or Des
virtual machine under the control of V8/370.
"Section 8. Developing as Programs Under CftS" is for programmers who
use as. It describes procedures and techniques for using CftS co.mands
that simulate as functions.
"Section 9. Developing DOS Programs Under CftS" is for programmers who
use DOS. It describes procedures and techniques for using CftS/DO~
co.mands to simulate DOS/VSE functions.
If you use VSAft and access method services in either a DOS or an OS
environment, "Section 10. Using Access Method Services and VSlft in CBS
and CftS/DOS" provides usage information for you. It describes how to
use CftS to manipulate VSAft disks and data sets.
You can use the interactive facilities of CP and CftS to test and
debug programs directly at your terminal. "Section 11. How Vft/370 Can
Help You Debug Your Programs" shows examples of commands and debugging
techniques.
The CftS batch facility is a CftS
to another machine for execution.
to a CftS batch virtual machine is
CftS Batch Facility."
feature that allows you to send jobs
How to prepare and send job streaas
described in "Section 12. Using the
As you learn to use CftS, you may want to write programs for CBS
applications.
"Section 13. Programming
for the CftS Environment"
contains information
for assembler language
programmers: linkage
conventions, programming notes, and macro instructions you can use in
CftS programs.
Part 2. Program Development Using CftS
125
March 30, 1979
126
IBM VM/370 CMSUser's Guide
March 30, 1919
Section 8. Developing OS Programs under
eMS
CMS simulates many of the functions of the Operating System
(OS),
allowing you to compile, execute and debug OS programs interactively.
For the most part,
you do not need to be concerned with the eMS OS
simulation routines~ they are built into the CMS system. Before you can
compile and execute as programs in CMS, however, you must be acquainted
with the following:
•
•
•
•
•
•
•
as macros that CMS can simulate
Using as data sets in CMS
How to use the FILEDEF command
creating CMS files from as data sets
Using CMS and as macro libraries
Assembling programs in CMS
Executing Frograms
These topics are discussed below.
Additional information for as VSAE
users is in "Section 10. Using Access Method Services and VSAM Under C~S
and CMS/DOS."
For a practice terminal session using the commands and techniques
presented in Section 8, see "Appendix D: Sample Terminal Sessions."
The CMS system uses many as terms, but there are a number of as
functions that CMS performs somewhat differently.
To help you become
familiar with the some of the CMS equivalents (where they do exist) for
as terms and functions, see Figure 11. It lists some commonly-used os
terms and discusses how CMS handles the functions they imply.
section 8. Developing as programs Under CMS
121
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 574S-XXS
CMS Equivalent
OS Tera/Function
Cataloged procedure
EXEC files can execute command sequences
similar to cataloged procedures, and provide
for conditional execution based on return
codes from previous steps.
Data set
Data sets are called files in CMS; CMS files
are always sequential but CMS simulates OS
partitioned data sets. CftS reads and writes
VSAft data sets.
Data Definition (DD)
card
The FILEDEF commandallcws you to perform the
functions of the DD statement to specify
device types and output file dispositions.
Data Set Control
Block (DSCB)
Information about a CMS disk file is contained
in a file status table (FST).
EXEC card
To execute a program in CMS you specify only
the name of the progiam if it is an EXEC,
ftODULE file, or CMS command. To execute TEXT
files, use the LOAD and START commands.
Job Control Language
(JCL)
CMS and user-written commands perform the
functions of JCL.
Link-editing
The CMS LOAD command loads object decks (TEXT
files) into virtual storage, and resolves
external references; the GENMOn command
creates absolute nonrelocatable modules.
Load .odule
CMS ftODULE files (resulting from the LOAD and
GENMOD commands) are nonrelocatable.
Object module
Language compiler output is placed in CftS
files with a filetype of TEXT.
Partitioned data set
CMS ftACLIBs and TXTLIBs are the only CMS files
that resemble partitioned data sets.
STEPCAT,JOBCAT
'SAM catalogs can be assigned for jobs or job
steps in CMS by using the special ddnames
IJSYSCT and IJSYSUC when identifying catalogs.
STEPLIB, JOBLIB
The GLOBAL command establishes macro and text
libraries; you can indirectly provide job
libraries by accessing and releasing CMS disks
that contain the files and programs you need.
Utility program
Functions similar to those performed by the OS
utility programs are provided by CMS commands.
Volume Table of
Contents (VTOC)
The list of files on a eMS disk is contained
in a file directory for SOO-byte format CMS
disks, or in the file directory for CMS disks
with a 1024-, 2048-, or 4096-byte block format
Figure 11. OS Terms and CMS Equivalents
128
IBM 'M/370 CMS User's Guide
Using OS Data Sets In eMS
You can have as disks defined in your virtual machine configuration;
they may be either entire disks or minidisks: their size and extent
depends on their VM/370 directory entries.
You can use partitioned and
sequential data sets on as disks in CMS. If you want, you can create
CMS files from your os data sets. If you have data sets on os disks,
you can read them from programs you execute in CMS, but you cannot
update them. The CMS commands that recognize os data sets on os disks
are listed in Figure 12.
Command
)
operation
ACCESS
Makes the os disk containing the data set available
to your eMS virtual machine.
ASSEMBLE
Assembles an
DDR
Copies an entire
DLBL
Defines as data sets for use with access method services
and VSAM files for program input/output.
FILEDEF
Defines the OS data set for use under CMS by associating
an as ddname with an OS data set name. Once defined,
the data set can be used by an as program running under
CMS and can be manipulated by the other commands that
support as functions.
GLOBAL
Makes macro libraries available to the assembler. You can
prepare an as macro library for reference by the GLOBAL
command by issuing a FILEDEF command for the data set and
giving the data set a filetype of MACLIB.
LISTDS
as
source program under CMS.
as
disk to tape.
Lists information describing
disks.
as
as
data sets residing on
MOVEFILE
Moves data records from one device to another device. Each
device is specified by a ddname, which must have been
defined via FILEDEF. You can use the MOVEFILE command to
create CMS files from as data sets.
QUERY
Lists (1) the files that have been defined with the
FILEDEF and DLBL commands (QUERY FILFDEF, QUERY DLBL), or
(2) the status of as disks attached to your virtual machinel
(QUERY DISK, QUERY SEARCH).
I
I
Releases an OS disk you have accessed (via ACCESS) from
I
your CMS virtual machine.
I
I
verifies the existence of an as data set on a disk.
I
Before 'STATE can verify the existence of the data set,
I
you must have defined it (via FILEDEF).
I
RELEASE
STATE
Figure 12. CMS Commands That Recognize
as
Data Sets and
as
Disks
)
Section 8. Developing
as
Programs Under eftS
129
ACCESS METHODS SUPPORTED BY CMS
as access methods are supported, to varying extents, by CMS. Under eMS,
you can execute programs that use the as data management macros that are
supplied for the access methods listed below.
Access Method
BDAM
BPAM
BSAM
QSAM
VSAM
eMS Support for OS
Simulated Data Sets
on eMS Disks
Yes
Yes
Yes
Yes
No
eMS Support for Real
as Data Sets on as
Disks
No
Yes (read only)
Yes (read only)
Yes (read only)
Yes
L----------------------------------------------------------------------J
~~AM,
~2A~, g~£ QSA~: You can execute
programs in eMS that read records
from as data sets using the BPAM, BSAM, or QSAM access methods,. You
cannot, however, write or update as data sets that reside on as disks.
BDAM: CMS can neither read nor write as
access method.
BDAM
data sets on as disks using the
VSAM Files: eMS can read and write VSAM files on as disks.
For
Information on using VSAM under eMS, see "section 10. Using ,Access
Method Services and VSAM Under eMS and eMS/DOS."
If you want to test programs in eMS that create or modify as data sets,
you can write "aS simulated data sets."
These are eMS files that are
maintained on eMS disks, but in as format rather than in CMS for.at.
Since they are eMS files, you can edit, rename, copy, or manipulate them
just as you would any other eMS file. Since they are in OS-simulated
format, files with variable-blocked records may contain block and record
descriptor words so that the access methods can manipulate them
properly.
The files that you create from as programs do not necessarily have to
be as simulated data sets. You can create eMS files.
The format of an
output file depends on how you specify the filemode number when you
issue the FILEDEF command to identify the file to eMS.
If you specify
the filemode number as 4, CMS creates a file that is in as simulated
data set format on a eMS disk.
eMS can read and write as simulated data sets using
BSAM, and QSAM access methods.
the BDAM, BPAe,
When an input or output error occurs, do not depend on as sense
bytes. An error code is supplied by eMS in the EeB in place of the
sense bytes. These error codes differ for various types of devices and
their meaning can be found in the !~~ !ALJIQ 2I§!g~ ~~§22g~2' under DMS
message 120S.
130
IBM VM/370 eMS User's Guide
March 30, 1979
The following restrictions apply
disks under CMS:
when you
read
as
data sets
from
os
•
Read-password-protected data sets are not read.
•
BDAM and ISAM 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
(except for user
standard labels on tapes). See "Tape Labels in CMS" for details.
•
Results may be unpredictable if two DCBs
the same time.
access the same data set at
Using the FILEDEF Command
Whenever you execute an as program under CMS that has
output files, or you need to read an as data set onto a
must first identify the files to CMS with the PILEDEF
FILEDEF command in CMS performs the same functions
definition (DD) card in os job control language (JCL): it
input and output files.
input and/or
CMS disk, you
command. The
as the data
describes the
When you enter the PILEDEF command, you specify:
•
The ddname
•
The device type
•
A file identification, if the device type is DISK
•
Type of label on
specified
•
Options (if necessary)
your
tape
file,
if
taFe label
processing
is
Some guidelines for entering these specifications follow.
SPECIPYING THE DDNAME
If the FILEDEP command is issued for a
then the ddname must be the same as the
for the file in the source program.
For
language source program that contains the
INFILE
DCB
program input or output file,
ddna.e or file na.e specified
example, you have an assembler
line:
DDNAME=INPUTDD,MACRF=GL,DSORG=PS,RECPft=P,LRECL=80
Par a particular execution of this program, you want to use as your
input file a CMS file on your A-disk that is named MYINPUT FILE, then,
you must issue a FILEDEF for this file before executing the prograa:
Section 8. Developing
as
programs Under CftS
131
~
March 30, 1979
filedef inputdd disk myinput file a1
If the input file you want to use is on an OS disk accessed as your
C-disk, and it has a data set name of PAYROLL. RECORDS. AUGUST, then your
FILEDEF command might be:
filedef inputdd c1 dsn payroll records august
SPECIFYING THE DEVICE TYPE
For input files, the device type you enter on the FILEDEF command
indicates the device from which you want records read. It can be DISK,
TERMINAL, READER (for input from real cards or virtual cards), or TAPn
(for tape).
Using the above example, if your input file is to be read
from four virtual card reader, the FILEDEF command might be as follows:
filedef inputdd reader
or, if you were reading from a
virtual address 181 (TAP1):
tape attached to your virtual machine at
filedef inputdd tap1
For output files, the device you specify can be DISK, PRINTER, PUNCH,
TAPn (tape), or TERMINAL.
If you do not want any real I/O performed during the execution of a
program for a disk input or output file, you can specify the device type
as DUMMY:
filedef inputdd dummy
ENTERING FILE IDENTIFICATIONS
If you are using a CMS disk file for your input or output, you specify:
filedef ddname disk filename filetype filemode
*
Note that if
is used for the filemode of an output file, unpredictable
results may occur.
The filemode field is optional; if you do not specify it, your A-disk is
assumed. If you want an output file to be constructed in OS simulated
data set format,
you must specify the filemode number as 4.
For
example, a program contains a DCB for an output file with a ddname of
OUTPUTDD, and you are using it to create a CMS file named DAILY OUTPUT
on your B-disk:
filedef outputdd disk daily output b4
If your input file is an OS data
it in several ways:
•
If
the
data
HEALTH~RECORDS,
set on an OS disk, you can identify
set name has only
you can specify:
two
filedef inputdd disk health records b1
132
IBM VM/370 CMS User's Guide
qualifiers,
for
example
Pg. of GC20-1819-2 Rev ftarch 30, 1979 by Supp. SD23-902Q-1 for 57Qa-IJa
•
If it has .ore
enter:
than two qualifiers, you can use
the DSI keyword and
filedef inputdd b1 dsn health records august 197Q
Or you can request a proapt for a coaplete data set naae:
filedef inputdd b1 dsn ?
ENTER DATA SET NAftE:
health.records.august.1974
Section 8. Developing OS prograas Under CBS
132.1
March 30, 1979
132.2
IBM VM/370 eMS User's Guide
March 30, 1979
!2!~:
When you enter a data set name using the DSN keyword, either
with or without a request for prompting, you should omit the device
type specification of DISK,
unless you want to assign a CftS file
identifier, as in the example below.
•
You can also relate an as data set name to a CMS file identifier:
filedef inputdd disk ossim file c1 dsn monthly records
Then you can refer to the OS data set MONTHLY.RECORDS by
CMS file identifier, OSSIM FILE:
using the
state ossim file c
When you do not issue a FILEDEF command for a program input or output
file, or if you enter only the ddname and device type on the FILEDEF
coamand, such as:
filedef oscar disk
then CMS issues a default file definition, as follows:
FILEDEF ddname DISK FILE ddname A1
where ddname is the ddname you assigned in the DDNAftE operand of the DCB
macro in your program or on the FILEDEF command. For example, if you
assign a ddname of OSCAR to an output file and do not issue a FILEDEF
command before you execute the program, then the CftS file FILE OSCAR A1
is created when you execute the program.
SPECIFYING CftS TAPE LABEL PROCESSING
You can use the label operands on the FILEDEF command to indicate that
CMS tape label processing is not desired
(this is the default). If CftS
tape label processing is desired you can use the label operands on the
FILEDEF command to indicate the types of labels on your tape. See "Tape
Labels in CMS" for a description of CMS tape label processing.
SPECIFYING OPTIONS
The FILEDEF command has many options; those mentioned below are a
sampling only.
For complete descriptions of all the options of the
FILEDEF command, see the !~L1IQ ~~~ ~Q!!g~£ g~£ ~g££Q ~~fe£~~£~.
~1Q£!,
~Hj~1,
HjCF~, ~~Q~Q:
If you are using the FILEDEF command to
relate a data control block
(DCB) in a program to an input or output
file, you may need to supply some of the file format information, such
as the record length and block size, on the FILEDEF command line. For
example, if you have coded a DCB macro for an output file as follows:
OUTFILE
DCB
DDNAME=OUT,MACRF=PM,DSORG=PS
then, when you are issuing a FILEDEF for this ddname, you must specify
the format of the file. To create an output file on disk, blocked in OS
simulated data set format, you could issue:
filedef out disk my output file a4 (recfm fb lrecl 80 block 1600
Section 8. Developing OS programs Under CMS
133
March 30, 1979
To punch the output file onto cards, you would issue:
filedef out punch (lrecl 80 recfm f
You must supply file format information on the FILEDEF command line
whenever it is not supplied on the DCB macro, except for existing disk
files.
f]B~:
Usually, when you execute one of the language processors, all
existing file definitions are cleared. If the development of a program
requires you to recompile and re-execute it frequently, you might want
to use the PERM option when you issue file definitions for your input
and output files. For example:
cp spool punch to *
filedef indd disk test file a1 (lrecl 80 perm
filedef outdd punch (lrecl 80 perm
In this example, since you spooled your virtual punch to your own
virtual card reader, output files are placed in your virtual reader. You
can either read or delete them.
All file definitions issued with the PERM option stay in effect until
you log off, specifically clear those definitions, or redefine them:
filedef indd clear
filedef outdd tap1 (lrecl 80
In the above example, the
redefined as a tape file.
definition for
INDD is
cleared; OUTDD
is
When you issue the command:
filedef * clear
all file definitions
option.
are cleared, except those you enter
with the PERM
When a program abends, or when you issue the HX Immediate command,
all file definitions are cleared, including those entered with the PERM
option.
121SP J!QJ2: When you issue a FILEDEF command for an output file and assign
it a CMS file identifier that is identical to that of an existing CMS
file, then when anything is written to that ddname the existing file is
replaced by the new output file. If you want, instead, to have new
records added to the bottom of the existing file, you can use the DISP
MOD option:
filedef outdd disk; new update a1 (disp mod
If the file you want to read is a member of an as partitioned
data set (or a CMS MACLIB or TXTLIB), you can use the MEMBER option to
specify the membername; for example:
1!]MB]~:
filedef test c dsn sys1 maclib (member test
defines the member TEST from the as macro library SYS1.MACLIB.
!!!U~Q~:
This option allows an auxiliary processing routine to receive
control during I/O operating. It is valid only when FILEDEF is executed
by an internal program call and cannot be entered on a terminal command.
For details on how to use this option of the FILEDEF command, see the
!1!LJIQ
134
~Y§!~! f!2g!~!!~!~§ ~~!g~.
IBM VM/370 eMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-X18
Creating CMS Files From
as
Data Sets
If you have data sets on as disks, or on tapes or cards, you can copy
thea into CMS files so that you can edit, modify, or manipulate them
with CMS commands. The CMS MOVEFILE command copies as (or eMS) files
from one device to another. You can move data sets from any valid input
device to any valid output device.
Section 8. Developing as Programs Under eMS
134.1
March 30, 1919
134.2
IBM VM/370 eMS User's Guide
Before using the MOVEFILE command, you must define the input and
output data sets or files and assign them ddnames using the FILEDEF
command. If you use the ddnames INMOVE and OUTMOVE, then you do not
need to specify the ddnames when you issue the MOVEFILE co.mand. For
example, the following sequence of commands copies a CMS disk file into
your virtual card punch:
filedef inmove disk disk in file a1
filedef outmove punch
movefile
The result of these
issued the com.and:
punch diskin file
commands is
effectively the
same as
if you
had
(noheader
The example does, however, illustrate the basic relationship between the
FILEDEF and MOVEFILE commands. In addition to the MOVEFILE command, if
the OS input data set is on tape or cards, you can use the TAPPDS or
READCARD command to create CMS files. These are also discussed below.
~QR!l!~ ~]2Y]!1!A1
DATA SETS FROM DISK: The MOVEFILE command copies a
sequential OS disk data set-froi-a--read-only os disk into an integral
CMS file on a CMS read/write disk. You use FILEDEF commands to identify
the input file disk mode and data set name:
filedef inmove c1 dsn sales manual
the CMS output file's disk location and fileid:
filedef outmove disk sales manual a1
and then you issue the MOVEFILE command:
)
movefile
~QR!!!~ ~Ai1!I!Q!ED
Q!!A ~!!~ I~Q~ QI~~: The MOVEFILE command can copy
partitioned data sets (PDS) into CMS disk files, and create separate CMS
files for each member of the data set. You can have the entire data set
copied, or you can copy only a selected member. For example, if you
have a partitioned data set named ASSEMBLE. SOURCE whose members are
individual assembler language source files, your input file definition
might be:
filedef inmove c1 dsn assemble source
To create individual CMS ASSEMBLE files, you would issue the output file
definition as:
filedef outmove disk qprint assemble a1
Then use the PDS option of the MOVEFILE command:
movefile (pds
When the eMS files are created, the filetype on the output
definition is used for the filetype and the member names are
instead of the CMS filename you specified.
If you want to copy only a
option of the FILEDEF command:
)
single member, you
filedef inmove disk assemble source c
can use
file
used
the MEMBER
(member qprint
Section 8. Developing OS programs Under CMS
135
and omit the PDS option on the MOVEFILE command:
movefile
Figure 13 summarizes
from OS data sets.
Input File:
the various ways that you can
create CMS files
An OS seguential data set named: COMPUTE. TEST. RECORDS
CMS Output File
Source
CMS Command Examples
OS RIO
C-disk
filedef outdd disk compute records a1
movefile indd outdd
-------------------------------------------------------------------,COMPUTE RECORDS A1
filedef indd c1 dsn compute test records
Disk:
TEST RECORDS A1
filedef inmove tap1 (lrecl 80
filedef outmove disk test records a1
movefile
Tape:
181
Cards
tappds newtest compute (nopds
NEWTEST COMPUTE A1
filedef cardin reader
filedef diskout disk compute cards a1
lIIovefile cardin diskout
COMPUTE CARDS 11
readcard compute test
COMPUTE TEST 11
Input file: OS partitioned data set named: TES~.CISES
Members named: SIMPLE, COMPLEX, MIXED
Source
Disk:
OS R/O
C-disk
Tape:
182
CMS Command Examples
CMS Output File(s)
filedef infile disk test cases c1
filedef out file disk new testcase a1
movefile infile outfile (pds
SIMPLE TESTCISE 11
COMPLEX TESTCISE 11
MIXED TESTCISE
filedef in c1 dsn test cases (member simple
filedef run disk
lDovefile in run
FILE RUN 11
tappds
*
testrun
SIMPLE TESTRUN 11
COMPLEX TESTRUN A1
MIXED TESTRUN 11
(tap2
Figure 13. Creating CMS Files From OS Data Sets
Using eMS Libraries
CMS provides two types of libraries to aid in OS program development:
•
Macro litraries contain macro definitions and/or copy files
•
Text, or program
(compiler output)
libraries
contain
relocatable
object
programs
These CMS libraries are like OS partitioned data sets; each has a
directory and members. Since they are not like other CMS files, you
create, update, and use them differently than you do other CMS files.
Although these library files are similar in function to OS partitioned
data sets, OS macros should not be used to update them. Macro libraries
are discussed below; text libraries are discussed under "TEXT Libraries
(TXTLIBs)" later in this section.
A CMS macro library has a filetype of MACLIB. You can create a MACLIB
from files with filetypes of MACRO or COPY. A MACRO file may contain
macro definitions; COpy files contain predefined source statements.
(
136
IBM VM/370 CMS User's Guide
When you want to assemble or compile a source program that uses macro
or copy definitions, you must ensure that the library containing the
code is identified before you invoke the compiler. Otherwise, the
library is not searched. You identify libraries to be searched using the
GLOBAL command. For example, if you have two MACLIBs that contain your
private macros and copy files whose names are TESTMIC MACLIB and
TESTCOPY MACLIB, you would issue the command:
global maclib test mac testcopy
The libraries you specify on a GLOBAL command line are searched in the
order you specify them.
A GLOBAL command remains in effect for the
remainder of your terminal session, until you issue another GLOBAL
MACLIB command or re-IPL CMS. To find out what macro libraries are
currently available for searching, issue the command:
query maclib
You can reset the libraries or the
command.
search order by reissuing the GLOBAL
THE MACLIB COMMAND
The MACLIB command performs a variety of functions. You use it to:
•
•
•
•
Create the MACLIB (GEN function)
Add, delete, or replace members (ADD, DEL, and REP functions)
Compress the MACLIB (COMP function)
List the contents of the MAC LIB (MAP function)
Eescriptions of these MACLIB command functions follow.
XYD£1i2D: The GEN (generate) function creates a CMS macro library
from input files specified on the command line. The input files must
have filetypes of either MACRO or COPY. For example:
~~B
maclib gen osmac access time put regequ
creates a macro library with the file identifier OSMAC MACLIB
macros existing in the files with the file identifiers:
A1 from
ACCESS { MACRO}, TIME { MACRO}, PUT { MACRO}, and REGEQU {MACRO}
COpy
COpy
COpy
COpy
If a file named OSMAC MACLIB A1 already exists, it is erased.
Assume that the files ACCESS MACRO, TIME COPY, PUT MACRO, and REGEQO
COpy exist and contain macros in the following form:
ACCESS MACRO
-----------GET
PUT
TIME COPY
--------*COPY TTIMER
POT MACRO
--------PUT
TTIMER
*COPY STIMER
STIMER
REGEQO COpy
----------XREG
YREG
)
Section 8. Developing
as
Programs Onder CMS
137
The resulting file, OSMAC MACLIB Al, contains the members:
GET
PUT
TTIMER
STIMER
PUT
REGEQU
The PUT macro, which appears twice in the input to the command, also
appears twice in the output~ The MACLIB command does not check for
duplicate macro names. If, at a later time, the PUT macro is requested
from OSMAC MACLIB, the first PUT macro encountered in the directory is
used.
When COpy files are added to MACLIBs, the name of the library member
is taken from the name of the COpy file, or from the *COPY statement, as
in the file TIME COpy, above. Note that although the file REGEQU COpy
contained two macros, they were both included in the MACLIB with the
name REGEQU. When the input file is a MACRO file, the member name(s) are
taken from macro prototype statements in the MACRO file.
1YD£!!QD: The ADD function appends new members to an existing macro
library. For example, assume that OSMAC MACLIB 11 exists as created in
the example in the explanation of the GEN function and the file DCB COpy
exists as follows:
A~~
*COPY DCB
DCB macro definition
*COPY DCBD
DCBD macro definition
If you issue the command:
maclib add osmac dcb
the resulting OSMAC MACLIB Al contains the members:
GET
PUT
TTIMER
STIMER
PUT
REGEQU
DCB
DCBD
1YD£!!QD: The REP (replace) function deletes the directory entry for
the macro definition in the files specified. It then appends new macro
definitions to the macro library and creates new directory entries. For
example, assume that a macro library MYMAC MICLIE contains the members
A, B, and C, and that the following command is entered:
~~E
maclib rep mymac a c
The files represented by file identifiers A MACRO and C MACRO each have
one macro definition. After execution of the command, MYMAC MACLIB
contains members with the same names as before, but the contents of 1
and C are different.
1YD£!!QD: The DEL (delete) function removes the specified macro name
from the macro library directory and compresses the directory so there
are no unused entries. The macro definition still occupies space in the
library, but since no directory 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:
~~1
maclib del osmac get put ttimer dcb
(
138
IBM VM/370 CMS User's Guide
March 30, 1979
deletes macro names GET, PUT, TTIMER, and DCB from the directory of the
macro library named OSMAC MACLIB. Assume that OSMAC exists as in the ADD
function example. After the above command, OSMAC MACLIB contains the
following members:
STIMER
PUT
REGEQU
DCBD
COMP Function: Execution of a MACLIB command with the DEL or REP
functionS--can leave unused space within a macro library. The COMP
(compress)
function removes any macros that do not have directory
entries. This function uses a temporary file named MACLIB CMSUT1. For
example, the command:
maclib camp mymac
compresses the library MYMAC MACLIB.
MAP Function: The MAP function creates a list containing the name of
each-macro--in the directory, the size of the macro, and its position
within the macro library. If you want to display a list of the members
of a MACLIB at the terminal, enter the command:
maclib map mylib (term
The default option, DISK, creates a file on your A-disk, which has a
filetype of MAP and a filename corresponding to the filename of the
MACLIB. If you specify the PRINT option, the list is spooled to your
virtual printer.
!~te:
TERM and PRINT options will erase the old MAP file.
The following CMS commands have MEMBER
reference individual members of a MACLIB:
•
•
•
•
options, which
allow you
to
PRINT (to print a member)
PUNCH (to punch a member)
TYPE (to display a member)
FILEDEF (to establish a file definition for a member)
You can use the CMS editor to create MACRO and COpy files and then
use the MACLIB command to place the files in a library. Once they are
in a library, you can erase the original files.
To extract a member from a macro library, you can use either the
PUNCH or the MOVEFILE command. If you use the PUNCH command you can
spool your virtual card punch to your own virtual reader:
cp spool punch to
*
Then punch the member:
punch testmac maclib (member get noheader
and read it back onto disk:
readcard get macro
Section 8. Developing OS Programs Under CMS
139
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. S1::23-9024-1 for 5748-XX8
In the above example, the member was punched with the NOHEADER option of
the PUNCH coamand,so that a name could be assigned on the READCARD
co •• and line. If a header card had been created for the file, i t wou1d
have indicated the filename and filetype as GET MEMBER.
If you use the MOVEFILE command, you must issue a file definition fer
the input member name and the output macro or copy name before entering
the MOVEFILE command:
filedef inmove disk testcopy maclib (member enter
filedef outmove disk enter copy a
movefile
This example copies the member ENTER from
MACLIB into a CMS file named ENTER COpy~
the macro
library TESTCOPY
When you use the PUNCH or MOVEFILE commands to extract members froa
CMS MACLIBs, each member is followed by a II record, which is a MACLIB
delimiter.
You can edit the file and use the DELETE subcommand to
delete the II record.
If you wish to
COpy FILE command.
move
th~
coaplete
MACLIB to
another file,
use the
The macro libraries that are on the .system disk contain CMS and
assembler language macros that you may want to use in your programs:
•
I •
OS
CMSLIB MACLIB contains the CMS macros.
DMSB20 MACLIB contains the CMS macros
Extensions (Program No. 5748-XX8).
for
VM/370
Basic
System
•
OSMACRO MACLIB contains the OS macros
or those that require no CMS support.
that CMS supports or simulates
•
OSMACR01 MACLIB contains" the macros CMS does not support or simulate.
(You can assemble programs in CMS that contain these macros, but you
must execute them in an OS virtual machine.)
•
TSOMAC MACLIB contains TSO macros.
•
DOSMACRO MACLIB contains macros used in CMS/DOS.
To obtain a list of the macros in any of these libraries, use the MAP
function of the MACLIB command.
USING OS MACRO LIBRARIES
If you want to assemble source programs that contain macro statements
that are defined in macro libraries on your OS disks, you can use the
FILEDEF command to identify them to CMS so that you can name them when
you issue the GLOBAL command. For example, the commands:
filedef cmslib disk temp maclib c dsn test asm macros
global maclib temp
allow you to access the
accessed as your C-disk.
140
macro library
IBM VM/370 CMS User's Guide"
TEST.ASM.~ACROS
on the
OS disk
Assembling Programs in eMS
To assemble assembler language source programs into object module
for.at, you can use the ASSEMBLE command, and sFecify assembler options
on the command line; for example:
assemble .myfile (print
assembles a source program named MIFILE ASSEMBLE and directs the output
listing to the printer. All of the ASSEMBLE command options are listed
in the !~LJ1Q £~~ £Q!~~~~ ~~~ ~~£EQ ~~f~E~!£~·
When you invoke the ASSEMBLE command specifying a file with the
filetype of ASSEMBLE, CMS searches all of your accessed disks, using the
standard search order, until it locates the sFecified file.
When the
assembler creates its output listing and text deck, it creates files
with filetypes of LISTING and TEXT, and writes them onto disk according
to the following priorities:
1.
If the source file is on a read/write disk, the TEXT
files are written onto that disk.
2.
If the source file is on a read-only extension of a read/write
disk, the TEXT and LISTING files are written onto the parent disk.
3.
If the source file is on any other read-only disk, the
LISTING files are written onto the A-disk.
In all of the above cases, the TEXT and LISTING files
that is the same as the input ASSEMBLE file.
)
and LISTING
TEXT and
have a filename
The input and output files used by the assembler are assigned by
FILEDEF commands that CMS issues internally when the assembler is
invoked. If you issue a FILEDEF command using one of the assembler
ddna.es before you issue the ASSEMBLE command, you can override the
default file definitions.
The ddname
enter:
for the source
input file
(SISIN) is ASSEMBLE.
If you
filedef assemble reader
assemble sample
then the assembler reads your input file from your card reader, and
assigns the filename SAMPLE to the output TEXT and LISTING files.
Iou could
entering:
assemble a
source
file
directly
from
an
as
disk
by
filedef assemble disk myfile assemble b4 dsn os source file
assemble myfile
In this example, the CMS file identifier MIFILE ASSEMBLE is assigned to
the data set as. SOURCE. FILE and then assembled.
LISTING and TEXT are the ddnames assigned to the SYSPRINT and SISLIN
output of the assembler. Iou might assign file definitions to override
these defaults as follows:
filedef listing disk assemble listfile a
filedef text disk assemble textfile a
assemble source
In this example, output from the assembly of the file, SOURCE ASSEMBLE,
is written to the files, ASSEMBLE LISTFILE and ASSEMBLE TEXTFILE.
Section 8. Developing
as
Programs Under CMS
143
The ddnames PUNCH and CMSLIB are used for SYSPUNCH and SYSLIB data
sets. PUNCH output is produced when you use the DECK option of the
ASSEMBLE command. The default file definition for CMSLIB is the macro
library CMSLIB MACLIB, but you must still issue the GLOBAL command if
you want to use it.
Executing Programs
After you have assembled or compiled a source program you can execute
the TEXT files that were produced by the assembly or compilation. You
may not, however, be able to execute all your OS programs directly in
CHS. There are a number of execution-time restrictions placed on your
virtual machine by VM/370. You cannot execute a program that uses:
•
•
•
•
Multitasking
More than one partition
Teleprocessing
ISAM macros to read or write files
The above is only a partial list, representing those restrictions with
which you might be concerned. For a complete list of restrictions, see
the !~LJ1Q El~n~i~g ~ng ~I§!~! Q~n~!g!!Qn Qy!g~.
EXECUTING TEXT FILES
TEXT files, in CMS, are relocatable, and can be executed simply by
loading them into virtual storage with the LOAD command and using the
START command to begin execution. For example, if you have assembled a
source program named CREATE, you have a file named CREATE TEXT. You can
issue the command:
load create
which loads the relocatable object file into storage,
execute it, you can issue the START command:
and then,
to
start
In the case of a simple program, as in the above example, you can
load and begin execution with a single command line, using the START
option of the LOAD command:
load create (start
When you issue the START command or LOAD command with the START
option, control is passed to the first entry point in your program. If
you have more than one' entry point and you want to begin execution at an
entry point other than the first,
you can specify the alternate entry
point or CSECT name on the START command:
start create2
When you issue the LOAD command specifying the filename of a TEXT file,
CMS searches all of your accessed disks for the specified file.
If your pro~ram expects a parameter list to be passed (via register
1), you can specify the arguments on the START command line. If. you
en~er arguments, then you must specify the entry point:
start
144
*
name1
IBM VM/370 CMS User's Guide
(
When you specify the entry point as an asterisk (*) it
you want to use the default entry point~
indicates that
You can issue the FILEDEF command to define input and output files any
time before you begin program execution.
You can issue all your file
definitions before loading any TEIT files, or issue them during the
loading process. You can find out what file definitions are currently
in effect by issuing the FILEDEF command with no operands:
filedef
You can also use the FILEDEF operand of the QUERY command.
TEIT LIBRARIES (TITLIBS)
You may want to keep your TEIT files in text libraries, that have a
filetype of TITLIB. Like MACLIBs, TITLIBs have a directory and members.
TITLIBs are created and modified by the TITLIB command, which has
functions similar to the MACLIB command:
•
•
•
•
The
The
The
The
GEN
ADD
DEL
MAP
function
function
function
function
creates the TITLIB.
adds members to the TITLIB.
deletes members and compresses the TITLIB.
lists members.
There is no REP function; you must use a DEL followed by an ADD to
replace an existing member. The CMS commands that recognize MACLIBs as
special filetypes also recognize TITLIBs, and allow you to display,
print, or punch,TITLIB members.
The TITLIB command reads the object files as it writes them into the
library, and creates a directory entry for each entry point or CSECT
name. If you have a TEIT file named MYPROG, which has a single routine
named BEGIN, and create the TITLIB named TESTLIB as follows:
txt lib gen test lib myprog
TESTLIB contains no entry for the name MYPROG;
membername,BEGIN to reference this TITLIB member.
you must
specify the
When you want to load members of TITLIBs into storage to execute them
(just as you execute TEIT files), you must issue the GLOBAL command to
identify the TITLIB:
global txt lib test lib
load begin (start
'When you specify more than one TITLIB on the GLOBAL command line, the
order of search is established for the TITLIBs. However, if the AUTO
option is in effect (it is the default), CMS searches for TEIT files
before searching active TITLIBs.
)
When the TITLIB command processes a TEIT file, it writes an LDT
(loader terminate) card at the end of the TEIT file, so that when a load
request is issued for a TITLIB member, loading terminates at the end of
the member.
If you add OS linkage editor control statements to the TEIT
file (using the CMS editor) before you issue the TITLIB command to add
the file to a TITLIB, the control statements are processed as follows:
section 8. Developing OS programs Under CMS
145
!!~:
A NAME statement causes the TXTLIB command to create the directory
entry for the member using the specified name. Thereafter, when you want
to load that member into storage or delete it from the TXTLIB you must
refer to it by the name specified on the NAME statement.
If you use an ENTRY statement, the entry point you specify is
validated and checked for a duplicate. If the entry point name is valid
and there are no duplicates in the TEXT file, the entry name is written
in the LDT card.
otherwise, an error message' is issued.
When this
member is loaded, execution begins at the entry point specified. (See
the following "Determining Program Entry Points.")
~!TR!:
!1I!~:
An entry is created in the directory for the ALIAS name you
specify. A maximum of 16 alias names can be used in a single text deck.
You may load the single member and execute it by referring to the alias
name, but you cannot use the alias name as the object of v-type address
constant (VCON), because the address of the member cannot be resolved.
~~TS~J:
Information you specify on the SETSSI card is
26 through 33 of the LDT card.
written in bytes
All other OS linkage editor control statements are ignored by the
TXTLIB command and written into the TXTLIB member. When you attempt to
load the member, the CMS loader flags these cards as invalid.
RESOLVING EXTERNAL REFERENCES
There is no real linkage editor in CMS; the link-edit function, that of
locating external references and loading additional object modules into
storage, is performed by the CMS loader.
The CMS loader loads files
into storage as a result of a LOAD or INCLUDE command, or when you issue
a dynamic load request from a program (using the OS macros LOAD, LINK,
or XCTL).
When a file is loaded, the loader checks for unresolved references;
if there are any, the loader searches your disks for TEXT files with
filenames that match the external entry name. When it finds a match, it
loads the TEXT file into storage. If a TEXT file is not found, the
loader searches any available TXTLIBs for members that match; if a match
is found, it loads the member.
If there are still unresolved references, for example, if you load a
program that calls routines PRINT and ANALYZE but the loader cannot
locate them, you receive the message:
THE FOLLOWING NAMES ARE UNDEFINED:
PRINT
ANALYZE
You can issue the INCLUDE command to load additional TEXT files or
TXTLIB members into storage so the loader can resolve any remaining
references.
For eXample, if you did not identify the TXTLIB that
contains the routines you want to call, you may enter the GLOBAL command
followed by the INCLUDE command:
global txt lib newlib
include print analyze (start
This situation might also occur if you have TEXT files with filenames
that are different from the CSECT names; you must explicitly issue LOAD
and INCLUDE commands for these files.
146
IBM VM/370 CMS User's Guide
(
At execution time, if there are still any unresolved references,
their addresses are all set to 0 by the loader, so any attempt to
address them in a program may result in a program check.
The INCLUDE command has the same format and option list (with one
exception) as the LOAD command. The main difference is that when you
issue the INCLUDE command the loader tables are not reset; if you issue
two LOAD commands in succession, the second LeAD command cancels the
effect of the first, and the pointers to the files loaded are lost.
Conversely, the INCLUDE command, which you must issue when you want
to load additional files into storage, should not be used unless you
have just issued a LOAD command.
You may sFecify as many INCLUDE
commands as necessary following a LOAD command to load files into
storage.
CONTROLLING THE CMS LOADER
The LOAD and INCLUDE commands allow you
You can:
to specify a number of options.
•
Change the entry point to which
execution begins (RESET option).
control
is
to be
passed
when
•
Specify the location in virtual storage at Which you
to be loaded (ORIGIN option).
•
Control how CMS resolves references and handles duplicate CSECT names
(AUTO, LIB, and DUP options).
•
Clear storage to binary zeros before loading files (CLEAR option).
want the files
When the LOAD and INCLUDE commands execute, they produce a load map,
indicating the entry points loaded and their virtual storage locations.
You may find this load map useful in debugging your programs. If you do
not specify the NOMAP option, the load map is written onto your A-disk,
in a file named LOAD MAP AS. Each time you issue the LOAD command, the
old file LOAD MAP is erased and the new load map replaces it. If you do
not want to produce a load map, specify the NOMAP option.
You can find details
discussion of the LOAD
~~fe!~~£~.
about these, and other options
command in !~L11~ ~~~ £Qmmg~g
under
gDg
the
Ag£!Q
In addition to the options provided with the LOAD and INCLUDE commands
that assist you in controlling the execution of TEXT files, you can also
use loader control statements. These can be inserted in TEXT files,
using the CMS editor. The loader control statements allow you to:
)
•
Set the location counter to specify the
TEXT file is to be loaded (SLC statement).
addres~
at which
the next
Section 8. Developing OS Programs Under CMS
147
TEXT file, and change
modifications (Replace
the
and
•
Modify instructions and constants in a
length of the TEXT file to accomodate
Include Control Section statements) •
•
Change the entry point (ENTRY statement).
•
Nullify an external reference so that it dces not receive control
when it is called, and you do not receive an error message when it is
encountered (LIBRARY statement).
These statements are also described under the LOAD command in VML37.Q
£.QU.§!!,g ,g1!,g !1.§£!:.Q !!~!~!:~.n£~,.
~11~
When you load a single TEXT file or a TXTLIB membe~ into storage for
execution, the default entry point is the first CSECT name in the object
file loaded. You can specify a different entry point at which to start
execution either on the LOAD (or INCLUDE) command line with the RESET
option:
load myprog (reset beta
where BETA is the alternate entry point of your
specify the entry point on the START command line:
program, or
you can
start beta
When you load multiple TEXT files (either explicitly or implicitly,
by allowing the loader to resolve external references), you also have
the option of specifying the entry point on the LOAD, INCLUDE, or START
command lines.
If you do not specifically name an entry point, the loader determines
the entry point for you, according to the following hierarchy:
1.
An entry point specified on the START command
2.
Th~ last entry specified with the RESET option on a LOAD or INCLUDE
command
3.
The name on the last ENTRY statement that was read
4.
The name on the last
that was read
5.
The name on the first assembler- or compiler-produced END statement
that was read
6.
The first byte of the first control section loaded
LDT statement
that contained an
entry name
For example, if you load a series of TEXT files that contain no
control statements, and do not specify an entry point on the LOAD,
INCLUDE, or START commands, execution begins with the first file that
you loaded. If you want to control the execution of program subroutines,
you should be aware of this hierarchy when you lead programs or when you
place them in TXTLIBs.
(
148
IBM VM/370 CMS User's Guide
An area of particular concern is when you issue a dynamic load (with
the OS LINK, LOAD, or ICTL macros)
from a program, and you call members
of CMS TITLIBs. The CMS loader determines the entry point of the called
program and returns the entry point to your program. If a TITLIB member
that you load has a VCON to another TITLIB member, the LDT card from the
second member may be the last LDT card read by the loader. If this LDT
card specifies the name of the second member, then CMS may return that
entry point address to your program, rather than the address of the
first member.
CREATING PROGRAM MODULES
When your programs are debugged and tested, you can use the LOAD and
INCLUDE commands, in conjunction with the GENMOD command, to create
program modules. A module is a nonrelocatable file whose external
references have been resolved. In CMS, these files must have a filetype
of MODULE.
To create a program module, load the TEIT files or
into storage and issue the GENMOD command:
TITLIB members
load create analyze print
genmod process
In this example, PROCESS is the filename you are assigning the
module; it will have a filetype of MODULE. You could use any name; if
you use the name of an existing MODULE file, the old one is replaced.
To execute the program composed of
and PRINT, enter:
the source files CREATE, ANALYZE,
process
If PROCESS requires input and/or output files, you will have to define
these files before PROCESS can execute properly; if PROCESS expects
arguments passed to it, you can enter them following the MODULE name;
for example:
process test1
For more information on creating program modules, see
Programming for the CMS Environment."
"Section 13.
USING EIEC PROCEDURES
During your program development and testing cycle, you may want to
create EIEC procedures to contain sequen~es of CftS commands that you
execute frequently. For example, if you need a number of MACLIBs,
TITLIBs, and file definitions to execute a particular program, you might
have an EIEC procedure as follows:
)
Section 8. Developing OS programs Under CMS
149
&CONTROL ERROR TIME
&ERROR SEXIT &RETCODE
GLOBAL MACLIB TESTLIB OSMACRO OSMACR01
ASSEMBLE TESTA
PRINT TESTA LISTING
GLOBAL TXTLIB TESTLIB PROGLIB
ACCESS 200 E
&BEGSTACK
OS.TEST3.STREAM.BETA
&END
FILEDEF INDD1 E DSN ?
FILEDEF INDD2 READER
FILEDEF OUTFILE DISK TEST DATA A1
LOAD TESTA (START
&IF &RETCODE = 100 &GOTO -RET100
&IF &RETCODE = 200 &GOTO -RET200
&EXIT &RETCODE
-RET100 &CONTINUE
-RET200 &CONTINUE
The &CONTROL and &ERROR control statements in the EXEC procedure
ensure that if an error occurs during any part of the EXEC, the
remainder of the EXEC does not execute, and the execution summary of the
EXEC indicates the command that caused the error.
Note that for the FILEDEF command entered with the DSN ? operand,
you must stack the response before issuing the FILEDEF command. In this
example, since the OS data set name has more than eight characters, you
must use the &BEGSTACK control statement to stack it. If you use the
&STACK control statement, the EXEC processor truncates all words to
eight characters.
When your program is finished executing, the EXEC special variable
&RETCODE indicates the contents of general register 15 at the time the
program exited. You can use this value to perform additional steps in
your EXEC procedure. Additional steps are indicated in the preceding
example by ellipses.
For detailed information on creating
Learning to Use EXEC."
EXEC procedures, see
"Part 3.
c
150
IBM VM/310 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
Section 9. Developing DOS Programs underCMS
You can use CMS to create, compile, execute and debug DOS programs
written in assembler, COBOL, or PL/I programming languages.
CMS
simulates many functions of the Disk Operating System '(DOS/VSE) so that
you can use the interactive facilities of VM/370 to develop your
programs, and then execute the~ in a DOS virtual machine.
It
This section tells you how to use the CMS/DOS environment.
describes the CMS commands you can use to manipulate DOS disks and DOS
files and CMS/DOS commands you can use to simulate the functions of
DOS/VSE:
•
•
•
•
•
•
•
•
•
•
The CMS/DOS environment
Using DOS files on DOS disks
Using the ASSGN command
Using the DLBL command
Using DOS libraries in CMS/DOS
Using macro libraries
DOS assembler languag~ macros sUFPorted
Assembling source programs
Link-editing programs in CMS/DOS
Executing programs in CMS/DOS
For a practice terminal session using the commands and techniques
presented in this section, see "Appendix D: Sample Terminal Sessions."
eMS/DOS is neither CMS nor is it DOS; it is a composite, and its
vocabulary contains both CMS and DOS terms. CMS/DOS performs many of
the same functions as DOS, but where, under DOS, a function is initiated
by a control card, in eMS it is initiated by a command. Many CMS/DOS
commands, therefore, have the same names as the DOS control statement
that '~erforms the same function.
In' those cases where the control
statement you would use in DOS and the command you use in eMS are
different, the differences are explained. For the most part, whenever a
term that is familiar to you as a DOS ter~ is used, it has the same
meaning to CMS/DOS, unless otherwise indicated.
The eMS/DOS Environment
After you have loaded CMS into your
CMS/DOS environment by issuing:
virtual machine you can
enter the
set dos on
If you want to access a DOS system residence volume during your eMS/DOS
terminal session, you should link to and access the disk that contains
the DOS SYSRES before you issue the SET command. For example, if you
share the system residence volume with other users and it is in your
directory at virtual address 390, you .ould issue the command:
access 390 g
and then issue the SET command as follows:
Section 9. Developing DOS Programs Under eMS
151
Pg. of GC20-1819-2 Rev ftarch 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
set dos on g
to indicate that the SYSRES is located on your G-disk. If you are going
to use the CftS/DOS librarian facilities to access any of the libraries
on the system residence volume, you must enter the CftS/DOS environment
this way.
If you are usingCftS exclusively for DOS applications, you .could put
the ACCESS and SET DOS ON commands in your PROPILE EXEC.
If you are going to use access method services functions in CftS/DOS,
or execute functions that read or write VSAM data sets, you must use the
YSAft option of the SET DOS ON command:
set dos on g (vsam
When you are using CftS/DOS, you can use your virtual machine just as
you would if you were in the eMS environment; but you cannot execute any
CftS commands or program modules that load and/or use OS macros. The
SCRIPT command, for example, uses OS macros, and is therefore invalid in
the CftS/DOS environment.
You have, however, in addition to the CP and CftS commands available,
a series of commands that simulate DOS/VSE functions. Except for the
DLBL and DOSLIB commands, these commands or oFerands should only be
issued in the CftSjDOS environment.
The CMS/DOS commands are summarized in Figure 15.
DL/I in the eMS/DOS Environment
in the CMS/DOS
Batch DL/I programs
can be written and tested
environment. This includes all programs written in COBOL, PL/I, and
Assembler language.
Data base description generation and program specification block
generation can also be executed. However, the aFplication control block
generation must be submitted to a DOS/VSE virtual machine for execution.
The data tase recovery and reorganization utilities must also be
executed in a DOS/VSE virtual machine.
This support provides the ability to:
•
Interactively code DL/I control blocks
contain imbedded DL/I calls.
and application programs that
•
Store and maintain macros used to generate DL/I control blocks, and
programs created under CMS, in the CMS library. Production libraries
are thus isolated from the test environment.
•
Modify and compile
EXEC facilities.
•
Link-edit and execute batch DL/I programs either interactively or in
CMSBATCH.
Online DL/I application programs requiring access to
CICS/YS must be
submitted to a DOS/VSE
virtual machine fer
link-editing, cataloging, and execution.
programs using the CMS/DOS
text manipulation and
The following restrictions apply:
•
152
All the existing guidelines and restrictions that apply to VSAft data
set creation, maintenance, and aFplication program use apply to DL/I
data sets.
IBM VM/370 CftS User's Guide
March 30, 1979
Command
Function
ASSGB
Relates system and programmer logical units to physical
devices.
DLBL
Relates a program ddname (filename) to a real disk file
so you can perform input/output operations on it.
DOSLIB
Lists or deletes phases from a eftS/DOS phase library, or
compresses the library.
DOSLKED
Link-edits CMS TEXT files or DOS phases from system or
private relocatable libraries.
DSERV
Displays the directories of DOS libraries.
DOSPLI
An EXEC procedure that invokes the DOS/VS PL/I compiler.
ESERV
An EXEC procedure that invokes the ESERV utility functions
on edited assembler language macros.
FCOBOL
An EXEC procedure that invokes the DOS/VS COBOL co.piler.
FETCH
Loads executable phases from a DOSLIE or DOS library into
storage for execution, and optionally starts execution.
GLOBAL
When you want DOSLIBs searched for executable phases or
macro libraries searched for macro definitions, you must
identify them with the GLOBAL command.
LISTIO
Displays the current assignments of system and programmer
logical units, and optionally creates an EXEC file to
contain the information.
OPTION
Sets or changes the options in effect for the DOS/VS
COBOL compiler.
QUERY
Use QUERY command operands to list current DLBL defintions
(QUERY DLBL), to determine whether or not you are in
the CMS/DOS environment (QUERY DOS), the setting of the
UPSI byte (QUERY UPSI), the DOSLIBs identified by GLOBAL
commands (QUERY DOSLIB or QUERY LIBRARY), the current
number of lines per page (QUERY DOSLNCNT), which options
are in effect for the COBOL compiler (QUERY OPTION). or to
find out whether you have set a virtual partition size
(QUERY DOSPART).
PSERV
Creates CMS files with a filetype of PROC from the DOS/VS
procedure library, or displays, prints or punches
procedures.
RSERV
Copies a relocatable module from a DOS library and places
it in a CMS file with a filetype of TEXT, or displays,
prints, or punches modules.
SET
The SET command has operands that allow you to enter or
leave the CMS/DOS environment (SET DOS ON or SET DOS OFF),
to set the number of SYSLST lines per page (SET DOSLBCNT).
to set the UPSI byte (SET UPSI). and to set a virtual
partition size (SET DOSPART) •
SSERV
Creates CMS COPY files from books on DOS source statement
libraries.
Figure 15. CMS/DOS Commands and
CMS/DOS
CMS Commands with Special
Operands for
Section 9. Developing DOS Programs Under CMS
153
Pg. of GC20-1819-2 Rev March 30, 1979 bySupp. SD23-9024-1 for 5748-XX8
•
The CMS/DOS restriction on
SHSAM and HSAM.
writing to
sequential files
applies to
•
To assemble a DBD or PSB under CMS/DOS, you must first copy the
DBDGEN and PSBGEN macros from the DOS/VSE source statement library to
a CMS MACLIB.
For more information about using DL/I in the eMS/DOS environment, see
~1Ll ~Q~L!~ §~~~£g1!g~ Infg£~g!!g~·
Using DOS Files on DOS Disks
You can have DOS disks attached to your virtual machine by a directory
entry or you can link to a DOS disk with the LINK command. You can use
the ACCESS command to assign a mode letter to the disk:
access 155 b
and the RELEASE command to release it:
release b
Except for VSAM disks, you cannot write on DOS disks, or update DOS
files on them. You can, however, execute programs and CMS/DOS commands
that read-from these files,
and you can use the LISTDS command to
display the file-ids of files on a DOS disk; for example:
listds b
You can also verify the existence of a particular file.
the file-id is NEW.TEST.DATA you can enter:
For example, if
listds new test data b
You can use this form only if the file-id has one- to eight-character
qualifiers separated by periods. If the file-id of the DOS file you
want to verify contains embedded blanks, for example NEW.TEST DATA, then
you have to enter the LISTDS commands with a question mark:
listds ? b
CMS responds:
ENTER DATA SET NAME:
and you can enter the exact file-id:
new.test data
If the data set exists, you receive a response:
FM DATA SET NAME
B NEW. TEST DATA
READING DOS FILES
Under CMS/DOS, you can execute programs that read DOS sequential (SAM)
files; you can also execute programs that read and write VSAM files.
You cannot,
however, execute programs to read direct (DAM)
or ihdexed
sequential (ISAM) DOS files.
154
IBM VM/370 CMS User's Guide
March 30, 1979
Complete information on using CMS to access and manipulate VSAM files
is described in "Section 10. Using Access Method Services and VSAM In
CMS and CMS/DOS." The discussion below lists the restrictions placed on
reading SAM files.
CMS cannot read DOS files that:
•
Have the input security indicator on.
•
Contain more than 16 user labels 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.)
•
Multivolume files are read as single-volume
Are multivolume files.
There is no
files.
End of volume is treated as end of file.
end-of-volume switching.
•
Have user labels.
User labels in user-labeled files are bypassed.
CMS does net support duplicate volume labels; you cannot access more
than one volume with the same six-character label while you are using
CMS/DOS.
CREATING CMS FILES FROM DOS LIBRARIES
You can create CMS files from existing DOS files on DOS disks. C~S
simulates the DOS librarian functions DSERV, RSERV, SSERV, ESERV, and
PSERV with commands of the same names; you can use these CMS/DOS
commands to create CMS files from relocatable, source statement, or
procedure libraries located either on the DOS system residence volume or
in private libraries.
The functions are fully described later in this
section.
If you want to create CMS files from DOS files that are not cataloged in
libraries or from DOS files on tape, you can use the MOVEFILE command.
The MOVEFILE command allows you to copy a file from one device to
another device of the same or a different type. Before issuing the
MOVEFILE command, the input and the output files must be described to
CMS with the FILEDEF command.
The MOVEFILE and FILEDEF commands are described and examples are
given of how to use thea in "Section 8. Developing OS Program Under
CMS." The procedures are the same for copying DOS files as for OS data
sets. You must, however, keep the following in mind:
•
Since DOS files on DOS disks do not contain ELKSIZE, RECFM, or LRECL
options, these options must be specified via the FILEDEF command;
otherwise,
defaults of BLOCKSIZE=32760 and RECFM=U are assigned.
LREeL is not used for RECFM=U files.
•
If a DOS file-id does not follow OS naming conventions (that is, oneto eight-byte qualifiers with each qualifier separated by a period;
Section 9. Developing DOS Programs Under CMS
155
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
up to 44 characters including periods),
operand of FILEDEF and the 1 operand of
, file-ide
you must use the DSN 1
LISTDS to enter the Des
You can create individual CMS files for DOS modules from a DOS
library distribution tape or DOS SYSIN tape. Use the VMFDOS command.
The VMFDOS command can create a CMS file for each DOS module that
exists, and the CMS filename corresponds to the DOS module name. You
can restore individual modules, groups of modules, or the entire
module set.
For DOS library distribution tapes, the 1MFDOS command restores
modules from either system or private
(relocatable and/or source
statement)
libraries. The created CMS files have a filetype of
'TEXT' if they are from a relocatable library. They have a filetype
of 'MACRO' if they are from a source statement library.
For DOS SYSIN tapes, modules containing a period as the second
character (for example, 'A.')
of a DOS 'CATALx' control statement
have a filetype of 'MACRO'.
All other files have a filetype of
'TEXT'.
The VMFDOS command is described in
the
!~LJ1~ g!~nning
2~~~~g!i~D ~Yide.
gng
~y§!~~
If you have DOS files or source programs on cards, you can create eMS
files directly by having these cards read into the real system card
reader. You direct the cards to your virtual machine by punching a
CP ID card in this format:
ID HARMONY
and placing this card in front of your card deck. When the cards
appear in your virtual card reader, you can read them onto your eMS
A-disk with the READCARD command:
readcard dataproc assemble
You can use the editor to remove
included in the deck.
any DOS control cards
that may be
See "Tape Labels in eMS" for a description of eMS tape labe~
processing for CMS/DOS tape files. The sup~ort for tape labels is
only for files defined by a DTFMT macro. If you do not use this
macro, eMS bypasses IBM standard labels on input tapes and writes a
tape mark over any existing labels on an output tape. The eMS
LABELDEF command is equivalent in eMS/DOS to the DOS/VM TLBL control
statement when standard tape label processing is used.
156
IBM VM/370 eMS User's Guide
Pg. of GC20-1819-2 Rev ftarch 30, 1919 by Supp. SD23-9024-1 for 5148-118
Using the ASSGN Command
The 15SGN and DLBL commands perform the same functions for CftS/DOS as
the 155GN and DLBL control statements in D05/VSE. You use the 155GB
command to designate an I/O device for a system or programmer logical
unit (5YSxxx) and, if the device is a disk device, you can use the
DLBL command to establish a real file identification for a symbolic
filename in a program. The DLBL command is described under nusing
the DLBL Command."
In addition to using the 155GN command to relate real I/O devices
with symbolic units, you must use it in CftS/DOS to:
•
1ssign SY5IN or 5Y5IPT for the input source file
compiler when you use the D05PLI or FCOBOL com.ands.
for a
•
Identify the disk, by mode letter, on which a private
re1ocatab1e, or source statement library resides.
language
core image,
5ection 9. Developing 005 Programs Under Cft5
156.1
March 30, 1979
156.2
IBM VM/370 CMSpser's Guide
•
Assign SYSIN or SYSIPT to the CMS disk on which an ESERV
containing control statements .for the ESERV program, resides.
When you enter the ASSGN command,
and the device; for example:
you must supply the
file,
logical unit
assgn sys100 printer
assigns the logical unit SYS100 to the printer. When you want to make
an assignment to a disk device, you must specify the mode letter at
which the disk is accessed. The command:
assgn sys010 b
assigns the logical unit SyS010 to your B-disk.
The system logical units you can assign and the valid
you can assign to them in CMS/DOS follow.
device types
~!SIfI,
~!~~Q~, ~!~I!: These units can be assigned to disk (mode), TAPE,
or READER. If you make an assignment to SYSIN, both SYSRDR and SYSIPT
are also assigned the same device.
~!SL~I:
The system logical unit
(mode), PRINTER, or TAPE.
for listings
can be assigned
to disk
~!~1Q~:
Terminal or operator output or messages can be assigned to
PRINTER or TERMINAL •. eMS/DOS always assigns SYSLOG to TERMINAL by
default, so you never have to make this assignment except when you want
to alter it.
~!SPf~:
Punched output, for example
PUNCH, disk (mode), or TAPE.
text
decks, can
be assigned
to
~!SC1~, ~!~~1~,
SY~~1~: The system logical· units SYSCLB,
SYSRLB, and
SYSSLB can be assigned to private core image, relocatable, and source
statement libraries, respectively. The only valid assignments for these
units is to disk (mode).
If you want to reference private libraries
with the DSERV, ESERV, FETCH, SSERV, or RSERV commands, you must assign
SYSCLB, SYSRLB, or SYSSLB to the disks on which the libraries reside.
You can assign programmer logical units SYSOOO through SYS241 with the
ASSGN command.
This deviates from
DOS/VS, where the number of
programmer logical uni~s varies according to the number of partitions.
MANIPULATING DEVICE ASSIGNMENTS
Besides assigning I/O
previous assignment:
devices, the
ASSGN
command can
also negate
a
assgn syspch ua
or specify that, for a given device, no real I/O
performed during the execution of a program:
)
operation is
to be
assgn sys009 ign
Section 9. Developing DOS Programs Under CMS
157
When you release a disk from
to that disk are unassigned.
your virtual machine, any assignments made
You can find. out the current assignments for system and programmer
logical units with the LISTIO command, which lists all the system or
programmer logical units, even those that are unassigned:
listio
To list only currently assigned units, enter:
listio a
To find out the current
SYS100, enter:
assignment of
one specific unit,
for example
listio sys100
With the EXEC option of the LISTIO command, you can create a disk
file containing the list of assignments.
The $LISTIO EXEC that is
created contains two EXEC numeric variables, &1 and &2, for each unit
listed. For example, if you entered the command:
listio sys081 (exec
then the file $LISTIO EXEC may contain the record:
&1 &2 SYS081 PRINTER
When you use the STAT option, LISTIO lists, for disk devices, whether
the disk is read-only or read/write; for example:
listio sys100
SYS100 B
R/i
indicates that SYS100
disk.
is assigned to the B-disk, which
You can cancel all current assignments
environment and then re-entering it:
by
is a read/write
leaving
the
CMS/DOS
set dos off
set dos on
VIRTUAL MACHINE ASSIGNMENTS
When you assign a physical device type to a system or programmer logical
unit, CMS relates the device to your virtual machine configuration; you
receive an (error message if you try to assign a logical unit to a device
not in your configuration.
For example, if you are using the ASSGN
command to assign a logical unit to a disk file, you must specify the
access mode letter of the disk. If the disk is not accessed, the ASSGN
command fails.
For another example, if you issue:
assgn syspch punch
the punch specified is your own virtual machine card punch. The. actual
destination
of punched
output
then
depends on
the
spooling
characteristics of the punch; if it is spooled to another user or to *,
then no real cards are punched, but virtual card images are placed in
158
IBM VM/370 CMS User's Guide
(
the virtual reader of the destination
virtual machine or your own.
userid, which
may be
another
eMS supports only one reader, one punch, and one printer; you cannot
make any assignments for multiple output devices in CftS/DOS. When you
make an assignment for a logical unit that has already been assigned, it
replaces the current assignment.
Using the DLBL Command
Use the DLBL command to supply eMS/DOS with specific file identification
information for a disk file that is going to be used for input or
output. For any DLBL command you issue, you must previously have issued
an 1SSGN command for the disk, specifying a system or programmer logical
unit. The basic relationship is:
assgn SYSxxx mode
dlbl filename mode DSN 1 (SYSxxx
Both the SYSxxx and the mode values must match on the 1SSGN and DLBL
commands; the disk on which the file resides must be accessed at mode.
The filename on the DLBL command line, called a ddname in CMS/DOS,
corresponds to the symbolic name for a file in a program. If you want to
reference a private DOS library, you must use one of the following
ddnames:
2.Y§l~!
~2g.!.£g! !!.!!.!1
SYSCLB
SYSRLB
SYSSLB
~i.!~.!!~!g
IJSYSCL
IJSYSRL
IJSYSSL
ENTERING FILE IDENTIFICATIONS
When you issue the DLBL command you must identify the file, by file-id
(for a DOS file)
or by file identifier (for a eMS file). The keywords
DSN and eftS indicate whether it is a DOS file or a eMS file,
respectively.
If the file is a DOS file residing on a DOS disk, you can enter the
DLBL command in one of two ways.
For examFle, for a file named
TEST.INPUT you could enter either:
assgn·sys101 d
dlbl infile d dsn test input (sys101
-- or
assgn sys101 d
dlbl infile d dsn 1 (sys101
ENTER DATA SET NAME:
test. input
)
For any DOS file with a file-id that
hyphens, you must use the "DSN 1" form.
contains embedded
blanks or
Section 9. Developing DOS Programs Under CMS
159
When you issue a DLBL command for a CMS file, you enter the filename
and filetype following the keyword CMS:
assgn sys102 a
dlbl outfile a cms new output (sys102
In this example, if SYS102 is defined as an output file for a program,
the output is written to your CMS A-disk in a file named NEW OUTPUT.
You can, for convenience, use a
enter:
'
CMS defauit file identifier.
If you
dlbl out file a cms (sys102
then the output filetype defaults to that of the ddname and the filename
to FILE. So, this output file is named FILE OUTFILE.
You can clear a DLBL definition for a file by using the CLEAR operand of
the DLBL command:
dlbl out file clear
To clear all existing definitions# except
'option, you can enter:
dlbl
*
those entered
wit~
the PEBK
clear
This co~mand is issued by the assembler and the language processors when
they complete execution. Definitions entered with the PERM option must
be individually cleared.
Whenever you use the HI Immediate command to halt the execution of a
program, the DLBL definitions in' effect are cleared, including those
entered with the PERM option.
You can find out what definitions
the DLBL command with no operands:
are currently in effect by issuing
dlbl
or, you can use the QUERY command with the DLBL operand.
Using DOS Libraries in eMS/DOS
CMS/DOS provides you with the capability of using various types of files
from DOS system or private libraries. You can copy, punch, display at
the terminal, or print:
•
Books from system or
SSERV command
•
Relocatable modules from
using the RSERV command
•
Procedures from the system procedure library using the PSERV command
160
pri va te sour,ce
system' or
IBM VM/370 CMS User's Guide
statement libraries
using the
private relocatable
libraries
(
ftarch 30, 1979
You can also:
•
Copy and de-edit macros from system
the ESERV command
and private E sublibraries using
•
Access the directories of system or private libraries using the DSERV
command
•
Link-edit relocatable modules from
libraries with the DOSLKED command
•
Read core image phases from system or private
core image libraries
into storage for execution using the FETCH command
system
or private
relocatable
THE SSERV COMMAND
If you have cataloged source programs or copy files on the system source
statement library and you want to use CMS to modify and test them, you
can copy them into CftS files using the SSERV command.
For example,
suppose you want to copy a book named PROCESS from the A sublibrary on
the system residence volume.
The DOS system residence is in your
virtual machine configuration at virtual address 350, and you have
accessed it as your F-disk. First, to indicate to CftS/DOS that the
system residence is on your F-disk, you enter:
set dos on f
then you can enter the SSERV
identification and the book name:
command,
specifying
the
sublibrary
sserv a process
This creates, from the A sublibrary, a file named PROCESS COpy and
places it on your A-disk. If the book contained assembler language
source statements you would want the filetype to be ASSEftBLE, so you may
enter:
sserv a process assemble
If you want to copy a book from a private source statement library,
you must first use the ASSGN and DLBL commands to make the library known
to CftS/DOS.
For example, to obtain a copy file from a private library
on a DOS disk accessed as your D-disk, enter:
assgn sysslb d
dlbl ijsyssl d dsn 1 (sysslb
ENTER DATA SET NAME:
program. test library
NOV, when you enter the SSERV command:
sserv t setup copy
the book named SETUP in the T sublibrary of PROGRAft.TEST LIBRARY is
copied into a CMS file named SETUP COPY. If SETUP is not found in the
private library, then CMS searches the system library, if it is
available.
Section 9. Developing DOS Programs Under CftS
161
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp,. SD23-9024-1 for 5748-XX8
THE R5ERV COMMAND
In CMS/DOS, to manipulate relocatable modules that have been cataloged
either on the system or a private relocatable library you must first
copy them into CMS files with the RSERV command. You can link-edit
.odules directly from DOS relocatable libraries, but if you ~ant to add
or modify linkage editor control statements for a module, you must place
the control statements ina CMS file.
If you are copying a relocatable module from the system relocatable
library, then you should make sure that you have indicated the system
residence disk when you entered the CMS/DOS environment:
set dos on f
then you can issue the RSERV command
relocatable module you want to copy:
specifying
the name
of
the
rserv rtna
The ~xecution of this command results in
named RTNA TEXT on your A-disk.
the creation
If you want to copy a relocatable module from
library, you must first use the AS5GN and DLBL
private library known to CMS/DOS:
of a
CMS file
a private relocatable
commands to make the
assgn sysrlb d
dlbl ijsysrl d dsn reloc lib (sysrlb
Then, issue the RSERV command for a specific module in that library:
rserv testrtna
to create the CMS file TESTRTNA TEXT from the module named TESTRTNA. If
the module TESTRTNA is not found in RELOC.LIB, eMS searches the system
library, if it is available.
THE PSERV COMMAND
If you want to copy DOS cataloged procedures intoCMS files to use. for
example, in preparing job streams for a DOS/VS virtual machine, you can
use the PSERV command:
pserv prep job
This command creates a CMS file on your A-disk; the file is named
PREPJOB PROC. To copy a procedure from the procedure library you must
have entered the CMS/DOS environment specifying a disk mode for the
system residence volume.
You
cannot execute DOS/VSprocedures directly from the eMS/DOS
However, if you modify a procedure, you can punch it to a
virtual machine that is running a DOS/VSE system. and execute" it there.
environment~
162
IBM VM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by SUppa SD23-9024-1 for 5748-XX8
THE ESERV COMMAND
The CMS/DOS ESERV command is actually an EXEC procedure that calls the
DOS/VSE ESERV utility program. To use the ESERV program, you first must
use the CMS Editor to create a file with a filetype of ESERV that
contains the ESERV control statements you want to execute. For example,
if you want to write a de-edited copy of the macro DTFCD onto your
A-disk, you might create a file named DTFCD ESERV, with the record:
PUNCH E.DTFCD
As when you submit ESERV jobs in DOS/VSE, column 1 must be blank.
Then, you must assign SYSIN to the device on which
file resides, usually your A-disk:
the ESERV source
assgn sysin a
Then you can enter
ESERV file:
the ESERV
command specifying
the filename
of the
eserv dtfcd
No other ASSGN commands are required; the CMS/DOS
default assignments for SYSPCH and SYSLST to disk.
ESERV EXEC
makes
To copy and de-edit macros from a private E sublibrary, issue the
ASSGN and DLBL commands to identify the library.
For example, to
identify a source statement library named TEST.MACROS on the DOS disk
accessed as the C-disk, enter:
assgn sysslb c
dlbl ijsyssl c dsn test macros (sysslb
The SYSLST output is contained in a CMS file with the same filename
as the ESERV file and a filetype of LISTING; you must examine the
LISTING file to see if the ESERV program executed successfully. You can
either edit it (using the CMS editor), or display its contents with the
TYPE command:
type dtfcd listing
The SYSPCH output is contained in a file with the same name as the
ESERV file and a filetype of MACRO. If you want to punch ESERV output
to your virtual card punch, make an assignment of SYSPCH to PUNCH.
When you use the PUNCH or DSPCH ESERV control statements, CATAL.S,
END, or /* records may be inserted in the output file.
When you use the
MACLIB command to add the MACRO file to a CMS macro library, these
statements are ignored.
See "Using Macro
Libraries"
manipulating CMS macro libraries.
for
information
on
creating
and
THE DSERV COMMAND
You can use the DSERV command to examine the contents of system or
private libraries. If you do not specify any options with it, the DSERV
co •• and creates a disk file, named DSERV MAP, on your A-disk. You can
use the PRINT or TERM options to specify that the directory list is
either to be printed on your spooled printer or displayed at your
terminal.
You can also use the SORT option to create a list in
collating sequence.
Section 9. Developing DOS Programs Under eMS
163
Pg,. of GC20-1819-2 Rev March 30.,1919 by Supp. SD23-9024.-1 for 5148-118
In order to examine a system directory, you must have
CMS/DOS environment specifying the ~ode letter of the
residence:
entered the
DOS system
set dos on f
If you want to examine the directory of a private source statement,
core image, or relocatable library you must issue the ASSGN and DLEL
commands establishing SYSSLB, SYSCLB, or SYSRLB before using the DSEBV
cOJllmand.
For example, to display at your terminal an alphameric list of
procedures cataloged on the system procedure library, you would issue:
dserv pd (sort term
If the directory you are exam1n1ng is for a core image library, you
can specify a particular phase name to ascertain the existence of the
phase:
dserv cd phase $$bopen (term
To list the directory of a private source
would first issue the ASSGN and DLBL commands:
statement library,
you
assgn sysslb b
dlbl ijsyssl b dsn test source (sysslb
then enter the DSERV command:
dserv sd
The CMS file, DSEBV MAP A, that is created in this example contains the
directory of the private source statement library TEST.SOURCE.
USING DOS CORE IMAGE LIBRARIES
You can load core image phases from DOS core image libraries into
virtual storage and execute them under CMS/DOS. Since CMS cannot write
directly to DOS disks, linkage editor output under CMS/DOS is placed in
a special CMS file called a DOSLIB.
When you execute the FETCH command
in CMS/DOS you can load phases from either system or private DOS core
image libraries as well as from CMS DOSLIBs. More information on using
the FETCH command is contained under "Executing programs in CMS/DOS~"
Using Macros Libraries
DOS/VS macro libraries cannot be accessed directly by the VM/310
assembler. If you want to assemble DOS programs in CMS/DOS that use DOS
macro or copy files that are on the system or a private macro library
you must first create a eMS macro library (MACLIE) containing the macros
you wish to use. Since the process of creating a CMS MACLIB from the
DOS system source statement library
(E sublibrary)
can be very
time-consuming,
you should check
with your installation's system
programmer to see if it has already been done, and to verify the
filename of the m~cro library, so that you can use it in CMS/DOS.
!gte: The DOS/VSE PL/I and DOS/VSE COBOL compilers executing in CMS/DOS
cannot read macro or cOFY files from CMS MACLIBs.
164/ IBM VM/310 CMS User's Guide
If you want to extract DOS system macros te modify them for your
private use, or if you want to use macros from a private library in CftS,
you must use the procedure outlined below to create the MACLIB files.
CMS MACLIBS
A CMS macro library has a filetype of MACLIB. You can create a MACLIB
from files with filetypes of MACRO or COPY. A MACRO file may contain
macro definitions; COpy files contain predefined source statements.
When you want to assemble a source program that uses macro or copy
definitions, you must ensure that the library containing the code is
identified before you invoke the assembler. Otherwise, the library is
not searched. You identify libraries to be searched using the GLOBAL
command. For example, if you have two MACLIBs that contain your private
macros and copy files whose names are TESTMAC ftACLIB and TESTCOPY
MACLIB, you would issue the command:
global maclib test mac testcopy
The libraries you specify on a GLOBAL command line are searched in
order you specify them.
A GLOBAL command remains in effect for
remainder of your terminal session, or until you IPL CMS. To find
what macro libraries are currently available fer searching, issue
command:
the
the
out
the'
query maclib
)
You can reset the libraries or the
command.
search order by reissuing the GLOBAL
CREATING A CMS MACLIB
To create a CMS macro library, each macro or copy file you want included
in the MACLIB must first be contained in a eftS file with a filetype of
COpy or MACRO. If you are creating a CMS MACLIB file from a DOS library
you must use the SSERV command to copy a file from any source statement
library other than an E sublibrary, or use the ESERV command to copy and
de-edie-a macro from an E sublibrary.
The SSERV command uses a default
filetype of COPY; the ESERV command uses a default filetype of MACRO.
The f~llowing example shows how to copy macros
and shows how to create and use the CMS ftACLIB
macros.
1.
Enter the CMS/DOS environment with the
disk accessed as mode C:
from various sources
that contains these
DOS system residence
on a
set dos on c
2.
)
Copy the macro book named
source statement library:
~PEN
from
the A sublibrary of the system
sserv a open
Section 9. Developing DOS Programs Under CMS
165
3.
Establish a private source statement library:
access 351 d
assgn sysslb d
dlbl ijsyssl d dsn ? (sysslb
test source. lib
4.
Issue the SSERV command for
SOURCE.LIB:
sserv
5.
II
a macro in
the M sublibrary
of TEST
releas
create an ESERV file to copy from the E sublibrary:
edit contrl eserv
NEW FILE
EDIT:
input
punch contrl
file
6.
Execute the ESERV command:
assgn sysin a
eserv contrl
create a CMS macro library named MYDOSMAC fro~ the files just
created, which are named OPEN COpy, RELEAS COPY, and CONTRL MACRO:
7.
maclib gen mydosmac open releas contrl
To use these macros in an assembler language program, you must
indicate that this MACLIB is accessible before assembling a source
file:
8.
global maclib mydosmac
THE MACLIB COMMAND
The MACLIB command performs a variety of functions. You use it to:
•
•
•
•
Create the MACLIB (GEN function)
Add, delete, or replace members (ADD, DEL, and REP functions)
Compress the MACLIB (CaMP function)
List the contents of the MAC LIB (MAP function)
Descriptions of these MACLIB command
func~ions
follow.
§~! !Y~£l!Q~:
The GEN (generate) function creates a CMS macro library
from input files specified on the command line. The input files must
have filetypes of either MACRO or COPY. For example:
maclib gen mymac get pdump put regequ
creates a macro library with the file identifier MYMAC MACLIB
macros existing in the files with the file identifiers:
A1 from
GET { MACRO },PDUMP, {MACRO}, PUT { MACRO },and REGEQU { I1ACRO}
COpy
COpy
COpy
.
COpy
If a file named MYMAC MACLIB A1 already exists, it is erased.
166
IBM VM/370 CMS User's Guide
(
Assume that the files GET MACRO, PDUMP COPY, PUT MACRO,
COPY exist and contain macros in the following form:
GET MACRO
--------GET
WAIT
PDUMP COpy
----------
*COpy PDUMP
PDUMP
*COPY WAIT
WAIT
The resulting file, MYMAC MACLIB
GET .
WAIT
PDUMP
PUT MACRO
--------PUT
and REGEQU
REGEQU COpy
----------XREG
YREG
A1, contains the members:
WAIT
PUT
REGEQU
The WAIT macro, which
appears twice in the
duplicate macro names.
from MYMAC MACLIB, the
used.
appears twice in the input to the command, also
output. The MACLIB command does not cbeck for
If, at a later time, the WAIT macro is requested
first WAIT macro encountered in the directory is
When COpy files are added to MACLIBs, the name of the library member
is taken from the name of the COpy file, or from the *COPY statement, as
in the file PDUMP COPY, above. Note that although the file REGEQU COpy
contained two macros, they were both included in the MACLIB with the
naae REGEQU. When the input file is a MACRO fil~, the member name is
taken fro. the macro prototype statement in the MACRO file.
A~~ IYA£~i2A:
The ADD function appends new members to an existing macro
library. For example, assume that MYMAC MACLIB A1 exists as created in
the example in the explanation of the GEN function and the file DTFDI
COpy exists as follows:
)
*COPY DTFDI
DTFDI macro definition
*COPY DIMOD
DIMOD macro definition
If you issue the command:
aaclib add mymac dtfdi
the resulting MYMAC MAC LIB A1 contains the members:
GET
WAIT
PDUMP
WAIT
PUT
REGEQU
DTFDI
DIMOD
~]~ IYA£~i2~:
The REP (replace) function deletes the directory entry for
the macro definition in the files specified. It then appends new macro
definitions to the macro library and creates new directory entries. For
example, assume that a macro library TESTKAC MACLIB contains the members
A, B, and C, and that the following command is entered:
maclib rep testaac a c
The files represented by file identifiers A MACRO and C MACRO each have
one macro definition. After execution of the command, TEST MAC MACLIB
contains members with the same names as before, but the content~ of A
and C are different.
)
Section 9. Developing DOS Programs Under CMS·
167
J2~1
l.!Ul£:tiQ!!: The DEL (delete) function removes the specified macro name
from the macro library d~rectory and compresses the directory so there
are no unused entries. The macro definition still occupies space in the
library, but since no directory 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:
maclib del mymac get put wait dtfdi
deletes macro names GET, PUT, WAIT, and DTFDI from the directory of the
macro library named MYMAC MACLIB. Assume that MYMIC exists as in the IDD
function example. After the above command, MYMIC MICtIB contains the
following members:
PDUMP
WAIT
REGEQU
DIMOD
COMP Function: Execution of a MICLIB command with the DEL or REP
functions--can leave unused space within a macro library. The CaMP
(compress)
function removes any macros that do not have directory
entries. This function uses a temporary file named MICLIB CMSUT1. For
example, the command:
maclib comp mymac
compresses the library MIMAC MACLIB.
MAP Function: The MIP function creates a list containing the name of
each-iacro--in the directory, the size of the macro, and its position
within the macro library. If you want to display a list of the members
of a MAeLIB at the terminal, enter the command:
i
\~
maclib map mymac (term
The default option, DISK, creates a file on your A-disk which has a
filetype of MAP and a filename equal to the filename of the MACLIB. If
you specify the PRINT option, then a copy of the map file is spooled to
your virtual printer as well as being written onto disk.
The following CMS commands supply a MEMBER option, which
reference individual members of a MACtIB:
•
•
•
•
allows you to
PRINT (to print a member)
PUNCH (to punch a member)
TYPE (to display a member)
FILEDEF (to establish a file definition for a member)
Iou can use the CMS editor to create the MACRO and COpy files and
then use the MACLIB command to place them in a library. Once they are
in a library, you can erase the original files.
ToWextract a member from a macro library, you can use either the
PUNCH or the MOVBFILE command. If you use the PUNCH command you can
spool your virtual card punch to your own virtual reader:
cp spool punch to
168
IB~
*
VM/370 CMS User's Guide
(
Pg~
of GC20-1819-2 Rev March 30, 1919 by Supp. SD23-9024-1 for 5148-118
Then punch the member:
punch test mac maclib (member get noheader
and read it back onto disk:
readcard get macro
In the above example, the member was punched with the NOHEADER option of
the PUNCH command, so that a name could be assigned on the RE1DCABD
command line. If a header had been created for the file, it would have
indicated the filename and filetype as GET MEMBER.
If you use the MOVEFILE command, you must issue a file definition for
the input member name and the output macro or copy file before entering
the MOVEFILE command:
filedef inmove disk testcopy maclib (member enter
filedef outmove disk enter copy a
movefile
This example copies the member ENTER from
MACLIB A into a CMS file named ENTER COPY.
the macro
library TESTCOPY
When you use the PUNCH or MOVEFILE commands to extract members fro.
CMS MACLIBs, each member is followed by a II record, which is a MAetIB
delimiter.
You can edit the file and use the DELETE subcommand to
delete the II record.
If you wish to
COPYFILE command.
move the complete
MACtIB to
another file,
use the
The macro libraries that are on the systea disk contain CMS, DOS, and OS
assembler language macros. The MACLIBs are:
•
I •
CKSLIB MACLIB, which contains the CMS macros.
DKSB20 MACLIB contains the CMS macros
Extensions (Program No. 5148-118).
for
VM/310
contains DOS/VS macros that
Basic
Syste.
•
DOS MACRO MACLIB, which
use.
CMS/DOS routines
•
OSMACRO MACLIB, OSMACR01 MACLIB, and TSOMAC MACtIB, which are used by
as programmers.
DOS Assembler Language Macros Supported
Figure 16 lists the DOS/VSE assembler language macros supported by
CMS/DOS. You can assemble source programs that contain these macros
under CMS/DOS, provided that you have the macros available in either
your own or a shared CMS macro library,. The macros whose functions are
described in the "Function" column with the term "no-op" are supported
for assembly only; when you execute programs that contain these m~cros,
the DOS/VSE functions are not performed~
To accomFlish the ·macro
function you must execute the program in a DOS/VSE virtual machine.
Section 9. Developing DOS Programs Under CMS
169
Pg.;. of GC20-1819-2 Rev March 30, 1919 by Supp. SD23-9024-1 for 5748-XX8
Ma£!:Q
CALL
CANCEL
CDLOAD
CHECK
CLOSEt
CLOSER
CNTRL
COMRG
~!£
DEO
DEOB
DTFxXl
DUMP
ENQ
ENOB
EOJ
ERET
EXCP
EXIT PC
EXIT AB
FCEPGOUT
FETCH
41
FREEVIS
GENL
GET
GETVIS
GETIME
JDUMP
LOAD
!!VCOM
NOTE
OPEN/
OPENR
PAGE IN
PDUMP
PFIX
PFREE
POINTR
POINTS
POINTi
POST
PRTOV
PUT
PUTR
READ
RELEASE
RELPAG
RELSE
RETURN
RUNMODE
SECTVAL
SEiZE
SETIME'
SETPFA
06
65
33
9
42
2
14
00
17
95
86
01
02
62
61
34
04
05
Function
Pass-control to another program
Terminate processing
Load a VSAM phase
Verify completion of a read or write operation
Deactivate a data file
Control a physical device
Return address of background partition
communication region
no-op
Release a resource
Establish file definitions
Dump storage and registers and terminate processing
no-op
Protect a resource
Terminate processing normally
Provide an error routine
Execute a channel program
Return from program check routine
Return from abnormal termination routine
no-op
Load and pass control to a phase
Load and pass control to a logical transient
Release user free storage
Generate a phase directory list
Access a sequential file
Obtain user free storage
Get the time of day
Dump storage and registers and terminate processing
Read a phase into storage
Modify bytes in the partition communication region
Manage data set access
Activate a data file
87
no-op
Dump storage and registers and continue processing
67
no-op
68
no-op
Position a file for reading
Reposition a file to its beginning
Position a file for writing
40
Post the event control block
Control printer overflow
Write to a ~equential file
Communicate with the system operator
Access a sequential file
64
Release a system resource
85
no-op
Skip to begin reading next blcck
Return control to calling program
Check if program is running real or virtual
66
Obtain a sector number
75
22
no-op
10/24 no-op
71
no-op
tThe declarative macros supported are:
DTFCN, DTFCD, DTFPR, DTFDI, DTFMT, DTFSD, DTFCP, and DTFSL
Figure 16. DOS/VSE Macros Supported by CMS (Part 1 of 2)
170
IBM VM/370 CMS User's Guide·
Pg. of GC20-1819-2 Rev March 30,1979 by Supp. SD23-9024-1 for 5748-XI8
!t~££2
STIlT AB
PC
IT
OC
TRACK FREE
TRACK HOLD
TRUNC
TTIMER
USE
WAIT
WRITE
xxMODl
~!~
37
16
20
18
36
35
52
63
07
Function
ProvIde-or terminate linkage to abnormal ending
routine
no-op
no-op
no-op
no-op
Skip to begin writing next block
Return a 0 in Register 0 (effectively a noop)
Reserve a systen resource
Wait for the completion of I/C
Write to a sequential file
Create Logical IOCS routine inline
lThe DOS logic modules supported are:
CDMOD, PRMOD, DIMOD, MTMOD, SDMODxx, and CPMOD
Figure 16. DOS/VSE Macros Supported by CMS (Part 2 of 2)
Assembling Source Programs
If you are a DOSjVSE assembler language programmer using CMS/DOS, you
should be aware that the assembler used is the VM/370 assembler, not the
DOS/VSE assembler. The major difference is that the VM/370 assembler,
invoked by the ASSEMBLE command, is designed for interactive use, so
that when you assemble a program, error messages are displayed at your
terminal when compilation is comFleted, and you do not have to wait for
a printed listing to see the results.
You can correct your Source file
and reassemble it immediately. When your program assembles without
errors, you can print the listing.
To specify options to be used during the assembly, you enter them on
the ASSEMBLE command line.
So, for example, if you do not want the
output LISTING file placed on disk, you can direct it to the printer:
assemble myfile (print
All of the ASSEMBLE command options are listed in
Y~L37Q £~~ £om~£ ~~g
~!!g~ !!.~!~£~1l£~.
When you invoke the ASSEMBLE command specifying a file with a
filetype of ASSEMBLE, CMS' searches all of your accessed disks, using the
standard search order, until it locates the file.
When the assembler
creates the output LISTING and TEXT files, it writes them onto disk
according to the following priorities:
1.
If the source file is on a read/write disk,' the TEXT
files are written onto the same disk.
and LISTING
2~
If the source file is on a read-only disk that is an extension of a
read/write disk, the TEXT and LISTING files are written onto the
parent disk.
3.
If the source is on any other read-only disk, the TEXT and LISTING
files are written onto the A-disk.
In all of the above cases, the filenames assigned to the
LISTING files are the same as the filename of the input file.
The output files used by the assembler are defined via
commands issued by CMS when it calls the assembler.
If you
TEXT and
FILEDEF
issue a
Section 9. Developing DOS programs Under CMS
111
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-IX8
FILEDEF command using one of the assembler ddnames before you issue the
ASSEMBLE command, you can override the default file definitions.
The ddname for the source input file is
ASSEM~LE.
If you enter:
filedef assemble reader
assemble sample
then the asiembler reads your input file from your card reader, and
assigns the filename SAMPLE to the output TEXT and LISTING files~ You
can use this method to assemble programs directly from DOS sequential
files on DOS disks.
For example, to assemble a source file named
DOSPROG from a DOS disk accessed as a C-disk, you could enter:
filedef assemble c dsn dosprog (recfm f lrecl 80
assemble dosprog
Again, the name you assign on the ASSEMBLE command may be anything; the
assembler uses this name to assign filenames to the TEXT and LISTING
output files.
LISTING and TEXT are the ddnames assigned to the SYSLST and SYSPCH
output of the assembler. You might issue file definitions to override
these defaults as follows:
filedef listing disk assemble listfile a
filedef text disk assemble textfile a
assemble source
When these commands are executed, the output from the assembly. of the
file SOURCE ASSEMBLE is written to the disk files ASSEMBLE LISTFILE and
ASSEMBLE TEXTFILE.
Link-editing Programs In eMS/DOS
When the assembler or one of the language compilers executes, the object
module produced is written to a CMS disk in a file with a filetype of
TEXT. The filename is always the same as that of the input source file.
These TEXT files (sometimes referred to as decks, although they are not
real card decks) can be used as input to the linkage editor or can be
the target of an INCLUDE linkage editor control statement.
You can invoke
for example:
the CMS/DOS linkage editor with
the DOSLKED command,
doslked test testlib
where TEST is the filename of either a DOSLNK or TEXT file (that is, a
file with a filetype of either DOSLNK or TEXT) or the name of a
relocatable module in a system or private relocatable,library. TESTLIB
indicates the name of the output file which, in CMS/DOS, is a phase
library with a filetype of DOSLIB.
When you issue the DOSLKED command, CMS first searches for. a file
with the specified name and a filetype of DOSLNK. If none are found, it
searches the private relocatablelibrary, if you have assigned one (you
must issue an ASSGN command for SYSRLB and use the ddname IJSSYRL in a
DLBL state,ent). If the module is still not found, CMS searches all of
your accessed disks for a file with the specified name and a fil~type of
TEXT~
Last, eMS searches the system relocatable library, if it is
available (you must enter the CMS/DOS environment specifying the mode
letter of the DOS/VSE system residence if you want to acces·s the system
libraries) '.
172
IBM VM/370 CMS User's Guide
LINKAGE EDITOR INPUT
You can place the linkage editor control statements ACTION,
PHASE,
INCLUDE, and ENTRY in a CMS file with a filetype of DOSLNK. When you
use the INCLUDE statement, you may specify the filename of a CMS TEXT
file or the name of a module in a DOS relocatable library:
INCLUDE XYZ
or you may use the INCLUDE. control statement to indicate that the object
code follows:
INCLUDE
(CMS TEXT file)
A typical
following:
DOSLNK
file,
named
CONTROL
DOSLNK,
might
contain
the
ACTION REL
PHASE PROGMAIN,S
INCLUDE SUBA
PHASE PROGA,*
INCLUDE SUBB
When you issue the command:
doslked control
the linkage editor searches the following
SUBB:
•
for the object files SUBA and
A DOS private relocatable library, provided you have issued the ASSGN
and DLBL commands to identify it:
assgn sysrlb d
dlbl ijsysrl d dsn ? (sysrlb
•
Your CMS disks for files with filenames
of TEXT
SUBA and SUBB and a filetype
•
The system relocatable library located
volume (if it is available)
on the DOS
system residence
When you want to link-edit individual CMS TEXT files, you can insert
linkage editor control statements in the file using the CMS editor and
then issue the DOSLKED command:
edit rtnb text
EDIT:
input
include rtnc
file
doslked rtnb mydoslib
When the above DOSLKED command is executed, the CMS file RTNB TEXT is
used as linkage editor input, as long as there is no file named RTNB
DOSLNK. The ACTION statement, however, is not recognized in TEXT files.
)
You can also link-ed1t relocatable modules directly from a DOS system
or private relocatable library, provided that you have identified the
library. If you do this, however, you cannot provide control statements
for the linkage editor.
Section 9. Developing DOS programs Under CMS
lJ3
To link-edit a relocatable module from a DOS private library and add
linkage editor control statements to it, you could use this procedure:
1.
Identify the library and use the RSERV command to copy
relocatable module into a CMS TEXT file. In this example,
-module RTNC is to be copied from the library OBJ.MODS:
the
the
assgn sysrlb e
dlbl ijsysrl e dsn obj mods (sysrlb
rserv rtnc
2.
create a DOSLNK file, insert the linkage editor control statements,
and copy the TEXT file created in step 1 into it using the GBTPILE
subcommand:
edit rtnc doslnk
input
action reI
get file rtnc text a
file
3.
Invoke the linkage editor with the DOSLKED command:
doslked rtnc mydoslib
Alternatively,
records:
you
could
create
a DOSLNK
file
with
the
following
ACTION REL
INCLUDE RTNC
and link-edit the module directly from the relocatable library. If you
do not need a copy of the module on a CMS disk, you might want to ~se
this method to conserve disk space.
When the linkage editor is reading modules, it may encounter a blank
card at the end of a file, or a * (comment) card at the beginning of a
file.
In either case, it issues a warning message indicating an invalid
card, but continues to complete the link-edit.
LINKAGE EDITOR OUTPUT: CMS DOSLIBS
The CMS/DOS linkage editor always places the link-edited executable
phase in a CMS library with a filetype of DOSLIB. You should specify
the filename of the DOS LIB when you enter the DOSLKED command:
doslked progO templib
where PROGO is the relocatable module you are
is the filename of the DOSLIB.
link-editing and TEMPLIB
If you do not specify the name of a nOSLIB, the output is placed in a
DOSLIB that has the same name as the DOSLNK or TEXT file being
link-edited.
In the above example, a CMS DOSLIB is created named
TEMPLIB nOSLIB, or, if the file TEMPLIB DOSLIB already exists, the phas~
PROGO is added to it.
nOSLIBs can contain relocatable core image phases suitable for
execution in CMS/DOS. Before you can access phases in it, you must
identify ~t to CMS with the GLOBAL command:
global doslib templibpermlib
174,
IBM VM/310 CMS User's Guide
When CMS is searching for executable phases, it searches all nOSLlBs
specified on the last GLOBAL nOSLIB command line. If you have named a
number of DOSLIBs, or if any particular DOSLIB is very large, the time
required for CMS to fetch and execute the phase increases. You should
use separate DOSLIBs for executable phases, whenever possible, and then
specify only the DOSLlBs you need on the GLOBAL command.
When you link-edit a module into a DOSLIB that already contains a
phase with the same name, the directory entry is updated to point to the
new phase. However, the space that was occupied by the old phase is not
reclaimed. You should periodically issue the command:
doslib comp lib name
where libname is the filename of the
delete unused space.
DOSLIB, to compress the nOSLIB and
The DOSLKED command also produces a linkage editor map, which it writes
into a CMS file with a filename that is that of the name specified on
the DOSLKED command line and a filetype of MAP. The filemode is always
A5. If you do not want a linkage editor map, use the NOMAP option on
the ACTION statement in a DOSLNK file.
Executing Programs in eMS/DOS
After you have assembled or compiled a source program and link-edited
the TEXT files, you can execute the phases in yeur CMS virtual machine.
You may not, 'however~ be able to execute all your DOS programs directly
in CMS. There are a number of execution-time restrictions placed on your
virtual machine by VM/370. you cannot execute a Frogram that uses:
•
•
•
•
I •
Multitasking
More than one partition
Teleprocessing
ISAM macros to read or write files
CMS module files created by DOS programs
The above is only a partial list, representing those restrictions with
which you might be concerned. For a complete list of restrictions, see
the !~Ll1Q E!g~~i»g g~g ~I2!~! §~~~!g!!Q~ §y!g~.
EXECUTING DOS PHASES
You can load executable phases into your CMS virtual machine using the
FETCH command.
Phases must be link-edited before you load them; they
must have been link-edited with ACTION REL. When you issue the FETCH
command, you specify the name of the phase to be loaded:
fetch myprog
Then you can begin executing the program by issuing the START command:
)
start
Section 9j Developing DOS Programs Under
C~S
175
orr you
line:
can fetch a
phase and begin executing
it on a
single command
fetch prog2 (start
When you use the FETCH command without the START option, CMS issues a
.essage telling you at what virtual storage address the phase is loaded:
PHASE PROG2 ENTRY POINT AT LOCATION 020000
Location X'20000' is the starting address of the user program area for
CMS; relocatable phases are always loaded starting at this address
unless you specify a different address using the ORIGIN option of the
FETCH command:
.
fetch prog3 (origin 22000
start
The program PROG3
program area.
executes beginning at location 22000 in
the CMS user
SEARCH ORDER FOR EXECUTABLE PHASES
When you execute the FETCH command, CMS
specify in the following places:
1.
In a DOS/VS private core image library on a DOS disk. If you have
a private library you want searched for phases, you must identify
it using the ASSGN and DLBL commands, using the logical unit
SYSCLB:
assgn sysclb d
dlbl ijsyscl d dsn ?
2.
searches for the phase name you
/
\
(sysclb
In CMS DOSLIBs on CMS disks. If you want
phases, you must use the GLOBAL command
CMS/DOS:
DOSLIBs searched for
to identify them to
global doslib templib mylib
You can specify up to eight DOSLIBs on the GLOBAL command line.
3.
On the DOS system residence core image library. If you want the
system core image library searched you must have entered the
CMS/DOS environment specifying the mode letter of the system
residence:
set dos on z
When you want to fetch a core image phase that has copies in both the
core image library and a DOSLIB, and you want to fetch the copy from the
CMS DOSLIB, you can bypass the core image library by entering the
command:
assgn sysclb ua
When you need to use the core image library, enter:
assgn sysclb c
where C is the mode letter of the system residence volume.
need to reissue the DLBL command to identify the library.
116
IBM VM/370 CMS ·User's Guide
You do. not
«
Pg~
of GC20-1819-2 Rev
~AKING
I/O DEVICE
~arch
30, 1919 by Supp. SD23-9024-1 for 5148-XX8
ASSIGN~ENTS
If you are executing a program that performs I/C, you can use the ASSGN
coamand to relate a system or programmer logical unit to a real I/O
device. As in DOS/VSE, device type assignment in CMS/DOS is dependent
on device specifications in the program~
assgn syslst printer
assgn sys052 reader
In this example, your program is going to read input data from your
virtual card. reader;
the output print file is directed to your virtual
printer. If you want to reassign these units to different devices, you
must be sure that the files have been defined as device independent.
If you assign a logical unit to a disk, you should identify the file
by using the DLBL command. On the DLBL command, you must always relate
the DLBL to the system or programmer logical unit previously specified
in an ASSGN command:
assgn sys015 b
dlbl myf1le b dsn ? (sys015
When you enter tpe DLBL command with the? operand
enter the DOS file-ide
you are prompted to
You must issue all of the ASSGN and DLBL commands necessary for your
program's I/O before you issue the FETCH command to load the program
phase and begin executing.
SPECIFYING A VIRTUAL PARTITION SIZE
For most of the programs that you execute in CMS, you do not need to
specify how large a partition you want those Frograms to execute in.
When you issue the START command or use the START option on the FETCH
command, CMS calculates how much storage is available in your virtual
machine and sets a partition size. eMS calculates how much storage is
available in the following manner:
FREELOWE -
(MAINHIGH + (4096
*
FRERESPG)
where:
FREELOWE
equals the low extent of allocated storage obtained from the
top of virtual storage downwards via the DMSFREE system
request.
MAINHIGH
equals the high extent of allocated storage obtained from the
.low virtual storage .upwards via the GETMAIN user reque~t for
storage.
FRERESPG
equals the amount of storage to
system requests, in pages.
be reserved
for subsequent
In some inst~nces, you may want to control the partition size:
•
For performance considerations
•
Because the default may not leave enough free storage to satisfy the
GET VIS commands issued by the DOS program or the access methed
services function being executed.
Section 9. Developing DOS Programs Under CMS
~11
March 30, 1979
You can set the, partition size with the DOSPART operand of
command. For example, after you enter the command:
the SET
set dospart 300k
all programs that you subsequently execute during
execute in a 300K partition~ In this way you can:
this session
will
•
Set a smaller partition size for
partitions.
programs that run better in smaller
•
S~t a
smaller partition size to leave more free storage.
If the
reduction of the DOS partition does not free enough storage for the
GETVIScommands, a larger virtual machine must be defined.
If you enter:
set dospart off
the CMS calculates a partition size when you execute a prograa.
the default setting.
This is
Bote that the eMS partition, unlike the DOS partition, is used only for
the loading and executing of programs invoked by the FETCH or LOAD
commands. Areas allocated by GETVIS will be assigned addresses outside
the partition but within the user's virtual machine~
SETTING THE UPSI BYTE
If your program uses the user program switch indicator (UPSIl byte, you
can set it by using the UPSI operand of the CMS SET command~ The UPSI
byte is initially binary zeros~ To set it to 1s, enter
set upsi 11111111
To reset it to zeros, enter:
set upsi off
Any value you set remains in effect for the duration of your terminal
session, unless you reload CMS (with the IPL command) '.
DEBUGGIHG
PROG~AMS
IN CMS/DOS
You can debug your DOS programs in CMS/DOS using the facilities of CP
and C~S. By executing'your programs interactively, you can more quickly
determine the cause of an error or program abend, correct it, and
attempt to execute a program again~
The CP and eMS debugging facilities are described in "Section 11. Bow
VM/370 Can Help You Debug Your Programs~" Additional information for
assembl,er language programmers is in "Section 13. Programlling for the
CMS Environment."
178
IBM VM/370 CMS User's Guide
USING EXEC PROCEDURES IN CMS/DOS
During your program development and testing cycle, you may want to
create EXEC procedures to contain sequences of CMS commands that you
execute frequently. For example, if you need a number of MACLlBs,
DOSLlBs, and DLBL definitions to execute a particular program, you might
have an EXEC procedure as follows:
SCONT~OL ERROR TIME
SERRO$ SEXIT SRETCODE
GLOBAL MACLIB TESTLIB DOSMAC
ASSEMBLE TESTA
PRINT TESTA LISTING
DOSLKED TESTA TESTLIB
GLOBAL DOSLIB TESTLIB PROGLIB
ACCESS 200 E
ASSGN SYS010 E
SBEGSTACK
DOS.TEST3.STREAM.BETA
SEND
DLBL DISK1 E DSN ? (SYS010
ASSGN SYS011 PUNCH
CP SPOOL PUNCH TO
ASSGN SYS012 A
DLBL OUTFILE A CMS TEST DATA (SYS012
FETCH TESTA (START
SIF SRETCODE = 100 &GOTO -RET100
SIF SRETCODE = 200 &GOTO -RET200
SEXIT SRETCODE
-RET100 &CONTlNUE
*
-RET200 &CONTINUE
The SCONTROL and SERROR control statements in the EXEC procedure
ensure that if an error occurs during any Fart of the EXEC, the
remainder of the EXEC does not execute, and the execution summary of the
EXEC indicates the command that caused the error.
Note that for the DLBL command entered with the DSN ? operand, you
must stack the response before issuing the DLBL command. In this
example, since the DOS file-id has more than eight characters, you must
use the SBEGSTACK control statement to stack it. If you use the SSTACK
control statement, the EXEC processor truncates all words to eight
characters.
When your program is finished executing, the EXEC special variable
&RETCODE indicates the contents of general register 15 at the time your
program exited.
You can use this value to perform additional steps in
your EXEC procedure. Additional steps are indicated in the preceding
example by ellipses.
For detailed information on creating
Learning To Use EXEC."
EXEC procedures, see
"Part 3.
)
Section 9. Developing DOS Programs Under CMS
179
(
'~
(
180
IBM VM/370 eMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-118
Section 10. Using Access Method Services
and VSAM under CMS and CMS/DOS
This section describes how you can use CftS to create and manipulate VSA!
catalogs, data spaces, and files on as and DOS disks using access method
services. The CftS support is based on DOS/VSE and VSE/VSAM; this .eans
that if you are an as VSAft user and plan to use CftS to manipulate VSAM
files you are restricted to those functions of access method services
that are available under the access method services portion of VSE/VSA!.
The control statements you can use are descrited in the publication
Q§ing !~Al!~!~ £~~~g~g§ g~g ~g£!~§.
You can use CftS to:
•
Execute the access method services utility programs for VSll! and 51!
data sets on as and DOS disks and minidisks. CI!S can both read and
write VSAft files using access method services.
•
Compile and execute programs that read and write VSAI! files from DOS
programs written in the COBOL or PL/I programming languages.
•
Compile and execute programs that read and write VSAI! files fro. OS
programs written in the vs BASIC, COBOL, or PL/I programming
languages.
•
Assemble assembler language source programs under CBS that use VSAI!
macros. You must create your own macro library from as or DOS macro
libraries.
VSAM files written under CMS are wholly compatible for reading and
writing under as and DOS systems. None of the CMS commands normally used
to manipulate CMS files are applicable to VSAM files, however. This
includes such commands as PRINT, TYPE, EDIT, COPYFILE, and so on.
This section provides information on using the CftS A!SEDV command
with which you can execute access method services. The discussion is
divided as follows:
•
"Using the AftSERV command" contains general information.
•
"Manipulating as and DOS Disks for Use with AftSERV" describes how to
use CMS commands with as and DOS disks.
•
"Defining DOS Input and output Files" is for CMS/DOS users only.
•
"Defining as Input and output Files" is for
•
"Using AMSEDV Under CMS" includes notes and examples showing how to
perform various access method services functions in Cfts.
as
users only.
EXECUTING VSAM PROGRAMS UNDER eMS
The commands that are used to define input and output data sets for
access method services (DLBL)
and for CftS/DOS users (ASSGN)
are also
used to identify YSAft input qnd output files for program execution.
Information on executing programs under eMS that manipulate VSAft files
is contained in the program product documentation for the language
processors. These publications are listed in the !AL~l~ !n~!QgY£!iQ~.
Section 10. Using Access Method Services and VSAM
181
March 30, 1979
Restrictions on the use of access method services and VSA" under CMS
for as and DOS users are listed inY~LJ1Q ~~~ ~Q!!gn~ gn~ ~~£!~
Reference, which also contains complete CMS and eMS/DOS command formats,
operand-descriptions, and responses for each of the commands described
here.
When you are going to execute VSAM programs in eMS or C"S/DOS, you
should remember to issue the DLBL command to id€ntify the master
catalog, as well as any other program input or output file you need to
define.
Using the AMSERV Command
In CMS,
A~SERV
you execute access method services
command, which has the basic format:
utility programs
with the
amserv filename
"filename" is the name of a CMS file
statements for access method services.
that
contains
the
control
!Qte: Throughout the remainder of this section the term "AMSERV" is used
to refer to both the CMS A"SERV command and the OS/VS or DOS/VS access
method services, except where a distinction is being made between CMS
and access method services.
You create an AMSERV file with the CMS editor using a
A"SERV and any filename you want; for example:
filetype of
edit mastcat amserv
NEW FILE:
EDIT:
input
The editor recognizes the filetype of AMSERV and so automatically sets
the margins for your input lines at columns 2 and 72. The sample AMSEBV
file being created in the example above, MASTCAT AMSEBV, might contain
the following control statements:
DEFINE MASTERCATALOG (NAME (MYCAT) VOLUME (123456) CYL(2) FILE (IJSYSCT) )
Note that the syntax of the control statements must conform to the rules
for access method services, including continuation characters and
parentheses. The only difference is that th~ A"SERV fiie does not
contain a "/*" for a termination indicator.
Before you can execute the DEFINE control statement in this AMSEBV
example, you must define the output file, using the ddname IJSYSCT. You
can do this using the DLBL command~
Since the exact form required in
the DLBL command varies according to whether you are an as or a DOS
user, separate discussions of the DLBL command are provided later in
this section. All of the following examples assume that any disk data
set or file that you are referencing with an AMSEBV command will have
been aefined by a DLBL command.
When you execute the AMSERV command" the AMSERV control statement
file can be on any accessed CMS disk; you do not need to specify the
filemode and, if you are aDOS user~ you do not need to assign SYSIPT.
The task of locating the file and passing it to access method services
is performed by C~S.
182
IBM VM/370 CMS User's Guide
AMSERV OUTPUT LISTINGS
When the AMSERV command is finished processing, you receive the CMS
ready message, and if there was an error, the return code (from register
15) is displayed following the "R". For example:
R (00008) ;
or, if you are receiving the long form of the ready message, it appears:
R(00008); T=0.01/0.11 10:50:23
If you receive a ready message with an error return code, you should
examine the output listing from AMSERV to determine the cause of the
error.
AMSERV output listings are written in CMS files with a filetype of
LISTING; by default, the filename is the same as that of the input
AMSERV file. For example, if you have executed:
amserv mastcat
and the CMS ready message indicates an
examine the file MASTCAT LISTING:
error return code,
you should
edit mastcat listing
EDIT:
locate /idc/I=
Issuing the LOCATE subcommand twice to find
will position you in the LISTING file at
services message.
the character string IDC
the first access method
The publication ~Q2L!~ ~~22Sg~2 lists and explains all of
messages generated by
access method services together
with
associated reason codes.
the
the
Instead of editing the file, you could also use the TYPE command to
display the contents of the entire file, so that you would be able to
examine the input control statements as well as any error messages:
type mastcat listing
If you need to make changes to control statements before executing
the AMSERV command again, use the CMS editor to modify the AMSERV input
file.
If you execute the same AMSERV file a number of times, each execution
results in a new LISTING file, which replaces any previous listing file
with the same filename.
When you use AMSERV to print a VSAM file, or to list catalog or recovery
area contents using the PRINT, LISTCAT, or LISTCRA control statements,
the output is written in a listing file on a CMS read/write disk, and
not spooled to the printer unless you use the PRINT option of the AMSERV
command:
)
amserv listcat (print
Sectio~
10. Using Access Method Services and VSAM
183
If you want to save the output, you should issue the AftSERV command
without the PRINT option and then use the CftS PRINT command to print the
LISTING file.
CONTROLLING AftSBRV COMBAND LISTINGS
The final disposition of the listing, as a printer or disk file, depends
on how you enter the AMSERV command. If you enter the AMSERV command
with no options, you get a CMS file with a filetype of LISTING and a
filename equal to that of the AMSERV input file. This LISTING file is
usually written on your A-disk, but if your A-disk is full or not
accessed, it is written on any other read/write CMS disk you have
accessed.
If there is not enough room on your A-disk or any other disk, the
AMSBRV command issues . an error message saying that it cannot write the
LISTING file. If this happens, the LISTING file created may be
incomplete and you may not be able to tell whether or not access method
services actually completed successfully. In this case, after you have
cleared some space on a read/write disk, you may have to execute an
AMSERV PRINT or LISTCAT function to verify the completion of the prior
job.
LISTING files take up considerable disk
them as soon as you no longer need them.
space, so you
If you do not want AMSERV to create a disk file from
can execute the AMSERV command with the PRINT option:
should erase
the listing, you
amserv myfile (print
The listing is spooled to your virtual printer, and no disk file is
created. You might want to use this option if you are executing a PRINT
or LISTCAT control statement and expect a very large output listing that
you know cannot be contained on any of your disks.
You can also control the filename of the output
specifying a second name on the AMSERV command line:
listing file
by
amserv listcat listcat1
In this example, the input file is LISTCAT AMSERV and the output listing
is placed in a file named LISTCAT1 LISTING. A subsequent execution of
this same AMSERV file:
amserv listcat,listcat2
creates a second listing file, LISTCAT2 LISTING,
created from the first execution is not erased.
184
IBM VM/370 CMS User's Guide
so that
the listing
March 30, 1979
Manipulating OS and DOS Disks for Use with
AMSERV
To use CMS VSAM and AMSERV, you can have OS or DOS disks in your virtual
machine configuration. They can be assigned in your directory entry, or
you can link to them using the CP LINK command. You must have read/write
access to them in order to execute any AMSERV function or VSAM program
that requires opening the file for output or update.
Before you can use an OS or DOS
ACCESS command:
disk you must access it with the CMS
access 200 d
The response from the ACCESS command indicates that the disk is in OS or
DOS format:
D(200) R/W - OS
-- or -D(200) R/W - DOS
You can write on these disks only through AMSERV or through the
execution of a program writing VSAM data sets. Once an OS disk is used
with AMSERV or VSAM, CMS considers it a DOS disk, so regardless of
whether you are an OS user, when you access or request information about
a VSAM disk, CMS indicates that it is a DOS disk. You can still use the
disk in an OS or DOS system for VSAM data set processing.
Although the
format
is not
changed,
the "disk
is
still
subject to
any
incompatibilities that can currently exist between OS and DOS disks.
DATA AND MASTERCATALOG SHARING
There are two meanings of "sharing" that must be defined clearly with
respect to the CMS support of VSAM.
The first is that of the
SHAREOPTION parameter found in the DEFINE (and ALTER) command for access
method services.
The SHAREOPTION keyword enables the VSAM user to define bow a
component will be shared across pattitions
(users). Since CMS is a
single-partition, single-user system and there is no data set sbaring
capability in the control program (CP), the built-in data sharing in
VSAM is of no value under CMS.
However. if the VSAM user specifies
SHAREOPTION three fewer lines of code will be executed and. therefore.
that option is recommended.
The ar.a of sharing mos~ familar to CMS users is that of disk
(minidisk) read-sharing provided by CP. For the VSAM user under eMS, it
is still possible to share disks in read-o~ly mode in order to
read-share VSAM components.
However, there 1S a
restriction with
respect to the VSAM master catalog. That is, only one virtual machine
may have the disk containing the master catalog in write status. This
is necessary even if only read functions are being performed during the
session. This is due to the master catalog updating read statistics'at
close time and, when necessary, writing a new control record in the
catalog at open time.
Under the OS/VS and DOS/VS systems (rea1) this is
not a consideration because the master catalog is always on a system
pack and, therefore, always in write status by that system and by the
VSAM routines. The virtual machines (OS or DOS) cannot share the VSAM
cat.log since each thinks it is a "real" system and has control of the
VSAM master catalog.
Section 10. Using Access Method Services and VSAM
185
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-118
Under CMS, it is possible to have the master catalog disk read-only.
A bit in the ACB indicates to VSE/VSAM that it is running under CMS. If.
this bit is on, VSAM will not write to the master catalog for either of
the two cases described above. This allows one or more CftS virtual
machines to share the~SAM maste~ catalog. This assume~ either no other
virtua1 machine has the master catalog disk in write status or only one
virtual machine (DOS, OS, or CMS) has it.
Multiple CMS users may have the VSAM master catalog disk in read-only
status but only one virtual machine may have the same in write status.
with respect to dataset sharing, there is only read-sharing for the CftS
user.
DISK COMPATIBILITY
Since the CMS VSAM support writes VSAM datasets to DOS disks, the
question of disk compatibility is not one between CMS and DOS nor
between CMS or OS but rather between DOS and as disks. In other words,
because CMS actually uses VSE/VSAM for processing VSAM datasets, all
disks used by CMS VSAM are DOS disks. For this reason, we need only
discuss how DOS and as disks are compatible and, because they are
compatible, we can conclude, that CMS and as are also compatible.
In the format-4 DSCB"there is a bit in the VTOC Indicators (byte 59,
bit 0) defined by OS/VS to indicate (when OFF) that a.£ormat-5 label is
included in the VTOC.
This bit is always On under DOS/VSE because Des
does not maintain the format-5 label.
This technique allows OS/VS to
realize when the format-5 is invalid and that it must recompute free
space and rewrite the format-5 so that device integrity is maintained.
Thus, if a disk originally was used (allocated)
under OS/VS and,
subsequently, with DOS/VSE, further allocation could occur under DOS/VSE
but with the format-5 ignored and, therefore, no longer valid. If the
disk was then used under OS/VS and still further allocation performed,
OS/VS would recognize the fact that the format-5 was not valid
(contamination bit turned ON by DOS/VSE) and would rewrite the format-5,
turning the bit OFF.
This shows
that DOS and as disks are compatible in that they are
the two systems, but one of the systems
(OS/VS) must
perform some extra processing (rewriting format-5) prior to using the
disk if it intends to reallocate using the,format-5.
portabl~between
DOS and OS disks containing VSAM datasets are no exception to this.
OS and DOS disks containing VSAM datasets that are used
(~llocated)
under CMS are portable among all three systems. Since CMS uses VSE/VSAM
code, all disks used under CMS to process VSAM datasets become DOS/VSE
disks in that the contamination bit is turned ON as it is when using
DOS/VSE.
The term "minidisk" may be interchanged with ihe word "disk" in the
above explanation if we ,a~e dealing with "virtual" DgS/VSE an~ OS/VS
systems. ~owever, real systems are not aware of, and do not support,
minidisks. ,
It is necessary to distinguish between two types of allocation under
VSAM. The first refers to actual space allocation on the disk, and the
second is that within the dataset itself.
Space for VSAM componepts must be allocated cn the DASD device using
the DEFINE commands. The only component for which the user is able to
186
IBMVM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev Karch 30, 1979 by Supp. SD23-902Q-1 for 5748-118
allocate space is for the .aster catalog, a data space, and a UBIQUE
cluster. In defining the actual DASD space for components, there are
parameters for the DEFINE SPACE command which allows the user to include
a "secondary allocation" specification.
These parameters (CYLIBDERS,
RECORDS, TRACKS)
have this secondary facility only as a syntactic
compatibility with the OS/VS access method services commands. That is,
DOS/VSE
(and, therefore,
CKS)
does not perform
secondary space
allocation on a DASD.
The facility does exist under DOS/VSE (and CftS) to extend data or
index components through already allocated data space, catalog extents,
or UNIQUE cluster extents.
Thus, the CYLINDERS, TRACKS, and RECORDS
parameters of the DEFINE commands for alternate indexes, clusters, and
catalogs do not dynamically allocate DASD space but only extend a
component through existing space.
USING V8/370 MINIDISKS
If you have a VM/370 minidisk in your virtual machine configuration, you
can use it to contain VSAM files. Before you can use it, it aust be
formatted with the IBCDASDI program or other appropriate· operating
system utility program. When you request that a disk be added to your
virtual machine configuration for use with VSAM files under CMS, you
should indicate that it be formatted for use with as or DOS. Or you can
format it yourself using the IBCDASDI program. A brief example of how to
do this is given under the following "Using Temporary Disks."
The
IECDASDI control statements are fully described in the !~L11~ ~~~at2~~§
§~id~.
If you are an as user, you should be careful about allocating
space for VSAM on minidisks. Once you have used CMS AMSERV to allocate
VSAM data space on a minidisk, you should not attempt to allocate
additional space on that minidisk using an OS/VS system. as does not
recognize minidisks, and would attempt to format the entire disk pack
and thus erase any data on it. To allocate additional space for VSAM,
you should use CMS again. If you use the IBCDASDI program to format the
disk, and use the CYLNO parameter, the entire disk is flagged as full,
so that as cannot allocate additional space. Kinidisk space allocation
is fully described in the !!Ll1Q f!g~~i~g ~~g ~I§!~ §~~~~!io~ §~!g~.
l!21~:
USING THE LISTDS COMMAND
For as or DOS disks or minidisks, you can use the LISTDS command to
determine the extents of free space available for use by VSAft. You can
also determine what space is already in use. You can use this
information to supply the extent information when you define VSAM files.
The options used with VSAM disks are:
•
•
EXTENT, to find out what extents are in use, and
FREE, to find out what extents are available.
For example, if you have an
as
disk accessed as a G-disk, and you enter:
listds g (extent
Section 10. Using Access Method Services and VSAM
187
March 30, 1979
The response might look like:
EXT"ENT INFORMATION FOR 'VTOe' ON 'G' DISK:
SEQ TYPE CYL-HD(RELTRK) TO CYL-HD(RELTRK)
OOO.VTOC 09900 1881
0991S
1899
TRACKS
19
i
EXTENT:INFORMATION FOR 'PRIVAT.CORE.IMAGE.LIE' ON 'G' DISK:
SEQ TYPE CYL-HD(RELTRK) TO CYL-HD(RELTRK)
TRACKS
000 DATA 000 01
1
049 18
949
949
EXTENT INFORMATION FOR 'SYSTEM.WORK.FILE~NO.6' ON 'G'
SEQ TYPE CYL-HD(RELTRK) TO CYL-HD(RELTRK)
TRACKS
000 DATA 050 00
950
051 18
987
38
DISK~
You could also determine the extent for a particular data set:
listds ? * (extent
DMSLDS220R ENTER DATA SET NAME:
system recorder file
EXTENT INFORMATION FOR 'SYSTEM RECORDER FILI' ON 'F' DISK:
SEQ TYPE CYL-HD(RELTRK) TO CYL-HD(RELTRK)
TRACKS
000 DATA 102 00
1938
102 18
1956
19
002 DATA 010 06
206
010 08
208
3
LISTDS searches all minidisks accessed until it locates the specified
data set. In this example, the data set occupies two separate extents on
disk F.
If the data set 1S a multivolume data set, extents on all
accessed volumes are located and displayed.
If you want to find the free extents on a particular disk, enter:
listds g (free
FREESPACE EXTENTS
CYL-HD(RELTRK) TO
052 00
988
054 02
1028
08101
1540
FOR 'G' DISK:
CYL-HD (RELTRK)
052 01
989
080 00
1520
098 18
1880
TRACKS
2
493
341
You can use this information when you allocate space for VSAM files.
you enter:
listds
*
If
(free
CMS lists all the free space available on all of your accessed disks.
USING TEMPORARY DISKS
When you need extra space on a temporary basis for use with CMS VSAM and
AMSERV, you can use the CP DEFINE command to define a temporary minidisk
and then use the IBCDASDI program to format it. Once formatted and
accessed, it is available to your virtual >machine for the duration of
your terminal session or until you detach it using the CP DETACH
command. Remember that anything placed on a temporary disk is lost, so
that you should copy output that you want to keep onto permanent disks
hefore you log off.
f88
IBM VM/310 CMS User's- Guide
March 30, 1979
The example below shows a control statement file and an EXEC procedure
that, together, can be used to format a minidisk with the IBCDASDI
program. For a complete description of the control statements used,
refer to the !~L~70 Q~~!g!2~~§ ~y!~g.
The input control statements for the IBCDASDI programs should be
placed in a CMS file, so that they can be punched to your virtual card
reader. For this example, suppose the statements are in a CMS file named
TEMP IBCDASDI:
DASD198
JOB
MSG
DADEF
VLD
VTOCD
END
TODEV=1052,TOADDR=009
TODEV=3330,TOADDR=198,VOLID=SCRATCH,CYLNO=10
NEiVOLID=123456
STRTADR=185,EXTENT=5
Now consider the CMS file named TEMPDISK EXEC:
&ERROR &EXIT 100
CP DEFINE T3330 198 10
CP CLOSE C
CP PURGE READER ALL
ACC 190 Z/Z IPL
CP SPOOL PUNCH CONT TO
PUNCH IPL IBCDASDI Z (NOH)
PUNCH TEMP IBCDASDI
(NOB)
CP SPOOL PUNCH NOCONT
CP CLOSE PUNCH
CP IPL OOC
*
*
*
You execute this procedure by entering the filename of the EXEC:
tempdisk
When the final line of this EXEC is executed, the IBCDASDI program is in
control. You must then signal an attention interruption using the
Attention or Enter key, and you receive the message:
IBC105A DEFINE INPUT DEVICE
You should enter:
input=2540,OOc
to indicate that the control statements should be read from your card
reader, which is a virtual 2540 device at virtual address OCC.
When the IBCDASDI program is finished, your virtual machine is in the
CP environment and must reload CMS (with the IPL command) to b~~in
virtual machine execution. You can then access the temporary disk:
acc 198 c
and CMS responds:
C(198) R/i - OS
Section 10. Using Access Method Services and VSAM
189
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for
5748~XX8
Defining DOS Input and Output Files
Note: lhis information is for VSE/VSAM users. OS/VS VSAM
refer to the section "Defining OS Input and Outpu't Files."
~sers
should
You must use the DLBL command to define VSAM inp~t and output files for
both the AMSERV command and for program execution.
The operands
required on the DLBL command are:
dlbl ddname fi1emode DSN datasetname (options SYSxxx
where "ddname" corresponds to the FILE parametei in the AMSERV file and
"datasetname" corresponds to the entry name or filename of the VSA~
file.
There are several options you can use when issuing
to define VSAM input and output files. These are:
•
the DLBL command
VSAM, which you must use to indicate that the file is a VSAM file.
Note: You do not have to use the VSAM option to identify a file as a
file if you are using any of the other options listed here,
In addition, the
since they imply that the file is a VSAM file.
ddnames (filenames) IJSYSCT and IJSYSUC also indicate that the,file
being defined is a VSAM file.
VSAM
•
EXTENT, which you must use when you are defining a catalog or a VSAM
data space; you are prompted to enter the volume information. This
option effectively provides the function of the EXTENT card in
DOS/VS.
•
MULT, which you must use in order to access a multivolume VSAM file;
you are prompted to enter the extent information.
•
CAT, which you can use to identify a catalog which contains the entry
for the VSAM file you are defining.
•
BUFSP, which you can use to specify
should use during program execution.
the size
of the
Options are entered following the open parenthesis on
line, with the SYSxxx:
buffers VSAM
the DLBL command
assgn sys003 e
d1bl file1 b1 dsn workfile (extent cat cat2 sys003
Additional examples using some of these options are shown below.
USING VSAM CATALOGS
While you are developing and testing your VSAM Frograms in CMS, you may
find it convenient to create and use your own master catalog, which may
be on a CMS minidisk. VSAM catalogs, like any other c1uster# can be
shared read-only among several users.
You name the VSAM master catalog for your terminal session using the
logical unit SYSCAT in the ASSGN command and the ddname IJSYSCT for the
CLBL command. For example, if your VSAM master catalog is located on a
COS disk you have accessed as a C-disk, you would enter:
190
IBM VM/370 CMS User's Guide
assgn syscat c
dlbl ijsysct c dsn mastcat (syscat
Note: When you use the ddname IJSYSCT you do
iSAM option on the DLBL command.
not need to
specify the
You must identify the master catalog at the start of every terminal
session. If you are always using the same master catalog, you might
include the ASSGN and DLBL commands in an EXEC procedure or in your
PROFILE EXEC. You could also include the commands necessary to access
the DOS system residence volume and enter the CMSIDOS environment:
ACCESS 350 Z
SET DOS ON Z (VSAM
ACCESS 555 C
ASSGN SYSCAT C
DLBL IJSYSCT C DSN MASTCAT (SYSCAT PERM
you should use the PERM option so that you do not have to reset the
master catalog assignment after clearing previous DLBL definitions.
You must use the VSAM option on the SET DOS ON command line if you
want to use any access method services function or access VSAM files.
The sample ASSGN and DLBL commands used in the above EXEC are almost
identical with those you issue to define a master catalog using AMSERV.
The only difference is that you must enter the EXTENT option so that you
can list the data spaces that this master catalog is to control.
)
As an example, suppose that you have a 30-cylinder 3330 minidisk
assigned to you to use for testing your VSAM programs under CMS.
Assuming that the minidisk is in your directory at address 333, you
should first acce~s it:
access 333 d
D(333) RIW - OS
If you formatted the minidisk yourself, you know what its label is.
not, you can find out what the label is by using the CMS command:
If
query search
The response might be:
USR191
DOS333
SYS190
SYS19E
Use the
file:
191
333
190
19E
A
C
S
liS
label DOS333
RIW
R/i -
as
RIO
RIO
in the
VOLUMES parameter
in the
MASTC1T AMSERV
DEFINE MASTERCATALOG (NAME
(MASTCAT) ~
VOLUME (DOS333) CYL (4) FILE (IJS1SCT)
)
NOW, to find out what extents on the minidisk you can allocate for VSAM,
use the LISTDS command with the EXTENT option:
Section 10. Using Access Method Services and VSAM
191
listds d (free
The response from LISTDS might look like this:
FREESPACE INFORMATION FOR ID' DISK:
CYL-HD(RELTRK) TO CYL-HD(RELTRK)
TRACKS
000 01
1
000 09
9
9
000 11
11
029 18
569
560
From this response, you can see that the volume table of contents (VTOC)
is located on the first cylinder, so you can allocate cylinders 1
through 29 for VSAM:
assgn syscat c
dlbl ijsysct c dsn mastcat (syscat perm extent
DMSDLB331R ENTER EXTENT SPECIFICATIONS:
19 551
(null line)
After entering the extents, in tracks, g1v1ng the relative track number
of the first track to be allocated followed by the number of tracks, you
must enter a null line to complete the command. A null line is required
because, when you enter multiple extents, entries may be placed on more
than one line. If you do not enter a null line, the next line you enter
causes an error, and you must re-enter all of the extent information.
Note that, as in DOS/VS, the extents must be on cylinder boundaries, and
you cannot allocate cylinder O.
Now you can issue the AMSERV command:
amserv mastcat
A ready message with no return code indicates that the master catalog is
defined. You do not need to reissue the ASSGN and DLEL commands in order
to use the master catalog for additional AMSERV functions.
You can use the AMSERV command to define private catalogs and spaces for
them, also. The procedures for determining what space you can allocate
are the same as those outlined in the example of defining a master
catalog.
For a user catalog, you may use
ddname:
any programmer logical unit, and any
access 199 e
listds e (free
assgn sys001 e
dlbl cat1 e dsn private cat1 (sys001 extent perm
amserv usercat
(
192
IEM VM/370 CMS User's Guide
The file USERCAT AMSERV might contain the following:
DEFINE USERCATALOG (NAME (PRIVATE.CAT1) FILE
(IJSYSUC)CYL (4) VOLUME (DOSVS2) CATALOG (MASTCAT)
After this AMSERV command has completed successfully you can use the
catalog PRIVATE.CAT1. When you issue a
DLBL command to identify a
cluster or data set cataloged in this catalog, you must identify the
catalog using the CAT option on the DLBL command for the file:
assgn sys100 c
dlbl file2 e dsn 1 (sys100 cat cat1
Or, you can define this catalog as a job catalog.
If you want to set up a user catalog as a job catalog so that it will be
searched during all subsequent jobs, you can define the catalog using
the special ddname IJSYSUC. For example:
assgn sys101 c
dlbl ijsysuc c dsn private cat1
(sys101 perm
If you defined a user catalog
(IJSYSUC) for a terminal session and
you use the AMSERV command to access a VSAM file, the user catalog takes
precedence over the master catalog.
This means that for files that
already exist,
only the user catalog is searched.
When you define a
cluster, it is cataloged in the user catalog, rather than in the master
catalog, unless you use the CAT option to override it.
If you want to use additional catalogs during a terminal session, you
first define them just as you would any other VSAM file:
assgn sys010 f
dlbl mycat2 f dsn private cat2 (sys010 vsam
Then,
when you enter the DLBL command for the VSAM file that is
cataloged in PRIVATE.CAT2 use the CAT option to refer to the ddname of
the catalog:
assgn sys011 f
dlbl input f dsn input file
(sys011 cat mycat2
If you want to stop using a job catalog defined as IJSYSUC, you can
clear it using the CLEAR option of the DLBL command:
dlbl ijsysuc clear
Then, the master catalog becomes the job catalog for
with the CAT option.
files not defined
)
Section 10. using Access Method
S~rvices
and VSAM
193
When you define passwords for VSAM catalogs in CftS, or when you use CMS
to access VSAM catalogs that have passwords associated with them, you
must supply the password from your terminal when the AMSERV command
executes. The message that you receive to prompt you for the password
is the same message you receive when you execute access method services:
4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOE AMSERV
FILE catalog
When you enter the proper password, AMSERV continues execution.
DEFINING AND ALLOCATING SPACE FOR VSAM FILES
You can use CMS
use the DEFINE
catalog that is
volumes on which
AMSERV to allocate additional data spaces for VSAM. To
SPACE control statement,
you must have defined the
to control the space, and you must have the volume or
the space is to be allocated mounted and accessed.
For example, suppose you have a DOS-formatted 3330 disk attached to
your virtual machine at virtual address 255. After accessing the disk
and determining the free space on it, you could create a file named
SPACE AMSERV:
DEFINE SPACE (FILE (FILE1) TRACKS (1900) VOLUME (123456) CATALOG (PRIVATE~CAT2 CAT2) )
To execute this AMSERY file, define PRIYATE.CAT2 as a user catalog using
the ddname CAT2, and then define the ddname for the FILE parameter:
access 255 c
assgn sysOl0 c
dlbl cat2 c dsn private cat2 (sysOl0 vsam
assgn sysOl1 c
dlbl file1 c (extent sysOl1 cat cat2
Note that you do not need to enter a data set name to define the space.
When CMS prompts you for the extents of the space you can enter the
extent specifications:
DMSDLB331R ENTER EXTENT SPECIFICATIONS:
190 1900
When you define space for VSAM, you should be sure that the VOLUMES
parameter and the space allocation parameter (whether CYLINDER, TRACKS,
or RECORDS) in the AMSERV file agrees with the information you provide
in the DLBL command.
All data extents must begin and end on cylinder
boundaries. Any additional space you provide in the extent information
that is beyond what you specified in the AMSERV file is claimed by VSAM.
194
IBM VM/370 CMS User's Guide
March 30, 1979
When you are specifying extents for a master catalog, data space, or
unique file, you can specify up to 16 extents on a volume for a
particular space. When prompted by CMS to enter the extents, you aust
separate different extents by commas or place them on different lines.
To specify a range of extents in the above example, you can enter:
dlbl file1 c (extent sys011
190 190, 570 190, 1900 1520
(null line)
or -dlbl file1 c (extent sys011
190 190
570 190
1900 1520
(null line)
Again, the first number entered for each extent represents the relative
track for the beginning of the extent and the second number indicates
the number of tracks.
You can define spaces that span up to nine volumes for VSAM files; all
of the volumes must be accessed and assigned when you issue the DLBL
command to define or identify the data space.
You should remember, though, that if you are using AMSEBV and you do
not use the PBINT option, you must have a read/write CMS disk so that
AMSERV can write the output LISTING file.
If you are defining a new multivolume data space or unique cluster,
you must specify the extents on each volume that the data is to. occupy
(starting track and number of tracks), followed by the disk mode letter
at which the disk is accessed and the programmer logical unit to which
the disk is assigned:
access 135 b
access 136 c
access 137 d
assgn sys001 b
assgn sys002 c
assgn sys003 d
dlbl newfile b (extent sys001
DMSDLB331R ENTER EXTENT SPECIFICATIONS:
100 60 b sys001, 400 80 b sys001, 60 40 d sys003
2000 100 c sys002
(null line)
If you specify more than one extent on the same line, the extents must
be separated by commas; if you enter a comma at the ena of a line, it is
ignored.
Different extents for the same volume must be entered
consecutively.
Note that in the preceding example, the extent informationi~ for
2314 disks; and that these extents are also on cylinder boundaries.
When you
example:
enter multivolume extents you
can use a default
Section 10. Using Access Method
Se~vices
m~de. For
and VSAM.
195
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-IX8
dlbl newfile b (extent sys001
DMSDLB331R ENTER EXTENT SPECIFICATIONS:
100 60, 400 80, 60 40 d sys003,
2000 100 c sys002
(null line)
Any extents you enter without specifying a mode letter and SYSxxx value
default to the mode and SYSxxx on the DLBL command line, in this case,
the B-disk, SYS001.
If you make
any errors issuing the DLEL
command
information, you must re-enter the entire command sequence.
IDENTIFYING EXISTING
IdentIfy-an existing
or
extent
!g~~!!Q~gA~ ~!~~~:
When you issue a DLBL command to
multivolume VSAM file, you must use the MULT option
of the DLBL command:
dlbl old b1 dsn ? (sys002 mult
DMSDLB220R ENTER DATA SET BAME:
dostest.file
DMSDLB330R ENTER VOLUME SPECIFICATIONS:
c sys004, d sys003
e sys007
(null line)
When you enter the DLBL command you should specify the mode letter and
logical unit for the first volume on the command line. When you enter
the MULT option you are prompted to enter additional specifications for
the remaining extents. In the preceding example, the data set has
extents on disks accessed as B~, C-, D-, and E-disks.
USING TAPE INPUT AND OUTPUT
If you are using AMSERV for a function that requires tape input and/or
output, you must have the tape(s) attached to your virtual machine. The
valid addresses for tapes are 181, 182,
183, and 184. When referring to
tapes, you can also refer to them using their CMS symtolic names TAP1,
TAP2, TAP3, and TAP4.
For AMSERV functions that use tape input/output, the TLBL control
statement is
simulated by building
a dummy DLBL
containing a
user-supplied ddname (filename). CMS does not read tape labels and does
not recognize tape data set names.
When you invoke the AMSERV command, you must use the TAPIN or TAPOUT
option to specify the tape device being used:
amserv export (tapout 181
In this example, the output from the AMSERV control statements in a file
riamed EXPORT goes to a tape at virtual address 181. CMS prompts you to
enter the ddname:
DMSAMS367R ENTER TAPE OUTPUT DDNAMES:
After you enter the ddname specified on the FILE parameter in the AMSERV
file and press the carriage return, the AMSERV command executes.
AMSERV opens all tape files as standard labe~led tapes (FILAB=STD on
the DTFMT .acro).
Therefore, tou need a LABELDEF command for any tape
file used for input or output with AMSERV. The LABELDEF command is the
CMS/DOS equivalent of the DOS/VSE TLB control stat'ement. The LABELDEF
command is used to specify information in VOLl and RDR1 labels on the
196
IBM VM/370 CffS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1919 by Supp. SD23-9024-1 for 5148-118
tape.
See the description of the LABELDEF command in section 1 for more
information on this command.
You should use the same name for the filename on your LABELDEP
command as you do for the ddname you enter in reply to message
DMSAMS361R (the ddname specified on the FILE ~arameter in the AMSEBV
file).
However, the LABELDEF command must be issued tefore the AMSEBV
command. The following sequence of commands might be used when you have
tape output:
assgn sys005 tap1
tape rew (181
assgn syscat e
assgn sys006 e
labeldef catout fid catfile volid amserv
dlbl ijsysct e dsn mastcat (syscat vsam
dlbl catin e dsn file (sys006 vsam
amserv repro (tapout 181
DMSAMS361R ENTER TAPE OUTPUT DDNAMES
catout
Note that if you do not care what is written in a tape output label
or do not want input labels checked,
you can specify a LABELDEF with no
parameters other than filename.
The command:
labeldef intape
used for an input tape with ddname INTAPE causes the standard labels cn
the tape to be skipped without any checking. A similar statement for
output writes tape labels with default values (see the description of
the LABELDEP command in section 1).
If you try to use a tape that does not already contain
for an AMSERV tape file, you will receive an error message.
is used for output, this message is followed by another
informs you that you have a choice of continuing by writing
on the previously unlabelled tape or rejecting this tape.
files must already contain standard VOL1 and HDR1 labels to
by AMSERV.
a VOLl label
If the tape
message that
a VOL1 label
Input tape
be processed
Section 10. Using Access Method Services and VSAM
196.1
March 30, 1979
196.2
IBM VM/370 eMS User's Guide
Pg. of GC20-l8l9-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
When you create a tape in CMS using AMSERV, CMS writes a tape mark
preceding each output file that it writes. When this same tape is read
using AMSERV under CMS, HDR1 and VaLl labels are checked using the
LABELDEFcommand you provide~ If you read this tape in a real DOS/VS
system, you should use a TLBL card instead of the LABELDEF command.
Similarly, when you create a tape under a DOS/VS system using access
method services, if the tape is created with sta~dard labels, CMS AMSERV
has no difficulty reading it.
The only time you should worry about positioning a tape created by
AMSERV is when you want to read the tape using a method other than
AMSERV, for example, the MOVEFILE command. Then, you must forward space
the tape past the label, using the CMS TAPE command before you can read
it.
Defining OS Input and Output Files
!!gte: This information is for OS/VS .VSAM users only.
VSE/VSAM users
should r~fer to "Defining DOS Input and output Files" for information on
defining files for use with VSAM.
If you. are going ,to use access method services to manipulate VSAM or SAM
files or you are going .to e~ecute VSAM programs under eMS, you must use
the DLBL command to define the input and output files. The basic format
of the DLBL command is:
DLBL ddname file mode DSN datasetname (options
where ddname corresponds to the FILE parameter in the AMSERV file and
datasetname corresponds to the entry name of the VSAM file, that is, the
name specified in the NAME parameter of an access method services
control statement.
If you are using a CMS file for AMSERV input or
operand and enter CMS file identifiers as follows:
dlbl mine a cms out file1
output, use the CMS
(vsam
The maximum length allowed for ddnames under CMS VSAM is seven
characters. This means that if you have assigned eight-character ddnames
(or filename$)
to files in your programs, only the first seven
characters of each ddname are used. So, ~f a program refers· to the
ddname OUTPUTDD, you should issue the DLBL command for a ddname of
OUTPUTD. Since you can encounter problems with a program that contains
ddnames with the same first seven characters, you should recompile those
programs using seven-character ddnames.
There are several options you can use when iSSUing
to define VSAM input and output files. These are:
•
the DLBL command
VSAM, which you must use to indicate that the file is a VSAM file.
Note: you do not have to use the VSAM option to identify a file as a
file if you are using any of the other options listed here,
si~ce~hey
imply that the file is a VSAM file.
In ~ddition, the
ddnames (filenames) IJSYSCT and IJSYSUC also indicate that the file
being defined is a VSAM file.
VSAM
Section 10. Using Access Method Services and VSAM
197
March 30, 1979
VS~ft
•
EXTENT, which you must use when you are defining a catalog or a
data space; you are prompted to enter the volume information.
•
MULT, which you must use in order to access amultivolu.e VSAM file;
you are prompted to enter the extent information.
•
CAT, which you can use to identify a catalog which contains the entry
for the VSAft file you are defining.
•
BUFSP, which you can use to specify
should use during program execution.
ALLOCATING EXTENTS ON
as
the size
of the
buffers VSAM
DISKS AND ftINIDISKS
When you use access method services to manipulate VSAM files under as,
you do not have to worry about allocating the real cylinders and tracks
to contain the files.
When you use CMS AftSERV, however, you are
responsible for indicating which cylinders and tracks should contain
particular VSAM spaces when you use the DEFINE control state merit to
define space.
Extents for VSAM data spaces can be defined, in AMSERV files, in
terms of cylinders, tracks, or records. Extent information you supply to
CftS when executing AMSERV must always be in terms of tracks.
When you
define data spaces or unique clusters, the extent information (number of
cylinders, tracks, or records) in the AMSERV file must match the extents
you supply when you issue the DLBL command to define the file.
When you
supply extent information for the master catalog, any extents you enter
in excess of those required for the catalog are claimed by the catalog
and used as data space.
CMS does not make secondary space allocation for VSA8 data spaces.
If you execute an AMSERV file that specifies a secondary space
allocation, CMS ignores the parameter.
When you use the DLBL command to define VSAM data space, you must use
the EXTENT option, which indicates to CMS that you are going to enter
data extents. For example, if you enter:
dlbl space b (extent
CMS prompts you to enter the extents:
DMSDLB331R ENTER EXTENT SPECIFICATIONS:
When you enter the extents, you specify the relative track number of the
first track of the extent, followed by the number of tracks. For
example, if you are allocating an entire 2314 disk, you would enter:
20 3980
(null line)
You can never write on cylinder 0, track 0; and, since VSA~ data
spaces must be allocated on cylinder boundaries, you should never
allocate cylinder O. Cylinder 0 is often used for the volume table of
contents (VTOC) as well, so it is always best to begin defining space
with cylinder 1.
The list below shows the DASD devices supported by CMS VSAM~ the
number of cylinders on each that can be allocated for VSAM space, and
the number of tracks per cylinder:
198
IBM tM/370 CMS User's
~uide
;
Disk
2314/2319
3330 Model
3330 Model
3340 Model
3340 Model
3350
~I!!~g~!§
1
11
35
70
200
404
808
348
696
555
I!~£!§L£I!iBg~!
20
19
19
12
12
30
You can determine which disk extents on an as disk or minidisk are
available for allocation by using the LISTDS command with the FREE
option, which also indicates the relative track numbers, as well as
actual cylinder and head numbers.
USING VSAM CATALOGS
While you are developing and testing your VSAM programs in CMS, you may
find it convenient to create and use your own master catalog, which may
be on a CMS minidisk. VSAM catalogs, like any other cluster, can be
shared read-only among several users.
You name the VSAM master catalog for your terminal session using the
ddname IJSYSCT for the DLBL command. For example, if your VSAM master
catalog is located on an OS disk you have accessed as a C-disk, you
would enter:
dlbl ijsysct c dsn master catalog (perm
)
You must define the master catalog at the start of every terminal
session. If you are always using the same master catalog, you might
include the DLBL command you need to define it in your PROFILE EXEC:
ACCESS 555 C
DLBL IJSYSCT C DSN MASTCAT (PERM
You should use the PERM option so that you do not have to reset the
master catalog assignment after clearing previous DLBL definitions. The
command:
dlbl
*
clear
clears all file definitions except those entered with the PERM option.
The sample DLBL command used in the preceding example is almost
identical with the one you would issue to define a master catalog using
AMSERV. The only difference is that you must enter the EXTENT option so
that you can list the data spaces that this master catalog is to
control.
As an example, suppose that you have a 30-cylinder 3330 minidisk
assigned to you to use for testing your VSAM programs under CMS.
Assuming that the minidisk is in your directory at address 333, you
should first access it:
access 333 d
D(333) R/W - OS
Section 10. Using Access Method Services and VSAM
199
If you formatted the minidisk yourself, you know what label you assigned
it; if not, you can find out the label assigned to the disk by issuing
the CMS command:
query search
The response might be:
USR191
VSAM03
SYS109
SYS19E
191
333
190
19E
A
C
S
Y/S
RIll
RIll - OS
RIO
RIO
Use the volume label VSAM03 in the MASTCAT AMSERV file:
DEFINE MASTERCATALOG (NAME
(MASTCAT)VOLUME (VSAM03) CYL (4) FILE (IJSYSCT)
To find out what extents on this minidisk you can allocate for VSAM, use
the LISTDS command with the FREE option:
listds d (free
The response from LISTDS might look like this:
FREESPACE INFORMATION FOR 'D' DISK:
CYL-HD(RELTRK) TO CYL-HD(RELTRK)
TRACKS
000 01
1
000 09
9
9
000 11
11
029 18
569
560
From this response, you can see that the VTOC is located on the first
cylinder, so you can allocate cylinders 1 through 29 for 'SAM:
dlbl ijsysct c dsn mastcat (perm extent
DMSDLB331R ENTER EXTENT SPECIFICATIONS:
19 551
(null line)
After entering the extents, in tracks, g1v1ng the
of the first track to be allocated followed by the
must enter a null line to complete the command. (A
because, when you enter multiple extents, entries
than one line.)
relative track number
number of tracks, you
null line is required
may te placed on more
Now you can issue the AMSER' command:
amserv mastcat
A Ready message with no return code indicates that the master catalog is
defined. You do not need to reissue the DLBL command in order to
identify the master ?atalog for additional AMSERV functions.
You can use the AMSERV command to define private catalogs and spaces for
them. The procedures for determining what space you can allocate are the
same as those outlined in the example of defining a master catalog.
To define a user catalog, you can assign any ddname you want:
200
IBM VM/370 CMS User's Guide
(
access 199 e
listds e (free
dlbl cat1 e dsn private cat1 (extent
amserv usercat
The file USERCAT AMSERV might contain the following:
DEFINt USERCATALOG (NAME (PRIVATE.CAT1) FILE
(CAT1)CYL (4) VOLUME (OSVSAM) CATALOG (MASTCAT)
After this AMSERV command has completed successfully you can use the
catalog PRIVATE.CAT1. When you define a file cataloged in it, you
identify it using the CAT option on the DLBL command:
dlbl file2 c dsn ? (cat cat1
or, you can define it as a job catalog.
During a terminal session, you may be
catalog many times. If this is the case,
by using the ddname IJSYSUC. Then, that
subsequent jobs, unless you override it
use the DLBL command to define a file.
referencing the same private
you can identify a job catalog
catalog is searched during all
using the CAT option when you
If you defined a user catalog
(IJSYSUC) for a terminal session and
you use the AMSERV command to access a VSAM file, the user catalog takes
precedence over the master catalog. This means that for files that
already exist, the job catalog is searched. When you define a cluster,
it is cataloged in the job catalog, rather than in the master catalog,
unless you use the CAT option to override it. CMS never searches more
than one VSAM catalog.
You should use the CAT option to name a catalog when the AMSERV file
you are executing references, with the CATALOG parameter, a catalog that
is not defined either as the master catalog or as a user catalog.
If you want to use additional catalogs during a terminal session, you
first define them just as you would any other VSAM file:
dlbl mycat2 f dsn private cat2 (vsam
Then, when you enter the DLBL command for the VSAM file that is
cataloged in PRIVATE.CAT2 use the CAT option to refer to the ddname of
the catalog:
dlbl input f dsn input file (cat mycat2
)
If you want to stop using a job catalog defined with the ddname IJSYSUC,
you can clear it using the CLEAR option of the DLBL command:
Section 10. Using Access Method Services and VSAM
201
dlbl ijsysuc clear
or, you can assign the ddname IJSYSUC to some other catalog.
clear the ddname for IJSYSUC, then the master catalog becomes
catalog.
If you
the job
When you define passwords for VSAM catalogs in CMS, or when you use CMS
to access VSAM catalogs that have passwords associated with them, you
must supply the password from your terminal when the AMSERV command
executes. The message that you receive to prompt you for the password
is the same message you receive when you execute access method services:
4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOE AMSERV
FILE catalog
When you enter the proper password, AMSERV continues execution.
DEFINING AND ALLOCATING SPACE FOR VSAM FILES
You can use CMS AMSERV to allocate additional data spaces for VSAM. To
use the DEFINE SPACE control statement, you must have defined either the
master catalog or a user catalog which will control the space, and you
must have the volume or volumes on which the space is to be allocated
mounted and accessed.
For example, suppose you have an OS 3330 disk attached to your
virtual machine at virtual address 255. After accessing the disk and
determining the free space on it, you could create a file named SPACE
AMSERV:
DEFINE SPACE (FILE (FILE1) TRACKS (1900) VOLUME (123456) CATALOG (PRIVATE.CAT2 CAT2) )
To execute this AMSERV file, you must define PRIVATE.CAT2 using
ddname CAT2, and then define the ddname for the file:
the
access 255 c
dlbl cat2 c dsn private cat2 (vsam
dlbl file1 c (extent cat cat2
You do not need to enter a data set name to define the space. When CMS
prompts you for the extents of the space, you can enter the extent
specifications:
DMSDLB331R ENTER EXTENT SPECIFICATIONS:
190 1900
When you define space for VSAM, you should be sure that the VOLUMES
parameter and the space allocation parameter (whether CYLINDER, TRACKS,
or RECORDS)
in the AMSERV file agree with the track information you
provide in the DLBL command.
202
IBM VM/370 CMS User's Guide
March 30, 1979
When you are specifying extents for a master catalog, data space, or
unique file, you can specify up to 16 extents on a volume for a
particular space. When prompted by eMS for the extents, you must
separate the different extents by com.as, or place them on different
lines. To specify a range of extents in the'above example, you could
enter:
dlbl file1 c (extent
190 190, 510 190, 1900 1520
(null line)
or -dlbl file1 c (extent
190 190
510 190
1900 1520
(null line)
Again, the first number entered for each extent represents the relative
track for the beginning of the extent and the second number indicates
the number of tracks.
You can define spaces that span up to nine volumes for VSAM files; all
of the volumes must be accessed and assigned when you issue the DLBL
command to define or identify the data ,space.
You should remember, though, that if you are using AMSERV and you do
not use the PRINT option, you must have a read/write CMS disk so that
AMSERV can write the output LISTING file.
If you are defining a new multivolume data space or unique cluster,
you must specify the extents on each volume that the data is to occupy
{starting track and number of tracks), followed by the disk mode letter
at which the disk is assigned:
access 135 b
access 136 c
access 131 d
dlbl newfile b (extent
DMSDLB331R~NTER EXTENT SPECIFICATIONS:
100 60 b, 400 80 b, 60 40 d ,
2000 100 c
(null line)
If you enter more than one extent on the same line, the extents must be
separated by commas; if you enter a comma at the end of a line, it is
ignored.
Different extents for the same volume must be entered
consecutively. Note that in this example, the extent information is for
2314 disks and that these extents are also on cylinder toundaries.
When you enter multi90lume extents, you do not have to enter a mode
letter for those extents on the disk identified in the DLBL com~and.
For the extents on disk B in the abov~ eXample, you could enter:
Section 10. Using Access Methoa Services and VSAM
203
March 30, 1919
dlbl new file b (extent
DMSDLB331R ENTER EXTENT SPECIFICATIONS:
100 400 80, 60, 60 40 d
2000 100c
(null line)
If you make
any errors iss~ing the DLBL
command
information, you must re--enter the entire cpmmand sequence.
or
extent
IDENTIFYING EXISTING MULTIVOLUME lI~~2: When you issue a DLBL command to
IdentIfy-an exIsting mUltIvolume VSAM file, you must use the MULT option
of the DLBL command sequence:
dlbl old bl dsn ? (mult
DMSDLB220R ENTER DATASET NAME:
vsamtest.file
DMSDLB330R ENTER VOLUME SPECIFICATIONS:
c, d
e
(null line)
When you enter the DLBL command you should specify the mode letter for
the first disk volume on the command line. When you enter the MULT
option you are prompted to enter additional specifications for the
remaining extents. In the above example, the data set has extents on
disks accessed as B-, C-, D-, and E-disks.
USING TAPE INPUT AND OUTPUT
If you are using AMSERV for a function that requires tape input and/or
output, you must have the tape(s) attached to your virtual machine. The
valid addresses for tapes are 181, 182,
183, and 184. When referring to
tapes, you can also refer to them using their CES symtolic names TAP1,
TAP2, TAP3, and TAP4.
When you use AMSERV to create or read a tape, you supply the ddname
for the tape device interactively, after you issue the AMSERV command.
You must also supply a LABELDEF command for tape label checking before
you issue the AMSERV command. To indicate to AMSERV that you are using
tape for input or output, you must use the TAPIN or TAPOUT option to
specify the tape device being used:
labeldef tapedd fid filename •••
amserv export (tapout 181
In this example, the output from an EXPORT function is to a
virtual address 181. CMS prompts you to enter the ddname:
tape at
DMSAMS361R ENTER TAPE OUTPUT DDNAMES:
After you enter the ddname (TAPEDD in this example) for
AMSERV begins execution.
the tape file,
AMSERV in CMS. treats all, tape files as having standard labels. The
LABELDEF. command is required because the CMS/DOS routine that performs
the tape open needs la,bel information for standard labelled tapes. See
the description of the LABELDEF command in Section 1 for further
information. The filename you specify~n the LABELDEF command should be
the same one you use to reply to the access method service message that
requested you to supply the tape's ddnames.. However, the LABELDEF
command must be issued before the AMSERV command. If you only want the
tape labels skipped, but not checked, enter a LABELDEF with no
parameters other than filename.
204
IBM VM/310 eMS ~User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for S74S-XXS
Tapes used for input aust always
EOP1 labels or they are rejected by
need to contain VOL1 labels because
volume serial number and have the
However, blank tapes should not be
routine tries to read the tape.
contain standard VOL1, DDR1, and
CftS A!SERV. Output tapes do not
the user is proapted to enter a
VOL1 label written if he wants.
used for output because the open
When you create a tape file using AMSERV under CftS, CMS writes a label
file preceding each output data file. When CftS AMSERV is used to read
this same file,
it checks the HDR1 and VOL1 labels using the LABELDEF
coaaand you provide before it reads the data file. If you want to read
the tape on a real OS/VS system, however, you must use the LABEL=SL as a
paraaeter on the data definition (DD) card for the tape.
Section 10. Using Access Method Services and VSAft
204.1
March 30, 1979
204.2
IBM VM/370 CMS User's Guide
March 30, 1979
If you are creating a tape under OS/VS access method services to be
read by CMS AMSERV, you must be sure to create the tape using standard
labels so that CMS can read it properly. CMS will not be able to read a
tape created with LABEL=(,NL) on the DD card.
For CMS to read this tape for any other purpose (for example, to use
the MOVEFILE command to copy it), you must remember to forward space the
file past the label file before beginning to read it.
Using AMSERV under eMS
This section provides examples of AMSERV functions executed under CMS.
The examples are
applicable to both the CMS
(OS)
and CMS/DOS
environments. You should be familiar with the material presented in
either "Defining DOS Input and output Files" or "Defining OS Input and
Output Files," depending on whether you are a DOS or an OS user,
respectively.
For the examples shown below, command lines and options
that are required only for CMS/DOS users are shaded. OS users should
ignore these shaded entries.
A CMS format variable file cannot be used directly as input to AMSERV
functions as a variable (V) or variable blocked (VB) file because the
standard variable CMS record does not contain the BL and RL headers
needed by the variable record modules. If these headers are not included
in the record, errors will result.
All files placed on the CMS disk by AMSERV viII show a RECFM of V,
even if the true format is fixed (F), fixed blocked (FB), undefined (U),
variable or variable blocked. The programmer must know the true format
of the file he is trying to use with the AMSERV command and access it
properly or errors will result.
A CMS standard variable-format file can be accessed as RECFM=U to use
the file as follows:
AMSERV
AMREPUV
The file AMREPUS AMSERV contains the following 2 cards:
REPRO
INFILE (INPUT ENV(RECFM(U),BLKSZ(800),PDEV(3330»)
OUTFILE (OUTPUT ENV(RECFM(V),BLKSZ(800),RECSZ(84),PDEV(3330»)
The input file can be any CMS file with LRBCL 800 or less. The
output file will be a true variable file that can be used with AMSERV.
USING THE.DEFINE AND DELETE FUNCTIONS
When you use the DEFINE and DELETE control statements of AMSERV, you do
not need to specify the DSN parameter on the DLBL command:
If the above commands are ~xecuted prior to an AMSERV command to define
a master catalog, the DEFINE will be successful as long as you have
assigned a data set name using the NAME parameter in the AMSERV file.
The same is true when you define clusters, or vhen you use the DELETE
function to delete a cluster, space, or catalog.
Section 10. Using Access Method Services and VSAM
205
March 30, 1979
When you do not specify a data set name, AaSHRV obtains the name fro.
the AMSERV file. In the case of defining or deleting space. no data set
name is needed; the FILE parameter corresponding to the ddname is all
that is necessary, and AMSERV assigns a default data se~ name to the
space.
When you define. space on a minidisk using AaSHRV, CI!S does not check
the extents you specify to see whether they are greater than the number
of cylinders available. As long as the starting cylinder is a valid
cylinder number and the extents you specify are on cylinder boundaries,
the DEFINE function completes successfully. However, you receive an
error message when you use an AMSERV function that tries to use this
space.
To define a cluster for VSAM space that has already been allocated, you
n~ed (1) an AMSERV file containing
the control statements necessary for
defining the cluster, and
(2) the master catalog (and, perhaps, user
catalog) volume, which will point to the cluster. The volume on Which
the cluster is to reside does not have to be online when you define a
suballocated cluster.
For example, the file CLUSTER A"SERV .contains the following:
DEFINE CLUSTER
( NAME (BOOK. LIST) VOLUMES (123456) TRACKS (40) F.ILE (BOOK) KEYS (14,0) RECORDSIZE (120,132)
DATA (NAME (BOOK.LIST.DATA) ) INDEX (NAME (BOOK. LIST. INDEX) )
)-
you would need to enter the following command
To execute this file,
sequence (assuming that the master catalog, on volume 123456, is in your
virtual machine at address 310):
access 310 b
"1;.'II[[~~Jm,:tm.l~
dlbl ijsysct b (perm III• •
amserv cluster
Note that to define a suballocated cluster, you do not need to provide a
DLBL command to define it to AMSERV.
For a unique cluster (one defined with the UNIQUE attribute), you must
define the space for the cluster at the same time you define its na.e
and attributes; thus" the volume or volulles on which the cluster is to
reside must be mounted and accessed when you execute the AMSERV command.
You must supply extent information for the cluster's data and index
portions separately.
T.o execute an AMS"ERV file named UNIQUEwhic.h contains the following
(the ellipses indicate that the AMSERV file, is not complete):
206
IBM VM/370 CMS User's Guide
DEFINE CLUSTER (NAME (PAYROLL) ) DATA ( FILE (UDATA) UNIQUE VOLUMES (567890) CYLINDERS (40) .~.
)
-
INDEX ( FILE (UINDEX) ) UNIQUE VOLUMES (567890) CYLINDERS (10) -
...
)
the command sequence should be:
access 350 c
dlbl udata c (extent
DMSDLB331R ENTER EXTENT SPECIFICATIONS:
800 800 c
dlbl uind
tent
600 200 c
amserv unique
)
When you use AMSERV to delete a VSAM cluster, the volume containing the
cluster does not have to be accessed unless the volume also contains the
catalog in which the cluster is defined. In the case of data spaces and
user catalogs or the .aster catalog, however, the volume(s) must be
mounted and accessed in order to delete the space.
When you delete a cluster or a catalog, you do not need to use the
DLBL command, except to define the master catalog; AMSBRV can obtain the
necessary file information from the AMSERV file.
In the case of data
spaces, you must supply a ddna.e (filename) with the DLBL command, but
you do not need to use the DSN parameter.
You should be particularly careful when you are using temporary disks
with AMSERV, that you have not cataloged a temporary data space or
cluster in a permanent catalog. You will not be able to delete the space
or cluster from the catalog.
USING THE REPRO, IMPORT, AND EXPORT (OR EXPORTRA/IMPORTRA)
FUNCTIONS
You can manipulate VSAM files in CMS with the REPRO, IMPORT, and EXPORT
functions of AMSERV.
You can create VSAM files from sequential tape or
disk files (on OS, DOS, or CMS disks) using the REPRO function. Using
REPRO, you can also copy VSAM files into CMS disk files or onto tapes.
For the IMPORT/EXPORT process, you have the option
(for smaller files)
of exporting VSAM files to CMS disks, as well as to tapes.
You cannot, however,
use the EXPORT function to write files onto OS
or DOS disks. Nor can you use the REPRO function to copy ISAM (indexed
sequential) files into VSAM data sets, since CMS cannot read ISAM files.
)
When creating a VSAM file from a non~VSAM disk file, the device track
size must be the maximumBLOCKSIZE in the INFILE statement.
AMSERV
expects a DOS or OS file as input and will not open a disk f~le when the
Section 10. Using Access Method Services and VSAM
207
BLOCKSIZE specified is
device being used.
greater than
the
track capacity
of the
disk
You cannot use the ERASE or PURGE options of the EXPORT command if
you are exporting a VSAM file from a read-only disk. The export
operation succeeds, but the listing indicates an error code 184, meaning
that the erase function could not be performed.
You should not use an EXPORT DISCONNECT function from a CMS minidisk
and try to perform an IMPORT CONNECT function for that data set onto an
OS system~
OS incorrectly rebuilds the data set control block (DSCB)
that indicates how much space is available.
The AMSERV file below gives an example of using the REPRO function to
copy a eMS sequential file into a VSAM file. The CMS input file must be
sorted in alphameric sequence before it can be copied into the VSAM
file, which is a keyed sequential data set (KStS). The VSAM cluster,
NAME.LIST, is defined in an AMSERV file named PAYROLL:
DEFINE CLUSTER ( NAME (NAME.LIST ) VOLUMES (CMSDEV) TRACKS (20) FILE (BOOK) KEYS (14,0) RECORDSIZE (120,132) ) DATA (NAME (NAME.LIST.DATA) ) INDEX (NAME (NAME.LIST.INDEX ) )
To sort the ~MS file, create the cluster
use the following commands:
and copy the eMS file into it,
sort name list a name sort a
DMSSRT604R ENTER SORT FIELDS:
1 14
access 135 c
(perm
name sort
name list
vsam
The file REPRO AMSERV contains:
REPRO
INFILE ( SORT
ENV (RECORDFORMAT (F) BLOCKSIZE (80) PDEV (3330) ) ) OUTFILE (NAME)
When you use the REPRO, IMPORT, or EXPORT functions with tape files,
you must remember to use the TAPIN and TAPOUT options of the AMSERV
command. These options perform two functions:
they allow you to specify
the device address of the tape, and they notify AMSERV to prompt you to
enter a ddname.
In the example below, a VSAM file is being exported
file, TEXPORT AMSERV, contains:
EXPORT
The
NAME.~IST
INlILE (NAME) ~UTFILE (TAPE ENV (PDEV (2400) ) )
208
to a tape.
IBM VM/370 CMS User's Guide
(
March 30, 1979
To execute this AMSERV, you enter the commands as follows:
vsam
labeldef tape f~d tapf volid dept10 exdte 79040
amserv texport (tapout 181
DMSAMS367R ENTER TAPE OUTPUT DDNAMES:
tape
The fid, volid, and exdte parameters on LAB!LDEF are only examples;
you can substitute any value you want for them on your tape label.
WRITING EXECS FOR AMSERV AND VSAM
You may find it convenient to use EXEC procedures for most of your
AMSERV functions, as well as setting up input and output files for
program execution, and executing your VSAM programs. If, for exaaple, a
particular AMSERV function requires several disks and a nuaber of DLEL
statements, you can place all of the required commands in an EXEC file.
For example, if the file below is named SETUP EXEC:
ACCESS
ACCESS
ACCESS
ACCESS
135
136
137
300
B
C
D
G
l'''llil••_~if..
DLBL IJSYSCT G (PERM
f. . . .111Ial.~4.
111111
DLBL FILE1 B DSN FIRST FILE (VSAMjllllllll~
D11.;••_ t l r
DLBL FILE2 C DSN SECOND FILE (VSAMIIIIII
DLBL FILE D DSN THIRD FILE (V SAM
AMSERV MULTFILE
to invoke this sequence
of the EXEC:
;lllllil,:
of commands, all you have to
enter is the name
setup
If you place,
statement:
at the
beginning of
the
EXEC file,
the EXEC
control
&ERROR &EXIT &RETCODE
then, you can be sure that the AMSERV command does not
all of the prior commands completed successfully.
execute unless
For those AMSERV functions that issue response messages, you can use
the &STACK EXEC control statement. For example:
&ERROR &EXIT &RETCODE
ACCESS 305 D
BL
TPUT D (VSAM
LABELDEF TAPE FID FILE1
&ERROR &CONTINUE
&STACK TAPE
AMSERV TIMPORT (TAPIN 181
&IF &RETCODE NE 0 TYPE TIMPORT LISTING
TAPE REW
&EXIT 0
Section 10. Using Access Method Services and VSAM
209
March 30, 1979
When the AMSERV command in the EXEC is executed~ the request for the
tape ddname is satisfied immediately, by the response stacked with the
&STACK statement.
If you are executjng a command that accepts multiple response lines,
you have to stack a null line as follows:
&STACK C .
&STACK
. DLBL M.ULTFILE B
D
l!Qte: You can use the&BEGSTACK control statement to stack a series of
responses in an EXEC, but you must use &STACK to stack a null line.
210
IBM VM/370 eMS
user'.~Guide
Section 11. How VM/370 Can Help You Debug
Your Programs
Debugging is a critical part of the program development process. When
you encounter problems executing application programs or when you want
to test new lines of code, you can use a variety of CP and CftS debugging
commands and techniques to examine your program while it is executing.
You can interrupt the execution of a program to examine and change
your general registers, storage areas, or control words such as the
program status word (PSW), and then continue execution.
Also, you can
trace the execution of a program closely, so you can see where branches
are being taken and when supervisor calls or I/O interruptions occur.
In many cases, you
identify a problem.
may never need to look at a dump
of a program to
Preparing to Debug
)
Before beginning to debug a program, you should have a current program
listing for reference. When you use VM/370 to debug a program, you can
monitor program execution, instruction by instruction, so you must have
an accurate list of instruction addresses and addresses of program
storage areas. You can obtain a listing of your program by using the
PRINT command to print the LISTING file created by the assembler or
compiler. To determine the virtual storage locations of program entry
points, use the LOAD MAP file created by the LOAD and INCLUDE commands.
If you are a CftS/DOS user, use the linkage editor map produced by the
DOSLKED command.
If the program that you are debugging creates printed or punched
output and you will be executing the program repeatedly, you may not
wish all of the output printed or punched.
You should place your
printer or punch in a hold status, so that any files spooled to these
devices are not released until you specifically request it:
cp spool printer hold
cp spool punch hold
When you are finished debugging you can use the CP QUERY command to see
what files are being held and then you can select which files you may
want to purge or release.
When a Program Abends
The most common problem you might encounter is an abnormal termination
resulting from a program interruption. When a program running in a CftS
virtual machine abnormally terminates (abends), you receive, at your
terminal, the message:
DMSITP141T exception EXCEPTION OCCURRED AT address IN ROUTINE name
)
and your virtual machine is returned to the CftS environment. Prom the
message you can determine the type of exception (program check,
operation, specification, and so on), and, often, the instruction
address in your program at which the error occurred.
Section 11. How VM/370 Can Help You bebug Your Programs
211
sometimes this is enough information for you to correct the error in
your source program, recompile it and attempt to execute it again.
ihen this information does not immediately identify the problem in
your program, you can begin debugging procedures using V!/370.
To
access your program's storage areas and registers you can enter the
command:
debug
immediately after rece~v~ng the abend message.
virtual machine in the debug environment.
To check the contents of general
DEBUG subcommand:
This command places your
registers 0 through 15,
issue the
gpr 0 15
If you want to look at only one register, enter:
gpr 3
You might also wish to check the program status word (PSi).
subcommand:
Use the PSi
psw
You can examine storage areas in your program using the X sUbcommand:
X 201AC 20
In this example, the sUbcommand requests a display of 20 bytes,
beginning at location 201AC in your program. User programs executed in
CMS are always loaded beginning at location X'20000' unless you specify
a different address on the LOAD or FETCH com.and.
To identify the
virtual address of any instruction in a program, you only need to add
20000 to the hexadecimal instruction address.
RESUMING EXECUTION AFTER A PROGRAM CHECK
On occasion, you will be able to determine the cause of a program check
and continue the execution of your program. There are DEBUG subcommands
you can use to alter your program while it is in storage and resume
execution.
If, for example, the error occurred because you had forgotten to
initialize a register to contain a zero, you could use the DEBUG
subcommand SET to place a zero in the register, and then resume
execution with the GO subcommand. You can use the GO subcommand to
specify the instruction address at which you want execution to begin:
set gpr 11 0000
go 200BO
An alternate method of specifying a starting address at which execution
is to resume is by using the SET subcommand to change the last word of
the PSi:
set psw
go
212
0
000200BO
IBM VM/370 CMS User's Guide
{
If your program executes successfully, you can then make the
necessary changes to your source file, recompile, and continue testing.
Using DEBUG Subcommands to Monitor Program
Execution
The preceding examples
did not represent a wide
range of the
possibilities for DEBUG subcommands. Nor do they represent the only way
to approach program debugging. Some additional DEBUG subcommands are
illustrated below.
For complete details in using these subcommands,
refer to the !~L170 ~~~ ~Q~~~Bg gBg ~~££2 ~~!~f~Bf~·
When you prepare to debug a program with known problems, or when you
are beginning to debug a program for the first time, you might want to
stop program execution
at various instructions and
examine the
registers, constants, buffers, and so on. To temporarily stop program
execution, use the BREAK subcommand to set breakpoints. You should set
breakpoints after you load the program into storage, but before you
begin executing it. You can set up to 16 breakpoints at one time. For
each breakpoint, you assign a value (id), and an instruction address:
load myprog
debug
break 0 20BCO
break 1 20C10
break 2 20DOO
Then, you can return to CMS and begin execution:
return
start
When the first breakpoint in this
the messages:
example is encountered,
you receive
DEBUG ENTERED.
BREAKPOINT 0 AT 20BCO
Then, in the debug environment, use the subcommands GPR, CSW, CAW, PSi,
and X to display registers, control words, or storage locations.
you can resume program execution with the GO subcommand:
go
If, at any time, you decide that you do not want to finish executing
your program, but want to return to the CMS environment immediately, you
must use the HX subcommand:
hx
,There are three
environment:
)
subcommands
you can
use to
exit
from the
debug
1.
RETURN, to return to the CMS environment when DEBUG is entered with
the DEBUG command
2.
GO, to resume
breakpoint
3.
HX, to halt
environment
program execution when it has been
program
execution entirely
and
interrupted by a
return
to the
Section 11. How VM/370 Can Help You Debug Your Programs
CMS
213
If you try to leave the debug
receive the message:
environment with t~e wrong subcommand you
INCORRECT DEBUG EXIT
and you have to enter the proper
subcommand~
USING SYMBOLS WITH DEBUG
To simplify the process of debugging in theCMS debug environment, you
can use the ORIGIN and DEFINE subcommands. The ORIGIN command allows
you to set an instruction location to serve as the base for all the
addresses you specify. For exa.~le, if you specify:
origin
20000
then, to refer to your virtual storage
enter:
location 201BC, you only need to
x lbc
By setting the DEBUG origin at your program's base address, you can
refer to locations in your program by the virtual storage numbers in the
listing, rather than having to compute the actual virtual storage
address each time.
The current DEBUG origin stays in effect until you
set it to a different value or until you reload CMS
(with the IPL
command).
You can use the DEFINE subcommand to assign symbolic names to storage
locations so that you can reference those locations by symbol, rather
than by storage address. For example, suppose that during a DEBUG
session you will repeatedly be examining three particular storage
locations labeled in your program NAME1, NAftE2, and NAME3. They ar~ at
locations 20EFO, 20EFA, and 20F04. Enter:
load nameprog
debug
origin 20000
define namel EFO
define name2 EFA
define name3 F04
break 1 a04
return
start
10
10
10
When the specified breakpoint is
storage areas by entering:
encountered, you
can examine
these
x name1
x name2
x name3
You can also refer
subcommand:
to these
symbols by
name when
you use
the STORE
store name2 c4c5c3c5c1e4e5d6c9d9
The names you specify do not have to be the same as the
program; you can define any name up to eight characters.
Figure 17 summarizes the DEBUG subcommands.
214
IBM Vft/370 CMS User's Guide
labels in the
(
Subcommand Format
Function
BReak id {SY.bOI}
hexloc
IStops prograa execution at the
Ispecified breakpoint.
CAW
IDisplays the contents of the
Ichannel address word.
CSW
IDisplays the contents of the
Ichannel status word.
r
IAssigns a symbolic name to the
Ivirtual storage address.
,
DEFine symbol hexloc Ibytecountl
I
~
I
L
I
I
..J
r
r
,
,
IDumps the contents of specified
DUap Isymbol1 Isyabol21 [ident] I Ivirtual storage locations to the
Ihexloc1 Ihexloc21
I Ivirtual spooled printer.
I
.Q
I
* I
I I
L
1l..J
L
r
)
..J
I
GPR reg1 [reg2]
IDisplays the contents of the
Ispecified general registers.
HI
IHalts execution and returns to
Ithe CftS command environment.
r
ISpecifies the base address to be
ladded to locations specified in
lother DEBUG subcommands.
,
ORigin Isymboll
Ihexlocl
I
.Q I
L
I
I
..J
PSi
IDisplays. the contents of the old
Iprogram status word.
RETurn
IExits from debug environment to
Ithe CftS command environment.
SET {CAi bexinfo
}
CSi hexinfo [hexinfo]
PSi hex info [hexinfo]
GPR reg hexinfo [hexinfo]
IChanges the contents of specified
Icontrol words or registers.
I
STore {symbol} hexinfo [hexinfo]
{hexloc}
Istores up to 12 bytes of informaItion starting at the specified
Ivirtual storage location.
r
I
symbol
,
I
n
I
1!~1!g!l!1
L
..J
r
hexloc
I
Figure 17.
,
I n I
L
)
I
IReturns control to your program
land starts execution at the
Ispecified location.
,
GO Isymboll
Ihexlocl
L
..J
~
I
..J
I
IExamines virtual storage
Ilocations.
I
I
I
I
I
I
Summary of DEBUG Subcommands
Section 11. How Vft/370 Can Help You Debug Your Programs
215
What To Do When Your Program Loops
If, when your program is executing, it seems to be in a loop, you should
first verify that it is looping, and then interrupt its execution and
either (1)
halt it entirely and return to the CftS environment or (2)
resume its execution at an address outside of the loop.
The first indication of a program loop may be either what seems to be
an unreasonably long processing time, or, if you have a blip character
defined, an inordinately large number of blips.
You can verify a loop by checking the PSi frequently. If the last
word repeatedly contains the same address, it is a fairly good
indication that your program is in a loop. You can check the PSW by
using the Attention key to enter the CP environment.
You are notified
by the message:
CP
that your virtual machine is in the CP environment.
the CP command DISPLAY to examine the PSW:
You can
then use
cp display psw
and then enter the command BEGIN to resume program execution:
cp begin
If you are checking for a loop, you might
same line using the logical line end:
enter both commands
on the
cp d plb
When you have determined that your program is in a loop, you can halt
execution using the CMS Immediate command HI. To enter this command,
you must press the Attention key once to interrupt program execution,
then enter:
hx
If you want your program to continue executing at an address past the
loop, you can use the CP command BEGIN to specify the address at which
you want to continue execution:
cp begin 20cdO
Or, you could use the CP command STORE to change the instruction address
in the PSW before entering the BEGIN command:
cp store psw 0 20cdOIbegin
Tracing Program Activity
When your program is in a loop, or when you have a program that takes an
unexpected branch, you might need to trace the execution closely to
determine at what instruction the program goes astray. There are two
commands you can use to do this.
The SVCTRACE command is a CMS command
which traces all SVCs
(supervisor calls) in your program.
The TRACE
command is a CP command which allows you to trace different kinds of
information, including supervisor call instructions.
216
IBM VM/370 CMS User's Guide
(
USING THE CP TRACE COKKAND
You can trace the following kinds of
TRACE command:
•
•
•
•
activity in a program using the CP
Instructions
Branches
Interrupts (including program, external, I/O and SVC interrupts)
I/O and channel activity
When the TRACE command executes, it traces all your virtual machine's
activity; when your program issues a supervisor call, or calls any CftS
routine, the TRACE continues.
You can make most efficient use of the TRACE command by starting the
trace at a specific instruction location. You should set an address
stop for the location.
For example, if you are going to execute a
program and you want to trace all of the branches made, you would enter
the following sequence of commands to begin executing the program and
start the trace:
load progress
cp adstop 20004
start
ADSTOP AT 20004
cp trace branch
cp begin
NOW, whenever your program executes a branch instruction,
information at the terminal that might look like this:
)
02001E BALR
05E6
==)
you receive
020092
This line indicates that the instruction at address 2001E resulted in a
branch to the address 020092. When this information is displayed, your
virtual machine is placed in the CP environment, and you must use the
BEGIN command to continue execution:
cp begin
When you locate the branch that caused the problem in your program, you
should terminate tracing activity by entering:
cp trace end
and then you can use CP commands to continue debugging or you can use
the EXTERNAL command to cause an external interruption that places your
virtual machine in the debug environment:
cp external
You receive the message:
DEBUG ENTERED.
EXTERNAL INTERRUPT
And you can use the DEBUG subcommands
program.
to investigate the status of your
)
Section 11. How Vft/370 Can Help You Debug Your Programs
217
There are several things you can do to control the amount of information
you receive when you are using the TRACE command, and how it is
received. For example, if you do not want program execution to halt
every time a trace output message is issued, you can use the RUN option:
cp trace svc run
Then, you can halt execution by pressing the Attention key when the
interruption you are waiting for occurs.
You should use this option if
you do not want to halt execution at all, but merely want to watch what
is happening in your program.
Similarly, if you do not require your trace output immediately, you
can specify that it be directed to the printer, so that your terminal
does not receive any information at all:
cp trace inst printer
When you direct trace output to a printer, the trace output is mixed in
with any printed program output. If you want trace output separated
from other printed output, use the CP DEFINE command to define a second
printer at a virtual address lower than that of your printer at OOE. For
example:
cp define printer 006
Then, trace output will be in a separate spool file.
always goes to the printer at address OOE.
When you finish tracing,
virtual printer file:
use the
CP CLOSE
C8S printed output
command
to close
the
cp close e
-- or -cp close 006
If you want trace output at the printer and at the terminal, you can use
the BOTH option:
cp trace all both
If you are debugging a program
many SVCs, and you are tracing
wish to have tracing in effect
control. When you notice that
program, you can enter:
that does a lot of I/O, or that issues
instructions or branches, you might not
when the supervisor or I/O routine has
addresses being traced are not in your
cp trace end
and then set an address stop at the location in your program
receives control when the supervisor or I/O routine has completed:
cp adstop 20688
begin
218
IBM VM/370 CMS User's Guide
that
4(
Then, when
command.
this address is encountered,
you can re-enter the
CP TBACE
USING THE SVCTBACB COftMAND
If your program issues many SVCs, you may not get all of the information
you need using the CP TBACE command.
The SVCTBACE command is a CBS
command, which provides more detailed information about all SVCs in your
program, including register contents before and after the SVC, the name
of the called routine, and the location from which it was called, and
the contents of the parameter list passed to the SVC.
The SVCTBACB command has only two operands, ON and OFF, to begin and
end tracing. SVCTRACB information can be directed only to the printer,
so you do not receive trace information at the terainal.
Since the SVCTRACB command can only be entered frail the CBS
environment, you must use the I.mediate commands SO (suspend tracing) or
HO (halt tracing) if you want tracing to stop while a prograa is
executing. Use the Immediate command RO to resume tracing.
Since the CMS system is "SVC-driven", this debugging technique can be
useful, especially, when you are debugging eftS programs. For more
inforaation on writing programs to execute in CftS, see "Section 13.
Programming for the CMS Environment."
Using CP Debugging Commands
In addition to the CftS debugging facilities, there are CP commands that
you can use to debug your programs. These commands are:
•
DISPLAY, which you can use to
control words, like the PSW
examine virtual storage, registers, or
•
ADSTOP, which you can use to set
program
•
STORB, which you can use to change
location, register, or control word
an instruction
the
a~dress
contents of
stop in your
a
storage
When you use the display command, you can request an EECDIC translation
of the display by prefacing the location you want displayed with a "T":
cp display t20000.10
This command requests a display of X'10' (16) bytes beginning at
location X'20000'. The display is formatted four words to a line, with
EECDIC translation at the left, much as you would see it in a dump.
You can also use the DISPLAY command
registers. For example, the commands:
to
examine
the
general
cp display g
cp display gl
cp display g2-5
)
result in displays of all the general registers, of general register 1,
and of a range of registers 2 through 5.
Section 11. How VM/370 Can Help You Debug Your programs
219
The DISPLAY command also displays the PSi, CAW, and CSW:
cp display psw
cp display caw
cp display csw
With the STORE command,
storage areas, or the PSW.
you can change
the contents
of registers,
As you can see, the CMS DEBUG subcommands and the CP commands ADSTOP,
DISPLAY, and STORE, have many duplicate functions.
The environment you
choose to work in, CP or debug, is a matter of personal preference. The
differences are summarized in Figure 18. What you should be aware of,
however, is that you should never attempt to use a combination of CP
commands and DEBUG subcommands when you are debugging a program. Since
DEBUG itself is a program, when it is running (that is, when you are in
the debug environment), the registers that CP recognizes as your virtual
machine's registers are actually the registers being used by DEBUG.
DEBUG saves your program's registers and PSW and keeps them in a special
save area. Therefore, if you enter the DEBUG and CP commands to display
registers, you will see that the register contents are different:
gpr 0 15
tcp d g
DEBUGGING WITH CP AFTER A PROGRAM CHECK
When a program that is executing under CMS abends because of a program
check, the DEBUG routine is in control and saves your program's
registers, so that if you want to begin debugging, you must use the
DEBUG command to enter the debug environment.
I
~
You can
prevent DEBUG from
gaining control when
a
interruption occurs by turning on the wait bit in the program
(location X'68' in low storage):
program
new PSW
,\
cp store 68 00020000
You should do this before you begin executing your program. Then, if a
program check occurs during execution, when CP tries to load the progra.
new PSW, the wait bit forces CP into a disabled wait state and you
receive the message:
DMKDSP450W CP ENTERED; DISABLED WAIT PSW
All of your program's registers and storage areas remain exactly as they
were when program interruption occurred. The PSW that was in effect
when your program was interrupted is in the program old PSW, at location
X'28'.
Use the DISPLAY command to examine its contents:
cp display 28.8
The program new PSW, or the PSW you see if you enter the command DISPLAY
PSW, contains the address of the DEBUG routine.
If, after using CP to examine your registers and storage areas, you
can recover from the problem, you must use the STORE command to restore
the PSW, specifying the address of the instruction just before the one
indicated at location X'28',. For example, if the instruction address in
your program is X'566' enter:
220
IBM VM/310 CMS User's Guide
(
cp store psw 0 20566
cp begin
In this example, setting the first word of the PSi to
bit off, so that execution can resume.
0 turns the wait
Program Dumps
When a program you execute under eMS abnormally terminates, you do not
automatically receive a program dump. If, after attempting to use CMS
and CP to debug interactively, you still have not discovered the
problem, you may want to obtain a dump. You might also want to obtain a
dump if you find that you are displaying large amounts of information,
which is not practical on a terminal.
Depending on whether you are using CMS DEBUG or CP to do your
debugging, you can use the DUMP command to specify storage locations you
want printed. The formats of the DUMP command
(CP)
and the DUMP
subcommand (DEBUG) are a little different. See !~Ll1~ £~~ £2!~~~g ~~g
Macro Reference for a discussion of the DEBUG subcommand, DUMP; see
!~LJ1~-~g ~giii~g R~!~~~~£~ !~ Q~~~~~1 Q2~§ for a discussion of the CP
DUMP command.
In either event, you can selectively dump portions of your virtual
storage, your entire virtual storage area, or portions of real storage.
For example, in the debug environment, to dump the virtual storage space
that contains your program, you would enter:
dump 20000 20810
The second value depends upon the size of your program.
From the CP environment, enter:
cp dump t20000-20810
The CP DUMP command allows you to request EBCDIC translation
hexadecimal dump.
The dump produced by the DEfUG subcommand
provide EBCDIC translation.
with the
does not
Debugging Modules
You can debug nonrelocatable MODULE files
(created with the GENMOD
command) in the same way you can debug object modules (TEXT files).
To load the MODULE into storage, use the LOADMOD command:
loadmod mymod
cp adstop 201CO
start
If you make any changes to the module while it is in your virtual
storage area and then issue the GENMOD command, the changes are a
permanent part of the executable module:
loadmod mymod
cp store 201CO 0002
genmod mymod
)
To debug MODULE files in this manner, you must have a listing
program as it existed when the module was created.
Section
~1.
How VM/310 Can Help You Debug Your Programs
of. the
221
Comparison of CP and CMS Facilities for Debugging
If you are debugging problems while running CftS, you can choose the CP or CMS debugging
tools. R~fer to Figure 18 for a comparison of the CP and C!S debugging tools.
Function
ces
CP
,
I
-------------------------------------------------------------------------------------1
Setting
Can set only one address stop at a time.
Can set up to 16 address stoFsl
address
stops.
at a time.
contents I with EBCDIC translation. The storage adof storagel dress of the first byte of each line is
to the
I identified at the left.
Frinter. I
I
decimal format. The storage
1
address of the first byte of I
each line is identified at the
left. The contents of general
and floating-po~nt registers
are printed at the beginning
of the dump.
I
I
----------------------------------------------------------------------------------1
rumping
The dump is printed in hexadecimal format
The dump is Frinted in hexa- 1
,
I
Displaying'
the con- ,
tents of I
storage
,
and
,
control
I
registers I
at the
,
terminal. ,
The display is typed in hexadecimal format
with EBCDIC translation. The CP command
I
disFlays storage keys, floating-point regi-I
sters and control registers.
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
full word 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
cr CSW. However, data can be stored in the
CSW or CAW by specifying the hardware address in the STORE command.
The CMS command stores up to
12 bytes of informatien. CftS
stores data in the general
registers tut net in the
floating-point er control registers~ CftS stores data in the
PSi, CAi, and CSW.
Tracing
information.
CP traces:
• All interruptions, instructions, and
branches
• SVC interruptions
• I/O interruptions
• program interruptions
• External interruptions
• privileged instructions
• All user I/O operations
• Virtual and real CCi's
• All instructions
CMS traces all SVC interruFtions. CMS displays the
contents of general and
floating-point registers
before and after a routine is
called. The parameter list is
recorded before a
routine is called.
The display is tYFed in hexadecimal format. Tbe C!S commands do ~! display storage
keys, floating-Foint registers
I or control registers as the CP
I command does.
,
I
I
The CP trace is interactive. You can stop
it and display other fields.
'Figu~e
18.
Comparison of CP and CMS Facilities for Debugging
(
222
IBM VM/370 eMS User's Guide
March 30, 1979
What Your Virtual Machine Storage Looks Like
Figure 19 illustrates a simplified CMS storage map. The portion of
storage that is of most concern to you is the user program area, since
that is where your programs are loaded and executed. 1he user program
area and some of the other areas of storage shown in the figure are
discussed below in general terms.
When you issue a LOAD command (for OS or CMS programs) or a FETCH
command (for DOS programs), and you do not specify the ORIGIN option,
the first, or only, program you load is loaded at location X'20000', the
beginning of the user program area.
The upper limit, or maximum size, of the user program area is
determined by the storage size of your virtual machine. You can find
out how large your virtual machine is by using the CP QUERY command:
cp query virtual storage
If you need to increase the size of your virtual machine,
must use the CP command DEFINE. For example:
then you
cp define storage 1024k
increases the size of your virtual machine to 1024K bytes.
If you are
in the CMS environment when you enter this command, you receive a
message like:
STORAGE = 01024K
DMKDSP450W CP ENTERED; DISABLED WAIT PSi '00020000 00000000'
and you must reload CMS with the IPL command before you can continue.
You might need to redefine your virtual machine to a larger size if
you execute a program that issues many requests for free storage, with
the OS GETMAIN or DOS/iS GETVIS macros. CMS allocates this storage fro.
the user program area.
At the top of the user program area are the loader tables, that are
used by the CMS loader to point to programs that have have been loaded.
You can increase the size of this area with the CMS SET LDRTBLS command.
If you use the SET LDRTBLS command, you should issue it immediately
after you IPL CMS.
The transient program area is used for loading and executing
disk-resident CMS MODULE files that have been created using the ORIGIN
TRANS option of the LOAD command, followed by the GENMOD cOllmand. For
aore information on CMS MODULE files and the transient area, see
"Executing Program Modules" in "Section 13. Programming for the C!S
Environment."
~HARED
AND NONSHARED SYSTEMS
The areas in storage labeled in Figure 19 as the C!S nucleus and the
ncss are system programs that are loaded by various types of requests.
When you enter the command:
cp ipl ems
~I
Section
~1.
How iM/370 Can Help You Debug Your Programs
223
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
~-------------------,
I
I
I
I
I
I
I
DCSS
I
I
I
I
I
I
I
"1
Loader Tables
X'n'
(where n = your
virtual machine
storage size)
User Program Area
X'20000'
CMS Nucleus
X'10000'
Transient program Area
X'EOOO'
Free storage used by
CMS routines
X'8000'
Low-storage
CMS routines
X'40CO'
System Control Blocks,
Pointers, Flags
X'O'
Figure
19~
Simplified CMS Storage Map
the area shown as the CMS nucleus is loaded with the CMS system, which
is known to CP by its saved name, CMS~ This saved system is a copy of
the CMS system that is available for many users to share. When you are
using CMS, you share it with other users who have also issued the IPL
command to load the saved CMS system.
By having many userS share the
same system, CP can manage system resources more efficiently.
Under some circumstances, you may need to lead the eMS system into
your virtual machine by entering the IPL command as follo~s:
cp ipl 190
This IPL command loads the CMS system bj r~ferring to its virtu~l
address, which in most installations is 190. The copy of CMS you load
this way is ncnshared; it is your own copy, but it is the same system,
functionally, as the sa ved system CMS.
.
Some of the CP and CMS debugging commands do not allow you to trace
or store information that is contained in shared areas of your virtual
machine. For example, if you have entered the command:
cp trace inst
224
IBM VM/370 CMS User's Guide
to trace instructions in your virtual machine, some of the instructions
may be located in the CMS nucleus. If you have ~ shared copy of CMS, you
receive a message like:
REPLACED WI!E NONSEARED COpy
DMKATS181E SHARED SYSTEM CMS
and CP
users.
loads a copy
of CMS for
]i§f~~!igy~y§ §~!~g 2~g!~~!§
you that you. do not share
with other
(~~~~)
Some CMS routines and programs are stored on disks and loaded into
storage as needed. These segments
include the CMS editor, EXEC
processor, and OS simulation routines; CMS/DOS; VSAM; and access method
services. Beyond the end of your virtual machine address space is an
area of storage into which these segments are loaded when you need them.
Since this area is not contiguous with your virtual storage, the
segments that are loaded in this area are called discontiguous saved
segments.
These segments are loaded only when you need them, and are released
fro. the end of your virtual machine when you are through using them.
Like the CMS system, they are saved systems and can be shared by many
users. For example, whenever you issue the lIlT com~and' the segment
named CMSSEG is loaded; when you enter the EtIT subcommands FILE or
QUIT, the saved system CMSSEG is released. The other segments are named
CMSDOS (forCMS/DOS), CMSVSAM (for VSAM interfaces), and CMSAMS (fer
access method services interfaces). These names are the defaults; they
can be changed by the installation.
You can specifically request a nonshared copy of a segment ty loading
the named sy~tem by volume rather than by name. If you do not do this
before altering a shared segment (unless with the AISTOP, TRACE, or
STORE CP commands), CP issues the message DMKVMA456W and places you in
console function mode.
In addition, for the CMSSEG segment only, you can indicate an
alternate segment to be loaded on the IPL command. The format of the
IPL command to support this is:
IPL { cuu
} PARM SEG=segmentname
systemname
SEG=segmentname
indicates the name of the saved segment to be loaded whenever the
CMS editor, EXEC processor, or OS simulation routines are needed.
Eight characters must be entered for segmentname; either assign an
eight-character segment name when you code the NAMESYS macro fer
your installation, or be sure that the operator enters trailing
blanks if segmentname is less than eight characters long.
The CMS batch facility loads whatever segment is specified
first IPL command issued for the batch virtual machine. Thus,
first IPL command for a CMS batch facility machine is:
on the
if the
IPL CMS PARM SEG=CMSSEG02
all subsequent IPL commands issued by the
specify the same segment name (CMSSEG02).
)
eMS
batch facility
will
For additional information on saved systems, discontiguous saved
segments, and CMS virtual storage, see the !~L~lQ §I§!~! E~gg!g~~~~~§
.§yid~.
Section 11. How VM/370 Can Help You £ebug Your programs
225
(
226
IBM VM/370 eMS User's Guide
Section 12. Using the eMS Batch Facility
The CMS batch facility provides a way of submitting jobs for
processing in CMS. You can use the CMS batch facility when:
batch
•
You have a job (like an assembly or execution) that takes a lot of
time, and you want to be able to use your terminal for other work
while the time-consuming job is being run.
•
You do not have access to a terminal.
The CMS batch facility is really a virtual machine, generated and
controlled by the system operator, who logs on VM/370 using the batch
userid and invoking the CMSBATCH command.
All jobs sutmitted for batch
processing are spooled to the userid of this virtual machine, which
executes the jobs sequentially. To use the CMS batch facility at your
location, you must ask the syste. operator what the userid of the batch
virtual machine is.
Submitting Jobs to the eMS Batch Facility
Under a real os or DOS system, jobs submitted in batch mode are
controlled by JCL specifications. Batch jobs submitted to the CMS batch
facility are controlled by the control cards /JOB, /SET, and /*, and by
CMS commands.
)
Any application or development program
written in a language
supported by VM/370 may be executed on the batch facility virtual
machine. However, there ~re restrictions on programs using certain CP
and CMS commands, as described later in this section.
INPUT TO THE BATCH MACHINE
Input records must be in card-image format, and may be punched on real
cards, placed in a CMS file with fixed-length, SO-character records, or
punched to your virtual card punch. These jobs are sent to the batch
virtual machine in one of two w~ys:
•
By reading the real punched card input into the system card reader
•
By spooling your virtual
batch virtual machine
card punch
to the
virtual reader
of the
When you submit a real card deck to the batch machine, the first card
in the deck must be a CP ID card. The ID card takes the form:
r
lID
)
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.
Section 12. Using the eMS Batch Facility
227
For example, if your installation's batch
userid of BATCH1, you punch the card:
virtual
machine has
a
ID BATCH1
and place it in front of your deck.
When you are going to submit a job using your virtual card punch, you
must first be sure that your punch is spooled to the virtual reader of
the batch virtual machine:
cp spool punch to batch1
Virtual card input can be spooled to the batch machine in several ways.
You may create a CMS file that contains the input control cards and use
the CMS PUNCH command to punch the virtual cards:
punch batch jcl (noheader
When you punch a file this way, you must use the NOHEADER option of the
PUNCH command, since the CMS batch facility cannot interpret the header
card that is usually produced by the PUNCH command. As it does with
cards in an invalid format, the batch virtual machine would flush the
header card.
You can use an EXEC procedure to submit input to the batch machine.
From an EXEC, you can punch one line at a time into your virtual punch,
uS1ng the &PUNCH and &BEGPUNCH EXEC control statements. When you do
this, you must remember to use the CP CLOSE comm~nd to release the spool
punch file when you are finished:
CP CLOSE PUNCH
If you are using the EXEC to punch individual lines and entire CMS files
to be read by the batch virtual machine as one continuous job stream,
you must remember to spool your punch accordingly:
CP SPOOL PUNCH CONT
&PUNCH /JOB BOSWELL 999888
PUNCH BATCH JCL
(NOHEADER
CP SPOOL PUNCH NOCONT
CP CLOSE PUNCH
*
A /JOB card must precede each job to be executed under the batch
facility. It identifies your userid to the batch virtual machine and
provides accounting information for the system. It takes the form:
/JOB
userid accntnum [jobname] [comments]
(
228
IBM VM/370 CMS User's Guide
is your user identification, or the userid under which you
want the job submitted. This parameter controls:
(1)
The
userid charged by the CP accounting routines for the system
resources used during a job.
(2) The name and distribution
code that appear on any spooled printer or punch output.
(3)
The userid to whom status messages are sent while the batch
machine is executing the job.
userid
Note that items 1 and 2 are correct only if the directory for
the userid involved contains the accounting option.
accntnum
is your account number. This account number appears in the
accounting data generated at the end of your job.
It
overrides the account number in the CP directory entry for the
userid specified for this job.
jobname
is an optional parameter that specifies the name of the job
being run.
If you specify a jobname, it appears as the CP
spool file identification in the filetype field. The filename
field always contains CMSBATCH. See "Batch Facility Output"
below.
comments
may be any additional information you want to provide.
The 1* card indicates the
takes the form:
end of a job
to the batch
facility.
It
1*
J
)
The batch facility 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 1* card is also treated as an end-of-file indicator when a file
is being read from the input stream. This is a special technique used in
submitting source or data files through the card reader and is discussed
under "A Batch EXEC for Non-CMS 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:
ISET
)
[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.
number
of
the maximum number of lines
Section 12. Using the eMS Batch Facility
229
cards
is a decimal number that specifies the maximum number of cards
a job can punch.
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 /SET 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.
A /SET card can appear anywhere in the job following the /JOB card.
The new limits defined by the /SET card apply only to the part of the
job that follows the /SET card.
A job can contain up to three /SET cards (one for each operand); a
/SET card cannot be entered more than once for the same operand.
Only use /SET cards for the operands whose values you want to change
from the default; the default values are reset between jobs.
A/SET
card for an operand overrides its default but does not reset the other
operands.
HOW THE BATCH FACILITY WORKS
The CMS batch facility, once initialized, runs continuously.
When it
begins executing a job, it sends a message to the userid of the user
submitting the job. If you are logged on when the batch machine begins
executing a job that you sent it, you receive the message:
MSG FROM BATCHID:
JOB 'yourjob' STARTED
When the batch machine finishes processing a job, it sends the message:
MSG FROM BATCHID:
JOB 'yourjob' ENDED
where yourjob is the jobname you specified on the /JOB card. Before it
reads the next job from its card reader, the batch virtual machine:
•
•
•
•
•
Closes all spooling devices and releases spool files
Resets any spooling devices identified by the CP TAG command
Detaches any disk devices that were accessed
Punches accounting information to the system
Reloads CMS
All of this "housekeeping" is done by the CMS batch facility
each job that is executed is unaffected by any previous jobs.
If a job that you sent to the batch virtual machine
abnormally (abends), the batch machine sends you a message:
MSG FROM BATCHID:
so that
terminates
JOB 'yourjob' ABEND
and spools a CP storage dump of your
The remainder of your job is flushed.
virtual machine to
Whenever the batch virtual machine has read and executed
jobs in its card reader, it waits for more input.
the printer.
all of the
(
230
IBM VM/370 CMS User's Guide
Preparing Jobs for Batch Execution
When you want to submit a job to the CMS batch facility for execution,
you should provide the same CMS and CP commands you would use to prepare
to execute the same job in your own virtual machine.
You must provide the batch virtual machine with read access to any
disk input files that are required for the job. You do this by supplying
the LINK and ACCESS command lines necessary. The batch virtual machine
has an A-disk (195), so you can enter commands to access your disks as
read-only extensions. For example, if you wanted the batch machine to
execute a program module named LONDON on your 291 disk, your input file
might contain the following:
IJOB FISH 012345
CP LINK BOSWELL 291 291 RR SECRET
ACCESS 291 BIA
LONDON
Similarly, if you are using the batch virtual machine to
program using input and output files,
you must supply
definitions:
)
execute a
the file
CP LINK ARDEN 391 391 RR FOREST
ACCESS 391 BIA
FILEDEF INFILE DISK VITAL STAT B
FILEDEF OUTFILE PUNCH
CP SPOOL PUNCH TO BOSWELL
LONDON
If you expect printed or punched output from your job, you may need
to include the spooling commands necessary to control the output. In
the above example, the batch machine's punch is spooled to userid
BOSWELL's virtual reader.
Any output printer files produced by your job are spooled by the
batch virtual machine to the printer. These files are spooled under your
userid and with the distribution code associated with your userid,
provided the userid's directory has the accounting option set. You can
change the characteristics of these output files with the CP SPOOL
command:
CP SPOOL E CLASS T
If you want output to appear under a name other than your userid, use
the FOR operand of the SPOOL command:
CP SPOOL E FOR JONSON
)
Output punch files are spooled, by default, to the real system card
punch (under your userid), unless you issue a SPOOL command in the batch
job to control the virtual card punch of the batch virtual machine.
Section 12. Using the eMS Batch Facility
231
RESTRICTIONS ON CP AND CMS COMMANDS IN BATCH JOBS
The batch facility permits the
The following CP commands can
machine:
CHANGEl
CLOSEl
DETACH2
DUMP
DISPLAY
LINK3
use of many CP and most CMS commands.
be used to control the batch virtual
MSG
QUERY
REWIND
SMSG
SPOOLl
STORE
TAG
Notes:
-l-.--These commands may not be used to affect the virtual card reader.
2.
You can not use this command to
system or 1PL disks.
detach any spooling devices or the
3.
The LINK command must be entered on one line in the format:
CP LINK userid vaddr vaddr mode password
None of the LINK command keywords
(AS, PASS, TO) are accepted. If
the disk has no password associated with it, you must enter the
password as ALL.
A maximum of ten links may be in effect at any
one time.
All CP commands
command.
in
a batch
job
must be
prefaced
with the
"CP"
Since the batch virtual machine reads input from its card reader, you
cannot use the following commands or operands that affect the card
reader:
ASSGN SYSxxx READER (CMS/DOS only)
DISK LOAD
FILEDEF READER
READCARD
The RDCARD
machine.
macro cannot be
used by jobs that
run under the
CMS batch
Invalid SET command operands are:
BLIP
EMSG
IMPCP
INPUT
OUTPUT
REDTYPE
RELPAGE
PROTECT
All the other operands of the SET command can be used in a job executing
in the batch virtual machine.
BATCH FACILITY OUTPUT
Any files that you request to have printed during your job's execution
are spooled to the real system printer under your userid, unless you
have spooled it otherwise. Once released for processing, these output
files are under the control of the CP spooling facilities; if you are
logged on, you can control the disposition of these files before they
232
IBM VM/370 CMS User's Guide
(
are printed with the CLOSE, PURGE, ORDER, and CHANGE commands. See the
following section "Purging, Reordering, and Restarting Batch Jobs."
Output files produced by the batch virtual machine are identifiable
by the filename CMSBATCH in the CP spool file name field. The spool file
type field contains the filetype JOB, unless you specified a jobname on
the /JOB card. This applies to both printer and Funch output files.
In addition to your regular printed output, the CMS batch facility
spools a console sheet that contains a record of all the lines read in,
and the responses, error messages, and return codes that resulted from
command or program execution. This file is identified by a spool file
name of BATCH and a spool file type of CONSOLE.
PURGING, REORDERING, AND RESTARTING BATCH JOBS
When required, you can control the execution of batch virtual machine
jobs by purging, reordering, and restarting them; by the same token,
because all the closed printer files are queued for system output under
the submitting userid, you can change, purge, or reorder these files
prior to processing on the system printer.
To purge a
job
procedure below:
executing under
the
batch
monitor,
follow
1.
Signal attention and enter the virtual machine environment.
2.
Enter the HX (halt execution) Immediate command.
3.
Disconnect the virtual machine using the CP DISCONN command.
the
The HX command causes the batch facility to abnormally terminate.
This provides the user with an error message and a CP dump of the batch
facility virtual machine. The batch monitor then loads itself again and
starts the next job (if any).
To purge an individual input spool
issue the CP PURGE command:
file that is not
yet executing,
PURGE READER spoolid
In the format above, spoolid is the spool file number of the job to
be purged from the batch virtual machine's job queue. For example, the
statement:
PURGE READER 123
would purge 123 from the batch virtual machine's job queue.
To reorder individual spool files in
use the CP ORDER ~ommand:
the batch facility's job queue,
ORDER READER spoolid 1 spoolid2 .•••
In this format, spoolid1 and spoolid2 are
identifications of the jobs to be reordered.
You can determine which
command:
)
the
jobs are in the queue by
assigned spool
file
using the CP QUERY
QUERY READER ALL
section 12. Using the CMS Batch Facility
233
This QUERY command lists the filenames and filetypes of all the jobs
in the batch virtual machine's job queue. You can then reorder them,
using the ORDER command.
Using EXEC Files for Input to the Batch Facility
There are a variety of ways that EXEC procedures can help facilitate the
submission of jobs to the CMS batch facility.
You can prepare an EXEC
file that contains all of the CMS commands you want to execute, and then
pass the name of the EXEC to the batch virtual machine. For example,
consider the files COpy JCL and COPYF EXEC:
COpy JCL:
/JOB CARBON 999999
EXEC COPYF
/*
COPYF EXEC: COPYFILE FIRST FILE A SECOND = =
COPYFILE THIRD FILE A FOURTH = =
Then, if you enter the commands:
cp spool punch to cmsbatch
punch copy jcl
(noheader
*
the commands in the EXEC file are executed by the batch virtual machine.
You could also use an EXEC to punch input to the batch virtual
machine. Using the same commands as in the example above, you might
have an EXEC named BATCOPY:
CP SPOOL PUNCH TO BATCH3
&PUNCH /JOB CARBON 999999
&PUNCH COPYFILE FIRST FILE A SECOND = =
&PUNCH COPYFILE THIRD FILE A FOURTH = =
&PUNCH /*
CP CLOSE PUNCH
Then, when you enter the EXEC name:
batcopy
the input lines are punched to the batch virtual machine.
The examples above are very simple; you probably would not go to the
trouble of sending such a
job to the batch virtual machine for
processing. The examples do, however, illustrate the two basic ways
that you can use EXEC procedures with the batch facility:
1.
Invoking an EXEC procedure from a batch virtual machine
2.
Using an EXEC procedure
virtual machine
to create
a job
stream
for the
batch
In either case, the EXECs that you use may be very simple or very
complicated. In the first instance, an EXEC might contain many steps,
with control statements to conditionally control execution, errcr
routines, and so on.
In the second instance, you might have an EXEC that is versatile so
that it can be invoked with different arguments so as to satisfy more
than one situation. For example, if you want to create a simple EXEC to
234
IBM VM/370 CMS User's Guide
(
send jobs to
ccntain:
the
batch
virtual machine
to
te
assembled, it
migbt
CP SPOOL PUNCH TO BATCH3 CONT
&PUNCH /JOB ARIEL 888888
&PUNCH CP LINK ARIEL 191 391 RR LINKPASS
&PUNCH ACCESS 391 B/A
&PUNCH ASSEMBLE &1 (PRINT
&PUNCH CP SPOOL PUNCH TO ARIEL
&PUNCH PUNCH &1 TEXT A (NOHEADER
&PUNCH /*
CP.SPOOL PUNCH NOCONT CLOSE
If this file were named BATCHASM EXEC, then whenever you wanted the C!S
tatch facility to assemble a source file for you, you would enter:
batchasm filename
and the batch virtual machine would assemble the source file, print tbe
listing, and send you a copy of the resulting TEXT file.
SAMPLE SYSTEM PROCEDURES FOR BATCH EXECUTION
)
To extend the abcve examFle a little further, suppose you wanted to
process source files in languages other than the assembler language. Yeu
want, also, fcr any user to be able to use this EXEC. You might have a
separate EXEC file for each language, and an EXEC to control the
submission of the job. This example shows the controlling EXEC file
EATCH and the ASSEMBLE EXEC.
~!~£] ~!~£:
*
**
*
*
THIS EXEC SUBMITS ASSEMBLIES/COMPILATIONS TO CMS EATCH
-
PUNCH BATCH JOB CARD;
CALL APPROPRIATE LANGUAGE EXEC (&3) TO PUNCH
&CONTROL ERROR
&IF &INDEX GT 2 &SKIP 2
&TYPE CORRECT FORM IS: BATCH USERID FNAME
&EXIT 100
&ERROR &GOTO -ERR1
CP SPOOL D CONT TO BATCHCMS
&PUNCH /JOB &1 1111 &2
&PUNCH CP LINK &1 191 291 RR SECRET
&PUNCH ACCESS 291 B/A
EXEC &3 &2 &1
&PUNCH /*
CP SPOOL D IOCONT
CP CLOSE D
CP SPOOL DOFF
&EIIT
-ERR1 &EXIT 100
F~YPE
~XECUTABLE
COMMANDS
(LANGUAGE)
Secticn 12. Using the CMS Batch Facility
235
!~~!;!!1!1!; !;!!;~:
*
CORRECT FORM IS: ASSEMBLE FNAME USERID
**
*
PUNCH COMMANDS TO:
INVOKE CMS ASSEMBLER
- RETURN TEXT DECK TO CALLER
-
*
*
&CONTROL ERROR
&ERROR &GOTO -ERR2
&PUNCH GLOBAL MACLIB UPLIB CMSLIB OS MACRO
&PUNCH CP MSG &2 ASMBLING ' &1 '
&PUNCH ASSEMBLE &1 (PRINT NOTERM)
&PUNCH CP MSG &2 ASSEMBLY DONE
&PUNCH CP SPOOL D TO &2 NOCONT
&PUNCH PUNCH &1 TEXT A1 (NOHEADER)
&BEGPUNCH
CP CLOSE D
CP SPOOL DOFF
RELEASE 291
CP DETACH 291
&END
&EXrT
-ERR2 &EXIT 102
If the above EXEC procedure is invoked with the line:
batch fay payroll assemble
the BATCHCMS virtual machine's card reader should contain the following
statements (in the same general form as a FIFO console stack):
/JOB FAY 1111 PAYROLL
CP LINK FAY 191 291 RR SECRET
ACCESS 291 B/B
GLOBAL MACLIB UPLIB CMSLIB OS MACRO
CP MSG FAY ASMBLING ' PAYROLL '
ASSEMBLE PAYROLL (PRINT NOTERM)
CP MSG FAY ASSEMBLY DONE
CP SPOOL D TO FAY NOCONT
PUNCH PAYROLL TEXT A1 (NOHEADER)
CP CLOSE D
CP SPOOL DOFF
RELEASE 291
CP DETACH 291
/*
When the batch facility executes this job, the commands are executed as
you see them: if you are logged on, you receive, in addition to the
normal messages that the batch facility issues, those messages that are
included in the EXEC.
A BATCH EXEC FOR A NON-CMS USER
Many installations run the CMS batch facility for non-CMS users to
submit particular types of jobs. Usually, a series of EXEC files are
stored on the system disk so that each user only needs include a card to
236
IBM VM/370 CMS User's Guide
(
invoke the EXEC, which executes the correct CMS commands to process data
included with the job stream.
For example, if a non-CMS user wanted to compile FORTRAN source
files, the following BATFORT EXEC file could be stored on the system
disk:
&CONTROL OFF
FILEDEF INMOVE TERM (RECFM F BLOCK 80 LRECL 80
FILEDEF OUTMOVE DISK &1 FORTRAN A1 (RECFM F LRECL 80 BLOCK 80
MOVEFILE IN OUT
GLOBAL TXTLIB FORTRAN
FORTGI &1 (PRINT)
&FORTRET = &RETCODE
&IF &RETCODE NE 0 &GOTO -EXIT
PUNCH &1 TEXT A1 (NOHEADER)
-EXIT &EXIT &FORTRET
To use this EXEC, a non-CMS user
deck in the system card reader:
might place the following real card
ID CMSBATCH
JOEUSER 1234 JOB10
BATFORT JOEFORT
IJOB
source file
1* (end-of-file indicator)
1* (end-of-job indicator)
When the batch virtual machine executes this job, it begins reading
the EXEC procedure from disk, and executes one line at a time. When it
encounters the MOVEFILE command, it begins reading the source file from
its card reader (the batch facility interprets a terminal read as a
request to read from the card reader). It continues reading until it
reaches the end-of-file indicator (the 1* card), and then resumes
processing the EXEC on the next line following the MOVE FILE command
line.
Additional functions may be added to this EXEC procedure, or others
may be written and stored on the system disk to provide, for example, a
compile, load, and execute facility.
These EXEC procedures would allcw
an installation to accommodate the non-CMS users and maintain common
user procedures.
)
Section 12. Using the CMS Batch Facility
237
c
238
IBM VM/370 eMS User's Guide
Section 13. Programming for the eMS
Environment
This section contains information for assembler language programmers who
may occasionally need to write programs to be used in the CMS
environment. The conventions described here apply only to CMS virtual
machines; you can not execute these programs under any other operating
systems.
Program Linkage
Program linkages, in CMS, are generally made by means of a supervisor
call instruction, SVC 202. The SVC handling routine takes care of
program linkage for you. The registers used and their contents are
discussed in the following paragraphs.
1: Points to a parameter list of successive doublewords. The
first entry in the list is the name of the called routine or program,
and any successive doublewords may contain arguments passed to the
program. Parameter lists are discussed under "Parameter Lists."
~~g!§!~£
lJ: Contains the address of a 24-fullword save area, which you
can use to save your caller's registers. This save area is provided to
satisfy standard OS and DOS linkage conventions; you do not need to use
it in CMS, since the SVC routines save the registers.
~~g!§!~£
~~g!§!~£ 1~:
Contains the return address of the SVC handling routines.
You must return control to this address when you exit from your program.
)
The CMS routines that get control by way of register 14 close files,
update your disk file directory, and calculate and type the time used in
program execution. These values appear in the CMS ready message, which
is displayed at your terminal when your program finishes execution:
R;T=n.nn/x.xx hh:mm:ss
where n.nn is the CMS CPU time (in seconds) and x.xx is the combined CP
and CMS CPU time. hh:mm:ss is the time of day in hours, minutes, and
seconds.
~~g!§!~£ 1~:
Contains your program's entry point address. You can use
this address to establish immediate addressability in your program. You
should not use it as a base address, however, since all CMS SVCs use it
for communication with your programs.
Figure 20 shows a sample CMS assembler language program entry and exit.
)
Section 13. programming for the CMS Environment
239
PROGRAM
CSECT
USING PROGRAM,12
LR
12,15
ST
14,SAVRET
14,SAVRET
15,0
14
L
SAVRET
LA
BR
DS
F
ESTABLISH ADDRESSABILITY
SAVE RETURN AnrRESS IN R14
LOAD RETURN ADDRESS
SET RETURN CODE IN R15
GO
SAVE AREA
Figure 20. Sample eMS Assembler program Entry and Exit Linkage
RETURN CODE HANDLING
Register 15, in addition to its role in entry linkage, is also used in
CMS as a r~turn code register. All of the CMS internal routines pass a
completion code by way of register 15, and the SVC routines that receive
control when any program completes execution examine register 15.
If register 15 contains a nonzero value,
CMS readj message, following the "R":
this value is placed in the
a(nnnnn);T=n.nn/x.xx hh:mm:ss
When you are executing programs in CMS, it is good practice, if your
programs do not use register 15 as a return code register, to place a
zero in it before transferring control back to CMS. Otherwise, the ready
message may display meaningless data.
PARAMETER LISTS
When you execute a program from your terminal, a CMS scan routine sets
up a parameter list based on your command input line. The parameter list
is dophleword-aligned, with parameters occupying successive doublewords.
The scan routine
recognizes blanks and parentheses
as argument
delimiters; parentheses are placed, in the parameter list, in separate
doublewords.
For ~xample, if you have a CMS
call it with the command line:
MODULE file named TESTPROG,
and you
testprog(file2)
The scan routine sets up the parameter list:
CMNDLIST DS
DC
DC
DC
DC
pC
OD
CL8'TESTPROG'
CL8' ('
CL8'FILE2'
CL8 .) ,
8X'FF'
The last doubleword is made up of all 1s, to act as a delimiter.
If you enter any argument longer than .eight characters, it is
truncated and only the first eight characters appear in the list.
However, no error condition results.
240
laM VM/370 CMS User's Guide
(
The scan routine that sets up this parameter list places the address of
the list in register 1 and then calls the SVc handling routine. The SVC
routine gives control to the program named in the first doubleword of
the parameter 1ist.
When your program receives control, it can examine the parameter list
passed to it by way of register 1.
You can
programs.
use this
technique, also,
to call
CMS commands
When you use the LOAD and RUN commands to execute
you can pass an argument list to the p~ogralB on the
example, if you enter:
from your
a program in CMS,
command line~ Por
load myprog
start * runl proga
the arguments
*, RUN1, and PROGA are placed in a parameter list of
doublewords and register 1 contains the address of this list when your
program receives control. If you want to use the RUN command to perform
the load and start functions, you could enter:
run myprog (run1 proga
The parenthesis indicates the beginning of the argument list.
To detect the absence of a parameter list that occurs when the LOAD
command START option is used, your program may test the doubleword
pointed to by register 1 for a delimiter made up of l's in all of the
bit positions.
Calling a CMS Command from a Program
You can call a CMS command from a program by setting up a parameter
list, like that shown above, and then issuing an SVC 202. The parameter
list you set up must have doublewords that contain the parameters or
arguments you would enter if you were entering the command from the
terminal. Por example:
PUNCHER
DS
DC
DC
DC
DC
DC
DC
DC
OD
CLS'PUNCH'
CLS'NAME'
CLS'TYPE'
CLS'*'
CLS' (.
CLS'NOH'
SX'FP'
In your program, when you want to execute this command, you should load
the address of the list into register 1, and issue the supervisor call
instruction (SVC) as follows:
LA
1,PUNCHER
SVC 202
DC
AL4 (ERROR)
)
Section 13. Programming for the CMS Environment
241
When you issue an SVC 202, you must supply an error return address in
the four bytes immediately after the SVC instruction. If the return code
(register 15)
contains a nonzero value after returning from the SVC
call, control passes to the address specified. In the above example,
control would go to the instruction at the label ERROR.
If you want to ignore errors, you can use the sequence:
LA
1,PUNCHER
SVC 202
DC
AL4 (*+4)
If you do not specify an error address, control is returned to the next
instruction after a normal return, but if there was an error executing
the CMS command, your program terminates execution.
If you want to execute a CP command or an EXEC procedure
program, you must use the CP and EXEC commands; for example:
SPOOL
DS
DC
DC
DC
DC
DC
DC
DC
DC
DC
EXEC
from a
OD
CL8'CP'
CL8'SPOOL'
CL8'PRINTER'
CL8'CLASS'
CL8'S'
8X'FF'
CL8'EXEC'
CL8'PFSET'
8X'FF'
It is not possible to
characters this way.
enter a parameter
that is longer
than eight
As an alternative, you can use the CMS LINEDIT macro to call a CP
command from a program. Specify DISP=CPCOMM on the macro instruction;
for example:
,
/
LINEDIT TEXT='SPOOL E CLASS S',DISP=CPCOMM,DOT=HO
On return from the execution of the LIHEDIT macro instruction, register
15 contains the return code from the CP command.
The
LINEDIT macro
is
described in
!~Ll1Q
~~~
£Q~~s~Q s~~
~~£!~
~~fe!~~£~.
Another way
DIAGNOSE x'08'
to execute a CP command from a program is to use the
instruction. For additional information on this, see
!~Ll1Q ~I§!~~ E!Qgf~!!~!~§ §y!g~.
Executing Program Modules
MODULE files,
in CMS, are nonrelocatable programs. Using the GEHMOD
command, you can create a module from any program that uses OS or CMS
macros.
When you create a module, it is generated at the virtual
storage address at which it is loaded, for example:
load myprog
genmod testit
The CMS disk file, TESTIT MODULE A, that is created as a result of this
GEHMOD command, always begins execution at location X'20000', the
beginning of the user program area.
242
IBM VM/370 CMS User's Guide
(
March 30, 1979
If you want to call your own program modu~es using SVC 202
instructions, you must be careful not to execute a module that uses the
saae area of storage that your program occupies. If you want to call a
module that executes at location X'20000'. you can load the calling
program at a higher location; for example:
load myprog (origin 30000
As long as the MODULE file called by MYPROG is
bytes, it will not overlay your program.
no longer than X'10000'
Many CMS disk-resident command modules also execute in the user
program area; if you call these commands from a program, you should load
your program at a higher location.
THE TRANSIENT PROGRAM AREA
To avoid overlaying programs executing in the user program area, you can
generate program modules to run in the CftS transient area, which is a
two-page area of storage that is reserved for the execution of prograas
that are called for execution frequently. ftany CMS co •• ands run in this
area, which is located at X'EOOO'. programs that execute in this area
run disabled.
To generate a module to run in the transient area; use the ORIGIN
TRANS option when you load the TEXT file into storage, then issue the
GENMOD command:
load myprog (origin trans
genmod setup (str
!Qte: If a program running in the user area calls a transient routine in
which a module was generated using the GENMOD command with the STR
option, the user area storage pointers will be reset. This reset
condition could cause errors upon return to the original program (for
example, when OS GETMAIN/FREEMAIN macros are issued in the user
program).
The two restrictions
transient area are:
placed
on command
modules
executing in
the
1.
They may have a maximum size of 8192 bytes. since that is the size
of the transient area. This size includes any free storage acquired
by GETMAIN macros.
2.
They ~ust be serially reusable. When a program is called by an SVC
202, if it has already been loaded into the transient area. it is
not reloaded.
The CMS 'commands that execute in the transient area are: ACCESS,
ASSGB, COMPARE, DISK, DLBL, FILEDEF, GENDIRT. GLOBAL, LISTFILE. MODMAP.
OPTioN, PRINT, PUNCH, QUERY, READCARD, RELEASE, RENAME, SET, SVCTRACE.
SYNONYM, TAPE, and TYPE.
eMS Macro Instructions
There are a number of assembler language macros distributed with the CMS
system that you can use when you are writing programs to execute in the
CMS environment. They are in the macro library CMSLIB MACLIB, which is
Section 13. Programming for the CMS En.ironment
243
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp.
SD23~9024-1
for 5748-118
normally located on the system disk.
To allow for proper macro
expansion in a system supporting VM/370 Basic System Extensions (program
NO. 5748-118), DMSB20 MACLIB must be used in addition to CMSLIB MACtIE.
There are macros to manipulate CMS disk files,
to handle terminal
communications, to manipulate unit record and tape input/output, and to
trap interruptions. These macros are discussed in general terms here;
for complete format descriptions, see !~L170 ~~~ ~Qmm~~g ~n~ ~~£!Q
!l~fe!~1!£~.
MACROS FOR DISK FILE MANIPULATION
Disk files are described in CMS by means of a file system control block
(FSCB). The CMS macro instructions that manipulate disk files use FSCBs
to identify and describe the files. When you want to manipulate aCeS
file,
you can refer to the file either by its file identifier,
specifying 'filename filetype filemode' in quotation marks, or you can
refer to the FSCB for the file,
specifying FSCB=fscb,.where fscb is the
label on an FSCB macro.
To establish an FSCB for a file,
you can use
instruction specifying a file identifier; for example:
INFILE
FSCB
the
FSCB
macro
'INPUT TEST All
You can also provide, on the FSCB macro instruction, descriptive
information to be used by the input and output macros. If you do not
code an FSCB macro instruction for a file,
an FSCB is created inline
(following the macro instruction) when you code an FSREAD, FSWRITE, or
FSOPEN macro instruction.
The format of an
each of the fields.
1912~1
FSCBCOMM
FSCBFN
FSCBFT
FSCBFM
FSCBITNO
FSCBBUFF
FSCBSIZE
FSCBFV
FSCBFLG
FSCBNOIT
FSCBNORD
FSCBAITN
FSCBANIT
FSCBWPTR
FSCBRPTR
DC
DC
DC
DC
DC
DC
DC
DC
EQU
DC
DC
DC
DC
DC
DC
FSCB is listed below, followed by
CL8'
CL8'
CL8'
CL2'
,
,
,
,
H'O'
A'O'
P'O'
CL2'P'
PSCBFV+l
H'l'
AL4 (0)
AL4 (0)
AL4 (1)
AL4 (0)
AL4 (0)
a description of
Q~§£!:!.E!!Q1!
File system cqmmand
Filename
Filetype
Filemode
Relative record number (RECNO)
Address of buffer (BUFPER)
Number of bytes to read or write (BSIZE)
Record format - F or V (RECFM)
Flag byte
Number of records to read or write (NOREe)
Number of bytes actually read
Extended FSCB relative record .. number
Extended FSCB relative number of records
Extended FSCB relative write pointer
Extended FSCB re1ative read pointer
The fields FSCBAITN, FSCBANIT, FSCBWPTR, and FSCERPTR are only generated
in the FSCB when the extended format FSCB is requested (FORM=E is coded
on the FSCB macro instruction). In this case, the fields .FSCBITNO and
FSCBNOIT are reserved fields.
Extended format FSCB~ must be used to
manipulate files larger than· 65, 533 items.
The labels shown above are not generated by the FSCB macro; to reference
fields within the FSCB by thes~ labels, you must use the FSCBD macro
instruction to generate a DSECT.
244
IBM VM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
X~~~~Q!~:
When the FSCBFN, FSCBFT, and FSCBFM fields are filled in, yeu
can fill in the FSCBCOMM field with the name of a CMS command and use
the FSCB as a parameter list for an SVC 202 instruction.
(You must
place a delimiter to mark the end of the command line.)
X~~~l!,
l~£~l!, FS~~I~:
The filename, filetype and filemode fields
identify the CMS file to be read or written. You can code the fileid cn
a macro line in the format 'filename filetype filemode' or you can use
register notation. If you use register notation, the register that you
specify must point to an 18-byte field in the format:
FILEID
DC
DC
DC
CLS'filename'
CLS'filetype'
CL2'fm'
Section 13. Programming for the CMS Environment
244.1
March 30, 1979
2qq.2
lBft Yft/370 CftS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1919 by Supp. SD23-9024-1 for 5148-118
The fileid must be specified either in the FSCE for a file or on the
lSREAD, lSWRITE, PSOPEN, or PSERASE macro instruction you use that
references the file.
PSCBITNO: For anPSCB without the POBM=E option, the record or ite.
Dimber-Indicates the relative record number of the next record to be
read or written; it can be changed with the RECNO option. The default
value for this field is O. When you are reading files, a 0 indicates
that records are to be read sequentially, beginning with the first
record in the file~
When you are writing files,
a 0 indicates that
records are to be written sequentially, beginning at the first record
following the end of the file, if the file already ex~sts, or with
record 1, if it is a new file.
lor an lSCB generated with the
contains the record or item number.
PORM=E option, the PSCBAITN field
The PSCBITNO field is reserved.
Whenever you read discontiguous files in CMS (that is, files with
missing records), the input buffer will be filled with the appropriate
number of bytes.
Be aware that the flag byte in the PSCB may not
reflect whether the input buffer contains generated data items fro~
RDBUl.
lSCBBUlP: The buffer address, specified in the fUFlER option, indicates
the-Yabel of the buffer from which the record is to be written or into
which the record is to be read. You should always supply a buffer large
enough to accommodate the longest record you expect to read or write.
This field must be specified, either in the lSCB, or on the PSREAD or
lSWRITE macro instruction.
lSCBSlZE: This field indicates the number of bytes that are read or
wrItteii-with each read or write operation. The default value is o. If
the buffer that you use represents the full length of the records you
are going to be reading or writing, you can use the BSIZE option to set
this field equal
to your buffer length; when
you are writing
variable-length records, use the BSlZE operand to indicate the length of
each record you write. This field must be specified.
FSCBFV: This two-character field indicates
the-iIle. The default value is F (fixed).
the record format
(RECFM) of
1:.§CB1:1Q: The flag byte is X'20' indicating an extended FSCB generated
when the FORM=E option is coded on the FSCB macro instruction.
1:~~~!Q1I:
For an FSCB without the FORM=E option, this field contains the
number of whole records that are to be read or written in each read or
write operation. You can use the NOREC option with the BSIZE option to
block and deblock records. The default value is 1.
For an PSCB generated with the PORM=E option, the FSCBANIT field
contains the number of whole records to be read or written.
The
FSCBNOlT field is reserved.
1:~~~!Q!Q:
Following a read operation, this field contains the number of
bytes that were
actually read, so that if you
are reading a
variable-length file,
you can determine the size of the last record
read. The FSREAD macro instruction places the information from this
field into register O.
FSCBAlTN: The alternate record or item number indicates the relative
record-iiumber of the next record to be read or written in an extended
lSCB format. See "the description of the FSCBITNO field for the usage of
this field.
Section 13. Programming for the CMS Environment
245
Pg. of GC20-1819-2 Rev'March 30, 1919 by Supp. SD23-9024-,1 for 5148-118
F,SCBANIT: This field contains the alternate number of whole records in
ineitended FSCB forllat. See the description of the FSCBNOIT~ field for
the usage of this field.
F.5CBWPTR: The FSPOINT macro instruction uses this field to conta"in the
alternate write pointer for an extended FSCB during a POINT operation.
FSCBRPT:R: The FSPOIIT macro instruction uses this field to contain the
alternate read pointer for anextended"FSCBd'uringa POINT operation.
!!§ing
!.h~ I~~~
The following example shOWS how you lIight code an FSCB macro instruction
to define various file and buffer charaQteristics, and then use the sa.e
FSCB to refer to different files:
FSREAD 'INPUT FILE A1',FSCB=COMMON,FOR!~E
FSWRITE 'OUTPUT FILE A1',~SCB=CO!MON,FOBM=E
COMMON
SHARE
FSCB
DS
BUFFER=SHARE,RECFM=V,BSIZE=200,FOR!=E
CL200
In the above example, the fi1eid specifications on the FSREID and
FSWRITE macro instructions modify the FSCB at the label COMMON each tiae
a r~ad or write operation is performed. You can also modify an FSCB
directly by referring to fields by a displacement off the beginning of
the FSCB; for example:
MVC
FSCB+S,=CLS'NEWNAME'
moves the nalle NEWNAME into the filename
FSCBFN.
field of the FSCB at the label
As an alternative, you can use the FSCBD 'macro instruction to
generate a DSECT and refer to the labels in the DSECT to modify the
FSCB1 for example:
LA
R5,INFSCB
USING FSCBD,R5
MVC
INFSCB
NEWNAME
FSCBFN,NEWNAME
FSCB 'INPUT TEST
DC
CLS'OUTPUT'
FSCBD
Al'~FOR!=E
In the above example, the MVC instruction places the filename OUTPUT
into the FSCBFN (filename) field of the FSCB.The next time this FSC! is
referenced~ the file OUTPUT TEST is the file that is manipulated.
CMSdisk files are sequential files; when you use CMS macros to read and
write these files, yoti can access them sequentially with the FSREID and
FSWRITE macros. However, you may also refer to records in a CMS file by
their relative record numbers, so you can, in effect, access records
using a direct access method.
246
IBM VM/310'CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-X18
If you know which record you want to read or write, you can specify
the RECNO option on the FSCB macro instruction, or on the FSOPEB,
FSREAD, or FSWRITE macro instructions. When you use the RECNO option on
the FSCB macro instruction, you must specify it as a self-defining term;
for the FSOPEN, FSREAD, or FSWRITE macro instructions, you may specify
either a self-defining term, as:
WRITE
FSWRITE FSCB=WFSCB,RECNO=10,FORM=E
or using register notation, as follows:
WRITE
FSWRITE FSCB=WFSCB,RECNO=(5) ,FORM=!
where register 5 contains the record number of the record to be read.
When you want to access files sequentially, the FSCBITNO field of the
FSCB must be 0 for an FSCB without the FORK=E option; for an extended
FSCB, the FSCBAITN field must be O. This is the default value. When you
are reading files with the FSREAD macro instruction, reading begins with
record number 1. When you are writing records to an eXisting file with
the FSWRITE macro, writing begins following the last record in the file.
To begin reading or writing files sequentially beginning at a
specific record number, you must specify the RECNO option twice: once to
specify the relative record number at which you want to begin reading,
and a second time to specify RECNO=O so that reading or writing will
continue sequentially beginning after the record just read or written.
Section 13. programming for the CMS Environment
246.1
March 30, 1919
246.2
IBM 'M/310 eMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5148-118
You can specify the RECNO option on the PSREAD or PSWRITE .acro
instruction, or you may change the FSCBITNO or PSCBAITN field in the
FSCB for the file, as necessary for the FSCB for ••
For example, to read the first record and then the
file, you could code the following:
READ1
READ50
RFSCB
WFSCB
COMMON
50th record of a
FSREAD FSCB=RFSCB,FORM=E
FSWRITE PSCB=WPSCB,FORM=E
LA
5,RFSCB
USING FSCBD,5
MYC
FSCBAITN,=F'50'
FSREAD FSCB=RFSCB,FORM=E
FSWRITE FSCB=WFSCB,FORM=E
FSCB 'IHPUT FILE A1',BUFFER=COMKOH,BSIZE=120,FORft=E
FSCB 'OUTPUT FILE A1',BUFFER=COftMOR,BSIZE=120,FORK=E
DS
CL120
FSCBD
In this example, the statements at the label READ1 write record 1 fro.
the file INPUT FILE A1 to the file OUTPUT FIL! A1. Then, using the
DSECT generated by the FSCBD macro, the FSCEAlTH field is changed
because an extended FSCB is being used and record 50 is read fro. the
input file and written into the output file.
jl!~l!~
!!~ !BI!I!2 !!!!!~~E-~1!2!B !l~Q~~:
When you read or write
variable-length records, you must specify RECF!=Y either in the PSCB for
the file or on the FSWRITE or FSREAD macro instruction. The read/write
buffer should be large enough to acco •• odate the largest record you are
going to read or write.
To write variable-length records, use the BSIZE= option on the
FSWRITE macro instruction to indicate the record length for each record
you write. When you read variable-length records, register 0 contains,
on return fro. PSREAD, the length of the record read.
The following example
variable-length file:
READ
shows
how
you
could
read
and
write
a
FSREAD 'DATA CHECK A1',BUFPER=SHAR!,BSlZE=130,ERBOB=OUT,
FORM=E
FSWRITE 'COpy DATA A1',BUFFER=SHAR!,BSIZE=(O),POB!=E
B
READ
You can specify the ERROR= operand with the FSBEAD or FSWBlTE .acro
instruction, so that an error handling routine receives control in case
of an error. In CMS, when an end of file occurs during a read request,
it is treated as an error condition.
The return code is always 12. If
you specify an error handling routine on the FSREAD mac~o instruction,
then the first thing this routine can do is check for a 12 in register
15.
Your error handling routine may also check for other types of errors.
See the .acro description in YMLJ1~ ~A~ £2!!~B~ ~n~ !~~£2 !ef~~B~~ for
details on the possible errors and the associated return codes.
Section 13. progra •• ing for the CBS Environ.ent
241
Pg. of GC20-1819-2 Rev March 30, 1919 by Supp. sn23-9024-1 for 5748-118
Usually, CMS opens a file whenever
an FSHEAD or FSWRITE macro
instruction is issued for the file. When control returns to CMS from a
calling program, all open files are closed by CMS, so you do not have to
close files at the end of a program.
For a minidisk in 1K-, 2K-, or 4K-byte block format, a file may be
open for concurrent read and write operations, and an FSCLOSE need not
te issued when switching from reading to w~iting, or vice versa. For
example:
READ
LA
3,2
FSREAD FSCB=UPDATE,RECNO=(3},ERROH=READERR,FOHM=E
FSWRITE FSCB=UPDATE,RECNO=(3},ERROR=WRITERR,FORM=E
LA
3, 1 (3)
BREAD
UPDATE
FSCB
'UPDATE FILE A1',BUFFER=BUF1,BSIZE=80,FORM=E
However, if you want to read and write records from the same file on
an 800-byte block format minidisk, you must issue an FSCLOSE macro
instruction to close the file whenever you switch from reading to
writing. For example:
READ
LA
3,2
FSREAD FSCB=UPDATE,RECNO=(3},ERROR=READERR
FSCLOSE FSCB=UPDATE
FSWRITE FSCB=UPDATE,RECNO=(3),ERROB=WRITERR
FSCLOSE FSCB=UPDATE
LA
3,1 (3)
B
READ
UPDATE
FSCB
'UPDATE FILE A1',BUFFER=BUF1,BSIZE=80
To execute a loop to read, update, and rewrite records, you must read
a record, close the file,
write a record, close the file, and so on.
Since closing a file repositions the read pointer to the beginning of
the file and the write pointer at the end of the file, you must specify
the relative record number (RECNO) for each read and write operation. In
the above example, register 3 is used to contain the relative record
number.
It is initialized to begin reading with the second record in
the file and is increased by one following each write operation.
When you use an EIEC to execute a program to read or write a file,
the file is not closed by CMS until the EXEC completes execution.
Therefore, if you read or wiite the same file more than once during the
EXEC procedure, you must use an FSCLOSE macro instruction to close the
file after using it in each program, or use the FSOPENmacro instruction
to open it before each use. Otherwise, the read or write pointer is
positioned as it was when the previous program completed execution.
248
IBMVM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-X18
~!]AI!!~ !~! X!1~~:
When you want to begin writing a new file using C!S
data management macros, there are two ways to ensure that the file you
want to create does not already exist. One way is to issue the FSST1TE
macro instruction to verify the existence of the file.
A second way to ensure that a file does not already exist is to issue
an FSERASE macro instruction to erase the file. If the file does not
exist, register 15 returns with a code of 28. If the file does exist, it
is erased.
Figure
macros.
21 illustrates
a samIle
program using
CMS data
management
Section 13. Programming for the CMS Environment
248.1
ftarch 30, 1979
248.2
lBft 'ft/370 efts User's Guide
Pg. of GC20-1819-2 Rev March 30, 1919 by Supp. SD23-9024-1 for 5148-XX8
LINE
SOURCE STATE!ENT
BEGII
*
**
RD
CSECT
1
PRIIT 10GEI
USIIG *,12
ESTABLISH ADDRESSABILITY
LR
12,15
ST
14,SAYE
LA
2,8(,1) R2=ADDR OF INPUT FILEID II PLIST
LA
3,32(,1) R3=ADDR OF OUTPUT FILElt II PLIST
DETER!INE IF INPUT F~LE EXISTS
FSST1TE (2),EBBOR=ERR1,FOR!=E
2
READ A RECORD FRO! INPUT FILE AND WRITE ON OUTPUT FILE
FSREAD (2),EBBOR=EOF,BUFFER=BUFF1,BSIZE=80,FOR!=E
FSWRITE (3),ERROR=EBR2,BUFFER=BUFF1,BSIZE=80,FOB!=E
B
RD
LOOP BACK FOR NEXT RECOBD
3
*•
COME HERE IF ERROR BEADING INPUT FILE
EOF
C
15,=F'12'
EID OF FILE ?
4
BNE
ERR3
ERBOR IF NOT
15,0
ALL O.K. - ZERO OUT R15
LA
EXIT
GO EXIT
B
FILE DOES lOT EXIST
•EBR1
IF INPUTWRTER!
'FILE NOT FOUID',EDIT=YES
EXIT
B
••
IF ERROR WRITIIG FILE
ERR2
LB
10,15
SAVE BET CODE II REG 10
5
LINEDIT TEXT='EBROR CODE •••• IN WBITING FILE',SUB=(DEC, (10))
B
EXIT
• IF READING ERROR WAS NOT NOR!AL END OF FILE
ERB3
LR
10,15
SAVE RET CODE IN REG 10
5
LINEDIT TEXT='ERBOR CODE •••• IN BEADING FILE',SUB=(DEC, (10)l
•EXIT
14,SAVE
14
L
BR
*BUFF1
SlYE
DS
DS
END
LOAD RETURN ADDRESS
RETURN TO CALLER
CL80
F
Notes:
-'1'-The prograll might be invoked with a parameter list in the format
prognaae INPUT FILE A1 OUTPUT FILE A1. This line is placed in a
parameter list by C!S routines and addressed by register 1
(see ~ote 2).
2 The parameter list is a series of doublewords, each containing
one of the words entered on the command line. Thus, 8 bytes
past register 1 is the beginning of the input fileid; 24 bytes
beyond that is the beginning of the secondfileid.
3 The FSBEAD and FSWRITE macros cause the files to be opened; no
open macro is necessary. C!S routines close all open files when
a program completes execution.
4 The return code in register 15 is tested for the value 12.
which indicates an end-of-file condition. If it is the end of
the file, the prograll exits; otherwise, it writes an error
message.
5 The dots in the LINEDIT lIacro are substituted, during execution,
with the decillal value in register 10.
figure 21.
A Sa.pIe Listing of a Program that Uses CMS
~acros
Section 13. Programming for the C!S Environment
249
March 30, 1979
CMS MACROS FOR TERMINAL COMMUNICATIONS
Tbere are
four CMS macros you
can use to
write 'interactive,
terminal-oriented programs. They are RDTERM, WRT!RM~: LINEDIT, and WAITT.
RDTERM and WRTERM only require' a read/write buffer for sending and
rece1v1ng lines from
the terminal.
The third,
LINEDIT, has a
substitution and translation c a p a b i l i t y . '
.
When you use the WRTERM macio ~b write'~line to your terminal yeu
can specify the actual text line in the macro in'structicn, for· example :
DISPLAY
WRTERM 'GOOD MORNING'
You can also specify
contains the message.
the meSsage text by referrin~ to
a bhffer that
The RDTERM macro accepts a line from the terminal and reads it into a
buffer you specify. You could use the RDTERM andWRTERM macros together,
as follows:
WRITE
READ
REWRITE
WRTERM 'ENTER LINE'
RDTERM BUFFER
LR
3,0
WRTERM BUFFER, (3)
BUFFER
DS
CL130
In this example, the WRTERM macro results in a prompting message. Then
the RDTERM macro accepts a line from the terminal and places it in the
buffer BUFFER. The length of the line read, co~tained in register 0 cn
return from the RDTERM macro, is saved in register 3. When you specify
a buffer address on the WRTERM macro instruction, you must specify the
length of the line to be written.
Here, register notation is used to
indicate that the length is contained in register 3.
The LINEDIT macro converts decimal and hexadecimal data into EBCDIC,
and places the converted value into a specified field in an output line.
There are list and execute forms of the macro instruction, which you can
use in writing reentrant code. Another option allows you tb write-lines
to the offline printer. The LINEDIT macro is described, withexa~ples,
in !~L1IQ £~.§ £.Q!.!~1!g ~1!g ~~£!:.Q !!~t~!:~1!£~. Figure 21 shows how you
might use the LINEDIT macro to conVert and display CffS return codes~
The WAITT
(wait terminal)
macro
instruction can hel'p you to
synchronize input and output to the terminal. If~ you are executing a
program that reads and writes to the terminal frequerrtly,' you may want
to issue a WAITTmacrb instruction to halt e~ecution of the program
until all terminal I/O has completed.
CMS MACROS FOR UNIT RECORD
AN~
TAPE I/b
CMS provides macros to simplify reading and punching cards (RDCARD and
PUNCHC), ana creating printer files (PRrNTL). ~hen you use either the
PUNCHC or PRINTL macros to write or punch output'files while a program
is e%ecuting, you should remember to issue a CLOSE command for y"our
virtual prin~ter or punch when' you are finished. You Can do this either
after your program returns control to CMS, by entering:
250
IBM VM/370 CMS Userts Guide
cp close e
-- or -cp close d
or, you can set up a parameter list
CP CLOSE D and issue an SVC 202.
with the command line CP CLOSE E or
The tape control macros, RDTAPE, WRTAPE and TAPECTL, can read and
write CMS files from tape, or control the positioning of a tape.
INTERRUPTION HANDLING MACROS
You can set up routines in your programs to handle interruptions caused
by I/O devices, by SVCs, or by external interruptions using the BNDINT,
BNDSVC, or HNDEXT macro instructions.
with the HNDINT macro instruction, you can specify addresses that are
to receive control when an interruption occurs for a specified device.
If the WAIT option is used for a device specified in the BNDINT macro
instruction, then the interruption handling routine specified for the
device does not receive control until after the WAITD macro instruction
is issued for the device.
You can use the BNDSVC macro instruction to trap supervisor call
instructions of particular numbers, if, for example, you want to perform
some additional function before passing c~ntrol or you do not want any
SVCs of the specified number to be executed.
)
The CP EXTERNAL command simulates external interruptions in your
virtual machine; if you want to be able to pass control to a particular
internal routine in the event of an external interruption, you can use
the BNDEXT macro instruction.
Updating Source Programs Using eMS
As you test and modify programs, you may want to keep backup copies of
the source programs. Then you can always return to a certain level of a
program in case you have an error. CMS provides several approaches to
the problem of program backup: the method you choose depends on the
complexity of your project, the changes you want to make, and the size
of your programs.
The simplest method is to .ake a copy of the current source file
under a new name. You can do this using either the COPYFILE command or
the CMS editor. If you use the COPYFILE command, your command line
might be:
copy file account assemble a oldacct assemble a
Then, you can use the editor to modify ACCOUNT ASSEMBLE; the
OLDACCT ASSEMBLE contains your original source file.
You can make a copy of your source
directly. For example, if you issue:
)
file
using the
CMS
file
editor
edit account assemble
EDIT:
fname newacct
Section 13. Programming for the CMS Environment
251
then any subsequent changes you make to the file ACCOUNT
written into the file NEWACCT ASSEMBLE. When you issue a
subcommand, your source file remains intact.
After your changes to the source program
replace the source file with your new copy.
ASSEMBLE are
FILE or SAVE
have been tested
you can
THE UPDATE PHILOSOPHY
While the procedures outlined above for modifying programs are suitable
for many applications, they may not be adequate in a situation where
several programmers are applying changes to the same source code. These
procedures also have the draWback of not providing you with a record of
what has been changed. After using the editor, you do not have a record
of the lines that have been deleted, added, replaced, and so on, unless
you manually add comments to the code, insert special characters in the
serialization column, or use some technique that records program
activity.
The UPDATE command provides a way for you to modify a source program
without affecting the original, and
it produces an update log,
indicating the changes that have been made. Moreover, it also has the
capability of combining multiple updates at one time, so that changes
made by different programmers or changes made at different times can be
combined into a single output file.
The UPDATE command is a basic element of the entire V8/370 updating
scheme and is used by system programmers who maintain VM/370 at your
installation. Although the input filetypes used by the UPDATE command
default to ASSEMBLE file characteristics, the UPDATE command is not
limited to assembler language programs, nor is it limited to system
programming applications. You can use it to modify and update any
fixed-length, SO-character file that does not have data in columns 72
through 80.
UPDATE FILES
A simple update involves two input files:
•
The source file, which is the program you want to update
•
An update file, containing
changes you want to make
control
statements that
describe
the
The control statement file usually has a filetype of UPDATE. For
convenience, you can give it the same filename as your source file. For
example, if you want to update the file SAMPLE ASSEMBLE, you would
create a file named SAMPLE UPDATE.
To apply the changes in the update file, you issue the command:
update sample
The default values used by the UPDATE command are filetypes of ASSEMBLE
and UPDATE for the source and update files, respectively. If you are
updating a COBOL source program named READY COEOL with an update file
named UPDATE READY, you would issue the command:
update ready cobol a update ready a
252
IBM VM/370 CMS User's Guide
(
After an UPDATE command completes processing, the input files are not
changed; two new files are created.
One of them contains the updated
source file, with a filename that is the same as the original source
file but preceded by a dollar sign ($).
Another file, containing a
record of updates is also created; it has a filename that is the same as
the source file and a filetype of UPDLOG. For example:
~2Y~£~ !!!~§
SAMPLE ASSEMBLE
SAMPLE UPDATE
QytEY! !!!~§
$SAMPLE ASSEMBLE
SAMPLE UPDLOG
READY COBOL
UPDATE READY
$READY COBOL
READY UPDLOG
NoW, you can assemble
UPDATE command.
or compile the
new source
file created
by the
The control statements used by the UPDATE command are similar to those
used by the OS IEBUPDTE utility program or the DOS MAINT program UPDATE
function.
Each UPDATE statement must have the characters./ in columns one and
two,
followed by' one or more blanks. The statements are described
below, with examples.
~~2Q~!£~ Stgt~~~~t:
This statement tells the UPDATE command that you
want to number or renumber the records in a file.
Sequence numbers are
written in columns 73 through 80. For example, the statement:
)
./ S
1000
indicates that you want sequence numbering to be done, in increments of
1000, with the first statement numbered 1000. The SEQUENCE statement is
convenient if you want to apply updates to a file that does not already
have sequence numbers.
In this case, you may want to use the REP
(replace) option of the UPDATE command, so that instead of creating a
new file ($filename), the original source file is replaced:
update sample (rep
INSERT Statement: This statement precedes new records that you want to
ada-to -a-source file.
The INSERT statement tells the UPDATE command
where to add the new records. For example, the lines:
./ I
TEST2
1600
TM
BNO
HOLIDAY,X'02'
VACATION
HOLIDAY?
NOPE ••• VACATION
result in the two lines of code being inserted into the output file
following the statement numbered 00001600.
The inserted lines are
flagged with asterisks in columns 73 through 80.
The INSERT statement
also allows you to request that new statements be sequenced; see
"Sequencing Output Records."
DELETE Statement: This statement tells the UPDATE command which records
yoU-want-to-delete from the source file. If your UPDATE file contains:
)
./ D
2500
Section 13. Programming for the CMS Environment
253
then only the record 00002500 is deleted.
./ D
2500
If the file contains
2aOO
then all the statements
source file.
from 2500
through 2aOO
are deleted
from the
REPLACE Statement: The REPLACE statement allows you to replace one or
iore-records-In-the source file. It precedes the new records you want
to add. It is a combination of the DELETE and INSERT statements. Por
example, the lines
. / R 3aOOO 3a500
PLIST
DS
OD
DC
CLa'TYPE'
DC
CLa"
DC
CLa'PILE'
DC
CLa'A1'
DC
ax'pp'
replace existing statements numbered 3aOOO through 3a500 with the new
lines of code. As with the INSERT statement, new lines are not
automatically resequenced.
~gftft~!I ~~~!~~~~!:
Use this statement when you want to place comments in
the update log file. For example, the line:
./ *
Changes by John J. Programmer
is not processed by the UPDATE command when it creates the
file, but it is written into the update log file.
new source
SEQUENCING OUTPUT RECORDS
~
(~
The UPDATE command expects source files to have sequence numbers in
columns 73 through ?O.
If you use the SERIAL subcommand of the CftS
editor to sequence your files, the sequence numbers are usually written
in columns
76 through
ao; columns
73 through
75 contain
a
three-character identifier which is usually the first three characters
of the filename. If you want an eight-character sequence number, you
must use the subcommand:
serial all
prior to issuing a PILE or SAVE subcommand when you are editing the
file. Or, you can create an UPDATE file with the single record:
./ S
and issue the UPDATE command to sequence the file.
If you use the UPDATE command with a file that has been sequenced
using the CMS editor's default values, you must use the NosEQa option.
Otherwise, the UPDATE command cannot process your input file.
The
command:
update sample (noseqa
tells UPDATE to use
sequence numbers.
only columns
76
through ao
Figure 22 shows the four files involved in
contents.
254
IBft VM/370 CftS User's Guide
~
when
it looks
for
simple update, and their
(
The Source File, SA"PLE ASSE"BLE
CSECT
00000100
00000200
USING SAMPLE,R12
LR
R12,R15
00000300
00000400
ST
R14,SAVRET
LINEDIT TEXT='PLEASE ENTER YOUR NAME'
00000500
00000600
RDTERM NA"E
LINEDIT TEXT='PLEASE ENTER YOUR AGE'
00000700
RDTERM AGE
00000800
LINEDIT TEXT='HI, •••••••••• , YOU JUST TOLD "E YOU ARE ••••• ',x00000900
00001000
SUB=(CHAR1,Nl"E,CHARA,AGE} ,RENT=NO
R14,SAVRET
L
00001100
00001200
BR
R14
00001300
EJECT
DC
CL 130' ,
00001400
NAME
DC
CL 130' ,
AGE
00001500
SAVRET
00001600
DC
F'O'
REGEQU
00001700
END
00001800
L - - - - -___________________________________________________________________________________
SA"PLE
~
The Update File, SAMPLE UPDATE
)
. j * REVISION BY DLC
. j R 500
LINEDIT TEXT='WHAT"S YOUR NAME?',DOT=NO
. j R 700 1000
LINEDIT TEXT='HI, •••••••••• , ENTER THE DOCNIME',
SUB=(CHARA,NAME}
RDTERM NAME
MVC
DOCFN,NAME
LA
1,PLIST
SVC 202
DC
AL4 (ERROR)
RETURN
EQU
*
. j I 1200
ERROR
EQU
*
WRTERM 'FILE NOT FOUND'
B
RETURN
. j D 1500
. j I 1600
PLIST
DS
OD
DC
CL8'TYPE'
CL8' ,
DOCFN
DC
DC
CL8'FILE'
DC
CL8' Al'
DC
8X'FF'
Figure 22.
SI"00010
SA"00020
SI"00030
51"00040
xSl"00050
SI"00060
S1M00070
SI"00080
S1M00090
SI"00100
SA"00110
SA"00120
SA"00130
SA"00140
51"00150
SAM00160
5AM00170
51M00180
S1M00190
SAM00200
S1M00210
SAM00220
S1M00230
S1M00240
Updating Source Files with the UPDATE Command (Part 1 of 2)
)
Section 13. Programming for the CftS Environment
255
The Update Log File, SAMPLE UPDLOG
,
UPDATING 'SAMPLE
ASSEMBLE A1' WITH 'SAMPLE
UPDATE
Al'
UPDATE LOG -- PAGE
11
./ * REVISION BY DLC
I
./ R 500
1
DELETING •••
LINEDIT TEIT='PLEASE ENTER YOUR NAME'
000005001
INSERTING •••
LINEDIT TEIT='WHAT"S YOUR NAME?',DOT=NO
********1
./ R 700 1000
I
DELETING •••
LINEDIT TEIT='PLEASE ENTER YOUR AGE'
000007001
RDTERM AGE
OOOOOSOOI
LINEDIT TEIT='HI, ~ ••••••••• , YOU JUST TOLD ME YOU ARE ••••• ',x000009001
SUB=(CHARA,NAME,CHARA,AGE),RENT=NO
000010001
INSERTING •••
LINEDIT TEIT='HI, •••••••••• , ENTER THE DOCNAME',
x********1
SUB=(CHARA,NAME)
****.**** 1
RDTERM NAME
********1
MVC
DOCFN,NAME
********1
LA
1,PLIST
********1
SVC 202
********1
DC
AL4 (ERROR)
********1
RETURN
EQU
*
********1
./ I 1200
1
INSERTING...
ERROR
EQU
*
********1
WRTERM 'FILE NOT FOUND'
********
B
RETURN
********
./ D 1500
CL 130' ,
DELETING...
AGE
DC
00001500
./ I 1600
INSERTING...
PLIST
DS
OD
********
DC
CLS'TYPE'
********
CLS' ,
DOCFN
DC
********
DC
CLS'FILE'
********
DC
CLS' Al'
********
DC
SX'FF'
********
The Updated Output File, SSAMPLE ASSEMBLE
r--
SAMPLE
CSECT
USING SAMPLE,R12
R12,R15
LR
R14,SAVRET
ST
LINEDIT TEIT='WHAT"S YOUR NAHE?',DOT=NO
RDTERM NAME
ENTER THE DOCNAME',
LINEDIT TEXT='HI,
'
SUB=(CHARA,NAME)
RDTERM NAME
HVC
DOCFN,NAME
1,PLIST
LA
SVC 202
DC
AL4 (ERROR)
EQU
*
R14,SAVRET
L
R14
BR
EQU
*
WRTERM 'FILE NOT FOUND'
RETURN
B
EJECT
DC
CL130' ,
DC
F'O'
DS
OD
DC
CLS'TYPE'
DC
CLS' ,
DC
CLS'FILE'
DC
CLS'A1'
DC
SX'FF'
REGEQU
END
.........
RETURN
ERROR
NAME
SAVRET
PLIST
DOCFN
Figure 22.
..
00000100
00000200
00000300
00000400
********
00000600
x********
********
********
********
********
********
********
********
00001100
00001200
********
********
********
00001300
00001400
00001600
********
********1
********1
********1
********1
********1
000017001
00001S001
r1
~
Updating Source Files with the UPDATE Command (Part 2 of 2)
(
256
IBM VM/370 eMS User's Guide
The INSERT and REPLACE statements allow you to control the numbering
increment of records that you add to a source file.
Notice, in Figure
22, that inserted records have the character string '********' in
columns 73 through 80. If you want sequence numbers on the inserted
records, you must do two things:
1.
Use the INC option on the UPDATE command line. If you use the CTL
option, you do not have to specify the INC option. The CTL option
is described below, under "Multiple Updates."
2.
Include a dollar sign ($)
on the INSERT or REPLACE statement,
optionally followed by operands indicating how the records should
be sequenced.
For example, to sequence the
statements would appear as:
./
./
./
./
R
R
I
I
records added
in Figure 22,
the control
500 $
700 1000 $
1200 $
1600 $
and you would issue the UPDATE command:
update sample (inc
The upDATE command sequences inserted records by increments of 10.
If you want to control the numbering, for eXample, if you need to insert
more than 10 statements between two existing statements, you can specify
an alternate sequencing scheme:
./ I
1800 $ 1805
5
)
Records introduced
following this INSERT statement
are numbered
00001805, 00001810, 00001815, and so on.
(If the NOSEQ8 option is in
effect, then the records would be XIX01805, XXX01810, and so on, where
XXX is the three-character identifier used in columns 73 through 75.)
MULTIPLE UPDATES
If you have several UPDATE files to apply to the same source, you may
apply them in a series of UPDAtE commands.
For example, if you have
updates named FICA UPDTUP1, FICA UPDTUP2, and FICA UPDTUP3 to apply to
the source file FICA PLIOPT, you could do the {allowing:
1.
Update the source file with TEST1 UPDATE:
update fica pliopt a fica updtupl
2.
Update the source file produced by the above command with the TEST2
UPDATE:
update $fica pliopt a fica updtup2
3.
)
Update the new source file with TEST3:
update $$fica pliopt a fica updtup3
section 13. Programming for the CMS Environment
257
This final UPDATE command produces the file $$$FICA PLIOPT, which is now
the fully updated source file.
This method is cumbersome, however,
particularly if you have many updates to apply and they must be applied
in a particular order.
Therefore, the UPDATE command provides a
multilevel update scheme, which you can use to apply many updates at one
time, in a specified order.
To apply multilevel updates, you must have-a control file, which by
convention has a filetype of CNTRL and a filename that is the same as
the source input file. Therefore, to apply the three update files to
FICA PLIOPT, you should create a file named FICA CNTRL.
A control file is actually a list: it does not contain any actual update
control statements (INSERT, DELETE, and so on), but rather it indicates
what update files should be applied, and in what order. In the case of
a multilevel update, all the update files must have the same filename as
the source file. Therefore, only the t!lg!~£g§ need be specified in the
control file to uniquely identify the update file. In fact, if all your
update files have filetypes beginning with the characters UPDT, you need
only specify the unique part of the filetype. The control file for FICA
PLIOPT, named FICA CNTRL, may typically look like the following:
TEXT MACS PLILIB
FICA3 UP3
FICA2 UP2
FICAl UPl
The first record in the control file must be a MACS record. The
second field in this record must be "MACS," and it may be followed by up
to eight macro library names.
Every record in the control file must
have an "update level identifier;" in this example, the update level
identifiers are TEXT on the MACS record, FICAl for the UPl record, and
so on.
The update level identifier may have a maximum of five
characters.
The UPDATE command only uses the MACS record and the update level
These ar~ described later,
identifier under special circumstances.
under "VMFASM EXEC Procedure."
For now, you only need to know that
these things must be in a control file in order for the UPDATE command
to execute properly.To update
follows:
FICA PLIOPT, then, you
would issue the UPDATE
command as
update fica pliopt (ctl
When you use the CTL option, and you do not specify the name of a
control file, the UPDATE command looks for a control file with the
filetype of CNTRL and a filename that is the same as the source file.
From the control file, it reads the filetypes of the updates to be
applied. In this example, it searches for the file FICA UPDTUP1 and if
found, applies the updates; then UPDATE searches for FICA UPDTUP2, and
applies those updates, if any. Last it searches for FICA UPDTUP3, and
applies those updates.
Notice that the updates are applied from the bottom of the control
file,
toward the top.
This becomes important when an update is
dependent on a previous update. For example, if you add some lines to a
file in FICA UPDTUP1,then modify one of those lines in FICA UPDTUP2, it
is important that UPDTUP1 was applied first.
258
IBM VM/370 eMS User's Guide
(
l1TEj!1!~
!!!§ Q! ~f~£!!!!!~ ~Q1I!1~!~& Qf~lI~ !1~~~: The example above,
showing FICA CNTRL and UPDTxxxx files, illustrates a naming scheme using
the UPDATE command defaults. You can override the default filetypes for
the control file's filename and filetype, as well as filetypes for the
update files.
If you name a control file GROUPA CNTRL, for example, you can specify
the name of the control file on the UPDATE command line:
update fica pliopt a groupa cntrl (ctl
Similarly, if your update files have unique filetypes, you must
specify the entire filetype in the control file. If your updates to
FICA PLIOPT are named FICA TEST1, FICA TEST2, and FICA TEST3, your
control file may look like the following:
TEXT MACS PLILIB
"FICA3 TEST3
FICA2 TEST2
FICA1 TEST1
Regardless of the filetypes you choose, however, the filenames
always be the same as the filename of the input source file.
must
The two levels of update processing shown so far may be adequate fer
your applications. There is, however, an additional level, or step, in
the update structure that the VM/370 procedures use and which you may
want to use also.
These techniques may be useful when you have more than one set of
updates to apply to a source program. For example, you may have two
groups of programmers who are working on different sets of cbanges for
the same source file. Each group may create several update files, and
have a unique control file. When you combine these changes, you could
create one control file, or yOu can use what are known as auxiliary
control files.
The updating structure for auxiliary control files is based on
conventions for assigning filenames and filety~es. If a control file
contains an entry that begins with the characters 'AUX', the UPDATE
command assumes that the file 'fn AUXnnnn' contains a list of filetypes,
not UPDATE control statements. For example, if,the file SAMPLE ASSEMBLE
is being updated with a control file that contains the record:
TEST1 AUXLIST
then SAMPLE AUXLIST does not contain UPDATE control statements; it
contains entries indicating the fi!~1I£~§ of the update files, all ef
which must have the same filename, SAMPLE.
Let's expand the example to see how this structure works.
We have
the source file, SAMPLE ASSEMBLE. The file SAMPLE CNTRL contains the
entries:
,
TEXT MACS
3676 AUXLIST
Section 13. Programming for the CMS Environment
259
The file, SAMPLE AUXLIST may look like the following:
TEST1
FIXLOOP
BYPASS
The files:
SAMPLE TESTl
SAMPLE FIXLOOP
SAMPLE BYPASS
all contain UPDATE control statements (INSERT, DELETE, and so on) that
are to be applied to the file SAMPLE ASSEMBLE. As with control file
processing, the updates are applied from the bottom of the AUX file, so
that the updates in SAMPLE BYPASS are applied first, then the updates in
SAMPLE FIXLOOP, and so on. For an illustration of a set of update
files, see Figure 23.
Since the updating scheme uses only filetypes to uniquely identify
update files,
it is possible to use the same control file to update
different source input files.
For example, using the control file
REPORT CNTRL shown in Figure 23, you issue the command:
update fica pliopt a report cntrl (ctl
The UPDATE command begins searching for updates to apply to FICA PLIOPT,
based on the entries in REPORT CNTRL: it searches for FICA AUXLIST,
which may contain entries pointing to update files; then it searches for
FICA UPDTREP1, and so on.
As long as all updates and auxiliary files associated with a source
file have the same filename as the source file, the updates are uniquely
identifiable, so the same control file can be used to update various
source files.
VM/370 takes advantage of this capability in its own
updating procedures. By maintaining strict naming conventions, updates
to various CP and CMS modules are easily controlled and identified.
A control file may point to many AUX files in addition to many UPDT
files.
You can modify a control file when you want to control which
updates are applied to a program, or you may have several control files,
and specify the name of the control file you want to use on the UPDATE
command line. There is a lot of flexibility in the UPDATE command
processing; you can implement procedures and conventions for your
individual applications.
PREFERRED LEVEL UPDATING: There may exist more than one version of an
update;-each-ipplIcable--to different versions of the same module. For
example, you may need one version of an update for an unmodified base
source module, and another version of that update if that module has
been mOdified by a program product. The AUX file that will be used to
update a particular mOdule must then be selected based on whether or not
a program product modifies that module.
The AUX files listing the
updates applicable to modules modified by a program product are called
"preferred AUX files" because they must be used if they exist rather
than the mutually exclusive updates applicable to unmodified modules.
Using this preferred AUX file concept, every module in a component can
be assembled using
the one CNTRL file applicable
to a user's
configuration.
A single AUX file entry in a CNTRL file can specify more than one
filetype.
The first filetype indicates a file that UPDATE uses only on
one condition: the files that the second and subsequent filetypes
indicate do not exist. If they do exist, this AUX file entry is ignored
and no updating is done.
The files that the second and subsequent
260
IBM VM/370 CMS User's Guide
(
filetypes indicate are perferred because, if they exist, UPDATE does net
use the file that the first filetype indicates. Usually, the preferred
files appear later in the CNTRL file in a format that causes them to be
used for updating.
UPDATE scans each CNTRL file entry until a preferred filetype is
found,
until there are no more filetypes on the entry, or until a
comment is found.
(A character string that is less than four or more
than eight characters is assumed to be a comment.)
REPORT
CNTRL
TEXT
UP2
LIST
UPl
TEXT
REPORT
UPDTPROC
MACS
UPDTPROC
AUXLlST
UPDTREPl
AUXFIX
REPORT
AUXFIX
REPORT
AUXLlST
REPORT
FIXIN
REPORT
FIXOUT
REPORT
RTNA
REPORT
RTNB
update report assemble a (etl
UPDATING 'REPORT ASSEMBLE Al' WITH 'REPORT RTNA Al'.
UPDATING WITH 'REPORT RTNB Al'.
UPDATING WITH 'REPORT UPDTREPl Al'.
UPDATING WITH 'REPORT FIXOUT Al'.
UPDATING WITH 'REPORT FIXIN Al'.
UPDATING WITH 'REPORT UPDTPROC Al'.
R;
Figure 23. An Update with a Control File
)
Section 13. Programming for the CMS Environment
261
THE VMFASM EXEC PROCEDURE
If you are an assembler language programmer and you are using the UPDATE
command to update source programs you may want to use the VftFASM EXEC
procedure. VftFASM is a Vft/310 update procedure; it invokes the UPDATE
command and then uses the ASSEftBLE command to assemble the updated
source file.
If you are not an assembler language programmer, you may wish to
create an EXEC similar to VftFASM that, instead of calling the assembler,
calls one of the language compilers to compile an updated source file.
When you use VMFASft, you specify the source filename, the filename of
the control file, and optionally, parameters for the assembler.
(The
control file for VftFASM must have a filetype of eNTRL). For example, if
you use the file GENERAL eNTRL to update SAMPLE ASSEMBLE, you enter the
command line:
vmfasm sample general
The VMFASft EXEC uses the MACS card and the update level
in the control file.
It reads the ftACS card to determine
libraries (ftACLIBs)
should be searched by the assembler.
issues the GLOBAL MACLIB command specifying the ftACLIBs you
MACS card.
identifiers
which macro
Then VMFASM
name on the
The update level identifier is used by VMFASM to name the output text
file produced by the assembly. If the update level identifier of the
most recent update file (the last one located and applied) is anything
other than TEXT, the update level identifier is prefixed with the
characters TXT to form the filetype. For example, if the file GENERAL
CNTRL contains the records:
TEXT MACS CMSLIB MILIB OSMACRO
UP2 FIX2
UPl FIXl
TEXT AUXLIST
and it is used to update the file SAMPLE ASSEMBLE, then:
•
If the file SAMPLE UPDTFIX2 is found and the updates applied, VftFASM
names the output text deck SAMPLE TXTUP2.
•
If the file SAMPLE UPDTFIXl is found and the updates applied but no
SAMPLE UPDTFIX2 is found, the text deck is named SAMPLE TXTUP1.
•
If the file SAMPLE AUXLIST is found but no SAMPLE UPDTFIXl or SAMPLE
UPDTFIX2 files are found, the text deck is named SAMPLE TEXT.
•
If no files are found, the update level identifier on
is used and the text deck is named SAMPLE TEXT.
the MACS card
Since the UPDATE command works from the bottom of a control file
toward the top, it is logical that the text filename be taken from the
identifier of the last update applied.
The VMFASft EXEC does not produce an updated source file, but leaves
the original source intact. VMFASft produces two output files: a printed
output listing that shows update activity; and the text file, which
contains the update log as well as the actual object code. If you use
the CftS LOAD command to load a text file produced by VftFASft, records
from the update log are flagged as invalid, but the LOAD operation is
not impaired.
262
IBft VM/310 CftS User's Guide
(
!~~ ~!!
OP!lQB: If you are interested in writing your own EXEC procedure
to invoke the UPDATE command, you may wish to use the STK option. The
STK (stack) option is valid only with the CTL option, and is meaningful
only when the UPDATE co.mand is invoked within an EXEC procedure.
When the STK option is specified,
lines in the console stack:
first line:
second line:
*
*
UPDATE stacks the
following data
update level identifier
library list from MACS record
The update level identifier is the
that was found and applied.
identifier of the most recent update
Por example, an EXEC file that invokes the UPDATE command
the ASSEMBLE command may contain the lines:
*
and then
*
UPDATE &1 ASSEMBLE
&2 CNTRL
(STK CTL
&READ VARS &STAR &TX
&READ VARS &STAR &LIB1 &LIB2 &LIB3 &LIB4 &LIB5 &LIB6 &LIB7 &LIB8
GLOBAL MACLIB &LIB1 &LIB2 &LIB3 &LIB4 &LIES &LIB6 &LIB7 &LIB8
&IF &TX NE TEXT PILEDEP TEXT DISK &1 TXT&TX 11
ASSEMBLE &1 &3 &4 &5 &6 &7 &8 &9
ERASE $&1 ASSEMBLE
If this EXEC is named UPASM EXEC and is invoked with the line:
upasm fica fica (print noxref
and the file PICA CNTRL contains:
)
MAC MACS CMSLIB OSMACRO MYTEST
PIX1 UPDTFIX
LIST AUXLIST
then the EXEC' executes the following commands:
*
*
UPDATE FICA ASSEMBLE
FICA CNTRL
(STK CTL
GLOBAL MACLIB CMSLIE OSMACRO MYTEST
FILEDEF TEXT DISK FICA TXTFIX1 A1
ASSEMBLE FICA (PRINT BOX REF
ERASE $FICA ASSEMBLE
The above example assumes that the
and applied.
update file FICA UPDTFIX
was found
Section 13. programming for the CMS Environment
263
(
264
IBM VM/370 eMS User's Guide
Part 3. Learning to Use EXEC
In previous sections, the CMS EXEC facilities were described in general
terms to acquaint you with the expressions used in EXEC files and the
basic way that EXECs function. Also, examples of EXEC procedures have
appeared throughout this publication. You should be familiar at least
with the material in "Introduction to the EXEC Processor" before you
attempt to use the information in Part 3.
"Section 14. Building EXEC Procedures" describes the EXEC facilities
in detail, with examples of techniques you may find useful as you learn
about EXEC and develop your own EXEC procedures.
Special considerations for using CMS commands in EXECs and modifying
CMS command functions using EXEC procedures are described in "section
15. Using EXECs With CMS Commands."
"Section 16. Refining Your EXEC Procedures" lists several techniques
you can use to make your EXEC files easier to use and provides some
hints on debugging EXEC procedures.
If you are a frequent user of the CMS editor, then you may be
interested in "Section 17. writing Edit Macros," which describes how to
create your own EDIT subcommands using EXEC procedures.
)
Part 3. Learning to Use EXEC
265
(
266
IBM VM/370 eMS User's Guide
Section 14. Building EXEC Procedures
This section discusses various techniques that you can use when you
write EXEC procedures. The examFles are intended only as suggestions:
you should not feel that they represent either the only way or the best
way to achieve a particular result. Many combinations and variations of
control statements are possible; in most cases, there are many ways to
do the same thing.
This section is called "Building EXEC procedures" because you will
often find that once you have created an EXEC procedure and begun to use
it, you continually think of new applications or new uses for it. Using
the CMS editor, you may quickly build the additions and make the
necessary changes. You are encouraged to develop EXEC procedures to help
you in all the phases of your CMS work.
What Is a Token?
An executable statement is any line in an EXEC file that is processed by
the EXEC interpreter, including:
•
•
•
•
).
CMS command lines
EXEC control statements
Assignment statements
Null lines
Executable statements may appear by themselves on a line or as the
object of another executable statement, for example in an &IF or &LOOP
control statement.
If you want to execute CP commands or other EXEC
procedures in an EXEC, you mu~t use the CP and EXEC commands,
respectively. CP commands are passed directly to CP for processing.
All executable statements in an EXEC are scan~ed by the CMS scan
routine. This routine converts each word (words are delimited by blanks
and parentheses) into an eight-character quantity called a token. If a
word contains more than eight characters, it is truncated on the right.
If it contains fewer than eight characters, it is padded with blanks.
When a parenthesis appears on the line, it is treated both as a
delimiter and as a token. For example, the line:
&TYPE WHAT IS YOUR PREFERENCE (REDIBLUE)?
scans as follows:
&TYPE WHAT IS YOUR PREFEREN ( REDIBLUE) ?
After a line has been scanned, each token is scanned for ampersands
and substitutions are performed on any variable symbols in the tokens
before the statement is executed. After elimination of any null
variables, the statement may contain a maximum of 32 tokens.
Nonexecutable statements are lines that are not processed by the EXEC
interpreter, that is, comment lines (those that begin with an *), and
data lines following an &BEGEMSG, &BEGPUNCH, &BEGSTACK, or &BEGTYPE
control statement.
Since these lines are not scanned, words are not
truncated, and tokens are neither formed nor substituted.
)
Since all executable statements in an EXEC are scanned, and the data
items are treated as tokens, the term "token" is used throughout this
Section 14. Building EXEC Procedures
267
section to describe data items before and after scanning.
The VftLl1.Q
CMS Command and Macro !~!~~~~£~, which contains the formats and
descrIptIons of--the-iiic control statements, uses this convention as
well. Therefore, as you create your EXEC procedures, you may think of
the items that you enter on an EXEC statement as tokens, since that is
how they are used by the EXEC interpreter.
Variables
To make the best use of the CMS EXEC facilities,
you should have an
understanding of how the EXEC interpreter performs substitutions on
variable symbols contained in tokens. Some examples follow. For each
example, the input lines are shown as they would appear in an EXEC file
and as they would appear after being interpreted and executed by EXEC.
Notes concerning substitution follow each example.
~lMP1!
~Q~~~!~Q~!Q!: Most
of the EXEC examples in this publication
contain variable symbols that result in one-far-one substitution. Most
of your variables, too, will have a similar relationship.
Lines
&i-;-123
&TIPE &X
!!!~~ ~YQ~!i!Y!i2~
&X = 123
&TIPE 123
The EXEC interpreter accepts the variable symbol &X and assigns it the
value 123. In the second statement, &X is substituted with this value,
and the control statement &TIPE is recognized and executed.
Lines
SY-;-456
&z = &y
After Substitution
Sy-;-456---------&Z = 456
The symbol &1 is assigned a value of 456. In the second statement, the
symbol &1 is substituted with this value, and this value is assigned to
&z.
SUBSCRIPTS FOR VARIABLES: Since each token is scanned more than once for
ampersands,-you-can-sIiulate subscripts by using two variable values in
the same token.
Lines
S1'-;-ALPHA
&2 = BETA
&INDEX1 = 1
&TIPE &&INDEI1
&INDEI1 = 2
&TIPE &&INDEI1
After Substitution
S'-;-ALPHi-------&2 = BETA
&INDEI1 = 1
&TIPE ALPHA
&INDEI1 = 2
&TIPE BETA
In the statement &TIPE &&INDEI1, the token &INDEI1 is scanned the first
time, and the value &INDEI1 is substituted with the value 1. The token
now contains &1, which is substituted with the value ALPHA on a second
scan. When the value of &INDEI1 is changed to 2, the value of &&INDEI1
also changes.
1i!!~§
&1 =
&1&1
&1 =
&1&1
&1 =
268
!t!~~ ~YQ§!i!yti~!!
2
=
5
1
= 2
&1&1 + &X&I&I
&1 = 2
&X2 = 5
&1 = 1
&11 = 2
&1 = 2 + 5
IBM VM/370 CMS User's Guide
In the statement &1&1 = 5, analysis of the first token results in the
substitution of the symbol &1 with the value of 2. The symbol &12 is
assigned a value of 5.
The value
value of 2.
of &1 is changed
to 1, and
the symbol &X1 is
assigned a
In the last statement, &1 = &1&1 + &1&1&1, the value of &1 in the
token &1&1 is replaced with 1, then the symbol &X1 is substituted with
its value, which is 2. The token &1&1&1 is substituted after each of
three scans: &1 is replaced with the value 1, to yield the token &1&X1.
The symbol &11 has the value of 2, so the token is reduced to &X2, which
has a value of 5.
COMPOUND VARIABLE
character-strIngs.
2I~~Q12:
1i1!~
&X = BEE
&TYPE HONEY&I
&TYPE ABUMBLE&X
Variable symbols
may also be
combined with
!!!~! 2Y~2!i!ytiQ1!
&1 = BEE
&TYPE HONEYBEE
&TYPE ABUMBLE
In the above example, the first symbol encountered in the scan of
HONEY&I is &X, which is substituted with the value &BEE.
In the second
&TYPE statement, the I is truncated when the line is scanned; the symbol
& is an undefined symbol and is therefore set to blanks.
1J:J!~2
&1 = HONEY
&Y = BEE
&TYPE &I&Y
!!!~! 2Y~2!itytiQ1!
&1 = HONEY
&Y = BEE
&TYPE
In the above example, after the symbol &Y is substituted with the value
BEE, the token contains the symbol &IBEE, which is an undefined symbol,
so the symbol is discarded.
Lines
&123=
ABCDE
&1 = 12345678
&TYPE ABLE&&I
After Substitution
&123-=-iBCDE-----&1 = 12345678
&TYPE ABLEABCD
In this example, the substitution of &X in the token ABLE&&X results in
the character string ABLE&12345678,
which
is truncated to eight
characters, or ABLE&123. The scan continues,
and &123 is substituted
with the appropriate value, to result in !BCDE. The token is again
truncated to eight characters.
SUBSTITUTING 1II~RA1 !!1Q~2: You might want an ampersand to appear in a
token:---Yoll can use the &LITERAL built-in function to suppress the
substitution of variable symbols in a token.
1i1!~2
&9 = HELLO
&A = &LITERAL &9
STYPE SA
After Substitution
&9-;-HELLO-------&A = &LITERAL &9
STYPE &9
Because the value of SA was defined
performed.
1J:1!~2
&TYPE = QUERY
&TYPE BLIP
)
as a literal &9, no substitution is
!!!~! 2Y~2!i!ytiQ1!
STYPE = QUERY
QUERY BLIP
In the above example, even though &TYPE is an EIEC keyword, it
assigned the value of QUERY, and substitution is performed when
Section 14. Building EIEC Procedures
is
it
269
appears on an input line. In this example, when it is substituted with
its value, the result is a command line which is passed to CMS for
processing.
li~
SCONTROL = FIRST
SLITERAL SCONTROL ALL
!!!~! 2YR§!i!Y!i~D
SCONTROL = FIRST
SCONTROL ALL
In this example, SCONTROL is assigned a value as a variable symbol, but
when it is preceded by the built-in function SLITERAL, the substitution
is not performed, so EXEC processes it as a control statement.
~~!!~~£!~!1
!!~ ~I£!!!~
~Q!!!B2!QB~: Iou
can perform hexadecimal to
decimal and decimal to hexadecimal conversions in an EXEC if you use the
control statement SHEX ON. To convert hexadecimal to decimal, you must
use an assignment statement, prefacing the hexadecimal value you want to
convert with the characters X' and assigning the value to a variable
sy.bol.
When 'HEX ON' is in effect, the following additional rules
restrictions apply to tokens on EXEC control statements:
1.
and
Any token, variable argument, or combination which results in a
token with the string X' as the first two characters (this will be
referrred to as an X' token)
must also result in the next six
characters being either:
(a)
A valid decimal number, if the token is part of an EXEC
control which is not an assignment statement, or a valid
hexadcimal number, if the token is part of an EXEC control
statement which is an assignment statement.
(b)
The numbers mentioned in item 1a may be positive (no sign), or
negative, (prefixed with a minus sign
(-220 or -FE». The
negative hexadecimal number is the absolute hexadecimal number
prefixed with a minus sign (-F is a hexadecimal minus F, not a
/
\1
minus~
(c)
These numbers may be explicit (in the orginal token), or
substituted from a variable or an argument
(for example,
X'SX).
(d)
The rules for token length apply with 'SHEX ON'.
(e)
The range of decimal numbers that may be contained in an X'
token is -99999 to 999999. The range of hexadecimal numbers
that may be contained in an X' token is -FFFFF to FFFFFF. The
ahove range of numbers may be extended by placing the number
to be converted in a variable or an argument and substituting
at conversion time. If this is done, the conversion is
accomplished using the variable or the argument as the number
source. The range for decimal numbers is -9999999 to 99999999,
the range for hexadecimal numbers is 5F5EOFF to -98967F.
These examples illustrate this feature:
SI = X'FFFFFF
STIPE X'SI
SI = 5F5EOFF
SX = X'SI
(f)
SI = 16777215
STIPE FFFFFF
SI = SF5EOFF
SX = 99999999
The notation X'-SX should not be used, because this will cause
unwanted truncations and conversion errors.
(
270
IBM VM/370 CMS User's Guide
If these restrictions are violated,
inconsistant conversion will result.
a
conversion
error
or
These statements are not valid if "HEX ON' is in effect:
SHEX ON
SX = X'50
CAUSES CONVERSION ERROR - See Item 1a above
This sequence results in a conversion error
contain a decimal number after the X', so
violates item 1a above.
SHEX ON
SX = SLITERAL X'ABC
SI = SX
STIPE SX
because SX does not
the STIPE statement
SX = X'ABC
LEGAL STATEMENT
XI = 2748
LEGAL STATEMENT
CAU~ES CONVERSION ERROR
2.
An X' token cannot appear on an EXEC statement
assignment statement (for example, STIPE,SIF).
3.
If an X'
token appears on an assignment
decimal converS10n 1S performed before
statement E1 in the HEX EXEC Example.
4.
The largest hexadecimal value that will be converted to decimal is
5F5EOFF,
if the number is in a variable or an argument.
If
explicitly defined, only the leftmost six digits will be used. See
statement E2 of HEX EXEC Example.
5.
A decimal number contained in a variable or an argument and
referenced as such on an X' token (for example, X'SX)
will not be
truncated before it is converted to a hexadecimal number. Decimal
numbers 0 through 99999999 may be converted to hexadecimal if they
are first placed in a variable or an argument.
)
other than
an
statement, hexadecimal to
the token is used.
See
Note that the hexadecimal number typed is seven digits long.
Example:
SHEX ON
SX = 99999999
STIPE X'SX
SX = 99999999
STIPE 5F5EOFF
The following illustrates conversions with 'SHEX ON' in effect:
~!~£ £gD!~gl ~!g!~!~D!§
-E1
-E2
-E3
-E4
)
SCONTROL ALL
SHEI ON
SNUM = X'FFFFFF
STIPE HEX'SNUM = DEC SNUM
SIF 1'16777215 = X'SNUM SGOTO -E3
&TIPE SLITERAL X'16777215
NE SLITERAL X'SNUM
&TIPE X'16777215 NE I'&NUM
&NUM = X'10
&1 = SNUM + X'B
&TIPE SI X'SI
SI = X'NUM
SZ = SCONCAT SLITERAL X'1 X'SNUM
SHEX OFF
&TIPE SI SZ
SHEX ON
&TIPE SI SZ
&NUM = 16777215
&TIPE HEX FFFFFF
= DEC 16777215
&IF 28F5C = FFFFFF
SGOTO -E3
&TIPE 1'167772 NE X'SNUM
STIPE 28F5C BE FFFFFF
SlUM = 16
&Y = 16 + 11
STIPE 27 1B
SI = 22
SZ = SCONCAT 1'1 22
SHEX OFF
STIPE 22 X'122
SHEX ON
&TIPE 22 7A
Section 14. Building EXEC Procedures
211
To suppress hexadecimal conversion during an EXEC procedure
having used it, you can use the EXEC control statement:
after
&HEX OFF
so you can use tokens containing the characters
processor converting them to hexadecimal.
X' without
the EXEC
Arguments
An argument in an EXEC procedure is one of the special variable symbols
&1 through &30 that are assigned values when the EXEC is invoked. For
example, if the EXEC named LINKS is invoked with the line:
links viola ariel oberon
the tokens VIOLA~ ARIEL, and OBERON are arguments and are
the variable symbols &1, &2, and &3, respectively.
assigned to
You can pass as many as 30 arguments to an EXEC procedure; thus the
variable symbols you can set range from &1 to &30. These variables are
collectively referred to as the special variable &n. Once these symbols
are d~fined, they can be used and manipulated in the same manner as any
other variable in an EXEC. They can be tested, displayed, changed, and,
if they contain numeric quantities, used arithmetically.
&IF &2 EO PRINT &GOTO -PR
&TIPE &1 IS AN INVALID ARGUMENT
&1 = 2
&CT = &1 + 100
The above exa.ples illustrate some explicit methods of manipulating the
&n variables. They can also be implicitly defined or redefined by two
EXEC control statements: &ARGS and &READ ARGS.
An &ARGS control statement redefines all of the special &n variables.
The statement:
&ARGS ABC
assigns the value of A, B, and C to the variables &1, &2, and
sets the remaining variables, &4 through &30, to blanks.
&3 and
Iou can also redefine arguments interactively by using the &READ ARGS
control statement. When EXEC processes this statement, a read request is
presented to your terminal, and the tokens you enter are assigned to the
&n variables. for example, the lines:
STIPE ENTER FILE NAME AND TYPE:
&READ ARGS
STATE &1 &2
*
request you to enter two tokens, and then treat these tokens as the
arguments &1 and &2. The remaining variables &3 through &30 are set to
blanks.
If you want to redefine specific &n variables, and leave the values
of others intact, you can either redefine the individual variables in
separate assignment statements, or use the variable symbol in the &ARGS
or &R~AD ARGS statement. For example, the statement:
.
&ARGS CONT &2 &3 RETURN &5 &6 &7 &8 &9 &10
272
IBM V8/370 CMS User's Guide
(
assigns new values to the variables Sl and &4, but does not change the
existing values for the remaining symbols through S10.
If you need to set an argument or &n special variable to blanks,
either on an EXEC command line or in an SARGS or &READ ARGS control
statement, you can use a percent sign (I) in its place. Por example, the
lines:
SARGS SET QUERY 1 TYPE
STYPE Sl S2 S3 S4
result in the display:
SET QUERY TYPE
The symbol S3 has
from the line.
a value of blanks, and as a
null token, is discarded
USING THE SINDEX SPECIAL VARIABLE
The EXEC special variable, SINDEX, initially contains a numeric value
corresponding to the number of arguments defined when the EXEC was
invoked. The value of SIND EX is reset whenever an SARGS or &READ IRGS
control statement is executed.
SINDEX can be useful in many circumstances. If you create an EXEC
that may expect any number of arguments, and you are going to perform
the same operation for each, you might set a counter and use the value
of &INDEX to test it. Por example, an EXEC named PRINTX accepts
arguments that are the filenames of ASSEMBLE files:
SCT =
SLOOP
PRINT
SCT =
1
2 SCT > SIND EX
SSCT ASSEMBLE
SCT + 1
In the preceding example, the token SCT is substituted with Sl, S2, and
so on until all of the arguments entered on the PRINTX line are used.
You can also use SINDEX to test the number of arguments entered. If
you design an EXEC to expect at least two arguments, the procedure might
contain the statements:
SIP SINDEX LT 2 SGOTO -ERRl
-ERRl STYPE INVALID COMMAND LINE
SEXIT 1
In this example, if the EXEC is invoked with one or no arguments, an
error message is displayed and the EXEC terminates processing with a
return code of 1.
)
As another example, suppose you wanted to supply an EXEC with default
arguments, which might or might not be overridden. If the EXEC is
invoked with no arguments, the default values are in effect; if it is
invoked with arguments, the arguments replace the default values:
Section 14. Building EXEC procedures
273
&DISP = PRINT
&COUNT = 2
&IF &INDEX GT 2 &EXIT 1
&IF &INDEX EQ 0 &GOTO -GO
&COUNT = &1
&IF &INDEX = 2 &DISP = &2
-GO
Default values are supplied for the variables·&DISP and &COUNT. Then,
&INDEX is tested, and the variables are reset if any arguments were
entered.
CHECKING ARGUMENTS
There are a number of tests that you can perform on arguments passed to
an EXEC. In some cases, you may want to test for the length of a
specific argument or to test whether an argument is character data or
numeric data. To perform these tests, you can use the EXEC built-in
functions &LENGTH and &DATATYPE.
To use either &LENGTH or &DATATYPE, you must first assign a variable
to receive the result of the function,
and then test the variable. For
example, to test whether an entered argument is five characters long,
you could use the statements:
&LIMIT = &LENGTH &1
&IF &LIMIT GT 5 &EXIT &LIMIT
When these statements are executed, if the first argument (&1)
is
greater than five characters, the exit is taken, and the return code
indicates the length of &1.
If you wish to check whether a
use the &DATATYPE function:
number was entered for
an argument,
&STRING = &DATATYPE &2
&IF &STRING ~= NUM &GOTO -ERR4
In this example, the second argument expected by the EXEC must be a
numeric quantity. If it is not, a branch is taken to an error exit
routine.
Often, you may create an EXEC that tests for specific arguments and
then takes various paths, depending on the argument. For example:
&IF &2
&IF &2
&IF &2
&EXIT
= PRINT &GOTO -PR
= TYPE &GOTO -TY
= ERASE &GOTO -ER
In this EXEC, if the value of &2 is not PRINT, TYPE, or
not entered, the EXEC terminates processing.
ERASE, or was
There are two special EXEC keywords that you may use to test arguments
passed in an EXEC. They are &* and &$, which can be used only in an &IF
or an &LOOP control statement. They test the entire range of numeric
variables &1 through &30~ as follows:
274
IBM VM/370 CMS User's Guide
(
~!:
The special token &$ is interpreted as "any of the variables &1, &2,
••• , &30." That is, if the value of anyone of the numeric variables
satisfies the established
condition, then the &IF
statement is
considered to be true. The statement is false only when none of the
variables fulfills the specified requirements.
As an example, suppose you want to make sure that
value is passed to the EXEC. You can check to see
arguments satisfy this condition, as follows:
some particular
if any of the
&IF &$ EQ PRINT &SKIP 2
&TYPE PARM LIST MUST INCLUDE PRINT
&EXIT
In this example, the path to the &TYPE state.ent is taken only when none
of the arguments passed to the EXEC procedure equal the character string
PRINT.
§!: The special token &* is interpreted as "all of the variables &1, &2,
••• , &30."
That is, if the value of each of the numeric variables
satisfies the established
condition, then the &IF
statement is
considered to be true. The statement is false when at least one of the
variables fails to meet the specified requirements.
Use &* to test for the absence of an argument as follows:
&IF &* NE ASSEMBLE &EXIT 3
In this example, if an EXEC is invoked, and none of the arguments equals
ASSEMBLE, the EXEC terminates with a return code of 3.
)
The tokens &* and &$ are set by arguments entered when an EXEC is
invoked and reset when you issue an &ARGS or &READ ARGS control
statement. If either &* or &$ is null because no arguments are entered,
the &IF statement is considered a null statement, and no error occurs.
Execution Paths in an EXEC
You have already seen examples of the &IF, &GOTO, &SKIP, and &LOOP
control statements. A more detailed discussion on each of these
statements and additional techniques for controlling execution paths in
an EXEC procedure follow.
LABELS IN AN EXEC PROCEDURE
In many instances, an execution control statement in an EXEC procedure
causes a branch to a particular statement that is identified by a label.
The rules and conventions for creating syntactically correct EXEC labels
are:
•
A label must begin with a hyphen (dash) and must have
additional character following the hyphen.
•
Up to seven additional alphameric characters may follow
(with no intervening blanks). However, the sequence:
at least one
the hyphen
&GOTO -PROBABLY
)
-PROBABLY
Section 14. Building EXEC Procedures
275
executes successfully, because when each statement is scanned, the
token -PROBABLY is truncated to the same eight-character token,
-PROBABL.
•
A label name may
statement.
be
the
object
of
an &GOTO
or
&LOOP
control
•
A label that is branched to must be the first token on a line. It
may stand by itself, with no other tokens on the line, or it may
precede an executable CMS command or EXEC control statement.
The following are examples of the correct use of labels:
&GOTO -LAB1
-LAB1
-LAB2 &CONTINUE
-CHECK &IF &INDEX EQ 0 SGOTO -EXIT
&IF SINDEX LT 5 &SKIP
-EXIT SEXIT 4
&TYPE &LITERAL SINDEX VALUE IS SINDEX
CONDITIONAL EXECUTION WITH THE &IF STATEMENT
The main tool available
an EXEC procedure is
statement provides the
conditional branches in
to you for controlling conditional execution in
the &IF control statement. The SIF control
decision-making ability that you need to set up
your EXEC procedure.
One approach to decision-making with the SIF control statement is to
compare two tokens, and perform some action based on the result of the
comparison.
When the comparison specified is equal
(or true), the
executable statement is executed. When the comparison is unequal (or
false), control passes to the next sequential statement in the EXEC
procedure. An example of a simple &IF statement is:
&IF &1 EQ &2 STYPE MATCH FOUND
If the comparand values are not equal, the statement &TYPE MITCH
FOUND is not executed, and control passes to the next statement in the
EXEC procedure. If the co.parand values are equal, the statement &TYPE
MATCH FOUND is executed before control passes to the next statement.
SIF statements can also be used to establish a comparison between a
variable and a constant. For example, if a terminal user could properly
enter a YES or NO response to a prompting message, you could set up &IF
statements to check the response as follows:
&READ ARGS
&IF &1 EQ YES &GOTO -YESANS
&IF &1 EQ NO &GOTO -NOANS
&TYPE &1 IS NOT A VALID RESPONSE (MUST BE YES OR NO)
&EXIT
-YESANS
-NOANS
In this example, the branch to -YESANS is taken if the entered
argument is YES; otherwise, control passes to the next SIF statement.
216
IBM VM/310 CMS User's Guide
(
The branch to -NOANS is taken if the argument is NO; otherwisE~, control
passes to the STYPE statement, which displays the entered argument in an
error message and exits.
The test performed in an SIF statement need not be a simple test of
equality between two tokens; other types of comparisons can be tested,
and more than two variables can be involved. The tests that can be
performed and the symbols you can use to represent them are:
~Y~~~l
=
~=
<
<=
>
)=
~~~~~~i£
EO
NE
LT
LE
GT
GE
~~!~!Bg
A
A
A
A
A
A
equals B
does not equal B
is less than B
is less than or equal to B (not greater than)
is greater than B
is greater than or equal to B (not less than)
You can place multiple SIF control statements on one line, to test a
variable for aore than one condition. For example, the statement:
SIF SNOM GT 5 SIF SNOM LT 10 STYPE O.K.
checks the variable symbol SNOM for a value greater than 5 and less than
10. If both of these conditions are satisfied, the &IF statement is
true, and the STYPE statement is executed. If either condition is false,
then the STYPE statement is not executed.
The number of SIF statements that may be nested is limited
restrictions placed on the record length of the EXEC file.
only by
BRANCHING WITH THE SGOTO STATEMENT
The SGOTO control
EXEC procedure:
•
statement allows you to transfer
control within your
To a specified EXEC label somewhere in the EXEC file:
SGOTO -TEST
where -TEST is the label to which control is passed.
•
To a particular line within the EXEC file. For example:
SGOTO 15
results in control being passed to statement 15 in the EXEC file.
•
Directly to the top of the EXEC file. For example:
SGOTO TOP
)
passes control to the beginning of the EXEC procedure.
Section 14. Building EXEC Procedures
277
The &GOTO control statement can be coded wherever an executable
statement is permitted in an ~XEC procedure.
One of its common uses is
in conjunction with the &IF control statement. For example, in the
statement:
&IF &INDEX EO 0 &GOTO -ERROR
the branch to the statement labeled -ERROR is taken when the value of
the &INDEX special variable is zero. otherwise, control passes to the
next sequential statement in the EXEC proceduie.
An &GOTO statement can also stand alone as an EXEC control statement.
When coded as such, it forces an unconditional branch to the specified
location.
For example, you might create an EXEC that has several
execution paths, each of which terminates with an SGOTO state.ent
leading to a common exit routine:
-PATHl &CONTINUE
&GOTO -EXIT
-PATH2 &CONTINUE
&GOTO -EXIT
&PATH3 &CONTINUE
-EXIT &CONTINUE
You can
example:
use the &GOTO
control statement
to establish a
loop.
For
&GLOBAL1 = &GLOBALl + 1
&TYPE ENTER NUMBER:
&READ VARS &NEXT
&IF .&NEXT = .&GOTO -FINIS
&IF &GLOBALl = 2 &TOTAL = 0
STOTAL = &TOTAL • &NEXT
&GOTO TOP
-FINIS
&TIPE TOTAL IS &TOTAL
In this EXEC example, all of the statements, through the &GOTO TOP
statement, are executed repeatedly until a null line is entered in
response to the prompting message.
Then, the branch is taken to the
label -FINIS and the total is typed.
Note the use of the special variable &GLOBALl in the preceding
example. The &GLOBALn special variables are self-initializing and have
an initial value of 1.
When an EXEC procedure processes an &GOTO statement, and searches for a
given label or line number, the scan begins on the line following the
&GOTO statement, proceeds to the bottom of the file, then wraps around
to the top of the file and continues to the line immediately preceding
278
IBM VM/370 CMS User's Guide
(
the SGOTO state.ent. If there are duplicate labels in an EXEC file, the
first label encountered during the search is the one that is branched
to.
If the label or line number is not found during
terminates processing and displays the message:
the scan,
EXEC
ERROR IN EXEC PILE filename, LINE n - SSKIP or SGOTO ERROR
If the label or line nuaber is found, control is passed to that location
and execution continues.
BRANCHING WITH THE SSKIP STATEMENT
The SSKIP control statement provides you with a second aethod of passing
control to various points in an EXEC procedure. Instead of branching to
a naaed or numbered location in an EXEC procedure, SSKIP passes control
a specified nuaber of lines forward or backward in the file.
Iou pass control forward in an EXEC by specifying how many lines to
skip. Por exa.ple, to handle a conditional exit fro. an EXEC procedure,
you could code the following:
SIP SRETCODE EO 0 SSKIP
SEXIT SRETCODE
)
where the SEXIT statement is skipped whenever the value of SRETCODE
equals zero.
If the value of SRETCODE does not equal zero, control
passes out of the current EXEC procedure with a return code that is the
nonzero value in SRETCODE.
NQte that when no SSKIP operand is
specified, a value of 1 is assu.ed.
A succession of SSKIP statements can be used to perform multiple
tests on a variable. Por example, suppose an argu.ent should contain a
value from 5 to 10 inclusive:
SIP S1 LT 5 SSKIP
SIF S1 LE 10 SSKIP
STIPE S1 IS NOT WITHIN RANGE 5-10
If the value of S1 is less than 5, control passes to the STYPE control
statement, which displays the erroneous value and an explanatory
message. If the value of S1 is greater than or equal to 5, the next
statement checks to see if it is less than or equal to 10. If this is
true, then the value is between 5 and 10 inclusive, and execution
continues following the STIPE statement.
When you want to pass control to a statement that precedes the
current line, deter.ine how many lines backward you want to go, and code
SSKIP with the desired negative value:
SVAL = 1
STIPE SVAL
&VAL = &VAL + 1
&IP SVAL NE 10 SSKIP -2
In this EXEC, the STIPE statement is executed repeatedly until the value
of SVAL is 10, and then execution continues with the statement following
the SIP statement.
)
Section 14. Building EXEC Procedures
279
USING COUNTERS FOR LOOP CONTROL
A primary consideration in designing a portion of an EXEC procedure that
is to be executed many tiaes is how to control the number of executions.
One way to dontrol the execution of a sequence of instructions is to
create a loop that tests and changes the value of a counter.
Before entering the loop, the counter is initialized to a value.
Each time through the looPr the counter is adjusted (increased or
decreased) toward a li.it value. When the limit value is reached (the
counter value is the same as the limit value), control passes out of the
loop and it is not executed again. For example, the following EXEC
initializes a counter based on the argument &1:
&IF &INDEX EO 0 &EXIT 12
&TYPE COUNT IS &1
&1 = &1 - 1
&IF &1 GT 0 &SKIP -2
When this EXEC procedure is invoked, it checks that at least one
argument was passed to it. If an argument is passed, it is assumed to
be a number that indicates how many times the loop is to execute. Each
time it passes through the loop, the value of &1 is decreased by 1.
When the value of &1 reaches zero, control passes from the loop to the
next sequential statement.
There are several ways of setting, adjusting,
Some ways to set counters are by:
•
and testing counters.
Reading arguments fro. a terminal, such as:
&READ VARS &COUNT1 &COUNT2
•
Assigning an arbitrary value, such as:
&COUNTER
•
= 43
Assigning a variable value or expression, such as:
&COUNTS
= &INDEX
- 1
Counter values can be increased or decreased by
decrement that meets your purposes. For example:
any increment
or
&COUNTEM = &COUNTEM - &RETCODE
&COUNT1 = &COUNT + 100
LOOP CONTROL WITH THE &LOOP STATEMENT
A convenient way- to control execution of a sequence of EXEC statements
is with the &LOOP control statement. An &LOOP statement can be set up
in four ways:
•
To execute a particular number of statements a specified
times. For example, the statement:
number of
&LOOP 3 2
indicates that the three statements following the &LOOP statement are
to be executed twice.
280
IBM VM/310 CMS User's Guide
(
•
To execute a particular number of
condition is satisfied. For example:
statements until
a
specified
&LOOP 4 &X = 0
The four statements
value of &X is O.
•
following this statement are
executed until the
To execute the statements down to
(and including) the statement
identified by a label for a specified number of times. For example:
&LOOP -ENDLOOP 6
The statements between this &LOOP
are executed six times.
•
statement and the
label -ENDLOOP
To execute the statements down to
(and including) the state.ent
identified by a label until a specified condition is satisfied. In
the following example:
&LOOP -ENDLOOP &X
=
0
the statements are executed repeatedly until the value of &X is O.
The numbers specified for the number of lines to execute and the
number of times through the loop must be positive integers. You can use
a variable symbol to . represent the integer. If a label is used to
define the limit of the loop, it must follow the &LOOP statement (it
cannot precede the &LOOP statement).
In a conditional &LOOP statement, any
conditional phrase are substituted each time
example, the statements:
variable symbols in
the loop is executed.
the
For
&X = 0
&LOOP -END &1 EQ 2
&X = &1 + 1
-END &TYPE &X
are interpreted and executed as follows:
1.
The variable &1 is assigned a value of
2.
The &LOOP statement is interpreted as a conditional form; that is,
to loop to -END until the value of &X equals 2. Since the value of
&X is not 2, the loop is entered.
3.
The variable &X is increased by 1 and is then displayed.
4.
Control returns to the beginning of the loop, where &X is tested to
see if it equals 2. Since it does not, the loop is executed'again
and 2 is displayed. The next time through the loop~ when &X equals
2, control is passed to the EIEC statement immediately following
the label -END.
When this
displayed:
EXEC
procedure
is executed,
~.
the
following
lines
are
1
2
)
at which time the value of &1 equals 2; the loop is not executed again.
Section 14. Building EXEC procedures
281
Another example of a conditional loop is:
SY = SLITERAL ASB
SLOOP 2 .SX EQ SLITERAL .S
SX = SSUBSTB SY 2 1
STYPE SX
These statements are interpreted and executed as follows:
1.
The variable SY is set to the literal value ASB.
2.
The two statements following the SLOOP statement are to be executed
until the value of SX is S.
3.
The SSUBSTR built-in function is used to set the variable SX to the
value of the second character in the variable SY, which is a
literal ampersand (S).
4.
The ampersand is typed once, and the loop does not execute again
because the condition that the value of SX be a literal ampersand
is met.
NESTING EXEC PROCEDURES
If you want to use an EXEC procedure within another EXEC, you must use
the EXEC command to execute it. Por example, if you have the statement:
EXEC TEST
in an EXEC procedure, it invokes the EXEC procedure TEST. The procedure
TEST EXEC executes independently of the other EXEC; the variables S1, S2
and so on are assigned values and the default settings for control
statements such as SCONTROL and SHEX are reset.
When TEST EXEC
completes execution, control returns to the next line in the calling
EXEC, where the values for variable symbols and EXEC settings are the
same as when the TEST EXEC was invoked.
Variables in an EXEC file have meaning only within the particular
procedure in which they are defined. There are two methods you can use
to pass variable information to nested EXECs. One way is to pass
arguments on the EXEC command line.
Por examFle, if the CHECK EXEC
contains the line:
EXEC COUNTEM SITEMCT SHUM
then the current values of SITEMCT and SHU! are assigned to the variable
symbols S1 and S2 in COURTEM EXEC. (The values of S1 and &2 in CHECK
EXEC do not change.)
You can also use the ten special variables &GLOBALO through &GLOB1L9.
These variables can only contain integral numeric values; you cannot
assign them character-string values. These variables can be used to set
up arguments to pass to nested procedures, or to communicate between
EXEC files at different recursion levels.
282
IBM VM/370 CftS User's Guide
(
Thus, if CHECK EXEC contains:
&GLOBAL1 = 100
EXEC COUNTEM
The variable &GLOBAL1 has a value of 100 in COUNTEM EXEC, which may also
test and modify it.
The EXEC interpreter can handle up to 19 levels of recursion at one
time, that is, up to 19 EXECs may be active, one nested within another.
An EXEC may also call itself.
Iou can test the &GLOBAL special variable to see if an EXEC is
executing within another procedure and if so, at what level of recursion
it is executing. For example, if the file RECOMP EXEC contained the
lines:
&IP &GLOBAL EQ 2 &GOTO -2NDPASS
EXEC RECOMP
-2NDPASS &TIPE SECOND PASS BEGINS
then when the line "EXEC RECOMP" is executed, control passes
beginning of the EXEC; the value of &GLOBAL changes from 1 to
control is passed to the &TIPE statement at the label 2NDPASS.
to the
2; and
EXITING FROM EXEC PROCEDURES
Execution in an EXEC procedure proceeds sequentially through a file,
line by line. When a statement causes control to be passed to another
statement, execution continues at the second statement, and again
proceeds sequentially through the file.
When the end of the file is
reached, the EXEC terminates processing. Frequently, however, you may
not want processing to continue to the end of the file. You can use the
&EXIT statement to cause an immediate exit from EXEC processing and a
return to the CMS environment. If the EXEC has been invoked from
another EXEC, control is returned to the calling EXEC file.
For
exaaple, the statement:
&IF &RETCODE
~=
0 &EXIT
would cause an immediate exit from the
last issued CMS command was not zero.
)
EXEC if the return code from the
You can use the &EXIT statement to terminate each of a
execution paths in
an EXEC.
For example,
using the
statements,
series of
following
Section 14. Building EXEC Procedures
283
&IF &1 EQ PRINT &GOTO -PRINT
&IF &1 EQ TYPE &GOTO -TYPE
-PRINT
&EXIT
-TYPE
&EXIT
you ensure that once the path through the -PRINT routin~ has been taken,
the .EXEC does not continue processing with the -TYPE routine.
The &EXIT control statement also provides a special function that allows
you to pass a return code to CMS or to the program or EXEC that called
this EXEC. You specify the return code value on the &EIIT control
statement as follows:
&EXIT 4
Execution of this line results in a return to CMS with a ready message:
R (00004) ;
If you have a variety of exits in an EXEC, you can use a different value
following each &EIIT statement, to indicate which path had been taken in
the EXEC.
You can also use
return code:
a variable symbol as the value to
be passed as the
&EXIT &VAL
Another common use of the &EXIT statement is to cause an exit to be
taken following an error in a CMS command, and using the return code
from the CMS command in the &EIIT statement:
&IF &RETCODE NE 0 &EIIT &RETCODE
Terminal Communications
You can design EXECs to be used interactively, so that their execution
depends on information entered directly from the terminal during the
execution. With the &TYPE statement, you can display a line at the
terminal, and with the &READ statement, you can read one or more lines
from the terminal or console stack. Used together, these statements can
provide a prompting function in an EXEC:
(
284
IBM VM/370 CMS User's Guide
STYPE
STYPE
SREAD
SGOTO
-STOP
WHAT DO YOU WANT TO DO NOW?
ENTER (STOP CONTINUE REPEAT):
VARS SLABEL
-SLABEL
-CONTINUE
-REPEAT
In this example, the SREAD control statement is used with the VARS
operand, which accepts the words entered at the terminal as values to be
assigned to variable symbols. If the word STOP is entered in response to
the &READ VARS statement in this example, the variable symbol SLABEL is
assigned the value STOP. Then, in the SGOTO statement, the symbol is
substituted with the value STOP# so the branch is taken to the label
-STOP.
You can specify up to 17 variable .names on an &READ VARS control
statement. If you enter fewer words than are expected, the remaining
variables are set to blanks.
If you enter a null line, any variable
sy.bols on the SREAD line are set to blanks. If the execution of your
EXEC depends on a value entered as a result of an SREAD VARS, you might
want to include a test for a null line immediately following the
statement; for example:
SREAD VARS STITLE &SUBJ
SIF .STITLE = . SEXIT 100
If no tokens are entered in response to the terminal read request, the
variable STITLE is null, and the EXEC terminates with a return code of
100.
If you are writing an EXEC that may receive a number of tokens from
the terminal, you may find it more convenient to use the SREAD ARGS form
of the SREAD control statement. When the SREAD ARGS statement reads a
line from the terminal, the tokens entered are assigned to the &n
special variables (S1, S2, and so on).
READING CMS COMMANDS AND EXEC CONTROL STATEMENTS FROM THE TERMINAL
When you use the &READ control statement with no operands, or with a
numeric value, EXEC reads one line or the specified number of lines from
the terminal. These lines are treated, by EXEC, as if they were in the
EXEC file all along. For example, if you have an EXEC named COMMAND that
looks like the following:
STYPE ENTER NEXT COMMAND:
SREAD 1
SSKIP -2
)
all the commands you enter during the terminal session are processed by
the EXEC. Each time the SREAD statement is executed, you enter a CMS
command. When the command finishes, control returns to EXEC, which
prompts you to enter the next command. Since the CMS commands are all
Section 14. Building EXEC
procedu~es
285
being executed from within the EXEC, you do not receive the
message at the completion of each command.
CMS ready
You could
also enter EXEC
control statements
or assignment
statements. To terminate the EXEC and return to the CMS environment,
you must enter the EXEC control statement SEXIT from the terminal:
Sexit
DISPLAYING DATA AT A TERMINAL
You can use the STYPE and SBEGTYPE control statements
from your EXEC at the terminal. In addition, you can
command to display the contents of CMS files.
to display lines
use the CMS TYPE
When you use the STYPE control statement, you can display variable
symbols as well as data. Variable symbols on an STYPE control statement
are substituted before they are displayed. For example, the lines:
SNAME = ARCHER
STYPE SNAME
result in the display:
ARCHER
You can use the STYPE statement to display prompting messages, error
or information messages, or lines of data.
In an EXEC file with fixed-length records, only the first 72
characters of each line are
processed by the EXEC interpreter.
Therefore, if you want to use the STYPE control statement to display a
line longer than 72 characters, you must convert the file into
variable-length records.
All of the words in an STYPE control statement are scanned into
8-character tokens. If you need to display a word that has aore than 8
characters, you must use the SBEGTYPE control statement. The SBEGTYPE
control statement precedes one or more data lines that you want to
display; for example:
SBEGTYPE
THIS EXEC PERFORMS THE FOLLOWING FUNCTIONS:
1. IT ACCESSES DISKS 193, 194, and 195 AS
B, C, AND D EXTENSIONS OF THE A-DISK.
2. IT DEFINES, FORMATS, AND ACCESSES A
TEMPORARY 195 DISK (E).
SEND
The SEND statement must be used to terminate a series of lines
introduced with the SBEGTYPE statement. "SEND" must begin in column 1 of
the EXEC file.
The lines following an SBEGTYPE statement, up to the SEND statement,
are not scanned by the EXEC interpreter. Therefore, no substitution is
performed on the variable symbols on these data lines. If you need to
display a symbol, you must use the STYPE control statement. To display a
286
IBM VM/370 CMS User's Guide
(
combination of scanned and unscanned lines, you might need
the &TYPE and &BEGTYPE control statements:
to use both
&BEGTYPE
EVALUATION BEGINS •••
&END
&TYPE &VAL1 IS &IUM1.
&TYPE &VAL2 IS &IUM2.
&BEGTYPE
EVALUATIOI COMPLETE.
&END
If you use the &BEGTYPE control statement in an
fixed-length records, and you want to display lines
characters, you must use the ALL operand. For example:
EXEC file with
longer than 72
&BEGTYPE ALL
••• data line of 103 characters
••• data line of 98 characters
••• data line of 50 characters
&END
You can display lines of up to 130 characters in this way. When you
enter lines that are longer than the record length in an EXEC file, the
records are truncated by the editor. You must increase the record length
of the file by using the LRECL option of the EDIT command, for example:
edit old exec a
)
(lrecl 130
In a variable-length EXEC file,
you do not need to specify ALL to
display long lines. If you originally created the file with a record
length of 130 characters, you do not need to increase the size later to
accomodate longer records.
You can use the TYPE command in an EXEC file to display data files, or
portions of data files.
For example, you might have a number of files
with the same filetype; the files contain various kinds of data. You
could create an EXEC that invokes the TYPE comnand to display a
particular file as follows:
&IF &lNDEX EQ 2 &IF &2 EQ ? &GOTO -TYPE
-TYPE
ACCESS 198 B
TYPE &1 MEMO B
The filetype MEMO is a reserved filetype, which accepts data
uppercase and lowercase; you can use it for documentation files
programming notes.
)
in
or
The two CMS Immediate commands that control terminal display are HT
(halt typing) and RT (resume typing). When data is being displayed at
Section 14. Building EXEC Procedures
287
your terminal, you can suppress the
interruption and entering:
display by signaling
an attention
ht
This command affects output that is being displayed:
•
As a response to a CMS command, including prompting messages, error
messages, or normal display responses (as from the TIPE command)
•
From a program
•
In response to an STIPE or SBEGTYPE request in an EXEC
Once display has been suppressed, and before the command, program, or
EXEC completes execution, you can request that display be resumed by
signaling another interruption and entering:
rt
In an EXEC file, if you want to halt or resume display, you must use
the SSTACK control statement to enter the RT or HT commands.
For
example, the ACCESS command issues a message when a disk is accessed:
D(198) R/O
If you are going to issue the ACCESS command within an EXEC and you do
not wish this message displayed, you could enter the lines:
&STACK HT
ACCESS 198 D
Once you have stacked an HT command, all displaying
the remainder of the EXEC file's execution, unless
command is processed, either following an attention
described above) or within the EXEC.
To execute
command in an EXEC, use the statement:
is suppressed for
the RT Immediate
interruption
(as
the RT Immediate
&STACK RT
A physical read to the terminal, for example the result
control statement, also resets the display setting to RT.
of an &READ
!~~ ~!!g~f1!~
~~~i~l !g~igRl~: You can
test the current value of the
display controlling an EXEC with the STIPEFLAG special variable. The
value of STIPEFLAG can only be one of the literal values HT or RT. For
example:
SIF &$ EQ ROTYPE SSTACK HT
SIF &TIPEFLAG EQ HT SSKIP 3
&TIPE LINE1
STIPE LINE2
&TIPE LINE3
SCONTINUE
In this example, if ROTYPE is entered as an argument when the EXEC is
invoked, an HT command is stacked, so that no displaying is done at the
terminal. Within the EXEC, the variable &TIPEFLAG is tested, and, if it
is BT, then a series of &TIPE statements is skipped. Since EXEC does
not have to process these lines, you can save time and system resources
by not processing them.
288
IBM VM/370 CMS User's Guide
(
Reading from the Console Stack
When you are in the CMS environment executing programs or CMS commands,
you can stack commands, either by entering multiple command lines
separated by the logical line end symbol, as follows:
print myfile listingtcp query printer
or by signaling
as follows:
an attention interruption and entering
a command line,
print myfile listing
!
cp query printer
In both of the preceding examples, the second command line is saved
in a terminal input buffer, called the console stack.
Whenever a read
occurs in your virtual machine, CMS reads lines from the console stack,
if there are any lines in it. If there are no lines in the stack, the
read results in a physical read to your terminal
(on a typewriter
terminal, the keyboard unlocks) •
A virtual machine read occurs whenever a command or subcommand
finishes execution, or when an EXEC or a program issues a read request.
Many CMS commands also issue read requests, for example, SORT and
COPYFILE. If you want to execute one of these commands in an EXEC, you
may want to stack, in the console stack, the response to the read
request so that when it is issued it is immediately satisfied. For
example:
)
&STACK 42-121 1
COPYFILE &NAME LISTING A = ASSEMBLE
=
(SPECS
When the COPYFILE command is issued with the SPECS option, a prompting
message for a specification list is issued, followed by a read request.
In this EXEC, the request is satisfied with the line stacked with the
&STACK control statement. If the response was not stacked, you would
have to enter the appropriate information from the terminal during the
execution of the EXEC that contained this COPYFILE command line.
In addition to stacking predefined
responses to commands and
programs, you can use the console stack to stack CMS commands and EDIT
subcommands, as well as data lines to be read within the EXEC.
The number of lines that you can place in the console stack at any
one time varies according to the amount of storage available in your
virtual machine for stacking. You may want to stack one or two lines at
a time, or you may wish to stack many lines. There are several features
available in EXEC that can help you manipulate the stack.
)
Just as the &TYPE control statement has an &BEGTYPE counterpart, the
&STACK control statement has an &BEGSTACK counterpart. You can stack
multiple data lines following an &BEGSTACK statement. Lines stacked in
this way are not scanned by the EXEC processor, and no substitution is
performed on variable symbols. For example, the lines:
Section 14. Building EXEC Procedures
289
SBEGSTACK
.~.line of data
••• line of data
••• line of data
SEND
stack three data lines in the stack. The stacked lines must be followed
by an SEND control statement, which must be entered in the EXEC file
beginning in column 1.
If you have an EXEC with fixed-length records, and you want to stack
data lines longer than 12 characters, you must use the ALL operand of
the SBEGSTACK control statement:
SBEGSTACK ALL
••• line of 103 characters
••• line of 98 characters
••• line of 60 characters
SEND
The ALL operand is not necessary for variable-length EXEC files.
When you are stacking multiple lines in an EXEC, you may choose to
reverse the sequence in which lines are read in from the stack. The
default sequence is FIFO (first-in, first-out), but you may specify LIFO
(last-in, first-out) when you enter the SSTACK or SBEGSTACK control
statement. For example, execution of the lines:
SSTACK
SSTACK
SSTACK
SSTACK
SSTACK
STYPE A
STYPE B
LIFO STYPE C
LIFO STYPE D
STYPE E
results in the display:
D
C
A
B
E
The EXEC special variable SREADFLAG always contains one of two values,
STACK or CONSOLi.
When it contains the value STACK, it indicates that
there are lines in the stack. When it contains the value CONSOLE, it
indicates that the stack is empty and that the next read request results
in a physical read to the terminal (console).
You can test this value in an EXEC, for example:
SIF SREADFLAG EQ STACK &SKIP 2
STYPE STACK EMPTY
SEXIT
SCONTINUE
290
IBM VM/310 CMS User's Guide
(
You might use a similar test in an EXEC that processes a nu.ber of lines
from the stack, and loops through a series of steps until the stack is
empty.
STACKING CftS COftftANDS
Whenever you place a command in the console stack, it remains there
until a read request is presented to the terminal. If the request is the
result of an SREAD control statement, then the line is read from the
stack. For example, the lines:
SSTACK CP QUERY TIftE
SREAD
result in the command line being stacked, read in, and then executed.
If there are no read requests in an EXEC file, then any commands that
are stacked are executed after the EXEC-has finished and has returned
control to the CftS environment. For example, consider the lines:
TYPE S1 LISTING A
ACCESS 198 A
TYPE S1 LISTING A
If this EXEC is located en your 191 A-disk, then when the ACCESS command
accesses a new A-disk, CftS cannot continue reading the EXEC file and
issues an error message. However, if the EXEC was written as follows:
TYPE S1 LISTING A
SSTACK ACCESS 198 A
SSTACK TYPE S1 LISTING A
then, after the TYPE command, the next command lines are stacked, the
EXEC finishes executing and returns cdntrol to CftS, which reads the next
command lines from·the console stack.
When you stack CftS commands with the SSTACK control statement in an
EXEC procedure, you cannot place multiple command lines in one statement
separated by the logical line end symbol
(for example, print ate
listinglprint xyz listing). CP does not translate the logical line end
symbol (#)
to a value of x'15' because a line is being read from the
EXEC file cn disk and not from the terminal. However, you can place
multiple command lines in one statement if separated by the value x'15'.
The ALTER subcommand of EDIT can be used to insert the x'15' value. C~S
does recognize the x'15' character.
~!~!i~~ ~Yl~ ~Y~fg!!!~g§
If you want to issue the EDIT command from within an EXEC, you might
want to stack EDIT subcommands to be read by the CftS editor. You should
stack these subcommands, either with SSTACK statements, or with the
SEEGSTACK statement, just before issuing the EDIT command. For example:
)
SBEGSTACK
CASE M
GET SETUP FILE A 1 20
TOP
LOCATE /XX/
SEND
SSTACK REPLACE
EDIT &1 DATA (LRECL 120
Section 14. Euilding EXEC Procedures
291
If this EXEC is named E,DEX, and you invoke it with:
edex fr01
the EDIT subcommands are stacked in the order they appear in the EXEC.
The EDIT command is invoked to edit the file FR01 DATA, and the EDIT
subcommands are read from the stack and executed~ When the stack is
empty, your virtual machine is in the edit environment in input mode,
and the first line you enter replaces the existing line that contains
the character string xx.
Note that all of the EDIT subcommands in the example, except for the
REPLACE subcommand, are stacked within an SBEGSTACK stack, and that the
REPLACE subcommand is stacked with &STACK. If you are creating EXEC
files with fixed-length records, you must use SSTACK to stack the INPUT
and REPLACE subcommands. If you use SBEGSTACK, then the INPUT and
REPLACE subcommands are treated as if they contain text data, and so
insert or replace one line in the file
(a line of bl.nks). This is not
true, however, for variable-length EXEC files.
Similarly, if you want to stack a null line, to change from input
mode to edit mode in an EXEC, you must use the SSTACK statement with no
other data on the line (in both fixed- and variable-length EXEC files),
for example:
SSTACK INPUT
SBEGSTACK
••• data line
••• data line
••• data line
SEND
SSTACK
SSTACK FILE
EDIT &1 S2
SEXtT
When this EXEC is invoked with a filename and filetype as arguments, the
INPUT subcommand, data lines, null line, and FILE subcommand are placed
in the stack before the EDIT command is issued.
The data lines are
placed in the specified file and the file is written onto disk before
the EXEC- returns control to CMS.
STACKING LINES FOR EXEC TO READ
Lines in the console stack can be read by the
SREAD control statement; for example:
-SETUP
SLOOP 3 SlUM = 50
SSTACK SNUM SCHAR
SNUM = SNUM + 1
SCHAR = SCONCAT SSTRNG SNUM
-READ
SLOOP -FINIS SREADFLAG EQ COISOLE
SHEAD AHGS
-FINIS
292
IBM VM/370 CMS User's Guide
EXEC interpreter with an
In this EXEC procedure, the statements following the label -SETUP stack
a number of lines. The variables SNUM and SCHAR are substituted before
they are stacked. At the label -READ, the lines are read in from the
stack and processed. The values stacked are read in as the variable
symbols S1 and S2. Control passes out of the loop when the stack is
eapty.
CLEARING THE CONSOLE STACK
If you use the console stack in an EXEC procedure, you should be sure
that it is empty before you begin stacking lines in it. Also, you
should be sure that it is empty before exiting from the EXEC (unless you
have purposely stacked CMS commands for execution).
One way to clear a line from the stack without affecting the
execution of your EXEC is to use the SREAD VARS or SREAD ARGS control
statement.
You can use SREAD VARS without specifying any variable
sy.bols so that the line read is read in and effectively ignored. For
example:
SLOOP 1 SREADFLAG EO STACK
SREAD ARGS
If these lines occur at the beginning of an EXEC file, they ensure that
any stacked lines are cleared.
If the EXEC is named EXEC1 and is
invoked with the line:
exec1.type help memo'type print memo
)
then the lines TYPE HELP MEMO and TYPE PRINT MEMO
stack and are not executed.
are cleared from the
You could use the same technique to clear the stack in case of an
error encountered in your EXEC, so that the stack is cleared before
returning to CMS. You would especially want to do this if you stacked
data lines or EXEC control statements that have no meaning to CMS.
Another way to clear the
DESBUF. For example:
console stack
is with
the CMS
function
&IF &READFLAG EO STACK DESBUF
When you use the DESBUF function to clear the console input stack, the
output stack is also cleared. The output stack contains lines that are
waiting to be displayed or typed at the terminal.
Frequently, when an
EXEC is processing, output lines are stacked, and are not displayed
immediately following the execution of an STYPE statement. If you want
to display all pending output lines before clearing the console input
stack, you should use the CONWAIT function, as follows:
CONWAIT
SIF SREADFLAG EO STACK DESBUF
The CONWAIT (console wait)
function causes a suspension of program
execution until the console output stack is empty. If there are no lines
waiting to be displayed, CONWAIT has no effect.
)
Clearing the stack is important when you write edit macros, since all
subcommands issued in an edit macro must be first stacked. See "Section
11. Writing Edit Macros" for additional information on using the console
stack.
Section 14. Building EXEC Procedures
293
File Manipulation with EXECs
You can, to a limited degree, read and write CMS disk files using EXECs.
You can stack files with a filetype of EXEC in the console stack and
then read them, one record at a time, with SREAD control statements. All
data items are truncated to eight characters. You can write a file, one
record at a time, with the SPUNCH control statement, and then you can
read the spool punch file onto disk. Examples of these techniques
follow.
STACKING EXEC FILES
There are two methods to stack EXEC files in the console stack. One is
illustrated us~ng a CMS EXEC file, as shown in the following PREFIX
EXEC:
*
SLNAME = SCONCAT Sl
LISTFILE SLNAME SCRIPT
(EXEC
EXEC CMS SSTACK
SLOOP -END SREADFLAG EQ CONSOLE
SREAD VARS SHAME STYPE SMOD
SSUFFIX = SSUBSTR SHAME 3 6
SHEWNAM = SCONCAT S2 SSUFFIX
RENAME SNAME &TYPE SMOD SNEWNAM &TYPE &MOD
&IF SRETCODE EQ 0 SSKIP
STYPE FILE SNAME &TYPE NOT RENAMED
-END
*
This EXEC procedure is invoked with two arguments, each two characters
in length, which indicate old and new prefixes for filenames. The EXEC
renames files with a filetype of SCRIPT that have the first prefix,
changing only the prefix in the filename.
The LISTFILE command, invoked
EXEC file in the format:
with the EXEC
option, creates
aces
Sl S2 filename SCRIPT mode
When the EXEC is invoked with the line:
EXEC Cl-1S SSTACK
the argument &STACK is substituted for the variable symbol S l i n each
line in the CMS EXEC. The execution of the CMS EXEC effectively stacks,
in the console stack, the complete file identifications of the files
listed:
SSTACK filename SCRIPT mode
SSTACK filename SCRIPT mode
These stacked lines are read back into the EXEC, one at a time, and the
tokens "filename", "SCRIPT", and "mode" are substituted for the variable
symbols &NAME, STYPE, and SMOD.
Using the &SUBSTR and SCONCAT built-in functions, the new name for
each file is constructed, and the RENAME command is issued to rename the
files.
294
IBM VM/370 CMS User's Guide
(
For example, if you invoke the EXEC procedure with the line:
prefix ab xy
all SCRIPT files that have filenames beginning with the characters AE
are renamed so that the first two characters of the filename are XY. A
sample execution summary of this EXEC is illustrated under "Debugging
EXEC Procedures" in "Section 16. Refining Your EXEC Procedures."
You can create a data file, containing fixed-length records, using a
fi1etype of EXEC. TO stack these data lines in the console stack, you
can enter them following an &EEGSTACK
(or &EEGSTACK ALL)
contre1
statement. For example, the file DATA EXEC is as follows:
&EEGSTACK
HARRY 10/12/48
PATTI 1/18/49
DAVID 5/20/70
KATHY 8/6/43
!ARVIN 2/28/50
The file EDAY EXEC contains:
)
&CONTROL ERROR
EXEC DATA
&IF &READFLAG EQ CONSOLE &GOTO -NO
&READ VARS &NAME &DATE
&IF &NA!E NE &1 &SKIP -2
-FOUND
&IF .&1 EQ • &EIIT
&TYPE &1 'S BIRTHDAY IS &DATE
CONWAIT
DESBUF
&EXIT
-NO &TYPE &1 NOT IN LIST
&EXIT
When the BDAY EXEC is invoked, it expects an argument that is a first
naae. The function of the EXEC is to display the birthday of the
specified person. A sample execution of this EXEC might be:
bday kathy
KATHY'S BIRTHDAY IS 8/6/43
R;
BDAY EXEC first executes the DATA EXEC, which stacks names and dates
in the console stack. Then, BDAY EXEC reads one line at a time from the
stack, assigning the variable names &NAKE and &DATE to the tokens on
each line. It compares &NAME with the argument read as &1. When it finds
a match, it displays the message indicating the date, and clears the
console stack after waiting for terminal output to finish.
Note that the file DATA EXEC begins with an &BEGSTACK control
statement, but contains no &END statement. The stack is terminated by
the end of the EXEC file.
"Writing Data Files" describes a technique
you might use to add new names and birth dates to the DATA EXEC file.
)
Section 14. Building EXEC Procedures
295
You can build a CMS file in your virtual card punch using the SPUNCH and
SBEGPUNCH control statements. Depending on the spooling characteristics
of your virtual punch, the file that you build may be sent to another
user's card reader, or to your own virtual card reader.
When you read
the file with the CMS READCARD command, the spool reader file becomes a
CMS disk file.
The following example illustrates how you might use your card punch
and reader to update a CMS file by adding records to the end of it. The
file being updated is the DATA EXEC, which is the input file for the
BDAY EXEC, shown in the exaaple in "Stacking Data Files."
You could
create a separate EXEC to perform the update, but this example shows how
you might modify the BDAY EXEC to perform the addition function
(ellipses indicate the body of the EXEC, which is unchanged):
SCONTROL ERROR
&IF &1 EQ ADD &GOTO -ADDNAME
&EXIT
-ADDNAME
&TYPE ENTER FIRST NAME AND DATE IN FORM MM/DD/YY
&READ VARS &NAME &DATE
SIF .&NAME = . SSKIP 3
&PUNCH &NAME &DATE
&TYPE ENTER NEXT NAME OR NULL LINE:
&SKIP -4
CP SPOOL PUNCH TO
CP CLOSE PUNCH
READCARD NEW NAMES
COPYFILE NEW NAMES A DATA EXEC A (APPEND
&IF &RETCODE = 0 &SKIP 2
&TYPE ERROR CREATING FILE
&EIIT &RETCODE
ERASE NEW NAMES
*
When BDAY EXEC is invoked with the keyword AtD, you are prompted to
enter lines to be added to the data file.
Each line that you enter is
punched to the card punch. When you enter a null line, indicating that
you have finished entering lines, the CP commands SPOOL and CLOSE direct
the spool file to your card reader and close the punch.
The file is read in as the file NEW NAMES, which is appended to the
file DATA EXEC using the COPYFILE co.mand with the APPEND option. The
file NEW NAMES is erased and the EXEC terminates processing.
When you punch lines in your virtual punch, the lines are not released
as a CP spool file until the punch is closed. Since the EXEC processor
does not close the virtual punch when it terminates processing, you must
issue the CLOSE command to release the file. You can do this in the EXEC
with the command line:
CP CLOSE PUNCH
or from the CMS environment after the EXEC has finished. If you use the
CLOSE command in the EXEC, you must preface it with CP.
296
IBM VM/370 CMS User's Guide
(
The CMS PUNCH command, which you can use in an EXEC to punch an
entire CMS file, does close the punch after punching a file.
Therefore,
if you want to create a punch file using a combination of SPUNCH control
statements and PUNCH commands, you must spool your punch using the CONT
option, so that a close request does not affect the file:
CP SPOOL PUNCH TO * CONT
SPUNCH FIRST FILE
SPUNCH
PUNCH FILE1 TEST ( NOH EADER
SPUNCH SECOND FILE
SPUNCH
PUNCH FILE2 TEST ( NOH EADER
CP SPOOL PUNCH CLOSE NOCONT
The preceding example punches title lines introducing the files punched
with the CMS PUNCH command. The null SPUNCH statements punch blank
lines. The PUNCH command is issued with the NOBEADER option, so that a
read control card is not punched.
You can also use an EXEC procedure to punch a job to send to the CMS
batch facility for processing. The batch facility, and an example of
using an EXEC to punch a job to it, are described in "Section 12. Using
the CMS Batch Facility."
All lines punched
to the virtual card
punch are fixed-length,
80-character records.
When you use the SPUNCH control statement in a
fixed-length EXEC file, EXEC scans only the first 72 columns of the
EXEC.
If you want to punch a word that contains more than eight characters,
you must
use the SBEGPUNCH
control statement, which
also, in
fixed-length files, causes EXEC to punch data in columns 1 through 80.
)
Section 14. Building EXEC Procedures
297
c
298
IBM VM/370 eMS User's Guide
Section 15. Using EXECs with CMS Commands
Whenever you create an EXEC file you are, for all practical purposes,
creating a new CMS command. When you enter a command line in the CBS
environment, CMS searches for an. EXEC file with the specified fi1ena.e
before searching for a MODULE file or CMS command. You can place the
names of your EXEC files in a synonym table and assign minimu.
truncation values for the synonyms, just as you can for CMS command
names.
While many of your EXEC procedures may be very simple, others may be
very long and complicated, and perform many of the housekeeping
functions perfor.ed by CMS co •• ands,
such as syntax checking, error
message generation, and so on.
Monitoring CMS Command Execution
Many, or most, of your EXEC procedures may contain sequences of CMS
commands that you want to execute. If your EXEC procedure contains no
EXEC control statements, each command line is displayed and then the
command is executed.
If an error occurred, the CMS error message is
displayed, followed by a return code in the format:
+++ R(nnnnn) •• +
where nnnnn is the nonzero return code from the CMS command.
If the
command is not a valid CMS command, or the command function for SET or
QUERY is invalid and the implicit CP function is in effect, the return
code is a -3:
+++ R(-0003)
+++
You may also receive this error return when you use a CP command without
prefacing it with the CP command. If you enter an unknown CP command
following "CPU, you receive a return code of 1.
If a command completes successfully, no
ret~rn
code is displayed.
If you do not want to see the command lines displayed before
execution, nor return codes following execution, you can use the EXEC
control statement:
SCOBTROL OFF
Or, if you want to see only the command lines that produced errors, and
the resultant return codes, you can specify:
SCONTROL ERROR
Regardless of these settings of the SCORTROL statement, CMS error
messages are displayed, as long as the value of SREADFLAG is RT, and the
terminal is displaying output.
If you issue the LISTFILE, STATE, ERASE, or RENAME commands in an
EXEC procedure, and you do not want to see the error message FILE NOT
FOUND displayed, you can use the statement:
)
SCONTROL NOMSG
to suppress the display of these particular messages.
Section 15. Using EXECs with CMS Commands
299
You can request that particular timing inforaation be
during an EXEC's execution. If you want to display the time
which each com.and executes, you can specify:
displayed
of day at
&CONTROL TIME
Then, as each com.and
for example:
line is displayed, it is prefaced
with the time;
SCONTROL CMS TIME
QUERY BLIP
executes as follows:
10:34:16 QUERY BLIP
BLIP
= *
If you wish to see, following the execution of each CMS command,
specific CPU timing information, such as the long form of the ready
message, you can use the &TIME control statement. For example:
&TIKE ON
QUERY BLIP
QUERY FILEDEF
might execute as:
QUERY BLIP
BLIP
= OFF
T=0.01/0.04 10:44:21
QUERY FILEDEF
NO USER DEFINED FILEDEF'S IN EFFECT
T=0.01/0.04 10:45:26
Handling Error Returns from CMSCommands
In many cases, you want to execute a com.and only if previous commands
were su'ccessful.
For example, you would not want to execute a PRINT
command to print a file if you had been unable to access the disk on
which the file resided. There are two methods, using EXEC procedures,
that allOW you to monitor and control what happens following the
execution of CKS commands. One method uses the EXEC control statement
&ERROR to transfer control when an error occurs; the other tests the
special variable &RETCODE upon co.pletion of a CMS command to determine
whether that particular command completed successfully.
USING THE SERROR CONTROL STATEKENT
When a CMS command is executed within an EXEC, a return code is passed
to the EXEC interpreter, indicating whether or not the command completed
successfully. If the return code is nonzero, EXEC then activates the
SERROR control statement currently in effect.
For example, if the
following statement is included at the beginning of an EXEC file:
SERROR SEXIT
then, whenever a eMS command (or user program) completes with a nonzero
return code, the &EXIT statement in the &ERROR statement is executed,
and the EXEC terminates processing. You might use a similar statement
300
IBM VK/370 CMS User's Guide
(
in your EXECs to ensure that they
in the event of an error.
do not attempt to continue processing
An &ERROR control statement can specify any executable statement. It
may transfer control to another portion of the EXEC, or it many be a
single statement that executes before control is returned to the next
statement in the EXEC. For exaaFle:
&ERROR &GOTO -EXIT
transfers control
statement:
to the label
-EXIT, in case
of any CMS
error.
The
&ERROR &TYPE CMS ERROR
results in the display of the message "CBS ERROR" before returning
control to the statement following the command that caused the error.
If you do not have an &ERROR control statement in an EXEC, or if you
specify &ERROR with no operands, EXEC takes no special action when·a CMS
command returns with an error return code. Specifying &ERROR with no
operands is the same as specifying:
&ERROR &CONTINUE
Since an &ERROR control statement remains in effect for the remainder
of the EXEC execution, or until another &ERROR control statement is
encountered, you may use &ERROR &CONTINUE to restore default processing.
USING THE &RETCODE SPECIAL VARIABLE
An error return from a CMS command, in addition to calling an &ERRCR
control statement, also places the return code value in the EXEC special
variable &RETCODE.
Following the execution of any CMS command in an
EXEC procedure, you can test whether or not the command completed
without error. For example:
TYPE ALPHA FILE A
&IF &RETCODE ~= 0 &EXIT
TYPE BETA FILE A
&IF &RETCODE ~= 0 &EXIT
Note that the value of &RETCODE is
CMS command.
modified after the execution of each
The value of &RETCODE is affected by your own programs. If you
execute a program in your EXEC using the LOAD and START
(or FETCH and
START) commands, or if you execute a MODULE file, then the &RETCODE
special variable contains Whatever value was in general register 15 when
the program exited.
If you are nesting EXEC procedures, then &RETCODE
contains the value passed from the &EXIT statement of the nested EXEC.
)
You can use the value of the return code, ,as well, to analyze the
extent or the cause of the error and to set up an error analysis routine
accordingly.
For example, suppose you want to set up an analysis
routine to identify return codes 1 through 11 and to exit from the EXEC
when the return code is greater than 11.
When a return code is
identified, control is passed to a corresponding routine that attempts
to correct the error.
You could set up such an analysis routine as
follows:
Section 15. Using EXECs with CMS Commands
301
-ERRANAL
SCNT = 0
&LOOP 2 SCNT EO 12
SIF &RETCODE EO SCNT SGOTO -FIXSCNT
. SCNT = SCNT + 1
-FIXO SGOTO -ALLOK
-FIX1
SGOTO -ALLOK
-FIX2
SGOTO -ALLOK
-FIX11
-ALLOK
When the value of the SCNT variable equals the return code value in
SRETCODE, the branch to the corresponding -FIX routine is taken. Each
corrective routine performs different actions, depending on its code,
and finishes at the routine labeled-ALLOK.
You can, in some cases, determine the cause of a CMS command error
and attempt to correct it in your EXEC. To do this, you must know the
return codes issued by VM/370 commands. See !~Ll1~ ~I§!~. ~~§§gg~§ for a
discussion of the return codes for Vft/370 commands. In addition, the
error messages and corresponding return codes are listed under the
command descriptions for each CMS command in the !~Ll1~ ~1I~ £.Q.I!!g.n~ g.n~
11~£f:.Q .R~!~f:.!Hl£~ •
As an example, all CMS commands that search for files issue a return
code of 28 .when a file is not found. If you want to test for a
file-nat-found condition in your EXEC, you might use statements similar
to the following:
SCONTROL OFF NOMSG
TYPE HELP MEMO A
SIF &RETCODE
28 &GOTO -NOFILE
=
Tailoring eMS Comma.nds for Your Own Use
You can create EXEC procedures that simplify or extend the use of a
particular CMS command. Depending on your applications, you can modify
the CMS command language to suit your needs. You can create EXEC files
that have the same names as CMS commands, and, since CftS locates EXEC
files before MODULE files, the EXEC is found first.
For example, the
COPYFILE command, when used to copy CftS disk files, requires six
operands. If you change only the filename when you copy files, you could
create a COPY EXEC as follows:
302
IBM VM/370 CftS User's Guide
c
;
&CONTROL OFF
&IF &INDEX ~= 3 &SKIP 2
COPYFILE &1 &2 = &3 &2 =
&EXIT
COPYFILE &1 &2 &3 &4 &5 &6 &7 &8 &9 &10 &11 &12 &13 &14 &15
If you always invoke the COPYFILE command using the truncation COPY,
EXEC processes the command line for you, and if you have entered the
three arguments, EXEC formats the COPYFILE command for you. If any
other number of arguments is entered, the COPY FILE command is invoked
with all the arguments as entered.
CREATING YOUR OWN DEFAULT FILETYPES
If you use special filetypes for particular aPFlications and they are
not among those that the CMS editor supplies default settings for, but
do require special editor settings, you can create an EXEC to invoke the
editor. The EXEC can check for particular filetypes, and if it finds
thea, stack the appropriate EDIT subcommands. If you name this EXEC
procedure E EXEC, then you can bypass it by using a longer form of the
EDIT command. The following is a sample E EXEC:
)
)
&CONTROL OFF
&IF &INDEX GT 1 &SKIP 2
EDIT &1 SCRIPT
&EXIT
&IF &2 EQ TABLE &GOTO -TABLE
&IF &2 EQ CHART &GOTO -CHART
&IF &2 EQ EXEC &GOTO -EX
&IF &2 EQ SYSIN &GOTO -SYSIN
-NORM EDIT &1 &2 &3 &4 &5 &6
&EIIT
-TABLE &BEGSTACK
IMAGE ON
TABS 1 10 20
CASE M
&END
EDIT &1 &2 &3 (LRECL 20
&EXIT
-CHART &BEGSTACK
CASE M
IMAGE ON
&END
EDIT &1 &2 &3
&EXIT
-EX
EDIT &1 &2 &3 (LRECL 130
&EXIT
-SYSIN &BEGSTACK
TABS 1 10 16 31 36 41 46 69 72 80
SERIAL ON
TRUNC 71
VERIFY 72
&END
EDIT &1 &2 &3
&EXIT
This EXEC defines special characteristics for filetypes CHART, TABLE,
and SYSIN, and defaults an EXEC file to 130-character records. If only
one argument is entered, it is assumed to be the filename of a SCRIPT
file.
Since the editor is invoked from within the EXEC, control returns
to EXEC after you use the FILE or QUIT subcommands during the edit
session. You must use the &EXIT control statement so that the EXEC does
not continue processing, and execute the next EDIT command in the file.
Section 15. Using EXECs with CMS Commands
303
(
304
IBM VM/370 eMS User's Guide
Section 16. Refining Your EXEC Procedures
This section provides supplemen,:tary information for writing complex EXEC
procedures. Although the EXEC interpreter resembles, in some aspects, a
high-level programming language, you do not need to be a programmer to
write EXECs.
Some of the techniques suggested here, for example, on
annotating and writing error messages, are common programming practices,
which help make programs self-documenting and easier to read and to use.
Annotating EXEC Procedures
Lines in an EXEC file that begin with an asterisk (*) are commentary and
are treated as comments by the EXEC interpreter. You can use
statements to annotate your EXECs. If you write EXECs frequently, you
may find it convenient to include a standard comment at the beginning of
each EXEC, indicating its function and the date it was written, for
example:
*
*
*
*
EXEC TO HELP CONVERT LISTING FILES
INTO SCRIPT FILES
J. BEAN 10/18/75
You can also use single asterisks or null lines to provide spacing
between lines in an EXEC file to make examining the file easier.
In an EXEC, you cannot place comments on the same line with an
executable statement. If you want to annotate a particular statement or
group of statements, you must place the comments either above or below
the lines you are annotating.
A good practice to use, when writing EXECs, is to set them up to
respond to a ?
(question mark)
entered as the sole argument.
For
example, an EXEC named FSORT might contain:
SCONTROL OFF
SIF SINDEX = 1 SIF S1
=?
SGOTO -TELL
-TELL SBEGTYPE
CORRECT FORM IS ' FSORT USERID '
PRINTS AN ALPHABETIC LISTING OF ALL FILES ON THE SPECIFIED
USER'S DISK. IF A VIRTUAL ADDRESS (VAtDR) IS NOT
SPECIFIED, THE USER'S 191 IS THE DEFAULT.
SEND
You may also wish to anticipate the situation -in which a user might
enter an EXEC name with no arguments for an EXEC that requires
arguments:
)
Section 16. Refining Your EXEC Procedures
305
SIF SINDEX = 0 SGOTO -HELP
SlF SINDEX
1 SIF Sl
? SGOTO -TELL
=
=
SEXIT
-HELP SBEGTYPE
CORRECT FORM IS • COPY OLDFN OLDFT NEWFN '
TYPE • COpy ? ' FOR MORE INFO
SEND
SEXIT
-TELL SBEGTYPE
CORRECT FORM IS ' COpy OLDFN OLDFT NEWFN '
USES COPYFILE COMMAND TO CHANGE ONLY THE FILENAME
SEND
SEXIT
This type of annotating is especi~lly useful
your EXECs with other users.
if you share your disks or
Error Situations
It is good practice, when writing EXECs, to anticipate error situations
and to provide meaningful error or information messages to describe the
error when it occurs. The following error situations, and suggestions
for handling them, have already been discussed:
•
Errors in invoking the EXEC~ either
arguments, or with invalid arguments.
14. Building EXEC procedures.")
•
Errors in CMS command processing that can be detected with an SERROR
control statement or with the SRETCODE special variable.
(See
"Handling Error Returns from CMS Commands" in "Section 15. Using
EXECs With CMS Commands.")
with an improper number of
(See "Arguments" in "Section
Many different kinds of errors may also occur, in the processing of
your EXEC control statements. EXEC process1ng errors, such as an attempt
to branch
to a
nonexistent label or
an invalid
syntax, are
"unrecoverable" errors.
These errors always terminate EXEC processing
and return your virtual machine to the CMS environment or to the calling
EXEC procedure or program. The error messages produced by EXEC, and the
associated return codes, are described in the !~L11~ ~I21~! ~~§§!g~.
WRITING ERROR MESSAGES
One way to make your EXECs more readable, especially if they are long
EXECs, is to group all of your error messages in one place, probably at
the end of the EXEC file.
You may also wish to number your messages and
associate the message numbe~ with a label number and a return code. For
example:
(
306
IBM VM/370 CMS User's Guide
&IF &CT
&IF &CT
>
<
100 &GOTO -ERR100
0 &GOTO -ERR200
&IF &RETCODE EQ 28 &GOTO -ERR300
-ERR100
&TIPE COUNT TOO HIGH
&EIIT 100
-ERR200
&TIPE COUNT TOO LOW
&EIIT 200
-ERR300
&TIPE &1 &2 BOT ON DISK
&EIIT 300
'ct.
There is a facility, available in the EIEC processor, which allows you
to write error messages that use the standard VM/370 message format,
with an identification code and message number, as well as message text.
When you use the &EMSG or &BEGEMSG control statement, the EXEC
interpreter scans the first token and checks to see if the seventh (and
last character)
is an I, E, or W, representing information, error, or
warning messages, respectively. If so, then the message is displayed
according to the CP EMSG setting (ON, OFF, CODE, or TEXT). For example,
if you have the statement:
&EMSG ERROR1E BAD ARGUMENT ' &f '
the ERROR1E is considered the code portion of the message and
ARGUMENT is the text. If you have issued the CP command:
BiD
cp set emsg text
when this &EMSG statement is executed it may display:
BAD ARGUMENT ' PRNIT '
where PRNIT is the argument that is invalid.
When you use &EMSG (or &BEGEMSG, which allows you to display error
messages of unscanned data), the code portion of the message is prefixed
with the characters DMS, when displayed. For example:
&BEGEMSG
ERROR2E INCOMPATIBLE ARGUMENTS
&END
displays when the EMSG setting is ON:
DMSERROR2E INCOMPATIBLE ARGUMENTS
)
You should use the &BEGEMSG control statement when you want to display
lines that have tokens longer than eight characters; however, no
variable substitution is performed.
Section 16. Refining Your EIEC Procedures
307
Debugging EXEC Procedures
If you have difficulty getting an EXEC procedure to execute properly, or
if you are modifying an existing EXEC and wish to test it, there are a
couple of simple techniques that you can use that may save you time.
One is to place the &CONTROL ALL control statement at the top of your
EXEC file.
When &CONTROL ALL is in effect, all the EXEC control
statements are displayed before they execute, as well as the CftS command
lines. One of the advantages of usihg this method is that the line is
displayed after it is scanned, so that you can see the results of symbol
and variable substitution.
"Stacking EXEC Files" in "Section 14. Building EXEC procedures"
described a PREFIX EXEC, which chang.s the prefixes of groups of files.
If the EXEC had an &CONTROL ALL statement, it might execute as follows:
prefix pt ag
&CONTROL ALL
&LNAME = &CONCAT PT
LISTFILE PT* SCRIPT
EXEC
EXEC CMS SSTACK
&LOOP -END &READFLA EO CONSOLE
LOOP UNTIL:
STAC K
EQ
&READ VARS SNAME &TIPE &MOD
&SUFFIX = &SUBSTR PTA 3 6
&NEWNAM = SCONCAT AG A
RENAME PTA SCRIPT A1 AGA SCRIP~
SIF 0 EQ 0 SSKIP
&SKIP
LOOP UNTIL:
STAC K
EQ
SREAD VARS SNAME &TIPE &MOD
&SUFFIX = SSUBSTR PTB 3 6
SNEWNAM = SCONCAT AG B
RENAME PTB SCRIPT A1 AGB SCRIPT
&IF 0 EQ 0 SSKIP
SSKIP
LOOP UNTIL:
CONS OLE EQ
*
* (
CONS
A1
CONS
A1
CONS
R;
lou can see from this execution summary that the files named PTA SCRIPT
and PTB SCRIPT are renamed to AGA SCRIPT and AGB SCRIPT.
Notice that
the &LOOP statement results in a special LOOP UNTIL statement in the
execution summary, which indicates the condition under which the loop
executes.
USING CMS SUBSET
When you are using the CMS editor to create or modify an EXEC procedure,
you can test the EXEC in the eMS subset environment, as long as the EXEC
does not issue any CMS commands that are invalid in CMS subset.
Before entering CMS subset with the CMS subcommand, you must issue
the SAVE subcommand to write the current version of the EXEC onto disk;
then, in CMS subset, execute the EXEC. For exaaple:
308
IBM VM/370 CMS User's Guide
\
edit new exec
NEW FILE:
EDIT:
input
INPUT:
Sa = Sl + S2 + S3
Stype answer is Sa
EDIT:
save
EDIT:
cms
CMS SUBSET
new 34 56 899
ANSWER IS 989
R;
return
EDIT:
quit
R;
If the EXEC does not execute properly, you can return to the edit
environment using the RETURN command, modify the EXEC, reissue the SAVE
and CMS subcomaands, and attempt to execute the EXEC again.
SUMMARY OF EXEC INTERPRETER LOGIC
The following information is provided for those who have an interest in
how the EXEC interpreter works. It may help you in debugging your EXEC
procedures if you have some idea of how processing is done by EXEC.
When an EXEC file is invoked for execution, the EXEC interpreter
examines each statement and analyzes it, according to the following
sequence:
)
If the first nonblank character of the
counted and ignored.
2.
Null lines, except as a
counted and ignored.
3.
The line is
tokens.
4.
All EXEC special variables, and then all user variables, except for
those that appear as the target of an assignment statement, are
substituted.
6.
All blank tokens (resulting from
symbols) are discarded.
7.
If the first nonblank character is a hyphen
(-), indicating
label, the next token is considered the first token.
8.
If the first logical token does not begin with an ampersand (S),
the line is passed to CMS for execution. The return code from CMS
is placed in the special variable SRETCODE.
9.
If the first logical token begins
interprets the statement.
10.
reponse to
line is an
*,
1.
the line is
an SREAD statement,
scanned, and nonblank character strings
the
are placed in
substitution of
with
an
are also
undefined
ampersand (S)
a
EXEC
If a statement is syntactically invalid and can be made valid by
adding a token of blanks at the end, EXEC adds blanks, for example:
Section 16. Refining Your EXEC Procedures
309
&BLANK =
&TIPE
&LOOP 3 &X NE
All of the above are valid EXEC control statements.
11.
EXEC executes the statement. If no error is encountered, control
passes to the next logical statement. If an error is encountered,
EXEC terminates processing.
\
310
IBM VM/370 CMS User's Guide
Section 17. Writing Edit Macros
If you have a good knowledge of the CMS EXEC facilities and an
understanding of the CMS editor, you may wish to write edit macros.
An
edit macro is simply an EXEC file that contains a sequence of EDIT
subcommands. Edit macros can only be invoked frem the edit environment.
An edit macro may contain a simple sequence of EDIT subcommands, or its
execution may be dependent on arguments you enter when you invoke it.
This section provides information on creating edit macros, suggestions
on how to manipulate the console stack, and some examples of macros that
you can create and use.
Creating Edit Macro Files
An edit macro aust have a filename beginning with a dollar sign ($) and
a filetype of EXEC.
Rules for file format, scanning and token
substitution are the same as for all other EXEC files. A macro file may
contain:
•
•
•
)
EDIT subcommands
EXEC control statements
CMS commands that are valid in CMS subset
When you create an edit macro that accepts arguments, you should be
sure to check the validity of the arguments, and issue appropriate error
messages. If you are writing an edit macro to expect arguments, you must
keep in mind that the macro command line is scanned, and that any data
items you enter are padded or truncated into eight-character tokens.
Tokens are always translated to uppercase letters.
You should annotate all of your macro files, and provide a response
to a question mark (1) entered as the sole argument (as described under
"Annotating EXEC Procedures" in "Section
16. Refining Your EXEC
Procedures").
How Edit Macros Work
Since an edit macro is an EXEC file,_ it is actually executed by the EXEC
interpreter, and not by the editor.
The EXEC interpreter can only
execute EXEC control statements and CMS commands. The only way to issue
an EDIT subcommand from an EXEC file is to stack the subcommand in the
console stack, so that when the editor is invoked, or receives control,
it reads the subcommand(s) from the console stack before accepting input
lines from the terminal. For example:
&STACK CASE M
&STACK RECFM V
EDIT &1 CHART A1
When the EDIT command is invoked from this EXEC, the editor
subcommands from the stack and executes them.
)
reads the
To execute these same subcommands from an edit macro file, you must
use the same technique;
that is, you must place the subcommands.in the
console stack, for example:
section 17. Writing Edit Macros
311
&BEGSTACK
CASE M
RECFM V
&END
&EXIT
If this were an EXEC file named $VARY, you
edit environment as follows:
might execute it
from the
edit test file
NEW FILE.
EDIT:
$vary
Stacked subco.mands are executed only when the EXEC completes its
execution, either by reaching the end of the file, or by processing an
&EXIT statement.
When you stack EDIT subcommands, you can use the &STACK and &BEGSTACK
control statements. If you are stacking a subcommand that uses a
variable expression, you must use the SSTACK control statement, rather
than the &BEGSTACK control statement. The following EXEC, naaed $T,
displays a variable number of lines and then restores the current line
pointer to the position it was in when the EXEC was invoked:
SCONTROL OFF
&IF &INDEX EO 0 &GOTO -ERR
&CHECK = &DATATYPE &1
&IF &CHECK HE NUK &GOTO -ERR
&STACK TYPE Sl
SUP = &1 - 1
&STACK UP SUP
&EXIT
-ERR STYPE CORRECT FORK IS < $T H
&EXIT 1
>
This edit macro uses the built-in function
numeric operand is entered.
SDATATYPE to check
that a
CKS commands in an edit macro are executed as they are read by the
EXEC interpreter, just as they would if the EXEC were invoked in the CftS
environment. You could create a $TYPE edit macro, for example, that
would allow you to display a file from the edit environment:
&CONTROL OFF
TYPE S1 &2 &3 &4 &5 &6 &7
Or you might create a
another file:
$STATE EXEC that
would verify the
existence of
SCONTROL OFF
STATE &1 &2 &3
In both of these examples, the macro file invokes the CKS command.
Macros like these can eliminate having to enter CftS subset environment
to execute one or two simple CMS commands. You must be careful, though,
not to execute any CMS co.mand that uses the storage occupied by the
editor. Only commands that are valid in CftS subset are valid in an edit
macro.
(
312
IBM VM/370 CMS User's Guide
THE CONSOLE STACK
When you write an edit macro, you want to be sure that there are no EDIT
subcommands in the stack that could interfere with the execution of the
subcommands stacked by the macro file.
Your macro should check whether
there are any lines in the stack, and if there are, it should clear thea
from the stack. For example, you might use the lines:
&IF &READFLAG EQ CONSOLE &SKIP 2
DESBUF
&TYPE STACKED LINES CLEARED BY &0
The message "STACKED LINES CLEARED BY macro name" is issued by the edit
macros distributed with the VM/310 system~ You may also want to use
this convention in your macros, to alert a user that the console stack
has been cleared.
When an edit macro is invoked and the current line pointer is positioned
at the top of the file or at the end of the file, the editor stacks a
token in the console stack. If the line pointer is at the top of the
file, the token stacked is "TOF"; if the line pointer is at the end of
the file the token stacked is "EOF".
If you write an edit macro that
does not check the status of the console stack, and the .acro is invoked
from the top or the end of the file, you receive the message:
1EDIT: TOF
or:
1EDIT: EOF
The editor does not recognize these tokens as valid subcommands.
You may want to use these tokens to test whether the EXEC is invoked
from the top or end of the file. If you want to clear these tokens in
case the macro has been invoked from the top or end of the file, you
might use the statement:
&IF &READFLAG EQ STACK &READ ARGS
which clears the token from the stack.
If you do not want to clear the console stack when you execute an edit
macro, you can stack all of the subcoamands using the LIFO (last-in
first-out) operand of the &STACK and &BEGSTACK control statements. For
example, suppose $FORMAT is the name of the following edit macro:
&BEGSTACK LIFO
TABSET 3 10 11
TRUNC 11
PRESERVE
SEND
)
Section 11. Writing Edit Macros
313
When this edit macro is executed, the subcommands are placed in the
console stack in front of any eXisting lines •. For example, if this macro
were invoked:
!format#input
the subcommands would execute in the following order: PRESERVE, TRUNC,
TABSET, INPUT.
If
the subcommands were stacked
FIFO (first-in
first-out), the default, the INPUT subcomman~ would be the first to
execute (since it is the first command in the stack) and the remaining
subcommands would be read into the file as input lines.
If an EXEC processing error occurs during the execution of an edit
macro, the editor clears the console stack and issues the "STACKED LINES
CLEARED" message. An EXEC processing error is one that causes the error
message DMSEXT072E:
ERROR IN EXEC FILE filename, LINE nnnn - description
These errors cause the EXEC interpreter to terminate processing. Any
stacked subcommands are cleared before the editor regains control, so
that none of the subcommands are executed, and the file remains
unchanged.
You should also ensure that any error handling routines in your edit
macros clear the stack if an error occurs. Otherwise, the editor may
begin reading invalid data lines from the stack and attempt to execute
them as EDIT subcommands.
You should not interrupt the execution of an edit macro by using the
Attention or Enter key, and then entering a command or data line.
Results are unpredictable, and you may inadvertently place unwanted
lines in the stack.
If your edit macro contains a CMS command that is invalid in the CftS
subset environment, you receive a return code of -2.
The
varies
at the
editor
maximum number of lines that you can stack in an edit macro
according to the amount of free storage that is available to CftS
time of the stacking request. If you stack too many lines, the
terminates abnormally.
Notes on Using EDIT Subcommands
You can use any EDIT subcommand in a macro file, and there is one
special subcommand whose use only has meaning in a macro: the STACK
subcommand. For the most part, there is not any difference between
executing an EDIT subcomaandfrom the edit environment, or from an EXEC
edit macro. You do have to remember, however, that if you want a
variable symbol on a subcommand line, you . must stack that subcommand
using the SSTACK control statement rather than following an SBEGSTACK
control statement.
Listed below are some notes on using various EDIT subcommands in your
macro files. You may find these notes useful when you design your own
macros.
(
314
IBM VM/370 CMS User's Guide
!1!I!!, !!~ R~a!Q!~: Often, you may want to create an edit
macro that alters the characteristics of a file
(format, tab settings,
and so on). To ensure that the original characteristics are retained
when the macro has finished executing, you can stack the PRESERVE
subcommand as the first subcommand in the stack, and the RESTORE
subcoamand as the last subcommand in the stack:
gjESlj!~,
SBEGSTACK
PRESERVE
CASE M
I A lowercase line
RESTORE
SEND
The PRESERVE and RESTORE subcommands save and reinitialize the settings
for the CASE, FMODE, FNAME, IMAGE, LINEMODE, LONG, RECFM, SERIAL, SHORT,
TABSET, TRUNC, VERIFY, and ZONE subcommands.
In an edit macro that issues many subcommands that display lines in
response to CHANGE or LOCATE subcommands, you may want to turn the
verification setting to OFF to suppress displays during the execution of
the edit macro:
SBEGSTACK
PRESERVE
VERIFY OFF
RESTORE
SEND
You would particularly want to turn verification off for a macro that
executes in a loop or that issues a global request. If you want a line
or series of lines displayed, you can use the TYPE subcommand.
If you have verification set off in an edit macro, then when you
execute it you ~ay not receive any indication that the edit macro
completed execution. The keyboard unlocks to accept your next EDIT
subcommand from the terminal. To indicate that the macro is finished,
you can stack, as the last subcommand in the procedure, a TYPE
subcommand, to display the current line. Or, if you write an edit macro
that terminates when an end-of-file condition occurs the EOF: message
issued by the editor may indicate the completion of the macro.
!!PU£, R!f~!£~: To change from edit mode to input mode in an edit macro,
you can use the INPUT and REPLACE subcommands. In a fixed-length EXEC
file, you must stack these subcommands using the SSTACK control
statement:
SSTACK INPUT
-- or -SSTACK REPLACE
If you use either of these subcommands following an &BEGSTACK control
statement, the subcommand line is padded with blanks to the line length
and the result is a line of blanks inserted into the file.
,
In a variable-length EXEC file, lines are not padded with blanks, so
the INPUT and REPLACE subcommands with no data line execute the same
following an SBEGSTACK control statement as they do when stacked with
the SSTACK control statement.
Section 17. Writing Edit Macros
315
~Qing I£Q~
l~Eut HQgg!Q
Edit Mode: To stack a null line in an edit
macro, to cause the editor to-Ieave- input mode, you must use the SSTACK
control statement with no other tokens, as follows:
SSTACK
Q~~Bll~,
~Q~!~!: If
you want to use the CHANGE, DSTRING, or
LOCATE subcommands in an EXEC, you must take into account that when you
stack any of these subcommands using the SSTACK control statement, all
of the character strings on the line are truncated or padded to eight
characters. Also, if you want to use a variable value for a character
string, you are limited to eight characters, all uppercase.
~]AN~~,
For example, if a macro is used to locate a character string and
delete the line on which it appears, the LOCATE subcommand has a
variable symbol:
SSTACK LOCATE /Sl
SSTACK DEL
IMAGE, TABSET, OVERLAY: The TABSET and OVERLAY subcommands allow you to
stops for records in a file and to overlay
character strings in particular positions. For example, the following
macro places a vertical bar in columns 1, 15, 40, and 60 for all records
in the file from the current line to the end of the file:
se~-margIns-and--column
SBEGSTACK
PRESERVE
IMAGE ON
TABSET 1 15 40 60
REPEAT *
o 1->1->1->1
RESTORE
SEND
In the above example, the "->" symbol represents a tab character
(X'OS'). To create this EXEC, you can either issue the EDIT subcommand:
image off
and use the Tab key (or equivalent) on your terminal vhen you enter the
line, or jou can enter some other character and use the ALTER subcommand
to alter that character to a X'OS'.
If you want to overlay only one character string in a particular
position in a file, you can use the TABSET subcommand to set that column
position as the left margin, and then use the OVERLAY subcommand, as
follows:
SCONTROL OFF
&BEGSTACK
PRESERVE
VERIFY OFF
TRUNC *
TABS 72
&END
&STACK REPEAT &1
SBEGSTACK
OVERLAY C
RESTORE
SEND
316
IBM VM/370 eMS User's Guide
If you name this file $CONT EXEC, and if you invoke it with the line:
$cont 3
then the OVERLAY subcoamand is executed on three successive
place the continuation character "C" in column 72.
lines, to
THE STACK SUBCOMMAND
The STACK subcommand allows you to stack up to 25 lines from a file in
the console stack. The lines are not deleted from the file, but the line
pointer is moved to point to the last line stacked.
You can also use the STACK subcommand to stack EDIT subcommands. You
might do this if there were subcommands that you wanted to place in the
stack to execute after all the subcommands stacked by the EXEC had
executed.
These techniques are used in the two edit macros that are distributed
with the VM/370 system: $MOVE and $DUP.
If you want to examine these
files for examples of how to use the STACK subcommand, you can display
the files by entering, from the CMS environment:
type $aove exec
type $dup exec
An additional use
Edit Macro."
*
*
of the STACK subcommand is shown
in "An Annotated
)
Section 17. Writing Edit Macros
317
An Annotated Edit Macro
The edit macro shown below, $DOUBLE, can be used to double ~pace a CftS
file. Regardless of where the current line pointer is, a blank line is
inserted in the file following every existing line.
The statements in
the edit macro are separated into groups; the number to the left of a
statement or group of statements indicates an explanatory note. The
numbers are not part of the EIEC file.
1
&CONTROL OFF
2
&IF &INDEI = 1 &IF &1 = 1 &GOTO -TELL
3
&IF &INDEI = 1 &IF &1 = TWO &GOTO -LOOP
4
&IF &INDEX NE
o
5
&IF &READFLAG
EO STACK &READ VARS &GARB
6
&STACK
&STACK PRESERVE
&STACK VERIFY OFF
7
&STACK BOTTOM
&STACK I IXXXXXXI
SSTACK TOP
&GOTO -TELL
Notes:
-l---The &CONTROL statement suppresses the display of CMS commands, in
this case, the DESBUF command.
The first SIF checks that there is only one operand passed in the
2
$DOUBLE command.
The second SIF checks whether $DOUBLE has been
invoked with a question mark (1). If both SIFs are true, control
is passed to the statement at the label -TELL. STYPE control
statements at -TELL explains what the macro does.
The second SIF statement checks whether $DOUBLE has been invoked
3
with the argument TWO, which indicates that the macro has executed
itself, so the subcommands that initialize the file are stacked
only once.
There are three ways to properly invoke this edit macro: with a 1,
4
with the argument TWO, or with no arguments. The third SIF
statement checks for the (no arguments)
condition; if the macro is
invoked any other way, control is passed to the label -TELL, which
explains the macro usage.
5
The SREADFLAG special variable is checked. If $DOUBLE is executed
at the top or at the end of the file, the token TOF or EOF is in
the stack, and should be read out.
A null line is placed in the console stack for loop control (see
6
Note 9.)
The PRESERVE and VERIFY subcommands are stacked so that
the editor does not display each line in the file as it executes
the stacked subcommands.
7
The BOTTOM, INPUT, and TOP subcommands initialize the file by
placing a marker at the bottom of the file, and then positioning
the current line pointer at the top of th~ file.
318
IBM VM/310 CMS User's Guide
8
-LOOP
&BEGSTACK
NEXT
STACK 1
INPUT
&END
9
&READ ARGS
&IF .&1 = • &SKIP
&IF &1 EQ XXXXXXXX &SKIP 2
10
-ENDLOOP &STACK $DOUBLE TWO
11
&EXIT
12
DESBUF
&BEGSTACK
UP 2
DEL 3
TYPE
RESTORE
&END
&EXIT
13
-TELL
&IF &READFLAG EQ STACK &READ VARS
&BEGTYPE
CORRECT FORM IS: $DOUBLE
THIS EXEC DOUBLE SPACES A FILE BY INSERTING
A BLANK LINE FOLLOWING EVERY LINE IN THE FILE
EXCEPT THE LAST.
&END
8
9
10
11
12
13
The NEXT, STACK, and INPUT subcommands are going to be repeated for
each line in the file~ The INPUT subcommand with no data line
stacks a null line. Note that in order for $DOUBLE to execute this
subcommand properly, $DOUBLE EXEC must have fixed-length records.
Each line is stacked, with the STACK subcommand; this stacked line
is Checked in the read loop (Note 9).
When the stacked line is
equal to the marker, XXXXXXXX, it indicates that the end of the
file has been reached.
These lines check for an end of file, which occurs when the line
containing the marker is read. The first time this loop is
executed, the stack contains the null line (statement/6), so the
check for the marker is skipped.
The last subcommand stacked is $DOUBLE TWO, which re-invokes
$DOUBLE, but causes it to skip the first sequence of subcommands.
The &EXIT statement causes an exit from $IOUBLE, so that all the
EDIT subcommand stacked thus far are executed.
When the marker is read in, the EXEC clears the stack, moves the
current line pointer to point to the null line added above the
marker, and deletes that line, the marker, and the null line that
was inserted following the marker. The RESTORE subcommand restores
editor settings.
This edit macro is self-documenting. If $DOUBLE is invoked with a
question mark, or invoked with an argument, information regarding
its proper use is displayed.
)
section 17. Writing Edit Macros
319
User-Written Edit Macros
You can create the edit macros shown below, for your own use in CMS.
You may want to refer to them as examples when you are learning to write
your own macros. The macros have not been formally tested by IBM; they
are presented for your convenience only.
$MACROS
The $MACROS edit macro verifies the existence of and describes the usage
of edit macros. If you enter:
$macros
it lists the filenames of all the
If you enter:
edit macros on your
accessed disks.
$macros name1 name2
it displays, for each valid macro name entered, the macro format and
usage.
(This macro assumes that all macros have been designed to
respond to a 1 request.)
The format of the $M1CROS edit macro
instruction is:
$MACROS
filename
[filenamel [filename2 [filenamen]]]
is the filename(s)
of macro files whose usage is to be
displayed. If filename is omitted, the filenames of all
available macro files are listed.
To create $MACROS, enter:
edit $macros exec
and in input mode, enter the following:
(
320
IBM VM/370 CMS User's Guide
&CONTROL OFF
&IF &INDEX EQ 1 &IF &1 EQ ? &GOTO -TELL
&IF &INDEX GT 0 &GOTO -PARTIC
*&BEGTYPE
ALL
EXEC FILES STARTING WITH A DOLLAR-SIGN ARE AS FOLLOWS.
FOR INFORMATION ON ONE OR MORE OF THEM, TYPE:
SMACROS FILENAME1
&END
LISTF S* EXEC * (NOHEADER FNAME)
&EXIT
*
-PARTIC &TRIP = 0
&INDEXl = 0
*&LOOP
-ENDLOOP &INDEX
&INDEX1
&INDEX1 + 1
&SUB = &SUBSTR &&INDEXl 1 1
&IF &SUB EQ S &GOTO -STATIT
&TYPE &&INDEXl IS INVALID
&TRIP = 1
&GOTO -ENDLOOP
-STATIT STATE &&INDEX1 EXEC *
&IF &RETCODE EQ 0 &GOTO -CALLIT
&TYPE &&INDEX1 NOT FOUND
&TRIP = 1
&GOTO -ENDLOOP
-CALLIT EXEC &&INDEX1 ?
-ENDLOOP
*&EXIT
*
-TELL
=
&TRIP
&BEGTYPE
'SMACROS' HANDLES THE 'SMACROS' REQUEST.
TYPE 'SMACROS' ALONE FOR MORE INFORMATION.
&END
&EXIT
SMARK
The $MARK edit macro inserts from one to six characters, starting with
the current line and in the column specified, for a specified nURber of
records.
If there is data already in the columns specified, it is
overlayed. If you enter:
$mark
the macro places an
you enter:
asterisk (*) in column 72 of
the current line.
If
$mark 10 30 abc
the macro places the string ABC beginning in column 30 in each of ten
records, beginning with the current record. The format of the $MARK
edit macro instruction is:
r-----.------------------------------------------------.-------------------,I
$MARK
)
r
r
r
",
L
L
L
.J.J.J
I n I col I char III
I 1 I 1~ I
* III
I
I
I
J
section 17. Writing Edit Macros
321
n
indicates the number of consecutive lines, starting with the
record currently being pointed to, that will be marked. If n is
not specified, 1 is assumed, and the other default values are
also assumed.
col
indicates the starting column in each record where the character
string is to be inserted. The default is coluan 72.
char
indicates from one to six characters to be
record. The default is an asterisk (*).
inserted in
each
To create $MARK, enter:
edit $mark exec
and in input mode, enter the following:
&CONTROL OFF
&IF &INDEX EQ 1 &IF &1 EQ ? &GOTO -TELL
&IF &INDEX GT 3 &GOTO -BADPARM
&INDEXl = 1
&IP &INDEX GT 0 &INDEX1 = &1
&IF &INDEXl LT 0 &GOTO -BADPARM
&INDEX2 = 72
&IF &INDEX GT 1 &INDEX2 = &2
&IF &INDEX2 LT 0 &GOTO -BADPARM
&IF &INDEX2 GT 133 &GOTO -BADPARM
&CHAR = *
&IF &INDEX EQ 3 &CHAR = &3
&LEN3 = &LENGTH &CHAR
&IF &LEN3 GT 6 &GOTO -BADPARM
&STACK LIFO RESTORE
&STACK LIFO OVERLAY &CHAR
&STACK LIFO REPEAT &INDEX1
&STACK LIFO TABS &INDEX2
&BEGSTACK LIFO
IMAGE ON
TRUNC *
VERIFY OFF
LONG
PRESERVE
&END
&EXIT
*
-BADPARM &BEGTYPE
INVALID $MARK OPERANDS
&END
&EXIT 1
*
-TELL
&BEGTYPE
CORRECT FORM IS: $MARK
PUTS A 1-6 CHARACTER STRING IN COLUMN 'COL' OF 'N' LINES, STARTING
WITH THE CURRENT LINE. THE NEW CURRENT LINE IS THE LAST LINE
MARKED. DEFAULTS ARE: N=1; COL=72; CHAR=*.
&END
&EXIT
(
322
IBM VM/370 CMS User's Guide
$POINT
The $POINT edit macro positions the current line pointer at the
specified line number. The line numbers must be in columns 13 through 80
and padded with zeros. For exaaple, if you enter:
$point 800
the current line pointer is positioned at the line that has the serial
nu.ber 00000800 in columns 13 through 80. The format of the $POINT
macro instruction is:
$POINT
key
1
key
I
is a one- to eight-character line number. If the specified key
is less than eight characters long, it is padded with leading
zeros.
To create $POINT, enter:
edit $point exec
and in input mode, enter the following:
SCONTROL OFF
SIF SINDEX EQ 0 SGOTO -TELL
SIF SINDEX EQ 1 SIF &1 EQ 1 SGOTO -TELL
&IF SINDEX GT 1 &GOTO -BADPARM
&KEYL = &LENGTH &1
SINDEX1 = 8 - &KEYL
&Z = &SUBSTR 00000000 1 &INDEll
&1 = SCONCAT SZ S1
SSTACK LIFO RESTORE
SSTACK LIFO FIND S1
SBEGSTACK LIFO
TOP
TABS 13
IMAGE ON
LONG
PRESERVE
&END
SEXIT
*
-BADPARM
SBEGTYPE ALL
INVALID $POINT OPERANDS
SEND
SEXIT 1
*
-TELL
SBEGTYPE ALL
CORRECT FORM IS: SPOINT KEY
IF 'KEY' CONTAINS LESS THAN 8 CHARACTERS, IT IS PADDED WITH LEADIBG
ZEROS. THE FILE IS THEN SEARCHED FROM THE TOP FOR 'KEY' IN COLUMNS
73-80.
SEND
SEXIT
)
Section 17. Writing Edit Macros
323
$COL
The $COL edit macro inserts, after the current record in the file, a
line containing column numbers (that is, 1, 6, 11, ••• , 76). The format
of the $COL macro instruction is:
,
,I
$COL
No operands are used with $COL.
usage is explained.
If any arguments are entered, the macro
To create $COL, enter:
edit $co1 exec
and in input mode, enter the following:
SCONTROL OFF
SIF SIND EX NE 0 SGOTO -TELL
SSTACK LIFO RESTORE
SSTACK LIFO
&BEGSTACK LIFO ALL
1
6 11 16 21 26 31 36
&END
SSTACK LIFO INPUT
SBEGSTACK LIFO
TRUNC
VERIFY OFF
LONG
PRESERVE
SEND
&EXIT
41
46
51
56
61
66
*
*
-TELL &BEGTYPE
CORRECT FORM IS: $COL
INSERTS A LINE INTO THE FILE SHOWING COLUMN NUMBERS.
&END
&EXIT
324
IBM VM/370 CMS User's Guide
71
76
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-118
Part 4. Learning to Use the HELP Facility
The CMS HELP facility enables the user to interactively display co.mand
and message information on a terminal.
The command and message
information is contained in files either supplied by IBM or created by
the user.
"Section 18. HELP File Naaing Conventions and Creation" describes the
naming conventions for HELP facility files and techniques that the HELP
facility provides for creating user HELP description files.
Part 4. Learning to Use the HELP Facility
324.1
March 30, 1919
324.2
IBM VM/310 eMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-118
Section 18. HELP File Naming Conventions
and Creation
The HELP facility enables the user to:
I.
I
Extend the command and message description files IBM
additional description files of the user's choice
I •
I
Produce a formatted terminal display by using the
when creating the HELP description file
provides with
HELP format words
Naming Conventions
When you extend the HELP text files IBM provides, you
following naming conventions for the HELP files:
must use
the
I •
I
The filename for components, commands, subcommands, or EXECs aust be
the exact full name of the component, command, subcommand, or EXEC.
I •
The filename for messages has the form xxxnnnt where:
xxx
is the component code
messages).
See !~Ll1Q
component code prefixes.
prefix (for
§y£!~~
example, DMS for
for a list of
~~~£gg~£
CMS
the
nnn
is the message number.
t
is the message type code (for example, E for error messages in
CMS).
For example, the filename for the CMS message "NO FILENAME SPECIFIED"
would be DMS001E.
I •
I
I
I
The filetype for components, commands, or EXECs is 'HELPxxxx' where
xxxx identifies the system associated with this component, command,
or EXEC.
For example, the filetype for a CMS command would be
'HELPCMS' •
I.
I
I
The filetype for subcommands is 'HELPxxxx' where xxxx identifies the
command name associated with this subcommand; for example, DEBU for
the DEBUG command.
I •
The filetype for messages is 'HELPMSG'.
I •
I
The filetype for a list
function is 'HELPMENU'.
of all
supported
The following examples illustrate the
interface with the HELP command.
ACCESS
E~IT
CHANGE
DMS186W
CMS
HELPCMS
HELPCMS
HELPEDIT
HELPMSG
HELPMENU
commands
for a
given
naming conventions required to
A CMS command description
A CMS command description
An EDIT subcommand description
A CMS message description
A list of the CMS command and/or EXEC names
supported by the HELP facility
Section 18. HELP File Naming Conventions and Creation
324.3
Pg.' qf
.GC20-1819~2
Rev March 30, 1919 by Supp. SD23-9024-1 for 5748-XX8
HELP File Creation
Users creating additional files for the HELP facility
own file or use the format words the HELP facility
format ~ords do the following:
can format their
supports. These
I •
Draw boxes to enclose tables, illustrations or text
I •
Place comments within a file
I •
I
Indicate that certain input lines are to be included in the formatted
output only under certain conditions
I.
I
Cause concatenation of input lines
of output
I •
Indent only the next input line the specified number of spaces
I •
Indent a series of input lines the specified number of spaces
I.
I
Indent the specifie~ number of
series of input lines
I.
Insert blank lines between output lines
I.
Change the final output representation of any input character
and left- and right-justification
spaces all but
The HELP format words are su.marized in Figure
and examples of their use follow.
324.4
IBK VM/310 CMS User's·Guide
the first line
23.1.
in a
Descriptions
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for S748-XX8
Format WOI:d
• BX
(BOX)
Operand Format
V1 V2
••• Vn
OFF
Function
I Break I
Draws horizontal and
vertical lines around
subsequent output text,
in blank columns.
Yes
Default Value
Draws a
horizontal
line.
• CM
(COMMENT)
Comments
Places comments in a file
for future reference.
No
• CS
(CONDITIONAL
SECTION)
nON/OFF
Allows conditional
inclusion of input in
the formatted output.
No
• FO
(FORMAT
-MODE)
ON/OFF
Causes concatenation of
input lines, and left and
right justification of
output.
Yes
On
.IL (INDENT LINES)
nl+nl-n
Indents only the next
line the specified
number of spaces.
Yes
o
• IN (INDENT)
n\+nl-n
Specifies the numbeI:
of spaces subsequent
text is to be indented.
Yes
o
• OF (OFFSET)
nl+nl-n
Provides a technique
for indenting all but the
first line of a section.
Yes
o
.SP
(SP ACE)
n
specifies the numbeI: of
blank lines to be inserted
befoI:e the next output line.
Yes
• TR (TRANSLATE)
s t
specifies the final output
representation of any input
character.
No
Figure 23.1.
HELP Format Word Summary
Section 18. HELP File Naming Conventions and Creation
324.5
Pg. of GC2o-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-118
ENCLOSING TEXT
(.~X
FORMAT WORD)
The HELP facility can insert vertical and horizontal lines in the
formatted output to enclose text, illustrations, or tables. You use the
.BI format word to specify when you want the horizontal lines to appear
and in which coluans the vertical lines should appear.
The .BX
text:
format word
is used
in three
steps to
completely enclose
The first time you issue the .BX format word, specify the columns
in which you want the vertical lines to appear~ For example:
1.
.bx 1 10 20 30
results in the following output:
,
Note that this first occurrence of the .EI format word causes a
horizontal line to appear between the first and last column you
specified.
2.
After the first issuance of .BX, begin entering the text that is to
be enclosed. As HELP formats these lines, vertical lines are
placed in the columns that you specified on .EX. However, if a
column already has a data character in it, it is not overlaid with
the vertical line.
Note that whenever you want just a horizontal line to appear (for
example, to separate lines in a table), enter the .BX format work
without operands. For example:
.bx
results in the following output:
3.
When you
issue:
have finished entering the
text that is to
be enclosed,
.bx off
to cause another horizontal line to appear and to prevent any more
vertical lines from appearing. This output is:
L--------I
The following example illustrates this technique of enclosing text •
• fo off
.bx 1 10 50
.in 2
.of 8
Ite. 1
Put Item1 text here.
The second line can be written here •
• bx
.of 8
Item 2
Then put Item2 text here •
• bx off
324.6
IB~
V8/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-X18
When these input lines are processed, the result is:
,
I
I
I Item1
I
•
I Item2
IPut Item1 text here.
IThe second line can be written her«.
I
IThen put Item2 text here.
L
,
I
,
I
I
This example shows how you can change the vertical structure several
times i~ succession. The control words:
.bx
.sp
.bx
.sp
.bx
.sp
.bx
.sp
.bx
.sp
.hx
10 20
5 25
10 20
5 25
10 20
off
result in:
r
I
L--~--
__________
~
,I
PLACING COMMENTS IN HELP FILES (.CM FORMAT WORD)
In addition to text and format words, HELP files
Comments are useful for:
can contain comments.
I •
I
I
Tracking files.
You can include comments that give your name, the
date and reason you created a file,
and a future date at which the
file may be erased.
I •
I
I
Documenting formats. If you use a special format in a HELP file that
may be accessed by other peoFle, you may want to place notes within
the file explaining how to update the file.
I •
I
Place-holders. If a file is incomplete, you may want to put comments
in the file where information should be added later.
You can place comments in a HELP file with the .CM format word:
.cm Created 12/21/75
.cm Updated 3/3/76
HELP ignores all .CM format words when processing.
Section 18. HELP File Naming Conventions and Creation
324.7
Pg. of GC20-1819-2 Rev March 30, 1979 by,Supp. SD23-9024-1 for 5748-118
CONDITIONAL DISPLAY OF TEXT (.CS FORMAT WORD)
You can indicate to HELP that certain sections ot the file are to be
displayed as output only if the appropriate HELP command options are
specified. These options are PARM, FORM, DESC, and ALL.
(See VML11~
CMS Command and Macro Reference for information on the use of these
options:)-- --- ----- ---------
In order for HELP command processing to display the appropriate
information, you must use the .CS format word in the following manner:
.cs 1 on
(text for DESC option)
.cs 1 off
.cs 2 on
(text for FORM option)
.cs 2 off
.cs 3 on
(text for PARM option)
.cs 3 off
USE OF FORMAT MODE (.FO FORMAT WORD)
Format-mode processing means that the HELP facility displays the output
lines
without
breaks,
unless
specifically
requested,
and
right-justified. You may not want this type of formatting in all cases;
you may want certain output to appear exactly as it appears in the HELP
file.
For this, use the .FO format word to turn off for.at-mode
processing as follows:
.fo off
When you want to resume format-mode processing, enter:
.fo on
Format-mode processing is the default.
INDENTING TEXT (.IN AND .IL FORMAT WORDS)
When you are creating documents, you may want to set off paragraphs or
portions of text by indenting them. This often improves the readability
by emphasizing certain text. You can cause paragraphs to be indented
using the .IN format word. For eXample, the lines:
This line is not indented.
~in 5
This line is indented.
result in:
This line is not indented.
This line is indented.
The .IN format word causes a break so that text accu.ulated before
the .IN format word is processed and displayed, then the next text is
processed.
324.8
IBM VM/370 CMS User's Guide
Pg~
of GC20-1819-2 Rev March 30, 1979 by Supp. 'SD23-9024-1 for 5748-XX8
The .IN format word effectively sets a new left margin for output
text so that when you want text indented you do not have to enter blanks
in front of the input lines (as you would for normal typing). HELP
continues to concatenate and justify input text lines that begin to
column 1, but displays the output indented the number of space's you
specify.
Here's another example:
These few lines of text
are formatted
with enough words
.in 5
so that you can
see how HELP's formatting
process
.in +3
continues and may
'. in -6
even be reversed, by using a
negative value.
These lines may result in:
These few lines of
text are
formatted
with enough words
so that you can
see how HELP's
formatting
process
continues and
may
even be reversed,
by using a negative
value.
In this example, the first' • IN format word shifts output to the right
five spaces so that text begins in column 6. The second .IN format vord
requests that the current indentation incr~ase by three spaces sotbe
left margin is now in column 9. When you supply a negative value with
the. IN format wor,d, the margin is shifted to the left.
To cancel an indentation that is in
value, or you can use the format word:
effect, you can use
a negative
.in 0
Because 0 is the default value, you need not specify it when you want to
restore the left margin to column 1. You can specify simply:
.in
When you want to indent only a single line of text (that is, the next
output line), use the .IL format word. For exam~le:
This line begins in column 1 •
• in 5
This line begins in column 6,
which is now the left margin •
• il -3
This line is shifted 3 spaces
to the left of the current margin.
Section 18. HELP File Naming Conventions, and Creation
324.9
Pg. of GC20-1819-2Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
.il 3
This line is shifted 3 spaces to
the right of the curr~nt margin.
Help processes these lines as follows:
This line begins in column 1.
This
line
begins in
column 6, which is now
the left margin.
This
line is shifted 3
spaces to the left of
the current margin.
This line is shifted
3 spaces to the right
of the current margin.
Because the .IL format word causes a break in text, you may find it
useful to indicate the beginning of a new paragraph. For example:
.il 3
This line begins a paragraph •
• il 3
This line begins another.
These lines result in:
This line begins
a paragraph.
This line begins
another.
USE OF OFFSETS (.OF FORMAT WORD)
In HELP formatting, an offset differs from an indentation in that
offsets do not affect the first line immediately following the format
word; the second and subsequent input lines are indented the specified
number of characters.
This is useful, for example, when formatting
numbered lists where text is blocked to the right of the number.
When a .OF format word is processed, the next text line is printed at
the current left margin and subsequent lines (until the next .OF or .IN
format word) are offset the specified number of characters.
For
example, the lines:
.of 5
-----This line begins
a 5-character offset •
• of 5
-----This is another line offset
5 characters •
• sp
.in 5
An indent changes the left.
margin and cancels the offset •
• of 3
---This paragraph begins
at the new left margin •
• of 3
---Here's one.ore line.
324~10
I~B'V~/370
CBS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1919 by Supp. SD23-9024-1 for 5748-118
result in:
-----This line begins a
5-character offset.
-----This is another line
offset 5 characters.
An indent
changes
the left aargin and
cancels the offset.
---This
paragraph
begins at the new
left margin.
---Here's one more
line.
An offset can be canceled with the format word •
• of 0
This format word causes a break; subsequent text is printed at the
current left margin, that is, whatever the indention is (0, if no .IN
format word is in effect).
A~y INDENT format
word cancels a current offset and resets the left
aarg1n. If you specify a positive or negative increment with the INDEIT
format word and an offset is in effect, the offset is canceled and the
new left margin is computed from the current indent value.
The .IL (INDENT-LINE) format word uses the current margin (the indent
value plus the offset value) when computing the margin for the next
line.
To achieve a format that has sever~l levels of offsetting,
combine the .IN and .OF format words.
you can
When you use blank space following the item indicator (for exaaple,
the number in a numbered list), HELP may add extra blanks when it
justifies the line; if so, the first line may not be aligned with the
remainder of the offset item.
SPACING BETWEEN LINES OF TEXT (.SP FORMAT WORD)
If you do not want an input line to be concatenated with the line above
it, you must cause a break. To cause a break in a HELP file, begin a
line with one or more blank characters (by using the space bar on your
terminal keyboard).
When HELP reads an input line that begins with a
blank character, the formatting process is interrupted; all of the text
that has" accumulated for the current line is displayed as is, even if
more words would have fit on the line; the next input line begins a new
output line.
To create paragraphs in text, then, all you have to do is to enter
spaces at the beginning of each line that is to begin a new paragraph.
For example, the input lines:
The quick brown
fox
came over to greet the lazy poodle.
But the poodle was frightened
and ran away.
Section 18. HELP File Naming Conventions and creation
324.11
Pg. of GC20-1819:-2 Rev ftarch 30, 1979 by Supp. SD23-902lt-1 for 57lt8-XX8
may be displayed by HELP as:
The quick brown
came over to greet
lazy poodle.
But the poodle
frightened
and
away.
fox
the
was
ran
If you want to place blank lines between lines of text, you can press
the space bar at least once on a line that has no other text, then press
the Return or Enter key.
Instead of entering
Thus the input lines:
a blank line, you
can use the .SP
format word.
The quick brown fox came over to
greet the lazy poodle •
• sp
But the poodle Was frightened
and ran away.
are formatted as follows by HELP:
The quick brown fox
came over to greet the
lazy poodle.
poodle
But the
frightened
and
away.
The .SP format
indicating how many
example:
was
ran
word allows you to enter a numeric parameter
spaces you want to leave on the text output. For
.sp 5
indicates that you want to leave five lines of space in the text output.
You can use multiple spaces when you want a heading or a title to stand
out, for example the lines:
A Love Story
.sp 3
The quick brown fox
was eager
to meet the pretty poodle.
will result in:
A Love Story
The quick brown fox
was eager to meet the
pretty poodle.
324.12
IBft Vft/370 CftS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. 5D23-9024-1 for 5148-X18
TRANSLATING OUTPUT CHARACTERS (.TR FORMAT WORD)
After HELP has formatted an output line but before it displays that
line, HELP may translate any of the characters in that line to a
different character representation.
You use the .TR format word to
request that this translation be done. For example, to request that all
blanks (x'40') in the file be displayed as question marks, enter:
.tr 40 1
To stop the translation of the question mark as a blank, enter:
~tr
1 1
Note that when the .TR format word is
translation of all characters is stopped.
used
without operands,
Section 18. HELP File Naming Conventions and Creation
the
324.13
!arch.30, 1919
324.14
IB! V!/370 C!S User's Guide
Appendixes
This publication contains the following appendixes:
A. Summary of CMS Commands
B. Sumaary of CP Commands
C. Considerations for 3270 Display Terminal Users
D. Sample TerminaL Sessions
)
Appendixes
325
(
~
(
326
IBM VM/370 eMS User's Guide
"arch 30, 1919
Appendix A: Summary of CMS Commands
ligures 24 and 25 contain alphabetical lists of the CMS commands and the
functions performed by each. Figure 24 list's' those commands that -are
available for general use; Figure 25 lists the commands used by syste.
programmers and system support personn~l whd' are responsible for
generating, aaintaining, and updating V"/310. Unless otherwise noted,
C"S commands are described in '!ftLl1Q ~ft~ £21!!~ng ~ng ~~£!:2 !!~!~!:~!!£~.
~2de
l1!g.!!i.!!.9
Indicates that this command invokes a
available froll IB! for a lic~nse f~e.
EREP
Indicates that this command is described in .!!L31.Q .Q1I SE,R g.!!.9
I!!Q! i!£2!ging ~~ig~.
Further details on the operands used
by this command are contained in Q~L!'§ In!i!QnJ!!~!s! !H~.£2!gin.9
l.9i!i.D.9 g.!!g f!i.D!ing (I!!f)' f!.Qg!~!·' '
IPCS
Indicates that this command is a part of the Interactive
Problem Control System (IPCS) and is described in !AL~10 !R~~
!!§!!~§ Guig!·
DOS PP
Op Gd
Indicates
that
this
command
is
DOS Program
described
in
prcduct,
the
.!~L~l.Q
Q]~!§!2~§ ~~ig~·
OS PP
Indicates that this command invokes an
available fro. IB! for a license fee.
SCRIPT
Indicates that this command invokes a text processor that is
an IB" Installed User Program, available from IBM for a
license fee.
SPG
Indicates that this command is
f!2g!g!I!!~§ ~Yig~·
SYSGEN
Indicates that this command
flg.!!.!!illg §ng ~§!~! Q~n~!§!!Q!!
OS program
product,
described in the !J1L31.Q
~I§!~!
is
VftLl1Q
described
in
the
~uig!.
In addition to the commands listed in Figure 24 and 25, there are
seven commands called Immediate commands that 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 i.mediately. The Immediate commands are:
•
•
•
•
•
•
•
HB
HO
HT
HI
RO
RT
SO
-
Halt batch execution
Halt tracing
Halt typing
Halt execution
Resume tracing
Resume typing
Suspend tracing
Appendix A: Summary of C"SCo •• ands
321
Pg. of GC20-1819-2 Rev March 30, 1979 bySupp. SD23-9024-1 for 5748-118
I
. :;,;'
Code
ICo.mand
I
I ACCESS
I
I
I·
Il~SERV
I
I
IIdentify direct access space to a CMS virtual
1 machine, create extensions and relate the disk
I space to a logical directory.
1
I
I
I
lI
I·
"1 , c . : '
As'semb~e:assemb~.~r ianguage so~'r'ce code.
IASSEMBLE· I
I
IASSGN
I
I·
ICMSBATCH
I
COBOL
COMPARE
CONVERT
I
I
I
Assign or unassign a CMS/DOS system or programmer
logical unit for a virtual I/O device.
,I
Invoke the eMS batch fac~l.i ty.
I
I
Compile QS ANS Version 4 or OS/VS COBOL source
code.
I.OS PP .
T
I
ICompare records in CMS
di~k
files.
I
OSPP
I Convert fr.ee form FORTRAN statements to fixed form.;
I
COPYFILE
ICopy CMS disk files according to specifications.
I
CP
IEnter CP commands from the CMS environment.
CPEREP
I
EREP
IFormats and edits system error records for output.
I
I Perform bac:'kup, rest()re, and copy operations for
I disks.
DDR
",
DEJ3UG
I '
.,
,
tEnter
DISK
,
D~BUG
I Perform
flubcommand
environ~ent,
debug mode.
disk-to-card and card-to-disk operations
·1 for CMS files.
I
DLBL
IDefine a DOS filename or VSAM ddname and relate
J that name to a disk file.
I
"
'
DOSLIB
DOSPLI
I·
"
.. Link-e'dit CMS text decks or object modules from a
DOS/VS relocatable library and place them in
executable form in\ a CMS/DOS phase l i b r a r y . ,
DOS PP
1DSERV
I
I
•
Figure 24.
...'
I Delete, compact, 'or list inf'ormation about the
I phases of a CMS/DOS phase library.
DOSLKED
328
'. '
or
f
I,.,
.,':
I I n,vok,e :.&ccess method services utili tyfuDctions to
Icrea te.,'al t~r,: list, copy, delete, 'import,
l'expo'rt .~VS~M 'cfl:talogsand' da tasets.; . .
,I
Display information contained in the DOS/VSE core
image, relocatable, source, procedure, and
transient directories.
,
,
,
CMS Command Summary (Part 1 of 4)
IBM V,,/370 CMS
I
Compile DOS PL/I source code under CMS/DOS.
User's~uide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-118
Command
ICode
Usage
EDIT
'Invoke the CMS editor to create or .odif! a disk
file.
ERASE
Delete CMS disk files.
ESERV
Display, punch or print an edited (co.pressed)
macro from a DOS/VSE source statement library
(E sublibrary).
EXEC
Execute special procedures made up of frequently
used sequences of commands.
FCOBOL
DOS PP
Compile DOS/VS COBOL source code under CftS/DOS.
FETCH
Fetch a CMS/DOS or DOS/VSE executable phase.
FILEDEF
Define an OS ddnaae and relate that ddname to any
device supported by CftS.
FORMAT
Prepare disks in
block £ormat.
800~,
1024-, 2048-, or 4096-byte
.
FORTGI
OS PP
Compile FORTRAN source code using the G1 coapiler.
FORTHX
OS PP
Compile FORTRAN source code using the
compiler.
GENDIRT
Fill in auxiliary module directories.
'GENMOD
Generate nonrelocatable CMS files (!ODULE files).
GLOBAL
GOFORT
B-extended
Identify specific CMS libraries to be searched for
macros, copy files, missing subroutines, or DOS
executable phases.
OS PP
Compile FORTRAN source code and execute the program
using the FORTRAN Code and Go compiler.
HELP
Display information regarding CP, C!S, or usersupplied commands and messages.
INCLUDE
Bring additional TEXT files into storage and
establish linkages.
LABELDEF
specify standard BDR1 and EOF1 tape label description information for CMS, C!S/DOS, and as
simulation.
LISTDS
List information about data sets and space
allocation on OS, DOS, and VSAM disks.
LISTFILE
List information about CMS disk files.
LISTIO
Display information concerning CMS/DOS system and
programmer logical units.
LOAD
Bring TEXT files into storage for execution.
LOADMOD
MACLIB
Bring a single MODULE file into storage.
create or modify CMS macro libraries.
Figure 24.
CMS Command Summary (Part 2 of 4)
Appendix A: Summary of C!S Commands
329
Pg~
of GC20-1819-2 Rev March 30, 1979 by Supp::- SD23-9024-1 for 5748-XX8
t
I
Command
ICode
Usage
I
-------------------------------------~--------~~------------~----I
I
I
Move data from one device to another device of the I
same or a different type.
I
I
Change the DOS COBOL compiler (FCOBOL) o.ptions that.1
are in effect. for the current. terminal session.
I
MODMAP
Display the load map of a KODULE file.
MOVEFILE
OPTION
PLIC
as PP
Compile and execute PL/~ s6urce code using the
PL/I Checkout Compile~.
PLICR
as PP
Execute the PL/I object code generated by the OS
PL/I Checkout Compiler~
PLIOPT
OS PP
Compile PL/I source code using the OS PL/I
Optimizing Compiler.
PRINT
Spool a specified CMS ,file tcthe virtual printer.
PSERV
Copy a procedure from the DOS/VSE procedure library
onto a CMS disk, displa¥ the procedure at the
I
terminal, or spool the procedure to the virtual
I
punch or printer.
I
I
Spool a copy of a CMS file to ,the virtual punch.
I
I
Request information about a CMS virtual machine.
I
I
Read data from spooled card input device.
I
I
Make a disk and its directory inaccessible to a CMSI
virtual machine.
I
PUNCH
QUERY
READCARD
RELEASE
RENAME
Change the name of a CMS -file or files.
RSERV
Copy a DOS/VSE relocatable module onto a CMS disk,
display it at the terminal, or spool a copy to
the virtual punch or printer.
I
I
IRUN
I
I
ISCRIPT
I
I
ISET
I
IInitiate series ,of functions to be performed on a
I source, MODULE, TEXT, or EXEC file.
I
SCRIPT IFormat and print documen~s according to embedded
I SCRIPT control words in the document file.
I
IEstablish, set, or reset CMS virtual machine
I characteristics.
Figure 24.
CMS Command Summary (Part 3 of 4)
t
J
330
IBM YM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev Karch 30, 1979 by Supp. SD23-9024-1 for 5748-118
Co •• and
ICode
Usage
SORT
Arrange a specified file in ascending order
according to sort fields in the data records.
SSERV
Copy a DOS/VS! source statement book onto a CftS
disk, display it at the terminal, or spool a copy
to the virtual punch or printer.
START
Begin execution of programs ~reviously loaded (aS
and CftS) or fetched (CMS/DOS).
STATE
Verify the existence of a CftS disk file.
STATEW
Verify a file on a read/write CftS disk.
SYCTRACE
Record information about supervisor calls.
SYNONYK
Invoke a table containing synonyms you have created
for CftS and user-written co.mands.
TAPE
Pe~for.
TAPEKAC
create CKS KACLIB libraries directly from an
IEHMOVE-created partitioned data set on tape.
TAPPDS
Load as partitioned data set (PDS) files or card
image files from tape to disk.
tape-to-disk and disk-to-tape operations
for CftS files, position tapes, ana display or
write VOL1 labels.
TESTCOB
OS PP
Invoke the as COBOL Interactive Debug Progra ••
TESTFORT
as PP
Invoke the FORTRAN Interactive Debug program.
TXTLIB
Generate and modify text libraries.
TYPE
Display all or part of a CftS file at the terminal.
UPDATE
Kake changes in a program source file as defined
by control cards in a control file.
YSAPL
as PP
Invoke VS APL interface in CMS.
YSBASIC
as PP
Compile and execute VS BASIC progra.s under Cfts.
VSBUTIL
as PP
Convert BASIC 1.2 data files to VS BASIC for.at.
Figure 24.
CMS Command summary (Part 4 of 4)
Appendix A: Summary of CMS Co •• anas
331
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp'. SD23-9024-1 for 5748-XX8
Command
I Code
Usage
ASM3705
SYSGEN , Assemble 370x source code.
ASMGEND
SYSGEN
Regenerate the VM/370 assembler command modules.
CMSGEND
SYSGEN
Generate a new CMS disk-res:ident module from
updated TEXT files.
CMSXGEN
SYSGEN
Generate the CMSSEG discontiguous saved segment.
CPEREP
EREP
Formats and edits system error records for output.
DIRECT
Op Gd
Set up VM/370 directory entries.
DOSGEN
SYSGEN
Load and save the CMSDOS shared segment.
DUMPS CAN
IPCS
Provide interactive analysis of CP abend dumps.
GEN3705
SYSGEN
Generate an EXEC file that assembles and link-edits
the 370x control program.
GENERATE
SYSGEN
Update VM/370 or the VM/370 directory, or generate
a new standalone copy of a service program.
LKED
SYSGEN
Link-edit the 370x control program.
NCPDUMP
OP Gd,
SPG
Process CP spool reader files created by 370x
dumping operations.
PRB
IPCS
Update IPCS problem status.
PROB
IPCS
Enter a problem report in IPCS.
SAVENCP
SYSGEN, Read 370x control program load into virtual
SPG
storage and save an image on a CP-owned disk.
SETKEY
SPG
Assign storage protect keys to storage assigned to
named systems.
STAT
IPCS
Display the status of reported system problems.
VMFBLD
SYSGEN
Generate and/or update VM/370 using the PLC tape.
VMFDOS
SYSGEN
Create CMS files for DOS modules from DOS library
distribution tape or SISIN tape.
VMFDUMP
Op Gd,
IPCS
Format and print system abend dumps; under IPCS,
create a problem report.
VMFLOAD
SYSGEN
Generate a new CP, CMS or RSCS module.
VSAMPP
SYSGEN
Load and save the CMSVSAM, CMSAMS, and CMSBAM
segments.
ZAP
Op Gd,
SPG
Modify or dump LOADLIB, TXTLIB, or MODULE files.
Figure 25.
332
CMS Commands for System programmers
IBM VM/370 CMS User's Guide
March 30, 1979
Appendix B: Summary of CP Commands
Figure 26 describes the CP command privilege classes.
User and Function
Class
f~~!g!I ~I§1~! QE~!g1Q!:
The class A user controls the
VM/370 system. Class A is assigned to the user at the V!/370
system console during IPL. The primary system operator is
resFonsible for the availability of the VK/370 system and its
communication lines and resources. In addition, the class A
user controls system accounting, broadcast messages, virtual
machine performance options and other command operands that
affect the overall performance of VM/370.
H~1~:
The class A system operator who is automatically logged
on during CP initialization is designated as the primary
system operator.
Bl
~I§1~! Re§QY!£~ QE~!§1Q~:
Cl
~I§1~! f~Qg!~!!~!: The class C user updates certain
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.
functions of the VM/370 system.
Dl
~EQgl~~g QE~!~1Q!:
El
~y§!~!
Fl
~~£!~£~ R~E£~§~~1~1!!~:
G2
General User: The class G user controls functions associated
iIth-the-execution of his virtual machine.
Any2
The Any classification is given to certain CP commands that
are available to any user. These are Frimarily for the
purpose of gaining and relinquishing access to the V!/370
system.
H
Reserved for IBM
The class D user controls spool data
files and specific functions of the system's unit record
equipment.
An§lI§!: The class E user examines and saves certain
data in the VM/370 storage area.
The class F user obtains, and
examines, in detail, certain data about input and output
devices connected to the VM/370 system.
lDescribed in the
2Described in the
Figure 26.
use~
!~Ll1Q QE~£$1Q£~§
!!1Ll1Q
Guide.
~f ~Q!!§~g R~!~£~~£~ !g~ ~~~~~gl .!!2~rs.
CP Privilege Class Descriptions
Appendix B: Summary of CP Commands
333
March 30, 1979
Figure 27 contains an alphabetical list of the
privilege classes which may execute the command, and
about the use of each command.
Command
IPrivilegel
1 Class I
-----------11 any
*
CP commands, the
a brief statement
Usage
1-------------------------------------------------IAnnotate the console sheet.
'CP
1
1 any
1
ACNT
A
ADSTOP
G
Halt execution at a specific virtual machine
instruction address.
B
B
B
Attach a real device to a virtual machine.
Attach a DASD device for CP control.
Dedicate all devices on a particular channel
to a virtual machine.
ATTN
G
Make an attention interruFtion pending for the
virtual machine console.
AUTOLOG
A,B
Automatically log on a virtual machine and
have it operate in disccnnect mode.
BACKSPAC
D
Restart or reposition the output of a unit
record spooling device.
BEGIN
G
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.
CLOSE
G
Terminate spooling operations on a virtual card
reader, punch, printer, or console.
COUPLE
G
Connect channel-to-channel adapters.
CP
any
Execute a CP command while remaining in the CMS
virtual machine environment.
DCP
C,E
Display real storage at terminal.
DEFINE
G
Reconfigure your virtual machine.
Redefine the usage of SYSVIRT and VIRTUAL 3330V
devices.
ATTACH
B
Figure
334
27~
I
IExecute a CP command while remaining in the
I virtual machine environment.
I
ICreate accountiqg records for logged on users,
I reset accounting data, and close the spool
I file that is accumulating accounting records.
CP Co.mand Summary (Part 1 of 4)
IBM Y8/370 CMS User's Guide
March 30, 1979
Command
DETACH
privilege
Class
B
B
B
G
G
Usage
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.
Detach a channel from your virtual machine.
DIAL
any
Connect a terminal or display device to the
virtual machine's virtual communication line.
DISABLE
A,B
Disable 2701/2702/2703, 370X in EP
and 3270 local communication lines.
D1SCONN
any
Disconnect your terminal from your virtual
machine.
DISPLAY
G
Display virtual storage on your terminal.
DMCP
C,E
Dump the specified real storage location on your
virtual printer.
DRAIN
D
Halt operations of specified spool devices upon
completion of current operation.
DUMP
G
Print the following on the virtual printer:
virtual PSi, general registers, floating-point
registers, storage keys, and contents of
specified virtual storage locations.
ECHO
G
Test terminal hardware by redisplaying data
entered at the terminal.
ENABLE
A,B
Enable communication lines.
EXTERNAL
G
Simulate an external interruption for a virtual
machine and return control to that machine.
I FLUSH
D
Cancel the current file being printed or punched
on a specific real unit record device.
FORCE
A
Cause logoff of a specific user.
FREE
D
Remove spool HOLD status.
HALT
A
Terminate the active channel program on
specified real device.
HOLD
D
Defer real spooled output of a particular user.
INDICATE
A,E,G
Indicate resource utilization and contention.
IPL
G
Simulate 1PL for a virtual machine.
LINK
G
Provide access to a specific DASD by a
virtual machine.
LOADBUF
D
Load real UCS/UCSB or FCB printer buffers.
Figure 27.
mode,
CP Command Summary (Part 2 of 4)
Appendix B: Summary of CP Commands
335
March 30, 1979
Command
Privilege
Class
Usage
LOADVFCB
G
Load virtual forms control buffer for a virtual
3203 or 3211 printer.
LOCATE
C,E
Find CP control blocks.
LOCK
A
Bring virtual pages into real storage and lock
them; thus, excluding them from future paging.
LOGOFF
any
Disable access to CP.
LOGON
any
Provide access to CP.
MESSAGE
A,B,any
Transmit messages to other users.
MONITOR
A,E
Trace events of the real machine and record
system performance data.
MSGNOH
B
Send a specified message, without the standard
message header, from one virtual machine to
another.
NETWORK
A,B,F
Load, dump, trace, and control the operation of
the 370X control program. Control the
operation of 3270 remote devices.
NOTREADY
G
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
G
Simulate device end interruption for a virtual
device.
REPEAT
D
Repeat (a specified number of times) printing or
punching of a specific real spool output file.
REQUEST
G
Make an attention interruption pending for the
virtual machine console.
RESET
G
Clear and reset all pending interruptions for a
specified virtual device and reset all error
conditions.
REWIND
G
Rewind (to load point) a tape and ready a tape
unit.
SAVESYS
E
Save virtual machine storage contents,
registers, and PSi.
SET
A,B,E,F, Operator--establish system parameters.
G
User--control various functions within the
virtual machine.
Figure 27.
336
CP Command Summary (Part 3 of 4)
IBM VM/370 eMS User's Guide
March 30, 1979
Command
IPrivilegel
I Class I
Usage
SHUTDOWN
A
Terminate all VM/370 functions and checkpoint CF
system for warm start.
SLEEP
any
Place virtual machine in dormant state.
SMSG
G
Send special message to aFFropriate virtual
machine.
SPACE
D
Force single spacing on printer.
SPOOL
G
Alter spooling control options; direct a file to
another virtual machine or to a remote
location via the RSCS virtual machine.
SPTAPE
D
Dump output spool files cn tape
spool files from tape.
START
D
Start spooling device after draining or changing
output classes.
STCP
C
Change the contents of real storage.
STORE
G
Alter specified virtual storage locations and
registers.
SYSTEM
G
Simulate RESET, CLEAR STORAGE, and RESTART
buttons on a real system console.
TAG
G
Specify variable information to be associated
with a spool file or output unit record
device.
Interrogate the current TAG text setting of a
given sFool file or output unit record device.
TERMINAL
G
Define or redefine the input and attention
handling characteristics of your virtual
console.
TRACE
G
Trace specified virtual machine activity at your
terminal, spooled printer, or both.
TRANSFER
D,G
Transfer input files to or reclaim input files
from a specified user's virtual card reader.
UNLOCK
A
Unlock previously locked page frames.
VARY
B
Mark a device unavailable or available.
WARNING
A,B
Transmit a high priority message to a specified
user or to all users.
Figure 27.
or load output
CP Command Summary (Part 4 of 4)
Appendix B: Summary of CP Commands
337
March 30, 1979
338
IBM VM/370 eMS User's Guide
March 30, 1919
Appendix C: Considerations for 3270 Display
Terminal Users
The IBM 3210 display terminal, co •• only referred to as a 3210, functions
somewhat differently from a typewriter-style terminal when you use it as
a virtual machine console under VB/310.
Apart from the obvious
difference in the way output is displayed, there are special techni~ues
you can use with a 3210 that you cannot use on a 2141 or other
typewriter terminal. This appendix describes how. to use a 3210 and
provides additional notes to supplement discussions in the first part of
this publication.
Entering Commands
Since the keyboard on a 3210 is never locked during the execution of a
co •• and or program, you can enter successive com.and lines without
waiting for the completion of the previous comaand. This stacking
function can be combined with the other methods of stacking lines, such
as using the logical line end syabol (I) to stack several command lines.
If you try to enter aore lines than the terainal buffer can accoa.odate,
however, you receive the status message BOT ACCEPTED and you aust wait
until the bQffer is cleared before you can enter the line.
You will find, as you becoae accustomed to using a 3210, that the ICP
function is very useful. The ICP function, reaember, is a function that
allows you to pass a command line to the control program im.ediately,
bypassing any processing by the virtual aachine (CBS). The ICP function
can be used in any VM/310 environment, and you can enter it even when a
program is executing. You do not have to interrupt a prograa's execution
to enter a command line such as:
Icp display psw
to display the current PSW, or:
Icp spool printer class s
to spool your virtual printer.
If there are CP and CMS commands that you use frequently, you can set
the program function (PF) keys on your terminal to execute thea. Soae
examples of commands you might wish to catalog on PF keys are:
ICP DISPLAY PSW
ICP QUERY PRINTER ALL
QUERY SEARCH
To set functions keys 1, 2, and 3 to perfora these co.mand functions,
enter:
cp set pf1 i.med "Icp display psw
cp set pf2 iamed "Icp query printer all
cp set pf3 im.ed query search
Appendix C: Considerations for 3210 Display Ter.inal Users
339
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
Wben you want to exe.cute a ,tcp functioDwi th a PF key,· or you,want a PF
key to execute a series of commands, you must use the logical escape
symbol (tI) when you enter the SET command. For exampl'e:
cp set pfS immed edit test filetltbo"#input line"tfile
sets the PF5 key as:
EDIT TEST FILEtBOIINPUT LINEIFILE
You cannot set lowercase characters in a PF key.
The above examples use the IMMED operand of the SET command, which
specifies that the function is performed as soon as you press the PF
key. You can al~o set a key so that it is delayed; that is, the command
or data line is placed in the user input area. Then, you must press the
Enter key to execute the command. You may modify the line before you
enter it. This is the default setting (DELAY) for program function keys.
For example, you might set a key as:
QUERY DISK XQ)
When you press this PF key, the command line is placed in th~ user input
area, with tbe cursor positioned following the "~" logical character
delete symbol; you can enter the mode letter of the disk you are
querying before yau press the Enter key to execute the command. If you
enter 'A', the resulting command as seen by CMS is 'QUERY DISK A'.
You can set all of your program function keys in your PROFILE EXEC,
so they are set each time you load CMS. You can change a PF key setting
any time during a terminal session, according to your needs.
If, for
example, you discover that you are repeating several procedures a number
of ti.es, and the ptocedure does not lend itself to being written into
an ErEC, yatt could use your program function keys.
All the lines in an EXEC procedure are scanned, and
strings are truncated to eight characters, so if you
command line, insert spaces where possible:
all character
enter a long
CP SET PFS IMMED EDIT TEST FILE 'BOt INPUT
To change PF settings within the edit environment, give the EXEC a
filename that begins with a dollar sign
($), so it functions as an edit
macro.
For more details
.§y!,g~.
on setting PF keys, see the
!~L11~ £~£mi~! ~2~£~2
Controlling the Display Screen
During a C~ or ~MS session (other than an EDIT session)
messages and
warnings from the system operator or other users are highlighted. This
distinguishes these messages
from other output and
lessens the
possibility of important messages being lost or ignored.
A major feature of a 3270 display screen is the screen status area,
which iridicates, at all times that you are ~ogged on, the current
operating condition your virtual machine is 1n.
Understanding the
status conditions can help you use CMS on a 3270 more effectively. The
screen status area indicates one of six conditions:
340
IBM VM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1919 by Supp. SD23-9024-1 for 5748-X18
~~ !~!~:
After you log on, this is the first status message you see; it
indicates that the terminal is waiting for a line to be read by the
control program. You can enter only CP commands when the screen status
area indicates a CP READ.
Appendix C: Considerations for 3210 Display Terminal Users
340.1
!!arch 30, 1979
340.2
IBB 'B/370 CBS User's Guide
!!
READ: This status indicates tha~ your terminal is waiting for a line
to be-Issued to your virtual machine; you may be in the CMS environment,
in the edit or debug environments, or you may be executing a program or
an EXEC that has issued a read to the console.
!Y!!l!§: This status means that your virtual machine is operating.
Once
you have loaded CMS and are using the CMS environment, this status is
almost continually in effect, even when you are not currently executing
a command or program.
You can alter the way this works by using the AUTOREAD function of
the SET com.and. When the AUTOREAD setting is OFF, (the default for
display terminals), your terminal displays a RUNNING status after the
execution of each CMS command. If you want the terminal to be in a VM
READ status following each command, issue:
set autoread on
The ON setting is the default for typewriter terminals, since a read on
a typewriter terminal must be accompanied by the unlocking of the
keyboard.
The advantage of keeping your virtual machine in a running status
even when it is not actually executing a program is that it makes your
terminal ready to receive messages. If your terminal is waiting for a
read, either from CP or from the virtual machine, and if a user or a
program sends a message to your virtual console, then the message is not
displayed until you use the Enter key to enter a command or null line.
When your machine is in a running status, the terminal console is always
ready to accept messages.
If your virtual machine is in the CP environment, and you want your
terminal to be in a running status, you can use the command:
cp sleep
To return to the CP READ status, you must press the PA1 key or the Enter
key.
MORE ••• : This status indicates that your display screen is full, but
that-there is more data to be displayed. This message, in addition to
indicating that there is more data, gives you a chance to freeze your
screen's current display so you can continue to examine it, if
necessary.
When you see the screen is in a MORE ••• status, you can either
press the Clear, Cancel, or PA2 keys to clear the screen and see
next screen, or (2) press the Enter key to hold the screen in
present status.
If you do not do either, then after 60 seconds,
screen is cleared and the next screen is displayed.
(1)
the
its
the
~gLD1!~:
This indicates that you have pressed the Enter key to freeze
the screen. You must use the Cancel, Clear, or PA2 keys to erase this
screen and go on to the next display.
A holding status also results if you have received a message that
appeared on this screen. When the screen becomes full,
it does not
automatically pass to the next display after 60 seconds, but waits until
you specifically clear the screen.
(This feature ensures that any
important messages you receive are not lost.)
)
!gI A££~g!!~: Indicates that you are trying to enter a command line but
the terminal buffer is full and cannot accept it. This message is also
issued when you attempt to use the 3270 COpy function and a printer is
either not available or not ready.
Appendix C: Considerations for 3270 Display Terminal Users
341
CONSOLE OUTPUT
When you use a 3210 terminal as your virtual machine console, you do not
ordinarily retain a console log, as you do on typewriter terminal.
There may be many circumstances in which you need a printed record of
your console output, whether it be to obtain a copy of program-generated
output, or to retain a record of CP and/or CMS commands that resulted in
an error condition. There are two techniques you can use in VM/310 to
obtain hardcopy representations of display terminal sessions: spooling
console output and the 3210 copy function.
The CP SPOOL command provides the CONSOLE operand, which
begin and end console spooling. You enter:
allows you to
cp spool console start
when you want to begin recording your terminal session, and:
cp spool console stop
when you have finished. In between, you can periodically close the
console file to release for printing whatever has been spooled thus far:
cp spool console close
other operands that you can enter are the same as you might specify for
any printer file, such as CLASS, COPY, CONT, and HOLD.
An alternate technique
reader:
cp spool console start
is to spool your console to
*
your own virtual
class a
Then, when you close the console file, instead of being released to the
CP printer spool file queue, it is routed to your virtual card reader,
and you can load it onto your A-disk as a CMS disk file:
readcard console file
You can then use the editor to examine it
(or to delete sections you
don't need) and use the PRINT command to spool it to the printer.
If you are using a 3210 display terminal, and you have available
3286, 3281, 3288, or 3289 printer, you can copy the full screen
currently appearing on the screen. TO copy the screen, you
assign the copying function to a program function key, with
command:
a 3284,
display
have to
the SET
cp set pf9 copy
Then, whenever you want to copy a screen display, you can press the PF9
key (or whichever key you set). The display is printed on any 3210
display printer that is attached t~ the same remote control unit as the
display terminal. If, when you press the PF key, the screen status area
342
IBM VM/310 CMS User's Guide
March 30, 1979
indicates NOT ACCEPTED, it means that the printer is either not ready or
not available. When you press the PF key and receive no response, it
means that the screen has been copied.
There is a print matrix available to the 3274 and 3276 user that
allows control of the display to printer operations. In addition, a
local print key is provided on the 3274 that can be used for copy
operations.
Figure 28 is an example of a 3270 screen display that could be copied
on the printer. When you use the copy function to copy a screen, all 24
lines of the display screen are copied; the screen status area
(indicated as RUNNING in Figure 28) is blank if the 3270 is locally
attached. If the 3270 is remotely attached, the entire screen including
the screen status area, is copied. You can use the user input area of
your screen to key in comments, or your name or userid, if several users
are spooling copy files.
DEFINE STORAGE 16384K
STORAGE = 16384K
IPL 190
CMS VERSION 3.0 02/28/76
10:32
testl ••• t. jones
RUNNING
Figure 28. 3270 Screen Display
Signaling Interruptions
The two keys on your 3270 keyboard that signal interruptions are the PAl
key -- REQ key on a 3278 Model 2A -- and the Enter key. Throughout this
publication, interruption signaling has been described in terms of the
Attention key, which is the interruption signaling key on a 2741.
On a typewriter terminal, the Attention key, pressed once, causes a
virtual machine interruption (if the terminal mode is set to VM); you
must use it when you want to enter an Immediate command, such as HT or
HX. On a display terminal, you can enter these commands whenever Jour
virtual machine is in a running status, without having to signal an
interruption before you enter the command.
Sometimes, however, if your terminal is displaying output very
rapidly, you must wait until the screen is full and the screen status
area indicates a MORE ••• status before you attempt to enter the HT or HX
command.
The Enter key can also be used as an interruption signaling key. If
you press it once when your virtual machine is running, you will place
your virtual machine in the VM READ status, so you can enter a command
line. If you press the Enter key twice, quickly, you enter the CP
environment, with your console in a CP READ status.
Appendix C: Considerations for 3270 Display Terminal Users
343
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-118
An easier way to enter the CP environment is ty pressing the PAl key.
Whenever you press this key, your virtual machine is placed in a CP READ
status, and you can enter any CP command. From t~e CP environment, you
must use the CP command BEGIN to resume execution of your virtual
machine.
HALTING SCREEN DISPLAYS
When your terminal is displaying successive screens of output from a
program or a CMS command, you can use the HT or HX Immediate commands to
halt the display or the execution of the command, respectively. If your
terminal is writing the information ~t a very rapid rate, you may have
difficulty entering the HT or HX command. In these circumstances, you
can use the PA1 key -- REQ key on a 3278 Model 2A -- or press the Enter
key twice to force your terminal to a CP READ status. Then, you can use
the CP command ATTN or REQUEST to signal a virtual machine read~ When
the screen status area indicates VM READ, you can enter HX or HT.
Using the eMS Editor with a 3270
The CMS editor has a special format and operation, called display mode,
that makes editing CMS disk files with a 3270 more convenient than on a
typewriter terminal. It uses most of the display screen, and, depending
on the terminal type and model, displays, depending upon the terminal
type end model, up to 38 lines of a file at once.
In addition to
displaying data lines of the file, the editor also indicates, on the
topmost line of the screen, the filename, filetype, record format, and
logical record length of the file being edited, as well as showing your
current mode:
input or edit. The format of the screen is shown in
Figure 29.
The screen lines that you are most concerned with while editing are
the current line, the user input area
(the bottom two lines), and the
editor's message line
(the second line from the top)
in which the
editor's responses and error messages are displayed.
The current line
and the editor's message line are highlighted.
When you first invoke the editor to edit a file, whatever is
currently on the screen (including your EDIT command line) is erased and
the full screen is controlled by the editor. The current line pointer
is positioned at the top of the file, the top part of the display screen
appears blank. The editor displays the characters "TOF:" and "EOP:" to
indicate the top and end of the file, respectively.
ENTERING EDIT SUBCOMMANDS
When you enter an EDIT subcommand into the user input area and press the
Enter key the subcommand is not displayed on the screen, but the change
(or line pointer movement) is reflected in the screen display. If you
enter a subcommand that moves the current line pointer, all of the lines
on the screen are shifted up or down, according to the action taken by
the subcommand.
If you use the INPUT subcommand to enter input lines, the edit status
field indicates INPUT; all of the lines that you enter are placed in the
file and appear on the screen as the current line.
(Entering input
lines from a remote 3270 is someWhat different. The following "Editing
on a Remote 3270" discusses the differences.)
344
IBM VM/370 CMS User's Guide
March 30, 1979
EDIT
»»>
1
1
DISPLAY SCREEN
80.
A12
F 80
3
TOF: 5
THIS IS THE FIRST LINE OF THE FILE. (CURRENT LINE).
THIS IS THE SECOND LINE OF THE FILE.
THIS IS THE THIRD LINE OF THE FILE.
EOF:
c
6
VM READ
Notes:
--i-Edit session status. This indicates EDIT, INPUT, or NEW FILE.
The NEW FILE message appears when you edit a new file; it is
replaced with INPUT when you enter input mode and thereafter is
EDIT or INPUT.
2 The filename, filetype, and filemode of the file.
3 Record format and logical record length.
4 Editor reponse area.
The response shown may be the response to
a VERIFY subcommand entered with no operands.
5 The symbols TOF: and EOF: indicate top of file and end of file,
respectively.
6 The current line is located in the approximate center of the
output area of the screen.
Figure 29. How the CMS Editor Formats a 3270 Screen
If you enter an invalid EDIT subcommand, or if you enter a subcommand
that requests information,
the edit response appears in the message
field of the screen. For example, if you enter:
trunc
the editor responds by displaying
might be:
»»>
the current truncation setting, which
81
If you enter:
copy file myfile edit (trunc
the editor would respond:
»»>
?EDIT: copyfile myfile edit (trunc
to indicate that it does not recognize the entered line (COPYFILE is not
an EDIT subcommand). When you use line-number editing, the prompting
message appears in this area; after you enter text in the user input
area,
the text line is written in the output display area, at the
current line position.
Appendix C: Considerations for 3270 Display Terminal Users
345
March 30, 1979
Two EDIT subcommands, CHANGE and 1, result in lines being copied in
the user input area. In the case of the CHANGE subcommand, the line that
is displayed is the current line. Once in the user input area, you can
modify it and re-enter it,. While you are changing it, the original line
appears unchanged in the output display area. If you decide that you do
not want changes entered, you must press the Erase Input key and then
press the Enter key before you enter any other EDIT subcommands.
You can use the 1 subcommand to request that the last EDIT subcommand
you entered be displayed in the user input area. If, for example, you
enter a CHANGE or LOCATE subcommand that results in a NOT FOUND
condition, or some other error, you can enter:
1
and modify the subcommand line and re-enter it, if you want; otherwise,
use the Erase Input key to delete it.
CONTROLLING THE DISPLAY SCREEN
Usually the editor controls the entire screen display during an edit
session. Occasionally, the screen goes into a MORE...
status, and you
must use the Cancel key or PA2 key to clear the screen. There are two
other situations in which the screen must be cleared, either by the
editor, or by you. When you use the CMS subcommand to enter CftS subset
to enter CMS commands, the screen is cleared and the message CMS SUBSET
is displayed at the top of the screen. When you issue the subcommand
RETURN to return to edit mode, the screen disFlay is restored to its
original appearance.
The
situation is
slightly different,
however, whenever
you
communicate with the control program
(CP), or receive messages from
other users during an edit session.
Any CP message or command response
causes your screen to go into a MORE ••• status; you must use the PA2
(Cancel) key to see the response. To restore your screen to its edit
display, you should use the EDIT subcommand TYPE. If you use the PA1
key to place your virtual machine in the CP environment, and the screen
status area indicates CP READ, use the CP command BEGIN to restore edit
mode. Then enter the TYPE subcommand.
If you enter a subcommand other
than TYPE, the entire screen is not restored, and the top two lines (the
editor's data and response fields) may contain lines of the CP response.
If your virtual machine was in input mode when you entered the CP
command, you may continue entering lines of input; the third through the
ninth lines of the screen are restored after you enter the next line.
If you enter a CP command that
there is no change to the screen.
does not
produce a
response, then
The VERIFY subcommand allows you to alter the verification columns when
you are editing a file or to cancel verification altogether.
If, for
example, you are editing a file with records longer than 80 characters,
each line is displayed on two lines of the display screen. Sometimes,
you may be editing only specific columns in a file, and do not need to
see the lines displayed in their entirety. To see only the first 80
columns, you could enter:
346
IBM VM/370 CMS User's Guide
March 30, 1919
verify 1 80
Or, if you wanted to see the last
120-character records, you could enter:
80
columns
of
a
file
with
verify 41 120
If you cancel verification entirely by entering:
verify off
then modifications that you make to the file (including movement of the
current line pointer) are not reflected on the display screen until you
use the TYPE subcommand.
THE CURRENT LINE POINTER
There is one aspect of the CMS Editor on a 3210 that is much the saae as
on a typewriter terminal: you must still be concerned with the
positioning of the current line pointer, and you can only add or modify
data on the current line, even though you see many lines being
displayed. The current line, on the screen, appears near the aiddle of
the output area of the screen (see Figure 29).
To move the current line pointer, you can use the subcommands OP and
DOWN: UP indicates movement toward the top of the file and DOWN
indicates movement toward the bottom of the file. When you issue either
of these subcommands, the entire display of the file shifts down the
screen (if you use the UP subcommand) or up the screen
(if you use the
DOWN subcommand).
If you have never used the CMS editor on a typewriter terminal, you
may find the UP and DOWN subcommands confusing to use, so you can use
instead the BACKWARD (UP)
and FORWARD or NEXT (DOWN) subcommands to
shift the display backward
(toward the top of the file)
and forward
(toward the bottom of the file).
You can also use the EDIT subcommand SCROLL, which allows you to
display successive screen displays, and to examine an entire file
quickly. For instance, on a 3210 Model 2 display terminal, you enter
the SCROLL subcommand with no operands, it is the equivalent of entering
the subcommand DOWN
(FORWARD) 20, which results in the screen changing
to display the 20 lines following the lines currently being displayed.
If you enter:
scroll 10
The SCROLL subcommand executes 10 times, placing the screen in a 80BE •••
state at the end of each display.
If the file you are editing has verification column settings greater
than 80 characters (so each line takes up tvo display lines), then the
SCROLL subcommand moves the screen 10 lines at once instead of 20.
The UP (or BACKWARD) counterpart of
abbreviated so.
SCROLL is SCROLLUP, which can be
Appendix C: Considerations for 3210 Display Terminal Users
347
March 30, 1979
USING PROGRAM FUNCTION KEYS
You can enhance the use of the CMS editor on a 3270 by setting the
program function (PF) keys on your terminal to correspond to some of the
more frequently used EDIT subcommands, such as UP, DOWN, SCROLL, FILE,
SAVE, and so on.
You can also set a program function key to contain a
line of data, so that if you are creating a file that has many duplicate
lines in it, you can use the PF key instead of having to key in the
entire line each time.
PF keys cannot, however, contain lowercase
character strings.
You can set a program function key while you are in edit mode either
by using the PA1 key -- REQ key on a 3278 Model 21
to enter the CP
environment or by using the ICP function.
USING THE EDITOR IN LINE MODE
The editor's display mode is the most common format of operation on a
3270. There are, however, instanc~s when it is not possible or not
desirable to use the editor in display mode. Fer these instances, you
should use the line mode of operation,
which is the equivalent to using
a typewriter terminal. When you use line mode, each EDIT subcommand you
enter, and the response (if you have verification on), is displayed, a
line at a time,
on the screen in the output display area. There is no
full screen display of the file.
You need only be concerned with using line mode if you are connected
to VM/370 by a remote 3270 line, or if you are editing a file from
within an EXEC and you want to control the screen display. Although it
is possrble to use the editor in line mode on a local 3270, it is rarely
necessary for normal editing purposes.
When you invoke the editor from a remote 3270, you are placed in line
mode by the editor. The advantage of using the 3270 in line mode
(particularly on a remote editor) is that the editor can respond more
quickly to display requests. When you use display mode, the editor has
to write out the entire output display area when you move the current
line pointer; in line mode, it has only to write a single line.
If you want to use display mode, you enter the EDIT subcommand:
format display
The editor hegins operating in display mode, and you can use the special
editing" functions available in display mode.
However, when you are using a remote 3270 in display mode, and you
enter the INPUT subcommand to begin entering input lines, the screen is
cleared, and your input lines are displayed as if you were in line mode,
beginning at the top of the screen. When you enter a null line to return
to edit mode, the editor returns to a full screen display.
You can resume editing in line mode by using the subcommand:
format line
3~8
IBM VM/370 CMS User's Guide
March 30, 1979
If you invoke the editor from an EXEC, but you do not want the screen
cleared when the editor gets control, you can specify the NQDISP option
on the EDIT command line:
edit test file (nodisp
This places the 3270 in line mode,
screen are not erased.
so that the
lines already
on the
The 3270 remains in line mode for the remainder of the edit session,
and you cannot use the FORMAT subcommand to place it in display mode.
USING SPECIAL CHARACTERS ON A 3270
There are two special characters available on a typewriter terminal
whose functions have no meaning on a display terminal. They are the tab
character (X'OS')
and the backspace character (X'16'). For most file
creation and editing purposes, you will probably not need to use the
backspace, but many CMS filetypes use tab settings to set up the proper
column alignment in files.
There are two methods you can use to enter
any special character on a 3270 (including tabs), and an additional
method of using tabs, which involves setting a program function key. In
addition, the tab character can also be set via the CP command TERMINAL
!!BC~!~.
-------To enter any special character (a
you can either:
1.
backspace is used in this example)
Enter another character at the appropriate place in the record, and
then use the ALTER subcommand to alter that character to the
hexadecimal value of the character you want to represent
(a
backspace character is a X'16'). For example:
input ABC»>
alter> 16 1-*~
When you enter backspaces and overstrike characters on a 3270,
however, the characters and backspaces each occupy character
positions, so that a single compound character occupies three
character positions on the screen. If the image setting is CANON,
and you want to use the backspace to enter compound characters, you
must not enter the backspace character first.
2.
Before you begin to create the file, use the CMS SET
define some other character as the backspace character:
command to
set input> 16
CMS then translates all occurrences of the character> to X'16'.
If you need to correct a line that contains backspaces, you can
reverse the above sequence; alter the X'16' characters to asterisks and
enter the CHANGE subcommand.
]~!i~i~g ~
ll1Q
gfQg!g~ ~Y~£i1g~ ~gy f2! !~Q ~gii1~g§
You can set up a program function key to operate like a tab key
typewriter terminal. You must use the CP SET command as follows:
on a
SET PFnn TAB nl n2 • • • nn
Appendix C: Considerations for 3270 Display Terminal Users
349
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
PFnn
is any valid function key from PF1 to PF24.
n1 n2 • • • nn
are the logical tab settings desired, expressed· as
decimal numbers. Invalid tab settings are ignored. You
can specify the setting values in any order, but they
are normally specified in ascending order.
You can define different PF keys with different tab settings for
different filetypes. Whenever you press the PF key you have set for a
tab, the cursor moves to the corresponding position in the user input
area, in much the same way that a typing element on a typewriter would
move to the next tab stop.
If you press the PF tab key to a position that already contains a
data character, the data remains intact. If there is no data in that
position, a tab character is entered in the file. The effect of the tab
in the file depends, as in normal usage, on the image setting of the
editor. If the image setting is set to on (the default), the tab expands
to an appropriate number of blanks, to correspond to the settings in
effect for the TABSET subcommand. When the TAESET settings match the
tab settings of the PF key, then any lines you enter in the user input
area appear exactly as they will appear in the output display area.
If you tab beyond the last defined tab position,
repositioned at the beginning of the user input area.
the cursor
is
When you edit a file on a 3270 terminal in display mode, you should not
copy a line containing tabs or backspaces into the user input area. The
tabs or backspaces are converted to blanks (X'40').
Similarly, if the
line contains VM/370 logical line editing symbols that have been entered
as data characters, the symbols are reinterpreted when you enter the
line.
If you use the SET OUTPUT function to display non printable characters
in CMS, the character translations do not appear when the editor is in
display mode. They are, however, displayed when the editor is in line
mode.
Using APL with a 3270
If you have a 3277 or 3278 display station equipped with an APL
keyboard, you can use APL on a 3270 terminal in CMS. You invoke the APL
virtual machine by issuing the command specified in the VSAPt Program
Product documentation. This command invokes the VSAPt-CMS interface
program. You are then prompted to press the APL On/Off key which is cn
your terminal; pressing this key changes the keyboard to APt character
input mode.
You are then prompted to press the Enter key to continue.
EBCDIC or APL characters can always be displayed; the APt On/Off key
does not change this.
The VSAPL-CMS interface program issues the
TERMINAL APL ON command for you and selects the appropriate translation
tables. The TERMINAL APL ON command automatically forces a TERMINAL
TEXT OFF condition. The interface program then invokes the VSAPL
program. When the VSAPL ready message appears on the screen, you can
use APL.
350
IBM VM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5148-XX8
You can send a copy of your display screen to a locally or remotely
attached printer. Be sure that the printer you send your output to has
the APL feature installed; if it does not, the APL characters are not
printed. Most system printers do not have an APt print chain; therefore
you may need to use the copy function to direct your screen output
displays to a 3284, 3286, or 3281 printer.
ERROR SITUATIONS
If you do not have the APL
3278 but you invoke APL:
hardware feature installed on
your 3271 or
•
The VSAPL program
issued.
•
You cannot communicate with the VSAPL program.
•
Any APL characters that are written to the screen appear as blanks.
is invoked
and the
TERMINAL APt
ON command
is
If you have the APL feature installed on your terminal, but invoke
APL manually without issui»g the TERMINAL APt ON command or issue
TERMINAL APL OFF at sometime during APL processing:
•
•
•
The VSAPL program is activated.
You cannot communicate with the VSAPL program.
Any APL characters written to the screen appear as blanks.
If you attempt to use· the APL 0/5
(overstrike) key when the APt
hardware key is set off, it acts as a backtab key and reFositions the
cursor to the beginning of the user input area.
LEAVING THE APL ENVIR0NMENT
Issue the APL command:
} OFF
to log off VM/370.
Issue the APL command:
} OFF HOLD
to return to CMS.
program, which:
•
•
•
This APL
command invokes
the VSAPL-CMS
interface
Issues the TERMINAL APL OFF command
Prompts you to press the APL hardware key
Returns to CMS
!gte: The APL hardware feature is a key, not a switch. Each time you
press the APL key you reverse its on/off setting. To determine whether
APL is on or off, press a key that represents a special APL character.
If the character displayed is an APL character, the hardware APL feature
is set on. If the character displayed is a non-APt character, you must
press the APL key once to set the APL feature on.
Appendix C: Considerations for 3270 D:.sp1ay Terminal Users
351
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
Using the 3277 Text Feature
If you have a 3271 or 3278 display station equipped with the Data
Analysis Text keyboard, you can key in, as well as display, all of the
special text characters. For a description of these characters, see the
!~LJIQ I~£~!Dg! Q§g£~§ ~y!g~.
These characters are in addition to those available with standard EBCDIC
3270 terminals.
If you have a suitably equipped printer attached to
your 3270, you can use the SET PFnn COpy function to obtain a printed
copy of the screen.
When you want to activate
characters, enter the command:
the text
feature, and
use the
special
cp terminal text on
The TERMINAL TEXT ON command automatically forces the TERMINAL APL OFF
command. NOw, you can use any of the special characters when you enter,
change, or locate text lines in a file.
ERROR SITUATIONS
If you do not have the appropriate text hardware feature on your 3270,
but attempt to display a file that contains the characters, the
characters appear as blanks on a 3277, and as hyphens on a 3276 and a
3278.
If you inadvertently issue the TERMINAL TEXT ON command while using a
terminal that does not have the text capability, you must do the
following to return to normal operating procedures:
1.
Press the PAl key to enter the CP environment.
2.
Key in, in uppercase letters only, the command line:
TERMINAL TEXT OFF
LEAVING THE TEXT ENVIRONMENT
You leave the special text environment by entering the command:
cp terminal text off
1.
The 3210 text hardware feature is activated by a key, not a switch.
Each time you press the TEXT On/Off key, you reverse its setting.
When the red light on the text keyboard is illuminated, the text
feature is on.
2.
Compound characters,
such as
a character/backspace/character
combination, are still entered and displayed as three characters.
The screen position occupied by the backspace character appears as
a blank because the character (X'16') is nondisplayable.
352
IBM VM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
Appendix D: Sample Terminal Sessions
This appendix provides sa.ple terminal sessions showing you how to use:
•
The CMS editor (using context editing), and the
RENAME, and ERASE commands
•
The CMS editor (using line-number editing)
•
CMS as simulation to create, asse.ble, and execute a program using OS
macros in the CMS environment
I •
I
•
CMS COPYFILE, SORT,
CMS DOS/VSE simulation to create, assemble, and execute
using DOS/VSE macros in the CMS/DOS environment
Access method services under CMS, to create VSAM catalogs
spaces, and to use the define and repro functions of AMSERV
a program
and data
Appendix D: Sample Terminal Sessions
353
March 30, 1919
Sample Terminal Session Using the Editor and CMS
File System Commands
This terminal session shows you how to create a CMS fil~ and make changes to it using the
CMS editor, and then manipulate it using the CftS file system commands, COPYFILE, ERASE,
RENAME, and SORT.
Bgte: Throughout this terminal session whenever a TYPE subcommand or command is issued
that results in a display of the entire file, the complete display is not shown; o.itted
lines are indicated by vertical ellipses
( ••• ). When you enter the TYPE command or
subcommand, you should see the entire display.
1
2
3
4
edit command data
NEW FILE:
EDIT:
image
ON
tabs 1 12 80
trunc 12
input
INPUT:
copyfile
copy cms files
sort
sort cms files in alphameric order by specific columns
edit
create a cms file
edit
modify a cms file
rename
change the name of a cms file
punch
punch a copy of a cms file on cards
print
print a cms file
erase
erase a cms file
listfile
list information on a cms file
state
verify the existence of a cms file
statew
verify the existence of a cms file on a read/write disk
readcard
read a cms file from your card reader onto disk
disk dump
punch a cms file in cms disk dump format into your virtual card punch for
TRUNCATED
DISK DUMP PUNCH A CMS FILE IN CMS DISK DUMP FORMAT INTO YOUR VIRTUAL CA
disk load
read a disk dump file onto disk
compare
compare the contents of cms disk files
tape dump
dump cms files onto tape
tape load
read ems files onto disk from tape
5
EDIT:
1
2
3
4
5
354
Use the EDIT command to invoke the CMS editor to create a file with a filename of
COMMAND and a filetype of DATA. Since the file does not exist, the editor issues
the message NEW FILE.
Check that the image setting is ON. This is the default for all filetypes except
SCRIPT. Then, set the logical tab stops for this file at 1, 12, and 80, and set a
truncation limit of 12.
Enter the subcommand INPUT to enter input mode and begin entering lines in the file.
For these input files, you should press the Tab key (or equivalent) on your terminal
following each CMS command name. If there is a physical tab step on your terminal
in column 12, the input data appears aligned.
The message, TRUNCATED, indicates that the line you just entered exceeded the
truncation limit you set for the file (column 12). The editor displays the line, so
you can see how much of the line was accepted.
Your virtual machine is still in
input mode, so continue entering input lines.
To get out of input mode, enter a null line (press the Return or Enter key without
entering any data). The editor responds with the message EDIT:.
IBM VM/370 eMS User's Guide
6
7
8
9
top
TOF:
type *
TOF:
COPYFILE
COpy CMS FILES
TAPE LOAD READ CMS FILES ONTO DISK FRO! TAPE
EOF:
locate /disk dump
DISK DU!P PUNCH A CMS FILE IN CMS DISK DU!P FOR!AT INTO YOUR VIRTUAL CA
replace disk dump punch a cas file onto cards
input
INPUT:
type
display the contents of a cms file at your terminal
rename
alter the name of a cms file
sort
resequence the records in a cms file
copyfile
reformat a file, by columns
comprae
verify that two files are identical
10
11
EDIT:
change /rae/are/
COMPARE
VERIFY THAT TWO FILES ARE IDENTICAL
bo
TAPE LOAD READ CMS FILES ONTO DISK FRO! TAPE
input
INPUT:
12
13
EDIT:
file
R;
6
7
8
9
10
11
12
)
13
Us~ the TOP subcommand to position the current
line pointer at the top of the file.
The editor responds TOF:.
Use the TYPE subcommand to display the entire file. Note that all of your input
lines are translated to uppercase characters, and that the tab characters you
entered have been expanded, so that the first word following each command name
begins in column 12.
The message EOF: indicates that the end of the file is reached. You can issue the
LOCATE subcommand to locate a line. Since you are at the bottom of the file, the
editor begins searching from the top of the file.
Notice that you can enter the
character string you want to locate in lowercase characters; the editor translates
it to uppercase to locate the line. The editor displays the line.
Use the REPLACE subcommand to replace this line, in a shortened form so that it is
not truncated. Remember to enter a tab character after the command name; when you
enter the line, the tab stop does not have to be in column 12. Then, use the INPUT
subcommand again to resume entering input. The lines that you enter next are written
into the file following the DISK DU!P line.
When you make a spelling error or other mistake, you may want to correct it
immediately. Enter a null line to return to edit mode, and use the CHANGE subcommand
to correct the error.
In this example, the string RAE is changed to ARE. The
editor displays the line as changed.
Use the BOTTO! subcommand to move the current line pointer to point to the last line
in the file. Enter input mode with the INPUT subcommand.
If you enter input mode and decide that you do not want to enter input lines, all
you have to do to return to edit mode is enter a null line.
To write the file onto disk, use the FILE subcommand.
This writes it onto disk
using the name with which you invoked the editor, CO!!AND DATA. The CBS ready
message indicates that you are in the CBS command environment.
Sample Terminal Session Using the CBS Editor and CBS File system Commands
355
14
type command data
COPYFILE
SORT
COpy CftS FILES
SORT CftS FILES IN ALPHAftERIC ORDER BY SPECIFIC COLUMNS
TAPE LOAD
READ CftS FILES ONTO DISK FROM TAPE
R;
15
edit command data
EDIT:
16
17
save
EDIT:
fname comm2
file
R;
18
copyfile comm2 data a (lowcase
R;
19
copyfile command data a com.2 data a
DMSCPY601R ENTER SPECIFICATION LIST:
1-12 1
20
type comm2 data
21
COpy FILE
SORT
EDIT
EDIT
RENAME
PUNCH
PRINT
ERASE
LISTFILE
ht
(ovly specs
R;
Copy cms files
Sort cms files in alphameric order by specific columns
Create a cms file
Modify a cms file
Change the name of a cms file
Punch a copy of a cms file on cards
Print a cms file
Erase a cms file
List information on a cms file
R;
14
15
16
17
18
19
20
21
356
To display the entire file at your terminal, use the CMS TYPE command. Note any
errors that you made that you might want to correct.
Use the EDIT command to edit the file COftMAND DATA again. This time, since the file
exists, the editor does not issue the message, NEW FILE:
While you are in edit mode, make any changes that you need to; then issue the SAVE
subcommand to save these changes, and replace the existing copy of the file onto
disk.
Use the FNAftE subcommand to ch~nge the filename of the file to COMM2 (the filetype
remains unchanged). When you 1ssue the FILE subcommand this time, the file is
written onto disk with the name COMM2 DATA.
You can rewrite the entire file, COMM2 DATA in lowercase characters, using the
COpy FILE command with the LOWCASE option.
The file COftft2 DATA is now all lowercase characters (you can display the file with
the TYPE command if you want to verify it).
However, the command names, and the
first character of the description should be uppercase characters. You can use the
COPYFILE command again, to overlay the original uppercase characters of COMMAND DATA
in columns 1 through 12 over the lowercase characters in columns 1 through 12 of
COMft2 DATA.
Use the TYPE command to verify that the COPYFILE command did, in fact, overlay only
the columns that you wanted.
The HT Immediate command suppresses the display of the remainder of the file; you
can see from the first few lines that the format of the file is correct.
IBM VM/370 eftS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
22
listfile * data
COMMAND DATA
COMM2
DATA
A1
A1
R;
23
sort comm2 data a command sort a
DMSSRT604R ENTER SORT FIELDS:
1 9
24
type command sort
R;
COMPARE
COMPARE
Verify that two files are identical
Compare the contents of cms disk files
TYPE
Display the contents of a cms file at your terminal
R;
25
copyfile comm2 data a function data a ( specs
DMSCPY601R ENTER SPECIFICATION LIST:
12-72 1 1-9 70
R;
26
type function data
Copy cms files
Sort ems files in alphameric order by specific columns
COpy FILE
SORT
Read ems files onto disk from tape
TAPE LOAD
R;
27
sort function data a function sort a
DMSSRT604R ENTER SORT FIELDS:
1 70
R;
type function sort
Alter the name of a cms file
Change the name of a cms file
RENAME
RENAME
Verify the existence of a ems file on a read/write disk
STATEW
R;
22
23
24
25
26
27
The LISTFILE command lists your two files with the filetype of DATA.
(If you
previously had files with these filetypes, they are also listed.)
To sort the file COMM2 DATA into alphabetic order, by command, issue the SORT
command. When you are promFted for the sort fields, enter the columns that contain
the command names, 1 through 9.
The output file from the SORT command is named COMMAND SORT. You can use the TYPE
command to verify that the records are now sorted alphabetically by command.
To create another copy of the file, this time with the command names on the right
and the functional description on the left~ use the COPYFILE command with the SPECS
option again. To create a file this way, you must know the columns in your input
file (COMM2 DATA) and how you want them arranged in your output file (FUNCTION
DATA). Columns 1 through 9 contain the command names; columns 12 through 12 contain
the descriptions.
The specif~cation list entered after the prompting message
indicates that columns 12 through 72 should be copied and placed beginning in column
1, and that columns 1 through 9 should be copied beginning in column 70.
Verify the COPYFILE operation with the TYPE command.
Sort the file FUNCTION DATA so that the functional descriptions appear in alphabetic
order. You may also want to display the output file, FUNCTION SOBT.
Sample Terminal Session Using the CMS Editor and CMS File System Commands
357
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
28
29
30
listfile
COMMAND DATA
COMM2
DATA
COMMAND SORT
FUNCTION DATA
FUNCTION SORT
R;
erase command data
R;
rename comm2 data a
R-,
listfile
FILENAME
FUNCTION
COMMAND
COMMAND
FUNCTION
* *
A1
A1
A1
A1
A1
command data a
a ( label
FILETYPE FM
SORT
A1
DATA
A1
SORT
A1
DATA
A1
FORMAT
F
F
F
F
LRECL
80
80
80
80
RECS ELOCKS
DATE
22
3 10/13/75
22
3 10/13/75
3 10/13/75
22
22
3 10/13/75
TIME
7:52:03
7:48:52
7:48:15
7:51:37
LABEL
ABC191
ABC191
ABC191
ABC191
R;
31
32
33
34
35
edit function sort
EDIT:
zone
1 80
zone 60
change /
// *
Alter the name of a cms file
Change the name of a cms file
Verify the existence of a cms file on a read/write disk
EOF:
top
TOF:
find List
NOT FOUND
EOF:
case
RENAME
RENAME
STATEW
U
case m
find List
List information on a cms file
28
29
30
31
32
33
34
35
358
LISTFILE
If these are the only files on your A-disk, the LISTFILE command entered with no
operands produces a list of the files created so far.
The file COMM2 was created for a workfile, in case any errors might have happened.
Since you no longer need the original file, COMMAND DATA, you can erase it.
Use the RENAME command to rename the workfile COMM2 DATA to have the name COMMAND
DATA. The LISTFILE command verifies the change.
To begin altering the file FUNCTION SORT, invoke the editor again.
The ZONE command requests a display of the current zone settings, which are columns
1 and 80. When you issue the command ZONE 60, it changes the sett~ngs to columns 60
and 80, so that you cannot modify data in columns 1 through 59.
The CHANGE subcommand requests that the first appearance of five consecutive blanks
on each line in the file be compressed. The editor displays the results of this
CHANGE r~quest by displaying each line changed (which is each line in the file). The
net effect is· to shift. th.e command. column 5 spaces to the left.
position the ~urrent 1ine pointer at the top of the file, and then issue a FIND
subcommand to ~ove the line pointer to the line that begins with "List".
The editor indicates that the line is not found. Checking the current setting for
the CASE subcommand, you can see that it is U, or uppercase, which indicates that
the editor is translating your input data to uppercase. You can issue the CASE M
subcommand to chang~ this setting, then reissue the FIND subcommand~
IBM VM/370 CMS User's Guide
36
37
38
39
40
41
42
43
)
44
36
37
38
39
40
41
42
43
44
)
change Ion a cas/about a CMS
NOT FOUND
= zone 1 *
List information about a CMS file
top
TOF:
change /cms/CMS/ *
Alter the name of a CMS file
Change the name of a CMS file
Verify the existence of a CMS file on a read/write disk
EOF:
save
EDIT:
top
TOF:
next
Alter the name of a CMS file
$dup
Alter the name of a CMS file
change /name/filetype/
Alter the filetype of a CMS file
next
Change the name of a CMS file
change /name/filename/
Change the filename of a CMS file
next
Compare the contents of CMS disk files
next
copy CMS files
find M
Modify a CMS file
up
List information about a CMS file
i Make a copy of a CMS disk file
top
TOF:
LISTFILE
RENAME
RENAME
STATEW
RENAME
RENAME
RENAME
RENAME
RENAME
COMPARE
COPYFILE
EDIT
LISTFILE
COPYFILE
The editor locates the line and displays it. You want to change the character string
"on a cms" to "about a CMS". The editor does not find the string you specify because
the zone setting for columns 60 through 80 is still in effect. You can enter the
ZONE subcommand, and reissue the CHANGE subcommand, or you can enter the = (REUSE)
subcommand to stack the CHANGE subcommand, and enter the ZONE subcommand to execute
first.
The ZONE subcommand is executed, then the CHANGE subcommand. The editor displays the
changed line.
At the top of the file, enter another global change request, to change lowercase
occurrences of the string cms to uppercase. The editor displays each line changed.
When the EOF: message indicates that the end of the file is reached, you can save
the changes made during this edit session with the SAVE subcommand before
continuing.
Move the current line pointer to point to the first line in the file. You want to
add an entry that is similar; use the $DUP edit macro to duplicate the line, then
change the copy that you made of the line.
You can change the word name to filename in the next line also.
You can scan a file, a line at a time, by issuing successive NEXT subcommands.
To insert a line beginning with the character M, and to maintain alphabetic
sequencing, use the FIND subcommand to find the first line beginning with an M. The
line to be inserted begins with the characters 8A, so you want to move the line
pointer up.
You can insert a single line into a file with the INPUT subcommand. Bere, the INPUT
subcommand is truncated to I, so that when you space over to write the co.mand name
in the right column, you can align it (you only have to allow for the two character
spaces use by "i ".
.
Sample Terminal Session Using the CMS Editor and CMS File System Commands
359
45
/COPYFILE
Copy CMS files
46
n
COPYFILE
EDIT
Create a CMS file
n
TYPE
Display the contents of a CMS file at your terminal
n
TAPE DUMP
Dump CMS files onto tape
n
47
ERASE
Erase a CMS file
up 3
Create a CMS file
i Delete a file from a CMS disk
file
EDIT
ERASE
R;
48
type function sort a
Alter the name of a CMS file
Alter the filetype of a CMS file
Change the filename of a CMS file
RENAME
RENAME
RENAME
Verify the existence of a CMS file on a read/write disk
STATEW
R;
49
50
45
46
47
48
49
50
360
edit function sort
zone 58
change I II * *
Alter the name of a CMS file
Alter the filetype of a CMS file
Change the filename of a CMS file
RENAME
RENAME
RENAME
Verify the existence of a CMS file on a read/write disk
EOF:
top
TOF:
change 1/1 I *
Alter the name of a CMS file
Alter the filetype of a CMS file
Change the filename of a CMS file
STATEW
Verify the existence of a CMS file on a read/write disk
EOF:
I STATEW
RENAME
RENAME
RENAME
Move the line pointer to the top of the file and begin scanning again. A diagonal
e/) is interpreted as a LOCATE subcommand.
The NEXT subcommand can be truncated to "N".
In front of the line beginning "Display", insert a line beginnirig with "Delete". If
you want to make any other modifications, do so. Otherwise, write this file onto
disk with the FILE subcommand.
Verify your changes.
Edit the file again. To compress unnecessary spaces in right hand columns, change
the zone setting. This time, issue a CHANGE subcommand that will delete all blank
spaces occuring after column 58. Since some changes you made to the file might have
spoiled the alignment in the command column, this CHANGE subcommand should realign
all of the columns.
Return the current line pOinter to the top of the file. Change a null string to the
string "I " for all lines in the file; since the left zone is still column 58, the
characters are inserted in columns 58 and 59.
IBM VM/370 CMS User's Guide
(
51
zone 1 *
top
TOF:
c //1 / *
Alter the name of a CMS file
Alter the filetype of a CMS file
Change the filename of a CMS file
.
52
53
54
55
verify the existence of a CMS file on a read/write disk
EOF:
top
TOF:
next
Alter the name of a CMS file
tabset 72
repeat *
overlay I
Alter the name of a CMS file
Alter the filetype of a CMS file
Change the filename of a CMS file
Compare the contents of CMS disk files
I STATEW
Verify the existence of a CMS file on a read/write disk
EOF:
bottom
Verify the existence of a CMS file on a read/write disk
input
zone 1 72
c / /-/ 1 *
STATEW
top
TOF:
input
c /
56
RENAME
RENAME
RENAME
/-/ 1
I RENAME
RENAME
RENAME
RENAME
COMPARE
I STATEW
*
file
R;
print function sort
R;
51
52
53
54
)
55
56
Change the left zone setting to column 1 and let the right zone be equal to the
record length; issue the CHANGE subcommand to insert the "I" in columns 1 and 2.
CHANGE can be abbreviated as "C".
At the top of the file, change the TABSET subcommand setting to 72. This makes
column 12 the left margin. The REPEAT * subcommand, followed by the OVERLAY
subcommand, indicates that all the lines in the file are to be overlaid with a I in
the leftmost column (column 72).
When you enter this INPUT subcommand, enter a number of blank spaces following it;
this places a blank line in the file.
Reset the ZONE setting to columns 1 and 72. The CHANGE subcommand indicates that all
blanks on this line should be changed to hyphens (-). Only the blanks within the
specified zone are changed.
Insert another blank line at the top of the file and change it to hyphens.
Write the file onto disk and use the CMS PRINT command to spool a copy to the
offline printer.
Sample Terminal Session Using the CMS Editor and CMS File System Commands
361
Sample Terminal Session Using Line-Number Editing
This terminal session shows how a terminal session using right-handed line-number editing
might appear on a typewriter terminal. The commands function the same way on a display
terminal, but the display is somewhat different. When you enter these input lines, you
should have physical tab stops set at your terminal at positions 16 and 22 (for assembler
columns 10 and 16; the difference compensates for the line numbers, as you will see). On
a display terminal, tab settings have no significance; once the line is in the output
display area, it has the proper number of spaces.
1
2
3
edit test assemble
NEW FILE:
EDIT:
linemode right
input
INPUT:
00010 * sample of linemode right
00020 test
csect
00030
balr 12,0
00040
using *,12
00050
st
14,sav14
00060
wrtera testing •••
00070
I
14,sav14
br
14
00080
00090
end
00100
4
5
6
7
1
2
3
4
5
6
7
362
EDIT:
60
00060
WRTERM
c /testing ••• /·testing ••• •
WRTERM
00060
80
BR
14
00080
input
INPUT:
TESTING •••
·TESTING ••• •
Use the EDIT command to invoke the CMS editor. Since this is a new file, the editor
issues the NEW FILE message.
Issue the LINEMODE subcommand to indicate that you want to begin line-number
editing .• For ASSEMBLE files, you cannot have line numbers on the left, because the
assembler expects data in columns 1 through 7.
As soon as you issue the INPUT subcommand, the editor begins prompting you to enter
input lines. For convenience in entering lines, the line numbers appear on the left,
as they would if you were using left-handed line-number editing.
In your ASSEMBLE
file, however, the line numbers are actually on the right.
When you are have finished entering these input lines, enter a null line to return
to edit mode from input mode.
To locate lines when you are using line-number ~diting, you can enter the line
number of the line. In this case, enter 60 to position the current line pOinter at
the line numbered 00060 •. The editor displays the line.
Issue the CHANGE subcommand to place quotation marks around the text line for the
WRTERM macro. The editor redisplays the line, with the change.
Issue the nnnnn subcommand, specifying line number 80, and use the INPUT subcommand
so you can begin entering more input lines.
IBM VM/370 CMS User's Guide
(
8
9
10
11
12
13
14
15
16
8
9
10
11
12
13
14
15
)
16
00083 sav14
00085 wkarea
00081 flag
00088 runon
00089 runoff
RENUftBER LINES
EDIT:
linemode off
serial on abc
save
EDIT:
linellode right
type
00030 RUNOFF
verify 1 *
type
00030 RUNOFF
135
50
00050
input
INPUT:
00053
00055
00051
ds
ds
ds
equ
equ
BQU
f
3d
x
x'80'
x'40'
X'40'
EQU
X'40'
runaix
equ x'20'
ST
14,SAV14
tm
bcr
flag,runon
1,14
EDIT:
top
TOF:
next
* SlftPLE OF LINEftODE RIGHT
restore
IBC00130
IBCOO050
ABCOO010
When you begin entering input lines between two existing lines, the editor uses an
algorithm to assign line nuabers.
The editor ran out of line numbers, since the next line in the file is already
numbered 90. You must renumber the lines. Before you can renumber the lines, you
must turn line-number editing off. Before issuing the SlVE subcollmand, which writes
the file and its new line numbers onto disk, you can issue the SERIIL subcommand.
SERIAL ABC indicates that you want the characters ABC to appear as the first three
characters of each serial number.
The EDIT message indicates that the SlVE request has completed.
Issue the LINEftODE subcommand to restore line-number editing.
Use the TYPE
subcommand to verify the position of the current line pointer.
If you want to see the serial numbers in columns 12 through 80, issue the VERIFY
subcommand, specifying *, or the record length.
Normally, the editor does not
display the columns containing serial numbers While you are editing.
.
You can use the nnnnn subcommand to insert individual lines of text. This subcommand
inserts a line that you want numbered 135, and places it in its proper position in
the file.
Note that although, in this example, the current line pOinter is
positioned at line 130, it does not need to be at the proper place in the file. When
the subcomaand is complete, however, the current line pointer is positioned
following the line just inserted.
position the line pointer at the line numbered 50, and again begin entering the
input lines indicated.
Enter a null line to return to edit mode, move the current line pointer to the top
of the file, and display the first line.
The RESTORE subcommand restores the default settings of the editor, and the the
verification columns are restored to 1 and 12, so that line numbers are not
displayed in columns 12 through 80.
Sample Terminal Session Using Line-Number Editing
363
17
18
19
type *
* SAftPLE OF LINEftODE RIGHT
TEST
CSECT
BALR 12,0
USING *,12
ST
14,SAV14
Tft
FLAG,RUNON
1,14
BCR
WRTERft
L
14,SAV14
14
BR
SAV14
DS
F
DS
3D
WKAREA
FLAG
DS
X
RUNON
EQU
X' 80'
RUNOFF
EQU
X'40'
EQU
RUNMIX
X'20'
END
EOF:
file
RESERIALIZATION SUPPRESSED
R;
type test assemble
* SAftPLE OF LINEftODE RIGHT
TEST
START X'20000'
BALR 12,0
USING *,12
14,SAV14
ST
FLAG,RUNON
TM
1,14
BCR
TYPE 'TESTING.~.'
14,SAV14
L
14
BR
SAV14
DS
F
WKAREA
DS
3D
FLAG
DS
X
EQU
RUNON
X' 80'
RUNOFF
EQU
X'40'
RUNMIX
EQU
X'20'
END
17
18
19
364
'TESTING •••
,
ABCOO010
ABCOO020
ABCOO030
ABCOO040
ABCOO050
00053
00055
ABCOO060
ABCOO070
ABCOO080
ABCOO090
IBC00100
IBC00110
ABCOO120
IBCOO130
00135
IBCOO140
Use the TYPE subcommand to display the file.
When you issue the FILE subcomm"and to write the file onto disk, the editor issues
the message RESERIALIZATION SUPPRESSED to indicate that it is not going to update
the line numbers, so that the current line numbers match the line numbers as they
existed when the SAVE subcommand was issued.
If you want to see how the file exists on disk, use the CftS TYPE command to display
the file. Note that the lines inserted after the SAVE subcommand do not have the
initial ABC characters, and that they retain the line nu.bers they had when they
were inserted.
IBM VM/370 CftS User's Guide
I
(~
Sample Terminal Session for OS Programmers
The following terminal session shows how you might create an assembler language program
in CMS, assemble it, correct assembler errors, and execute it. All the lines that appear
in lowercase are lines that you should enter at the terminal. Uppercase data represents
the system response that you should receive when you enter the command.
The input data lines in the example are aligned in the proper columns for the
assembler; if you are using a typewriter terminal, you should set your terminal's tab
stops at columns 10, 16, 31, 36, 41, and 46, and use the Tab key when you want to enter
text in these columns. If you are using a display terminal, when you use a PF key defined
as a tab, or some input character, the line image is expanded as it is placed in the
screen output area.
There are some errors in
errors in CMS.
)
the terminal session,
so that you
can see how
to correct
1
edit ostest assemble
NEW FILE:
EDIT:
input
INPUT:
dataproc csect
print nogen
space
rO
equ
0
r1
equ
1
r2
equ
2
r10
equ
10
r12
equ
12
r13
equ
13
r14
equ
14
r15
equ
15
space
stm
r14 ,r12, 12 (r13)
save caller's regs
balr r12,0
establish
using *,r12
addressability
st
r13,savearea+4 store addr of caller's savearea
la
r15,savearea
get the address of my savearea
st
r15,8(r13)
store addr in caller's savearea
lr
r13,r15
save addr of my savearea
space
*open files and check that they opened okay
space
r3,0
initially set return code
la
open (indata,outdata,(output»
open files
using ihadcb,r10
get dsect to check files
la
r10,indata
prepare to check output file
dcboflgs,x'10' everything ok?
tm
bnz
checkout
.~.continue
la
r3,100
set return code
exit
••• exit
b
checkout la
r10,outdata
check output file
tm
dcboflgs,x'10' is it okay?
process
bnz
la
r3,200
set return code
exit
b
1
The EDIT command is issued to create a file named OSTEST ASSEMBLE. Since the file
does not exist, the editor indicates that it is a new file and you can use the INPUT
subcommand to enter input mode and begin entering the input lines.
Sample Terminal Session for OS Programmers
365
space
equ
get
lr
put
b
space
equ
exit
close
1
lr
1
1m
br
space
savearea dc
indata
dcb
process
*
indata
r2,rl
outdata,(2)
process
read a record from input file
save address of record
move it to output
continue until end-of-file
*(indata"outdata)
r13,savearea+4
r15,r3
r14,12(r13)
rO,r12,20(r13)
r14
close files
addr of caller's save area
load return code
get return address
restore regs
bye •••
18f'0'
ddname=indd,macrf=gl,dsorg=ps,recfm=f,lrecl=80,
2
3
EDIT:
$mark
savelinput
EDIT:
INPUT:
outdata
eodad=exit
dcb
ddname=outdd,macrf=pm,dsorg=ps
dcbd
space
end
4
EDIT:
file
R;
5
global mac lib osmacro
R;
6
assemble ostest
*
*
*
*
*
**
2
3
4
5
6
366
Since the DCB macro statement takes up more than one line, you have to enter a
continuation character in column 12. To do this, you can enter a null line to return
to edit mode and execute the $ftARK edit macro, which places an asterisk in column
12. If the $ftARK edit macro is not on your system, you will have to enter a
continuation character some other way.
(See "Entering a continuation Character in
Column 12" in "Section 5. The CftS Editor.")
Before continuing to enter input lines, the EDIT subcommand SAVE is issued to write
what has already been written onto disk. The CP logical line end symbol
(I)
separates the SAVE and INPUT subcommands.
A null line returns you to edit mode. You may wish, at this point, to proofread
your input file before issuing the FILE subcommand to write the ASSEftBLE file onto
disk.
Since this assembler program uses OS macros, you must issue the GLOBAL command to
identify the CftS macro library, OS8ACRO 8ACLIB, before you can invoke the assembler.
The ASSEBBLE command invokes the V8/310 assembler to assemble the source file; the
asterisks (*) indicate the CftS blip character, which you mayor may not have made
active for your virtual machine.
IB8 V8/310 CftS User's Guide
March 30, 1979
7
8
ASSEMBLER DONE
OST00230
23
LA
R3,0
INITIALLY SET RETURN CODE
IF0188 R3 IS AN UNDEFINED SYMBOL
OST00240
24
OPEN
(INDATA,OUTDATA,(CUTPUT»
OPEN FILES
4000000
27+
12,*** IHB002 INVALIt OPTION OPERAND SPECIFIED-OUTDATA
IF0197 *** MNOTE ***
OST00290
32
LA
R3,100
SET RETURN CODE
IF0188 R3 IS AN UNDEFINED SYMBOL
OST00340
37
LA
R3,200
SET RETURN CODE
IF0188 R3 IS AN UNDEFINED SYMBOL
OST00460
63
LR
R15,R3
LOAD RETURN CODE
IF0188 R3 IS AN UNDEFINED SYMBOL
NUMBER OF STATEMENTS FLAGGED IN THIS ASSEMELY =
5
R (00012) i
edit ostest assemble
locate Ir2
R2
EQU
2
i r3
equ
3
lopen
OPEN
(INDATA,OUTDATA,(OUTPUT»
OPEN
(INDATA"OUTDATA, (OUTPUT»
OPEN FILES
c 1,1,,1
9
OPEN FILES
file
Ri
assemble ostest
*
*
*
*
*
*
10
ASSEMBLER DONE
NO STATEMENTS FLAGGED IN THIS ASSEMBLY
Ri
11
filedef indd disk test data a
Ri
12
filedef outdd punch
R;
13
#cp spool punch to *
7
The assembler displays errors encountered during ass~mbly. Depending on how
accurately you copied the program in this sample session, you mayor may not receive
some of these messages; you may also have received additional messages.
You must edit the file OS TEST ASSEMBLE and correct any errors in it. The errors
placed in the example included a missing comma on the OPEN macro, and the omission
of an EQU statement for a general register. These changes are made as shown. The
CMS editor accepts a diagonal (I) as a LOCATE subcommand.
After all the changes have been made to the ASSEMBLE file, you can issue the FILE
subcommand to replace .the existing copy on disk, and then reassemble it.
This time, the assembler completes without encountering any errors.
If your
ASSEMBLE file still has errors, you should use the editor to correct them.
The FILEDEF command is used to define the input and output files used in this
program. The ddnames INDD and OUTDD, defined in the DCBs in the program, must have a
file definition in CMS. To execute this program, you should have a file on your
A-disk name TEST DATA, which must have fixed-length, 80-charaqter records.
If you
have no such file, you can make a copy of your ASSEMBLE file as follows:
8
9
10
11
copy file ostest assemble a test data a
12
13
The output file is defined as a punch file, so that it will be written to your
virtual card punch.
The CP SPOOL command is issued, using the #CP function, to spool your virtual punch
to your virtual card reader. When you use the iCP function, you do not receive a
Ready message.
Sample Teiminal Session for OS Programmers
367
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 ,for
14
5748~XX8
load ostest
R;
15
16
start
DMSLI07401 EXECUTION BEGINS •••
DMSSOP036E OPEN ERROR CODE '04' ON 'OUTDD '
R(00200);
filedef
INDD
DISK
TEST
DATA
A1
OUTDD
PUNCH
R;
17
filedef outdd punch (lrecl 80 recfm f
R;
18
19
20
#cp query reader all
NO RDR FILES
load ostest (start
DMSLI07401 EXECUTION BEGINS •••
PUN FILE 6198 TO BILBO
COpy 01 NOHOLD
R;
21
fi indd reader
R;
fi outdd disk new osfile a4 (recfm fb block 1600 lrecl 80
R;
22
23
listfile new osfile a4 (label
DMSLST002E FILE NOT FOUND.
R(00028);
run ostest
EXECUTION BEGINS •••
*R;
24
listfile new osfile a4 (label
FILENAME FILETYPE FM FORMAT
NEW
OSFILE
A4 F
LRECL
1600
RECS fLOCKS
5
10
DATE
9/30/75
TIME
8:26:14
LABEL
PAT198
R;
14
15
16
17
18
19
20
21
22
23
24
368
The LOAD command loads the TEXT file produced by the assembly into virtual storage.
The START command begins program execution.
An open error is encountered during program execution.
The CMS ready message
indicates a return code ot 200, which is the value placed in it by your program.
The FILEDEF command, with no operands, results in a display of the current file
definitions in effect.
Error code 4 on an open request means that no RECFM or LRECL information is
available. An examinat~on of the program listing would reveal that the DCB for
OUTDD does not contain any information about the file format; you must supply it on
the FILEDEF command. Re-enter the FILEDEF command.
You can use the CPQUERY bommandto determine whether there are any files in your
card reader. It should be empty; if not, determine whether they might be files you
need, and if ~o, read them into your virtual machine; otherwise, Furge them.
Use the LOAD command to execute the program again; this time, use the START option
of the LOAD command to begin the program execution.
The PUN FILE message indicates that a file has been transferred to your virtual card
,reader. The ready message indicates that your program executed successfully.
For the next execution of this program, you are going to read the file back out of
your card reader and create a new CMS disk file, in OS simulated data set format.
FI is an acceptable system truncation for the command name, FILEDEF.
The LISTFILE command is issued to check that the file NEW OSFILE does not exist.
The RUN command (which is an EXEC procedure) is used instead of the LOAD and START
commands, to load and execute the program. The ready message indicates that the
'program completed execution.
The LISTFILE command is issued again, and the file NEW OSFILE is ,listed.
(If you
issue another CP QUERY READER command, you will also see that the file is no longer
in your card reader.)
IBM VM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30. 1979 by Supp_ SD23-9024-1 for 5148-118
Sample Terminal Session for DOS Programmers
The following terminal session shows how you might create an assembler language program
in CMS. assemble it, correct assembler errors. and execute it. All the lines that appear
in lowercase are lines that you should enter at the terminal. Uppercase data represents
the system response that you should receive when you enter the command.
The input data lines in the example are aligned in the proper columns for the
assembler; if you are using a typewriter terminal. you should set your terminal's tab
stops at columns 10, 16. 31, 36. 41, and 46 and use the Tab key when you want to enter
text in these columns. If you are using a display terminal. when you use a PF key or an
input character defined as a tab. the line image is expanded as it is placed in the
screen output area.
Note: The assembler, in CMS. cannot read macros from DOS/VSE libraries.
This sample
terminal session shows how to copy macros from DOS/VSE libraries and create CMS MACLIB
files. Ordinarily, the macros you need should already be available in a system MACLIB
file.
You do not have to create a MACLIB each time you want to assemble a program.
There are some errors in
errors in CMS.
1
the terminal session.
so that you
can see how
to correct
cp link dosres 130 130 rr linkdos
DASD 130 LINKED R/O
R;
2
access 130 z
Z (130) R/O - DOS
R;
set dos on z
R;
3
edit dostest assemble
NEW FILE:
EDIT:
input
INPUT:
begpgm
csect
balr 12,0
using *,12
la
13,savearea
open infile,outfile
loop
get
infile
put
outfile
b
loop
eodad
equ
*
close infile,outfile
eoj
eject
buffer
dc
CL80' ,
infile
dtfdi modname=shrmod.ioarea1=buffer.devaddr=sysipt.
1
Use the CP LINK command to link to the DOS system residence volume and the ACCESS
command to access it. In this example, the system residence is at virtual address
130 and is accessed as the Z-disk.
Enter the CMS/DOS environment. specifying the mode letter at which the DOS/VSE
system residence is accessed.
Use the EDIT command to create a file named DOSTEST ASSEMBLE.
Since the file does
not exist, the editor indicates that it is a new file and you can use the INPUT
subcommand to enter input mode and begin entering the input lines.
2
3
Sample Terminal Session for DOS Programmers
369
March 30, 1979
4
5
EDIT:
$mark
save#input
EDIT:
INPUT:
outfile
eofaddr=eodad,recsize=80
dtfdi modname=shrmod,ioarea1=buffer,devaddr=syspch,
6
EDIT:
$mark
save.input
EDIT:
INPUT:
shrmod
endpgm
recsize=81
dimod typefle=output
equ
*
end
7
EDIT:
file
R;
8
9
edit getmacs eserv
NEW FILE:
EDIT:
tabs 2 72
input
INPUT:
punch open,close,get,put,dimod,dtfdi
EDIT:
file
R;
10
assgn sysipt a
R;
eserv getmacs
R;
4
5
6
7
8
9
10
370
Since the DTFDI macro statement takes up more than one line, you have to enter a
continuation character in column 72. To do this, you can enter a null line to return
to edit mode and execute the $MARK edit macro, which places an asterisk in column
72. If the $MARK edit macro is not on your system, you will have to enter a
continuation character some other way.
(See "Entering a Continuation Character in
Column 72" in "Section 5. The CMS Editor.")
Before continuing to enter input lines, the EDIT subcommand SAVE is issued to write
what has already been written onto disk. The CP logical line end symbol
(#)
separates the SAVE and INPUT subcommands.
Another continuation character is needed.
A null line returns you to edit mode. You may want, at this point, to proofread your
input file before issuing the FILE subcommand to write the ASSEMBLE file on disk.
To obtain the macros you need to assemble this file, use the editor to create an
ESERV file. By setting the logical tabs at columns 2 and 72, you can protect
yourself from entering data in column 1.
PUNCH is an ESERV program control statement that copies and de-edits macros from
source statement libraries; in this case, the system source statement library. The
output is directed to the SYSPCH device, which the CMS/DOS ESEBV EXEC assigns by
default to your A-disk.
You must assign the logical unit SYSIPT before you invoke the ESEBV co.mand. GETMACS
is the filename of the ESERV file containing the ESERV control statements.
IBM VM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-118
11
listfile
GETMACS
GETMACS
GETMACS
getmacs
ESERV
MACRO
LISTING
*
A1
A1
A1
R;
12
maclib gen dosmac getmacs
R;
erase getmacs
R;
13
*
global maclib dosmac
R;
14
assemble dostest
*
*
15
16
17
ASSEMBLER DONE
DOS00040
4
LA
13,SAVEAREA
IF0188 SAVEAREA IS AN UNDEFINED SYMBOL
DOS00110
35
EOJ
IF0078 UNDEFINED OP CODE
NUMBER OF STATEMENTS FLAGGED IN THIS ASSEMELY
R (00008) ;
edit dotest assemble
EDIT:
locate /buffer/
BUFFER
DC
CL80"
input savearea ds
9d
file
R;
edit eoj eserv
NEW FILE:
EDIT:
i
punch eoj
file
2
R;
18
listio sysipt
SYSIPT DISK
A
R;
eserv eoj
R;
11
12
13
14
15
16
17
18
After the ESERV EIEC completes execution, you have three files.
You may want to
examine the LISTING file to check the ESERV program listing.
The MACRO file
contains the punch (SYSPCH) output.
The MACLIB command creates a macro library named DOSMAC MACLIB.
Since the MACLIE
command completed successfully, you can erase the files GETMACS ESERV. GETMACS
LISTING, and GETMACS MACRO; an asterisk in the filetype field of the ERASE command
indicates that all files with the filename ef GETMACS should be erased.
Before you can invoke the assembler, you have to identify the macro library that
contains the macros; use the GLOBAL command, specifying DOSMIC MICLIE.
The ASSEMBLE command invokes the VM/370 assembler to assemble the source file; the
.asterisks (*) indicate the CMS blip character, which you may o~ may not have made
active fer your virtual machine.
The assembler displays errors encountered during assembly. Depending on how
accurately you copied the program in this sample session, you mayor may not receive
some of these messages; you may also have received additional messages.
To correct the first error, which was the omission of a DS statement for SAVEAREI,
edit the file DOSTEST ASSEMBLE and insert the missing line.
The second error indicates that the macro EOJ is not available, since it was not
copied from the source statement library. Create another ESERV file to punch this
macro.
Use the LISTIO co.m~nd to check that SYSIPT is still assigned to your A-disk, so
that you do not have to issue the ASSGN command again. Then issue the ESERV command
again, this time specifying the filename EOJ.
Sample Terminal Session for DOS Programmers
371
March 30, 1979
19
maclib add dosmac eoj
Ro,
maclib map dosmac (term
MACRO
INDEX SIZE
2
43
OPEN
CLOSE
46
43
GET
90
56
147
93
PUT
241
DIMOD
647
889
284
DTFDI
1174
6
EOJ
R;
20
erase eoj
R;
*
assemble dostest
*
*
*
21
ASSEMBLER DONE
NO STATEMENTS FLAGGED IN THIS ASSEMBLY
R;
22
listfile
DOSTEST
DOSTEST
DOSTEST
dostest *
ASSEMBLE A1
LISTING A1
TEXT
A1
R;
print dostest listing
R;
23
doslked dostest
R;
24
listfile
DOSTEST
DOSTEST
DOSTEST
DOSTEST
DOS TEST
dostest *
ASSEMBLE A1
DOSLIB
A1
TEXT
A1
LISTING A1
MAP
AS
R;
19
20
21
22
23
24
372
Use the ADD function of the MACLIB command to add the macro EOJ to DOSMAC MACLIE.
Then, issue the MACLIB command again, using the MAP function and the TERM option to
display a list of the macros in the library.
Erase the EOJ files. You should always remember to erase files that you do not need
any longer. Reassemble the program.
This time, the assembler . completes without encountering any errors.
If your
ASSEMBLE file still has errors, you should use the editor to correct them.
Use the LISTFILE command to check for DOSTEST files. The assembler created the
files, DOSTEST LISTING and DOSTEST TEXT. The TEXT file contains the object module.
You can print the program listing, if you want a printed copy. Then, you may want to
erase it.
Use the DOSLKED command to link-edit the TEXT file into an executable phase and
write it into a DOSLIB. Since this program has no external references, you do not
need to add any linkage editor control statements.
NOw, you have a DOSTEST DOSLIB, containing the link-edited phase, and a MAP file,
containing the linkage editor map. You can display the linkage editor map with the
TYPE command, or use the PRINT command if you want a printed copy.
rBM VM/370 CMS User's Guide
Pg. of GC20-1819-2 Rev "arch 30, 1979 by Supp. SD23-9024-1 for 5148-118
25
Icp spool punch to *
punch test data a
PUN FILE 0100 TO BILBO
COpy 01 NOHOLD
R;
26
#cp query reader all
ORIGINID FILE CLASS RECDS CPY HOLD DATE TIME
NAME
PATTI
5840 A PUN 000097 01 NONE 09/29 15:00:39 TEST
assgn sysipt reader
TYFE
DATA
DIST
BIN211
R;
assgn syspch a
R;
21
dlbl outfile a cms punch output (syspch
R;
28
state punch output a
DMSSTT002E FILE NOT FOUND.
R (00028) ;
global doslib dostest
R;
fetch dostest
DMSFET710I PHASE 'DOSTEST' ENTRY POINT AT LOCATION 020000.
R;
29
start
DMSLI07401 EXECUTION BEGINS •••
R;
listfile punch output a (label
FILENAME FILETYPE FM FORMAT LRECL
PUNCH
OUTPUT
A1 F
80
RECS ELOCKS
97
10
DATE
TIME
9/29/75 14:50:55
LABEL
BBB191
R;
#cp query reader all
NO RDR FILES
25
To execttte this program in CMS/DOS, punch a file that has fixed-length 80-character
records into your virtual card punch.
If you do not have any files that have
fixed-length, aO-character records, you can create a file named TEST DATA with the
CMS editor, or by copying your ASSEMBLE source file with the CCPYFILE command, as
follows:
copy file dostest assemble a test data a
26
21
28
29
Use the CP SPOOL command to spool the punch to your own virtual machine, then use
the PUNCH command to punch the file. The PUN FILE message indicates that the file
is in your card reader.
Use the CP QUERY command to check that it is the first, or
only file in your reader.
Use the ASSGN command to assign SYSIPT to your card reader and SYSPCH to your
A-disk.
When you assign a logical unit to a disk mode, you must issue the DLBL command to
identify the disk file to CMS. For this program execution, you are creating a CMS
file named PUNCH OUTPUT.
The STATE command ensures that the file does not already
exist. If it does exist, rename it, or else use another filename or filetype on the
DLBL command.
Use the GLOBAL command to identify the tOSLIB, DOSTEST, you ~ant to search for
executable phases, then issue the FETCH command specifying the phase name. The
FETCH command loads the executable phase into storage. When the FETCH ccmmand is
executed without the START option, a message is displayed indicating the entry point
location of the program loaded.
The START command begins program execution.
The CMS ready message indicates that
your program completed successfully. YOl) can check the input and output activity by
using the LISTFILE command to list the file PUNCH OUTPUT. If you use the CP QUERY
command, you can see that the file is no longer in your virtual card reader.
Sample Terminal Session for DOS Programmers
373
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-XX8
30
assgn sysipt a
R;
dlbl infile a cms punch output (sysipt
R;
assgn syspch punch
R;
31
32
fetch dostest (start
DMSLI07401 EXECUTION BEGINS •••
PUN FILE 5829 TO BILBO
COpy 01 NOHOLD
R;
read punch2 output
R;
listfile punch2 output a (label
FILENAME FILETYPE FM FORMAT LRECL
PUNCH2
OUTPUT
A1 F
80
RECS fLOCKS
97
10
DATE
TIME
9/29/75 14:50:59
LABEL
BBB191
R;
30
31
32
374
If you want to execute this program again, you can assign SYSIPT and SYSPCH to
different devices; in this example, the input disk file PUNCH OUTPUT is written to
the virtual punch. You do not need to reissue the GLOBAL DOSLIB command; it remains
in effect until you reissue it or IPL CMS again.
This time, the program execution starts immediately, because the START option is
specified on the FETCH command line.
Again, the PUN FILE message indicates that a file has been received in your virtual
card reader. You can use the CMS command READCARD to read it onto disk and assign it
a filename and filetype, in this example, PUNCH2 OUTPUT.
IBM VM/370 CMS User's Guide
Sample Terminal Session Using Access Method Services
This sample terminal session shows you how to use access method services under CMS. You
should have an understanding of VSAM and access method services before you use this
terminal session.
The terminal session uses a number of CMS files, which you may create during the
course of the terminal session; or, you may prefer to create all of the files that you
need beforehand. Within the sample terminal session, the file that you should create is
displayed prior to the commands that use it.
This terminal session is for both
programmers; all the ASSGN commands and
environment is active are shaded. If you
enter the shaded entries; if not, you must
CMS OS VSAft programmers and CftS/DOS VSAft
SYSxxx operands that apply when the CftS/DOS
have issued the command SET DOS ON, you must
omit the shaded entries.
!!gte§:
1.
This terminal session assumes that you have, to begin with, a read/write CMS A-disk.
This is the only disk required. Additional disks used in this exercise are temporary
disks, formatted with the IBCDASDI disk initialization program under CMS. If you
have OS or DOS disks available, you should use them, and remember to supply the
proper volume and virtual device address information, where appropriate. The number
of cylinders available to users for temporary disk space varies among installations;
if you cannot acquire ample disk space, see your system support personnel for
assistance.
2.
Output listings created by AMSERV take up disk space, so if your A-disk does not
have a lot of space on it, you may want to erase the LISTING files created after
each AMSERV step •.
3.
If any of the ABSERV commands that you execute during
issue a nonzero return code; for example:
this sample terminal session
R(00012);
You should edit the LISTING file to examine the access method services error
messages. The publication QQ~!§ !~§§§g~§ contains the return codes and reason codes
issued by access method services. You should determine the cause of the error,
examine the DLBL commands and ABSERV files you used, correct any errors, and retry
the command.
),
1
Icp define t3330
DASD 200 DEFINED
Icp define t3330
DASD 300 DEFINED
#cp define t3330
DASD 400 DEFINED
1
These commands
400.
200
010
300
010
400
010
10
CYL
10
CYL
10
CYL
define temporary 3330
mindisks at
virtual addresses 200,
300, and
Sample Terminal Session Using Access Method Services
315
2
File: PUNCH IBCDASDI
222222
333333
444444
3
JOB
ftSG TODEV=1052,TOADDR=009
DADEF TODEV=3330,TOADDR=200,VOLID=SCRATCH,CYLNO=10
VLD NEWVOLID=222222
VTOCD STRTADR=10,EXTENT=5
END
JOB
ftSG TODEV=1052,TOADDR=009
DADEF TODEV=3330,TOADDR=300,VOLID=SCRATCH,CYLNO=10
VLD NEWVOLID=333333
VTOCD STRTADR=10,EXTENT=5
END
JOB
ftSG TODEV=1052,TOADDR=009
DADEF TODEV=3330,TOADDR=400,VOLID=SCRATCH,CYLNO=10
VLD NEWVOLID=444444
VTOCD STRTADR=10,EXTENT=5
END
File: IBCDASDI EXEC
&CONTROL OFF
CP CLOSE C
CP PURGE RDR ALL
ACC 190 Z/Z IPL *
CP SPOOL D CONT *
PUNCH IPL IBCDASDI Z ( NOH
PUNCH PUNCH IBCDASDI * ( NOH
CP SPOOL PUNCH NOCONT
CP CLOSE PUNCH
CP IPL OOC
4
5
2
3
4
5
376
ibcdasdi
NO FILES PURGED
DftSACC7231 Z (190) R/O
DftSACC7231 190 ALSO = S-DISK
PUN FILE 1492 TO BILBO COpy 01 NOHOLD
IBC105A DEFINE INPUT DEVICE. DASDI 7.77
input=2540,00c
This file contains control statements for the IBCDASDI program, which formats and
initializes disks for OS and DOS. These disks are labelled 222222, 333333, and
444444. Any messages produced by the IBCDASDI program are sent to your terminal.
This file contains the commands necessary to use the IBCDASDI program under CftS. You
must punch a copy of the IBCDASDI program, followed by the file containing your
control statements, to your virtual card reader, and then load the IBCDASDI program.
This is all done in the file IBCDASDI EXEC.
Execute the IBCDASDI EXEC. The last command in the EXEC is the IPL command, which
passes control to the IBCDASDI program. The message IBC105A prompts you to enter
the address of the control statements.
Since the control statements are in your card punch, you indicate the device type
(2540) and the address (OOC) on the INPUT= statement.
IBft Vft/370 CftS User's Guide
(
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp. SD23-9024-1 for 5748-118
6
DASDI 7.77
JOB
MSG TODEV=1052,TOADDR=009
DADEF TODEV=3330,TOADDR=200,VOLID=SCRATCH,CYLNO=10
VLD NEWVOLID=222222
VTOCD STRTADR=10,EXTENT=5
END
IBC163A END OF JOB.
DASDI 7.77
333333 JOB
MSG TODEV=1052,TOADDR=009
DADEF TODEV=3330,TOADDR=300,VOLID=SCRATCH,CYLNO=10
VLD NEWVOLID=333333
VTOCD STRTADR=10,EXTENT=5
END
IBC163A END OF JOB.
DASDI 7.77
444444 JOB
MSG TODEV=1052,TOADDR=009
DADEF TODEV=3330,TOADDR=400,VOLID=SCRATCH,CYLNO=10
VLD NEiVOLID=444444
VTOCD STRTADR=10,EXTENT=5
END
IBC163A END OF JOB.
DMKDSP450W CP ENTERED; DISABLED WAIT PSi 'OC060000 OOOOEEEE'
ipl cms
CMS ••• VERSION 3.0 02/28/76
222222
7
8
9
10
6
7
8
9
10
a
DMSACC7231 B
Ro,
access 300 c
DMSACC7231 C
R;
access 400 d
DMSACC7231 D
R;
query search
191
BBB191
222222 200
333333 300
444444 400
CMS190 190
(200) R/Ttl - OS
(300) R/i - OS
(400) R/ll - OS
A
B
C
D
S
R/i
R/W - OS
R/W - OS
R/ll - OS
These messages are issued by the IBCDASDI program, which displays the statements
executed and indicates the end of each job.
When the last IBCDASDI job 1S complete, your virtual machine is in the CP
environment and you must reload the CMS system before you can continue.
If you are a CMS/DOS user, you must reaccess the DCS/VSE system residence volume and
issue the SET DOS ON command line, specifying the VSAM option. If you have not
previously linked to the system residence, you must use the CP LINK command before
you issue the ACCESS command.
Access the three newly formatted disks as your B-, C-, and D-disks.
You can issue the QUERY SEARCH command to verify the status of all disks you
currently have accessed.
Sample Terminal Session Using Access Method Services
377
March 30, 1979
11
File: MASTCAT AMSERV
DEFINE MASTERCATALOG (MASTCAT)
( NAME
VOLUME (222222) CYL (4) UPDATEPW (GAZELLE) FILE IJSYSCT) )
12
(IIIIII!
sysct
dsn mastcat
perm extent
DMSDLB331R ENTER EXTENT SPEC:t'Flc'Jfi"IONS:
19 171
13
R;
14
amserv mastcat
R;
15
File: CLUSTER AMSERV
DEFINE CLUSTER ( NAME (BOOK. LIST ) VOLUMES (222222) TRACKS (20) FILE (BOOK) KEYS (14,0) RECORDSIZE (120,132) ) DATA (NAME (BOOK.LIST.DATA) ) INDEX (NAME (BOOK.LIST.INDEX ) )
16
amserv cluster
4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOE AMSERV
gazelle
FILE MASTCAT
R;
17
File: REPRO AMSERV
REPRO INFILE (BFILE ENV ( RECORDFORHAT(F) BLOCKSIZE(120) PDEV (3330) ) ) OUTFILE (BOOK)
11
12
13
14
15
16
17
378
The file MASTCAT AMSERV defines the VSAM master catalog that you are going to use.
Identify the master catalog volume, and use the EXTENT option on the DLBL command so
that you can enter the extents. For this extent, specify 171 tracks (9 cylinders)
for the master catalog. Since 4 cylinders are specified in the AHSERV file, the
remaining 5 cylinders will be used for suballocation by VSAM.
You must enter a null line to indicate that you have finished entering extent
information.
Issue the AMSERV command, specifying the MASTCAT file.
The ready message indicates
that the master catalog is created.
Define a suballocated cluster. T·his cluster is for a key-sequenced data set, named
BOOK.LIST.
No DLBL command is necessary when you define a suballocated cluster.
Note that
since the password was not provided in the AMSERV file,
access method services
prompts you to enter the password of the catalog, which is defined as GAZELLE.
Use the access method services REPRO command to copy a CMS data file into the
cluster that you just defined.
IBM VM/370 CMS User's Guide
18
data a (recfm f lrecl 120
R;
sort test data a book file a
DMSSRT604R ENTER SORT FIELDS:
1 14
R;
dlbl bfile a cms book file
19
book list {vsam
R;
amserv repro
R;
20
File: SPACE AMSERV
DEFINE SPACE ( FILE (SPACE) TRACKS (57) VOLUME (333333) )
21
SPECIFICATIONS:
22
19
20
21
)
22
R;
amserv space
4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOE AKSERV
gazelle
R;
FILE KASTCAT
You must identify the dnames for the input and output files for the REPRO function.
BFILE is a CMS file, which must be a fixed-length, 120-character file, and it must
be sorted alphamerically in columns 1 through 14. The COPYFILE command can copy any
existing file that you have to the proper record format; the SORT command sorts the
records on the proper fields.
The output file is the VSAM cluster, so you must use the VSAM option on this DLBL
command.
Create an AMSERV file to define additional space for the master catalog on the
volume labelled 333333.
Again, use the EXTENT option on the DLBL command so that you can enter extent
information, and a null line to indicate that you have finished entering extents.
Issue the AMSERV command. Again, you are prompted to enter the password of the
master catalog.
Sample Terminal Session Using Access Method Services
379
23
File: UNIQUE AMSERV
DEFINE CLUSTER( NAME (UNIQUE. FILE) UNIQUE ) DATA
( CIL (3) FILE (KDATA) RECORDSIZE (100 132) KEIS(12,0) VOLUMES (333333 ) } INDEX (CIL
(1)FILE (KINDEX) VOL UMES (333333)
24
111111
dlbl kdata c (extent
DMSDLB331R ENTER EXTENT SPECIfICATIONS:
76 57
R;
dlbl kindex c ( e x t e n t _
DMSDLB331R ENTER EXTENT SPECIFICATIONS:
133 19
R;
amserv unique
4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOE AMSERV
gazelle
FILE MASTCAT
R;
25
File: USERCAT AMSERV
DEFINE USERCATALOG ( CIL (4) FILE (IJSISUC) NAME (PRIVATE. CATALOG) VOLUME (444444) UPDATEPW (UNICORN) ATTEMPTS (2) ) DATA
(CIL (3)
)INDEX ( CIL (1) ) CATALOG (MASTCAT/GAZELLE
26
dlbl ijsysuc d dsn private catalog (extent
DMSDLB331R ENTER EXTENT SPECIFICATIONS:
19 152
peril
Ri
amserv usercat
*R;
23
24
25
26
380
This AMSERV file defines a unique cluster, with data and index components.
Iou must enter DLBL commands and extent information for both the data and index
components of the unique cluster.
Next, define a private (user) catalog for the volume 444444. This catalog is -named
PRIVATE.CATALOG and has a password of UNICORN.
When you define a user catalog that you are going to use as the job catalog for a
terminal session, you should use the ddname IJSYSUC.
IBM VM/370 CMS User's Guide
(
27
28
TAPE 181 ATTACHED
File: EXPORT AMSERV
EXPORT BOOK.LIST
INFILE (BOOK) OUTFILE (TEMP ENV (PDEV (2400)
29
30
31
dlbl
IJSYSCT DISK
FILE
IJSYSCT B1
DISK
BOOK
FILE
A1
BFILE
DISK
FILE
B1
BOOK
BOOK
SPACE
FILE
SPACE
C1
DISK
C1
KDATA
DISK
FILE
KDATA
C1
FILE
KINDEX
DISK
KINDEX
IJSYSUC DISK
FILE
IJSYSUC D1
Ri
dlbl book b dsn book list (cat ijsysct
Ri
amserv texport (tapout 181
DMSAMS361R ENTER TAPE OUTPUT DDNAMES:
temp
»
MASTCAT
BOOK.LIST
PRIVATE. CATALOG
111111
R;
32
File: IMPORT AMSERV
IMPORT
CATALOG (PRIVATE. CATALOG/UNICORN) INFILE (TEMP ENV (PDEV (2400») OUTFILE (BOOK2)
33
tape rew
R;
dlbl book2 d dsn book list (vsam 111111"\
Ri
amserv timport (tapin 181
DMSAMS361R ENTER TAPE INPUT DDNAMES:
temp
R;
27
28
29
30
31
)
32
33
You may want to try an EXPORT/IMPORT function, if you can obtain a scratch tape from
the operator. When the tape is attached to your virtual machine, you receive this
message.
The file that is being exported is the cluster BOOK.LIST created above. If you do
not have access to a tape, you can export the file to your CMS A-disk. Remember to
change the PDEV parameter to reflect the aPFropriate device type.
Before issuing the AMSERV command to perform the export function, you may want to
check the DLBL definitions in effect. Issue the DLBL command with no operands to
obtain a list of current DLBL definitions.
You must reissue the DLBL for BOOK.LIST, because there is a job catalog in effect,
and the file is cataloged in the master catalog. Use the CAT option to override the
job catalog.
There is no default tape value when you are using tapes with the AMSERV command. You
must specify the TAPIN or TAPOUT option and indicate the virtual address of the
tape. You are prompted to enter the ddname, which for this file is TEMP.
The last AMSERV
file imports the cluster BOOK.LIST to
the user catalog,
PRIVATE. CATALOG.
You should rewind the tape before reading it as input.
Sample Terminal Session Using Access Method Services
381
c
382
IBft Vft/370 efts User's Guide
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
Index
The entries in this Index are accumulative and reflect the addition
System Extensions Program Product, Program Number 5748-XX8.
¢
logical line delete symbol
.BX
.CM
.CS
.FO
.IL
.IN
.OF
.SP
.TR
format
format
format
format
format
format
format
format
format
word (57~~=!!~)
word (57~~=!!~)
word (57~~=!!~)
word (~1!~=!!~)
word (~1~~=!!~)
word (~1~~=!!~)
word (57~~=!!~)
word (5748-XX8)
word (~1!~=!!~)
7
324.6
324.7
324.8
324.8
324.8
324.8
324.10
324.11
324.13
&$ special variable
resetting 275
using to test arguments 275
&* special variable
resetting 275
using to test for absence of arguments
275
&ARGS control statement, changing &n
special variables with 272
&BEGEMSG control statement, when to use
307
&BEGPUNCH control statement, when to use
297
&BEGSTACK control statement, when to use
289
&EEGTYPE control statement
examples 106
when to use 286
&CONTINUE centrol statement
following label 104
used with &ERROR control statement 301
&CONTROL control statement
controlling execution summary of EXEC
procedure 299
examples 108
&DATATYPE built-in function, using to test
arguments 274
&EMSG control statement, examples 307
&ERROR control statement
examples 104
provide error exit for CMS commands 301
&EXIT control statement
examples 104
passing return code to CMS 284
&GLOBAL special variable, testing recursion
level of EXEC 283
&GLOBALn special variable
example 278
passing arguments to nested procedures
283
&GOTO control statement
examples 103
transferring control in EXEC procedure
277
of the VM/370 Basic
&HEX control statement, examples 271
&IF control statement
maximum number allowed in nest 277
testing variable symbols 276
&INDEX special variable 101
testing 273
using to establish loop 273
&LENGTH built-in function, using to test
arguments 274
&LITERAL tuilt-in functicn
examples 280
examples of substitution 269
&LCOP control statement
example 105
execution summary when &CONTROL ALL is
in effect 308
preparing loops in EXEC procedure 280
&n special variable, manipulating 272
&PUNCH control statement
punching jobs to CMS hatch facility 234
using to create file 296
&READ control statement
ARGS operand 101
changing &n special variables 272
examples 106
reading CMS commands 285
&READFLAG special variable
determining if console stack needs to be
cleared 293
using to test console stack 290
&RETCODE special variable
example 104
testing after CMS command execution 301
using with &EXIT control statement 283
&SKIP control statement
examples 104
transferring control in EXEC procedure
279
&SPACE control statement, example 106
&STACK control statement
stacking EXEC files with 294
using in edit macros 311
using to stack null line 292
when to use, in edit macros 315
&SUBSTR built-in function, examples
280,294
&TIME control statement, example 108
&TYPE control statement"
displaying prompting messages in EXEC
procedure 284
examples 106
when to use 286
&TYPEFLAG special variable, testing whether
EXEC is displaying data 288
&1 through &30, special variables 101
Index
383
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
!
(exclamation point), controlling whether
it is displayed 28
$, used as first character of filename for
edit macros 311
$COL edit macro 324
$CONT EXEC 316
$DUP edit macro, example 73
$LISTIO EXEC file 158
$MACROS edit macro 320
$MARK edit macro 321
used to enter continuation character 80
$MOVE edit macro, how to use 73
$POINT edit macro 323
* (asterisk)
in EDIT subcommands 65
in fileids on command lines 44
in fileids on command lines (~1~~=!!~)
44.1
in filemode field 53
used to write comments in EXEC procedure
305
*COpy statement
examples 138
in CMS/DOS 166
I logical line end symbol 7
restriction on stacking in EXEC
procedure 291
using to enter null line in input mode
62
using when setting program function keys
340
#CF function' 7,19
using in edit or input mode 84
using on display terminals 339
a
logical character delete symbol 6
using when setting prcgram function keys
340
(equal sign)
entered in fileids on command lines
entered in filemode field 53
subcommand
(§~~ REUSE subcommand)
45
" logical escape symbol 8
used when setting program function keys
340
A
/*
CMS batch acility control card, used to
signal end of job 229
end-of-file indicator
in AMSERV file 182
in batch job 237
// record, used as delimiter in MACLIBs
140,169
/ (diagonal), as delimiter on EDIT
subcommands 64
/JOB control card, description 228
/SET control card, description 229
% (percent symbol), setting EXEC arguments
to blanks
273
subcommand
usage 88
usage, on display terminal 346
usage as argument for EXEC procedure
305
?EDIT message 65
384
IBM VM/370 CMS User's Guide
abnormal termination (abend), effect on
DLBL definitions 160
ACCESS command
accessing CMS disks 14
response when you access VSAM disks 185
used with OS disks 129
access method services
control statements, executing 182
DOS/VS, using in CMS/DOS 181
DOS/VSE, using in CMS/DOS (~1~~=!!~)
181
executing in CMS, examples 205
functions
DEFINE CLUSTER 206
DEFINE MASTERCATALCG 191,199
DEFINE USERCATALOG 193,200
DELETE 207
EXPORT 208
IMPCRT 208
REPRO 208
OS/VS, restriction on using in CMS 181
return codes 183
sample terminal session 375
using in CMS 181
using tape input/output 204
in CMS/DOS 196
Pg. of GC20-1819-2 Rev ftarch 30, 1979 by Supp SD23-9024-1 for 5748-XX8
access methods
DOS, supported in CMS 154
OS, supported in CftS 130
accessing
directories of DOS/VS libraries 163
directories of DOS/VSE libraries
(.21!!!!=XX!!) 1 63
disks 14
as read-only extensions 51
in CftS batch virtual machine 231
DOS disks 154
DOS/VS system residence volume 151
DOS/VSE system residence volume
(.21!! 8- XX!!) 1 51
file directories for CMS disks 57
files of a particular mode number 55
multiple access systems with DIAL
command 26
OS disks 129
ACTION
DOS/VS linkage editor control statement
173
DOS/VSE linkage editor control statement
(.21!! 8- XX!!) 173
ADD operand
of MACLIB command
usage 138
usage in CMS/DOS 167
adding
members to macro library
example 138
example in CMS/DOS 167
address
stops
setting 217
to enter CP environment 23
virtual
calculating for instructions in
program 212
definition 12
for unit record devices 113
A-disk 51
ADSTOP command, how to set address stops
217
ALIAS, OS linkage editor control statement,
supported by TXTLIB command 146
ALL
operand
of &BEGSTACK control statement, when
to use 290
of &BEGTYPE control statement, when
to use 287
of &CONTROL control statement, using
to debug EXECs 308
allocating
space for VSAM files 186,188,202
in CMS/DOS 194
VSAM extents on OS disks and minidisks
198
ALTER subcommand
global changes 71
how to use 70
altering
characteristics of spool files 115
characters in CftS file, with ALTER
subcommand 70
multiple occurrences cf character in
file 71
AftSERV
command
executing in EXEC Irocedure 209
how to use 182
files
examples 182,378
filetype 182
usage in CftS 47
functions under CftS (5748~XX8)
205
using to read tapes (~1!~=!X8)
204
annotated, edit macro 318
annotating, EXEC procedure 305
APL, using on display terminal 350
appending, data to existing files, during
program execution 134
arguments
in EXEC procedure 95,101,272
checking 274
passing to nested JXECs 283
testing with &$ and &* 274
on RUN command, passing parameter list
241
on START command, parameter list 241
ASM3705 filetype, usage in CMS 47
ASSEMBLE
command
assembling OS programs 143
in CftS/DOS 171
filetype
usage in CftS 47
used as input to assembler 143
assembling
OS programs in CMS 143
programs
sample terminal session 366
using CMS batch facility 235
programs in CftS/DOS 171
sample terminal session 371
source files, from OS disks 143
VSAM programs in CftS 181
ASSGN command
entering before program execution 177
using to assign logical units 156
Index
385
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
assigning
file mode letters to disks 51
logical units in CMS/DOS
before program execution 177
for VSAM catalogs 193
to disk devices 158
to virtual devices 158
values to variable symbols, in EXEC
procedure 102
assignment statement, examples 102
attention interruption
causing 21
effect of mode setting 30
automatic
IPL 6
save function of CMS editor 63
AUTOREAD operand of CMS SET command,
display terminals 341
auxiliary control files 259
preferred 260
auxiliary processing routine, receiving
control during I/O operation 134
AUXPROC option, of FILEDEF command 134
AUXxxxx filetype
auxiliary control files 259
usage in CMS 47
B
backspace
characters
changing in file being edited 78
deleted in user input area 350
effect of image setting 78
entering on display terminal 349
batch
facility
(§~~ CMS batch facility)
jobs for CMS batch facility 227
non-CMS users 236
processing, in CMS 227
batch jobs
purging 233
reordering 233
restarting 233
BDAM, access method, CMS support 130
BEGIN command, to return to virtual machine
environment 18
beginning
tracing 217
virtual machine execution 18
386
IBM VM/370 CMS User's Guide
blanks
as delimiters, on EDIT subcommands 64
in character strings changed with CHANGE
subcommand 69
used on OVERLAY subcommand 70
blip, characters, setting 28
BLeCK option, of FILEDEF command 133
BLP
(§~~ bypass label processing)
(Jl~H~=~~l! )
books
from DOS/VS source statement libraries,
copying 161
from DOS/VSE source statement libraries,
copying (Jl~~=~X8)
161
BOTTOM subcommand, moving current line
pcinter to end of file 66
BPAM access method, CMS support 130
branching in EXEC procedure
&GOTO control statement 277
&SKIP control statement 279
based on &IF control statement 276
BREAK subcommand 4 setting program
breakpoints 213
breakpoints, setting 213
BSAM access method, CMS support 130
buffers, used by FSCB 245
BUFSP option
of DLBL command 198
in CMS/DOS 190
bypass latel processing (Jl~~=~X8)
122
C
calculating storage available in your
virtual machine 177
canceling
changes made during edit session 63
DLBL definitions 160
FILEDEF definitions 134
verification of changes made by editor
69
card punch
used to send jobs to eMS batch facility
228
using in EXEC procedure 296
card reader
restriction on use in job for CMS batch
facility 232
spooling punch or printer files to 115
cards
used as input to CMS batch facility
228,237
/* as end-of-file indicator 229
CASE subcommand, usage 76
CAT option of DLBL command 198
identifying catalogs 201
in CMS/DOS 190,193
Pg~
of
GC2~1819-2
Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
cataloged procedures, OS, equivalent in CMS
128
causing breaks in text (~1!8-~!~)
324.11
CAW (channel address word), displaying,
with DISPLAY command 220
CHANGE
command, changing hold status on spool
files 116
subcommand
global changes 71
how to use 69
using in edit macros 316
using on display terminal 346
changing
characteristics of spool files 115
characteristics of unit record devices
113
file identifier, on SAVE subcommand 85
filemode numbers 55
file mode of file, FMODE subcommand 85
lines in file being edited 69
that contain backspace characters 78
multiple occurrences of character string
in file 71
changing output representation of a
character (~1!8-XX~)
324.13
channel address word
(see CAW (channel
address word»
--channel status word
(see CSW (channel
status word»
character, strings, changing 69
characters
altering
with ALTER subcommand 70
with CHANGE subcommand 69
deleting from line 6
special
defining translate table for entering
30
displaying on display terminal 350
entering on display terminal 349
translated to uppercase, in edit macros
311
valid in CMS file identifiers 43
valid in CMS file identifiers (~74~=XX~)
44
CLASS, operand of SPOOL command 113
classes
CP command privilege 333
of CP spool files 113
clearing
console stack
at top or end of file 313
for edit macro execution 313
in EXEC procedure 293
issuing message after 313
DLBL definitions 160
FILEDEF definitions 134
job catalogs ,201
job catalogs in CMS/DOS 193
closing
CMS files, after reading or writing 248
virtual card punch l after using &PUNCH
control statement 296
virtual unit record devices 250
clusters, VSAM, defining and deleting 206
CMS
operand of DLBL command 160
saved system name 223
CMS (Conversational Monitor system)
basic description 3
commands
(~~~ CMS commands)
DOS/VS simulation 151
DOS/VS! simulation (~1!8-XX8)
151
file system 43
file system commands, samples 354
files
(~files, CMS)
loading into your virtual machine 6
OS simulation 127
CMS batch facility
control cards 227
/* 229
/JOE 228
/SET 229
controlling spool files 231
description 227
housekeeping done after executing job
230
how jobs are processed 230
jobs for non-CMS users 236
using EXEC procedure to submit jobs 234
CMS commands
executing
from programs 241
in edit macros 312
in !XEC procedure 299
for tape handling 119
general information 4
nucleus-resident 58
stacking in EXEC procedure 291
summary 328
that execute in transient area 58
used in CMS/DOS
(~~~ CMS/DOS co.mands)
used with OS data sets 129
using EXEC procedure to modify 302
valid in edit macros 312
Index
387
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
CMS editor
environment 19
format of 3270 display screen 345
how to use 61
invoking 61
in EXEC procedure 291
line mode on display terminal 348
sample terminal session 354
using on display terminal 344
CMS environment 18
CMS EXEC file 98
format 98
modifying 100
sorting 99
CMS files
(§~~ files)
CMS macro instructions
examples 249
usage 243
CMS subset
environment 19,84
using 90
using to test EXEC procedure 308
CMSAMS, saved system name 225
CMS/DOS
commands
ASSGN 156
ASSGN (~1!§=!!§)
156.1
DOSLIB 175
DOSLKED 172
DSERV 163
entering 21
ESERV 163
FETCH 175
LISTIO 158
PSERV 162
RSERV 162
sample terminal session 369
SSERV 161
summary 154
environment 21
entering 151
program development using 151
relationship to CMS and to DOS/VS 151
relationship to CMS and to DOS/VSE
(~1!!!=!!!! )
1 51
restrictions on e~ecuting OS programs
152
CMSDOS, saved system name 225
CMSLIB, ddname used to identify OS macro
libraries 141
CMSLIB MACLIB 140,169,243
CMSSEG, saved system name 225
CMSUT1 file~ CMS commands that create 50
CMSVSAM, saved system name 225
388
IBM VM/370 CMS User's Guide
CNTRL filetype
control files 258
usage in CMS 47
command
defaults 25
environments 17
how to enter 3
language 3
CMS 4
CP 3
lines, how scanned in CMS 240
comments
in EXEC procedure 305
in HELP text files (21!§=!!§)
324.7
communicating
with CMS and CP during editing session
84
with VM/370 3
COMP
operand of MACLIB command
usage 139
usage in CMS/DOS 168
COMPARE command, comparing contents of CMS
files 39
comparing, variable symbols in EXEC
procedure 105,276
compilers, supported in CMS 4
components, of VM/370 3
compressing
DOSLIB files 175
MACLIBs 139
in CMS/DOS 168
CONCAT option, of FILEDEF command, example
141
conditional execution. &LOOP control
statement 280
conditionally displaying text (21!§=!!§)
324.8
console
log
creating disk file from 342
printing 342
produced by CMS batch facility 233
output, spooling for display terminal
342
stack
cleared in case of error during edit
macro execution 314
clearing 293
clearing for edit macro execution
313
using in EXEC procedure 289
using to write edit macros 311
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
CONT
operand of SPOOL command 114
using to spool virtual punch in EXEC
procedure 297
continuation character, how to enter in
column 72 79
continuous spooling 114
control cards, for CMS batch facility
(§~~
CMS batch facility control cards)
controlling
CMS loader 147
execution of EXEC Brocedure, summary of
control statements 103
intensity of the redisplay of user input
(.21!!8-!!!!l
28
converting
decimal values to hexadecimal, in EXEC
procedure 270
fixed-length files to variable-length
format 75
hexadecimal values to decimal, in EXEC
procedure 270
CONWAIT function
example 295
using to clear console stack 293
COpy
files
adding to MACLIB 138
adding to MACLIB, in CMS/DOS 166
filetype
usage in CMS 47
usage in CMS/DOS 49
function, on display terminals 342
operand of SPOOL command 114
COPYFILE command
changing filemode numbers 55
changing record format of file 75
copying files from one virtual disk to
another 32
creating small files from large one 89
copying
books from DOS/VS source statement
libraries 161
books from DOS/VSE source statement
libraries (.21!!§=!!§)
161
contents of display screen 342
DOS files into CMS files 155
files
from one device to another 118
from tape to disk 122
lines in CMS file 73
macros from DOS/VS libraries to add to
CMS MACLIB 165
macros from DOS/VSE libraries to add to
CMS MACLIB (.21!!§=!!§)
165
members of MACLIBs 139,168
modules from DOS/VS relocatable
libraries 162
modules from DOS/VSE relocatable
libraries (.21!!~=!X8)
162
OS data sets into CMS files 135
parts of CMS file, with GETFILE
subcommand 73
spool files 114
VSAM data sets 208
into CMS files 208
copying modules from DOS library or SYSIN
tapes (.21!!~=!!§)
156
core image libraries
CMS
(§~~ DOSLIB files)
DOS/VS, using in CMS/DOS 164
DOS/VSE, using in CMS/DOS (~1!!~=!!~)
164
correcting, lines as you enter them 6
counters, using in EXEC procedure 280
CP (control program)
basic description 3
commands, general information 3
privilege classes 333
spooling facilities 113
CP commands 19
executing from programs 242
summary 334
used for debugging 220
compared with DEBUG subcommands 222
using in EXEC procedure 267
using in job for CMS batch facility 232
CP environment, entering 17
CP READ status, on display screen 340
creating
CMS EXEC file 98
CMS files 31
from DOS disks and tapes 156
from DOS libraries 155
from OS data sets 134,136
in EXEC procedure 296
CMS macro libraries
example 137
example in CMS/DOS 165
from DOS macro libraries 165
DOSLIB files 174
file system control block (FSCB)
244
files with CMS editor 61
HELP text files (~1.!l§=!!~)
324 .• 4
modules from DOS library or SYSIN tapes
(~1!!§=!X8)
156
one spool file from many files being
printed or punched 114
program modules 149
programs, sample terminal session 365
reserved filetypes 303
user-written commands 149
user-written edit macros 311
CSW (channel status word), displaying, with
DISPLAY command 220
current line pointer.
displaying when verification is off 86
how to use 65
position on display terminal screen 344
positioning 68
subcommands for display terminals 347
Index
389
Pg. of
GC20-1819~2
Rev ftarch
30~
1979 by Supp SD23-9024-1 for 5748-XX8
cylinders
extents
entering in CftS/DOS 192
specifying for OS disks 198
on 2314/2319 disk 199
on 3330 disk 199
on 3340 ftodel 35 disk 199
on 3340 Model 70 disk 199
D
data control block (DCB), relationship to
FILEDEF command 131
data sets, OS, using in CftS 129
ddna.es
in OS VSAft programs, restricted to 7
characters in CftS 197
specifying with FILEDEF command, 131
used by assembler 143
used with assembler 172
DDR command, used with OS data sets 129
DEBUG
cOllmand 20
to enter debug environment 212
sub commands
compared with CP debugging commands
222
entering 20
monitoring program execution 213
relationship to CP commands for
debugging 220
summary 215
debug environment 20
debugging
commands and subcommands used in
relationship 220
summary of differences 222
EXEC procedure 308
nonrelocatable ftODULE files 221
programs 211
summary of commands 37
using CP commands 219
decimal, and hexadecimal conversion in EXEC
procedure 270
de-editing
DOS/VS macros 163
DOS/VSE macros (~l.9.!!=!!~J \ 163
default
command 25
DLBL definition 160
FILEDEF definition 133
for filetypes for CftS editor,
establishing in EXEC procedure 303
logical line editing symbols 6
setting up in EXEC procedure 273
390
IBft Vft/370 CftS User's Guide
DEFINE
access method services function 206
command
defining temporary disk 12
defining virtual storage 223
to increase virtual storage size 89
subcommand, defining symbols for
debugging session 214
defining
logical line editing symbols 8
program input and outFut files in CftS
145
space for VSAft files 186,202
in eMS/DOS 194
temporary disks 12
translate tables 30
virtual printer for trace information
218
virtual storage 223
VSAft files
for AftSERV 197
for AftSERV, in CftS/DOS 190
VSAft master catalog 199
CftS/DOS 191
DEL
operand
of MACLIB command 138
of MACLIB command, in CftS/DOS 168
DELETE
access method services function 207
subcommand, how to use 72
deleting
lines in file being edited 72
to a particular line 72
members of ftACLIB
exallple 138
exallple in CftS/DOS 168
VSAft clusters and catalogs 207
delimiters, on EDIT subcommand lines 64
density of tapes, when to specify 123
DESBUF function
example 295
using to clear console stack 293
DETACH, command, after R!LEASE command 15
detaching
disks 15
without releasing them 57
device types
assignments in eftS/DOS 156
assignments in eMS/DOS (574~=!X8)
156.1
specifying with FILED!F command 132
devices, disks, cylinders and tracks 199
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
DIAGNOSE instruction, executing CP commands
242
DIAL command 26
DIRECT, filetype, usage in CMS 47
DISCONN, command 26
disconnecting, your terminal from your
virtual machine 26
discontiguous, saved systems 223
DISK
command
LOAD operand, restriction in job for
CMS batch facility 232
using 117
disk determination
default for reading files
commands for which you must specify
file mode 53
commands that search all accessed
disks 52
commands that search only A-disk 53
commands that search only A-disk and
its extensions 53
default for writing files
commands for which you must specify
file mode 54
.
commands that write files onto your
A-disk 54
commands that write output files to
read/write disk 54
filemode selection by editor 63
disks
defined in VM/370 directory entry 11
defining temporary disks for terminal
session 12
definition 11
DOS, accessing 154
full, during editing session 90
linking 13
listing information about 40
master file directory 56
OS
determining extents for VSAM 198
using in CMS 129
OS and DOS
compatibility 186
formatting with IBCDASDI program 189
used with VSAM data sets 185
providing for CMS batch virtual machine
231
querying status of 56
read-only, exporting VSAM files from
208
search order 14,51
sharing 13
VSAM, accessing 185
writing files on, how editor selects
disk 63
DISP MOD option, of FILEDEF command 134
DISPLAY command, displaying storage and
registers while debugging 219
display screen, status ccnditions 340
display terminals
changing editor verification setting
346
controlling screen, during edit session
346
display mode 348
entering backspace characters 349
entering commands 339
example of display screen 343
how editor formats screen 345
line mode 348
signaling interruptions 343
text feature 352
using CMS editor 344
using tab characters 349
displaying
eMS files 34
in EXEC procedure 287
column numbers in file being edited,
using $COL edit macro 324
command information (5748-XX8)
324.1
data lines at terminal------in EXEC procedure 286
WRTERM macro 250
directories of DOS/VS libraries 163
directories of DOS/VSE libraries
(21~~=!!~)
163
DLBL definitions 160
FILEDEF definitions 145
general registers, in debug environment
212
lines at terminal, in EXEC procedure
106
listings from access method services
183
particular columns of file, during edit
session 69
prompting messages in EXEC procedure
284
PSW (program status word), during
program execution 216
screensful of data 347
short form of editor error message 86
special characters on display terminal
350
Index
391
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
timing information in EXEC procedure
108
trace information on terminal 218
virtual storage during program execution
219
disposition, of spool files 113
DLBL
command
assigning filemode numbers 56
default file definition 160
defining OS data sets 129
entering before program execution
177
EXTENT option, examples 204
how to use in CMS/DOS 159
identifying VSAM data sets 197
identifying VSAM data sets in CMS/DOS
190
relationship to ASSGN command 159
specifying extents 203
specifying extents in CMS/DOS 195
DL/I programs in CMS/DOS 152
DMS, prefixing error messages in EXEC
procedure 307
documenting, EXEC procedure 305
DOS, disks, compatibility with OS disks
186
DOS (Disk Operating System)
files
identifying in DLBL command 159
restrictions on reading in CMS 155
using in CMS 154
macros supported in CMS 170
program development, summary of commands
36
simulation in CMS 151
DOSLIB
command, compressing DOSLIBs 175
files 174
executing phases from 176
size considerations 175
filetype, usage in CMS/DOS 49
DOSLKED command, link-editing programs in
CMS/DOS 172
DOSLNK
files, using in CMS/DOS 173
filetype
usage in CMS/DOS 49
used by DOSLKED command 172
DOSMACRO MACLIB 140,169
DOSPART operand, of CMS SET command,
example 178
392
IBM VM/370 CMS User's Guide
DOS/VS system residence volume, using in
CMS/DOS 151
DOS/VSE system residence volume, using in
CMS/DOS (21~~=!X8)
151
drawing boxes (21~8-!!~)
324.6
DSERV command, examples 163
DSN operand of DLBL command 159
DSORG option, of FILEDEF command, when to
specify 133
DSTRING subcommand
example 72
using in edit macros 316
dummy data set, specifying with FILEDEF
command 132
DUMP
command, example 221
subcommand, example 221
dumping, virtual storage 221
duplicating
filenames or filetypes 44
lines in CMS file 73
dynamic loading of TXTLIE members 148
E
E EXEC 302
EDIT command
creating CMS files 31
entering edit environment 19
executing in EXEC procedure 291
invoking CMS editor 61
edit environment 19
edit macros
$COL 324
$CONT 316
$DOUBLE 318
$DUP 73
$MACROS 320
$MARK 321
entering continuation character in
column 72 80
$MOVE 73
$POINT 323
CMS commands valid in 312
distributed with CMS 317
effect of IMPEX setting 29
examples 312
executing 311
how to write 311
sample 318
using variable-length EXEC files 315
edit mode, returning from input mode 62
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
EDIT subcommands
delimiters 64
entering on display terminals 344
executing in edit macros 314
stacking in console stack 291
summary 91
editing
CMS files 61
lines as you enter them from terminal 6
on display terminal 344
in EXEC procedure 349
session 61
end of file
executing edit macros 313
indicating for input stream to batch
virtual machine 237
indicating on jobs sent to batch virtual
machine 229
indication in file being edited 66
end-of-tape processing (21~~=!!~)
122
end-of-volume processing (21~~=!!~)
122
entering
APL characters on display terminal 350
CMS commands, in CMS subset environment
19
CMS environment 18
CMS/DOS environment 21,151
commands 3
more than one command on line 7
on display terminals 339
using synonyms 29
while command or program is executing
22
continuation character in column 72 79
CP commands
from CMS command environment 18
from edit environment 84
CP environment
after program check 220
during program execution 23
from CMS environment 17
from edit mode 84
debug environment
after program abend 212
via breakpoint 20,213
via DEBUG command 20
via EXTERNAL command 20
via external interruption 217
DEBUG subcommands 20
DLBL definitions, in EXEC procedure 179
edit environment 19
EDIT subcommands 64
on display terminal 344
extent information when defining VSAM
master catalog 199
file identifications
on DLBL command 159
on FILEDEF command 132
on LISTDS command 154
FILEDEF definitions, in EXEC procedure
150
Immediate commands 22
on display terminal 343
lines at terminal, during program
execution 250
logical line editing symbols as data 8
multivolume VSAM extents 204
in CMS/DOS 195
null lines 3
special characters
using ALTER subcommand 70
using translate tatle 30
tab characters on disFlay terminal 349
VSAM extent information, in CMS/DOS 191
entry, linkage, for assembler language
programs in CMS 240
ENTRY, OS linkage editor control statement,
supported by TXTLIB command 146
entry pOint
displayed following FETCH command 176
for program execution, determining 148
specifying, using OS ENTRY statement
146
specifying for program execution 144
environments
VM/370 17
summary 24
EOF, token stacked when edit macro executed
at end of file 313
EOF: message 66
ERASE, command 33
erasing
CMS files 33
after reading them 55
to clear disk space during editing
session 90
error messages
controlling whether you receive them 27
displayed by CMS editor 65
short form 86
displaying in red 27
in EXEC procedure 306
errors
during CMS commands, handling in EXEC
procedure 300
Index
393
Pg. of GC20-1819-2 Rev March 30. 1979 by Supp SD23-9024-1 for 5748-XX8
during EXEC processing 306
during standard label processing
(~l!!~=!!!D
122
handling in EXEC procedure 301
in edit macros 314
ESERV
command, examples 163
filetype 163
usage in CMS/DOS 49
examining, output listings from access
method services 183
EXEC
built-in functions, summary 103
command
using in EXEC procedure 267
when to use 96
control statements, summary 109
files
changing record format 96
differences between fixed-length and
variable-length 287,292
record format 96
stacking 294
filetype
for edit macros 311
usage ~n CMS 47
usage 1n CMS/DOS 49
interpreter, how lines are processed
309
procedures 95
building 267
debugging 308
executable statements 267
executing from programs 242
nesting 282
opening and closing CMS files 248
setting program function keys 340
submitting jobs to CMS batch facility
234
testing in CMS subset 308
to execute DOS programs 179
to execute IBCDASDI disk
initialization program 189,375
to execute OS programs 149
used by non-CMS users to submit batch
jobs 236
using to submit jobs to CMS batch
facility 228
with same names as CMS commands 29
processing errors 306
special variables, summary 112
executable statements, in EXEC procedure
267
394
IBM VM/370 CMS User's Guide
executing
access method services, in EXEC
procedure 209
CMS commands
from programs 241
in edit macros 312
in EXEC procedure 299
CMS EXECs 99
commands, using program function keys
339
CP commands
from programs 242
in EXEC procedure 267
DOS programs
sample terminal session 373
setting UPSI byte 178
specifying virtual partition size
178
using EXEC procedure 179
DOS/VS procedures 162
DOS/VSE procedures (~1!!~=!!§)
162
edit macros 311
verifying completion 315
EDIT subcommands
in EXEC procedure 292
using program function keys 340
EXEC procedure 58,95,96
from programs 242
in jobs for CMS hatch facility 234
executable statements in EXEC procedure
267
Immediate commands, in EXEC procedure
287
MODULE files 58.149
from programs 242
OS programs 144
restrictions 144
using EXEC procedure 149
PROFILE EXEC 98
programs
in CMS/DOS 175
sample terminal session 368
TEXT files 144
VSAM programs 181
execution
conditional, using &IF control statement
276
paths in EXEC procedure 275
execution summary of EXEC procedure
description 107
example when 8CONTROL ALL is in effect
308
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
exit linkage, for assembler language
programs in CMS 240
exiting
from EXEC procedure 104,283
based on &RETCODE special variable
301
EXPORT, access method services function
208
exporting, VSAM data sets 208
extensions, read-only, using 51
EXTENT option
of DLBL command 198
in CMS/DOS 190
extents
determining for VSAM functions 188
for VSAM files
entering in CMS/DOS 191
multiple 203
multiple in CMS/DOS 195
EXTERNAL, command, interrupting program
execution 217
external references, how CMS loader
resolves 147
extracting, members of MACLIBs 139,168
F
FETCH command, executing programs in
CMS/DOS 175
fetching, core image phases for execution
in CMS/DOS 175
FIFO, first-in first-out stacking, in EXEC
procedure 290
file
definitions, making with FILEDEF command
131
directories, CMS 56
format, specifying on FILEDEF command
133
identifier
assigned by FILEDEF command 132
changing with SAVE sUbcommand 85
CMS, rules for assigning 43
CMS, rules for assigning (~1!8-!!~)
44
coded as asterisk (*)
44
coded as asterisk (*) (~1~~=!!~)
44,.1
coded as equal sign (=)
45
default assigned by DLBL command 160
specifying for FSCB 244
used in FSCB 244
size, relationship to record length 75
system 43
macro instructions 244
FILE subcommand, writing file onto disk 63
FILED!F
command
assigning filemode nu.bers 56
default definition 132
guidelines for entering 131
how to use 131
used to identify OS macro libraries
140
used with OS data sets 129
commands, issued by asse.bler,
overriding 172
file.ode
in file identifier 43
letters 44
assigning 51
when to specify, reading files 52
when to specify, writing files 54
nUBbers
descriptions 54
when to specify 55
4 130
filename 43
for edit macros 311
for HELP text files (~1~8-XX8)
324.3
files
(§~~ ~!§Q DOS files, OS data sets)
CMS
erasing 33
format 43
identifiers 43
identifying on DLBL command 160
maximum number of records 43
renaming 33
too large to edit, what to do 89
manipulating with CftS macro instructions
244
that are erased after they are read 55
filetype
created by assembler and language
processors 48
for HELP text files (~1!8-XX8)
324.3
for workfiles 50
in file identifiers 43
reserved 45
establishing your own 303
used by CMS commands 46
used by language prccessors 46
FIND, subcommand, how to use 66
first-in first-out stacking, in EXEC
procedure 290
fixed-length, EXEC files, difference
between &STACK and &BEGST1CK 292
fixed-length files, converting to
variable-length 75
Index
395
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
FMODE
subcommand
examples 85
used to change filemode numbers 56
FOR, operand of SPOOL command, usage 114
FORMAT command, formatting CMS disk 12
format of disk files, specifying on FILEDEF
command 133
format words
.BX (~1!§=!!§)
324.6
.CM (~1~§=!!§)
324.7
.CS (~1!§=!!§)
324.8
.FO (~1~§=!!§)
324.8
• IL (~l!§=!!§J
324.8
.IN (~1~§=!!§)
324.8
.OF (~1~§=!!§)
324.10
• SP (~l!§=!!§J
324. 11
• TR (~1~§=!!§)
324. 13
functions (~1~8-!!§)
324.4
summary (~1~§=!!§)
324.5
format-mode processing (~1~§=!!§)
324.8
formatting
CMS disks, example 12
FB-512 disks (~1~§=!!§)
13
numbered lists (~1~§=!!§)
324.11
OS and DOS disks, example 189
forming, tokens of words in EXEC procedure
267
free space on OS and DOS disks, determining
for use with VSAM 188
FREELOWE 177
FRERESPG 177
FSCB, macro, usage 244
FSCB (file system control block)
creating 244
fields defined 244
modifying for read/write operations 245
usage 244
using with I/O macros 245
FSCBD macro, generating DSECT for FSCB 246
FSCLOSE macro, example 248
FSERASE macro, usage 248
FSREAD macro, examples 245
FSWRITE macro, examples 245
full disk 56
during editing session 90
G
GEN operand
of MACLIB command
usage 137
usage in CMS/DOS 165
general registers
conventions used in CMS 239
displaying in debug environment 212
displaying with DISPLAY command 219
modifying during program execution 212
GENMOD command
creating user-written CMS command 149
regenerating existing MODULEs 221
GETFILE subcommand
how to use 73
used to create small files from large
one '89
global changes, using EDIT subcommands 71
396
IBM. VM/370 CMS User's Guide
GLOBAL command
used to identify nOSLIEs 174
used to identify macrc libraries 137
in CMS/DOS 164
, used to identify OS macro libraries
129,140
used to identify TXTLIBs 145
GO subcommand, to resume program execution
213
H
halting
program execution 22
screen displays 344
terminal displays 22
in EXEC procedure 287
HELP command, usage (~1!§=!!§)
5
HELP facility
file naming conventions (21~§=!!§)
324.3
format words (21!§=!!§)
324.4
HELPCMS filetype, usage in CMS (~1!8-!!§)
47
HELPCP filetype, usage in CMS (~1!§=!!§)
47
HELPDEBU filetype, usage in CMS (~1!§=!X8)
47
HELPEDIT filetype, usage in CMS (2148=!!§)
47
HELPMENU filetype, usage in CMS (21!§=!!§)
47
HELPMSG filetype, usage in CMS (21~§=!!§)
47
hexadecimal, conversion in EXEC procedure
270
highlighting of messages on display
terminal (21~§=!!~)
340
highlighting the redisplay of user input
(11!!§=!!§)
28
HILIGHT operand of CP TERMINAL command
(11~§=!!§)
28
HOLD, operand of SPOOL command 114
hold status, placing virtual output devices
in during debugging 211
holding
display on display terminal 341
spool files to keep them from being
processed 114
HOLDING status, on display screen 341
HT Immediate command 22
executing in EXEC procedure 287
HX
DEBUG subcommand 213
Immediate command 22
effect in CMS subset 20
effect on DLBL definitions 160
effect on FILEDEF definitions 134
I
IBCDASDI disk initialization program
formatting temporary disks
example 189,375
ID card, to submit jobs to CMS batch
facility 228
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
identifying
macro libraries to search 137
in CMS/DOS 164
multivolume VSAM files 204
in CMS/DOS 196
VSAM master catalog 199
VSAM master catalog in CMS/DOS 191
IEBPTPCH utility program, creating CMS
files from tapes created by 122
IEBUPDTE utility program, creating CMS
files from tapes created by 122
IEHMOVE utility program, creating CMS files
from tapes created by 123
IJSYSCL, defining in CMS/DOS 159
IJSYSCT
defining 199
defining in CMS/DOS 190
IJSYSRL, defining in CMS/DOS 159
IJSYSSL, defining in CMS/DOS 159
IJSYSUC
defining 201
defining in CMS/DOS 193
image setting, effect on tab characters 76
IMAGE subcommand, using in edit macros 316
Immediate commands
entering, on display terminal 343
summary 327
IMPCP operand, of CMS SET command, setting
18
implied
CP function 18
controlling 29
EXEC function 97
. controlling 29
IMPORT, access method services function
208
importing, VSAM data sets 208
INCLUDE
command, entering after LOAD command
147
DOS/VS linkage editor control statement,
specifying in DOSLNK file 173
DOS/VSE linkage editor control
statement, specifying in DOSLNK file
(~1~8-!!!!)
173
increasing, virtual machine storage 89
indenting text (~1~!!=!!~)
324.8
INPUT
operand, of CMS SET command, defining
input translate table 30
subcommand
inserting single line into file 72
stacking in EXEC procedure 292
using in edit macros 315
input and output files, VSAM, defining 197
input data
left margin while using editor 77
right margin while using editor 79
translated to uppercase by editor 62
input mode 19,62
entered after REPLACE subcommand 72
on display terminal 344
on display terminal in line mode 348
returning to edit mode, in edit macros
316
input stack, clearing 293
inserting
lines in file being edited 72
using line-number editing 82
instructions
calculating virtual storage address 212
tracing 217
INTDK utility program (~1~!!=!!~)
13
intensity, highlighted on display terminal
(~148=11~)
340
Interactive Problem Control System
(§~~
IPCS (Interactive Problem Control System»
interrupting
execution of edit macros 314
program execution 21
with breakpoint 213
interruptions
CMS macros for handling 251
external 217
signaling on display terminal 343
invoking
access method services 182
Cl!S editor 61
EXEC procedure 96
VSAPL en display terminal 350
I/O
device assignments in Cl!S/DOS 156
manipulating 157
device assignments in CMS/DOS (~74~=!!!!)
156.1
macros used in CMS programs 244
IPCS (Interactive Problem Centrol System)
3
IPL command
entering CMS environment 6,18
loading alternate saved segment
IS AM access method
CMS restriction 131
CMS/DOS restriction 154
225
J
jot catalog
using 201
using in CMS/DOS 193
jot control language, equivalent in CMS
128
JOECAT, Cl!S equivalent 128
jobname
for jot sent to CMS batch facility
specifying 228
used to identify spool files 233
jots, for CMS batch facility, submitting
227
Index
397
Pg_ of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
L
label off processing (~1!~=!!~)
122
LABELDEF command, use in tape label
processing (~1!~=!!~)
122
labels
DOS 'SAM disks, determining for AMSER'
191
in EXEC procedure 103
how &GOTO searches for 278
rules for forming 275
terminating loop 280
OS 'SA~ disks, determining for AMSER'
199
tape 121
using 'SAM tapes 204
using 'SAM tapes in CMS/DOS 197
writing on CMS disks 12
LABOFF
(§~~ label off processing)
(~1!~=!!~)
large files, splitting into smaller files
89
LDRTBLS operand, of CMS SET command, usage
223
leaving
CMS subset environment 20
CMS/DOS environment 21
debug environment 20,213
edit environment 20,63
input mode 62
length, of lines displayed at your
terminal, controlling 28
libraries
CMS
(§~~ 2!§~ DOSLIB, MACLIB, TXTLIB)
CMS 136
distributed with CMS system 140,169
macro libraries
(§~~ macro
libraries, CMS)
TEXT libraries 145
DOS/'S
identifying in CMS/DOS 159
using directories 163
using in CMS/DOS 160
DOS/'S core image, executing phases from
176
DOS/'S procedure, copying procedures
162
DOS/'S relocatable
copying modules from
162
link-editing modules from 174
DOS/'S source statement, using in CMS
161
DOS/'SE
identifying in CMS/DOS (~1!~=!!~)
159
using directories (~1!~=!!~)
163
using in CMS/DOS (~1!~=!!~)
160
DOS/'SE core image, executing phases
from (~1!~=!!~)
116
DOS/'SE procedure, copying procedures
(~1!!~=!!~)
162
DOS/'SE relocatable
copying modules from (~1!~=!!~)
162
link-editing modules from (~1!~=!!~)
114
DOS/'SE source statement, using in CMS
(~1!!~=!!~)
161
OS, using in CMS 140
398
IBM 'M/370 CMS User's Guide
LIFO
last-in first-out stacking
in edit macros 313
in EXEC procedure 290
line
mode, of CMS editor 348
pointer
(§~~ current line pointer)
LINEDIT macro, executing CP commands 242
LINEMODE subcommand, beginning line-number
editing 81
line-number editing 81
sample terminal sessicn 362
lines, deleting at terminal before entering
7
LINK command
format in job for CMS batch facility
232
linking to other user's disks 13
linkage conventions, for ~rograms executing
in CMS 240
linkage editor
DOS/'S
invoking in CMS/DOS 112
specifying control statements 113
DOS/'SE
invoking in CMS/DOS (~1!~=!!~)
172
specifying control statements
(~1.!! 8- !!~ )
113
maps~ using when debugging
211
OS, control statements supported by
TXTLIE command \ 145
link-editing
modules from DOS/'S relocatable
libraries 114
modules from DOS/'SE relocatable
libraries (~1!~=!X8)
174
programs in CMS/DOS 112
specifying linkage editor control
statements 173
TEXT files and TXTLIB members 146
TEXT files in CMS/DOS 172
examples 173
linking
to other users' disks 13
to your own disks 13
LISTCAT, access method s€rvices function,
output 183
LISTCRA, access method services function,
output 183
LISTDS command
listing DOS files 154
listing extents occupied by 'SAM files
187
listing free space extents 187
used with OS data sets 129
LISTING, assembler ddname, overriding
default definition 143
listing
edit macros, with $MACROS edit .acro
320
information
about CMS files 39,99
about disks 40
about DOS files 154
about MAeLIB members 139,168
Pg. of GC20-1819-2 Rev March 30. 1979 by Supp SD23-9024-1 for 5748-XX8
about OS and DOS disks 187
about OS' and DOS files 40
about your terminal 38
about your virtual machine 40
logical unit assignments in CMS/DOS 158
listing files
created by AMSERV command
changing filename
184
printing 184
created by assembler, output filemode
143
created by assembler and language
processors 48
created by ESERV command 163
LISTING filetype
created by AMSERV command 183
usage in CMS 47
usage in CMS/DOS 49
LISTIO command, listing device assignments
158
literal values, using in EXEC 269
LKEDIT filetype, usage in CMS 47
LOAD, command, loading and executing TEXT
files
144
load map
produced by LOAD and INCLUDE commands
147
using when debugging 211
LOAD MAP file, created by CMS loader 147
loader
CMS
description 146
entry point determination 148
control statements, summary 147
tables
effect of LOAD and INCLUDE commands
147
usage 223
loader terminate (LDT) loader control
statement, usage 145
loading
alternate saved segment on IPL command
225
CMS into your virtual machine 6
specifying virtual device address
224
core image phases into storage for
execution 175
programs into storage, specifying
storage locations 243
TEXT files into storage 144
TXTLlB members
dynamically 148
into storage 145
LOADLlB filetype, usage in CMS 47
LOADMOD command, to debug MODULE file 221
LOCATE subcommand
how to use 67
using in edit macros 316
locating
lines in file being edited 67
using line-number editing 82
location, starting, for loading link-edited
phases 176
locking r terminal keyboard to wait for
communication 30
logging off VM/370 26
logging on to VM/370 5,25
logical
character delete symbol 6
escape symbol 8
line delete symbol 7
line editing symbols 6
defining 8
overriding 28
overriding (~1!~=!!~)
28.1
used with editor 62
line end symbol
(§~~ ~1§~ # logical
line end symbol)
line end symbol 7
operators, used for ccmparisons in EXEC
procedure 105
record length of CMSfile. overriding
editor defaults 74
units
assigning in CMS/DOS 156
assigning in CMS/DOS (~1!~=!!~)
156.1
LOGOFF command 26
LOGON command 25
contacting VM/370 5
LONG, subcommand. when to use 86
loop
during program execution, debugging 216
in EXEC procedure 105
based on number of arguments passed
273
using &LOOP control statement 279
using counters 280
lowercase letters
suppressing translation to uppercase 76
translated to uppercase by editor 62
LRECL option
of COPYFILE command, truncating records
in file 74
of EDIT command, when to use 74
of FILEDEF command, when to specify 133
Index
399
Pg_ of GC20-1819-2 Rev March 30, 1979 by Supp SD2.3-9024-1 for 5748-XX8
M
MACLIB
'command
usage 137
usage in CMS/DOS 164
files
adding MACRO files created by ESERV
program 163
moving to other files 140,169
querying 137
querying, in eMS/DOS 164
filetype, usage in CMS 47
MACRO
files
adding to MACLIB 138
adding to MACLIB in CMS/DOS 167
created by ESERV command 163
filetype
usage in CMS 47
usage in CMS/DOS 49
macro libraries
CMS 136
adding to 138
creating 137
deleting members of 138
displaying information about members
in 139
distributed with CMS system 140,169
replacing members of 138
using in CMS/DOS 164
DOS/VS assembler language, restriction
on using in CMS/DOS 164
DOS/VSE assembler language, restriction
on using in CMS/DOS (~1~~=!!~)
164
OS, identifying for use in CMS 140
macros
DOS/VS assembler language
creating CMS MACLIB 372
supported in CMS 170
DOS/VSE assembler language
creating CMS MACLIB (~1~~=!!~)
372
supported in CMS (~1~~=!!~)
170
OS, supported in CMS 142
MAINHIGH 177
MAP
filetype
created by DOSLKED command 175
created by DSERV command 163
created by MACLIB command 139,168
usage in CMS 47
usage in CMS/DOS 49
written to A-disk 54
operand
of MACLIB command 139,168
option of DOS/VS ACTION control
statement, effect in CMS/DOS 175
option of DOS/VSE ACTION control
statement, effect in CMS/DOS (~1~~=!!~)
175
400
IBM VM/370 CMS User's, Guide
maps
created by DOS/VS linkage editor 175
created by DOS/VSE linkage editor
(.21~~=!!~)
175
of eMS virtual storage 224
margins
setting left margin for input with
editor 77
setting right margin for input with
editor 79
master catalogs
VSAM
defining 199
defining in CMS/DOS 191
sharing 185
master file directory 56
maximum, number of records in CMS file 43
MEMBER option
CMS commands that have MEMBER aptian
168
of FILEDEF command 134
to copy member of OS partitioned data
set 135
MEMO filetype 50
MESSAGE command, using before logging on
25
messages
controlling whether you receive them 26
from CMS batch facility 230
from CP during edit session, effect on
display screen 346
from editor, on display terminal 344
to other virtual machine users 25
minidisks
(§!!~ s!§.Q disks)
definition 11
transporting to as system after using
with CMS VSAM 187
using with VSAM data sets 187
EXPORT/IMPORT restriction 208
mode
edit and input 62
setting for your terminal 22,30
switching 17
summary 24
modifying
CMS EXECs 100
CMS files, examples of commands 33
FSCB 245
groups of CMS files 53
registers during program execution 212
MODULE
files
creating 149
debugging 221
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
executing from programs 242
generating, to execute in transient
area 243
modifying 221
filetype, usage in CMS 48
modules
DOS/VS relocatable, copying into CMS
files 162
DOS/VSE relocatable, copying into CMS
files (21~!!=!X8)
162
MORE ••• status, on display screen 341
MOVEFILE command
copying os data sets 134
copying tape files
122
copying tape files (~1~§=!!§)
122
extracting member of MACLIB 140,169
moving labelled tapes (~1~§=!!§)
122
reading files from virtual card reader
118
used with os data sets 129
moving
CMS files, examples of commands 33
current line pointer 65
lines in file being edited 73
MULT option of DLBL command 198
in CMS/DOS 190
multiple
extents for VSAM files
specifying 203
specifying in CMS/DOS 195
output devices, restriction in CMS/DOS
159
updates 257
variable symbols in token, examples 269
multivolume VSAM extents
specifying 204
specifying in CMS/DOS 195
N
NAME, OS linkage editor control statement,
supported by TXTLIB command 146
naming
CMS files 43
CMS files (~1~§=!!§)
44
user commands 58
naming conventions for HELP text files
(21~§=!!§)
324.3
nesting
&IF statements in EXEC procedure 277
EXEC procedure 282
return code passed 302
NL
(see no label processing) (~1~§=!!§)
nnnnn-subcommand, examples 82
no label processing (~1~§=!!§)
122
NODISP option of EDIT command, using in
EXEC procedure 349
nonrelocatable modules, creating 149
nonshared copy
of CMS 224
of saved system, obtaining during
debugging 224
nonstandard label processing (~1~~=!!§)
122
NOPROF option, of ACCESS command,
suppressing execution of PROFILE EXEC 98
NO! ACCEPTED status, on display screen 341
NSL
(§~~ nonstandard label processing)
(]1~~=!!!l )
nucleus-resident CMS commands 58
null
line
after IPL 6
at top of file 66
entering to determine environment 17
how to enter 3
in EXEC procedure 267
stacking in EXEC procedure 210,292
testing for in EXEC procedure 285
to resume program execution after
attention interruption 22
to return to edit mode from input
mode 62
variables in EXEC procedure 102
o
object files
created by assembler and language
processors 48
loading into storage 144
offsetting text (~1~8-1!~)
324.10
opening, CMS files 248
options, for FILEDEF command 133
OREER command, selecting files for
processing 116
origin, for debug environment, setting 214
ORIGIN, subcommand, how to use 214
OS
access methods supported in CMS 130
data sets
copying into CMS files 134
restrictions on reading in CMS 131
using in CMS 129
disks
compatibility with DOS disks 186
using in CMS 129
linkage editor control statements, read
by TXTLIB command 145
macros supported in CMS 142
partitioned data sets
(§~~ partitioned
data sets)
program development
sample terminal session 365
summary of commands 35
simulated data sets 130
simulation in CMS 127
utility programs, creating CMS files
from tapes created by 122
Index
401
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
OSMACRO MACLIB 140 r 169
OSMACR01 MACLIB 140 r 169
output
files, produced by ASSEMBLE command 172
from CMS batch facility 233
from virtual console r spooling 342
OUTPUT, operand r of CMS SET command,
defining output translate table 30
output stack r clearing 293
OVERLAY subcommand
how to use 70
overlay more than one line 71
using in edit macros 316
overlaying
character strings 70
with $MARK edit macro 321
virtual storage r during program
execution 243
overriding, logical record length of file
being edited 74
p
parameter lists
detecting absence of 241
passing with START command 144 r 241
setting up to execute CMS command 241
used by CMS routines 240
using FSCB 244
parent disk r of read-only extension 52
parentheses r scanned by EXEC interpreter
267
partition sizer specifying for program
execution r in CMS/DOS 178
partitioned data sets
copying into CMS files
135
specifying member names with FILEDEF
command 134
passing
arguments
to EXEC procedure 272
to nested EXEC procedure 283
control in EXEC procedure 277,279
password suppression on command line
13 r 25,57
passwords
entering on LOGON command line 25
for VSAM catalogs 202
in CMS/DOS 194
for your virtual machine 5
supplying on LINK command line 13
402
IBM VM/370 CMS User's Guide
PAl key, to enter CP environment 344
PDS option, of MOVEFILE command, to copy OS
partitioned data sets 135
periods, used to concatenate EXEC variable
symbols 103
PERM option, of FILEDEF command r when to
specify 134
PF keys
(2~ program function keys)
phases r CMS/DOS core image, writing into
DOSLIBs 174
positioning
current line pointer 65,68
using $POINT edit macro 323
tapes, examples 120
preferred auxiliary files 260
preferred level updating 260
preparing r jobs for CMS batch facility 231
PRESERVE subcommand
saving EDIT subcommand settings 86
using in edit macros 315
preserving. editor settings 86
PRINT
access method services function, output
183
command, printing CMS files 34
printer files
produced by job running in batch virtual
machine 231
querying status of 115
printing
access method services listings 184
CMS files 34
multiple copies 114
trace information on virtual printer
218
PRINTL macro, usage 250
privilege classes, for CP commands 333
PROC filetype
162
usage in CMS/DOS 49
procedures
DOS/VS, copying into CMS files
162
DOS/VSE, copying into CMS files
(.21~~=!!~)
162
PROFILE EXEC
sample 97
for CMS/DOS VSAM user
191
for OS VSAM user
199
program
abend, message 211
check, using CP to debug 220
debugging 211
dumps, obtaining 221
March 30, 1919
execution
entry point determination 148
interrupting 21
resuming with BEGIN command 221
tracing 216
input and output files, identifying 131
interruptions
address stops 23
break{:oints 23
libraries 145
linkage, in CMS .239
listings, using when debugging 211
loops, debugging 216
program development
DOS programs 151
sample terminal session 369
summary of commands 36
OS programs 121
sample terminal session 365
summary of commands 35
using CMS 125
program function keys
setting 339
COpy function 342
for EDIT subcommands 348
in EXEC procedure 340
logical tab stops 349
using 339
program status word (§gg PSi (program
status word»
programmer logical units, assigning in
CMS/DOS 157
prompting
for line numbers while line-number
editing 82
.essages in EXEC procedure 284
protecting, files from being accessed 54
PSERV command, examples 162
PSi, operand of DISPLAY command 216
PSi (program status word)
displaying
in debug environment 212
while program loops 216
with DISPLAY command 220
modifying wait bit 220
PUNCH
command
example 111
punching jobs to batch virtual
machine 228
using with &PUNCH control statement
punch files, produced by job running in
batch virtual machine 231
PUNCHC macro, usage 250
punching
CMS files 34
files to your virtual card punch 117
jobs to batch virtual machine 228
in EXEC procedure 234
lines in EXEC procedure 101
lines to virtual card punch 118
members of MACLIBs 139,169
PURGE, command, purging spool files 116
purging batch jobs 233
Q
QSAM access method, C!S support 130
QUERY
command (CMS), used with OS data sets
129
command (CP), displaying status of spool
files 115
QUIT subcommand, terminating edit session
63
R
RDlER! macro, examples 250
read, to virtual console, definition 21
READ control card, punching 111
READCARD command
examples 111
restriction in CMS batch facility 232
used to assign file mode numbers 56
using with &PUNCH control statement 296
READER operand
of ASSGN command, restriction in job for
CftS batch facility 232
of FILEDEF command, restriction in job
for CftS batch facility 232
reading
arguments from terminal during EXEC
processing 216
cards from your virtual card reader 116
CftS commands
from console stack 291
from terminal during EXEC processing
285
291
ESERV control statement, executing in
CMS/DOS 163
Index
403
March 30,
1979
CMS files
from console stack 294
from EXEC procedure 294
with FSREAD macro 246
DOS files in CMS
154
files from tapes
119
from terminal
in EXEC proceaure 106
RDTERM macro 250
lines from console stack, in EXEC
procedure 289
real card decks into your virtual
machine
117
specific records in CMS file
246
variable symbols from terminal during
EXEC processing 285
read-only, extensions, using 51
read/write
pointer, positioning 248
status of disks
displaying 14
in VM/370 directory entry 11
ready message 8
controlling how it is displayed 27
CPU times displayed 239
displaying return code from EXEC
procedure 284
not displayed after #CP function used in
CMS environment
19
RECFM, option, of FILEDEF command, when to
specify 133
record format
describing for file being edited 73
of CMS file, changing 75
specifying for DOS files
155
specifying for program input and output
files
133
record length
creating long records with editor 74
of CMS file
changing 74
default values set by editor 74
relationship to file size 75
records, in CMS file, maximu~ number 43
recursion level of EXEC, testing with
&GLOBAL special variable
283
red type, displaying error messages in 28
re-executing, EDIT subcommands 87
register 15
checking contents after program
execution
150
in CMS/DOS 179
contents after CMS command execution
240
testing contents in EXEC procedure
301
404
IBM VM/370 CMS User's Guide
registers
(§~~ general registers)
relative record number, specified in FSCB
245
RELEASE command 14
updating master file directory 57
used with OS disks 129
releasing
disks
14,57
read-only extensions 52
relocatable
modules, link-editing in CMS/DOS
174
object files" loadirig into storage for
execution 146
Remote Spooling Communications subsystem
(§~~ RSCS (Remote Spooling Communications
Subsystem)}
remote terminals, using CMS editor 348
RENAME command, renaming CMS files 33
renaming, CMS files 33
RENUM subcommand, usage 82
renumbering, records in file, while
line-number editing 82
reordering batch jobs 233
REP
operand
of MACLIB command
138
of MACLIB command in CMS/DOS
167
REPEAT sutcommand, used with OVERLAY
subcommand 71
REPLACE
option of COPYFILE command, used to
change filemode letters 55
subcommand
how to use 72
using in edit macros 315
replacing
lines in file being edited 72
using line-number editing 82
members in macro library, example in
CMS/DOS 167
REPRO, access method services function 208
resolving, unresolved references
147
responding
to CMS commands in EXEC procedure 107
to prompting messages from AMSERV, in
EXEC procedure 209
responses
from CMS commands 9
suppressing display in EXEC procedure
287
from CP commands 9
from VM/370 8
to CMS commands, stacking in EXEC
procedure 289
restarting batch jobs 233
Pg. of GC20-1819-2 Rev Karch 30, 1919 by Supp SD23-9024-1 for 5148-XX8
RESTORE
subcommand
usage 81
using in edit macros 315
restoring
editor settings 81
screen display during edit session,
using TYPE subcommand 346
restrictions
on commands used in CMS batch facility
232
on ddnames in OS VSAM programs 191
on executing DL/I programs in CMS/DOS
152
on executing DOS programs in CMS/DOS
115
on executing OS programs in eMS 144
on executing OS programs in eMS/DOS 152
on number of files per disk (21~~=!!~)
43
on number of lines that can be stacked
in edit macro 314
on programs executing in transient area
243
on reading DOS files in CMS 155
on reading OS data sets in CMS 131
on using DOS/VS macro libraries in
CMS/DOS 164
on using DOS/VSE macro libraries in
CMS/DOS (5148-XX8)
164
on using miniaisks with VSAM data sets
181
resume
program execution
after attention interruption 22
after program check 212
terminal displays 22
in EXEC procedure 288
RETURN
CMS subset command, to leave CMS subset
20
DEBUG subcommand, before starting
program execution 213
return codes
displayed in ready message 240
from access method services 183
from eMS commands
displaying during EXEC processing
299
specifying error address following
SVC 202 242
from EXEC procedure 284
in CMS ready message 9
passed by register 15 240
1 299
-2 314
-3 299
REUSE subcommand
after LOCATE or FIND subcommand 61
usage 81
RSCS (Remote Spooling Communications
subsystem)
3
general information 123
RSERV command, examples 162
RT Immediate command 22
executing in ~XEC procedure 288
RUN, command~ specify~ng arguments 241
RUNNING status, on display screen 341
S
SAM files
(§~~ sequential access method
(SAM) files)
sample, terminal sessions 353
SAVE subcommand
changing file identifier 85
writing file onto disk 62
scanning
CMS command lines 240
lines in EXEC procedure 261,309
tokens in EXEC procedure 100
screen
example of 3210 screen display 343
format used by CMS editor 345
status
CP READ 340
CP READ (~1~~=]]~)
340.1
HOLDING 341
MORE... 341
NOT ACCEPTED 341
RUNNING 341
VM READ 341
SCRIPT
command, restriction cn executing in
CMS/DOS 152
files 50
using backspaces 18
filetype, usage in CMS 48
SCROLL subcommand, how to use 341
search order
for CMS commands
considerations when naming EXEC
procedure 302
summary 59
for CMS disks 51
displaying 14
for executable phases in CMS/DOS 116
used by DOSLKED command 112
searching
disks for CMS files
(see disk
determination)
for label in EXEC procedure 218
for line in file being edited 61
Index
405
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
only particular columns of file being
edited 69
read-only extensions 52
segment
alternate, loading on IPL command 225
shared system loaded into 224
sending messages, to other virtual machine
users 25
sequence numbers
specifying identifier 80
updating 254
sequential access meth6d (SAM) files,
reading in CMS/DOS 154
serial numbers
changing verification setting to display
81
in file being edited 80
SERIAL subcommand, examples 80
serializing
records in file 80
while line-number editing 82
SET command (CftS)
controlling message displays 27
operands invalid in job for CMS batch
facility 232
setting implied CP and EXEC functions
29
SET command (CP), controlling message
displays 26
SETSSI, OS linkage editor control
statement, supported by TXTLIB command
146
setting
entry point for program execution 148
limits on system resources during batch
jobs 229
program function keys 339
in edit macros 340
sharing
CftS system 223
data and master catalog, in CftS VSAM
185
virtual disks 13
SHORT subcommand, when to use 86
simulated data sets
filemode number of 4 55
format 130
size
of CftS file
maximum 43
relationship to record length 75
of virtual storage in your virtual
machine 223
406
IBft VM/370 CftS User's Guide
skipping, lines in EXEC Frocedure 279
SLEEP command
locking terminal keybcard 30
using on display terminals 341
SMSG command (CP)
27
sorting
CftS EXEC 99
directories of DOS/VS libraries 163
directories of DOS/VSE libraries
(5748-XX8)
163
spaCing-between lines of text (21!~=!!§)
324.11
special characters
eMS editor handling 76
on 3270 terminals 349
3270 Text feature 352
special messages, controlling whether you
receive them 26
special variahles, EXEC
(§~~ EXEC special
variables)
specifying
device type for FILEDEF command 132
filemode numbers, on tLEL and FILEDEF
command 56
which records to read or write 246
splitting, CMS files intc smaller files 89
SPOOL command
changing characteristics of unit record
devices 113
spooling console output 342
spool files 113
controlling in job for CftS batch
facility 231
determining status of 41,115
produced by CMS hatch facility,
controlling 233
spooling
hasic description 113
console output 342
multiple copies 114
SSERV command, examples 161
STACK, sutcommand, using in edit macros
317
stacking
eftS commands, in EXEC procedure 291
command lines, after attenticn
interruption 22
commands lines, with # (logical line end
symhol)
7
EDIT subcommands 291
in edit macros 311
with REUSE subcommand 88
EXEC files in console stack 294
Immediate commands in EXEC procedure
287
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
last-in first-out in EXEC procedure 290
lines in console stack, in EXEC
procedure 289
lines in EXEC procedure 107
limitations 289,314
null lines
after attention interruption 22
in EXEC procedure 210,292
responses in EXEC procedure 289
AMSERV command 209
DLBL command 179
FILEDEF command 150
to CMS commands 107
START
command
after LOAD command 144
used with FETCH command 175
option
of FETCH command 176
of LOAD command 144
starting, program execution in CMS 144
STATE command, used with OS data sets 129
STEPCAT, CMS equivalent 128
storage available in your virtual machine,
calculated by CMS 177
STORE
CP command, using to change program
status word (PSi)
216
subcommand, changing storage locations
214
suballocated VSAM cluster, defining 206
submitting
jobs to CMS batch facility 227
non-CMS users 236
substituting, variable symbols in EXEC
procedure 268
summary
of CMS commands 328
of CMS/DOS commands 154
of CP command privilege classes 333
of CP commands 334
of DEBUG subcommands 215
of EDIT subcommands 91
of EXEC built-in functions 103
of EXEC control statements 109
of EXEC special variables 112
of Immediate commands 327
suppressing
long form of editor ?EDIT message 86
verification of changes made by editor
86
suppression of passwords on the command
line 13,25,57
SVC
instructions
tracing with CP TRACE command 218
tracing with SVCTRACE command 219
SVC 202, used to call CMS command 241
SVCTRACE command, usage 219
symbolic addresses for tapes 118
symbols
debug
defining 214
using with DEBUG subcommands 214
logical line editing 6
used for comparisons in EXEC procedure
105
variable, in EXEC procedure
(see
variatle symbols)
SYNONYM
command, invoking syncnym tables 29
filetype, usage in CMS 48
synonyms, for CMS and user-written
commands, defining 29
SYSCAT, assigning in CMS/DOS 190
SYSCLB
assigning in CMS/DOS 157
unassigning 176
SYSIN
assignin~ in CMS/DOS
157
input for ESERV command 163
SYSIPT, assigning in CMS/DOS 157
SYSLIB, ddname used to identify OS macro
libraries 141
SYSLOG, assigning in CMS/DOS 157
SYSLST
assigning in CMS/DOS 157
output from ESERV program 163
SYSPCH
assigning in CMS/DOS 157
output from ESERV program 163
SYSRDR, assigning in CMS/DOS 157
SYSRLB, assigning in CMS/DOS 157
SYSSLB, assigning in eMS/DOS 157
system disk, files available 54
system logical units 157
SYSUT1 filetype 50
SYSUT2 filetype 50
SYSUT3 filetype 50
SYSUT4 filetype 50
SYSxxx
option of DLBL command 159
programmer logical units
assigning 156
assigning (~1~'§=]]'§)
156.1
Index
407
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
SISOOl filety~e
SY5002 filetype
5YS003 filety~e
SY5004 filety~e
5YS005 filety~e
SY5006 filety~e
50
50
50
50
50
50
T
tab
characters
deleted in user input area 350
entering in file being edited 76
using in edit macros 316
using on display terminals 349
settings, used by editor 77
TABSET subcommand, using in edit macros
316
TAPE command, examples 120
TAPEMAC command, use in tape label
processing (2I~~=!!~)
122
tapes
considerations for CMS/DOS users 156
controlling 118
density of, when to specify 123
for AMSERV, example 208
labels 121
end-of-tape processing (21~~=!!~)
122
end-of-volume processing (21~~=!!~)
122
error processing (21~~=!!~)
122
processing in CMS 156
processing in CMS (21~~=!!~)
121,133
processing in CMS/DOS (21~~=!!~)
122
processing in OS simulation
(21~~=!!~)
122
reading 204
reading in CMS/DOS 197
used for AMSERV input and output 204
in CMS/DOS 196
TAPESL macro, use in tape label processing
(21~~=!!~)
122
TAPn, symbolic addresses for tapes 118
TAPPDS command
copying files from tapes 122
copying files from tapes (21~~=!!~)
122
use in tape label processing (21~~=!!~)
122
temporary disks, using for VSAM data sets
188
TERMINAL, command, setting logical line
editing symbols 8
terminals
characteristics, setting 28
commands te centrol communications 25
communication in EXEC procedure 284
disconnecting 26
display
(§gg display terminals)
input buffer
(§g~ console stack)
macros for communication 248
mode setting 22,30
display terminals 341
sample sessions 353
terms, OS, equivalents in CMS 128
408
IBM VM/370 CMS User's Guide
testing
arguments passed to EXEC procedure 274
EXEC procedure, using CMS subset 308
for null line entered in EXEC procedure
285
return codes from CMS commands 283
in EXEC procedure 284
variables symbols, using &IF control
statement 276
TEXT
assembler output ddname, overriding
default definition 143
files
created by assembler and language
processors 48
link-editing in CMS/DeS 172
loading into storage 145
filetype
usage in CMS 48
usage in CMS/DOS 49
text feature, for 3270 terminals 352
time information, displaying during EXEC
processing 300
TO, operand of SPOOL command 115
TOF, token stacked when edit macro executed
at top of file 313
TOF: message 66
tokens 100
with multiple variable symbols 269
TOP, subcommand, moving current line
pointer to top of file 66
top of file
executing edit macros 313
indication in file being edited 66
TRACE, command, usage 217
tracing
output, printing 218
program execution 216
controlling trace 218
tracks
entering extent information in terms of
198
number per cylinder on disk devices 199
TRANSFER command, moving reader files 116
transferring
control in EXEC procedure
&ERROR control statement 301
using &GOTO control statement 277
transient area
CMS commands that execute in 58
creating modules to execute in 243
location in virtual storage 223
restrictions on modules executing in
243
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
translate tables
defining input and output characters for
30
using on display terminals 349
translating, virtual storage to EBCDIC 219
translating output characters (~1!~=!!~)
324.13
transporting, VSAM data sets 208
TRUNC
option of COPYFILE command, used to
convert record formats 75
subcommand, setting right margin for
input with editor 79
truncating
data while changing lines with editor
79
input data while using editor 78
trailing blanks from fixed-length
records 75
words in EXEC procedure 267
truncation, settings used by editor 79
TSOMAC MACLIB 140,169
TXTLIB
command
os linkage editor control statements
supported 145
usage 145
files
assigning entry point names 145
manipulating 145
filetype, usage in CMS 48
.embers, assigning names for 146
TYPE
command, displaying CMS files 34
subcommand
effect on current line pointer 65
using to restore screen display 346
U
unassigning logical unit assignments in
CMS/DOS 158
underscore
characters in file being edited 78
using on OVERLAY subcommand 70
unique clusters, defining 206
unit record, devices 113
unresolved references, how CMS loader
resolves 147
UPDATE
control statement usage 253
filetype
creating update files 252
usage in CMS 48
updating
CMS file directories 57
source files 251
examples 255,256
UPtLOG filetype, usage in eMS 48
UPDTxxxx filetype, usage in CMS 48
UPSI
byte, setting in CMS/DOS 178
operand, of CMS SET command, example
178
user catalog
VSAM 200
in CMS/DOS 193
user file directory 56
user program area 223
executing programs and CMS commands 243
userid
for your virtual machine 5
of eMS batch virtual machine 228
specifying for output spool files 114
user-written
commands, creating 149
edit macros 320
v
variable symbols
compound 269
examples of substitution 268
how scanned 268
in EXEC procedure 101
comparing 105
using as counters 280
reading values from terminal 285
stacking in edit macrcs 312
variable-length EXEC files, considerations
for writing edit macros 315
VARS operand of SREAD control statement
285
verification setting
changing in edit macros 315
changing on display terminal 346
columns used by editor 69
VERIFY subcommand
canceling editor displays 86
how to use 69
using in edit macros 315
verifying, execution of edit macros 315
Index
409
Pg. of GC20-1819-2 Rev March 30, 1979 by Supp SD23-9024-1 for 5748-XX8
virtual
addresses
for disks 12
for tapes 118
for unit record devic~s 113
storage
(§~~ virtual storage)
virtual disks
(§~~ ~!§Q disks)
definition 11
virtual Machine Facility/370 (VM/370)
basic description 3
command summaries 328
components 3
environments 17
virtual machines
definiticn 3
size 223
virtual storage
addresses, calculating 212
CMS utilization 224
displaying 219
examining in debug environment 212
how CMS uses 223
increasing size 89
overlaying during program execution 243
specifying locations for program
execution 243
used by editor, what to do when it is
full 88
VM READ status, on display screen 341
VMFASM EXEC procedure 262
VMFDOS command (~1~!!=!!!!)
156
VM/370
(§~~ Virtual Machine Facility/370
(VM/37 0) )
vm/370 online 5
VSAM
access method, CMS support 130
catalogs
deleting 207
passwords 202
passwords in CMS/DOS 194
using in CMS/DOS 190
clusters
defining 206
deleting 207
unique 206
data sets, manipulating with AMSERV
command 181
files
allocating space for 186
identifying multivolume 204
identifying multivolume in CMS/DOS
196
relationship to CMS files 43
410
IBM VM/370 CMS User's Guide
input and output files
defining 197
defining in CMS/DOS 190
master catalog
defining 199
defining in CMS/DOS 191
. identifying 199
identifying before executing programs
182
identifying in CMS/DOS 191
sharing 1 a5
multivolume extents
specifying 204
specifying in CMS/DOS 195
option
of DLBL command 197
of DLBL command, in CMS/DOS 190
programs, compiling and executing in CMS
181
user catalogs
defining 200
defining in CMS/DOS 192
using in CMS 181
VSAPL program, invoking on display terminal
350
W
wait bit, in program new PSW, modifying
220
WAITT macro, usage 250
warning messages, controlling whether you
receive them 27
writing
CMS files
in EXEC procedure 296
with FSWRITE macro 246
CMS files onto disk
disk determination 54
how editor selects disk 63
edit macros 311
error messages in EXEC procedure 306
labels on CMS disks 12
lines to terminal 250
specific records in CMS file 246
tape marks, examples 120
WRTERM macro, examples 250
ftarch 30, 1919
x
DEBUG sUbco.mand, example 214
EDIT subcom.and, usage 81
ZONE subcommand
setting truncation columns for CHANGE
subcommand 19
specifying columns for editor to search
69
y
Y subcommand, usage
81
Z
ZAP filetype, usage in CMS 48
zone setting
columns used by editor 69
increasing 19
1
19E virtual
Y-disk 51
190 virtual
accessed
using to
191 virtual
A-disk 51
192 virtual
D-disk 51
disk address, accessed as
disk address
as S-disk 51
IPL CftS 6
disk address, accessed as
disk address, accessed as
3
3210 terminals
(§~~
disFlay terminals)
Index
411
March 30,
412
IBM VM/370 eMS User's Guide
1979
READER'S
COMMENT
FORM
Title: IBM Virtual Machine
Facility/370:
CMS User's Guide
Order No. GC20·1819- 2
Please check or fill in the items; adding explanations/comments in the space provided.
Which of the following terms best describes your job?
[j Customer Engineer
o
o
Engineer
Instructor
o
o
o
Manager
Mathematician
Operator
o Programmer
o Sales Representative
o 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/ 0 Instructor text
o Other (explain) _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __
Did you find the material easy to read and understand?
0 Yes
o
No ( explain. below)
Did you find the material organized for convenient use?'
0 Yes
o
No (explain below)
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 the U.S.A.
GC20-1819-2
Reader's Comment Form
I
I
I
Fold and tape
Fold and tape
Please Do Not Staple
\\\\\\
First Class
Permit 40
Armonk
New York
I
I
I
I
I
I
I
Business Reply Mail
No postage stamp necessary if mailed in the U.S.A.
I
I
Postage will be paid by:
I
International Business Machines Corporation
Department 058, Building 706-2
PO Box 390
Poughkeepsie, New York 12602
I
I
I
. Attn: VM/370 PubUcations
Fold and tape
I
Please Do Not Staple
Fold and tape
--I
I
"'CJ
~
5'
S'
a.
5'
c:
en
~
G)
n
N
9...a
-------- ..........
-- - -----_
.-
_-
International Business Machines Corporation
Data Processing Division
1133 Westchester Avenue, Wh ite Plains, N. V. 10604
IBM World Trsae Americas/Far East Corporation
Town of Mount Pleasant, Route 9, Nor:th Tarrytown, N.V., U.S.A. 10591
IBM World Trade Europe/Middle East/Africa Corporation
360 Hamilton Avenue, White Plains, N.V., U.s.A. 10601
CO
...a
cp
N
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 Create Date : 2012:06:05 12:49:06-08:00 Modify Date : 2012:06:05 13:23:42-07:00 Metadata Date : 2012:06:05 13:23:42-07:00 Producer : Adobe Acrobat 9.51 Paper Capture Plug-in Format : application/pdf Document ID : uuid:950e7222-3e34-4144-805d-62250d221849 Instance ID : uuid:c3d4fc52-7c7a-4f6e-a1e5-796eabbce216 Page Layout : SinglePage Page Mode : UseNone Page Count : 492EXIF Metadata provided by EXIF.tools