GH20-0859-O

Type III

Control Program-67/Cambridge Monitor System(CP-67/CMS) Version 3
Program Number 3600-05.2.005
User's Guide

CP-67/CMS is a general purpose time-sharing systemdeveloped for the IBM System/360. This guidedescribes the facilities of CP-67/CMS and provides detailed information about the usercommands available and their usage.

Class A Program

First Edition (October 1970)
This Type III Program performs functions that may be fundamental to the operation and maintenanceof a system.
It has not been subjected to formal test by IBM.

Until the program is reclassified, IBM will provide for it: (a) Central Programming Service, including
design error correction and automatic distribution of corrections; and (b) FE Programming Service,including design error verification, AP AR documentation and submission, and application of Program
Temporary Fixes or development of an emergency bypass when required. IBM does not guarantee
service results or represent or warrant that all errors will be corrected.
You are expected to make the Imal evaluation as to the usefulness of this program in your own
environment.
THE FOREGOING IS IN LIEU OF ALL WARRANTIES EXPRESSED OR IMPLIED, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESSFOR A PARTICULAR PURPOSE.
This edition applies to Version 3, Modification Level 0, of ControIProgram-67/Cambridge Monitor
System (360D-05.2.005) and to all subsequent versions and modifications until otherwise indicated in
new editions or Technical Newsletters.
Changes are continually made to the information herein. Therefore, before using this publication,
consult the latest System/360 SRL Newsletter (GN20-0360) for the editions that are applicable andcurrent.
Copies of this and other IBM publications can be obtained through IBM branch offices.
A form has been provided at the back of this publication for readers' comments. If this form
has been removed, address comments to: IBM Corporation, Technical Publications Department,
1133 Westchester Avenue, White Plains, New York 10604.

PREFACE
The following documents
User's Guide.
Fortranarereferenced

in theCP-67/CMS

OS/360 Fortran IV Language
GC28-6515
Systew/360 Basic Fortran IV Language
GC28-6629
Syste~/360

Fortran IV Library Subprograms

GC28-6596
OS/360 Fortran IV (G and H) Programmer's Guide
GC28-6817
Scientific SubroutinE Package
Scientific Subroutine Package - Version II
Programmer's Manual
GH20-0205
PL/I

OS/360 PL/I

(F)

Programmer's Guide

GC2~-6594

OS/360 PL/I Subroutine Library Computational
Subroutines
GC28-6590
GC28-6808

A PL/I Primer
Assembler-

OS/360 Assembler Language
GC28-6514
OS/360 Assembler (F) Programmer's Guide
GC26-3756

CP-67/CMS Documents - CP-67 Operator·s Guide GH20-0856
CP-67 Program Logic ~anual GY20-0590
ctJ"S Prograrr' Logic Manua 1 GY20-0591
CP-67/CMS Installation Guide GH20-0857
C~S

SCRIPT User's Manual GH20-0860

i

SNOBOLCMS
SNOBOL User's
Manual, TypeIII
Documentation, Program
360D-03. 2,. 016, IBM
Corporation,
DP
ProgramInformation
Department,
40
Saw
Mill
River
Road,
Hawthorne, New York. October, 1910.

BRUIN

CMS
BRUIN
User'sManual, TypeIII
Documentation, Program
3600-03.3.013. IBM
Corporation,
DP
ProgramInformation
Department,
40
Saw
Mill
River
Road,
Hawthorne, New York, October, 1910.

Miscellaneous- System/360 Principles of Operation
GA22-6821
2140/2141 Communications Terminal
Operator's Guide
GA21-3001
OS/360-Supervisor & Data Management
Macro-Instructions
GC28-6647

ii

CP-67/CMS User's Guide
CONTENTS
Introduction
Components of the System
System Environment
The Control Program, CP-67
Cambridge Monitor System
CMS Batch Monitor
CP-67/CMS Sample Terminal Session

1
1

CP-67 Terminal Usage
2741 Characteristics
2741 Initiation Procedures
1050 Characterisitcs
1050 Initiation ProceduresType 33 Teletype Characteristics
Type 35 Teletype Characteristics

16
17
18
18
20
24
25

CP-67/CMS Conventions
Logging Procedures
CP Login
CMS Initialization
CP Logout
Dialing a Multiaccess System
Dialing
Disconnecting
General Typing Conventions
Attention Interrupt
CMS File Conventions
Disk Facilities
File IdentifiersFile Sizes
Disk Considerations
Environment Conventions
CP-67/CMS Environment, Commands, and Requests

27

CMS Commands
File Creation, Maintenance, and Manipulation
ALTER
CEDIT
CLOSIOCOMBINE
EDIT
Operation of the context Editor
Line PointerSaving Intermediate Results
Input Environment
Edit Environment
Edit Request
File (Record) Formats
Memo Files
iii

1
2
4

5
6

27
27
30
30
32
32
33
34
36
37
37

38
41
41
43

45
46

50
52
54
55
57

59
60
60
60
61
61
62
63
63

SCRIPT Files
Record Lengths
Tab settings
serialization of Records
Special Characters
Logical Tab Character
Logical Backspace Character
BACKSPACE Request
BLANl< Request
BOTTOM Request
BRIEF Request
CHANGE Request
DELETE Request
FILE Request
FIND Request
INPUT Request
INSERT Request
LOCATE Request
NEXT Request
OVERLAY Request
PRINT Request
QUIT Request
REPEAT Request
RETYPE Request
SAVE Request
SERIAL ~eqnest
TABDEF -Request
TABSET Request
TOP Request
UP Request
VERIFY Request
X and Y Request
ZONE Request
ERASE
FILEDEFFINIS
LISTF
OFFLINE
PRINTFSCRIPT
Script Control Words
APPEND Control
BOTTOM MARGIN Control
BREAK Control
CENTER Control
COMMENT Control
CONCATENATE Control
CONDITIONAL PAGE Control
DOUBLE SPACE Control
FORMAT Control
HEADING Control
HEADING MARGIN Control
IMBED Control
iv

63

63
64
65
65
65
66
69
11

12
13
14
16
17
79
81
82
84
86
87
89

90
91
92

93
9:4

96
97
99
100
101
102
103
105
107
112
114
118
124
121
131
132
133
134
135
136
137
138
139
140
141
142
143

INDENT Control
JUSTIFY Control
LINE LENGTH Control
NO CONCATENATE Control
NO FORMAT Control
NO JUSTIFY Control
OFFSET Control
PAGE Control
PAGE LENGTH Control
PAGE NUMBER Control
READ Control
SPACE Control
SINGLE SPACE Control
TAB SETTING Control
TOP MARGIN Control
UNDENT Control
SPLIT
STATE
UPDATE
Execution Control
EXEC
Special Features of EXEC
LabelsEXEC Words (&words)
Numeric Variables
Keyword Variables
Exec-Set Keywords
User-Specified Keywords
Exec Control Words
Profile EXECGENMOD
GLOBALLOAD
LOADMOD
REUSE
START
USE

$
Debugging Facilities
CLROVER
DEBUG
BREAR
CAW
CSW
DEF
DUMP
GO
GPR
IPL
KX
ORIGINPSWRESTART
v

144
145
146
lLJ7

148
149
150
151
152
153
154
155
156
157
158
159
164
167
168
113
115
119
119
179
180
180
180
181
181
188
189
192
196
202
204
206
208
210
212
214
218
221
227
228
229
232
235
238
240
241
242
244
246

RETURN

SET
STORE
TIN
X

SETERRSETOVER
Language Processors
ASSEMBLE
Assembler Language Programming
Program Naming
Program Entry
Program Exit
Linkage to CMS Commands and Routines
CMS Macros
C1<EOF Macro
CMSREG Macro
CMSYSREF Macro
ERASE Macro
FCB Macro
FINIS MacroRDBUF Macro
SETUP Macro
STATE Macro
TYPE Macro
TYPIN Macro
WRBUF Macro
OS MacrosOMS Routines (Functions)
ATTN Function
CARDIO Function
CONWAIT Function
CPFUNCTN Function
ERASE Function
FINIS Function
HNDINT Function
HNDSVC Function
POINT Function
PRINTR Function
RDBUF Function
STATE Function
TAPEIO Function
TRAP Function
TYPE Function
WAIT Function
WAITRD Function
WRBUF Function
FORTRANFORTRAN Programming
Sequential I/O
Direct Access I/O
Terminal Output
Fortran Files
vi

2q1
2q8
251
254
255
258
261
267
268
213
273
213
213
27q
276
278
219
280
281
282
283
284
286
281
288
290
292
294
291
299
300
301
302
303
304
305
301
308
309
310
311
312
315
316
311
318
319
321
328
328
333
334
335

I/O Format Conversion
PLI
PL/I Programming
Compilation Notes
PL/I Library
Loading of PL/I Program
Executing a PL/I Program
Terminal I/O
Passing Parameter to a PL/I Proqram
I/O Via Files
Error Recovery
Other Limitations
SYSIN/SYSPRINT to User·s Terminal
PL/I Subroutines
IHECMS--PL/I Initialization Routine
IHECLOK--PL/I Clock Routine
IHEFILE--PL/I File Access Routine
SNOBOLSNOBOL Programming
Subroutines
Input/Output
Subroutine Generation
Linkages
Debugging Aids
BRUIN
utilities
CNVT26
COMPARE
CVTFV
DISK
DUMPD
DUMPF
DUMPRESTECHOFORMAT
MAPPRT
MODMAPOSTAPE
SORT
STAT
TAPE
TAPEIOTAPRINTTPCOPYWRTAPE
Control Commands
BLIP
CHARDEFCPFUNCTN
IPL
KO
KT

KX
vii

336
338
342
342
342
342
342
343
343
345
346
347
347
349
350
351
352
355
359
359
359
360
361
361
363
364
365
366
368
370
373
374
375
377
379
383
386
387
389
392
394
399
401
402
404
406
407
408
410
411
412
414
415

LINENDLOGINLOGOUT
RELEASERT
SYN
Libraries
MACLIBTXTLIB
Text Libraries
SYSLIB TXTLIBBLIP Subroutine
NLSTON/NLSTOF Subroutines
CPNMON/CPNMOF Subroutines
DEFINE Subroutine
DSDSET Subroutine
ERASE Subroutine
GETPAR Subroutine
LOGDSR Subrou1:ine
RENAME Subroutine
REREAD Subroutine
TAPSET Subroutine
TRAP Subroutine
CMSLIB (Non-Error-Message FORTRAN Library)
PLILIB--PL/I Library460
SSPLIB--FORTRAN Scientific Subroutine Library
Macro Libraries
SYSLIB--Systero Macro Library
OS~ACRO--OS MACRO Library
CP-61 CONSOLE FUNCTIONS
Console Function Descriptions
Console Functions
BEGIN
CLOSE
DETACHDISCONNDISPLAY
DUMP
EXTERNAL
IPL
IPLSAVE
LINI<
LOGOUT
MSG
PURGE
QUERY
READY
RESET
SET
SLEEP
SPOOL
STORE

viii

416
418
421
423
425
426
429
430
435
440
441
442
443
443
445
448
450
451
452
453
454
455
458
459
461
462
462
462
463
464
465
467
468
470
472

473
418
480
481
483
484
481
488
489
490

493
494
495

498
499
502

XFER
Console Function Applications

506
508

CP-67 Messages

510

Operating Considerations
Offline Procedures'I'ape Procedures
Library Usage
Macro Libraries
Text Libraries
Recovery Procedures
Errors During CMS Login
Error Specified by the E(xxxxx) Message
Recovering·s From the System Going Down
Reinitializing CMSFile Space Full
General Recovery Procedures
Changing Object Programs
Set Location Counter (SLC) Card
Include Control Section (rCS) Card
Replace (REP) Card
Entry Card
Library Card

511
511
512
513
513
514
516
516
516
516
511
517
518
519
520
522
523
524
525

CMS Batch Monitor
Sample Batch Jobs
eMS Batch Control Cards/ / P,SSEMBLE// COMMAND// CP// DATASET// FORTRAN

526
526
528
530
532
533
534
535
538
540
541
542
543
543
543

/ / GO// PRINT// PUNCH// TEXT
Running the CMS Batch Monitor
Setup
Using CMS Batch

545

GLOSSARY
APPENDIX A:
APPENDIX B:
APPENDIX C:APPENDIX D:APPENDIX E:
APPENDIX F:APPENDIX G:APPENDIX H:
APPENDIX I :Control Program Console Functions
CMS Commands
Debug Requests
Edit Requests
Script Control Words
CMS Functions
Format of Commands, Requests, and Console Functions
CP-67 Machine Configuration
Devices Supported by CMS

ix

550
552
557
559
561
564
566
584
588

FIGURES1

IBM 2741 Keyboard (PTTC/EBCD Configuration)22

2

IBM 2741 Keyboard (Standard Selectric
Configuration)

22

IBM 1052 Switch Panel23

IBM 1052 Keyboard

23

5

Filetype implication and characteristics

39

6

Output form the LISTF command

115

7

Creation and printing of a CMS EXEC file116

8

Two examples of PRINTF commands which
type out an entire file

125

A PRINTF command which types out a MACRO
definition

125

A PRINTF command which types out the bottomof a FORTRAN listing file

126

11

Contents of a SCRIPT file

160

12

SCRIPT output

162

13

Exam~leof an EXEC file to compile, load,and execute a FORTRAN program

177

The file FORT EXEC is created, the file CMS
EXEC is typed out, and then an implied EXEC
is issued to nest EXEC·s

118

Sample offline printout of trace information
recorded by the SETOVER corr~and

217

16

Sample procedure for setting breakpoints

226

17

Sample output created by a FORTRAN commandin which the LIST and SOURCE options were
specified225

Examples of the SET request, using otherrequests as appropriate to inspectcontents both before and after SET isissued250

Sample DUMP output from the offline printer

234

3

9

10

14

15

18

19

x

20

Examples of the GPR request

239

21

Examples of the STORE request, using theX request to inspect the contents both
before and after storing

253

22

Examples of the X request

251

23

Sample offline printout of trace information
recorded by the SETERR command

260

Offline printout showing trace information
recorded by the SETOVER command with theoptions GPRSB, FPRSA, and NOPARM specified

265

Offline printout showing trace information
recorded by the SETOVER command with theoptions SAMELAST, PARMi, and WAIT2
specified (SAMELAST in this example refers
to the options as set in Figure 24)

266

26

Example of eMS Macros

277

21

RDBUF error return codes

285

28

WRBUF return codes

293

29

FORTRAN compilation with errors

324

30

INTENTIONALLY OMITTED

31

FORTRAN compilation with options

325

32

Multiple FORTRAN compilations

326

33

Summary of record formats and I/O statements
for sequential FORTRAN files

330

Files referenced by sequential FORTRAN I/Ostatements

332

File referenced by direct access FORTRAN I/Ostatements

334

Samples of the three types of nucleus map
files created by MAPPRT. Only the first few
entries of each are shown

384

37

Example of MACLIB LIST command

432

38

Printout of the CMSTYPE macro definition
using PRINTF

433

24

25

34
35
36

xi

39

Example of the TXTLIB LIST comroand

437

40

ExaJllple of a normal NAMELIST function

444

41

Example of a freeform NAMELIST function

444

42

output from DUMP console function

479

43

Format of an SLC card

521

44

Format of an ICS card

522

45

Format of a REP card

523

46

Format of an ENTRY card

524

47

Format of the LIBRARY card

525

48

Sample eMS batch stream

527

49

eMS batch control cards

529

xii

INTRODUCTIONCOMPONENTS OF THE SYSTE~
The
CP-61/CMS
time-sharing system
consistsoftwo
independent components: the Control Program (CP-67, or CP
for short) and the Cambridge Monitor System (CMS).
The
Control Program creates the time-sharing part of the system
to allow many users to access the cowputer simultaneously.
The cambridge Monitor System provides the conversationalpart of the system to allow a user to monitor his work froma remote terminal.
Both components are independent of each other. CP-61 can beused on an appropriate configuration without CMS, and CMS
can be run on a properly configured System/360 as asingle-user system without CP-67. If CP-61 is used without
CMS, an operating system (or systems) must be chosen toprovide the conversational or production aspect of thesystem, as CP provides only the time-sharing capability.
CP-61 is capable of running many System/360 operating
systems concurrently (including CP-61, OS/360, DOS, RAX, andAPL/360) as long as they
do not include any timing
dependencies ordynamically-modified channel
programs.
Dynamically-modified channel programs are those which arechanged between the time the Start Input/Output (SIO)
instruction is issued and the end of the I/O operation (thatis, changed by the channel program or the CPU). However,certain types of self-modifying channel programs can betranslated, including those generated by the OS/360 Indexed
Sequential Access Method (ISAM).
CP-61 is also capable of running System/360 operating
systems along with eMS in a multiprogramming mode concurrent
with its usual time-shared. multiaccess operation.
If theSystem/360 operating
system contains
telecommunication
facilities or remote job entry/remote job output support, CP
allows that system to control the lines of the 2701. 2702,
or 2103 transmission control unit and allows the user todial into that system froID a remote terminal.
SYSTEM ENVIRONMENTThe environment of CP-61 is one of "virtual machines". A
virtual machine is a functional simulation of a realcomputer and its associated I/O devices.
CP-61 builds andmaintains for each usera virtual
System/360 machine from a predescribed configuration. The
virtual 360 is indistinguishable to the user and his
programs froK: a real System/360, but it is really one ofmany that CP-61 is managing.
CP allocates the resources of
INTRODUCTION

1

the real machine to each virtual machine in turn for a short"slice" of time, then moves
on to the next virtual
machine--thus time-sharing.
since
the
virtualmachinesaresimulated,
theirconfigurations may differ from each other and from the realmachine. For instance, the real machine may have 512K andeight disk drives, and the virtual machine can have 768K and
two disk drives. One virtual machine may have a virtual
2702 and run an OS teleprocessing system, and anothervirtual ~achine that does not have a virtual 2702 may run
CMS. One virtual machine may have a remote printer and aremote card punch, while another virtual 360 may have a
dedicated
printer
and2250.
Regardlessoftheconfiguration, each user controls his virtual machine fromhis remote terminal, which is, in effect, his operator's
console.
Like
realmachines, virtual
machines
operateroost
efficiently under an operating
system.
The Cambridge
Monitor System (CMS) is designed to allow full use of asystem/360 through a simple command language entered at theconsole (in the case of a CP-67 virtual machine, at the
remote terminal).
CMS gives the user a full range ofcapabilities--creating and managing files,
compiling andexecuting problem programs, and debugging--using only his
remote terminal.
Since each user has his own virtual
machine with his own copy of CMS residing "in it", nothing
he does should affect any other user: if he destroys the CMS
nucleus or abends the C~S system, he can reIPL his virtual
machine and continue without disturbing other users.
In
addition, since users cannot get "outside" their virtual
machines, CP-67 is protected from any user error.
CMS also provides a batch version intended primarily for"compile, load, and go" type jobs coming from tape or cards.
The batch rr.onitor can be run from a virtual machine as a
background system with conversational eMS users on othervirtual machines.
THE CONTROL PROGRAM, CP-67
Before a user is authorized to use CP, he must be assigned a
USERID, which identifies him to the system. and a password,
which is checked when he ftlogs inft. Associated with each
USERID is information
concerning accounting, privilegeclass, options desired, and a table describing the virtual
machine assigned to that user. Whenever he logs in, CP sets
up this virtual 360 machine for him.
Although all thevirtual machines may be different, most are set up with theconfiguration expected by CMS, the most commonly used
operating system.
They include at least 256K of virtual
core storage, a minimum of two disk drives, a console (the2Im'RODUCTION

terminal>, a card read punch unit, and a printer. The realsystew usually has a larger number of disk drives, a drum,
tape drives, and perhaps more core storage.
Because there is not room in real core for all users'
virtual core"a technique called "paging" is used by thesystem. Virtual core is divided into 4096-byte blocks ofstorage called ·pages·. All but ~urrently active pages are
kept by the system on direct access secondary storage: thisdirect access space is allocated only on a demand basis: asactive and inactive pages change status they are "paged" inand out of real core on demand. While the paging operation
is being performed for one virtual machine, another can be
operating. The paging operation, and resultant allocationof real core to a given user's pages, is transparent to theuser. Special hardware is provided on the System/360 Model
61 that translates, at execution time, the user's (or user
program's) addresses into the current real addresses of therelocatedpages.
This iscalled"dynamicaddresstranslation" and is transparent to the user.
All virtual machine I/O operations are handled by CP, whichmust translate them into real machine I/O operations. Thisrequires two translations, accomplished as follows:CPintercepts all user I/O when Start I/O (SIO> is issued. Ittranslates virtual
device addresses into
real device
addresses, translates virtual core storage addresses into
real core storage addresses, ensures that all necessary
pages are in real core storage, builds a channel command
word (CCW) string for the user, and issues SIO when thechannel is free.
The virtual machine is not given control
from the time it issues an SIO until CP issues the real SIO
and delivers the resulting condition code to the virtual
machine. In the meantime, other virtual machines may be
executing. When CP receives an interrupt indicating I/Ocompletion, it sets an interrupt pending flag in the user's
virtual machine status table; when control is returned to
the virtual machine, the proper I/O interrupt is simulated.
Virtual machine unit record I/O is normally spooled onto
disk by CP. Thus, any card deck to be "read" by a virtual
machine would, in the normal case, have been read by CP
before the user's call for it on his virtual machine. ortransferred to that user from another user's files via the
XFER console function in CP; the physical deck must havebeen preceded by a card containing the USERID, so that CP
can know who will read the card-image file. Later, when thevirtual machine has read the card deck, a card reader end of
file is simulated.
Card and printer output, similarly
spooled, is not queued for physical output until CP isnotified of end of file in one of three ways: the user logs
off the systerr (end of file is assumed): the CLOSF console
function specifies the (virtual) address of the device to be
INTRODUCTION

3

closed; or CP detects an invalid Ccw addressed to the device(end of file is assumed). Further output for a closed
device is assuwed to start a new file. So that the system
operator can separate physical output, CP precedes all
printed and punched output files with a record containing
the USERID.
The CP console functions allow the user to control his
virtual machine frow. the terminal wuch as an operator
controls a real machine. To perform an IPL, for instance,
the user types IPL and a device address or the name of a"named" operating system, such as CMS. The user can stop
his virtual machine at any time by hitting the ATTN key andcan request display of any portion of his storage andregisters.
He can modify the contents, if desired, andrestart his machine.
CP also recognizes a few special
purpose commands, such as the XFER function mentioned above,
the QUERY function to obtain the number of users on thesystem and their USERID's, as well as the number of current
spooled files, the ~SG function to communicate with otherusers, the DIAL function to connect the terminal to amUltiaccess system, and the ATTACH and DETACH functions to
add orremove I/O
devices froma virtualmachineconfiguration (ATTACH can only be issued by the Operator) ,.
CAMBRIDGE MONITOR SYS-rEM.
The Cambridge Monitor System(CMS) is a single-user,conversational operating system capable of running on a realroachine as well as on a virtual machine. It interprets a
simple command language typed in at the operator's console(underCP-67, at the user's remote terminal).
When running on a real machine, eMS operates in the
supervisor state. When running under CP-61, CMS operates in
the pseudo-supervisor state: that is, CMS "thinks" it isrunning in the supervisor state,
but CP is actuallyintercepting and translating supervisor interrupts.
Whether running on a real machine (see note below) or a
the following
machinevirtualmachine, ~S
expects
configuration:

4

INTRODUCTION

Device
Number

VirtualAddress

1052
2311,2314
2311,2314*2311#2314*2311,2314*2311#2314

009
190
191**
192**
000**
000**
19C**

Symbolic
Name

Device Type

CON1
consoleDSKlsystem disk (read-only)
DSK2
permanent disk (user files)
DSK3
temporary disk (workspace)
DSK4
A disk (user files)
DSK5
B disk (user files)
DSK6
C disk (user files)*2311~2314
1403
OOE
PRNl
line printer
OOC
2540
RDR1
card reader
OOD
PCBI
card punch
2540
TAPI
tape drive
180
*2400
181
TAP2
tape drive*2400
at least 256R bytes of core storage, 360/40 and up*Optional devices not included in the minimum configuration**This virtual address may be changed at any time by the
CMS LOGIN command.
Note:

For use on a real machine not having this I/O
configuration, the device addresses can be redefined atload tiroe.

Under CP, of course, these devices are simulated and mapped
to different addresses and/or
different devices.
For
instance, CMS expects a 1052 Printer-Keyboard o~erator's
console, but roost remote terminals are 2741s: CP handles allchannel prograro modifications necessary for this simulation.
CMS allows the user to add his own programs for I/O devices
not supported by the standard system. CMS also provides for
dynamic specification of SVC routines.

CMS Batch Monitor
As well as being a conversational monitor, CMS provides abatch facility for running CMS jobs. The CMS batch monitor
accepts a job stream from a tape unit or the card reader andwrites the output on tapes, on the printer, or on the card
punch. The job stream can consist of a System/360 Operating
System SYSIN job stream with FORTRAN (G) and ASSEMBLER (F)compile, load, and gojobs calling certain cataloged
procedures; or it can consist of CMS commands. along with
control cards and card decks for compile, load, and go jobs
for all the CMS-supported compilers.
Like the conversational CMS, the batch monitor can run
either from a virtual machine or from a real machine. Under
CP, it can be used as a background monitor along with otherconversational eMS users.
INTRODUCTION5

To eliminate the possibility of one job modifying the CMS
batch monitor·s nucleus in such a way as to affect the nextjob, eMS is reIPLwed before each job begins. Files can also
be written onto the batch monitor's permanent disk and thenpunched or printed (such as files written by FORTRAN
programs); these files should be of limited size andconsidered temporary. as they are erased at the completionof each job.
CP-67/CMS SAMPLE TERMINAL SESSION
A sample terminal session is described and illustrated
below. User input is in lowercase; typeout from the systemappears in uppercase.
After logging in to CP-67 and initializing CMS, the user,
eSC1, issues a LISTF command to obtain a list of all files
stored on his read-write disks. To allow multiple comroands
to be entered on one line, there is a line-end character.
The LINEND comroand is issued
to define the line-end
character as the exclamation point (!) and to allow thepound sign (n) to be used as the logical tab character in
EDIT. The file MAIN FORTRAN is then created and filed on theuser's per~anent disk. Compilation of the file is terminated
due to prograro errors (indicated by a $ symbol below theerror encountered). The file is then Fodified and edited tocorrect the line in error, and the new source file stored on
disk. Again an error is encountered and the file reedited.
After a successful compilation, the $ command is called toload the file into core and execute it.
LOAD and START
perform the saroe function as $ (as shown). Specifying theXEQ option with the LOAD command also causes execution to
begin after the file is loaded.
LISTF and ERASE commands are used to selectively list anderase files, and the PRINTF command is used to print all,and then part, of the contents of a file. KT causes typeout
to be discontinued if entered after the ATTN key is hit
twice.
The OFFLINE command punches or prints the specified file on
offline devices. The ALTER command changes the identifier ofa file.
KX, entered after hitting ATTN twice, stops
execution of the current program, reloads a new copy of eMS,
and returns control to CMS.
An EXEC file (consisting of CMS commands) is created andfiled.
The file is then executed by issuing the EXEC
command, which causes each of the commands contained in thefile to be executed individually. Operand substitution is
illustrated by modifying and reexecuting the file using
6

INTRODUCTION

ampersand (&) arguments.
Hitting ATTN once transfers control to the Control Program.
where the QUERY console function is issued to determine thenumber of users on the system. their names. and the messageof the day from the operator. The BEGIN console function
then returns control to CMS and the user logs out from botheMS and CP-67.
The sample terroinal session follows.

INTRODUCTION7

itcp-67 online

xd.65 qsyosu

login cscl<-------The user·s id is specified upon logging in.
ENTER PASSWORD::<----------------------------------The protected password does
CP WILL BE UP 24 HOURS A DAY
not print when entered.
READY AT 09.14.49 on 11/27/69
CP
ipl cms
CMS ••• VERSION nn

LEVEL

rom

listf
FILETYPE ~ODE NO.REC.
003
Pl
INDIANLISTING
009
DUMPREST SYSINPlSUPERSCR SYSIN
010
Pl
MY
001
FORTRANPl
002
INDIANTEXT
Pl
001
FORTCLG EXEC
P1
LOAD
P5
003
MAP
FIN
Pl
001
SCRIPTTUESSCRIPTPl001
FRSTSCRIPT
Pl
001
007
DUMPREST LISTING
Pl
001
AGENDAPiSCRIPTINDIAN
001
FORTRANPlRi T=0.06/0.21 09.16.12
FILENA~E

DATE
8/18
8/20
8/22
8/26
8/29
8/29
8/30
8/30
8/31
8/31
9/01
9/01
9/01

linend !
Ri T=0.01/0.02 09.16.20
edit main fortran
NEW FILE.
INPUT:
c main program Nov. 21, 1969
write (6,10)
10Jformat (I a = .) <--------The # is a logical tab character that
#read (5,20) a
inserts blanks and places the following
20#format (8.3)
characters typed on the line into column#write (6.25) a,x
1 of the card image in a FORTRAN file.
#call exit
#end<--------Carriage return with no data enteredEDIT:
on line (that is, a null line) takes
fileuser out of Input mode into Edit mode
Ri T=O.08/0.51 09.18.31
of the EDIT command.

8

I Nl'RODUCTI ON

fortran main
0004

20
01)

FORMAT (8.])$
IEY013 I
SYNTA,X
IEY022I

UNDEFINED LABEL

25
E(00008); T=0.29/0.92 09.1P..42
edit main fortran
EDIT:
print 20

C MAIN
1020PROGRA~
NOV. 27, 1969
WRITE (6,10)
FOR~AT (' A = ')READ (5,20) A
FORMAT C8.3)
WRITE (6,25) A,X
CALL EXI1'

END

EOF:
locate /forrrat/
10
FORMAT Ce A = ')locate /forrr.at/
20
FORMAT CR.])change /8/f8/
20
FORMAT CF8.3)
up 2
10
FORMAT (' A = ')change / ' / ? ' /10
FORMAT (' A = ?')find 20
20
FORMAT CF8.3)
insert #x = a**2<--------Carriage return hit to confirm
environment the user is ine
EDIT:
print
x = A**2
topprint 20

C ~AIN PROGRA~~OV. 27. 1969
WRITE (6,10)
10
FORMAT (' A = ?')READ
20
FORMAT (Fa.3)
X = A**2
WRITE: (6,25) A, X
CALL EXIT
END

EOF:
file
INTRODUCTION

9Ri T=0.16/1.08 09.21.34

fortran main
IEY022125
E(OOOOS); T=O.30/0.94 09.21.43

UNDEFINED LABEL

edit ~ain fortran
EDIT:
locate /25/
WRITE (6,,25) A,X
insert 25#format C' a = 'f8.3,' x = 20.3)
print
25
FOR~AT (9 A = 'F8.3,' X = 20.3)
change /20/' f20/

25
FORMAT C' A = -F8.3,' X = ' F20.3)
file
Ri T=0.12/0.64 09.23.16
fortran main (list source)

Ri T=0.31/0.97 09.23.35$ mainEXECUTION BEGINS •••
A = ?
2.5
A =
2.500 X =Ri T=0.28/0.94 09.24.01

6.250

load main

Ri T=0.23/0.78 09.24.14
start
EXECUTION BEGINSo ••
A = ?
3.1
A

=

3.100 X =9.610

Ri T=0.04/0.18 09.24.29

load wain (xeq)
EXECUTION BEGINS •••
A = ?
3.2
1\ =
3.200 X =Ri T=0.26/0.93 09.24.50

10.240load roain!start<------The! allows multiple
Ri T=0.23/0.74 09.25.04
commands per line.
EXECUTION BEGINS •••
A = ?
2.5
2.500 X =
A =
10

6.250
INTRODUCTION

Ri T=0.04/0.13 09.25.15

listf main *FIL~NAME FILETYPE MODE NO.REC. D~TE
MAIN
LISTING
P1
003
11/27
MAIN
FORTRAN
P1
001
11/27
MAIN
TEX~
Pl
002
11/27
Ri T=0.02/0.07 09.25.23
listf * listing
FILENAME FILETYPE MODE NO.REC. DATE003
8/18
INDIANLISTING
P1
003
11/21
MAIN
LISTING
Pl001
8/20
DUMPREST LISTINGPl
Ri T=0.02/0.01 09.26.08
erase * listing
T=0.03/0.10 09.26.30

Ri

listf * listing
FILE NOT FOUND
E(00002); T=O.01/0.04 09.21.05
printf main fortranC MAIN PROGRAM
NOV. 27, 1969
WRITE (6 11 10)
10
FORMAT (. A = ? ')READ (5,20) A
20
FO~AT (FS.3)
X = A**2
WRITE (6,,25) A,X
25
FORMAT (' A = 'FS.3,' X = • F20.3)
CALL EXIT
END

Ri

T=0.03/0.09 09.27.23

printf rrain fortran* 3 25

NOV. 27
WRITE (6,,10)
FORMAT (. A = ? .)C MAIN PROGRAM

10R; T=0.02/0.08 09.30.47

printf main fortranC MAIN PROGRAM
NOV. 27, 1969
WRITE (6,,10)
10 "CP<------------------------ATTN was hit once to enter CP<-----------~------------ATTN was hit a second time
INTRODUCTION

11kt <------------------------to kill typeout
R: T=0.03/0.09 09.31.02
offline punch main texti~SSfortran <--The four a characters delete
R: T=0.03/0.14 09.31.32
the previous four characters.
offline print main fortran
R: T=0.03/0.10 09.31.40
offline print main listing
FILE NOT FOUND
E(00002); T=0.Ol/0.05 09.31.53
listf
FILENAME FILETYPE MODE NO.REC. DATE009
8/20
DUMPREST SYSIN
Pl
010
8/22
SUPERSCR SYSIN
P1
8/26
001
FORTRAN
MY
P1
8/27
001
FORTCLG EXEC
P1
8/30
P5
003
MAP
LOAD
001
11/27
FORTRAN
MAIN
Pl
8/30
P1
001
FIN
SCRIPT
8/31
001
TUES
SCRIPT
Pl
8/31
001
P1
FRST
SCRIPT
9/1
001
AGENDASCRIPT
P1
11/27
002
MAIN
Pl
TEXT
9/1
001
INDIANFORTRANP1
Ri T=0.05/0.14 09.33.05
alter main fortran * mainone
R: T=0.02/0.12 09.33.28* *listf main fortran
FILE NOT FOUND
E(00002): T=O.02/0.05 09.33.35
listf * fortran
FILENAME FILETYPE MODE NO.REC. DATEMYFORTRANPI
001
8/21
MAINONE FORTRAN
P1
001
11/21
INDIANFORTRANP1
001
9/1
R: T=0.01/0.01 09.33.45$ mainCP<-------------------ATTN was hit once to enter CP<-------------------ATTN was hit a second timekx <-------------------to kill execution
CMS •• VERSION n

LEVEL

m

listf mainonnae * <----- The a deletes one character.
FILENAME FILETYPE MODE NO.REC. DATE
MAINONE FORTRAN
P1
002
11/27
12

INTRODUc-rION

R: T=O.03/0.17 09.34.25

edit fortclgo exec
NEW FILE.
INPUT:
fortran 1I1ainone$~load mainone (xeq)
EDIT:
file
R: T=O.07/0.43 09.35.02

printf fortclgo exec
FORTRAN MAINONE
LOAD ~AINONE (XEQ)
R: T=O.02/0.06 09.35.11

exec fortclgo
09.35.23 FORTRAN ~AINONE
09.35.27 LOAD
MAINONE (XEQ)EXECU~ION BEGINS •••
A

= ?

3.4
A =
3.400 X =H: T=0.60/1.94 09.35.40

11.560edit fortclgo exec
EDIT:
change /mainonp/ &1/ * G
FORTRAN &1
LOAD &1 (XEQ)
EOF:
file
Hi T=0.10/0.60 09.36.17
exec fortclgo mainone
09.36.53 FORTRAN MAINONE
09.36.59 LOAD
MAINONE (XEC)EXECUTION BEGINS •••
A = ?
5.1
A =
5.100 X =26.010
R: T=0.62/2.00 09.37.10
edit fortclgo exec
EDIT:
insert &set err exit
print 9
&SET ERR EXITFORTHAN &1
LOAD &1(XEC)
INTRODUCTION

13

EOF:
file
R; T=O.10/0.S1 09.31.39
edit mainone fortran
EDIT:
print 4
C MAINPROGRA~
NOV. 27, 1969
WRITE (6.10)
10
FORMAT (. A = ?')blank aa
FORMAT (. A = ?')next
READ (5,20) A
change /read/red/
RED (5 , 20) P<.
file badone
R: T=O.13/0.71 09.40.15

listf * fortran
FILENAME FILETYPE MODE NO .. REC. DATEMYFORTRANP1
001
8/27
MAINONE FORTRAN
Pl
001
11/27
INDIANFORTRANP1
001
9/1
BADONEFORTRAN
Pi
001
11/27
R: T=O.03/0.11 09.41.23
exec fortclgo badone
09.41.36 FORTRAN BADCNF
0002
FORMAT (' A = ?')$0003

01) IEY0021
LABEL
RED (5,20) A$ $01) IEYOOI1 ILLEGAL TYPE
IEY022I
10!!! E(00008)!!!

R: T=0.36/1.02 09.42.03
edit fortclgo exec
EDIT:
change /&1/&1 &2 63 &4 &5/
FORTRAN &1 ~2 &3 &4 &5
LOAD &1 &2 &3 &4 &5 (XEQ)
EOF:
file
R: T=O.11/0.65 09.43.00

14

* 9

INTRODUCTION02)
IEY013I SYNTAXUNDEFINED LABEL

exec fortclgo mainone
09.43.19 FORTRAN MAINONE
09.43.28 LOAD
MAINONEEXECUTION BEGINS •••

A = ?
1.9
A =
1.900 X =R; T=0.64/2.21 09.44.10

(XEQ)

3.610

CP
<-----------ATTN was hit once to enter CP.
query user
14 USERS. 00 DIALED
query user names
LOVE- 044,SEYMOUR-02A,OPERATOR-009,~EYER -045,-028,
ROSATO - 024,NEWSON -040,LEVEY-027,BOYD
DJL- 056,BURR-062,SHIFLDS -051,SCHUPP -055,
EDNA- 043,CSCl-026
query logmsg
CP WI~L BE UP 24 HOURS A DAY
begin
CMS

<-----------------BEGIN returns contrel to CMS.

logout
T=S.49/20.S3 10.24.42
CP ENTERED, REQUEST, PLEASE.
CP
logoutCONNECT= 02.50.17 VIRTCPU= 000.05.49
LOGOFF AT 10.25.06 ON 11/27/69

INTRODUCTIONTOTCPU=OOO.20.54

15

CP-61 TERMINAL USAGE
The conversational input/output device used to access the
CP-67/CMS system is referred to as a "terminal" and isoperated by a·user" who types informationthat istransmitted
eitherbytelephone
line
or
by
permanently-connected wiring to acomputer, where theinformation is receiveo and processed by the system.
In
addition to receiving and processing information, the system
may cause information to be typed out at the terminal.
Information typed frorr the terminal keyboard by the user iscalled "input": that typed out at the terminal by the system
or by a user prograw is called "output".
Anyoneof four terminals may be used to access thesystere. These are the IBM 2141 Communication
Terminal, the IBM 1050 Data Communications System Terminal,
the Type 33 Teletype Terminal, and the Type 35 Teletype
Terminal. Any of these terminals may be connected to thecomputer by direct wiring or by telephone lineo
If theterminal is not directly wired to the computer, a data-phone
is placed near the terminal keyboard,and must be used todial an installation-specified number in order to establish
a connection with the computer. The procedure for using adata-phone is described under "CP Login" in the "Terminal
Usage-Logging Procedures· section.
CP-67/C~S

Terminals which are equivalent to those explicitly supported
also fUnction
satisfactorily.
The customerisresponsible for establishing equivalency.
IBM assumes noresponsibility for the irrpact that any changes to theIBM-supplied products
or programs
way haveon suchterminals.

~ay

16

Terminal Usage

2741 CHARACTERISTICS
The IBM 2741 Communication Terminal consists of an IBM
Selectric typewriter mounted on a typewriter stand.
The
stand
includesthe electronic
controls
neededforcommunications, a cabinet for mounting a data-phone. a rack
for mounting a roll of paper, and a working surface. For
use with the CP/CMS system, the 2741 should be equipped with
the Transmit Interrupt and the Receive Interrupt features.
The 2741 has two modes of operation: communicate mode andlocal mode. The mode of the terminal is controlled by theterminal mode switch. which is located on the left side of
the typewriter stand.
When in local mode. the terminal is
disconnected from the computer. It then functions as a
typewriter only, and no information is transmitted or
received. When in communicate mode. the terminal may beconnected to the communications line to the computer. The
power switch on the right side of the keyboard must be set
to ON before the terminal can operate in either communicate
or local mode. The procedure for establishing connections
with the computer and the terminal switch settings whichshould be used are discussed below under "2741 Initiation
Procedures".
Either of two 2741 keyboard configurations may be used inaccessing the CP/CMS system.
These are the PTTC/EBCD
configurations (shownin Figure 1) andthe standard
Selectric configuration (shown in Figure 2). On either
keyboard. the alphameric and special character keys, thespace bar, power switch,. the SHIFT. LOCK, TAB, tab CLR SET.
and MAR REL keys all operate in the same way as standard
Selectric typewriter keys.
On most 2741 terminals, the space bar. backspace. andhyphen/underline keys have the typamatic feature. If one ofthese keys is operated normally, the corresponding function
occurs only once.
If the key is pressed and held, thefunction is repeated until the key is released. The RETURN
and ATTN keys have special
significance on the 2741
keyboard.
The RETURN key is hit to signal the termination of each
input line. When RETURN is hit. control is transferredto the system. and the keyboard is locked until thesystem is ready to accept another input line.
The ATTN key
is used to generate
an attention
interrupt. It may be hit at any time (since it is neverlocked out) and causes the keyboard to be unlocked toaccept an input line. Refer to "Attention Interrupt"
for a discussion of the transfer between environmentsthat occurs when an attention interrupt is generated.
Terminal Characteristics

17

The 2741 paper controls (such as the paper release lever,line-space lever, impression control
lever, etc.) are
identical to the corresponding controls on an IBM Selectric
typewriter and operate accordingly.
Any invalid output character (one which cannot be typed by
the terminal and for which no keyboard function, such as tab
or carriage return, exists> appears in terminal output as aspace. For a further discussion of 2741 characteristics,
refer to the 2741 component description manual (GA24-3415).
2741 INITIATION PROCEDURES
The steps for preparing the 2741 for use are described
below. After these steps have been performed, log in.
1. set the terminal mode switch located on the left side of
the typewriter stand to LCL. This ensures that the terminal
is disconnected from the computer.
2. After making sure that the terminal is plugged in, turnthe power on by pressing the ON portion of the terminal
power switch at the right side of the keyboard.
3. Check to see that the margin stops, which are located on
the typing guide just above the keyboard, are set at thedesired positions (normally 0 and 130). If so, proceed tostep 4. To reset a margin stop, push it in, move it to thedesired position, and release it.
4. Check that the tabs are set at the desired intervals bytabbing an entire line using the TAB key.
If the settings
are satisfactory, proceed to step 5. Note that these tab
settings do not govern the internal positioning of input
characters.
For a discussion of internal tab settings,
refer to EDIT. If the tabs are to be reset, position thetyping element to the right margin, press and hold the CLR
portion of the tab control keYi, and hit the RETURN key.
This clears all previous tab settings. New settings may bemade by spacing the typing element to the desired locations
and pressing the SET portion of the tab control key. Aftertab stops have been set for the entire line, hit RETURN to
position the typing element at the left margin.
I

5. set the terminal mode switch on the left side of thetypewriter stand to COM. The terminal is now ready for use.
1050 CHARACTERISTICS
The IBM 1050 terminal is composed of the 1051 Control Unit
and a 1052 Printer-Reyboard. The 1051 Control Unit includes
the power supplies, printer code translator, data channel,

18

Terminal Characteristics

and control circuitry needed for 1050 operation. To be usedwith the CP/CMS system, the 1051 should be equipped with theTime-out suppression and the Transmit Interrupt and Receive
Interrupt special features. The 1052 keyboard is similar inappearance to the standard IBM typewriter keyboard. Figures
3 and q illustrate the 1050 switch panel and keyboard. The
alphameric and special character keys, the space bar, LOCK,SHIFT, and TAB keys,. and the paper controls operate in thesame way as those on a standard IBM typewriter.
The
following keys are of special significance on the 1052
keyboard:
RETURN. If the Automatic EOB special feature is included on
the terminal being used, and if the EOB switch on the switch
panel is set to AUTO. the RETURN key may be used toterminate an input line. otherwise,(if the Automatic EOB
special feature is not available on the terminal being used,
or if EOB on the switch panel is set to MANUAL) the
character transmitted when RETURN is hit is considered partof the input line.
ALTN CODING. This key, when pressed and held while one ofthe other keys is hit j,originates a single character codesuch as restore, bypass. reader stop, end of block (EOB),
end of address (EOA), prefix, end of transaction (EOT), or
cancel.
Note that input lines frow 1050 terminals not
equipped with the automatic EOB special feature must be
terminated by pressing the ALTN CODING key and holding it
down while hitting the 5 key.
This procedure causes a
carriage return at the terminal.
RESET LINE. Hitting this key (at the left side of the
keyboard) causes an attention
interrupt (provided theterminal is equipped with the Transmit Interrupt special
feature). The RESET LINE key may be hit at any time, since
it is never locked out" and causes the keyboard to be
unlocked to accept an input line. Refer to -Attention
Interrupt- fora discussion of thetransfer between
environments which occurs when an attention interrupt isgenerated.
RESEND. This key and its associated light (both located on
the right of the keyboard) are used during block checking.
The light comes on when an end-of-block character is sent by
the terminal; it is turned off when receipt is acknowledgedby the system.
If the light remains on, indicating anerror, RESEND may be hit to turn off the light!, and theprevious input line may then be reentered. While the lightis on, no input is accepted from the keyboard.
LINE FEED. This key causes the paper to move up one or twolines,. according to the setting of the line space levert,
without moving the typing element.
Terminal Characteristics

19

DATA CHECK.
This key should be hit to turn off theassociated light (to its left), which comes on whenever alongitudinal or vertical redundancy checking error occurs,
or when power is turned on at the terminal,.
Any invalid output character (one which cannot be typed by
the terminal and for which no keyboard function, such as tab
or carriage return, exists> appears in terminal output as aspace. For further information on the characteristics andhandling of the 1050 terminal, refer to the 1050 reference
digest (GA24-3020).
1050 INITIATION PROCEDURES
The procedure for preparing the 1050 for use are described
below. When these steps have been performed, log in.

1. After making sure that the terminal is plugged in, set
the panel switches (shown in Figure 3) as follows:
switchSetting

SYSTEMMASTER
PRINTER1PRINTER 2
KEYBOARDREADER1
READER 2
PUNCH1PUNCH 2STOP CODE
AUTO FILL
PUNCH
SYSTEMEOB
SYSTEMTESTSINGLE CY
RDR STOPOFF
SEND REC
REC
SEND
OFF
OFF
OFF
OFF
OFF
OFF
NORMALPROGRAMsee below
(up)
OFF
OFF
OFF

ATTENDIf an EOB switch appears on the terminal, it may be set toeither AUTO or MANUAL. If it is set to AUTO, the RETURN key
may be used to terminate an input line. If the EOB switch
is set to MANUAL, or if it does not appear on the terminal,
all input lines must be terminated by hitting the 5 key
while the ALTN CODING key is pressed and held down.
2.
Check to see that the margin stops--the two blue
indicators invisible in the transparent strip just below theswitch panel--are set as desired (normally at 0 and 130).
If so, proceed to step 3.
To change margin settings, set

20

Terminal Characteristics

the PRINTER1 and :KE¥BO}\JID swi tches to HOME.
Turn power onat the terrninaiby s·ett:ing t!he Il'a.inline switch to POWER ON.
Move the typingelemen't. 1tO 1i::he center of the line by spacingor tabbing. 1)urn pow.e:oc- 'off at the terminal.
Lift the top
cover of the lC52 and ,t·li.lt down the hinged portion of thefront panel.
Press tb,p blue margin indicators toward theback of the 1052 and slide theIr to the new locations.
Return the hinged panel to its original position and close
the top cover.
3. Check the tab settings by setting PRINTERl and KEYBOARD
switches to HOME, turning power
on at the terminal,
positioning the typing element at the left margin,andhitting the TAB key repeatedly.
If the tab settin~s are
satisfactory, proceed to step 4.
Note that terminal tab
settings do not governinternal positioning of input
characters.
For a discussion of internal tab settings,
refer to EDIT. If the tabs are to be reset,
position thetyping eleroent to the right margin.
Lift the tab setting
switch,labeled CLR/SET, and hol~ it while hitting the
RETURN key.
This clears all previous tab settings.
New
settings way be made by spacing the typing element to thedesired locations ana then pressing down on the tab setting
switch. After tab stops have been set for the entire line.
hit the RETURN key to position the typing element at theleft margin. Turn off power at the terminal.
4. Reset the PRINTERl switch to SEND REC
switch to SEND.

and the KEYBOARD

5. Turn the roainlin€ switch to POWER ON
the Login procedure.

and continue withTerminal Characteristics

21

Figure 1.

IBM 2741 Keyboard (PTTC/EBCD Configuration)

Note: When this keyboard and associated prinl elements are specified the mechanical changes in the keyboard mechanism
determine the li;le code assignments of the graphic characters. These arrangements are not compatible with theassignments provided by the use of the PTTC/BCD and PTTC/EBCD keyboards and associated print elements (see CodeChart, Figure 6).

Figure 2.

22

IBM 2741 Keyboard (Standard Selectric
Configuration)

Terminal Characteristics

SYSTEMMASTER

PRINTER 1

PRINTER 2

KEYBOARDREADER 1

READER 2

PUNCH 1PUNCH 2STOP CODE AUlO Fill

PUNCH

SYSTEMEOB

SYSTEMTESTSINGLE CY

RDR STOP111111111111111111,,111111," ,I"" I" 111,",11"'/"11 1111,1 I:, Ii 1111111"1,, 1,1" "II,,, I"" I"" I,,, ,I,,, Ii,,, ,I II III,,, ,/"" I~

Figure 3.

~

'~.~

J

_~

<

IBM 1052 Switch PanelD
om D D
D

FEED

D
D I

Figure 4.

RESENDI

IBM 1052 Keyboard

Terreinal Characteristics

23

TYPE 33 TELETYPE CHARACTERISTICS
The KSR (Keyboard Send/Receive) model of the Teletype Type33 terminal is supported by CP-67.
The Type 33 KSR includes
a typewriter keyboard,a control panel, a
data-phone,
control circuitry for the teletype, and roll paper.
The
Type 33 RSR keyboard contains all standard characters in theconventional arrange~ent. as well as anumber of special
symbols. All alphabetic characters are capitals. The SHIFT
key is used only for typing the "uppershift" special
characters.
The CTRL
key(Control key)isused inconjunction with other keys to perform special fUnctions.
Neither the SHIFT nor CTRL key is self-locking; each must be
depressed when used.
In addition to the standard keys,
the keyboard contains
several non-printinq keys with special functions.
Thesefunction keys are as follows:LINE FEED generates a line-feed character and moves thepaper upone line
without ~oving
the printing
roechanis~.
When the terminal is used offline, the LINE
FEED key should be depressed after each line of typing
to avoid overprinting of the next line.
RETURN is the carriage return key
physical end of the input line,.

and signifies

the

REPT repeats the action of any key depressed.
BREAK generates an attention interrupt and interrupts
program execution.
After breaking program execution,
the BRK-RLS button must be depressed to unlock the
keyboard.
CNTRL is used in conjunction with other keys to perform
special functions.
The tab character (Control-I) acts
like the tab key on the 2741.
Control-H acts like thebackspace key on the 2741.
Control-Q and Control-E
produce an attention interrupt like BREAK if theteletype is in input mode.
Control-S(X-OFF)
andControl-M act as RETURN. Control-D (EOT) should not be
used as i t may disconnect the terminal.
Control-G(bell), Control-R (tape), Control-T(tape), and allother Control characters are legitimate characters eventhough they have no equivalent on the 27ql.
HERE IS and RUBOUT are ignored by CP-67.
ESC (ALT MODE on soree units)
generates a legal character.

24

is not used by CP-67, but

Terminal Characteristics

The control panel to the right of the keyboard contains six
buttons below the telephone dial, and two lights, a button,
and the NORMAL-RESTORE knob above the dial. The buttons andlights are as follows:
ORIG{ORIGIN.ATE}. This butt.on obtains a dial tone
before dialing. The volume control on the loudspeaker(under the keycoard shelf to the right)
should beturned up such that the dial tone is audible.
Afterconnection with the computer has been made, the volume
can be lowered.
CLR(CLEAR).
This button, when depressed,
the typewriter.
ANS(Answer).

TS~(TEST).

turns off

This button is not used by CP-67.
This button isused for testing purposes

only.
LCL
(Local). This button turns
local or offline use.

on the typewriter for

BUZ-RLS(Buzzer-Release).
This button turns off thebuzzer that warns of a low paper supply. The light in
the BUZ-RLS button remains on until the paper has been
replenished.
ERR-RLS(Break-Releas~).
This button unlocks the
keyboard after prograw execution has been interrupted
by the BREAK key.
REST.

This light is not used by CP-67.

NORMAL-RESTORE. This knob is set to NORMAL, except tochange the ribbon, in which case the knob is twisted to
the OUT-OF-SERV l~ght. The knob is then set to RESTORE
and returned to NORMAL when the operation has been
completed.
OUT-OF-SERV(Out of Service). This light goes on when
the NORMAL-RESTORE knob is pointed to it for ribbon
changing.
Most teletype units have a loudspeaker and a volume control
knob {VOL}located under the keyboard shelf.
The knob isturned clockwise to increase the volume.
TYPE 35 TELETYPE CHARACTERISTICS
The KSR (Keyboard Send/Receive) model of the Teletype Type35 terminal is supported by CP-67.
The Type 35 KSR, likethe Type 33 KSR, includes a typewriter keyboard, a control
Terminal Characteristics

25

panel. a data-phone, control circuitry, as well as roll
paper. The Type 35 has basically the same features as theType 33. The additional features of a Type 35 are thefollowing:
LOC-LF (Local/Line Feed). This button operates as the
LIND FEED
button without generating
a line-feedcharacter. It is used along with the LOC-CR.
LOC-CR (Local/Carriage ~eturn). This button returns
the carrier as RETURN does without generating an
end-of-line character. LOC-CR is normally used only tocontinue a line of input to the.next line.
LOC-BSP (Logical/Backspace). This button generates acharacter but it has no meaning with the KSR model.
BREAK. This button generates an attention interrupt
and interrupts program execution.
After execution has
been interrupted, BRK-RLS, and then the K buttons must
be depressed to unlock the keyboard.
K (Keyboard).
This button unlocks thesets the terminal for page copy only.

keyboard andMost Type 35 terminals have a volume control knob (SPKR VOL)
for the loudspeaker located to the right of the keyboard.
Turning the knob clockwise increases the volume.
A column indicator at the uoper right of the keyboard
indicates the coluwn that has just been printed. When the
LOC-CR key is used. no end of line is recorded and thecolumn indicator does not reset.
A red light to the right of the column indicator warns theuser that the carrier is approachinq the right marginQ

26

Terminal Characteristics

CP-67/CMS CONVENTIONSLOGGING PROCEDURES
This section
describes the procedures whichroust beperformed at the terminal to begin and to terminate use of
the CP-67/CMS system. For the procedures of connecting auser to a multiaccess system such as RAX or APL,
refer towDialing a Multiaccess System w •Before the facilities o£
the CP-67/CMS system are made available to a user, he must
identify himself to the Control Program by giving his userid
and his password (two identifiers which are assigned to hiro
at the time he is authorized to use the system).
This
identification procedure is referred to as CP Login. When
CP Login is completed, a console function may be issued toinitialize CMS, as described below.
Note.
During the LOGIN procedure CP-67 uses the line
time-out feature when reading the userid and password.
If
the user fails to type any character for 28 seconds, theline will time-out and be disablen.
When the user has co~pleted his use of the system, hesignals this fact by issuing a WlogoutW to the Control
Program.
The period between CP Login and CP Logout isreferred to as a terminal session.
CP Login
After the terminal has been prepared for use (as describedunder ftTerminal Characteristics n )the procedure described
below must be performed in order to gain access to the
CP-67/CMS system.
(Note that input may be entered in either
uppercase or lowercase. Uppercase is used below to indicate
words which must be typed as they are shown; lowercase
indicates fields whose contents may vary.)
1.
A
communications line tothe computer
must beestablished. If the terminal is directly wired to thecomputer this is automatic, and you may proceed to step 2.
If the terminal is a Teletype 33 or 35, depress the ORIG
button, rr.ake sure the dial tone is audible, and then dial
the installation-specified number and proceed to step 2; the
ORIG button is lighted at this point--if the light goes out
during the terminal session, this CP Login procedure must be
repeated.
Otherwise, a data-phone is placed near theterminal and should be used to establish a communicationline with the computer as follows: After making sure thatthe plug from the data-phone is connected to the walljack,press the button labeled TALK, lift the receiver, and dial
the installation-specified number. When a continuous tone
is heard, press the button labeled DATA and replace thereceiver.
The DATA button should now be lighted, andLogging21

remains lighted as long as the terminal remains connected tothe computer.
If this light qoes out at any point during
the terminal session, the CP Login procedure must be
repeated.

2. The system acknowledges that a communication line has
been established by typing one of the following messages:
CP-67 ONLINE

xxxxxxxxxxxx

xxx:xxxxxxxxx

CP-67 ONLINE

CP-67 ONLINE
The first message is typed if the terminal is a 1052 or 2741
equipped with an EBeD character set. If the second message
istyped, the2141
basa standard
Selectricor
correspond'~ncecharacter set.
Ineither case,thexxxxxxxxxxxx portion of the message consists of meaninglesscharacters and should be ignored.
If the terminal is a
Teletype Type 33 or 35, the third message is typed.

3. At this point the system must be notified that someone
wishes to use the terminal. To do this, hit ATTN once. On
the Teletype 33 or 35, hit BREAK and then BRK-RLS.
4. The system responds by unlocking the keyboard on a 2141
or 1052 or waiting for input on the Teletype 33 or 35.
5. Identify yourself to the system by typing LOGIN userid,followed by a carriage return, where userid is your user
identification.
Note.
The LOGIN
and userid cannot
character-delete or line-delete symbols.
6.

beeditedusing

The system responds with one of the following messages:

ENTER PASSWORD:
This message indicates that yourbeen accepted. Proceed to step 1.

user identification

has

RESTART
If this roessagei:s ,typed" the word LOGIN has been enteredincorrectly. Return to step 5 and retype the input line ..
LOGGED IN ON DEV xxx
RESTART
This message indi.cat:es ·tha~t another user with the sameuserid is log.gedonat the terminal whose address is xxx.
You will not ~e ~ble to log in with the same userid until
the other user has legged off.

28

Logging

USER NOT IN DIRECTORY.
RESTART
If this message is typed, an invalid userid
specified. Return to step 5 and log in again.

has

been

MAX NO. OF USERS EXCEEDEDLOGGED OUT AT xx.xx.xx ON xx/xx/xx *** BY OPERATOR***If the keyboard unlocks or CP-67 waits for input, return tostep 5.
If the message is typed, the system is alreadyservicing the maximum number ofusers and the login
procedure is terminat~d. In this case wait for a few
minutes" and then try again by returning to step 1.
UPDATING DIRECTORYRESTART
The CP-61 system directory is being updated.
In this case,wait a few minutes, and then try again by returning to step5.

7. Type your password, followed by a carriage return: thepassword may be edited.
If the 2741 terminal is equippedwith the Print Inhibit feature, the password is not typed at
the terminal as the keys are hit. The Print Inhibit featureapplies only to the typing of a password. If the terminal isa Teletype 33 or 35,
three lines of characters are
overprinted before you are allowed to enter your password.
8. At this time, if there are any cards in the virtual card
reader or output for the printer or punch, the message
FILES:- xx RDR, xx PRT. xx PUN
is typed. If the CP operator has set any log messages forthe day, they are typed also.
9.

The system responds with one of the following messages:

READY AT xx.xx.xx ON xx/xx/xx
where xx.xx.xx is the time of day and xx/xx/xx is the date.
This message indicates that the password has been accepted
and the CP log in procedure is completed. The Control
Program environroent has been entered, and any console
function roay be issued. To initialize CMS, proceed to step
11. To initialize any other operating system proceed tostep 10.
PASSWORD INCORRECT.
RESTART
If this message is typed, an invalid password has been
specified and the log in procedure is repeated. Return tostep 5.

Logging29

10~ Any operating system can now be loaded into the virtual
machine. To load in CMS, go to step 11. To load in anotheroperating system, issue the IPL console function to CP-67,
specifying the device froro which the system is to loaded.
For example, IPL 293 or IPL OOC. If the device that is
IPL'ed contains an operating system (such as OS/360>, yourterminal becomes the operator's console. For information on
running os under CP-61. see WOS/360 in a CP-67 Virtual
Machine w , by C. I. Johnson, IBM Cambridge Scientific Center
Report 320-2035. Cambridge, Massachusetts, March 1969 .•CMS

Initialization

11.

To initialize CMS., issue the console function
IPL 190
or
IPL CMSfollowed by a carriage return. This causes a copy
CMS nucleus to be brought into core from disk.
12.

of theThe message
CMS ••• VERSION nn LEVEL rom

where nn is the version level and mm is the modificationlevel, is typed, and the keyboard is unlocked. The CMS
Command environment has control at this pOint,
and any CMS
command may be issued.
CP Logout
When the user has finished using the system and wishes to
end his terminal session, he should do so by logging out
from the Control Program. If the user is not already in theControl Program environment at the time he wishes to log
out, he may enter this environment by hitting ATTN once.
The keyboard is unlocked and the user types LOGOUT, followed
by a carriage return. The system responds with
CONNECT=hh.rom.ss VIRTCPU=mmm.ss.hs TOTCPU=~mro.ss.hs
LOGOUT AT xx.xx.xx ON xx/xx/xx
and the connection to the computer is lost. The connect timeis in hours, minutes, and seconds; the virtual CPU, andtotal CPU times are in minutes, seconds, and hundredths 011 a
second. The logout procedure is then completed, a~d theuser may turn power off at the terminal.
If the user desires to end his terminal session, but not
lose the connection with the computer so that another user
may log in from the terminal, the user types LOGOUT
30

Logginganything. followed by a carriage return. The "anything"must be at least one character or any combination ofcharacters. The connection with the computer is not lost
and the CP-61 ONLINE message is typed out for the next user
to log in. as in step 2.

Logging31

DIALING A MULTIACCESS SYSTEM
This section
describes the procedures whichmust beperformed to connect a user to a system that provides
multiterminal facilities. such as APL or RAX..
The processof placing a user into a multiaccess system is referred toas "dialing". The system to be dialed into must be logged
onto CP-67 (as in the logging procedures writeup) with some2102 or 2103 lines available
and enabled before theconnection can be made.. When the connection is made, dialing
has been completed, and the terminal is under the control ofthe system dialed into; consequently, the user is not known
to CP-67 as a regular logged in user but as a dialed user.
When the user has completed his use of the multiaccesssystem,. he should log out of that system in the appropriatemanner; when that mUltiaccess system issues a "disable"command for that terminal, the 'terminal will be free foranother user to login to CP-67/CMS or to dial a multiaccesssystem.
Dialing
After the terminal has been readied for use (as described in"Terminal Characteristics·) i, the procedure described below','must be performed to gain access to a mUltiaccess system.
(Note that input may be entered in either uppercase or
lowercase. Uppercase is used below to indicate words whichmust be typed as they are shown; lowercase indicates fields
whose contents may vary.)
1-4. These steps are, as
pages earlier.

for ·CP Login", described several

5. Specify the multiaccess system to which you wish to gain
access by typing
DIAL

systeIII

followed by a carriage return.
of the mUltiaccess system.

where "system" is the userid

Note.
DIAL
and
systemcannotbecharacter-delete or line-delete symbols.
6.
The systeromessages

thenresponds withone

editedof theusing

following••• connected •••This message indicates a connection has been made between
the terminal and the multiaccess systerr, and the terminal is
now under control of that system. Further responses will bethose of the multiaccess system, as the user cannot get to32

Dialing

CP-61 to issue console functions.

system ALL LINES BUSYRESTART
There are no 2702 or 2703 lines available on system. Thelines way not be available for anyone of the threefollo~ing reasons: 2102 or 2103 lines are not defined in thevirtual machine, the virtual lines are not enabled bysystem. or all of the lines are in use.
system NOT AVAILABLERESTART
The system being dialed is not logged in to CP-67.
system LINES NOT READYRESTART
The system has not issued an enablelines.

for the 2702

or 2703system NO DIAL LINESRESTART
The system has no 2702 or 2703 lines in its virtual machine
description.
£isconnecting
The dialed terminal remains connected to system until one of
the three following events occur:(1) system issues a disable for that terminal.
This isusually brought about by logging out of system in thecorrect manner.

(2)
system issues the CP console
specifying the terminal address.

function

DETACH.

(3) system logs out of CP-67.

When the terminal is disconnected from system, the following
message is typed out:
CP-67 LOGOUT

The terminal can now be used to log in to CP-67, or to dial
into a mUltiaccess system again.

Dialing

33

GENERAL TYPING CONVENTIONS
The typing conventions described below should be observed
when entering input to the CP-67/CMS system from a 2741,
1050, or a Teletype 33 or 35 terminal.
Input may be entered in either uppercase or lowercase.
When the keyboard is unlocked on the 2741 or 1050. theterminal is ready to accept input.
The keyboard r~mains
unlocked on the teletype, therefore a > (greater than sign)
is typed at the left marqin when the teletype is ready toaccept input. If the user types too soon on the teletype,
an interrupt may occur which will probably cause the user togo back to CP: if this happens, type BEGIN to return towhere you were previously.
The character-delete symbol (a) may be used to delete thepreceding character in the input line.
n character-delete
symbols delete the preceding n characters in the input line
and themselves. Exception: This feature does not apply withtheK-levelcomroandsortheRTcommand.
The
character-delete symbol can be redefined by the CHARDEF
command for use in eMS: it can never be redefined for CP.
The line-delete symbol, which is the¢on the 2741 or
1050, and the shift K (left bracket) on the teletype, may be
used to delete all characters in the current input line anditself. A line-delete symbol(¢l cannot
be deleted by acharacter-delete symbol(a).
Exception: This feature does
not apply with the R-level commands or the RT command. The
line-delete symbol can be redefined by the CHARDEF commandfor use in CMS; it can never be redefined for CP.
An input line may be a maximum of 130 characters in length.
Any line longer than
130 characters--including delete
symbols, blanks, and the tab character--is truncated to 130
characters.
On the teletype 33, an input line can only
contain a maximum of 72 characters.
An input line from the 2741 or teletype is terminated byhitting RETURN. To terminate an input line from the 1050,
hit the 5 key while holding down the ALTN CODING key, unlessthe 1050 is equipped with the Automatic EOB special feature.
If this special feature is available and the EOB panel
switch is set to AUTO, input lines may be terminated byhitting RETURN.
Input lines~ can contain a number of logical input lines
Eachwhich are separated by the. line-end character (#).
call to read a line from the terminal returns alogicalinput line.
Subsequent calls to read a line from theterminal return the logical input line which was typed

34

Typing conventions

following the previous logical input
single input line

line~

For exarople. the

FORTRAN ABLE # $ ABLE
causes the file ABLE FORTRAN to be compiled, loaded, andexecuted. The single input line to the EDIT environment
T # L /BUFT/ # C /FT/FFER/
causes the characters BUFT to be located and changed to
BUFFER. The line-end character can be changed with theLINEND command for use in CMS: it cannot be redefined forCP.

An output line on the 2741 and 1050 can be a maximum of 130
characters.
Any line longer than 130 characters causes
overprinting at the right margin. On the teletypes, lines
longer than 72 characters in length are printed as twolines; the first line cuts off after the 71st character, andan up arrow is printed at the end of the line to indicate
continuation.
Illegal output characters appear in terminal typeout as
spaces. An illegal output character is one which cannot be
typed and for which no keyboard function, such as a carriage
return or a tab, can be generated.
On the Teletype 33 or 35 terminal, the arrow translates tounderscore ( ), the backslash translates to a not sign (~),
and the uparrow to a vertical bar (1).
One or more blanks are used to delimit the fields
input line to the CMS command environment.

Typing Conventions

of an

35

ATTENTION INTERRUPT
After a phone connection with the computer has been made andthe message "CP-61 Online" has been printed, pressing theattention key causes the CP login procedure to begin, or the
dialing of a multiaccess system to begin.
The user's machine may be interrupted (stopped) an1 theterminal readied for input at any time by pressing theattention key (marked ATTN) on a 2141, hitting the RESET
button on a 1050, or the BREAK key on the Teletype 33 or 35.
This causes control to pass to CP provided that the Control
Program was not already in control. CP console functions
can then be issued.
After a previous attention (pressing ATTN) causes control topass from CMS to CP, a subsequent attention passes control
back to CMS. If C~S previously had control and was reading
a line from the terminal (that is, the keyboard was
unlocked), the CMS program is restarted and the keyboard is
unlocked again. If CMS previously had control and was notreading a line from the terminal (that is, the keyboard was
locked), the interruPtion permits a single line of input tobe entered and stacked. Stacked lines of input are used on
successive calls to read a line from the terminal until
there are no more stacked lines.
Input is then taken
directly from the terminal. After a line to be stacked isentered, CMS continues from the environment which was lastinterrupted. Any number of lines m~y be input and stacked
in this way.
When entering two attentions to the system to stack input,
ATTN should not be pressed the second time until the
keyboard has been unlocked in
response to the firstattention. If the second attention is entered before the
keyboard is unlocked. it is ignored.

36

Attention Interrupt

CMS FILE CONVENTIONS
One of the purposes of C~s is to provide the user withvarious file-handling facilities.
Files to be use0 under
CMS may be stored on disk, cards, or magnetic tape.
However, most CMS cowmands assume that files are stored on
disk. This rreans that files stored on media other than disk
wust be transferrea to disk before rrany of the CMS commands
can be issued for thew.
The commands which deal withtransferring files
between disk and othermedia arediscussed
under
"File
Creation,
Maintenance,
andManipulation".
conventions given in this section apply to disk files only.
Disk Facilities
Disk areas are available to each CMS user for storing
inforwation. A user may have up to five read/write disks andone read/only (that is, the syste~) disk attached to his CMS
virtual machine at anyone time. These areas are referred toas the user·s disks although the size of each area seldow
constitutes an entire physical disk. The sizes of a user's"mini" disks are assigned by the system administrator at thetime he establishes that person as an authorized user of the
CP-61/CMS system.
These assigned sizes are based on theamount of disk space available and the amount which the user
is likely to require.
P-ssigned disk sizes may vary amongusers.
The logical names of the disks a user may have are P, T, A,
B, S, and C. This order is normally the standard order ofsearch for C~S files. All users normally have a P (191) andan S(190) disk. The P disk contains user files retained
between terwinal sessions until the user erases them either
collectively or singly.
The S disk (that is, system disk)
contains the C~s nucleus of which each user receives a copy,
and the disk resident portion of CMS which is normallyshared by all users. The system disk is read-only--anyattempt to write on it is denied and causes an error message
to be typed to the user.
The T (192) disk contains information that is retained only
from the time it is created until the user terminates his
terminal session. The A, B, and C disks contain informationthat is retained between terminal sessions as does the P
disk.
Before a user can access the P, T, A, B, or C disk for the
first time, he must format each one by issuing the FORMAT
command in c~S.
If the disks are not properly formatted,
I/O errors occur.

File Conventions

37

Infor~ntation stored on~isk is organized into
files.
on the system disk are referred to as system files.

Files

File Identifiers
Each file must have a unique identifier, which is composedof a filename, a filetype, and a fileu1ode. This identifier(or a portion of it) is used by the various CMS cowmands toaccess user and systew. files.
If a new file is created with
an identifier identical to that of an existing user file,the original file is erased.
The filename may be any combination of from one to eight
nonblank EBCDIC characters, provided the first character is
not a zero or an asterisk. with system files, the filenameis the name which is issued by the user in calling a
specific command, and it is also the name of the program
whose code
constitutes thatcommand.
Permanent
andtemporary files may be assigned any filename the user
wishes, since filenaroes in themselves do not have any
special implications in eMS.
Filetype may be any combination of from one to eight
nonblank EBCDIC characters, provided the first character is
not a zero or an asterisk. Certain filetypes imply specificfile characteristics to CMS. Fil~types which have specificimplications for user files are given in Figure 5. The user
may assign any of the filetypes in this figure to any file
he wishes, but he should note that the commands which use
these filetypes are notsuccessfully executed if thecontents of the file are in any forro other than that which
the assigned filetype implies.

38

File Conventions

Filetypes
AED
ALPHABET
ALPHANUM
ASP360
ASl130
BRUIN
COBOL
COPY
CVTUTl
DATA

t"Ij

I

Record Format Created by
and Length
These Commands
F
F

F
F
F

F

F
F

80

F

132
80

DAxx

F
F

DIAG
EXEC
FILE

V or F(FILE)V or FFLOW
FT01FOOl
FT02FOOIFT03FOOl
FT04FOOIFTOSFOOIFT07FOOl
FT08FOOl
FT09FOOIFT10FOOl
FORTRANINTERLISTING

F
F
F

~.

80
80
80
80
80
80
80
80

F

EDIT, OFFLINEMAPPRT
MAPPRTOFFLINE, EDITOFFLINE, EDITBRUIN
OFFLINE, EDIT
EDIT, OFFLINECVTFVEDIT, OFFLINEFORTRANASSEMBLE
EDIT, OFFLINE, LISTF
EDIT, CEDIT, OFFLINE

F

F

F
F
F
F
F
F

F
F
F

80

MAP

F

72

MACLIB
LOAD, USE, REUSE, $

(j

132
80

MACLIB, TXTLIBEDIT, OFFLINE

MAP

F

o

MEMO

F

<

MODULENUMERICPLIPRINTERREPSSCRIPT
SNOBOL
SPLI
SYSIN
SYN
SYSUTISYSUT2
SYSUT3
TEMP FILETEXT
TXT LIBV max:6SK
80
80
F
132
F
80
V max:i32
F
80
F
80
F
80
F
80

F
F

80
80

.. TYPE ..
UPDATEUPDLOGUTILITY

F
F
F

80
80
80

:::1

~.

o
~

en

EXEC,

EDIT, OFFLINEFORTRANFORTRANFORTRANFORTRANFORTRANFORTRANFORTRANFORTRANFORTRAN
EDIT, OFFLINEFORTRANUPDATEASSEMBLE, FORTRAN, PLI PRINTF, EDIT, OFFLINEMACLIBrt

MACLIBCOMBINE, DISK, TAPE

It~

MACLIB

80
80
80
80
80
80
80
133
140
80
80
80
121

.....

<t)

For Use by
These Commands*

F
F

V'
V
V

ASSEMBLE, GLOBALGENMOD
LOADMOD, $MAPPRT
EDIT, OFFLINEPLIEDIT, OFFLINEPRINTF
EDIT, OFFLINESCRIPT
EDIT, SCRIPTSNOBOL
EDIT, OFFLINESNOBOLSNOBOLASSEMBLE, UPDATEEDIT ,OFFLINESYNEDITASSEMBLE, PLI
ASSEMBLE, PLI
ASSEMBLE, PLI
SNOBOLASSEMBLE, PLI, FORTRAN LOAD, USE, REUSE,TXTLIBGLOBAL,LOAD,USE,
REUSE, $OFFLINEUPDATE
EDIT, OFFLINEUPDATE
CNVTFVI

Usage
AED source code
Alpha listing of nucleus load map
Alpha and numeric listing of nucleus load map
Assembler language macros
1130 Assembler source code
Bruin source code
Cobol source code
Assembler source code
Utility file created by CVTFVUser data files
Direct access Fortran files
Assembler diagnostics
CMS and/or EXEC commands
User data files or utility file createdby EDIT and CEDIT
Utility file created by either COMBINE, DISKor TAPE
Flowchart input data
Fortran input/output file
Fortran input/output file
Fortran input/output file
Fortran input/output file
Fortran output file
Fortran input/output file
Fortran input/output file
Fortran input/output file
Fortran input/output file
Fortran source code
Utility file created by UPDATE
Assembler or compiler output containing source
statements and machine code
Assembler language macro definition library
Map of locations of loaded programs(Filename is LOAD)
Map of library file
Memorandum file - contains upper and lower
case data
Non-relocatable object code
Numeric listing of nucleus load map
PL/I source code
Printer output and listing files read onto disk
Replace cards for modifying TEXT files
Script input and/or output
SNOBOL source code
SNOBOL object code
Assembler language source code
Synonyms or abbreviations
Utility file created by Assembler or PL/I
Utility 'file created by Assembler or PL/I
Utility file created by Assembler or PL/I
Utility file created by SNOBOL
Relocatable object code
Library of relocatable object code
Utility file created by OFFLINE
Update control and replacement cards
Log of applied updates
Utility file created by CNVTFV* Other commands may use these filetypes; these are only the pertinent commands.

I.N\D

Figure 5.

Filetype implication and characteristics

Several of the CMS commands create files for their own use
and assign specific filename-filetype combinations to thesefiles.
These filename-filetype combinations are listed
below, and should not be assigned by the user
filename

filetype

creating command• TEMPCMS(INPUT1)(INPUT2)(TEMP)LOAD
SNOBOL• DUMMY(DISK)•• NAME ••BCDEBC

BRUIN
EXEC
FILE
FILE
(FILE)
MAP
TEMPFILETXTLIB(TFILE)• • TYPE .••UTILITY

BRUIN
LISTF
EDIT, CEDIT
CEDIT
COMBINE
LOAD,$,USE,REUSESNOBOL, SPLlTXTLIB
DISK, TAPE
OFFLINE
CNVT26

In addition to the above, note that if a user file iscreated whose filenawe and filetype are identical to thoseof a file on the disk-resident portions of CMS, the standard
order of search may access one user's file in place of thesystem file.
Reasons for this are described in "CMSCommands".
The third portion of the identifier, filemode, consists of
two characters. The first character is a letter indicating
the disk area on which the file resides: S for system disk,
P for perrranent disk, and T for temporary disk, etc. For
system files, the second character is always Y.
For userfiles, the second character is a number from one to six.
These numbers have the following meanings, although therestrictions they imply may not currently be implemented in
all cases:
1 or 5--file may be written or read.
2 or 6--file is read-only.
3--file may be written or read,file is closed.
4--file isclosed.

read-only, and isbut is erased when theerased when thefile is

Files are matched on the three identifiers.
If, however,both filename and filetype are explicitly given, the mode
letter only is checked (that is, the ITode number is ignoredon the match). However, if either the filename or filemodeis implied with a *. the mode number is matched together
with the mode letter.

40

File Conventions

File Sizes
Files stored on disk are formatted into records 829 bytes
long. This formatting is handled internally by CMS. and is
not controlled by the user. The maximum CMS file size
(assuming that the user·s assigned disk area can accommodateit), is 24.358 million bytes, or 65,533 records. If a fileconsists of a source language program .• a size limitation may
be imposed by the language in which that program is written.
and this size may be smaller than the 24.358 million bytes
allowed by CMS. The maximum disk file for user disks is 203
cylinders each. Although there is no inherent limitation to
the number of files a user may create. he is limited
practically by the sizes of his disk areas. When a user has
filled either of these areas. a message to this effect is
typed at his terminal. Refer to "Recovery Procedures" forsteps to be taken in this case.
A file is "accessed" when any portion of it is read or
written. Whenever a file is accessed for the first time by
a CMS command or function, the file is automatically opened.
Opening in this case consists of making an entry into theuser·s active file table. All open files are closed by CMS
after the successful execution of any CMS command. The user
does not need to be concerned with opening and closing
files.
Disk con~iderations:Read-only disks.
There are several ways a user can force anormally read-write
disk (that is, P/,T.A,.B,C)
to be
read-only.
If the user LINRs to a disk that is read-only in the CP
directory, then he has read-only access to that disk.
A disk may be logged into CMS as a read-only extension of
the P disk (for example;, LOGIN 196 B,P). This forces thedisk to a read-only status, and concatenates the B disk to
the P disk in the standard order of search.
A disk may be logged into CMS as a forced read-only disk bymaking it an extension of itself (for example. LOGIN 195
A.A). A user may thereby protect certain files by forcing
them to be read-only.
On read-only disks it is possible to login a portion of thefiles on that disk. See the LOGIN command for details on
how this done.
T-Disk.
The T-disk is automatically logged in when theuser IPL·s CMS if 192 is attached and ready, and the labelon that disk is readable and is CMS=T-DISK. If the label is
File Conventions

41

readable but not CMS=T-DISK., the disk is not logged in. If
the label is not readable, an automatic FORMAT T (NOTYPE) isissued.
C-LISK. The C disk's (19C) special usage lies in its ability

to be a read-only extension of the system disk by means of amodification to the system at installation time. Thus. if
the S disk is full and additional routines are needed aspart of the system, they may be placed on the C disk. For
example. the C disk could contain an old version of the CMS
system disk. Thus it's routines would be used only if they
were not present on the more recent system disk.
Formatting disks. The very first time a user logs in to CMS,
he should issue a FORMAT command to format his disk areas
into the CMS format.
For details on FORMAT, see the CMSFORMAT command.

42

File Conventions

ENVIRONMENT CONVENTIONSEach input line which is typed at the terminal by a user istransmitted to the CP/CMS system, where it is processed(examined, and accepted or rejected) by a given routine.
The particular routine by which input is processed isdetermined by which portion of the system has control at thetime the input line is entered.
Each portion of the system
to which input
may be entered constitutes
a uniqueenvironment, and only a subset of all possible input isacceptable to any given environment.
The following are theenvironments of the CP/CMS system:
Control Program environment
CMS Command environment
Debug environment
Edit environment
Input environment
Echo environment
In addition to these six specific environments, input may beentered to any otherexecuting program which expects
terminal input.
These other input-processing programs aregrouped into a seventh, Program environment, in which theacceptability of an input line
is determined by the
executing program.
the
exception of
the Program
environment, theinput-processing routines fall into three main categories:
input is received by either
the Control Program (CPenvironment), a central CMSservice routine (CMS Commandenvironment), or a particular CMS command (Debug, Edit,
Input, and Echo environments).
Input lines which areacceptable to the CP environment are referred to as ·console
functions·,. since for the most part they simulate functions
that can be performed at a System/360 console. Input to the
CMS Command environment may be any CMS command. Note that cp
console functions can also be issued from the CMS commandenvironment (see CPFUNCTN command).

~ith

A certain number of the CMS commands cause environments of
their own to be entered. These are the DEBUG, EDIT, andECHO commands. Lines acceptable to the environments ofthese commands are referred to as ·requests·, or merely·input-, depending on the particular environment which isentered when the command is issued. The EDIT command causes
either one of two environments to be entered.
If it isissued for a file which
already exists, the editing
environment is entered, allowing
the contents of theexisting file to be examined and modified. If an EDIT
command is issued for a file which does not currently exist,
the input environment is entered, allowing the file to becreated. The Input ·environment accepts any input typed at
Environment Conventions

43

the terminal, and this input becomes a part of the file
being created. The Echo environment also accepts any input
line, but repeats that line as output in order to test
terminal transmisssion.
Because nocheck is made to
determine
the acceptabilityof inputto thesetwoenvironments{, lines which are acceptable are termed merely
input. The Debug and Edit environments, on the other hand,
accept only specific input lines, which are referred to as
requests.
To verify at any time which
RETURN can be hit.

environ~ent

theuser isin,various actions by the user cause control to pass from one
environment to another.
These actions are specified indetail throughout this guide. Note that ATTN can always be
used to transfer control to the CP environment from any of
the other environments.
Hitting ATTN while in the CP
environment causes the keyboard to be unlocked, permitting
one line of input to be entered. If the line entered is aK-type CMS command (1<T" KX, 1(0) or the RT command, it isexecuted immediately and control returns to the environment
from which CP was entered.
If the line entered is not a
K-type eMS command or the RT command, the line is stacked to
be used as terminal input and control returns to theenvironment from which CP was entered.
As many lines as
desired may be stacked in this way to be used in place of
successive lines of terminal input.

44

Environment Conventions

CP-61/CMS Environments. Commands. and Reguests
These are illustrated below.
CP

CMS

INPUT

EDIT

DEBUG

ECHO

LOGIN
Q USERSIPL 190-> LISTF(file does not exist)
EDIT-------~-----~--->(file exists)
EDIT------>
PRINT
NEXT
FIND
LOCATE
DELETECHANGEINPUT-----> xxxx
xxxx
TOP(null line)
RETYPEFORTRAN<---FILE
PRINTF
LOAD
START
ERASE
DEBUG----------------------------> x
store
dump
CPFUNCTN<------------------------ restart
ECHO-----------------------------------------> abc
SCRIPT<-------------------------------------- return
OFFLINEMSG <----(press ATTN key)
BEGIN--->LOGOUT<-----

Environment Conventions

45

eMS COMMANDSThe CMS commands provide user facilties for file maintenanceand ~anipulation, execution control, debugging,languageprocessing, and various utility and control operations, andare described below in alphabetical order under thesegeneral headings.
These comroands may be issued from the terminal or calledfrom user progra~s. Each command consists of a command nameand its
operands, ifany.
Abbreviations
have been
established which allow the user to specify only as many
characters of each command name as uniquely identify thatcommand.
In the case of commands with the same leading
characters" the more commonly used command has been assigned
theshorter abbreviation.
For
example,A istheabbreviation for the ASSEMBLE command, and AL for ALTER.
Any number of additional characters beyond the minimum may
be specified in the command name.
For this reason, AL, ALT,
ALTE, and ALTER all identify the ALTER command.
The following is a list of the minimum number of charactersrequired to invoke CMS coromands:
SysteroCommands
ASSEMBLE
ALTER
CLOSIOCPFUNCTN
DEBUG

EDIT
FORTRAN
GENMODLISTF
OFFLINE
PRINTFSCRIPT
STAT

Shortest
Form
A

AL
CL
CP
DE
E
F
G
L

o
P
SC
S

TAPE

T

UPDATEU

If the user wants to change the abbreviations or to use
synonyms, the SYN command can be used to create the command
names,(see SYN).
The comuand name and each of its operands must be separated
by one or more blanks. The operands which are valid for eachcommand are discussed under-Format" in each commanddescription, and also in Appendix B. Each command must be
specified in a single line of input. The carriage return
signals the end of a typical input line. To stack multiple
46

eMS COFmands

CMS commands on one line of input. use the line-end
character, which is defined as # .
The line-end charactercan be redefined via the LINEND command. CMS commands cannot
be continued onto additional lines.
Each eMS command has a corresponding comman~ program which
resides in the nucleus, in a transient area. or in the
disk-resident portion of CMS. This program is i~entified by
the command word or its abbreviation. which is issued as theleftmost input on the cororoand line.
When a command is issued from the terminal, the user's
directories and the system directory are searched in thestandard order for a file with the specified filename and a
filetype of EXEC. The first file found which meets theserequirements has control transferred to it as if "EXEC
filename- had been issued. If the EXEC file is not found, acheck is made for a~breviations rr1 checking for user-definedsynonyms (see SYN) and then standard abbreviations; if amatch is found for a synonym or abbreviation, the typed
command is expanded to the original CMS command name and theabove searching sequence is repeated.
If the EXEC file search is not satisfied from above. thetables of thetransient area cororoands andthen thenucleus-resident coromands are searched for the corresponding
command program.
If the program is located in one of thetables, it is assurred to be in core, and control istransferred to it directly by a BALR instruction. If not, a
LOADMOD is issued to bring the command program into core. In
attempting to locate this program on disk, the user's
directories and the system directory are searched for a filewith the specified filename (command name) and a filetype of
MODULE, indicating that the file is in core-image form. The
first file found which meets these requirements is loaded
into core and control is transferred to it.
If the MODULE
file is not found, a check is made first for abbreviations
by checking for user-defined synonyms (see SYN), and thenfor standard system abbreviations; if a match is found for asynonym or abbreviation, the typed command is internallyexpanded to the original CMS command name, and the above
searching sequence is repeated.
This means that the user is able to substitute his own
programs for disk-resident commands by creating a core-image
file of the program and assigning it a filename identical tothat of the command it is to replace. This also means thatany user file in core-image form may be called directly as acommand. by issuing the filename (and any operands orparameters expected by the program) as an input line to ~he
CMS Command environment.

CMS Commands

41

A brief description of each CMS command is given in Appendix
A. Any invalid command, that is, one whose command program
does not reside in the eMS nucleus or transient-area and forwhich an EXEC file or a core-image module cannot be located,
is ignored, and the message INVALID CMS COMMAND is typed at
the terminal.
Operand processing is handled
by theindividual command programs, and these programs provide all
messages dealing with command format.
The format and usage of each of the CMS commands aredescribed in detail in the following sections. The generalformat for CMS commands follows.
operation< operands >command nameone or more operands delimited by spaces
field may be blank

The symbols used to represent
document are described below.

commandformats

in

this

UPPERCASE

information given in capitals must be
typed exactly as shown, although it may
be enteredin eitheruppercase or
lowercase.

lowercaselowercase information designates thecontents of a field, and does not in
itself constitute meaningful input.

( )parentheses must be typed as shown when
any of the information appearing withinthem is specified.
a period designates the beginning of a
Script control word, and must be typed
as shown.
a hyphen must be typed where shown, andmust not be offset by blanks.

/a slash denotes any string delimiter,other than blank, which does not appear
in the string.

*an asterisk, specified where shown,indicates the universality of an item or
items.

The following
typed:
48

are logical symbols

CMS Cororoands

only, and should

not be< >brackets indicate
be omitted.

< >< >

successive brackets enclose items which,if specified, may appear in any order.

«

nested brackets indicate
specified, must appear
shown.

»

information which may

ite~s

in

which, if
the order

an ellipsis indicates that the preceding
item(s) may be repeated more than oncein succession.
1

2
3

N

these suffixes indicate first, second,
third, and Nth items respectively.
underlining indicates the value which isassu~ed if
none is specified.
When nounderlined item appears in bracketed < >information, the default value is ~.
Stacked items not enclosed in anything
indicate that only one item may be
specified.

All parameters for CMS commands are positional unlessotherwise stated in the individual com~and description.
Examples of command usage and each response and error
message which may be issued are also given.
A response isany message typed at the terminal to indicate the cause ofan error return code in register 15. which terminatescommand execution.

CMS

Commands

49

FILE CREATION,~AINTENANCE,

and MANIPULATION

File Creation. Facilities are available in CMS for thehandling of disk, card, and tape files.
Most of the CMS
commands, however,require that the files they access be
stored on disk. This means that card and tape files must betransferred to disk before many of the commands can beissued for there.
Disk files can be created from terminal. card, or magnetic
tape input, or frcro other disk files.
Issuing the EDIT
command for a disk file which does not currently exist
allows the specified file to be created from terminal input.
To create a disk file from card input, the OFFLINE READ
command can be used. OFFLINE READ accepts card input in any
format.
Card files are created in CMS by requesting that thecontents of disk files be punched.
The OFFLINE PUNCH
command punches out any disk file whose records are 80
characters or less in length.
File Maintenance. Several commands provide facilities formaintaining disk files. UPDATE and EDIT allow any portion ofan existing file to be changed, deleted, or added to.
UPDATE processes the existing file against an update file,also stored on disk. EDIT allows the contents of an existing
disk file to be changed from the terminal. To change theidentifier of a disk file without changing its contents, the
ALTER command may be used. A file or group of files C3n be
deleted from disk by issuing the ERASE command. CLOSIO isused to signal the completion of output to the card punch or
printer from a user program.
File Manipulation.
eMS file manipulationconsists ofcopying. combining, reoving, splitting, and listing disk
files. To copy a disk file, the EDIT or COMBINE coromands
can be used. COMBINE also creates a new disk file from thecontents of two or more existing disk files and may be used
to transfer a file between the disk areas.
The SPLIT
command creates a new disk file coroposed of the specified
portions of an existing disk file or files.
LISTF and PRINTF cause file information to be typed at theconsole. The LISTF command types
the identifie~s and sizesof any or all files stored on the user and system disk
areas. PRINTF types out all or the specified part of a disk
file.
To print the contents of a disk file on the offline printer,
the OFFLINE PRINT, OFFLINE PRINTCC, or OFFLINE PRINTUPC
commands can be issued. OFFLINE PRINT prints the file withsingle spacing and CMS headings, the PRINTCC version uses
50

File Creation.Maintenance,Manipulation

the first character of each record as a printer carriage
control character, and the PRINTUPC version prints the filein uppercase (for MEMO or SCRIPT files when the PN train ison the printer).

File Creation, Maintenance, Manipulation

51

ALTER
Purpose:The ALTER command changes
specified filets).

the name, type,or modeof theFormat:
ALTER

ofn

oft

ofro

nfn

nft

nfm

*

*

*

*
=

*
=

*
=

of~

oft

nfn nftofn

are the original filename,filemode, respectively.

nfm are the new filename., filetype,respectively.

filetype,

andand filemode,*

An asterisk for ofn means all files with thatname" for oft means all
files with that type,and for ofm means any read-write disk.
Anasterisk for nfn, nft, or nfm means no change.

=means the same as before. no change.

Usage:The name, type, or mode number of files on a user's
read-write disk may be changed with the ALTER command. All
fields of the command must be specified.
Notes:a.
ALTER does not move files between disks. The
letter, may not be changed (see the COMBINE command).
h.
ALTER may not be used forsuch as the sytem (SY) disk.

modefiles on aread-only disk

the Readymessage, orana.
ALTER BEN SYSIN P5 PROG3 SYSIN P2
The file formerly called BEN is now referenced by
filename PROG3 and is read-only instead of read-write.

theResponses:
ALTER gives no response except
error message and code.
Examples:

52

ALTER

h.
ALTER JBS LISTING * JLEVEL3 = =The LISTING file from an assembly of JBS
by the filename JLEVEL3.
c.
ALTER * LISTING P5 = = P2
All files with LISTING type andmode P2.

is now referenced

mode of P5 arechanged toError Messages:
E(OOOOl)OLD SPECIFIED FILE CANNOT BE FOUND
The file to be redesignated is not in the file directory.
Check whether it was specified correctly.
E (00002)
NEW SP:ECIFIED FILE ALREADY EXISTS
A file with the ne~ name, type, and rr.ode already exists.
Change one of the fields of the new designation.
If
concatenation with ar existing file is wanted,
use theCOMBINE command.

E(00003)C~D ~ODE IS ILLEGAL FOR A CHANGE
The original ~ode specified is invalid--it may be for aread-only disk, or it may not end with a number frow one tosix.
E(00004)
NO CH]l,NGES WERE MADE AT AI.L
The new designation specified is the same as
designation.

the original

E(00005)
CHANGE-CF-MODE IS ILLEGAL
An attempt was made to change the mode letter. ALTER does
not move files between disks (see the COMBINE command).
E(00006)
NEW MODE IS ILLEGALThe new mode specified is not a valid one or the mode nuroberis not between one and six.
E(00007)
INCORRECT "ALTER- PARAMETER-LIST
Name, type, and mode were not specified for both files.
E(00008)
SPECIFIED FILE IS IN "ACTIVE" FILE TABLE
A fil~ may net be changed while it is active.

ALTER

53

CEDIT
Purpose:CEDIT creates and makes changes to card image files only.
Format:I CEDIT I<filename>filetype I

filename is the name of the file to be created or modified
filetype is the type of file being created or modified
Usage:
CEDIT works
only with card-image
files(fixed-lengthSO-character records).
If CEDIT is issued for larger
records (for example, LISTING
files). each record istruncated to 80
chlracters. If CEDIT isissued forvariable-length records (for exa~ple. SCRIPT files), they
are made fixed-length.
CEDIT should only be issued for files too large for EDIT.
and then only for card-image files,
as EDIT is faster.
CEDIT uses work files during editing, whereas EDIT is an
in-core editor.
The same requests used for EDIT are used for CEDIT, with the
exception of X, Y, and ZONE.
The responses are alsobaSically the same. (See the EDIT command for all requests,
responses, and error messages).
CEDIT searches all disks for the specified file.
If thefile is found its roode is saved and CEDIT writes themodified file back to the same disk. If the file is notfound~ the P disk is assumed.

54

CEDIT

CLOSIO
Purpose:CLOSIO notifies the system that I/O operations to an offline
unit record device are complete, or that output to an
offline device is to be collected before it is actually
output to the physical device.
Format:,-----~--------~--------~~--------------

I
I
I
I

READER

CLOSIOPRINTER
PUNCH

OFF
ON
OFF
ON

OFF collects files output to the specified device, but does
not output the files to the physical device.
ON

notifies the systero that I/O operations to the sgecified
device are complete and output should begin on thephysical device. ON is the default.

Usage:
CLOSIO is normally used as a supervisor-supplied function
within prograros written in assembly language.
However, it
may be used as a command in cases where user-written
programs that include unit record I/O routines terminate
abnormally, or do not include a call to CLOSIO, or whereconcatenatlon of spooled output is wanted.
CLOSIO either
notifies the system ofan end-of-filecondition for the devices specified or collects out~ut tooffline devices. Any combination of the three devices may be
specified with the command.
Undefined devices are ignored.
When CP-61 detects the end-of-file condition, the disk
spooling area assigned to the user for the specified device
is closed. Printer and card-punch files are queued for
actual output. Card-reader input files are erased.
If it is desired to collect output of punch or printer files
into one spooled output file per device preceded by only one
header record, the CLOSIO command can be issued to the
PRINTER or PUNCH with OFF specified. All succeeding output
to the OFF device is collected until ON is specified with
CLOSIO for that device. at which time the collected files
are queued for the physical device.

CLOSIO

55

Notes:a.

CLOSIO is not used after CMS I/O commands.

b.
All unit record devices areuser logs out.

closed by CP-67c.
CP-67 interprets any invalid CCW
device to which it is addressed.

as a CLOSIO

when thefor thed.
If READER, PRINTER, or PUNCH is not specified.
three devices are closed as if ON were specified.

alle.
If the 'OFF' option has been specified, the device must
be explicitely turned 'ON' to be reactivated.
Responses:
None.
Examples:a.
CLOSIO PRINTER READER
Spooling areas assigned to the user for the printer and card
reader are closed. The reader area is erased. The printerfile is queued for actual output.
CLOSIO PRINTF,R OFF
All further output to the print~r
end-of-file condition is generated.

b.

is collected

and

no

c.
CLOSIO PRINTER ON
An end-of-file condition for the printer is generated: thus
the spooling areas assigned to the user for the printer areclosed. The printer file is queued for actual output.
Error Messages:
None.

56

CLOSIOCOMBINE

Purpose:The COMBINE command joins two or more disk files into asingle file, moves files between disks, and changes filedesignations.
Format:I COMBINE I nfn nft nfm ofn1 oftl ofm1 ••• ofnN oftN ofmN-~~-~-~----~~----------~-----------~---~-~~~--~~----~- ------

nfn fnt nfm are the filename, filetype, and filemode of thefile to be created.
ofn

oft ofm

are the filename, filetype, and filemode ofexisting file(s} to be included in the new file.

Osage:
The file to be created and each of the included files mustbe specified by filename, filetype, and filemode.
Input
files musthave thesame record
format (fixedorvariable-length). Input files of fixed-length records musthave the same record length. Any number of input files canbe included in the new file, in the order named"
but thecommand must not exceed a single input line.
The output file is created on the specified disk, according
to the mode letter of the new file.
Input files may be on
any disk.
If the new filename, filetype, and filemode are those of an
existing file, the old file will be erased when the new fileis created. The old file may be among the input files.
Notes:a.

Files may not be copied to the system (SY) disk.

h.
As the input files are processed, a temporary work fileis created with the identifiers (TEMP) (FILE) mm, where rom
is the specified mode of the output file. When processing
is completed, this file is given the designation specified
for the output file.
If an error occurs such that input
files are destroyed, records can be retrieved from this work
file.
Responses:
None.
COMBINE

51

Examples:a.
COMBINE FILE DAOl P3 TSTl FILE P5 TST2 FILE P5
The file FILE DAOl P3 is created on the P-disk. It contains
all the records of TST1, followed by the records of TST2.
TSTl and TST2 are not changed.
b.
A

COMBINE JOBS EXEC T5 JOBS EXEC PS
copy of the P-disk fi1e JOBS is made on the T-disk.

c.
COMBINE JOBA FORTRAN P5 JOBA FORTRAN P5 SUBRl FORTRAN P5
The file SUBR1 is appended to a copy of JOBA, and the new
file replaces the ori9inal JOBA.
Error Messages:
E(OOOOl) FILE -filename filetype filemode w NOT FOUND.
The file specified in the message was not found. Filesremain as they were before the command.
E(00002) DISR ERROR WHILE READING.
An I/O error occurred. or there isfor buffers.

insufficient core space

E(00003) DISR ERROR WHILE WRITING.
An I/O error occurred, or the user's allotted disk space isfilled.
E(OOOOS) ERROR IN NAME, TYPE. OR MODE OF OUTPUT FILE.
Correct the designation of the output file.
E(00010) INCORRECT PARAMETER LISTThe command format was incorrect. Files were not changed.
EC00011) MODE SPECIFIED FOR OUTPUT FILE IS ILLEGAL.
Correct the mode specification of the output file.
If thefirst input file had mode number 3 or 4, it has been erased.
E(00012) ATTEMPT TO WRITE OUTPUT FILE ON READ-ONLY DISK.
Files may not be written on READ-ONLY disks. Change the modeof the output file.
E(00013)

ATTEMPT TO COMBINE FIXED AND VARIABLE LENGTH
FILES.
The input files must all have the same record format.

58

COMBINE

EDIT
Purpose:EDIT has three purposes: (1) to create card image and SCRIPT
files, (2) to make changes to existing files, and (3) toallow context-directed!, online perusal of files.
Format:EDIT

1 <filename>filetype

filename specifies the filename of thecreatedfile to be edited or

filetype specifies the filetype of thecreatedfile to be edited or

Usage:
If a file with the specified filename and filetype does notexist, EDIT assumes that the file is being created, theInput environment is entered, and information typed by theuser thereafter becomes input to that file. If such a filedoes exist, the Edit environment is entered, enabling theuser to issue EDIT requests and to modify the specified
file.
EDIT searches all disks for the file.
If the file is found,its mode is saved and EDIT writes the new file back to that
disk. If the file is not found, the newly created file isput on the P disk.

EDIT

59

OPERATION OF THE CONTEXT EDITORThe Editor is a program designed to provide facilities forthe creation and modification of card-image and SCRIPT files
from an online terminal. Editing is performed upon amain-storage-resident copy of the file.
This approachprovides for rapid movement both forward and backward
through the file.
It does, however, limit files which may
be edited to those wbi,ch may be wholly contained within theavailable main storage.
It is possible to perform edit
operations upon larger files by using the CEDIT command,(but the movement within the file may be slower, as CEDIT
works with disk files and not a core copy of the file) or byissuing SPLIT for the file. to break it up into smaller
files that can be handled by EDIT.
LINE POINTER
Associated with each file is a pointer which refers to aline in the file considered to be the current line. The
current line is defined as the line that is being created oredited in the file.
Various Edit requests are provided for moving the current
line pointer. This pointer may be moved (1) to a specificrecord (indicated by its record number),(2) to a record
specified by its relative
displacement (in number ofrecords) forward or backward from the current pOSition of
the pointer, or (3) to a record containing a specified
string of ·.:haracters or having a specified label.. The
ability to search for strings allows the user to concern
himself only with the textual context of the desired
movement" relieving him of the concern of keeping track ofrecord numbers and counts of inserted and deleted records.
Many of the record modification requests also reposition thecurrent line pointer (for example, LOCATE, FIND, DELETE., or
CHANGE). When a FIND, LOCATE, or CHANGE request is issued,
if the pointer is positioned at the end of file, the pointeris automatically moved to the TOP of the file before
executing the command.
the environment is changed from Input to Edit, thepointer is positioned to the last line entered from theterminal. When it changes from Edit to Input,the pOinter ispositioned such that the lines being entered follow the lastline edited.

~hen

When the EDIT command begins in the Edit environment, thepointer is positioned before the first line in the file.
During the Edit a null line is automatically placed in frontof the first line of the file to permit the insertion oflines at the beginning of the file. When EDIT begins in the
Edi t environment or when a TOP request" or possibly the UP
request, is issued, the pointer is positioned at this nullline. The null 1ine never gets written onto disk, nor is it
I

60

EDIT

ever printed by the terminal. When the pointer is positioned
at the null line, a PRINT request types a blank line.
If a null line is entered in the Input environroent, the Edit
environment is entered.
If a null line is entered in the
Edit environwent, the confirming message "EDIT:" is typedout.
To enterthe Input environwent fromthe Edit
environment, issue the INPUT (I) request.
SAVING INTERMFDIATE RESULTS
If extensive input and/or changes are beinq maje to a file,
it is a good time-sharing practice to rrake a few additions
and/or changes at a tirre, issue the S~VE request, and thencontinue making additions or changes to the file.
The
process should be repeated until all additions and/orchanges are wade. The final copy of a file being edited, orthe first copy of a newly-created file,
will not bepermanently written onto disk until the FILE or SAVE request
is issued. This procedu~e will pnsure that a miniroum of work
would be redone in the case of a system failure or a grossuser editing error.
A file rr-ust consist of at least one line to be written
permanently on disk.
A file consisting of only a null line
may not be saved.
INPUT ENVIRONMENTThe Input environment is indicated by the message "INPUT:",a carriage return, an~ the unlocking of the keyboard. The
user may then type successive lines of input to the file as
fast as he wishes.
One card image is created from each
input line. To insert a blank line in a file, type at least
one space and hit carriage return. A null line(that is, acarriage return with no prior blanks or characters> enteredfrom Input ~ode does not add a blank line to the file.
Entering the Edit Environwent
The Edit
environmentisenterec froIT the Input environroent by typing a null line(that is, a carriage return with no prior input on theline).
EDIT ENVIRONMENTThe Edit envircnroent is in1icated by the message "EDIT:", acarriage return, ann the unlocking of the keyboard.
The
user roay then type requests to the EDIT command.
Allchanges to the file becowe effective immediately in core,thus allowing recursive mo1ifications to be made to a file.
Changes are written out on disk with the FILE and SAVE
commands; QUIT keeps the original file as it existed before
any changes were wade.
Response Modes. ThereE~itenvironmpnt may

are two response modes in which theoperate:"verify· mode and "brief"
EDIT

61

mode. Verify is the normal mode and causes an automatic
typeout of each line that has been changed or found as theresult of a request.
The brief mode does not respond by
retyping the specified lines, and thus the user must issue a
PRINT request to get the typeout if it is wanted.
The messages "EDIT". " INPUT", " EO F: " • and "TRUNCATED", arealways printed even if the user has selected the brief
message mode.
End of File.
If the end of file is reached by an Edit
request, an "FOF:" rressage is typed, and the pointer ispositioned after the last line of the file.
Entering the Input Environment. The Input environment may beentered by typing thp INPUT request, and a carriage return.
EDIT REQUES'IS
Requests are issued to the EDIT command only when the user
is in the Edit environlTlent. These requests allow theluser
to manipulate and edit files.
If requests are issued during
the Input environwent, they becolTle lines of input to the
file.
Request For~ats. Each request is separated from its operandby one or more spaces unless otherwise specified.
These
spaces can be inserted by using the space bar, the tab key,or the logical tab character, which is discusse~ in a later
section. If the tab key or the logical tab character isused and the request has "line" as the operand, the "line"
is placed in the card iroage as if the tab key or logical tab
character were the first character in "line".
The tab settings discussed are internal or logical tab
settings, not the external or physical tab settings on theterminal. Detailed information concerning record for~ats,
serialization, and special character conventions follows.
String Arguments. Several of the Edit requests require
arguments called string arguments. These arguwents either
are matched against strings in the text, or replace a stringin the text.
A string argument beqins with a jelimiter andcontinues as a sequence of any legal characters until the
initial character(that is. the delimiter)is againencountered. Neither delimiter character is involved in theactual ITatching or replaceroent operation.
Although, by
convention. the slash (/) is used in the following request
descriptions to denote the string delimiter,
any legal
character may be used as the d.elimiter. The delimiter
character is redefined in each new request by its appearance
at the head of a string. If two strings exist in one
request, the same deli~iter character roust be used in eachstring.
Only one delirroiter may be used to separate two
adjacent string arguments in a request (for exarople, as in
the CHANGE request).
62

EDIT

FILE (RECORD) FORMATS
In general, the editor is used for the preparation of
fixed-length (logical) records of 80-character card images
with uppercase characters.
The exceptions are defined
below.
All input to the file being edited is converted fromlowercase to uppercase unless a filetype of MEMO or SCRIPT
has been specified. If a filetype of SCRIPT has been
specified, the file consists of variable-length (logical)
records.
If a filetype of ~EMO is specified, the fileconsists of 80-character card images.
MEMO Files
A filetype of ME~O is use1 to input 80-character card images
containing both uppercase and lowercase letters.
SCRIPT FilesThe EDIT corrmand allows processing of SCRIPT files in a form
compatible with the SCRIPT command.
If the filetype is
SCRIPT, all input lines introduced in the Input environmentand strings introduced in the Edit environment through useof CHANGE, OVERLAY, RETYPE, and INSERT are interpreted
without converting lowercase characters to uppercase. The
character-delete and line-delete symbols have the usual
effect;allothercharactersarestoredwithout
modification, including the tab key.
For
SCRIPT files,
thefile format
isset toV(variable-length records) so that the SCRIPT command can beused to edit or print files created by the EDIT command.
Input lines containing a backspace character are converted
into canonical forw, such that only one backspace follows
any character and only one backspace precedes the character
that overprints the character preceding the backspace.
Record Lengths
The truncation
follows:

colu~ns

INPUT and REPLACE:

for

EDIT

requestsareascolurr,n 71 for SYSIN, ASP360, UPDATE, COpy
column 72 for FORTRAN, COBOL, and PLI
files
column 132 for SCRIPT, LISTING,
PRINTER files
colurrn 80 for other files

FIND, OVERLAY, and BLANK:LOCATE and CHANGE:

used

column 80

end ZONE column
EDIT

63

PRINT:

coluren 12, if serialization is defaulted on, or if
VERIFY column is set after serialization is turnedon: otherwise all 80 columns are printed.

VERIFY:column 72, unless set otherwise.

(See the ZONE cororoand.)Tab Settings
Internal or logical tab settings indicate a column position
that defines the beginning of a field within a record. The
logical tab settings are automatically assumed according to
the filetype specified. These internal tab settings have no
relation to the external tab settings on the terminal. The
assumed internal tab settings are given below, where thefirst of these numbers indicates the column of the record inwhich input is to begin.
Filetype Specified
in EDIT Command
AED
ASP360
AS1130
COBOL
COpy
DATA

EXEC
FLOW
FORTRANLISTINGMEMO
PLIPRINTERREPS
SNOBOLSPLl
SYSIN
UPDATE
default

Assumed Tab settings

1,10,15.20,25,30.35,QO,QS
1.10,16,31,36,Ql,46,51,56,72
1.21,27,32,35.45,50,55,60
1 0 1,10,15,20,25,30
same as ASP360
default
1,5,8,17,27,31
same as ASP360
1~7,10,15,20,25,30

d·.!fault
default
2 0 10.15,20,25,30,35,40,45,50,55,60
d,.!fault
7,,, 17 If 31,36
1 0 10.20,25,30 n 35"40 o 45,50,55,60
1"7,17,30,40,50,60
Sij.me as ASP360
saroe as ASP360
1.5,10,15,20,25,30,35,40,45,50

If the specifieo filetype is not one of those listed, thedefault setting of every five spaces is assumed.
The
assumed tab settings can be redefined by the TAP-SET requestfrom the Edit environwent.
UPDATE files have the same tab settings as
are not sequenced.

SYSIN files but

If a filetype of REPS is EDITed. tab settings are assumed
and a 12-2-9 character is inserted into column 1 if itappears blank.

64

EDIT

COBOL as a filetypeis included to allow COBOL source
decks to be entered under CMS. Note that the COBOL compiler
is not included under CMS.

~.

Serialization of Records
If serialization is assumed for the filetype being edited,or if it is specified by the SERIAL request, an identifieris placed in columns 73-80 of each record. The identifierconsists of a three-character identification followed by afive-digit sequence number.
The identification is takenfrom the first three characters of the filename. or from thefirst parameter of the SERIAL request. The sequence number
begins at 00010 and is incremented by 10.
The line
identifier in columns 73-80 can be changed by issuing theSERIAL request when in the Edit environment.
Serialization is suppressed unless requested by the SERIAL
request. for all filetypes except FORTRAN, COBOL, PLI,
SYSIN, UPDATE, SPL1. COPY, SNOBOL, AED, FLOW, AS1130, and
REPS. If serialization is selected for other filetypes, andneither ZONE 1 71 nor SERIAL id is issued during subsequent
Edits ofthe file,
serialization characters
may beinadvertently shifted into column 72" or columns 73-80 may
be overwritten.
The placing of the identifier in columns 13-80 can beeliminated by specifying no serialization in the SERIAL
request; this causes the truncation of input lines at column
80 and no identifier to be assigned to each record. A filewhose filetype is MEMO, SCRIPT, PRINTER, LISTING, or EXEC
should Dot be serialized.
SPECIAL CHARACTERS
Logical Tab Character
There is a character" called the logical tab character. usedin conjunction with the logical tab settings. This character
causes blanks to be inserted into the record from the column
position at which this character is input, until the firstcolumn position of the next field defined by the logical tab
settings,. The next character from the input line after the
logical tab character is inserted as the first character ofthe next field. This blank insertion is done for all
filetypes except SCRIPT: for blank insertions in SCRIPT
files, refer to the SCRIPT command.
The standard logical tab character is the pound sign (#).
The logical tab character can be redefined by the TABDEF
request in the Edit environment, or by the CHARDEF commandin the CMS environment to allow the pound sign
to be used
as a normal input character. The physical tab key on theterminal can also be used for blank insertions, as it isinterpreted in the same manner as the logical tab character.
The only difference between the tab key and the logical tab
EDIT

65

character is that the tab key moves the typing element to
the next physical tab stop and does not print, while thelogical tab character prints when the character is depressed
and the typing element does not move to the next physicaltab stop.
Note that the logical line-end character is also defined as
the I
and it takes
precedence over the logical tab
character.
Logical Backspace
There is also a character~ called the logical backspace
which is used to backspace one column position in therecord. For n logicalbackspace characters, n column
positions are backspaced in the record, and the n backspaced
positions are overlaid with the n characters which follow
the n logical backspace characters.
If no character isgiven after a logical backspace character, the previously
entered character is not overlaid.
The backspacing is
performed for the column positions o£ a record, and not forthe characters of an input line.
The standard logical backspace character is the ~ character.
It may be redefined by the BACKSPACE request in the Edit
environment or the CBARDEF command in the CMS environment toallow the I sign to be used as a normal input character.
The logical backspace character has the same effect as thephysical backspace key on the terminal for all filetypes
except SCRIPT. With SCRIPT files the physical backspace key
moves the typing element back one position, and generates avalid input character that takes up one column in the record
for each time the key is depressed; the backspace key does
not print when entered on the terminal, nor does it print on
the offline printer" but it backspaces the typing element
one position per character when the record is printed out at
the terminal.
Thus the backspace key allows underscoringand overprinting at " the terminal for SCRIPT files.
The
logical backspace character prints only when entered anddoes not take up a column in the record; it logicallybackspaces one column in the record for allfiletypes,.
l•

The logicaltab character and thelogical backspacecharacter can be used in the following requests in the Edit
environment to insert blanks, and to backspace in the record
respectively:
BLANI<, FIND
INSERT"OVERLAY, and RETYPE.
The logicaltab character and thelogical backspacecharacter can be used as normal input characters in thestring operands of the CHANGE, LOCATE;. and DELETE requests.
1,

Responses:
NEW FILE.
The specified
file does notexist, thus
the Input
environment is entered. All subsequent input lines will be
accepted as input to the file.
66

EDIT

INPUT:
The logical tab settings
The Input environment is entered.
may be either those defined by the user or those assumed
from the filetype. All subsequent input lines will be
accepted as input to the file.
INVALID REQUEST: XXX ••• XXX
The invalid request xxx ••• xxx was issued to EDIT.
DEFAULT TABS SETThe filetype specified is not recognized by the EDIT
command; thus I' the default settings are taken for the
logical tab settings.
EDIT:
The Edit environment is entered. The logical tab settings
may be either those defined by the user or those assumed
from the filetype. An edit request may now be issued.
NO PRIMARY NAME SPECIFIEDThe EDIT command was issued specifying only the fi1etype.
When the file request is issued, a name must be specified.

TRUNCATEDThe input line was too long. If the filetype was FORTRAN,
PLI. SPLi, AED, FLOW t• EXEC. ASM1130. or REPS, then the input
line was truncated after 72 columns. If the filetype was
ASP360;. SYSIN, COpy .• or UPDATE, then it was truncated after
column 71. If the filetype was SCRIPT or LISTING, then it
was truncatedafter 132 columns.
Otherwise,
it wastruncated after column 80. Continue typing more input.
EOF:
The end of the file has been reached during an EDIT request.
The request has
been terminated and thepointer ispositioned after the last line of the file.
Another EDIT
request may be issued.
EDIT WORK FILE "(INPUT1) FILE Pl" EXISTS:
IF GOOD, ALTER IT TO APPROPRIATE FILENAME & FILETYPE:OTHERWISE. ERASE IT.
The EDIT command was issued but the EDrT environment was notentered since the EDIT workfile" (INPUT1) FILE, exists.. The
workfi1e contains whatever file the user had been editing
during a previous EDIT command that had not terminated (thatis t, if CP has crashed while the user was editing a file andthe READY message had not appeared yet. this file may
contain the updated file). If the contents are good~ alter
its identifiers: otherwise, erase it and then reissue EDIT.
Error Message
E(00002)
FILE EMPTY - EXIT TAREN
The user has attempted to save an empty file.
The file is
not written on the disk and the EDIT command is terminated.
EDIT

67

SUMMARY OF EDIT REQUESTS
The requests are listed below by functional group
Environment Selection
INPUT(See also SAVE)(null line)
returns to EDIT mode'(See also FILE)
QUIT
Message Mode Selection
VERIFYBRIEF
Pointer Movement
BOTTOM
FIND
LOCATE
NEXT
TOP
UP

*

Requests marked with * in the rest of thisthe pointer under certain conditions.
,Modification of Recerds
BLANK
CHANGE (*)
DELETE (*)
INSERT (*>OVERLAYREPEAT (*>RETYPE (*)
File Handling
FILE
SAVE
Information Requests
PRINT (*>
Special Characters and Format conventions
BACKSPACESERIALTABDEFTABSET
ZONE
Miscellaneous
REPEAT (*)
X (*)
y (*)

68

EDIT

list may moveBACKSPACE Request
Format:BACKSPACE<character>

BACK

character is any valid character. The default character is ~or the character specified by the CMS CHARDEF
command .•Usage:The BACKSPACE request defines the character to be used as
the logical backspace character. If the request is notissued, the default character is assumed.
The logicalbackspace character causes one column to be backspaced in
the card image for each logical character in the input line.
The backspace character must be redefined to allow
character to be used as a normal input character.

the ~If BACKSPACE is issued without specifying a character, thelogical backspace character is reset to the character
specified by the eMS command CHARDEF, which defaults to the, character.
The backspacecharacter is very usefulfor defining
continuation cards in FORTRAN files. If the first logicaltab setting is set to column 1, the tab key or logical tab
character followed by a logical backspace character may be
used to enter a character in column 6 instead of counting
forward the appropriate number of spaces. An example of theuse of the logical backspace character follows:column1
6
i #~5 'page')
input line:
5'PAGE')
card image in file:
This places w5-PAGE-)· beginning in column 6 of the card
image,• assuming the first logical tab setting is set tocolumn 1.
Note:
If the logical backspace character is redefined in the Edit
environment, the BACKSPACE request must be issued each timea file is edited if it is necessary to use the same
redefined logical backspace character.
If the logicalbackspace character is redefined by the CMS CHARDEF command,
that character is remembered from one Edit command to the
next.

EDIT - BACKSPACE

69

Responses:
The keyboard is unlocked.
Example:BACR $
The character $ is definedas the logical backspacecharacter. The ~ character can now be used as a normal input
character.

70

EDIT - BACRSPACEBLANR Request
Format:
line

BLANK

I
I

B

Rline w

I
1

is any valid input line.

Usage:The BLANK request places blanks in the current line wherever
nonblank characters occur in wline w•
Either the tab key or the logical tab character can be used
to generate blanks in the card image.
The wline w is separated from the request by only one blank.
All other blanks are considered part of wline w•
Responses:
Verify Mode:

The changed line is printed out.
The keyboard is unlocked.

Any mode:
EOF:
The end of file was reached by the request. For BLANK toreach the end of file. the repeat request had to be issued
before BLANR.
Example:BLANK AAAAAA A
line before request:
request:line after request:

column1
6
ABCDFJMNOP
blank aaaaaa a
M OP

Blanks are placed in columns 1-6, and 8
in the file.

EDIT -BLANK,
1of the current line

71

BOTTOM Request
Format:
BOTTOM
EO
Usage:
BOTTOM positions the pointer at the last line of the file.
Example:BO
The pointer is positioned at the bottom of the file.

72

EDIT - BOTTOMBRIEF Request
Format:.-..-~-----.......- .... ------

BRIEF
BR
Usage:The BRIEF request deselects the verify message mode (see the
VERIFY request), and selects the brief message mode in the
Edit environment. In the brief mode, lines that are changedin the file are not typed out automatically_ The requests
that are affected by BRIEF are BLANK, CHANGE, FIND, LOCATE,
NEXT" OVERLAY, and UP _ If INSERT or REPLACE was issued andthe line was truncated, the line is not verified in thebrief mode.
Example:BR
This request selects the brief mode.

EDIT - BRIEF

13

CHANGE Request

Format:n

CHANGE/stringl/string2/ < * < G »
1

C

*

I

,

,

---~~----------~-~~-~-~---~--------~--------/

is any unique delimiting character thatappear in string1 or string2.

does notstring1is the group of characters to be replaced

string2

is the group of characters to replace string1nspecifies the number of lines to bestring1. The default is one line.

Gsignifies that the change is to be applied to every
occurrence of string1 in the lines.

*

is used to mean -to EOF- or -GLOBAL- (G), or both,in a change request as follows:
C /a/b/ * *searched forUsage:The CHANGE request replaces the occurrence of stringl in nlines by string2. If G or * is specified, every occurrenceof string1 1n n or * lines is changed; if G is not
specified, only the first occurrence of string1 is changed.
If neither n nor * is specified, only the current line issearched for string1.
If the occurrence of string1 is not found, the line(s) is(are) not altered. The pointer remains positioned at thelast line searched for the occurrence of string1.
String1 and string2 can be of different lengths.
Each ofthe n or * lines is expanded or compressed accordingly.
If an end-of-file condition immediately preceded the CHANGE,
an automatic TOP request is performed before CHANGE begins.
Notes:a.

The n or * is required if G is to be specified~b. If n is greater than the number of lines to the end of
the filer, every occurrence of string1 from the current line
to the end is changed.
c.
That partoccurrence of74

of each record
string1 is thewhich is scanned for thepart defined by the ZONEEDIT - CHANGE

request, or it defaults to thoseunder -File Record Formats-.

columns definedearlier

Responses:
Verify Mode: The changed lineCs) is (are)the keyboard is unlocked.
Brief Mode:

printed out and

The keyboard is unlocked.

Any mode:
EOF:
The end of file was reached by the request. To position the
pointer at the top of the file~ a TOP request must be
issued. When a CHANGE request is issued after the occurrenCeof an end-of-file condition, a TOP request is automaticallyissued before the request begins.
Examples:a.

C/ALPHA/DELTA/
Column7
ALPHA=ALPHA - BETAc /alpha/delta/
DELTA=ALPHA - BETA

1line before request:
request:line after request:

The first occurrence of ALPHA in
DELTA.

the one line is changed to

The above"
lowercase. example works forfiles where
automatic .~apitalization is standard. For other files, such
as SCRIPT or MEMO, where capitalization is not automatic,
characters must be typed as they were input.
b.

C*ALPHA*DELTA*

1

G
Column1line before request:
request:line after request:
Every occurrence
DELTA.
c.

of ALPHA

1

ALPHA=ALPHA - BETAc *alpha*delta* 1 9
DELTA=DELTA - BETA
in theC .card-image.card-image.

one lineis changed

to

* *

Every occurrence of card-image fromend of file is changed to itself.

the current line to theInverify mode,
every
line
containing thestring-card-image- is printed, although this example does noteffectively change the contents of those lines.

EDIT - CHANGE

75

DELETE Request
Format:1,

1

DELETE
D

I
I
t

n

<

1

/string/

I

> I

1

n

specifies the number of lines todefault is 1,.

be deleted.

/string/

specifies thestringwhich,
terminates the delete operation.

when

The

matched,Usage:
If /string/ is specified. all lines, starting with thecurrent line and up to (but not including) the first line inwhich /stringl is matched, are deleted.
If n is specified, the DELETE request removes n lines fromthe file, starting with the line at which the pointer iscurrently positioned. Upon completion of this request, thepointer is positioned after the last deleted line. If n is0, the current line is deleted.
If n or /string/ is notdeleted.

specified"

only the current line is

Responses:
EOF:
The end of file was reached by the request. To position the
pointer at the top of the file, a TOP request must be
issued.
Examples:a.
D 5
The current line,. plus the next four lines"
are deleted.
The current line pointer is then positioned at the fourthline from the original current line.

D -/*All lines,. starting with the current line and up to (but notincluding) the first record containing a /. sequence" aredeleted.

h.

76

EDIT - DELETE

FILE Request
Format:FILE<filename>filename specifies the name to be used as the filename.
Usage:The FILE request terminates the editing of a file.
Apermanent copy of the file is written onto the disk as itexisted after the last pass through the file.
If the fileis being permanently stored for the first time,
it iswritten onto the disk.
If the file already exists on the
disk., i t is written on the same disk in the same mode as itpreviously existed. This latest copy replaces any existing
copy of the file on the disk, and the file directory is
updated.
If "filename" is specified, it is used as the filename of
the file.
If -filename" is not specified, the filename usedat the time of the invocation of the EDIT command is used.
After the file has been written onto disk, control isreturned to CMS. A file must consist of at least one line tobe permanently written on disk. A file consisting of a nullline only may not be filed.
Note:
If it is desired to move a partially-edited file to disk asa precaution against system or user failure, use the SAVE
request. It does not terminate the EDIT session.
Responses:
The EDIT command is terminated and an entry for the file ismade in the appropriate file directory.
FILE EMPTY - EXIT TARENThe FILE request was issued for an empty file.
No file issaved on the disk and its entry is removed from the file
directory. The error EC00002) is generated, and the EDIT
command terminated.
NO PRIMARY NAME SPECIFIED - RETRY
When EDIT was issued, only the filetype was specified.
Therefore, a filename must be given with the file request.

EDIT - FILE

77

Examples:a.
FILErequest:response:

file
R; xx.xx/xx.xx

hh.mm.ss

This request writes the latest copy of the file onto disk.
b.

FILE RECALC

request:response:

file recalc
R: xx.xx/xx.xx

hh.mm.ss

This request writes the latest copy of theand RECALC is its filename.

18

EDIT - FILE

file onto disk,

FIND Request
Format:
FIND

line

F
~-----------~-----~--

line

is any valid input line. It may contain blanks andthe logical tab character and/or tab--key .•Usage:The FIND request compares the nonblank characters in "line"with each line in the file.
The compare begins on the nextline from where the pointer is currently positioned andcontinues down the file until a match occurs or until the
end-of-file isreached.
If an
end-of-file condition
immediately preceded the FIND request, an automatic TOP
request is performed before FIND begins. If "line" is found,the pointer is positioned to the record in which "line" iscontained.
If -lineis not found, thepointer ispositioned after the last line of the file. The compare iscolumn-dependent, as the only columns compared in eachrecord are the ones specified by nonblank characters in"line". For example, if wline w contains A C, the search
will be for an A in column 1 and a C in column 3.
"Line" is separated from the request by only one blank.
other blanks are considered part of "line".

All

FIND can be used to search for a specific line identifier incolumns 73-80. One technique is to issue FIND, followed by
the appropriate number of tabs to position the specified
identifier to column 73.
Responses:

Brief Mode:

The record is typed and the keyboard
is unlocked.
The keyboard is unlocked.

Any MODE:EOF

Verify Mode:

The end-of-file was reached by the request. To position the
pointer at the top of the file;, a TOP request must be
issued. When a FIND. LOCATE, or CHANGE request is issued
after the occurrence of an end-of-file condition, a TOP
request is automatically issued before the request b~gins.

EDIT - FIND

19

Examples:a.

FIND 90

Columnrequest:line found:

1
f 90

1

90

FORMAT (S16)

The FIND request searched for 90 in columns 1 andfirst line found is typed out in the verify mode.
h.

2.

The

FIND $$SUMX
If $ selected as
logical tab char.
Column1
request:line found:

10$$sumx
LOOP
A

16

f

SUMX.X

Assuming that the logical tab settings are set in 1, 10, 16,
the request searches for SUMX in columns 16-19. The firstline found is typed out in the verify reode.

80

EDIT - FINDINPUT Request
Format:INPUTI

Usage:
This request causes the Input environment to be entered fromthe Edit environment. All subsequent input lines--including
Edit request--are treated as input to the file. and areplaced after the line at which the pointer is currently
positioned. If the INPUT request is given at the top of thefile~ the lines appear before the first line of the file.
If no lines were entered while in the Input environment andreturn is made to the Edit environment, the pointer ispositioned to theline pointed to before
the Input
environment was entered. The line after the pointer is thesame line before and after the Input environment wasentered.
To insert a blank line w type at least one space and hit
carriage return. If a null line is entered, a return to the
Edit environment occurs.
Responses:
INPUT:The Input environment is entered.

EDIT - INPUT

81

INSERT Request
Format:INSERTline

I

is the exact input line to be inserted into thefile.
It can contain blanks and tabs (logical tab
character and/or tab key).

line

Usage:
This request inserts the "line" into the file without
The line is inserted
entering the Input environment.
following the line at which the pointer is currently
positioned, and the pointer is advanced to point to thisThe line is separated from the request byinserted line.
only one blank: all other blanks are considered part of"line".
The conventions of the Input
the INSERT request.

environroent holdtrue during

A blank line can be inserted in the file by using one orroore spaces for "line". If "line" is omitted from the INSERT
request, it is interpreted as the INPUT request and theInput environment is entered.
Responses:
The keyboard is unlocked. Examples:a.

IbABLEbbbbbSbbbbbSUN,X
request:line after request:

Column1
10
i able
ABLE
S

12
s

16

18
sum,x
SUM,X

The input line AELEbbbbbSbbbbbSUM.X lis inserted in the file.
The letter b is used here to indicate a single space.
b.

I $DO 10 1=1,25
Column1
7
request:i $do 10 i=1,25(assuming $ is the logical tab)line after request:
DO 10 1=1,25

Assuming that the logical tab settings are in 1, 7, 10, and15, this request inserts the FORTRAN statement DO 10 1=1,25
in columns 7-18.

82

EDIT - INSERTc.

INSERT
request:response:

insertINPUT:The Input environment is entered,specified with the INSERT request.

EDIT - INSERT

aswline w was

not

83

LOCATE Request
Format:LOCATEL/string/ I

I/

is any unique delimiting character
contained in the string

stringis any group of characters to be
the filethat isnotsearched for in

Usage:
LOCATE scans the characters of each record (as defined by
the ZONE request) for the string specified between the twodelimiters. The scan begins on the next line from which thepointer is currently positioned and continues until thestring is found or until the end-of-file is reached. If an
end of file condition immediately preceded the LOCATE, anautomatic TOP request is performed before LOCATE begins. If
string is located, the pointer is positioned at the linethat contains it. If string is not located, the pointer ispositioned after the last line of the file.
The request is not column-dependent, because all characters
are scanned, as specified by the ZONE request. The logicaltab character and the logical backspace character can beused as normal input characters in string.
LOCATE can be used to scan
73-80.

for a line identifier in columns

Responses:
Verify Mode:
Brief Mode:

The located line is typed and the
keyboard is unlocked.
The keyboard is unlocked.

~ny Mode:
EOF
The end of file was reached by the request. To position the
pointer at the top of the file, a TOP request must be
issued. When a FIND or LOCATE request is issued after theoccurrence of an end-of-file condition. a TOP request is
automatically issued before the request begins.

84

EDIT - LOCATEExamples:a.

L/FORMAT/
Column1

request:line located:

1

1 /format/
55
FORMAT (-DAILY AUDIT')LOCATE searches all characters of each line for FORMAT.
the verify mode the first line found is typed out.
h.

In

L $61$

Columnrequest:line located:

1
1

5

9

$61$
12316XXX61981654321

LOCATE searches for 61 in all columns of each line.
verify mode the first line found is typed out.

EDIT - LOCATEIn the85

NEXT Request
Format:-------------~---~----

NEXT
N

n

<

n

>

1

is an integer indicating the number of lines by which
the pointer should be advanced. The default is 1.

Usage:
This request advances the pointer in the file by n lines. If
n is 0 or unspecified, a value of 1 is assumed and thepointer is advanced to the next line in the file.
If theend of file is reached before the pointer is advanced nlines, the pointer is positioned after the last line.
Specifying a value of n that is greater than the number oflines to the end of file is one method of reaching thebottom of the file.
Responses:
Verify Mode:Line typed and keyboard unlocked.

Brief Mode:

Keyboard unlocked.

Any Mode:
EOF
The end of file was reached by the request. To pOSition the
pointer at the top of the file, a TOP request must be
issued.
Examples:a.
N 5This request advances the pointer five lines.
b.

N

This request advances the pointer one line.

86

EDIT -NEXT

OVERLAY Request
Format:OVERLAY

o

line

I

1

line is an input line
line.

that replaces

parts ofthe current

Usage:
This request takes the nonblank characters from "line" andplaces them in the corresponding position of the current
line.
Blank charactersin"line"
do notre~lacecorresponding positions in the current line. If there ismore than one space after the request, these spaces are
considered as part of "line".
The logical tab character,the tab key, and the logical backspace character can be usedin specifying "line".
Note. The line typed as a result of this command does notprint directly below the corresponding characters resulting
from commands NEXT, PRINT, etc., as the characters 0 or
OVERLAY precede the line entered.
Thus, the characters
appear in the column which is n+l characters to the right ofthe character being overlaid, where n is the number ofcharacters typed in the request's name.
(See examples
below. )Responses:
Verify Mode:

The changed line is
keyboard is unlocked.

Brief Mode:

The keyboard is unlocked.

typed

out

and

the

Any Mode:
EOF
The end of file was reached by the request. For OVERLAY toreach the end of file, the REPEAT request had to be~issued
before the OVERLAY.
Examples:a.

ObbbbbbbbbINGline before request:
request:line after request:

Column1
9
PROGRAMMERoing
PROGRAMMING

Columns 9-11 in the current line are replaced by thenonblank characters in "line". The letter b is used here toindicate a single space.

EDIT - OVERLAY

87

b.

Column136
ABCDMNOPo 5 33 9
5B33M90P

Ob5b33b9line before request:
request:line after request:

Columns 1,3,4, and 6 in the cu~rent line are replaced by thenonblank characters in the "line". The letter b is usedhere to indicate a single space.
c.

ColumnOb#~c

13
FlO. 5,110)71line before request:
request:line after request:

0#%C
CF10.5,II0)

Assuming that a logical tab setting is set to column 7, thelogical tab character (#) followed by the logical backspacecharacter (~) places the next character from the input line
into column 6. The C overlays the blank in column 6 of thecurrent line. The letter b is used here to indicate asingle space.

88

EDIT - OVERLAYPRINT Request
Format:< n < LlNENO »

PRINT

1

P

L

I
I

n

is an integer specifying thetyped out. The default is 1.

Lsignifies
out.

that thenumber ofline identifierslines toshould be

be

typed

Usage:PRINT types out n lines from the file. starting with thecurrent line. Upon completion of this request, the pointeris positioned at the last line printed unless an end-of-filecondition occurred, in which case the pointer is positioned
after the last line printed. If n is 0 or unspecified, it
is assumed to be 1 and the current line is typed.
If L or LINENO is specified, the line identifier in columns
73-80 is typed out with each line.
If L or LINENO is not
specified, only the nonblank characters in column 1-72 ofeach line are typed.
The n is required if L or LINENO is to be specified.
Responses:
The line(s)unlocked.

is

(are)

printed out

and

the

keyboardis

EOF:
The end of file was reached by the request. To position the
pointer at the top of the file, a TOP request must be
issued.
Example:P 5
request:lines printed:

p 5

30
10

WRITE (6,30)
FORMAT C' HERE I AM')CALL SUBl
WRITE (6,10)
FORMAT C' BACK AGAIN')This request types five lines. The line identifier is notincluded. The pointer is positioned at the last line ~yped.

EDIT - PRINT89QUIT Request
Format:QUIT
Q

Usage:QUIT terminates the EDIT command and returns to theenvironment without causing a file to be written on
disk, or making permanent updates to an existing file.

eMS
the

Respense:
The EDIT command is terminated and the fileout or perroanently updated.

is not written

Example:Q

request:response:q

R: xx.xx/xx.xx

hh.mm.ss

EDIT is terminated and the file is not written on the disk.

90

EDIT - QUITREPEAT Request
Format:REPEATn

I < n > I!
I
I

is an integer specifying the number of times to repeat
the following BLANR or OVERLAY request. The default is

1.
Usage:
This request executes the following BLANK or OVERLAY request
n times. If n is 0 or unspecified. it is assumed to be 1.
If n is greater than the number of lines between the current
line and the end of file. REPEAT is in effect until the endof the file. Thus. the REPEAT request can provide global
BLANK and OVERLAY requests.
Response:
The keyboard is unlocked.
Example:REPEAT 25
The following BLANK or OVERLAY request is executed 25 times.

EDIT - REPEAT91

RETYPE Request
Format:
RETYPER<line>

line is an input line that replaces the current line.
Usage:
This request replaces the current line with "line".
The
logical tab character, the tab
key, and the logicalbackspace character can be used in ·line".
"line" isseparated from the request by only one blank; any otherblanks are considered part of "line".
If no line is
specified,the current line is deleted and the--INPUT
environment is entered.
The pointer is not advanced by this request unless the INPUT
environment is entered.
Responses:
The keyboard is unlocked.
INPUT:
No line was specified, The current line is deleted, and the
INPUT environment is entered with the keyboard unlocked.
Example:Rb#IREG = J + R**2
Colu~ns1
line before request:
request:line after request:

7lq
IRE555 = 1 - K
r #ireg = j + k**2
IREG = J + K**2

The "line" specified with the request replaces the current
line. Assuming that the logical tabs are set for a FORTRAN
filetype. the statement IREG = J + K**2 begins in column 7.

92

EDIT - RETYPESAVE Request
Format:<filename> ,SAVEfilenameis the name to be given to the file, aslatest copy is permanently written on disk.

theUsage:The SAVE request writes the latest copy of the file onto theappropriate disk and returns to the Input environment withthe pointer positioned at the same current line as before
the SAVE was issued.
If the file already exists on the
disk/ it is written onto the same disk in the same mode as
it previously existed.
This latest copy replaces any
existing copy of the file on the disk.
The file directory
is updated.
If "filename- is specified, it is used as the filename of
the file. If wfilename w is not specified. the filename usedat the time of the invocation of the EDIT command is used.
If "filename" is not specified at any time, a message istyped out.
Responses:
INPUT:The latest copy of the file has been saved on
has been entered.
The
Input environment
positioned at the same current line as before
issued.

disk and thepointer isthe SAVE was

FILE EMPTY - EXIT ~AREN
The SAVE request was issued for an empty file.
The file is
not written on disk and the Input environment is entered,.
NO PRIMARY FILE NAME SPECIFIED - RETRY
When EDIT was issued, only a filetype was given. To save thefile, a filename must be specified with SAVE.
Example:SAVE MYrequest:response:

save my
INPUT:SAVE MY was issued to write the latest copy of the file on
disk and to give i t the filename of MY.
The Input
environment of EDIT is then entered. The current line
pointer is repositioned as in the INPUT request. If a nullline is entered, EDIT environment is entered and the pointeris positioned as i t was when the SAVE request was issued.
EDIT - SAVE

93

SERIAL Request
Format:SERIAL
SER
id

id
(NO)

< n

>

10

specifies the three-character identification to be usedin columns 13-75.

(NO) specifies no serialization
placed in columns 13-80.
nor identifier

is

to

be

specifies the increment for the line number in columns
16-80.
This number also becomes the first lin~number. The default value is 10.

Usage:
This request
allows the user
to specify
the threeidentification characters and the increment of line numbers
to be used as the identifier in columns 13-80 of each card
image. If the SERIAL request is not issued, the standard
identifier is used. The standard identifier is formed fromthe first three characters of the filename: the increment
and beginning sequence number is 00010.
If columns 13-80 are to be used for data or if no identifier
is desired, the SERIAL (NO) request should be issued. If a
file is being created, the SERIAL (NO) request should be
issued before any input lines are typed. When the EDIT
command for a new file is issued, the Input environment isentered. Before any lines are typed in, the user should
immediately enter the Edit environment by typing a nullline, issue the SERIAL (NO) request, and then return to the
Input environment by issuing the INPUT request to enter
lines of input. Eighty character input lines can then be
entered.
If a file already exists with no identifiers, the SERIAL(NO) request must be given each time the EDIT command isissued to maintain the data that currently exists in columns
13-80 of the file.
If a file already exists with noidentifiers and the SERIAL (NO) request is not issued, thestandard identifier is placed in columns 13-80.
If a file already exists and the SERIAL request is issued
with an id and/or increment, the new identifier replaces thecontents of columns 13-80: the replacement does not occur
until a FILE or SAVE request is issued. The entire file isthen resequenced with the new identifier.
If a file already exists with identifiers. or if input lines
have been entered which were serialized, the SERIAL (NO)94

EDIT - SERIALrequest has no effect and the identifiers are not changed.
Once serialization has begun. it cannot be nullified.
Note:
For a filetype of ~EMO. SCRIPT, LISTING, or EXEC. thedefault option for serialization is SERIAL (NO).
That is,if serialization is wanted" it must be explicitly stated.
(See ·Serializationof Records· underftFile (Record)
Formats·. )Response:
The keyboard is unlocked.
Examples:a.
SERIAL REP 20
The request causes REP to be placed in columns 13-15 of eachcard image, the first input line to be numbered 00020, andthe line numbers to be incremented by 20.
h.
SERIAL (NO)
If the file is being created, this request allows the user
to create SO-character card images from each input line, as
no identifier is placed in colUl'lns 73-80. If the 'Iile
already exists without identifiers. the data in columns
13-80 is maintained.
If afile already exists withidentifiers, or if input lines have been entered which wereserialized. the SERIAL (NO) request has no effect until thecurrent pointer is positioned at the top of the file, after
which no new serialization takes place.

EDIT - SERIAL

95

TABDEF Request

Format:------~-------~--------------TABDEFTABD

character< character > I
I

is any valid character to be used as the logicaltab character.
The default character is the #or the character specified in the eMS CHARDEF
command.

Usage:TABDEF respecifies the character to be recognized as thelogical tab character. If TABDEF is not issued, the default
character is assumed. Note that the n is also defined as
To use the n as the tab
the logical line-end character.
character, the CMS LINEND command must be issued.

If the # character is to be used as a valid input character,the logical tab character and the line-end character must be
redefined.
IF TABDEF is issued without specifying any
character, thelogical tab character is reset to the # character or thecharacter specified by the CHARDEF command.
If the logical tab character is redefined in EDIT, the
TABDEF request must be issued each tiroe the EDIT command isissued, if the user desires to use the same redefinedlogical tab character. If the logical tab character isredefined by the CMS CHARDEF command, that character isremembered from EDIT to EDIT.
Response:
The keyboard is unlocked.
Examples:a.
TABD $
This frees the # as a valid input character and defines the$ as the logical tab character.

b.
An example of the use of the logical tab character in a
FORTRAN filetype is shown below
Column1
7
input line:#x = a + b
record in file:
X = A + B
If the logical tab setting is set in column
expression X=A+B begins in column 7 of the record.
96

EDIT - TABDEF

7,

the

TABSET Request
Format:TABSETTABS<n1 ••• nN>

n1

is the column
to begin.

in the record at which

the line isn2 ••• nN

are column positions for logical tab settings.
omitted, the default tab settings are used.

If

Usage:
This request enables the user to establish his own internal
or logical tab settings for a record,. The tab settings
determine the number of spaces to be inserted in the line
when either the 10gical tab character or the tab key isused.
The TAB SET request is followed by from one to eleven numbersthat do not exceed the value of 80.
The first number
indicates the column in which the record begins"
and thefollowing ten numbers specify the logical tab settings.
If more than eleven numbers are specified, only the firsteleven are used.. Input lines are truncated to 71 or 12
characters, when tabbing indicates a column position above
71. and when serialization is in effect.
Otherwise input
lines are truncated to 80 characters, even if a number
greater than 80 is specified.
If the first number, specifying the column in which therecord begins, is not equal to 1, all input to the file will
start at the specified column in the record and all previous
columns are set to blanks. The EDIT requests BLANK, FIND,
and OVERLAY consider each record to begin in column 1,
regardless of the first specified tab value.
The EDIT
requests INSERT and RETYPE interpret the beginning column
position and process the specified line in the same manneras input to the Input environment.
The TABSET request overrides
the assumed logical tab
settings, such as for FORTRAN, PLI, and SYSIN filetypes.
The user-defined tab settings apply on1y to the file during
the current EDIT command. If EDIT is issued again for thesame file ,• the assumed logical tab settings are in effectuntil TABSET is reissued.
If TAB SET is issued without specifying any values, thelogical tab settings are reset to the default settings forthe filetype of the file being edited,.
EDIT - TABSET

97

Logical tab settings. which are redefined by the user for afile. must be redefined each time the EDIT command isissued. if the same logical tab settings are desired.
Response:
The keyboard is unlocked.
Examples:a.
TABS 1 1 13 19 25 60
This request sets the logical tab settings in columns 7. 13.
19, 25. and 60. and input starts in column 1.
h.
TABS 2 5 10This request would be used to prevent entry of data intocolumn 1. and to set the tabs at columns 5 and 10.

98

EDIT -TABSET

TOP Request
Format:TOP
T

Usage:~hisrequest repositions the pointer to the top of the file(that is, to the null line in front of the user's first linein the file). An aptomatic TOP is performed by the FIND,LOCATE, and CHANGE requests if an end-of-file file condition
immediately preceded the FIND, LOCATE, or CHANGE request.
Response:
The keyboard is unlocked.
Example:T

The pointer is positioned at the top of the file,.

EDIT - TOP

99

UP Request
Format:

n

UP

< n >

U

1

is an integer indicating the number of lines by which
the pointer should be moved back. The default is 1.

Usage:The UP request repositions the pointer n lines before thecurrent line. If n is 0 or unspecified, a value of 1 isassumed, and the pointer is moved up to the previous line in
the file. If n is greater than the number of lines between
the top of the file and the current line, the request
functions as a TOP request,.
Responses:
Verify mode:

The line at which the pointer is repositioned
is printed, and the keyboard is unlocked.

Brief mode:

The keyboard is unlocked.

Example:U 9This request repositions
current line.

100

the pointer nine lines

EDIT -

UP

before the

VERIFY Request
Format:VERIFY
VER
nn

t

nn

I <
>
I
12

specifies the number of columns· to verify in each card
image. The default is all columns for MEMO and SCRIPT,
12 columns for all others.

Usage:
This request terminates the brief Bode (see the BRIEF
request) fI and selects the verify model' causing the automatic
typeout of lines changed or searched for by other EDIT
requests. If nn is specified, nn columns are verified_ If
nn is not specified,. 12 columns are verified; this is thenormal mode of operation in the Edit environment. If a MEMOorSCRIPT fileis beingedited,all columns
areautomatically verified.
The requests which are affected by VERIFY are BLANK, CHANGE,FIND/. LOCATE, NEXT. OVERLAY f and UP.
Response:
The keyboard is unlocked.
Example:VERIFY 50
The first 50 columns are verified in each card image.

EDIT - VERIFY101

X and Y Request
Format:I
I
Ix<request>

y

n

!

I
,

1

requestis any edit requestnis the number of times theexecuted. Default is 1.

saved request is to be

Usage:X and Y allow the user to save a request for later execution
and temporarily name it X or Y.
(Thus two requests may bein a saved status at one time.) This is done with the X
request form.
The X n form allows the user to direct that the request
currently named X be executed n times:. or until end of file.
If the form X with nQ parameter is used, the commandcurrently named X is executed ~.
Examp1es:a.
Y
CHANGE/ABCDE FG//
The change request is saved as Y, allowing the user todelete the string ABCDE FG each time he types the request,

Y.
b.
Y 3
The saved request
executes 3 times.

102(as in the above.

EDIT - X and Y

saved, CHANGE request)

ZONE Request
Format:
ZONE

I
I

Z

n1

!

n2
truncoln1

specifies the initial column of the zone of each record
which is to be scanned. The default value is column 1.

n2

specifies the terminal column of the zone of eachrecord which is to be scanned. If serialization is ineffect!, the default value is 71 for SYSIN,. ASP360,
COpy I' and UPDATE files and 72 for FORTRAN, PLI, SNOBOL,AED,
FLOW, MAD"
AS1130,and
REPS files.
If
serialization is suppressed, the default value is 132
for all SCRIPT and LISTING files, and 80 for allothers, including MEMO, DATA, and EXEC.

Usaqe:
This request causes subsequent LOCATE and CHANGE requests toapply only to the zone of the records specified by the
integer values for starting and ending columns.
The initial zone column, nl, must be strictly less than the
final zone column, n2" and n2 must be less than or equal to
the truncation column.
If serialization is requested by use of SERIAL and thecurrent zone overlaps columns 73-80, the ending zone column
is res'et to 72.
Notes.
a.
If serialization is in effect for SYSIN, ASP360, COPY,
or UPDATE files, the default value of truncol (n2) is 71,
but the ZONE ending column can be set to column 72 to insert
a continuation character in a record.
b.
In addition to its obvious uses in searching andmodifying fixed-format card files"
the ZONE request has
utility in source program editing for adding comment fields,
adding continuation
characters, and searchingon theserialization field, columns 73-80.
c.
To change the limits for fixed-column requests, such as
FIND., BLANK!, and OVERLAY,. the TABSET request should be used.
For ,.!xample l• to overlay starting in column 52 of each card,
the request TABSET 1 52 should be used.

EDIT -ZONE103

Response:
END ZONE RESET TO 12 FOR SERIALIZATION
If serialization is in effect,
and the ZONE request
specifies a terminal column (n2) of 13 or greater, theterminal column is set to 12.
Example:ZONE 1 12
The initial ZONE column is set to 1 and the terminal ZONE
column is set to 12, independent of whether serialization isin effect.

104

EDIT - ZONEERASE
Purpose:The ERASE command deletes a file or a related group of files
from a user·s read-write disks.
Format:-----------------------------------------_._-/
filename filetype < filemode >ERASE*filename filetype
erased.

**p*

filemode specify the

specifies all filenames,
filemodes.

allfile that isfiletypes

to beand/orall

Usage:
Filename and filetype must be specified in the ERASE
command, either by name or with an asterisk.
If thefileroode is omitted, the P-disk is assumed. If the filemodeis specified with an asterisk, all read-write disks aresearched.
Those parts of the file
identifier not specified byasterisks are used to search the file directories. Entries
for all files matching the specified identifiers are deleted
from the appropriate directory(s), and disk space occupiedby these files is made available for new files.

ERASE deletes read-only files.
Response:
ERASE gives no response except the Ready message or an error
code ..
Examples:a. ERASE DLFAC MODULE P5
The file specified is deleted from theits space on the P-disk is freed.

file directory, andb. ERASE * LISTING
All files with the type LISTING are deleted from the P-disk.
c. ERASE * * *All user files on read-write
directory is cleared.
ERASE

disks aredeleted, and

the

105

Error Messaqes:
E(00001) INVALID PARAMETER-LIST
The filename or type was omitted,
incorrect. Correct the command.

or thefilemodewasuser'sfile

E(00003)
An I/O error occurred.
Processing may not havecompleted.
It may be necessary to initialize theagain. See FORMAT.

been
disk

E(00002) FILE SPECIFIED DOES NOT EXISTThe file specified was not found in
directory.

106

ERASE

the

FILEDEF
Purpose:The FILEDEF command
allows the user tospecify the
Input/Output devices as well as certain file characteristics
which will be used by a program at execution time: FILEDEF
is also used to modify,. delete
and list current filedefinitions. FILEDEF is not currently used by any of thelanguages in CMS.
l•

Format:~---~----------~------------------~~-----~--~~~---~-~

1I DDNAME

IFILEDEF 1< DSRN

I

I

*

device
CLEAR
DUMMY<def1 ••• defN»

DDNAME is the DDNAME of a file in the user's
first letter cannot be numeric or an *.

program. The

DSRN is the data set reference number as referred to in theuser·s program. The DSRN can be a one or two digit
number. A DDNAME is created of the form FTxxF001.
where xx is the DSRN (right justified).

*

this parameter along with CLEAR deletes all assignments
previously made by the FILEDEF command.

DEVICE is one of the following which specifies the device
for input and/or output of the file being defined.
RDR

PCB
PTR
CON
DSK
CRT
TAPx

Card reader
Card punch
Printer
User·s terminal (see note 3 below)
Disk
Cathode ray tube (not yet
implemented)~agnetic tapex is blank or 1-5(see note on TAP below).

CLEAR

deletes
the assignmentsof I/Odevices, etc.
associated with the first parameter as previously
defined by the FlLEDEF command.
An * in the firstparameter erases all assiqnments made by previous
FILEDEF commands.

DUMMY

No actual I/O issets up a dummy I/O device.
accomplished during execution. This can be used forprogram testing or at other times when no I/O iswanted.

defl.••• defN are file characteristics for disk or tape files.
FILEDEF

101

Usage:Note that FILEDEF is not currently
languages.

used by any ofthe eMSThe FILEDEF command allows the user to specify the I/O
devices to be used at program execution time.
It is similar
to the DO (Data Definition) card in OS/360.
Certain filecharacteristics, such as logical record size, block size,
and record format can be specified for disk files, as well
as seven-track tape characteristics for tape files.
If no parameters are specified with the FILEDEF command, alist of all DDNAMES and the devices assigned to them by
previous FILEDEF commands are typed at the console(See
note 1 below). File definitions previously created by
FILEDEF can be deleted~ either individually, or for all filedefinitions. A file previously defined by FILEDEF can haveits definition modified by specifying the same DDNAME or
DSRN with new options.
If RDR, PCB, PTR, CON. DUMMY, or CLEAR has been specified,then def1,.,•• defN cannot be specified. RDR, PCB, and CON
input default to fixed unblocked, logical record length 80,
and blocksize 80.
CON output d'~faults to fixed unblocked,
logical record length 130, and blocksize 130. PTR defaults
to fixed unblocked logical record length 133 and blocksize
133.
If DSR has been specified, then def1 must specify DSNAME,
and def2 must specify DSTYPE. These become the filename andfiletype of the file on disk.
Filemode defaults to P1 at
this time.
The rest of the paraweters (definitions) after DSNAME andDSTYPE are in pairs. These pairs may appear in any order or
may be omitted, in which case the default value is assigned
for the parameters which are not included. These values areused only when they have not been defined during compilation
or assembly.
The pairs of parameters are the following:
RECFM ,!. FB"
file

V, VB, or U specifies the record format for the

The formats are the following:
Fixed unblocked
Fixed blocked
Variable unblocked
Variable blocked
Undefined
LRECL number specifies
108

F
FB

the default value

V

VB
U

the logical record length
FILEDEFin bytes.

The default is 80 bytes.
BLKSIZ number specifies the block size in bytes. The default
is 80 bytes.
If a tape device is beinq specified, then the above threepairs of parameters (RECFM, LRECL and BLKSIZ) may be
specified. Note that DSNAME, DSTYPE, and DSMODE may not be
specified. The following pair of parameters may also be
specified when~seven-track tapes are being used:
MODE number where number is a number from 0 to 15.
The following table shows the number to use for desired
tape characteristics. Note that 1-5 are for 800 BPI, 6-10
are for 556 BPI,and 11-15 are for 200 BPI.
800
BPI

556
BPI

200
BPI

M

1

6

11

0
D

2

7

12

3

8

13

4

9

14

E
N

u

M

B

5

10

15

PARITY
ODD

t
I
I
I

,,
,,
,

ODD
ODD
EVEN
EVEN

1
I

E

R

CONVERTER

I
I

1

,
,,
I

1

I
I
I

ON
OFF
OFF

TRANSLATOR

I
I
I
I
I
I

OFF

,

OFF

I
I

,

OFF
ON
OFF
ON
OFF

I

Notes.
a. File definitions are already set up for the console. The
DDNAMES of these are FT05F001 and FT06F001. These names
appear in the list of files whenever FILEDEF is issued
without parameters.
b.
TAP:, with no number following, defaults to TAPl.
and TAP2 are the only legitimate devices at this time.
through TAPS are provided for future expansion.

c.
Consoleediting anduppercase.

input
blank

is always
filling.

TAPl
TAP3

uppercase translation with
Console output is always

Examples:a.

FILEDEF
list of all DDNAMEs and devices previously defined
FILEDEF is printed at the user·s console.
A

FILEDEF INFILE RDR
is created with a DDNAME of
Device Type of Card Reader.

byb.

A file definition

FILEDEF

INFILE and a

109

c.
FILEDEF OUTFILE PTR
A file definition is created with
device type of PRIN~ER.

a DDNAME of OUTFILE and ad.
FILEDEF 12 PCB
A file definition is created with a DDNAME of FT12FOOl and a
device type of PUNCH.
e.
FlLEDEF TOM CON
A file definition is created with DDNAME of TOM and a device
type of console.
f.
FlLEDEF SYS004 DSR GEORGE DATA RECFM FB BLKSIZ 800
A file description is created with DDNAME of SYS004 and a
device type of disk. The filename of the disk file is
GEORGE and the filetype is DATA.
Record format is fixedblocked. and block size is 800. Logical record length isdefaulted to 80.
g•
FlLEDEF JOANNE TAP MODE 1
A file description is created with a DDNAME of JOANNE anddevice type TAP1 (defaulted). Mode is 800 BPI, ODD PARITY,CONVERTER-ON. TRANSLATOR-OFF.
h.
FILEDEF INFILE CLEAR
This deletes the file definition which has a DDNAME of
INFILE.
This file definition
must already have been
defined.
i •FILEDEF * CLEAR
This deletes all file definitions which have been created by
the user. FT05FOOl and FT06FOOl are not deleted.
Error Messages:
E(00001)
1st PARAMETER INVALID
The first parameter is something other than an *,two-digit number, or a DDNAME.

a one orE(00002)
BAD RTN CODE FROM INVOKED PROGRAM
The FILEDEF command got a bad return code from its call to
SVCFREE or
SVCFRET.
This isa systemproblem notcorrectable by the user. Try the command again.
E(00003)
PARAMETERS ~ISSING AFTER OPERAND xxxxxxxx
A parameter required by the FILEDEF command has been left
out of the option list by the user. Retype the command withthe proper options.
E(0004)
SUPERFLUOUS OR INVALID PARAMETERS AFTER xxxxxxxx
One or more parameters after xxxxxxxx is superfluous orinvalid. Retype the command with the proper option list.
E(OOOOS)LRECL OR BLRSIZ VALUES INVALID
One of the following conditions exists:
110

F1:LEDEF

'Illiilil' tiP

exceeded the maximum allowable size (61,439
This is the maximum positive half-word'II,." I imal).
.iH$~: ••••,.~,t~('t or BLRSIZ

values contained nonnumerics.

xxxxx REQUEST
or CLEAR.
"I ,A" REQUEST is generated when a CLEAR request is,. r ll.~ definition not created by the user. ILLEGAL,'M,I;I",'f Is generated when a
DUMMY request is made for
IftJ which has already been defined by FILEDEF.

11111iI.*il~IiIII~~IIIii!J.IIII!~IIiII.~I!I~I~II!lI~III~iIIiI!U~M~IIII"'I.illi_. 1., t."GAL
,JI/:

I'.",

!III

11!,

•

liN' DUMMY,,'.r:iNAME AND DSTYPE MUST BE SPECIFIED

Ii' :t<i.II.'I"~I'~,:,n' requiredli'i~• •with the"ItC', · t l l ; I : '1INAME NOT
d!jIi' \1\

when DSR is specified.
proper parameters .•Retype the

SPECIFIED AFTER FILEDEF

left out an *1' DDNAME or DSRN as his first"f'type the FILEDEF command with the proper

FILEDEF

111

FINIS
Purpose:Format:
FINIS

filename filetype < fi:a, .,.

*.

'filename is the name of the file to be*means all filenames.

•"'I)'"

filetype is the type of file to be clo2':."" ,.""~.,'"*
means all filetypes.
filemode is the mode of the file to be*means all filemodes P,T" and :,'.

'l1li1 ',',I I'H"'!~""""""

Usage:FINIS closes one or more specified tl:'I"u~.i
Closing a file consists of writing 0 _".'.' '.'111
that file on the disk"
updating't ,:.',, t"~directory, and removing the entry fo ' - : " t . "user's active file table. If the fi1.,''''''''~'''. '1111"'''9'(delete upon reading), the file is er~:. "."'!II ~"hl"be used for the filename,filetype.,.:'1'11,1'"
denote the closing of all opened file f,.'~, t :_""",111 .$,.lIIIIIIIII.II'I••I I I /I: :I I,I ,I,I I,I I !I I ,1I1111.i11111111• • •IIIIIIIIIII'";;I;,IIIIIIIII'"II,IIII.~
filenames, f i I etypes fI and/or f i lemodes.
',~'" ",,,.,!IIII_IIUd,,,,,,,,,, ,!,",~"~!'\.~~I"""!liilil"illlilll.lllili6:,!IUUI"J",,, """I ..,!,I"I"I"I"I!,,£iJIIIM,,il l ,,L,,,,I,i,,,,not given, the first file found with t: .11"" t'~'_lill,":;"'::;,':,(;;:;,I:liillil.1"i'~llli~,~1iia. . . . ._ _type is closed.
The order of sear<"~' "."11,
file (s) is (are) the standard order of.~"'II I'" II"~, ,,,',:''
ii

The specified file must already be'.""closed. If it is not, an error cod.FINIS command.

'II' ,~~' '1' ,~":,,
'I,

";'41

Note.
FINIS should be issued by the user whe r,,"~' •close the files used during the execu t 'i.",~ 1"'~lli,
Files accessed by CMS commands are CIO!I.II' '1,1"", ~... il'.#_ _ _ _ _- - - - - - - - Responses:
None.
Examples:a. FINIS DATAOUT CARDS P5
The file whose identifier is DATAOUT CI\.• '''.:I'i''~l'~1

112

FINIS

Value exceeded the maximum allowable size (61.,439
decimal). This is the maxiroum positive half-wordsize.
LRECL or BLRSIZ values contained nonnumerics.
E(00006)
ILLEGAL xxxxx REQUEST
xxxxx is either DUMMY or CLEAR.
ILLEGAL CLEAR REQUEST is generated when a CLEAR request is
made for a file definition not created by the user. ILLEGALDUMMY REQUEST is generated when a DUMMY request is made for
DDNAME or DSRN which has already been defined by FILEDEF.
E(00007)
DSNAME AND DSTYPE MUST BE SPECIFIED
These items are required when DSR is specified.
FILEDEF command with the proper parameters .•Retype theE(OOOOS)
DDNAME NOT SPECIFIED AFTER FILEDEF
The user has left out an *1' DDNAME or DSRN as his firstparameter.
Retype the FILEDEF command with the properparameters.

FILEDEF

111

FINIS
Purpose:FINIS closes one or more files that are currently open.
Format:
FINIS

filename filetype < filemode > I

*

•

*

I

'filename is the name of the file to be closed.
*means all filenames.
filetype is the type of file to be closed.
*means all filetypes.
filemode is the mode of the file to be closed.
*means all filemodes P,T" and S.
Usage:FINIS closes one or more specified files that are open.
Closing a file consists of writing out the last record ofthat file on the disk"
updating the appropriate file
directory, and removing the entry for that file from theuser's active file table. If the filemode number is 3 or 4(delete upon reading>, the file is erased. An asterisk may
be used for the filename, filetype, and/or filemode to
denote the closing of all opened files with the appropriate
filenames, filetypes u and/or filemodes.
If the filemode is
not given, the first file found with the specified name andtype is closed.
The order of search for the specified
file(s) is (are) the standard order of search.
The specified file must already be open in order to beclosed. If it is not, an error code is returned by the
FINIS command.
Note.
FINIS should be issued by the user when his program does not
close the files used during the execution of that program.
Files accessed by OMS commands are closed automatically.
Responses:
None.
Examples:a. FINIS DATAOUT CARDS P5
The file whose identifier is DATAOUT CARDS PS is closed.

112

FINIS

b. FINIS DATAOUT CARDS
The first file found with a filename filetype of DATAOUTCARDS is closed. The permanent disk. the temporary disk. andthe system disk are searched in that order for the file.

c. FINIS. FILEt •All files that are open
closed.

and have

a filetype of

FILE1 ared. FINIS • * •All files that are open are closed.
Error Messages:
E(OOOOl)The specified filename is invalid.
zeros. The file is not closed.
E(00003)error occurred while reading
command has terminated.

~n

It contains

or writing theleading

disk.

The

E(00004)
The first character of the mode is illegal.
E(00006)
The specified file is not open andclosed. The command has terminated.

FINIS

therefore cannot

be

113

LISTF
Purpose:LISTF has two purposes:(1) to type at the terminal the
and
name,
type,
model'
size,
date-Iast-updated,time-Iast-updated of specified files or (2) to create a fileon the permanent disk containing information similar to that
typed at the terminal.
Format:1 LISTF I <name
I

I

*

<type

<mode

«option1 ••• optionN»»>1

*

*

I

name is the name of the files to be listed.
*denotes all filenames and is the default value.
type is the type of file to be listed.
*denotes all filetypes and is the default value.
mode is the mode of the files to be listed. If omitted, all
read-write disks are searched.
*means all disks.
Note.
An asterisk,(*),
preceded by any
number ofcharacters for name or type searches for the specified
characters as the leading characters for that identifier.
For example, LISTF ABC* FORTRAN prints the identifiers for
all FORTRAN files with filenames beginning ABC.
Options:
EXEC(E) createsa file on the permanent
list of the specified files.

disk containing a

SORT (S) sorts, or groups together, all similar filetypes.
ITEM (I) types the number of logical items instead
number of BOO-byte physical records.
NAME

(N)

TYPE

(TY) causes
filetype.

MODE

(M)

produces a list of filenames only.
thelist tocontain

only filename

andtruncates the typed line after filemode.

REC (R) prints
records.

filename, filetype. filemode, andDATE (D) causes the list to
and date the file was
the default line.
114

of thenumber ofcontain name, type, mode. size,
last written (mm/dd).
This isLISTF

YEAR (Y) causes the date to include the year (mm/dd/yy).
TIME (Tl causes the time that the file was last(hh/mm) to be added to the defaulted line.

updatedUsage:
LISTF either types out the specified files or creates a filecontaining the information. All operands are optional. If
no operand is specified, a complete list of all the files
that exist on the user's read-write disks is typed out. The
list consists of the name, type, mode" number of records,
and date each specified file was last written. The number ofrecords is the number of SOO-byte records occupied by thefile,. The date is typed as month--date (mm/dd). See Figure
6.
listf
FILENAMEFORTCLG

w

UCC1
TRY
LOAD
W

FILETYPE
EXEC
LISrrING
MODULETXTLIB
MAP
TEXT
MODULEFORTRANFORTRANUPDATE
TEST1
SUBS
SUBS
TEXT
R: T=0.05/0.14 15.15.04
Figure 6.

MODE
Pi
Pi
P1
P1
Pi
P1
P1
Pi
P1
Pi

NO.REC
1
2
17
3

11
5
3

10
5
6

DATE
S/29
1/16
9/08
8/30
8/13
1/11
8/30
9/03
9/02
9/02

output from the LISTF command

filename, filetype, and/or filemode other than * isonly the file with that identifier is typed out
along with its size.
If a

specified~

If the filemode is not specified, only the read-write disk
directories are examined by LISTF. If a filemode of * isspecified~ all disks
are used. Therefore, in order to have
LISTF search read-only disks, a filemode must be specified.
If the (EXEC) parameter is specified, a card-image file iscreated on the user's permanent disk and assigned theidentifier CMS EXEC Pl.
If a file with the identifier CMS
EXEC Pl already exists, it is erased, and a new file iscreated. This file contains a card image for each of thespecified files and the format of each card image is asfollows:

LISTF

115

Columns

Contents

2-3
5-6
8-15
17-24
27-28
31-34
36-40
42-48

&1
&2
filenaroe
filetype
fileroodenumber of records
date
time

All other columns are blank. For an example of a CMS EXEC
file, see Figure 7, in which the PRINTF command has beenused to typeout the contents of the EXEC file.
listf • fortran (exec)
R; T=0.20/0.31 15.15.15
printf cms exec
&1 &2 W
FORTRAN&1 &2 SUB2
FORTRAN&1 &2 EXAMPLEFORTRAN&1 &2 DRGBFORTRAN&1 &2 GBBFORTRAN&1 &2 SSNSSFORTRANR; T=O.23/0.34 15.18.42

P1
PI
PI
P1
P1
P1

Figure 1. Creation and printing of a

3

12
5

11
10
1
C~S

8/12
8/111
7/29
8/30
8/30
8/31

EXEC file

The CMS EXEC file is like any other user file.
It can be
printed offline, edited, added to, changed, and so on, but
its main purpose is to be used with the EXEC or $ commands.
Refer to the EXEC writeup for a description of the usage ofa CMS EXEC file.
Responses:
If the (EXEC) option is specified, the file CMS EXEC isgenerated on the user's permanent disk, and no response is
typed at the terminal.
If the (EXEC) option is not given,
files is typed at the terminal.

the listof specified

As can be seen in the description of the options.
only
certain quantities of each specified file can be typed by
LISTF. Each option has a truncating effect on all optionsof lower priority.

Examples:a.
LISTF
The name,. type, mode, size and date of each fileread-write disks are typed. See Figure 6.

116

LISTF

on theb.
LISTF ABC* FORTRAN (N)The name of each file that has a filename beginning with thecharacters ABC, has a filetype of FORTRAN, and exists on theread-write disks is typed.

c.
LISTF FILE * * (T)The name. type, mode o size, date, and time of each file thathas a filename of FILE and exists on any disk is typed.
d.
LISTF (EXEC)
The file with the identifier CMS EXEC P1 is created on thepermanent disk. This file contains the same list of files
that was typed in the first example above, hut each entry in
the list has &1 an~ &2 placed in front of it.
e.
LISTF * FORTRAN (EXEC)
The file with the identifier eMS EXEC P1 is created. This
file contains the same list of files that was typed on theterminal in the second example above, but each entry in thelist has t1 &2 placed in front of it. See Figure 7.
Error Messages:
E(OOOOl)ERROR IN PARAMETER LIST.
An incorrect form of the command was issued.
if all parameters are valid.

Check to see

E(00002)
NO FILE FOUND.
The specified file does not exist on the disk.
E(00003)* Z (CCU) NOT LOGGED IN **LISTF was issued with Z as the specified mode, but there is
no Z-disk logged in. Either the wrong mode was specified,or LOGIN Z should be issued.
E(00003)
NO R/W DISR LOGGED IN
LISTF was issued with no mode specified. The default is all
read-write disks. and none are logged in.

LISTF

117

OFFLINE
Purpose:The OFFLINE command controls the unit record input/output
devices. Input files may be entered through the card reader.
Output files may be printed. with or without automatic
carriage control. or punched.
Format:I OFFLINE I commandII

filename<*,

filetype<filemode>

be readfrom thewhere command is as follows:
READ

specifies areader.

deck isto

PRINT

causes the specified file to be printed on thesystem printer with automatic single spacing.

PRINTCC

causes the specified file to be printed with thefirst character of each record interpreted as acarriage control character.

PRINTUPC

translates to uppercase, andrecords of the named file.

thenprintscard

thePRINTVLR causes the specified, variable-length file produced
by an OS/360 language processor to be printed.
PUNCH

causes the specified file to besystem card punch.

PONCHCC

causes an OFFLINE READ filename filetype control
card to be inserted as the first card before
punching the specified file.

PUNCHDTcauses an OFFLINE READ filename filetyped filemodedata-last-written time--last-written control card
to be inserted as the first card before punching
the specified file.

filename

filetype <filemode> identify
the file to betransferred. If filemode is omitted for a READ, Pl
is assumed.

*

specifies that filename,filetype, and filemodeare found in OFFLINE READ control cards in the
input card stream.
(Valid only when coromand =
READ)

118

OFFLINE

punched onto theUsage:Input
If filename and filetype are specified with the OFFLINE READ
command, only one file is read in. Input records of up to
132 characters are accepted. A file that was transferredwith the XFER E TO userid command should be read in with the
filetype PRINTER. A previously existing file with the same
identifiers is erased.
If filemode is omitted, P1 isassumed.
If the file designations are to be entered in the cardstream. a single asterisk must be specified with the OFFLINEREAD command instead of filename and filetype. The deck
entered through the card reader may contain any number offiles, each immediately preceded by a card containing an
OFFLINE READ control card specifying the filename. filetype,and optionally. filemode. The command must start in thefirst card column. These control cards are typed out at theterminal as they are encountered, and are interpreted by thesystem just as if they had been entered from the terminal.
Any existing file with the same identifiers as thosespecified on one of the OFFLINE READ cards is erased. Eachcommand card ends the file preceding it, and the last fileis ended by the end of the card deck.
If an OFFLINE READ * command is issued. and the first cardof the input stream is not of the form OFFLINE READ filename
filetype, a file identified as •• NAME,.. •• TYPE,.. P1 iscreated containing all cards read in until another OFFLINEREAD control card or an end of file is encountered. This
temporary file may now be altered to the desired filename
and filetype.
When operation is on a virtual machine, user card decks must
be read in by CP before an OFFLINE READ command can beissued. The user need not be logged in at the time thedecks are read in,. Each deck must be entered separately,and each must be preceded by an identification card with
CP67USERID punched in the first ten columns, and the user·s
identification startingin the13th column,
or thecharacters ID punched in columns 1 and 2 and the userid
starting in column 10,.
CP saves the deck until the user
logs in and requests it with an OFFLINE READ command. If
more than one deck has been read by CP, they are processedby successive OFFLINE READ commands in the order in which
they were entered.
Output
For the OFFLINE PRINT,. PRIN'rCC, PRINTUPC. PRINTVLR, PUNCH,PUNCHDT, and PUNCHCC commands, filename and filetype must be
specified. If the filemode field is blank, the P disk isassumed. Asterisks are not permitted in the filename or
filetype fields.
OFFLINE

119

The OFFLINE PRINT command prints the specified file withsingle spacing and CMS page headings containing the file
identifiers and a page number. Up to 55 lines are printed ona page.
If the file being printed has a filetype of
LISTING, it is printed as if PRINTCC were issued.
The OFFLINE PRINTCC command uses the first character of eachline in the file as a carriage control code.
The maximum
line size,
including thecontrol character,is 133characters.
A blank (hex'qO-) in the control position
causes the line to be followed by a single space. A zero(hex -FO-) causes a single space before, and after, theprinted line. A one (hex -Fl') causes a skip to the top of
the next page before the line is printed, and a single space
after the line. Another value in the control byte is
assumed to be a valid channel command code, and is filled
into a CCW. No headings or page numbers are supplied and noautomatic skip is performed at the end of the page.
OFFLINE PRINTUPC performs uppercase translation on all
records of the specified file.
For example, if a file oftype SCRIPT or MEMO is to be printed, and the correct
printer character chain is not available g PRINTUPC prints
the file in uppercase, eliminating all print checks andgarbled characters.
OFFLINE PRINTVLR prints variable-length records produced by
an OS access method. The printable data of the record is
preceded by a four-byte control field which contains thelength of the record. This field is discarded, and therecord printed under the PRINTCC format.
The OFFLINE PUNCH
command accepts records up
tocharacters in length.
Shorter records are padded tocharacters with blanks at the right.

80
80

OFFLINE PUNCHCC inserts as the first card of the specified
file to be punched, an OFFLINE READ ••• control card. The
punched deck can now be read by means of an OFFLINE READ *command.
OFFLINE PUNCHDT inserts a card with the same information as
OFFLINE PUNCHC, but also includes the filemode and date andtime last written.
Notes:a.
Files handled
by the OFFLINE commandmust have
fixed-length records, except for OFFLINE PRINTVLR, whichhandles variable-length records.
b. Only the first card of any input deck is checked for
CP67USERID or ID. CP processes as a single file all cards
following it until a physical end of file is reached.

120

OFFLINEc. Under CP, printer output is preceded by a single line
containing a USERID. PUNCH output is preceded by a card
containing a USERID.
d. OFFLINE READ accepts input records up to 132 charactersin length, such that LISTING files may be XFER·'ed from os to
CMS. The file should be read in with a filetype of FRINTER.
e. If OFFLINE READ was issued, and the file being read inis 132-byte records, CMS types at the finish of the read,RECORD LENGTH = 132 BYTES.

Responses:
a.

OFFLINE READ filename filetype filemodethe command OFFLINE READ * control cards encounteredin the input card stream are typed at the terminal.

~fter

b.
READER EMPTY OR NOT READY.
This response and the Ready message follow
command if no card deck has been entered
USERID.

an OFFLINE READ
for the user'sc.
RiT=xX.XX/xx.xx
xx.xx.xx
The Ready message indicates the command has completed
without error.
It does not mean that physical output hascompleted. The output file is held by CP until other users
free the output device.
"OFFLINE READ.~.w CONTROL CARD IS MISSING.
FOLLOWING ASSUMED:This response and the assumed control card are typed
whenever an OFFLINE READ * command is issued, and whenever
the first card of the input stream is not an OFFLINE READ
filename filetype <filemode> control card.
d.

THE

e.
(NULL FILE)
Attempt to read a file containing no records was made.
f.

SYSTEM I/O ERRORCP ENTERED, REQUEST PLEASE
This roessage indicates that an unrecoverable I/O error has
occurred on a spooled direct-access device. ReIPL CMS, andissue the OFFLINE coromand again.
Examples:a.
OFFLINE READ SEC23 SYSIN
Any previous file with the filename and filetype SEC23 SYSIN
is erased. All cards following the CP67 identification card
are placed in a file on the permanent disk identified as
SEC23 SYSIN Pl ..
b.
OFFLINE READ *Assume the following deck has been entered by the operator:

OFFLINE

121

/

/1

/

/

/d-a-t-a--c-a-r-d~s-----------------------,___ 1____________________________/OFFLINE READ FILE DA02 P5/--1-----------------------------///----------~--------------------~/sourcecards
1--1------------------------------i/OFFLINE READ SORTJ FORTRAN--I~----------------------------~/CP67USERIDJAYBEEI
Any previous files with the identifiers SORTJ FORTRAN or
FILE DA02 are erased. The card records are placed in files
on the permanent disk under the identifications SORTJFORTRAN Pi and FILE DA02 P5. The following response is
typed:OFFLINE READ SORTJ FORTRANOFFLINE READ FILE DA02 P5
c.

OFFLINE PRINT FILE DA02
search is made for FILE DA02, on all three disks,
ifnecessary.
When it is located, it is printed out withsingle spacing and ~S-supplied page headings.
The first
page of the printout contains only the USERID. The second
page starts with the following heading:A

FILE:FILE DA02 P5

CAMBRIDGE MONITOR SYSTEM PAGEOOl

The heading is followed by a blank line and 55 lines of the
file. The heading of the second and subsequent pages is thesame" except for the page number.
Error Messages:
E(OOOOl)INVALID OFFLINE FUNCTION OR PARAMETER LIST
There are three possible causes of this message:a.
The .operation specified with the command wasinvalid r it must be one of these: READ, PRINT, PRINTCC.
PRINTUPC, PRINTVLR. PUNCH, or PUNCHCC.
h. A filename (or * under the special READ mode) was
not specified.
c.
Filetype was specified as an *. which is not
permitted.
EC00002)
FILE NOT FOUND.
The file specified for output does
spelling of the filename and filetype.

notexist.

Check

ECOOOOS)An attempt has been made to read a variable length file. See
122

OFFLINEthe DISK command
length files.

to be

able

to readand punchvariable

E(00006)

PRINT (max=133) or PUNCH (rnax=SO) RECORDEXCEEDS MAXIMUM LENGTH
The record length of an output file is greater than 132
characters for PRINT. or 133 characters for PRINTCC. Thisis longer than a printer line. The OFFLINE PUNCH command
accepts records of 80 characters or less.
E(OOOO?)PRINT or PUNCH ERROR
System hardware failure has occurred.
on the specific unit record device.

Retry

the operation

E(OOOOS)READ or WRITE DISK ERROR
A disk I/O error has occurred.
If reading disk, an illegal
mode may have been specified. an attempt may have been madeto output an empty file. or there may not be enough core
space for the output buffers.
If writing disk, thespecified mode on the READ command roight be illegal, or no
more disk space is available.

OFFLINE123

PRINTF
Purpose:The PRINTF commandat the terminal.

types all, or part, ofa specified file

Format:~--------------~-------~----~---------------filena~e filetype
n1
n2
n3

IPRINTFI

I

<

<

*

I

»

*

filenawe filetype specify the file to be typed.
nl is the line number of the first line to be typed.
n2 is the line number of the last line to be typed.
n3 is the maximum number of characters toline, if the records are to be truncated.

be typedon aUsage:
The filenaIre and filetype must be specified.
If the firstline number and last line number are omitted, or specified
with asterisks, ,the entire file is typed. An asterisk in
the first line or end line fields specifies the beginning or
the end of the file, respectively.
Typed lines are truncated to the specified limit, if any, orto 113 characters for LISTING files, 120 for SCRIPT files,
80 for MEMO fi1es,
or to 72 for all other filetypes.
If alimit is specified, the first line number and last line
number fields must be filled, either explicitly, or withasterisks.
The standard order of search is used to find the file. In
the case of files with duplicate filename and filetype, only
the first file found is typed.
Notes:
a. The first line number and last line number must be lessthan 9999, and may not contain imbedded commas.

h. The first character of each line in a LISTING file is
not typed. This is a printer carriage-control character.
c. The KT coromand overrides
or line length.

any specified last line number

Examples:These are given in Figures 8, 9, and 10~
124

PRINTFprintf go exec
LOAD il
START

R: T=O.27/0.S3

10.40.16

printf go exec

* * soGO 00010
GO 00020

LOAD &1
START

R: T=0.27/0.55
Figure 8.

10.46.32

Two examples of PRINTF commands that type out an entire file

printf syslib maclib 157 171 72&LABEL

MACRO
MADDPLiCOMM=*.&NAME=*.&TYPE=*,&MODE=Pl,&ITNO=O.
&BUFF=*.&SIX ZE=80,&FV=F,&NOIT=100&LABELDS
COM~..AND&LABEL.COMM DC CLS'&COMM'
FILE-NAME&LABEL.NAME DC CLS'&NAME'&LABEL.TYPE DC CLS'iTYPE'
FILE-TYPE&LABEL.MODE DC CL2'&MODE.
FILE-MODE&LABEL.ITNO DC H'&ITNO'ITEM NUMBER&LABEL.BUFF DC A (&BUFF)BUFFER AREA&LABEL.SIZE DC A(&SIZE)
BUFFER SIZE
CL2'&FV'&LABEL.FV DCFIXED/VARIABLE FLAG&LABEL.NOIT DC H'&NOIT'NUMBER OF ITEMS&LABEL.NORD DC F'O'
NUMBER OF BYTES ACTUALLY READ
MEND

R: T=O.SO/0.72
Figure 9.

10.56.18

A PRINTF command that types out a macro definition

PRINTF125

printf fortj listing 33 • 72
SYMBOL
5

LOCATION
38C

SYMBOL
20

FORMAT STATEMENT MAP
LOCATION SYMBOL LOCATION
392
8
398

TOTAL MEMORY REQUIR~ENTS 00057E BYTES

R; T=O.33/0.47

10.59.42

Figure 10. A PRINTF command that types out the bottomof a FORTRAN LISTING file
Error ~essages:
E(OOOOl)

CORRECT FOF~ IS: ·PRINTF' FILENAME
FILETYPE STARTLINE ENDLINE LINE-LIMIT,
WHERE 'STARTLINE', -ENDLINE', AND'LINE-LIMIT- ARE OPTIONAL.
The filename or filetype was omitted, or one of the optional
fields was not valid.

E(00002) DISK ERROR.
An I/O error occurred.
It may be necessary
the disk again (see FOR~AT).

to initialize

E(00003)
FILE NOT FOUND.
No file with the specified filename and filetype exists.

126

PRINTFSCRIPT
Purpose:The SCRIPT command outputs to a printer." file, or terminal afile of variable-length records in a format specified byincluded control words.
Format:SCRIPT

filename(optionl •.•• optionN)1

filename specifies a file with a filetype of SCRIPT.
Options:
CENTER(CE) causes offline output
printer paper.

to becentered on

theFILE (FI) prints the edited and formatted output of SCRIPT
into a file named -.filenaroe", instead of at theterminal or offline printer.
NOWAIT (NO) starts SCRIPT output immediately without waiting
for the first page to be adjusted.
NUMBEROFFLINE

prints in theand line number
printed output.

(NU)

left margin the SCRIPT filename
corresponding to each line of(OF) prints the edited and formatted output of
SCRIPT on the offline printer, instead of at theterminal.

PAGE xxx causes printout to start at page xxx.
SINGLE (SI) terminates printing after one page, usually usedin conjunction with the PAGExxx option.
STOP (ST) causes
SCRIPT.

a pause at the botto« of

TRANSLATE (TR) translates lowercase
printout.

each page during

letters to uppercase in

UNFORMATTED (UN) prints the inputted SCRIPT file along withthe control words: the control words being ignoredwith no formatting of the output.
Usage:
Filename must be specified withfiletype SCRIPT is assumed.
SCRIPTtheSCRIPT command.

The

127

When the SCRIPT command is issued, the specified SCRIPT fileis typed either at the user's terminal, on the offline
printer, or into a file.
Execution is controlled hy format
control words included in the specified SCRIPT file. Whenthe file is located, and typing is ready to hegin, a
response is typed, and execution pauses until a carriage
return is entered at the terminal, unless the NOWAIT,OFFLINE, or FILE option has been specified. This pause
allows the user to position the output paper at the top of apage. If STOP is specified with the command, the pause isrepeated at the bottom of each page, allowing the user tochange paper if noncontinuous forms are being used.
If STOPis used. the paper should be positioned to the first line tobe printed (the heading) rather than to the physical top of
the page. Typing resumes when a carriage return is typed.
The TRANSLATE option is needed if output is to be directed
to an offline printer that is not equipped with theuppercase and lowercase letters (TN-chain). In conjunction
with the UNFORMATTED option, TRANSLATE provides a means ofprinting the original SCRIPT file on a printer that does nothave the TN-chain (this can also be done by the CMS command
OFFLINE PRINTUPC).
The PAGExxx option, in conjunction with the SINGLE option,
provides a means for selectively formatting and printing
portions of a manuscript. The xxx represents a three-digit
page number and must include leading zeros (for example,
page 12 only should be requested by SINGLE PAGE0121. Anothermeans of selectively manipulating a formatted manuscript is
to use the FILE option to generate the entire or relevant
portion of a manuscript into a file and then use the CMS
facilities of EDIT and/or PRINTF to process it.
The FILE option produces an output file in either typewriter
format (backspace characters and carriage return characters
are used) or printer format (printer control codes areused). The default format is typewriter. The printer format
can be specified by the combination of both the FILE and
OFFLINE options. A printer format file may be later printed
by the CMS command OFFLINE PRINTCC.
Each line read from the disk file by SCRIPT is inspected fora first character of f t . f t . which identifies a format control
word.
Format control
words are not typed,
but areinterpreted to specify changes
in the output format.
Control words may be entered in uppercase or lowercase andshould be separated from their operands (if any) by one ormore blanks.
Control words may appear at the beginning of any line in thefile, with changes effective below the points at which theyoccur. No input data should be included on lines containing
control words, since this data could, in some cases, be lostor interpreted as an operand of the control word.
128

SCRIPT

Note.
The TAB key generates an acceptable character in a SCRIPT
file. and is transmitted by SCRIPT. The number of spaces
actually skipped on print output is dependent on the logicaltab setting specified by the .TB command. For indentations,the .IN or .OF control words should be used instead of the
TAB key.
References:For
more detailed
SCRIPT User's Manual.

informationon

SCRIPT,

see

CMS

Response:
LOAD PAPER: HIT RETURN
This response is given whenever the SCRIPT
command isissued without specifying the NOWAIT option.
The carriage
return must be hit in order for SCRIPT
processing tocontinue. The paper should be adjusted first.
Example:An example of SCRIPT input and output is given in Figures 11
and 12, which follow the descriptions of SCRIPT control
words.
Error Messages:
EC00004)
INCORRECT PARAMETER LIST
An invalid parameter has been specified for a SCRIPT
control word, or a required parameter has been omitted. TheSCRIPT command has been terminated.
ECOOOOS)FILE xxxxxxxx NOT FOUND.
No SCRIPT version of filename xxxxxxxx was
SCRIPT command has been terminated.

found.

The£(00012)DISR ERROR WHILE READING
A disk error was incurred by SCRIPT. The SCRIPT commandhas been terminated, and the disk file being printed remains
unchanged.
EC00016)ILLEGAL CONTROL CARD ENCOUNTERED.
An unrecognizable
control word was
encountered while
printing a SCRIPT file.
The SCRIPT command has been
terminated.
For all of the error messages from SCRIPT, the following
message is printed:
ERROR OCCURRED AFTER READING XXXX LINES.
This usually assists in finding the error in the SCRIPT
file.

SCRIPT

129

E(OOOOO)***A TERMINAL ERROR HAS OCCURRED WHILE
PROCESSING ON OR AROUND LINE xxxxxxxx*** , ETC.
This message indicates a system error. The appropriate
personnel should be informed of the circumstances. Usually
this condition can be bypassed by diagnosing the cause of
the error and changing the SCRIPT file.

130

SCRIPTSCRIPT Control Words
SCRIPT control words are interpreted by the SCRIPT command
to govern format control as the file is being printed out.
The SCRIPT control words are listed below.
Control Word
.AP
.BM
.BR
.CE
.CM

.CO
.CP
.DS
.FI
.FO
.HE
.HM

.IM
.IN
.JU
.LL
.NC
.NJ

.OF
.PA
.PL
.PN
.RD
.SP
.SS
.TB
.TM

.UN

Meaning
AppendBottom margin
Break
Centercomment
Concatenate mode
Conditional page
Double space mode
Format (old form)
Format mode
HeadingHeading margin
Imbed
IndentJustification mode
Line length
No concatenate modeNo justification mode
OffsetPage eject
Page length
Page numbering mode
Read from terminal
Space lines
Single space mode
Tab settings
Top margin
UndentSCRIPT131

APPEND Control
Purpose:The APPEND control word allows an additional SCRIPT file tobe appended to the file just printed.
Format:.APfilenamefilename

specifies the name of the SCRIPT file to be
appended to the file which has just been printed.

Usage:
When the .AP control word is encountered, the current fileis closed, and the specified SCRIPT file is printed as acontinuation of the SCRIPT output from the previous file.
Note.
The .AP control word only allows files to be appended to theend of the current file. 1£ it is desired to insert filecontents into the printout of the current file, use the .1M
control word.
Example:.AP ABCThe contents of SCRIPT file ABC are typed immediately
following the last line of the current file which precedes
the ,.AP request.

132

SCRIPT -.AP

BOTTOM MARGIN Control
Purpose:The BOTTOM MARGIN control word specifies the number of lines
to be skipped at the bottom of output pages, overriding thestandard value of three.
Format:.BM

I n-----~~--------

nspecifies the number of lines to be skipped atbottom of output pages. If omitted. 3 is assumed.

theUsage:
This control overrides the standard bottom margin size of
three lines. and need not be included in the file if thatvalue is satisfactory.
It may be included anywhere in thefile, and the most recent value set applies on any page.
Note.
The BOTTOM MARGIN control word also acts as a BREAK.
Example:.BM 10Ten lines are left blank at the bottom of the current page
Cif possible), and on all subsequent pages.

SCRIPT -.BM

133

BREAK Control
Purpose:When CONCATENATE is in effect, BREAR causes the previous
line to be typed without filling in words from the nextline.
Format:.ER
Usage:
BREAK is used to prevent concatenation of lines, such as
paragraph beadings or the last line·of a paragraph.
It
causes the preceding line to be typed as a short line, if it
is shorter than the current line length.
Notes:
a. Many of the other control words have the effect of a
BREAK. No BREAK is necessary when one of these is present.
h. A leading blank or
BREAK.

tab on a line

has the effectof a

Example:Heading:.brFirst line of paragraph • • •This part of a file is printed by SCRIPT as
Heading:First line of the paragraphIf thetyped

BREAK control

Heading:

134

word were notincluded, itFirst line of the paragraph • • •SCRIPT - .BR

would be

CENTER Control.
Purpose:The line following the
between the margins.

CENTER

control wordiscenteredFormat:.ce
Usage:The line to be centered is entered on the line following the
CENTER control word.
It starts at the left margin, andleading or trailing blanks are considered part of its
length.
Notes:a.

The CENTER control acts as a BREAK.

h. If the line to be centered exceeds
length value. it is truncated.

the current

line

Example:.CE
Other Methods
When this line of the file is typed. the characters "Other
Methods· are centered between the margins.

SCRIPT - .CE

135

COMMENT Control
Purpose:The COMMENT control word causes the rewainder of the line tobe ignored, allowing comments to be stored within the SCRIPT
file.
Format:.CMcomments

Usage:
The .eM control word allows comments to be stored in the
SCRIPT file for future reference. These comments can beseen when editing the file, or printing the file under
UNFORMAT mode.
The
commentsmayalso be
used
to
store
uniqueidentifications that can be useful when attempting to locate
a specific region of the file during editing.
Example:.CM
Remember to change the date.
The line above is seen when examining an unformatted listingof the SCRIPT file, and it reminds the user to update thedate used in the text.

136

SCRIPI' - .CM

CONCATENATE Control
Purpose:
CONCATENATE cancels a previous NO CONCATENATE control word,causing output lines to be formed by concatenating input
lines and truncating at the nearest word to the specified
line length.
Format:.CO
Usage:The CONCATENATE control specifies that output lines are to
be formed by shifting words to or from the next input line.
The resulting line is as close to the specified line length
as possible without exceeding it or splitting a word; thisresembles normal typist output or the MT/ST. This is thenormal mode of operation for the SCRIPT command, CONCATENATE
is only included to cancel a previous NO CONCATENATE control
word.
Note:
This control acts as a BREAK.
Example:.CO
output from this point on in the file is formed to approach
the right margin without exceeding it.

SCRIPT -.co131

CONDITIONAL PAGE Control
Purpose:The CONDITIONAL PAGE control word causes a page eject tooccur, if less than the specified number of lines remain on
the current page.
Format:.CPnnspecifies the number of lines that must remain on thecurrent page for additional lines to be printed on it.

Usage:
The .CP control word causes a page eject to occur if n lines
do not remain on the current page.
This request is
especially meaningful (1) before an .SP control word toguarantee that sufficient space remains on the current pagefor the number of spaces requested along with any titles,
and (2) preceding a section heading to eliminate thepossibility of a heading occurring as the last line of a
page.
Note:
If no operand is specified with the .CP request, the request
is ignored.
Example:.CP 10If less than ten lines remain on the current page, an ejectis issued before printout continues. If ten or more lines
remain, printout continues on the current page.

138

SCRIPT - .CP-----------------DOUBLE SPACE Control
Purpose:The DOUBLE SPACE control word causes
between each line of typed output.

a line tobe skipped

Format:.DS
Usage:DOUBLE SPACE may be included anywhere in the
double spaced output.

file to force

Note:
This control word has the effect of a BREAK.
Example:.DS
Blank lines are inserted
point in the file.

between output

SCRI PI' -• OSlines below

this

139

FORMAT Control
Purpose:The FORMAT control word cancels a previous NO FORMAT control
word (or NO CONCATENATE and/or NO JUSTIFY control word),
causing concatenation and right justification of output
lines to resume.
Format:
.FI

or

.FO

Usage:The FORMAT control word is a shorthand way to specify thetwo control words: CONCATENATE and JUSTIFY.
This control
specifies that lines are to be formed by shifting words toor froID the next line (concatenate) and padded with extra
blanks to produce an even right margin (justify).
Since
this is the normal mode of operation for the SCRIPT command,
FORMAT is only included to cancel a previous NO FORMAT
control word.
Notes:a.

This control acts as a BREAK.

b. If a line without any
length, it is truncated.

blanks exceeds thecurrent linec.
The .FI form of the control word is provided forcompatibility with old SCRIPT file and should not be used in
new files.
Example:.FO
Output from this point on in the file isan even right margin on the output page.

140

SCRIPT - .FI/.FO

padded to produce

HEADING Control
Purpose:The HEADING control word specifies a heading
typed at the top of subsequent output pages.

line tobethe topofFormat:
.BE
line

line

specifies the heading tosubsequent pages~

beprinted at

Usage:All of the line following the first blank after the HEADING
control word is printed at the top of pages starting after
the control word is encountered. No heading is typed on thefirst page of an output file. The heading is typed at theleft margin. Its length must be at least ten less than the
output line length, to allow for a page number at the rightmargin. Leading blanks may be used to center the heading.
The heading is typed in the 1ine specified by the heading
margin and top margin control words. Additional.HE control
words may be included at any point in the file to change theheading on subsequent pages.
Note:
If a new heading is to be placed on a page forced with the
PAGE control word. the HEADING control must precede the PAGE
control .•Examples:a.
• HE CAMBRIDGE MONITOR SYSTEM
The characters CAMBRIDGE MONITOR SYSTEM are typed at theleft in the second-last line of the top margin on all pages
started after this point in the file:
PAGE 7CAMBRIDGE MONITOR SYSTEM

b.
.he
CMS
The leading blanks are considered. part of the heading:. sothe characters CMS are centered in the heading line
CMS

PAGE 8SCRIPT -.HE

141

HEADING MARGIN Control
Purpose:The HEADING MARGIN control word specifies the number oflines to be ski~ped between the heading and the first lineof text excluding forced space (TOP MARGIN), overriding thestandard value of 1.
Format:.HMnnspecifies the number
heading line.

of lines tobe skipped

after theUsage:The heading line is placed a specified number of lines above
the top margin. If no HEADING MARGIN control word isincluded in the file. the default value is 1.
The HEADING MARGIN specified mustcurrent TOP MARGIN.

always be lessthan theNote:
This control word acts as a BREAK.
Examples:a.
.HM 3
Three lines are left between the beading line and the firstline of text. If default top margin of 5 is in effect. theheading occurs one line from the top of paper, followed bythree more blank lines (the heading margin), and then the
text.
b.

..HM 1The standard heading margin of 1 is set.

142

SCRIPT - .HM

IMBED Control
Purpose:The IMBED control word is used to insert the contents of a
specified file into the printout of another SCRIPT file.
Format:---~-~---------~---------.IM

filenamefilename specifies thethe printout.

file to be currently formatted into
A filetype of SCRIPT is assumed.

Usage:
The .IM and .AP control words perform similar functions, but.IM allows the contents of a second file to be inserted into
the printout of an existing file" rather than appended tothe end of it_ Imbedding may be us,.!d to insert standard setsof control words at desired spots in a file, as well as formany other purposes.
Example:.IM CBAP4
The contents of the SCRIPT file whose filename is CHAP4 areinserted in the printout of the current SCRIPT file: whenthe end of the CHAP4 file is reached, printout of thecurrent file resumes.

SCRIPI' - .IM

143

INDENT Control
Purpose:The INDENT control word allows the left side
printout to be indented.

of the SCRIPT

Format:.INnnspecifies the number of spaces to be indented.
omitted, indentation reverts to the original margin.

If

Usage:
The .IN control word causes SCRIPT printout to be indented nspaces fromthe current
left margin
setting.
Thisindentation remains in effect for all following lines(including new paragraph and pages), until another .IN
control
word isencountered.
·.IN
O· cancels
theindentation, and printout continues at the original left
margin setting.
Notes:
a.

The .IN request acts as a BREAK.

h.
The .IN request resets the effective left margin,
causing any .OF setting to be cleared. The .OF request may
be used alone, or in conjunction with .IN. When the latteris the case, .IN settings take precedence.
Examples:a. .IN 5
All lines printed after this request are indented fivespaces fromthe current
left margin
setting,.
This
controlwordisindentation continues until another '. IN
encountered.
h.
.IN 0
The effect of any current indentation is canceled.
printout continues at the original left margin setting.

144

SCRIPT - .IN

andJUSTIFY Control
Purpose:The JUS~IFY control word cancels a previous NO JUSTIFY
control word (or part of a NO FORMAT control word), causing
right justification of output lines to resume.
Format:,.JU
Usage:
This control word specifies that lines are to be justified
by padding with extra blanks. If concatenate mode is ineffect,theconcatenation
process
occursbeforejustification. Since this is the normal mode of operation
for the SCRIPT command, JUSTIFY is only included to cancel aprevious NO JUSTIFY control word, or the NO JUSTIFY part ofa NO FORMAT control word.
Notes:a.

This control acts as a BREAK.

h.
If a line
CONCATENATE modeis.

exceeds
the current line length, andis not in effect, the line is printed asc. This control word is seldom
mode, therefore r, FORMAT should be
CONCATENATE mode.

used without CONCATENATE
used to enter JUSTIFY and

Example:.JU
output from this point on in the file is padded to produce
an even right margin on the output page, as long as the
input lines do not exceed the line length.

SCRIPT - .JU

145

LINE LENGTH Control
Purpose:The LINE LENGTH control word specifies a line length that is
to override the standard line length of 60 characters.
Format:.LLnnspecifies output
characters.

line

lengthnotgreaterthan

120

Usage:The LINE LENGTH control sets the length for output lines
until the next LINE LENGTH control word is encountered. If
no LINE LENGTH control is included in a file, the standardline length of 60 characters is used.
In the JUSTIFY/NO CONCATENATE mode,lines shorter than line
length are justified to length by blank padding.
In the CONCATENA~E mode, lines longer than line length are
spilled into the following line; lines shorter get words
from previous, or following lines, to approach line length.
Note:This control acts as a BREAK.
Example:.LL 50
Succeeding lines are no more than 50 characters in length.

146

SCRIPT -.LLNO CONCATENATE Control
Purpose:The NO CONCATENATE control stops words fromfrom the next line.

shifting to or

Format:.NC
Usage:The NO CONCATENATE control word stops words from shifting toandfrom thenext
line.
There isa
one-to-one
correspondence between the words on the input and output
lines. This control word is useful for sections of files
containing tabular information, or other special formats.
Note:This control acts as a BREAK.
Example:.NC
Concatenation is completed for the preceding line or lines,
but following lines are typed without moving words to andfrom lines.

SCRIPT - .NC

147

NO FORMAT Control
purpose:The NO FORMAT control stops the CONCATENATE and JUSTIFY
mode, causing lines to be typed iust as they appear in the
file~

Format:I .NF
Usage:The NO FORMAT control is a shorthand way to specify the twocontrol words:
NO CONCATENATE and NO JUSTIFY. This stops
line justificationand concatenation untila FORMAT,JUSTIFY, or CONCATENATE control word is encountered. This
control is useful for sections of files containing tabular
information or other special formats.
Note:This control acts as a

~REAK.

Example:.NF
Justification and concatenation arecompleted for thepreceding line or lines, but following lines typed exactly
as they appear in the file.

148 ,SCRIPT - .NF

NO JUSTIFY Control
Purpose:The NO JUSTIFY control stops padding lines tojustification of output lines.

cause right

Format:.NJ I
Osage:The NO JUSTIFY control word stops the padding of lines withadditional blanks. rf CONCATENATE mode is in effect, lines
are formed that approach the current line length but are notforced to the exact length.
The resulting lines resemble
the output usually produced by a typist or an MT/ST(Magnetic Tape/selectric Typewriter).
Note:
This control acts as a BREAK.
Example:.NJ
Justification is completed for the preceding line or lines,
but following lines are typed without inserting additional
blanks to pad the line.

SCRIPT -.NJ

149

OFFSET Control
Purpose:The OFFSET control word provides a technique
all but the first line of a section.

for indenting

Format:.OFnnspecifies the number of spaces to be indented after the
next line is printed. If omitted. indentation reverts tothe original margin setting.

Usage:
The .OF control word may be used to indent the left side of
the printout.
Its effect does not take place until after
the next line is printed. and the indentation remains ineffect until an indent or another offset control word isencountered.
The .OF control may be used within a section which is also
indented with the .IN control.
Note that .IN settings takeprecedence over .OF. however. and any .IN request causes aprevious offset to be cleared.
If it is desired to start a new section with the same offset
as the previous section. it is necessary to repeat the .OF n
request.
Notes:a.

This control acts as a BREAR.

h. Two OFFSET control words withoutline constitute an error condition.

an intervening

text

Examples:a.
.OF 10The line immediately following the .OF control word is
printed at the current left margin. All lines thereafter(until the next indent or offset request) are indented ten
spaces from the current margin setting.

h.
.OF
The effect of any previous .OF request is canceled, and all
printout after the next line continues at the current left
margin setting.

150

SCRIPT - .. OFPAGE Control
Purpose:PAGE causes the output form to be advanced to the next page.
Format:.PAnnspecifies the page number of the next page. If n is not.
specified, sequential page numbering is assumed.

Usage:
Whenever a PAGE control word is encountered, the rest of thecurrent page is skipped. The paper is advanced to the next
page. the heading and page number are typed, and output
resumes with the line following the PAGE control word. If
STOP was specified with the SCRIPT command, a carriage
return must be entered when the bottom of the page isreached .•Notes:a.

This control acts as a BREAK.

b. If the heading, line length, or other format parameters
are to be different on the new page, the appropriate control
words must appear before the PAGE control word.
Examples:a. .PAThe rest of the current page
page number are typed in theand output resumes.

is skipped. The heading andtop margin of the next page,b. .PA 5
Regardless of the number of the current page, the rest ofthat page is skipped, the heading and page number 5 aretyped in the top margin of the next page, and output
resumes.

SCRIPT -.PA

151

PAGE LENGTH Control
Purpose:The PAGE LENGTH control word specifies the length of output
pages in lines. The value specified overrides the standard
page length of 66 lines.
Format:.PLnnspecifies the length of output pages in lines.

Usage:The PAGE LENGTH control word allows varying paper sizes tobe used for output. If no PAGE LENGTH control word isincluded in a file, 66 is the default value. This is thecorrect size of standard typewriter· paper for terminals
typing eight lines per inch. Page length may be changed
anywhere in a file, with the change effective on the firstpage started after the control word is encountered.
Note:
This control word acts as a BREAK.
Example:.PL 51Page length is set to 51 lines. This is thefor a terminal typing six lines per inch.

152

SCRIPT - .PL

correct size

PAGE NUMBER Control
Purpose:The PAGE NUMBER control word allows the user to control both
external and internal page numbering of the file being
printed.
Format:

I

I

I

I

I • PN 1

OFF
OFFNO
ON

OFF suppresses external page
page numbering continues.

numbering, althoughinternal

OFFNO suppresses both external and internal page numbering.
ON causes external page numbering to be resumed.
Usage:.PN is used to control the page-numbering feature of thesystem. If the OFF operand is specified, page numbering is
discontinued on the printout, although the page numbers
continue to be incremented internally. The OFFNO operanddiscontinues page nurr'bering on the printout and stops theinternal incrementation of page numbers. When the ON operandis specified, page numbering resumes from the last internal
page number.
Examples:a.
.pn off
No further page numbers will appear on SCRIPT output,
although the internal page count continues to be incremented
for each page printed.
b.

.PN OFFNO
No page numbers will appear on SCRIPT output, and theinternal page count remains at its current setting without
further incrementation.

c.

.PN ON
Page numbering on SCRIPT output resuroes using the current
internal page count; this count is incremented for each page
printed.

SCRIPT -.PN

153

READ Control
Purpose:The READ Control word allows the user to enter
the terminal during SCRIPT output.

a line from

Format:.RDnnspecifies the number of lines to be read at the terminal.
If omitted, 1 is assumed.

Usage:
When the .RD control word is encountered during SCRIPT
output to the terminal, it acts as a BREAK, spins the typehead several times, and unlocks the keyboard for a line of
input. The line entered is ignored by the program, and noformatting occurs on it. This facility is useful for adding
headings to form letters, etc.
As many .RD·S may be used as wanted; eachseparate line accepted at the terminal.

results in

a

Note:
This control word acts as a BREAK.
Example:.RD
When this control word is encountered during SCRIPT output,
the type head rotates and the keyboard is unlocked to allow
one line to be typed at the terminal.

154

SCRIPT -.RDSPACE Control
Purpose:The SPACE control word generates a specified number of blanklines before the next typed line.
Format:.SPnnspecifies the number of blank lines to be inserted in the
output. If omitted. 1 is assumed.

Usage:The SPACE control word may be used anywhere in the file togenerate blank lines. If page end is reached during a SPACE
operation, remaining blank lines are inserted after theheading on the following page.
If DOUBLE SPACE is ineffect. twice as
many blank lines are
generated as
specified.
Note:
This control acts as a BREAK.
Examples:a. .SP 3
Three blank lines are inserted in the output before the next
typed line.
h. .spA single blank line is inserted in the output.

SCRIPI' - • SP

155

SINGLE SPACE Control
Purpose:The SINGLE SPACE control word cancels a previous DOUBLESPACE control word, and causes output to be singlespaced.
Format:.SS
Usage:
Outputfollowing the
SINGLE SPACE
control wordissinglespaced. Since this is the normal output format, SINGLESPACE is included in a file only to cancel a previous DOUBLESPACE control word.
Note:
This control word acts as a BREAK.
Example:.ss
Singlespacing resumes below this point in the file.

156

SCRIPT - .SS

TAB SETTING Control
Purpose:The TAB SETTING control word specifies the tab stops to be
assumed for the following lines when converting the TAB
character generated by the TAB key into the appropriate
number of spaces.
Format:.TB
neilnCl) n(2) n(3) n(4) neS)I

specifies the column location of the (i)th tab stop:
the sequence must consist of increasing positive
values separated by one or more spaces.

Usage:TAB characters generated by the TAB key entered into thefile during EDIT file creation are expanded by SCRIPT into
one or more blanks to simulate the effect of a logical tab
stop. The TAB SETTING control word specifies the locationsof the logical tab stops, this overrides the default tab
stops of 5, 10, 15, 20, 2S 30. 35, 40, 45, 50, 55" 60, 65,i,10, 75.

A TAB SETTING control word without any tab stops specified,results in reversion to the default tab settings.
This
control word is useful for indenting the beginning of aparagraph (remember a TAB causes a paragraph BREAK), or fortabular information and diagrams.
Notes:a.

This control word acts as a BREAR.

The tab settings must be monotonically increasing,. Tab
settings that are not so ordered result in unpredictablebehavior.

b.

Examples:a. .TB 10 20 30 40
Tab stops are interpreted as columns 10, 20"

and 30.

b.
.TB
Tab stops revert to default values of 5, 10, 15, etc.

SCRIPT - .TB

157

TOP

MARGIN (Purpose:The TOP MAR(be skipped
standard va]
Format:.TMnspecifief
output pc

Usage:The specifj
succeeding (page number
margin. If
file, the dE
always be gl
Note:This control
Example:.TM 3
Three lines
current pagEsecond line

.trn 10.ce
SCRIPT Example
.sp 2
.ds
This example will demonstrate some of the capabilitieof the SCRIPT command. This file was created byissuing:.br
EDIT EXAMPLE SCRIPT.brSince the file did not previously exist, the terminal
was placed directly into the input environment. This
paragraph was double-spaced with the .OS control.
.5S.sp
No BREAK was needed here, since the .SS (SINGLESPACE) control acts as a break. Although this isin FORMAT mode, tabular information can be included:
.sp
SPACE
.sp
.SP
.ss
SINGLE SPACE.S5.ds
DOUBLE SPACE,.DS.sp
The leading blanks caused each line to be handled
separately.
.sp
Use of the LINE LENGTH control allows space
to be left within a page for figures or drawings.
Naturally, i t may take some experimentation forfinding how n;any paragraphs will fit next to a
figure •• 11 30.sp
The new line length must take affectat a paragraph, since it acts as a BREAK. The
switch back to standard line length, usually 60,
also is a BREAK, and must end a paragraph. This
works only in FORMAT mode •• 11 60.nf
By switching out of FORMAT mode
CAPTIONand doing some justificationby eye" fancier effects can be obtained.
This also
takes some practice and experimentation •

• fi
.cp 5
Figure 11.

158

160

Contents of a SCRIPT file

SCRIPT

PARAGRAPHS:.br
If no space follows a paragraph heading., and if theparagraphs are not indented, a BREAK is necessary in
FORMAT mode, to keep the heading line from being justified.
A few leading blanks are the easiest way to force
a BREAK and separate paragraphs. A line with only a blankwill also force a BREAK and a blank line, if the following
line also begins with a blank, as follows:
The CENTER control is handy for small figures
included in the text. A .CE in front of each line of
the figure is necessary" and note that leading or trailingblanks count for figuring the length to be centered:
.sp
.ce
.ce
FORMAT

EXAMPLE

n

.ce
E

.ce
.ce
Figure EX.A
.sp
To offset the caption it would be necessary to leave
trailing or leading blanks, which are counted as partof its length:
.sp
.ce
.ce
Figure EX.A
.sp
The above caption has 14 trailing blanks, which moveit to the left. Leading blanks would move it to the right.

Figure 11 (cont.) Contents of a SCRIPT file ...

SCRIPT

161

SCRIPT Example
This example

will demonstrate somethe SCRIPT command.

of thecapabilities ofThis file was created by issuing:

EDIT EXAMPLE SCRIPT
Since thefile did notplaced directly into thepreviously exist, theinput environment.

terminal was

This paragraphwas'double-spaced with the .DS control.
No BREAK was needed here, since the .S5 (SINGLE- SPACE)
control acts as a break. Although this is in FORMAT mode,
tabular information can be included:

SPACE
SINGLE SPACEDOUBLE SPACE
The leading
separately.

blanks

.SP
.SS
.DS

.sp
.ss
.ds

caused

each

line

to

be

handledUse of the LINE LENGTH control allows space to be left
within a page for figures or drawings. Naturally, it may
take some experimentation for finding how many paragraphs
will fit next to a figure.
The new line length must takeaffect at a paragraph, since
it acts as
a BREAK.
The
switch back to standard line
length, usually 60, also is a
BREAK,
and
must
end
a
paragraph. This works only in
FORMAT mode.
By switching out of FORMAT modeand doing some justificationby eye, fancier effects can be obtained.
takes some practice and experimentation.

Figure 12.

162

SCRIPT output

SCRIPTCAPTION
This also

PARAGRAPHS:
If no space follows a paragraph heading, and if theparagraphs are not indented. a BREAK is necessary in FORMAT
mode, to keep the heading line from being justified.
A few leading blanks are the easiest way to force a
BREAK and separate paragraphs.
A line with only a blankwill also force a BREAK and a blank line, if the following
line also begins with a blank, as follows:
The CENTER control is handy for small figures
included in the text. A .CE in front of each line of the
figure is necessary~ and note that leading or trailingblanks count for figuring the length to be centered:
FORMAT

EXAMPLEnE

Figure EX.A
To offset the caption it would be necessary to leave
trailing or leading blanks, which are counted as part Of its
length:Figure EX.A
The above caption has 14 trailing blanks, which move it to
the left. Leading blanks would move i t to the right.
Figure 12 (cont.) SCRIPT output

SCRIPT163

SPLIT
Purpose:The SPLIT command copies a specified portion of a given fileand appends it to a second file or creates a new file.
Format:labell label2
n1
<
n2 >
eof

I
I
I SPLIT I fnamel ftypel fname2 ftype2
1
I
fnamel ftype1

specifies the
copiedfile fromfname2 ftype2 specifies the name ofis added

which a,,1

portion is

the file to which file1

label1an eight-byte alphameric label with the firstcharacter nonnumeric, specifying the firstrecord to be copiedlabel2an eight-byte alphameric label with the firstcharacter nonnumeric. specifying the item
after the last item to be copiedn1

a decimal number specifying the item number ofthe first item to be copiedn2

a decimal number specifying
items to be copied

the numberofUsage:The SPLIT command enables the user to copy a portion of
filel and to append it to file2. Filel and file2 cannot be
the same file. If file2 does not exist. it is created. The
files may have fixed-length
or variable-length length
records. If file2 exists. and is a fixed-length record file.
file1 must also be a fixed-length record file.
Copying begins at either the first record containing thealphameric string (labell), in the first eight bytes of arecord (label field) ,. or at the specified item number if theparameter consists o~ all numeric characters.

If the last parameter is not provided, copying continues tothe end of file. If the last parameter is specified as analphameric label,.
copying, once
initiated, terminates
immediately before the first item having the alphamericstring, labe12, in the label field of a record. The extent
of copying may alternatively be specified by an integer
count of the number of items to be copied.
164

SPLIT

No copying is done if (1) labels are used for both startingand stopping the copying and these two labels are identical,(2) the initial label or item number cannot be found, or(3) the number of items is specified as zero.
SPLIT searches all disks for the file.
The
placed on the same disk as the original file.

new file

isResponses:
NUMBER OF PARAMETERS
The specified number of parameters given is not five or six.

~RONG

INVALID LIMITOne of the limit
character numeric,nonnumeric,.

fields isand oneEOF REACHED
The end of filel has been
being initiated.

specified with
otherof thereached with or

the first
characterswithout copying

FILE NOT CHANGED
The command has been completed without any writing of files.
FILE MODIFIED
The command has been successfully
one item has been copied.

completed, andat least

Any error encountered in the reading of filel terminates thecommand after printing one of the following responses:
TYPE NOT FOUNDDISK ERRORILLEGAL MODENONSTANDARD FILE
OPEN FOR WRITING
OPEN FILE LIMIT
Any error encountered in the writing of file2 terminates thecommand after printing one of the following responses:
BAD OUTPUT TYPEERROR ON DISKOPEN FOR READ
TOO MANY FILESDISK FULL
READ ONLY
FILE TYPES INCOMPATIBLE.••• FILES NOT CHANGED
Examples:a. SPLIT FILE DATA Fl DATA q5 12
The twelve items beginning with the 45th item are extracted
from the FILE DATA file. If the Fl DATA file eXists, they
are appended to it..
If the Fl DATA file does not exist, i t
is created and they become its contents.

SPLIT

165

b~
SPLIT ABLE SYSIN ABLEl SYSIN BEG 20
The 20 items beginning with the item which has a label fieldcontaining BEG are extracted from the file ABLE SYSIN andappended to the file ABLEl SYSIN if it exists, or become thecontents of the file ABLE1 SYSIN if it doesn't exist andmust be created.

c. SPLIT PROG SYSIN PROGEND SYSIN END
If PROGEND SYSIN does not exist, items beginning with theitem with END in the label until the end of file PROG SYSIN
are used to create a new file called PROGEND SYSIN: if
PROGEND SYSIN does exist. those items are appended to it.
Error Messages:
The SPLIT command diagnoses all errors which occur andprints a response message indicating the nature of theerror. A11 returns from SPLIT are with general register 15
equal 0, indicating no error.

166

SPLIT

STATE

Purpose:The STATE command tests whether a file exists.
Format:
STATE I filename

filetype<filemode>I

Usage:
When STATE is issued for a file which exists, the command
returns with a code of zero. If the file does not exist, anonzero error code is returned.
Error Codes:
E(OOOOl)
File specified does not exist.
E(00004)
First character of filemode illegal.

STATE

167

UPDATE

Purpose:The UPDATE command makes changes in a snecified
according to control cards in a second file.

file

Format:---~------------------~-------------------------------.-------~----~,UPDATEI filenamel <filetypel <filenaroe2 <filetype2»> «options »1

filenamelis the name of the file to be changed.

filetypel

is the type of the fileomitted, SYSIN is assumed.

filename2

is the filename of the file containing the UPDATE
control cards. If omitted, filename1 is assumed.

filetype2

is the filetype of the file containing the UPDATE
control cards. If omitted, UPDATE is assumed.

tobe changed.

If

Options:P

specifies that the file incorporating the changes
is to replace the original file. If omitted, theold file is retained unchanged, and the new filereceives a filename consisting of a period (.l,followed by the first seven characters of theoriginal filename.

SEQ8

specifies that sequencing is to be done
eight characters in columns 73 to 80.

INC

specifies that the sequence numbers in columns 73
to 80 of the UPDATE deck are to be placed in the
new SYSIN deck.

on allControl Cards:
Changes are made in the original file according to the
UPDATE control cards in the UPDATE file.
The format ofthese cards is shown below:

1./ S

segnolincrementlabel I

S

specifies that the new file is to be sequenced incolumns 76-80. If this card is included in the
UPDATE file" it must be the first card.

segnolspecifies the starting sequence number.

168

UPDATEincrement

specifies the increment to besequence number for each item.

added

label

is a three-character labelcolumns 13-15.

beI ./ D segno1

segno2theplacedinI

specifies thatoriginal file,.

D

to

to

cards are to bedeleted from thesegno1is the (original) sequence number
card to be deleted.

segno2is the sequence number of the last card to bedeleted. If omitted, only one card is deleted.

I ./

I

of thefirst

segno1 I

I

specifies that cards are to be inserted in theoriginal file.
The inserted cards must follow
this./ I card immediately in the UPDATE file.
All cards, until the next control card, areinserted.

segnolspecifies the sequence number of thewhich the cards are to be inserted.

I ./

R

item after

segnol segno2----------~-------~------

R

specifies that cards are to be inserted in theoriginal file in place of cards now there.

segnolspecifies the first card to be replaced.

segno2

specifies the last card to be replaced. The cards
to be inserted in place of those deleted(notnecessarily the same number) must follow the ./ R
card immediately in the UPDATE file.

Usage:UPDATE modifies the specified file according to control
cards in a second file. The filetype SYSIN is assumed forthe file to be modified, if no other is specified,.
The
control-card file normally has the same name as the file tobe modified, and has the filetype UPDATE. It is referred toas the UPDATE file, with the understanding that both adifferent filename and filetype may be specified with the
UPDATE command. Note that if different identifiers are
UPDATE169specified, the filetype of the file to be modified must also
be included. The options must always be the last arguments
specified if they are to be included.
UPDATE generates two files during execution: "filename
UPDLOG PS" and "filename INTER PS" where filename is that of
the original file in both cases. The UPDLOG file contains arecord of the control cards in the UPDATE file, items added
to and deleted from the original file, and error messages.
A new UPDLOG file is generated on each execution, replacing
any existing UPDLOG file with the same filename.
The INTER file receives the records of the original file aschanges are made. At the end of execution, the identifiersof the INTER file are changed to one of two formats. If (P)is specified, the original file is erased, and the INTER
file receives its filename and filetype. If (P) is not
specified, the original file remains unchanged on thepermanent disk. new file receives the same filetype andfilemode, and a filename composed of a period (.) plus thefirst seven characters of the original filename.
The control cards of the UPDATE file always refer to theitems of the original file by the sequence numbers existing
before any changes in columns 16-80.
If no sequence numbers
exist, issue a pr~liminary UPDATE command with only the ./ S
control card in the UPDATE file.
If the SEQ8 option is
specified, the sequence numbers referred to are in columns
13 to 80. Sequence numbers will be assigned.
The control
cards must always be identified by a./ in columns 1 and 2,
but any number of blanks may separate the other fields.
Sequence numbers may
be expressed with up to five digits,
unless SEQ8 is specified. Leading zeros are not necessary.
Any sequence numbers in cards to be inserted in the file are
ignored unless INC is specified" in which case this number
is placed in the new SYSIN. If the . / S control card isomitted from the UPDATE file, and INC is not specified,asterisks are placed in columns 13-80 of all cards in the
new file which were added or replaced, to indicate wherechanges were wade.
Changes are made in order in a single pass through the file.
If control cards specify changes that are not in order., anerror is recorded, and no changes are made.
Responses:
INTERMEDIATE FILE EXISTS.
The file "filename INTER PS" already exists for the filename
specified. ERASE or ALTER this file, and issue the UPDATE
command again.
FATAL ERROR 1
A control card was detected in the UPDATE file whose second
field was not the character R, II' D, or S.

170

UPDATEFATAL ERROR 2
The file to be changed is not on-the permanent disk.
READ ERROR or WRITE ERROR
An error occurrerl while readingdisk.

or writing to the permanent

PARAMETER ERROR
No parameters were entered with the command.

filename filetype NOT FOUND
The file identified in the response wasuser's file directory.

not foundin theERRORS ENCOUNTERED. SYSIN REMAINS UNCHANGED.
all of the above error
This response is issued for
conditions. It indicates control is about to return to the
CMS command environment, and that no changes have been madeto the files.

Example:UPDATE RET
Assume that the file RET SYSIN P5 contains these items:
CSECT
BALR
USING
SR
END

RET

RETOOO10RETOOO20
RETOOO30
RETOOO40
RETOOO5012,0*,12
15(,15

Assume that the file RET UPDATE P5 contains
./
./

S
I

100
10

./

R

40

25

RTN

ENTRY RETCODE
L

RE'l'CODE

BR
DS

15,RETCODE
14
F

As the command is executed, the file RET INTER P5 iscreated. As items are placed into it, RTN is placed incolumns 73-75, and sequence numbers, beginning with 00100
and incrementing by 25, are placed in columns 16-80.. On
completion, the file becomes .RET SYSIN P5, and contains

RET

CSECT
ENTRY RETCODE

BALR 12,0
USING *1,12
L
15,RETCODE
BR
14
RE'l'CODE DS·FEND

UPDATE

RTN00100
RTN00125
RTN00150
RTN00175
RTN00200
RTN00225
RTN00250
RTN00275

171

RET UPDLOG P5 is also created, containing the control cards.
and all items added or deleted.
Error Messages:
E(00002)
FATAL ERROR 3
error occurred
while
attempting
to changeAn
identification of the INTER file. Enter the commandthe

ALTER fn1 INTER * fn1 filetype *where fn1 is the filename of the file changed, and filetypeis the desired filetype. If another error occurs" reenterthe UPDATE command.

172

UPDATEEXECUTION CONTROL
Several commands are available to the user for execution
control (that is
the loading and running of programs).
Files (or programs) which are to be loaded and run under CMS
must reside on disk and must be either in relocatable object
code form or in core-image form. A program in relocatableobject code form is one whose address references can be
modified to compensate for the relocation occurring when the
program is loaded into core. A program in core-image form is
one which represents a copy of the contents of core which
would be executable. All of its address references havebeen resolved and it can no longer be relocated.
j,output from the assembler and all compilers supported under
CMS is relocatable object code. Unless an option to thecontrary is specified by the user this output is created asa file on the user's permanent disk and assigned a filetypeof TEXT. All files, whose filetype is TEXT, are assumed toconsist of relocatable object
code and are processed
accordingly. To load such files into core, either the LOAD,
USE., or REUSE commands may be used. The LOAD command reads
the specified file(s) from disk and loads them into core,relocating the programs and establishing the proper linkages
between program segments. Several options may be specified
in the LOAD command r, which allow the user to specify text
libraries to be searched for missing subroutines, to requestthat execution of the loaded program(s) begin, etc. USE
and/or REUSE should be issued only after a LOAD command has
been issued. The purpose of the USE command is to load thespecified TEXT file(s) into core, and to establish linkages
between these programs and previously loaded programs. The
REUSE command performs the same function as the USE command,
but has the additional effect of changing the default entry
point of these programs to that of the first filename
specified in the REUSE command.
i,A core-image copy of any information currently residing incore may be created by issuing the GENMOD command,. This
command creates a file on the user's permanent disk that isa copy of the contents of core between the specified
locations, and assigns a filetype of MODULE to this file.
All files whose filetype is MODULE are assumed to be incore-image form, and are processed accordingly. To loadsuch files into core, the LOADMOD command is used. Since
address references do not have to be resolved, the LOADMOD
process is faster than the LOAD process for a given program.
After files have been loaded into core by the LOAD,. USE,
REUSE, or LOADMOD commands, execution may be begun byissuing the START command. Execution may also be initiatedby specifying the XEQ option with LOAD.
The $ command is used to load and start a specified file,depending on its filetype, as follows:(1) if a filetype of
EXEC is found, the file is assumed to consist of one or more
Execution Control

113

CMS commands, and the EXEC command is called to execute
these commands;(2) if a filetype of MODULE is found, theLOADMOD command is called to load the file into corel' andthen the START command is called to begin execution; or (3)if a TEXT filetype is found, the file is loaded into core by
a LOAD command, and START is called to begin execution.
The function of the GLOBAL command is to specify two typesof libraries: libraries containing TEXT files which are to
be searched by the LOAD, USE., or REUSE commands for missing
subroutines and undefined names; and libraries containing
macro definitions, which are to be searched by the assembler
for resolving undefined macros. If the GLOBAL command isused" it should be issued before the LOAD, USE, REUSE, or
ASSEMBLE commands to which it refers.

114

Execution Control

EXEC
Purpose:EXEC executes one or more CMS commands contained in a
specified file. allowing a sequence of commands to be
executed by issuing a single command.
Format:EXEC

filename <arg1 ••• argN>1

filename specifies the filename of a file containing one ormore CMS command to be executed. The filetype mustbe EXEC.
argI,•• '. argN are the arguments
to replace thevariables in the file wfilename EXEC ft •numeric

Usage:EXEC executes the sequence of commands that are specified in
the file ftfilename EXEC w• This file must be in card-image
form, and must consist of one CMS command per card image inthe same format as the command is entered at the terminal.
The filetype for the specified file must be EXEC.
EXEC
files can be created by the EDIT or LISTF commands, or by auser·s program.
Each CMS command in the EXEC file can have from one tothirty numeric variables. A numeric variable is made up of
an ampersand (&) followed by an integer ranging from one tothirty.
(that is, &1&2 ••• &30).
Before the command is
executed"each variable is temporarily replaced by anargument specified when the EXEC comroand was issued. For
example, each time an &1 appears as a variable in an EXEC
line. t:le first argument specified with the EXEC command
temporarily replaces the &1, the second argument specified
with the EXEC command replaces &2. and so on, to argument Nof the EXEC command.
If the double quotation mark (ft) is used in place of anargument,. the corresponding variable (&N) is ignored in all
the commands
which reference that variable.
If thespecified EXEC file contains more variables than arguments
given with the EXEC command, the higher numbered variables
are assumed to be missing, and are ignored when the commands
are executed.
Arguments can be concatenated to the right side of any wordin an EXEC line.
For example, the EXEC line LISTF ABC&1
FORTRAN&2 would result in LISTF ABCXYZ FORTRAN, if arg1 is
XYZ and arg2 is unspecified. Use of the double quote (W)for arg1 would cause the variable to be ignored leaving
EXEC

175

LISTF ABC FORTRAN. If the single quotation mark (t) is usedin place of an argument, the entire concatenated form isdeleted. For example, in the above EXEC line if arg1 is
specified with a double quote ("), and arg2 is specified
with a single quote (.), the line would be just LISTF ABC.
The EXEC command is completely recursive (that is, an EXEC
file can contain other EXEC commands in its sequence ofcommands). The recursiveness is limited by core size--eachlevel of recursion requiring about 1200 bytes of freestorage for data. This limits the depth of recursion toapproximately 16.
Notes:
a. Errors resulting from issued commands are not fatal anddo not cause the sequence of commands to be terminated.
This behavior may be modified by the EXEC control word
&ERROR (see "Special Features of EXEC" below).
b.

Each EXEC file may contain a maximum of 4095 EXEC lines.

c.
This versionof the EXEC commandis completely
compatible with EXEC files created for use with the previous
version of the EXEC command, except that in this version
only one command is allowed per line.
This compatibility
may be removed in a later version to save space in the CMS
nucleus.
d. If the EXEC command is issued from an EXEC file, EXEC
must be ~pecified explicitly, as the search for commands
does not include the EXEC filetype.
Response:
As each CMS command in the EXEC file is processed,. it istyped at the terminal along with the time"
unless the&TYPEOUT OFF control word has been specified (see "Special
Features of EXEC" below).
Examples:a. In Figure 13, the command EXEC FORTCLG LLHS is issued.
LLHS is a file whose filetype is FORTRAN, and LLHS replaces
the &1 in all CMS commands in the EXEC file·. The file LLHSFORTRAN is compiled, and the file LLHS TEXT is loaded andexecuted. Note that each CMS command is typed before it isexecuted.

116

EXEC

printf fortclg exec
FORTRAN &1 &2
LOAD &1 &2 (XEQ)

Ri T=O.45/1.23 01.24.45
fortclg llhs
01.29.50 FORTRAN LLHS
01.29.55 LOAD LLHS (XEQ)EXECUTION BEGINS.
APRIL 1968 DATA 5.320
Ri T=O.55/1.44 01.30.45

5.600

1.920

Figure 13.
Example of an EXEC
execute a FORTRAN program

file to compile,load, andb. In Figure 14, the FORT EXEC is created by EDIT. The
only command placj~d in the file is FORTRAN &1 (PRINT). The
file CMS EXEC was created earlier with the LISTF command(see LISTF), and contains the sequence of FORTRAN files tobe compiled.
The file CMS EXEC is typed by issuing the
PRINTF command. The EXEC command is issued specifying thefilename CMS and the two arguments EXEC and FORT. Each file
identifier in eMS
EXEC is preceded by
two symbolicarguments,&1 and &2. The ~1 is replaced by the firstargument specified with the EXEC command. which is EXEC" andthe &2 is replaced by the second argument specified, whichis FORT. The sequence of CMS commands generated in core by
EXEC from the file CMS EXEC are then executed, the first ofwhich is
EXEC

FORT

w

FORTRAN

P5001.

This command executes the sequence of commands in the file
FORT EXEC, and temporarily replaces the numeric variable &1
from FORT EXEC with the argument W. The arguments FORTRAN,
PS, and 001 are ignored because there are no variables &2,&3, and &4 for them to replace.
As soon as the sequence ofcommands in FORT EXEC are completed. the next command in thefile CMS EXEC is executed.
This sequence continues until
all commands are executed in the CMS EXEC file.

EXEC

177

edit fort exec
INPUT:
fortran &1 (print)

EDIT:
file
R; T=0.55/1.43 01.30.50
listf * fortran (exec)
R; T=0.40/0.50 01.31.00
printf cms exec
&1
&1
&1
&1

&2 W
&2 SUB2&2 A&2 SUBBFORTRANFORTRANFORTRANFORTRAN

P5
P5
P5

001
001
001
001

P5

R; T=O.55/3.21 01.32.15
ems exec fort
01.32.58 EXEC
FORT
W
01.33.00 FORTRAN
W
01.33.10 EXEC
FORT
SUB2
01.33.12 FORTRAN
SUB2
01.33.15 EXEC
FORT
A
01.33.17 FORTRAN
A
01.33.19 EXEC
SUBB
FORT
01.33.23 FORTRAN
SUBBRi T=1.50/1.80 01.33.27

P5

001

P5

001

FORTRANP5001(PRINT)
FORTRAN(PRINT)

P5

001

FORTRAN(PRINT)
FORTRAN(PRINT)

Figure 14. The file FORT EXEC is created, the file c~s E¥~C
is typed out_ and then an implied EXEC is issued to nest EXECs

178

EXEC

Error Messages:
E(OOOOl) FILE DOES NOT EXISTThe EXEC file does not exist.
The EXEC command has
terminated. Check to see if the filename specified has afiletype of EXEC.
E(00003) FILE HAS WRONG RECORD SIZE
The specified EXEC file does notrecords. The command is terminated.

contain

80-character

E(00006) WAITRD OR RDBUF ERRThis error would result if an EXEC file was erased after the
EXEC command had been successfully begun. For Example, withthe procedure shown below the file ABCD EXEC would be
erased, and the attempt to read the EXEC line containing
PRINTF would result in the error.
The EXEC command is
terminated.
printf abcd exec
ERASE ABCD EXECPRINTF XYZ&2
R=0.02/0.13 03.45.14
exec abcd
ERASE ABCD EXEC~AITRD OR RDBUF ERR
E(00006) T=O.05/0 .• 08 03.46.10

I I I E ( xxxxx ) I"
The error code xxxxx was generated by the CMS command issued
from the EXEC file. If E(-0003) occurs, the issued command
was invalid.
SPECIAL FEATURES OF EXEC
A line of an EXEC file is either a CMS command or an EXEC
control line. EXEC control lines control the sequence ofcommands to be executed, specify what is to be typed on the
console during the execution of the EXEC command, or provide
input to other command programs, or to the EXEC command
itself.
LABELSEXEC lines, containing either a CMS command or an EXEC
control, may be identified with a label,. All EXEC labels
have a dash as the first character. If the first word of an
EXEC line begins with a dash (-) that word is assumed to bea label.. Labels are used to control the sequence of EXEC
lines executed (see "EXEC Control Words", &GOTO and &LOOP).
EXEC WORDS (&WORDS)EXEC lines may

contain words which begin
EXEC

with an ampersand
119

(&). A word beginning with an ampersand may be a numericvariable, a keyword (that is, a symbolic variable), or acontrol word. A numeric variable consists of an ampersand
followed by an integer or an asterisk C*).
A keyword wordconsists of an ampersand followed by a string of not morethan seven characters, at least one of which is not an
integer. Control words have the same form as keywords andare defined under wEXEC Control Words w•
Numeric variables
and keywords are substituted before the EXEC line isinterpreted.
Numeric Variab1es
Numeric variables are substituted for any arguments which
are to be specified when the EXEC command is issued,. The
numeric variable &0 is replaced by the filename of thecurrent EXEC file. The numeric variable &n is ignored whenn is negative or greater thatn 30. or when n is greater than
the number of arguments supplied when the EXEC command. isissued..
The variable &* isinterpreted to mean allarguments specified~ When i t is included in a CMS command,the command is executed once for each argument specified.
For example. the command line ERASE &* * would cause theerasing of all files whose filename is the same as one of
the specified arguments.
The variable &* may also be usedin an &IF or &LooP condition (see WEXEC Control Words W).
Keyword Var~ables
The value substituted for a keyword may be one of two types:
specified in an EXEC line by the user;, or implied if the
keyword is a special keyword,.
EXEC-Set Keywords

A number of keywords have been defined to have special
meaning and have their values set in a special way,. Thesewords and their values are described below.•&LINENUM has the value of theone.

current EXEC line number plus

&INDEX1 ••• &INDEX9 are used as indices and initially have thevalue +1. Indices 1-9 may be reset or incremented
by an EXEC line. These indices may be set to an
integer value in the same way as the value of any
keyword is set. An index may be incremented or
decremented by
specifying the index
and theincrement in an EXEC line. For example:&INDEX5 = 30915 sets &INDEX5 to 30915.
&INDEX1 -50 adds -50 to the value of &INDEX1 .•Indices arerecursion.

180

local

to

EXEC

the

current

levelof

&INDEXO has as its value the return code number in register
15 from the previous CMS command,.
&INDEX has as its value the number ofthe EXEC command was issued,.

arguments given when

&GLOBALO ••• &GLOBAL9 are used
for communication between
levelsof EXEC
recursion andare setandincremented in the same way as &INDEX1 ••• &rNDEX9.
&GLOBAL has as its value the level of recursion.
user-Specified Keywords
The value of athe form

keyword may be specified by an

EXEC line of&KEYWORD = VALUE&ABLE = 12345
which defines the keyword &KEYWORD to haveand &ABLE to have the value 12345,.

the value VALUE

Keywords can be redefined as often as desired.
EXEC Control Words
The EXEC contro1 words described below can be used toprovide a versatile and flexible facility for controllingthe execution of commands and for defining a user-oriented
command environment. EXEC control words appear in EXEC
lines. which can be interspersed with CMS commands.

I &ERROR t
I
I

actionI&CON-rINUE ,where action is any EXEC line without a statement label.
Action is executed immediately upon an error return from asubsequent C~S command.
If action is not given, &CONTINUE(see below) is asswned. An error in execution of action,. if
action is a CMS command. results in an exit from this levelof EXEC with error code of 11.

EXEC

181

I &IF I

conditionactionwhere -condition consists of the three parameters shown below

&*

EO

S$
anything

NE

GT
LT
GE
LE

S*
&$
anything

and where action is any EXEC line without a label.
If thecondition is satisfied!, theaction is executed..
The
comparison specified by the second argument of condition ismade between
the first andthird arguments.
&$ isinterpreted as wany of the symbolic arguments·.
Thus, theEXEC line
SIF&$ EO XYZ &PRINT HI

would cause -HI- to be typed if at least one of thearguments specified when the EXEC command was issued was
XYZ. Similarly, &* is interpreted as Wall of the suppliedarguments w • (See below for a description of &PRINT,.)
A numerical comparison is made only if both the operands are
numeric. For example. the EXEC line
SIF 017 EQ 17 'PRINT HI
would cause the typing of wHIw. Otherwise,
in a condition is a logical comparison.
An &IF can have another &IF
nested to level 3.

as itsthe comparison

action; these

may beI &EXIT I n '&EXIT causes an EXI~ to the next lower level of recursion
with an error code of n.. If n is not given, a normal exit
with a code of 0 results. If n is negative and if EXEC wascalled from the CMS command level, the absolute value of n
is returned.
If this EXEC command was called from aprevious EXEC command, a negative value of n is returned as
the error code in register 15.

182

EXEC

'QUIT I n
I ON

I OFF

I
I
I

'QUIT n is similar to &EXIT n. except that &QUIT n returns
to level O. the CMS command level. regardless of the levelof recursion of EXEC commands.
&QUIT ON sets the return level for a subsequent &QUIT
control to a level of recursion one higher. Thus" if &QUIT
ON is issued twice and if the current level of recursion is5, an &QUIT n would cause a return to level 2 with an error
code of n.
'QUIT OFF resetscommand level.

I &SKIP ~II:hereturn level

to

level

0, theCMS

1n&SKIP causes n lines in the file to be skipped. If n<O, thenext EXEC line to be executed will be n lines before thecurrent line.
If n>O. the next EXEC line to be executed
will be n+l lines after the current line.

I
I
I &GOTO f
I
I

TOP I
label IEXIT I&GOTO controls the point from which execution will continue.
&GOTOTOP causes sequential execution of EXEC lines to becontinued at the beginning of the EXEC file.
&GOTO EXIT is identical to &EXI-r
the current leve.l of EXEC.

0 and causes a return from

&GOTO label searches the EXEC file, starting from thepresent EXEC line to the end of the file" then going to thebeginning of the file. and finally going back to the present
line lo~ation, looking for the first EXEC line beginningwith the specified label. (See label description under·Special Features of EXEC·.)

I &LooP I
I,&LOOP causes

label
nl

conditionn2looping either

to andEXEC,,
including thelabeled183

line,. or through the number
beginning with the next line.

oflines specified

by

nl.

Looping continues either until the condition is satisfied
or for n2 times..
Condition is specified the same way as
wi th the &IF control word and is tested before looping .•Loops may be nested to a depth of 4. The
must be less than 4096.

numbers nl and n2

I &COm'INUE I&CONTINUE as an EXEC line is ignored. It may be useful with'GOTO or &LOOP and is the default action for &ERROR..
&TYPEOUT

I
I
I
I
I

ALL
ON

PACK
NOPACl{TIME
NOTlMEERROR
OFFNOEXEC

I
I
I
I

1

where:
ALL types all eMS command lines and EXEC control lines.
ON types all CMS command lines
EXEC control lines.

but suppresses the typing of

ERROR types only CMS command lines which result in an error;
EXEC control lines are not typed .•OFF suppresses the typing of all EXEC lines.
NOEXEC is the same as OFF and is included for compatibility
with EXEC files created with the previous version of
the EXEC command.
TIME causes time of
typed.

day to precede

NOTIME suppresses the typing of the
CMS command line.

each CMS

command line

time of daywith each

PACK removes excess blanks from typed lines,.
NOPACK suppresses
lines.

184

the removal of

EXEC

excess blanks

from typed

TYPE
ON
OFF

&TIME

&TIME TYPE types the time since the previously typed time.
&TIME ONcommand.

types the

time

1

n

after typing

the typing of the time

&TIME OFF suppresses
command.

I 'SPACE I
I
I

messageeach

CMS

after each CMSIt&SPACE types n carriage returns at the console.

I &PRINT I line I&PRINT prints line on the typewriter console. All keywords,
symbolic arguments, etc., are substituted into the line,•. Any
word or words that exceed eight (8) characters are left
justified and truncated on the right.

I &COMMENT , line I&COMMENT is used to annotate the EXEC file.
during execution.

It is ignored

I &ARGS I<argl ••• argN>&ARGS is used to redefine the numeric variables &1 ..
&n with
the values specified by argl.,•• argN.
&INDEX is redefinedwith. the value of the current number of arguments.
I• •

&READ

&READ causes

I 1 I
I n I
I argsla read to the typewriter console.

If n is specified, the next n EXEC lines are read from theconsole and executed immediately. These lines must beentered as commandsas if they were included in the EXEC
EXEC

185

file,. since they are executed in the same way.
Reading
stops and the next EXEC line is obtained from the EXEC fileeither when n lines have been read, or when &GOTO. &SKIP.
&LOOP. &EXIT, or &QUIT are typed. Reading may be reset byentering &READ.
If ARGS is specified, one line is read from the console.
This line will be scanned and used to redefine the numericvariables. iINDEX is redefined to the number of arguments
read.
This is the only way to read without entering acommand.
Only the first 72 characters on a line are read.
, iSTACR II

I.Ell:Q

line

,
I

LIFO

&STACK stacks line in the input buffer" substituting for
keywords and variables. Subsequent &READ obtains lines whichwere stacked in this way.
&STACK can be used to specify input or EDIT requests to
EDIT, or DEBUG requests to the Debug environment when it isentered on purpose (that is. by a breakpoint or the DEBUG
command). iSTACK with a blank line is executed as a null
line.
are
stackedin
FIFO
specifies
that
the
lines
First-In-First-Out order. LIFO specifies that the lines arestacked in a Last-In-First-Out order.

I &BEGSTACI< I
I

I

~IFO

LIFO

1
I

line 1line 2. ... .

line N&END STACK&BEGSTACK stacks line 1 through line N, literally without
truncation and without substituting for numeric variables or
keywords,.
This sequence may also be used to specify input or EDIT
requests to the EXEC command" where a line of "#file" causes
the Edit environment of EDIT to be entered from the Input
environment and writes the file on disk. THis sequence may
also be used to specify DEBUG requests to the DEBUG
environment when that environment has been entered on
purpose (that is, via a breakpoint or the DEBUG command).

186

EXEC

FIFO and LIFO are as explained under &STACK.

I &SET I action I&SET has been included for compatibility with old EXEC files
that used the control words ERR and TYPEOUT or actions .•&SET may later be removed as an EXEC control word.
Notes on EXEC Control Words
a. All numeric variables,. keywords. EXEC control settings.
and limitations (for example. maximum depth of loop nesting)are local to the current level of EXEC, unless otherwise
noted.
b. Any EXEC control word may be abbreviated by a sufficientnumber of characters to distinguish it from other control
words. The following precedence order is observed: ERROR;.
EXIT. SKIP,. SPACE;, STACK I' SET, TYPEOUT, TIME, other control
words, oth~r keywords. Keywords cannot be abbreviated .•c. An error from a eMS command
the level of EXEC.

does not cause an exit fromd. When EXEC is entered~ the assumed state of the controls
are &ERROR, &CONTINUE,. &TIME OFF, and &TYPEOUT ON TIME PACK.
e. If an EXEC line specifies an invalid CMS command,; anerror code of E(-0003) is returned. The EXEC command is not
terminated.
Errors from EXEC Control Words
E(OOOOl)

File does not exist.•

E(00002)&SKIP or &GOTO error.

E(00003)

File has wrong record size.

E(OOOOIl)

Keyword or argument error.

E(00005)

Exceeded maximum depth of loop nesting.

E(00006)

Wai trd or Rdbuf error .•E(OOOOS)Illegal form of condition.

E(OOOlO)

Error in &GLOBAL or &INDEX usage.

E(00011)

Error occurred
action ..

in attempt

EXEC

to execute&ERROR's

187

PROFILE EXECThe PROFILE EXEC feature allows a user to set up his own
operating environment within CMS.. When eMS is IPL' ed andthe first CMS command is entered,. an automatic search ismade for a file with a filename and filetype of PROFILE
EXEC. If such a file exists, i t is automatically executed
before the first CMS command entered is executed--thereby
saving the user from entering any repetitious commands hemay be entering each time he uses CMS.
PROFILE EXEC is a standard EXEC file as described in thepreceding sections and,. as such.. may contain any valid
EXEC-type statements. Its only difference is in its name,which has a special meaning that causes this automatic
execution.
Examplesa.
A PL/I
user would have to use the GLOBAL T PLILIB
statement each time he was on the system so that the PL/I
library would be used rather than the FORTRAN libraries.
This PROFILE might be created as follows:
edit profile exec
NEW FILE.

INPUT:
global t plilib
EDIT:
file
b.
A user who wanted to redefine his LINEND and BLIP
characters' each time might set up the following PROFILE
EXEC:
edit profile exec
NEW FILE.
INPUT:&typeout off
linend !
blip *
EDIT:file
Note. This automatic execution may be avoided by issuing
LOGIN NOPROFas the very first CMS command (see LOGIN under
wControl Commands·).

188

EXEC

GENMOD
Purpose:The GENMOD commandcore-image files.

is usedtogenerate

non-relocatable

Format:
GENMODI entry1<entry2>(optionl .••• optionN) 1

entry1 specifies an entry point or a control section nameindicating the starting core location from which thecore-image copy is to be generated. It is also thefilename assigned to the newly generated file.
entry2 specifies an entry point or a control section nameindicating the ending core location from which thecore-image copy is to be generated.
Options:
NOMAP specifies that a load map
the core-image file,.

is not to becontained inP2 specifies that the MODULE file is to have a mode of P2.
Usage:The GENMOD command causes a file to be created which is acopy of the contents of a specified portion of core.. The
LOAD, USE, or REUSE commands will have been issued prior to
the GEMMOD command to load into core the file or files ofwhich a non-relocatable core-image copy is to be created.
The newly created file is placed on the user's permanent
disk and is assigned a filename of the first operand
specified in the GENMOD command, a filetype of MODULE, and afilemode of Pl unless the option P2 was specified, in whichcase the filemode is P2~
This file is in core-image form and is a copy of thecontents of core from the first entry point to the second
entry point specified in the GENMOD command. If only one
entry point is specified, the core-image file consists of acopy of the contents of core from the first entry point
specified to the next available load location.
(The next
available load location is indicated by a pointer which is
updated after each LOAD, LOADMOD, USE, or REUSE command isissued. )Before the core-image file is written, undefined symbols'aredefined to location zero and common is initialized. The
undefined symbols are not retained in the MODULE file as
being unresolved; therefore, once the MODULE is generated,
GENMOD189

those references can not be resolved.
Notes:
a.
Any f.iles existing on the permanent disk with afiletype of MODULE and the same filename as that specified
in the GENMOD command will be erased before the new file iscreated.
h.
To load into core any files which have been created by
the GENMOD command, the LOADMOD command should be used. If
the MODULE file is to be loaded into core and executed andthat MODULE file was generated with the (NOMAP) option,
LOADMOD can not be used; instead, the MODULE's filename mustbe issued as a command.
c.
The MODULE file contains a load reap
unless (NOMAP) is specified.

d.
A MODULE
space.

file without

a loadof the core-image

map requires

less disk

Responses:
None.
Examples:a.
GENMOD FIRS~Assuming that a file which containing an entry point FIRST
has been loaded into core prior to issuing this command, theabove example causes a core-image file to be created on theuser's permanent disk. This file consists of the contents ofcore from entry point FIRST to the next available load
lQcation and a load map. It has an identifier of FIRSTMODULE Pl.
b.
GENMOD ABC DEF (NOMAP)This example creates a file on the user's permanent disk
with a filename of ABC~ a filetype of MODULE, and a filemodeof Pl. The file is a copy of the contents of core from entry
point ABC to entry point DEF. A load map is not included in
the MODULE file.

Error Messages:

E(OOOOl)NO -entryl- ~ODULE
This message indicates that the entry point(s) specified
cannot be located in core. Check to see that these entry
points exist and reis~ue the command.
E(00002)DISK ERROR
An address has been generated outside the bounds
storage assigned to the user. Reissue the command.

190

GENMOnof coreE(00003)
DISK ERROR
A disk malfunction has
occurred.
Reissue the GENMOD
command. If the message persists, there is probably a disk
hardware problem.
E(00004)

DISK ERROR
An attempt to close the file after writing it out has notbeen successful.
Issue FINIS and then reissue the GENMOD
command.

DISK ERROR
An illegal second characterhas been
filemode. Reissue the GENMOD command.•E(OOOOS)

E(00006)
DISK ERROR
The system has attempted to close
it. Reissue the GENMOD command.

encounteredforthe file prior to opening

E(00013)DISK ERRORThe user's disk is full" and the core-image file cannot becreated.
Erase one or more of the unneeded files andreissue the GENMOD command.

GENMOD191

GLOBALpurpose:GLOBAL specifies either macro definition libraries to 'besearched during the ASSEMBLE command. or text libraries tobe searched when loading files containing relocatable object
code.
Format:I
I
1 GLOBALIIIASSEMBLER MACLIBMLOADER TXTLIBTASSEMBLER MACLIB
M

I
I<libnamel ••• 1ibnameN>1
LOADER TXTLIB
T

PRINT

I
I

1

specifies the library files thatare to be searched for macrodefinitions during subsequentassemblies.
specifies the library files thatare to be searched for missing subroutines during subsequent LOAD,.
USEt, or REUSE operations.

libname1 ••• 1ibnameN specifies the library files whose
filetype is either ~ACLIB orTXTLIB.
PRINT

specifies that a list of libraries
currently in use is to be typed at
the terminal.

usage:GLOBAL has three forms--the ASSEMBLER form, the LOADER form,
and the PRINT form.
ASSEMBLER Forro. The ASSEMBLER form of the GLOBAL command
allows the user to specify the macro libraries that are to
be used during the execution of the ASSEMBLE command. One
to five macro libraries may be specified. These macro
libraries are sea.rched for macro definitions in the order inwhich they are named.
If the CMS macro library ~YSLIBMACLIB and the OS macro library OS MACRO MACLIB are to be
searched along with the use,:- s macro libraries;, SYSLIB and
OSMACRO must be specified as two of the five libraries.
Each macro library specified must have a filetype of MACLIB.
For a description of MACLIB files and how to generate them,see the MACLIB command under "Libraries".

192

GLOBALIf no previous GLOBAL command has been issued, the ASSEMBLE
command searches the two macro libraries SYSLIB MACLIB and
OSMACRO MACLIB in that order. Both files reside on the CMS
system disk; SYSLIB MACLIB contains all of the CMS macros,and OSMACRO MACLIB contains the OS macros. If the user has
created a file named SYSLIB MACLIB or OSMACRO MACLIB that
resides on a disk which precedes the system disk in thestandard order of search, it is used in place of the systemfile. To terminate the searching of all macro libraries,
including SYSLIB MACLIB and OSMACRO ~ACLIB, the GLOBALASSEMBLER command can be issued with no libnames specified.
~Once the ASSEMBLER form of the GLOBAL command has been
issued" the specified macro libraries are searched for macrodefinitions during each assembly until either a GLOBALASSEMBLER
command isreissued, the
CMS nucleus
isreinitialized, or the user logs out from CP.
For a further discussion of macro libraries,
Library Usage under ·Operating Considerations·.

refer

to

PRINT Form.
The PRINT form of the GLOBAL command types at
the terminal a list of the current macro and text libraries
that are being searched for that user.
LOADER Form. The LOADER form of the GLOBAL command allows
the user to specify text libraries to be searched for
missing subroutines and filenames whenev~r the LOAD, USE,. or
REUSE commands are issued. One to eight text libraries may
be specified. These text libraries are searched in theorder in which they are named. If the system text libraries
SYSLIB TXTLIB and CMSLIB TXTLIB are to be searched alongwith the user·s text libraries, SYSLIB and CMSLIB must be
specified as two of the eight libraries.
Each text library specified must have a filetypeof TXTLIB.
For a description of TXTLIB files and how to generate them,see the TXTLIB command under "Libraries".
If no GLOBAL has been issued. the LOADf. USE, and REUSE
commands search the text library SYSLIB TXTLIB. This file
resides on the CMS system disk; SYSLIB TXTLIB contains theFortran library. If the user has created a file with theidentifier SYSLIB TXTLIB that resides on a disk thatprecedes the system disk in the standard order of search, it
is used in place of the system file.
If the GLOBAL LOADER command has been issued and the user
wishes toeliminate the searching of
the previously
specified text libraries;. GLOBAL LOADER TXTLIB can be issued
specifying nolibnames.This
terminates all
library
searching for missing ·subroutines when files are loaded by
LOAD,. USE" or REUSE.
Once the LOADER form of the

GLOBAL command has been issued.

GLOBAL193

the specified TXTLIB files are automatically searched for
missing subroutines or filenames not found during each LOAD.
USE;, or REUSE until either a GLOBAL LOADER command isreissued:. the option LIBE or SLIBE is specified with LOAD
which overrides the GLOBAL LOADER command for the durationof that LOAD and any USE or REUSE commands which follow that
LOAD;~' the CMS nucleus is reinitialized. or the user logs outof CP.
For further discussion on text libraries,. refer
Usage under ·operating Considerations·.

to Library

Notes:
a.
If the GLOBAL ASSEMBLER command is issued, one to fivemacro libraries ~ay be specified and each must have a
filetype of MACLIB.
h.
If the GLOBAL LOADER command is issued, one to eighttext libraries may be specified and each must have a
filetype of TXTLIB,.
c.
GLOBAL will verify the existence of the libraries.
a library does not exist,. an error message is generated.
d.
ASSEMBLER MACLIB and LOADER TXTLIB may
by M and T,. respectivelYte

If

be abbreviatedResponses:
THE CURRENT MACRO LIBRARIES (MACLIB) ARE:
xxxxxxxx xxxxxxxx
THE 'CURRENT TEXT LIBRARIES (TXTLIB) ARE:
yyyyyyyy yyyyyyyy
This is typed in response to the GLOBAL PRINT command where
xxxxxxxx and yyyyyyyy are the names of the libraries,.
Examples:a.
GLOBAL ASSEMBLER MACLIB NEWLIB MYMAC
The libraries NEwLIB MACLIB and MYMAC MACLIB are searched
for macro definitions during the ASSEMBLE command.
The
order of search for macro definitions is NEWLIB MACLIB" then
MYMAC MACLIB. The OMS macro librarySYSLIB MACLIB and theOS macro library OSMACRO MACLIB are not searched.
h.
GLOBAL ASSEMBLER MACLIBThis example cancels the effect of any previously issued
ASSEMBLER form of the GLOBAL command and causes no libraries
to be searched for macro definitions during execution of the
ASSEMBLE command.
c.
GLOBAL LOADER TXTLIB SCOOP OPS SYSLIBThe libraries SCOOP TXTLIB. OPS TXTLIB are searched for
missing subroutines
during the LOADI•USE.
and REUSE
commands. The order of search for missing subroutines is
194

GLOBALSCOOP TXTLIB

1,OPS TXTLIB

i,and SYSLIB TXTLIB.

d.
GLOBAL LOADER TXTLIBThis example cancels the effect of any previously issued
GLOBAL LOADER command and causes no libraries to be searched
for missing subroutines or undefined filenames by subsequent
LOAD" USE, or REUSE commands.
Error Messages:
E( 00001)

An invalid form of the GLOBAL command has been
Reissue the command in its correct format .•issued.

E(00002)

TOO MANY TXTLIBS (MAX=8) OR MACLIBS (MAX=S)
SPECIFIED
Reissue the GLOBAL command reducing the number of libraries
specified.
E(00003)-libname w LIBRARY DOES NOT EXIST
Existence of -libname w MACLIB or -libname w TXTLIB has notbeen verified: wlibname- has been omitted from the activel,ist of libraries ..

GLOBAL

195

LOAD
Purpose:LOAD reads from disk one or more TEXT· files containing
relocatableobject codeand loads
them intocore,
establishing the proper linkages between the files,.
If thespecified TEXT files are not found.. the appropriate TXTLIB-files are searched. Corrections or additions can ~e made atload tilll~ and the user can specify libraries to be searched
for missing subroutines. The user can also specify that
execution should
begin upon successful
completion ofloading.
Format:,LOAD I fnamel ••• fnameN < (optl ••• optN) <libnamel,••• libnameN» I
fnamel •• ,. fnameN

specify the names of TEXT files
to be loaded into core.

optl ••• 0ptN

specify the options to be ineffect during loading,.

libname1 ... ,.libnameN

specify the names of up to 8 TXTLIB
fi~esto be searched for missing
subroutines during loading.

Options:
CLEAR
NO CLEAR

zero the load area before loading
do not zero the load area before loading

SLCxxxxx
SLC12000

begin loading the program at hexadecimal
location xxxxx
begin 10ading the program at hexadecimallo.cation 12000

NOMAP
MAP

do not create the file LOAD MAP
create the file LOAD MAP

TYPE
NOTYPE

type the LOAD MAP file online
do not type the LOAD MAP- file online

SINV

suppress the printing of invalid card
images in the LOAD MAP file
print invalid card images in the
LOAD MAP file

PINV
SREP
PREP

196

suppress the print of Replace cardiroagesin the LOAD MAP file
print Replace card images in the
LOAD MAP file

LOAD

LIBE
SLIBE

search only the specified TXTLIB files
for missing subroutines
do not search any TXTLIB files for unresolved references

SAUTO
AUTO

suppress automatic searching for TEXT files
search the P, T,. and S disks for TEXT files
to resolve undefined references(AUTO is the default and can not be specified
as an option)

XEQ
NOXEQ

execute the loaded files
do not execute the loaded files

usage:The TEXT files specified in the LOAD command must consist of
relocatable object code, such as that produced by the
ASSEMBLEr, FORTRAN. or PLI commands. When LOAD, USE·, or REUSE
is issued, the standard order of search is used to locate
the specified TEXT files. Then, if any unresolved references
exist, the search is used again to locate TEXT files
corresponding to the unresolved names.
If there are stillunresolved references"
the appropriate TXTLIB files aresearched.. To suppress the automatic searching of TEXT files
for undefined names, specify the SAUTO option. To suppress
the library search for unresolved references,
specify the
SLIBE option ..
LOAD assumes the NOCLEAR option as a default, therefore thefiles that are being loaded are not placed in zeroed core.
To zero core before the files are loaded"
the option CLEAR
must be specified.
LOAD automatically begins loading the specified files into
core at hexadecimal location 12000.
This load point may bechanged by specifying the option SLCxxxxx. where xxxxx is
the hexadecimal location at which loading is to begin. The
SLCxxxxx option may not appear as the first option in astring unless it is preceded by one or more blanks .•Unless the NOMAP option is specified
a load map is createdon the perma~ent disk each time .the LOAD command is issued.
A load map 1S a file that contains the location of control
sections and entry points of files loaded into core.
It mayalso contain certain messages and card images of any invalid
cards or Replace cards that exist in the loaded files.. Thisload map is normally created as a·file with the identifier
LOAD MAP P5. Only ~ne SUch file may exist on the permanentdisk. Each time LOAD is issued"
a new LOAD MAP replaces any
previous LOAD MAP file.
To prevent a LOAD MAP file frombeing c'reated, the option NOMAP must be specified.
l•Since LOAD assumes a default of NOTYPE, the LOAD MAP file is
not automatically typed.
To· type this). the option TYPE is
specified. The LOAD MAP file may also be printed by PRINTF
LOAD

191

or OFFLINE PRINT,.
If invalid card images exist in the file or files that are
being loaded they are listed wi th the message INVALID CARD
in the LOAD MAP file.. To suppress this listing in the LOAD
MAP the SINV option must be specified.
t,load w (type)~
AT 12000
W
AT 12000
IBCFCOMH AT 12148
SAVAREA AT 1314C
IBCOM
AT 12148
FOIOCSAT 12204
IBCFCVTB AT 13198
ADCON
AT 13198
FCVEO
AT 13BBAFCVLOAT 13412
FCVIO
AT 13720
FCVCO
AT 13DB4
FCVAO
AT 1338AFCVZOAT 132E4IHCFIOSH AT 14188
Floes
AT 14188
IBCUATBL AT 14070
THE FOLLOWING NAMES ARE UNDEFINED:
SUB1
E(00004); T=O.05/0.20
14.21.33
Typeout of the LOAD MAP file during the LOAD command.

If Replace CREP) card images exist inthe files being
loaded, they are included in the LOAD MAP. To suppress thislistin9 of REP card images
the SREP option must be
specified.
For an explanation of REP card 1mages see
Changing Object Programs under' ·Operating Considerations....
Unless the GLOBAL LOADER command has been issued, LOAD
searches only the system text library SYSLIB TXTLIB forsubroutines that are missing from the files being loaded.
Using GLOBAL" the user can specify from one to eight text
libraries to be searched.. See the description of GLOBAL for
specific details.
If a file exists on a disk preceding the system disk in thestandard order of search with the identifier SYSLIB TXTLIB,
it is used in place of the ~ystem text library.
prevent LOAD from searching the system text library andthe files specified by. GLOBAL, the LIBE or SLIBE option canbe specified.
'LIBE terminates the searching. of all text
libraries except those specified with the LOAD command. If
SYSLIB TXTLIB is to be searched along with the specified
libnames!, SYSLIB must be included as one of the libnames,.

~o

198

LOAD

The order of search of the specified lihnames is the orderin which they are named. The maximum number of libraries
that can be searched is eight. If LIBE is issued and no
TXTLIB files are specified, none are searched for missing
subroutines. If SLIBE is specified with LOAD, no TXTLIB
files are searched. For a discussion of text library usage,refer to Library Usage under ·Operating Considerations",.
LOAD assumes NOXEQ as a default option, therefore, LOAD does
not normally begin execution of the loaded files. To begin
execution immediately upon successful completion of loading,
XEQ. can be specified. LOAD then transfers control to thedefault entry point 'in the program. The default entry point
is either the address specified in the operand field of thefirst END card containing a non-blank operand field or the
beginning of the first file loaded if all END card images in
the TEXT files contain blank operand fields. In the case of
TEXT files that are created by FORTRAN, control is· passed to
the first main program loaded. If XEQ is not specified,
START command must be issued to begin program execution.
Duplicate CSECT·s (Control Sections) are bypassed by theloader.
Only the first CSECT encountered is physicallyloaded. The duplicates are not loaded and a warning message
is included in the LOAD MAP.
LOAD allows the user to include the following card images in
the TEXT fi1es along with the relocatable object code: theSet Location Counter (SLC) card image, the Replace (REP)
card image"
the Include Control Section (IeS)
card image,and the Entry and Library statements.
SLC specifies thehexadecimal location at which files are to be loaded. REP
speci'fies corrections to be made to the relocatable object
code. ICS specifies additions to be made to the TEXT file.
The Entry statement specifies entry points and the Librarystatement
specifies thenever-call
function.
Foradescription of these card images and their use and placement
in a TEXT file, refer to Changing Object Programs under·Operating Considerations·.
Notes:a.
To terminate the searching of all text libraries,
including SYSLIB, specify LIBE with no libnames, or specify
SLIBE.
b.
If TEXT files do not exist for the names specified withLOAD,
either the specified or default TXTLIB files aresearched for the missing TEXT file.
c.
If unresolved names occur. the standard order of searchis used to locate the TEXT files;
if the names are stillunresolved" the appropriate TXTLIB files are searched,.

LOAD

199

Responses:
EXECUTION BEGINS •••XEQ has been specified with LOAD
begun execution.
Any further
program.

and the loaded program has
responses are from the

INVALID CARD - xxx,••• xxx
PINV has been specified with LOAD and an invalid card has
been found,. The message and the contents of the invalid card(xxx ••• xxx) are listed in the file LOAD MAP.
The invalid
card is ignored and loading continues.
CONTROL CARD - •••Aloader or
library-searchcontrolencountered, (that is, ENTRY or LIBRARY) '.
If TYPE is specified with LOAD"

card

has

been

the LOAD MAP file is typed.

Examples:a.
LOAD MAIN SQ3 CALCU
The files MAIN TErr., SQ3 TEXT. and CALCU TEXT are loaded
into core and the linkages resolved,.
If any subroutines are
missing.. the loader searches for the corresponding TEXT
file. If any references are still unresolved, and neither
the SLIBE option nor the GLOBAL LOADER command has beenpreviously issued, the file SYSLIB TXTLIB is searched. If
the GLOBAL LOADER command has been previously issued, thelibnames specified in that command are searched,.
The
followin9 default
options are
set: NOCLEAR,NOTYPE,
SLC12000,. PINV, PREP. MAP I, AUTO, and NOXEQ.
b.
LOAD MPS67 HOOK (XEQ TYPE CLEAR)
The files MPS61 TEXT and HOOK TEXT are loaded into core andthe linkages resolved. Core is zeroed before loading takes
place.
The LOAD MAP file is typed.
Upon successfullyloading MPS61 and HOOK" execution begins.
c.
LOAD MASS WHATZIT (LIBEl SSP MYLIB SYSLIBThe files MASS TEXT and WHATZIT TEXT are loaded into core
and the linkages resolved. If any subroutines are missing,
the following libnames will be searched in the order inwhich they are specified: SSP TXTLIB, MYLIB TXTLIBand"SYSLIB TXTLIB,. The remaining options are set to default.
d.
LOAD MASSPEC (LIBE)
The file MASSPEC TEXT is loaded into core and the linkages
resolved. Since
LIBE has been specified
without any
libnames~
no text libraries
are searched for missing
subroutines. If there are any missing subroutines, an error
code is returned.

200

LOAD

Error Messages:
E(OOOOl)
DEFINED MORE THAN ONCE-xxxxxxxx
The name xxxxxxxx has been defined more than once. Checkthe files that have been loaded for duplicate entry point
names or duplicate control section naroes. Loading has been
completed. Duplicate names are not loaded.
E(00002)
OVERLAY ERROR
The files being loaded have run out of core. Specify fewer
files or reduce the size of the files. Loading has been
completed.
E(00003)
REFERENCE TABLE OVERFLOW
There are too many entries for entry points or control
section names in the reference table built during loading.
Loading has been completed. Reduce the number of entry
points and/or control sections in the files.
E(00004)
THE FOLLOWING NAMES ARE UNDEFINED-xxxxxxxx
The names xxxxxxxx are referenced in a file and are neverdefined.
If the names are defined in a file with adifferent name, issue USE for that file.
Loading has been
completed.
Dynamic Loading
During program execution~ another relocatable object deck
may be brought into core, external references resolved, andcontrol given to it--that is, dynamic loading. The desired
routine must exist on the user's files with a filetype of
TEXT, or exist in one of the designated libraries withfiletype TXTLIB.
The routine may cause other TEXT or
library routines to be loaded into core.
The following CMS/OS macros support dynamic loading:
LOAD (SVC 8)

causes the object
deck containing thespecified entry point to be brought into
core and the entry point address to be
returned in register zero (0).

LINK (SVC 6)

calls in and transfers
specified entry point.

XCTL (SVC 7)

deletes the calling routine, then brings
the specified routine in and gives control
to it.

RETURN (SVC 3)

deletes thecalled routine
control back to the caller.

LOAD

control

and

to

the

gives

201

LOADMOD
Purpose:LOADMOD loads into core any
core image form.

single filein nonrelocatable

Format:LOADMOD

filename <filemode>,

filenameis the name of the file to be loaded
The filetype must be MODULE.

into core.

filemodeis the mode of the MODULE file to be loaded,.

Usage:LOADMOD is used to load a file which has been created by the
GENMOD command.
The filename of the file to be loaded isspecified as the operand of the LOADMOD command"and its
filetype must be MODULE. If the MODULE file was generated
without a load map and the MODULE file is to be read into
core and executed"
LOAD MOD can not be issued; instead, the
MODULE's filename must be issued as if it were a command.
When LOAD MOD is issued without specifying a filemode, thestandard order of search is used to locate a file with thespecified filename and a filetype of MODULE. If a filemodeis given, only that disk is searched for the MODULE file.
If such afile is found, it is assumed
to be innon-relocatable core-image form, and is loaded into core.
Responses:
N'one.
Example:LOADMOD FILE1
The file FILEl MODULE is loaded into core. If no such file
exists. an error message is returned!, and the loading
process does not take place.
Error Messages:

E(OOOOl)

FILE DOES NOT EXISTDISK ERROR
Either of the above messages indicates that a file with thespecified filename and a filetype of MODULE cannot belocated. Check to see that such a file exists and that the
filename specified in the LOADMOD command is identical to
the filename of the file to be loaded,.

202

LOADMODE(00002)
DISI{ ERROR
An address has been generated outside the bounds
storage assigned to the user. Reissue the command.

of coreE(00003)
DISI{ ERROR
A disk malfunction has occurred.
Reissue the LOADMOD
command. If the message persists a disk hardware problem
has probably been encountered.
l,E(00004)

FILE DOES NOT EXISTDISI{ ERROR
Either of the above messages indicates that the filemode of
the specified file is invalid. Change the filemode to avalid one and reissue the command.
E(00006)
DISI{ ERROR
Core space assigned to the user is not large enough forloading the specified file or the system has attempted toclose the file prior to opening it. Reissue the LOADMOD
command.
E(00007)
DISK ERROR
The specified fi1e cannot be read from disk.
Reissue the
LOADMOD command. If this message persists, the file should
be recreated using the GENMOD command.
E(00009)
DISK ERROR
The specified file is open for writing andReissue the LOADMOD command.

LOADMOD

cannot be read;.

203

REUSE
Purpose:REUSE reads from disk one or more TEXT files containing
relocatableobject codeand loads
them intocore,
establishing linkages with previously loaded files, andchanging the default entry point of these files to that of
the first file specified in the REUSE command. If the TEXT
files do not exist. the appropriate TXTLIB files aresearched,.
Format:I REUSE I fname1.

,w ,.

fnameN (opt1.

w •optN) <libname1 •.•• libnameN> I

fnamel ••• fnameN

specify the names ofloaded into core.

TEXT files to be

optl ••• optN

specify the options toduring loading •.libname1,.... 1ibnameN

specify the names of up to 8 TXTLIB
files to be
searched for missing
routines during loading.

be ineffectOptions:
The options that may be specified with REUSE are the same as
those with LOAD.
Usage:
REUSE does not overlay any file that has been previously
loaded by a LOAD, USE"
or REUSE command..
It loads the
specified files into higher core from the point at which theprevious LOAD, USE, or REUSE command terminated loading.
REUSE performs the same fUnction as USE except that REUSE
changes the default entry point to that of the first filespecified with the REUSE command.
The specified files must haverelocatable object code.

filetypes of TEXT and contain

If options have been specified with the previous LOAD. USE,
or
REUSE command,these options
rema1n set
unlessrespecified. The LOAD MAP file is automatically updated toreflect the files loaded by REUSE.
Refer to LOAD for a
description of the LOAD options; the LOAD MAP file, and how
LOAD operates.

204

REUSE

Responses:
INVALID CARD - xxx ••• xxx
PINV has been specified and an invalid card has been found.
The message and the contents of 'the invalid card (xxx... ,.xxx)
are listed in the file LOAD MAP. The invalid card is ignored
and loading continues.
CONTROL CARD
loader or
library-searchcontrolencountered. Normal loading resumes.

A

card

has

been

If TYPE has been specified with REUSE or bas not been resetfrom the previous LOAD~ USE, or REUSE command, the updated
portion of the LOAD MAP file is typed prior to thecompletion of the REUSE command.
Example:
REUSE READIT GAMMAThe TEXT files READ IT and GAMMA are loaded into core,
linkages resolved with-the files previously loaded, and thedefault entry point is changed to the first entry point in
READIT.
Error Messages:
E(00001)
DEFINED ~ORE THAN ONCE - xxxxxxxx
The name xxxxxxxx has been defined more than once. Checkthe files that have been loaded for duplicate entry point
names or duplicate control section names. Loading has been
completed. Duplicate names are not loaded.
E(00002)
OVERLAY ERROR
The files being loaded have run out of core. Specify fewer
files or reduce the size of the files.. Loading has- been
completed.
E(00003)
REFERENCE TABLE OVERLAY
There are too many entries for entry points or control
section names in the reference table built during loading.
Loading has been completed. Reduce the number of entry
points or control sections in the files.
E(00004)
THE FOLLO~ING NAMES ARE UNDEFINED - xxxxxxxx
The names xxxxxxxx are referenced in a file and are neverd-efined. If the names are defined in another file" issue
the USE command for that file. Loading has been completed.
EC00005)
NAME IS UNDEFINED - xxxxxxxx
The name xxxxxxxx specified as an entry point does notexist. Loadinq has been completed.
Check the name and see
if an entry point or a control section exists by that namein the loaded files.

REOSE

205

START
Purpose:begins ·execution of programs previously loaded andpasses the address of a string of user arguments to that
program.
S~ART

Format:START

I<entry <arqument1 ••• argumentN»1

I

•

I

------~------------------------------------

entry

specifies the nameof a control
section or entry
point to which
control is passed at execution time.

*

specifies that control
is to bepassed to the default entry pOint.

argument1 ••• argumentN

specify information to be
the started program.

passed toUsage:START begins execution at one of two entry points. If theentry operand is specified;, execution begins at that pointin the program.. If * or nothing is specified execution
begins at the default entry point. The default entry point
is either the address specified in the operand field of thefirst END card containing a non-blank operand field or the
beginning of the first file loaded if all END cards in the
TEXT files contain blank operand fields. The default entry
point can be changed by issuing the REUSE command tocontinue loading additional files.
Any undefined names or references specified in the files
loaded into core are defined to location zero.
Thus, ifthere is a call or branch to a subroutine from a main
program and the subroutine has never been loaded, the callor branch transfers control to location zero at executiontime.
If arguU!ents are specified with START., they are passed tothe program via general-purpose register 1.
The entry
operand and any arguments are set up as a string of words,
one argument per double word, and the address of theparameter is placed in general-purpose register 1.
Thearguments are accessed with displacements of 8/, 16. 24,
etc., from the address containedin register 1 when
execution of the specified program begins.

206

START

Notes:a.
Entry must be a contro1 section name or an entry point
name. It may be a filename only if the filename is identicalto a control section name or an entry point name.
b.
If user arguments are specified, entry
specified; otherwise~ the first argument isentry point.

or * must be
taken as the

Responses:
EXECUTION BEGINS •••The program previously loaded into core has begun execution.
Further responses are from the executing program.
Examples:a. START INITIL
The program already loaded
entry point INITIL.

into core

begins execution

ath. START MEGOP 13 ALL 109439
The program already loaded into core hegins execution atentry point MEGOP. The three arguments may be accessed in
the program by displacements of 8:. 16(, and 2q from theaddress in general-purpose register 1.
Error Messages:

E(00004)
The contents at STADDR in NUCON are either 0 or a locationthat does' not contain executable code. Issue LOADMOD and
START a9ain.
E(OOOOS)NAME IS UNDEFINED - xxxxxxxx
The name xxxxxxxx specified as the 'point at which execution
is to begin does not exist as an entry point name or acontrol section name.
Execution has not be9un.
Check thename xxxxxxxx and make sure i t is a valid entry point orcontrol section name.

START

207

USE
Purpose:
USE reads one or more TEXT files containing relocatableobject code from disk and loads them into core, establishinglinkages with previously loaded files.
If the TEXT files do
not exist. the appropriate TXTLIB files are searched.
Format:

1USE 1fnamel ••• fnameN < (opt1,••• optN) <libname1 ... _libnameN»,

fnamel ••• fnameN

specify the names
loaded into core.

beoptl ••• optN

specify the options
during loading_of TEXT
tofiles tobeineffectlibnamel ••• libnameN specify the names of up to eight TXTLIB
files to be searched for missing routines
during loading.
Options:
The options that may be specified with USE are
those that may be specified for LOAD,.

the same as

Usage:
USE does not overlay any file previously loaded by a LOAD,
USE" or REUSE command. It loads the specified file(s) into
hig:ler core from the point at which the previous LOAD, USE,
or REUSE command terminated loading. The files spe!~ified
with USE have filetypes of TEXT and contain relocatableobject code.
USE should be preceded by LOAD: it is issued to resolve
undefined names when LOAD gives the following error message:
E(00004) - THE FOLLOWING NAMES ARE UNDEFINED: xxxxxxxx.
USE may be issued repeatedly to resolve linkages and tocontinue loading more TEXT files.
It does not change thedefault entry point established in a previous LOAD command.
If options are specified with the previous LOAD.. USE" or
REUSE command" the options remain set unless respeci'fiedwhen USE is issued. The LOAD MAP file is automatically
updated to reflect the files loaded by USE.
Refer to LOAD
for a description of the LOAD options" the LOAD MAP file,and the operation of LOAD.

208

USE

Responses:
INVALID CARD - xxx ••• xxx
PINV has been specified with the previous LOAD command andan invalid card has been found.
The message and thecontents of the invalid card (xxx ••• xxx) are listed in thefile LOAD MAP.
The invalid card is ignored and loading
continues.
If TYPE has been specified with USE or has not been resetfrom the previous LOAD. USE. or REUSE command. the updated
portion of the LOAD MAP file is typed prior to thecompletion of the USE command.
Example:USE MYTEXTl CALCA WRITE6
MYTEXTl TEXT. CALCA TEXT. and WRITE6 TEXT are loaded intocore. Linkages are resolved between these three files andthe fil~ previously loaded into core.
Error Messages:
E(OOOOl)
DEFINED MORE THAN ONCE - xxxxxxxx
The name xxxxxxxx has been defined more than once. Checkthe files that have been loaded for duplicate entry pOint
names or duplicate control section names. Loading has been
completed. The duplicates are loaded.
E(00002)
OVERLAY ERROR
The files being loaded have run out of core. Specify fewer
files or reduce the size of the files. Loading has been
completed.
E(00003)
REFERENCE TABLE OVERFLOW
There are too many entries for entry points or control
section names in the reference table built during loading~Loading has been completed. Reduce the number of entry
points or control sections in the files.
E(00004)
THE FOLLOWING NAMES ARE UNDEFINED - xxxxxxxx
The names xxxxxxxx are referenced in a file and are neverdefined. If the names are defined in another file. issue the
USE command for that file. Loading has been completed.

USE

209

$
Purpose:$ loads and starts the specified file, provided its filetypeis EXEC. MODULE, or TEXT~Format:$,filename<arg1 ••• argN>

filenameis the name of a file whose
I'JODULE, or TEXT.

filetype is EXEC,

arg1 .••• argN

are one or more user arguments.

Usage:-rhe $ command is used to load and start a program.. The
program exists as a file on one of the user's disks, and its
filename must be specified as the first operand of the $command. The standard order of search is used to locate afile with the specified filename and a filetype of EXEC,MODULE, or TEXT, in that order.
If an EXEC filetype is found for the filename. the file isassumedto contain one or more CMS commands .. and EXEC iscalled to execute this file.
If no EXEC filetype exists,
but a filetype of MODULE is found" LOADMOD is called by $ toload the program into cor~ and START is called to begin
execution of the program. When only a TEXT filetype exists
LOAD is called followed by START.
The user may specify ·as many arguments in the $ command as
he wishes,. provided they all fit on the same input line.
The arguments are set up as a string of double words" oneargument per double word.
The address of this string is
passedtothespecified file.
Eachargument
isleft-justified, and any argument more than eight charactersin length is truncated on the right. ~ith an EXEC file~ anyarguments
specified inthe$command repla.cethecorresponding &n operands in the individual commands of the
EXEC f.ile (see EXEC under -Execution Control" for a full
explanation of this operand-substitution technique),.
with a file whose filetype is MODULE or TEXT, the arguments
are placed in a string as described above..
The address ofthe string may be obtained by adding 8 to the addresscontained ingeneral-purpose register 1 at
the time
execution of the specified program begins..
Additional
arguments may be referenced by displacements of 16" 24/, 32.
etc." from the address thus obtained.

210$

Note:
When a file with a filetype of MODULE or TEXT is used/I there
must be an entry point in the file that is identical to thefilename specified in the $ command.
After the file has
been loaded,. execution begins at this entry point.. such an
entry point is created by the Fortran compiler using thefilename specified in the FORTRAN cOFmand. With Assembler
language files, the user should create as an entry point or
assign as the name of a control section,. the filename bywhich he wishes to reference the TEXT or MODULE version ofthat file.
Responses:
For files with filetype EXEC, each command in the EXEC fileis typed at the user's terminal prior to its execution
unless the &TYPE option is used to suppress the printout.
EXECUTION BEGINS,. '••This message is typed when a file of filetype MODULE or TEXT
has been loaded into core and is about to be started. Output
appearing after this message is from the user's program orfrom a part of eMS called by that program.
DEFINED MORE THAN ONCE - xxxxxxxx
This message is generated by LOAD and indicates that
duplicate entry points or control section names (xxxxxxxxl
have been found in the TEXT file being loaded.
$ isterminated with an error code of 3.
OVERLAY ERROR
Th'ere is not enough room in core to hold the TEXT file forwhich a LOAD has been issued. $ is terminated with an error
code of 3.
REFERENCE TABLE OVERFLOW
There are too many entry points or control section names in
the TEXT file being loaded. $ is terminated with an error
code of 3.
THE FOLLOWING NA~ES ARE UNDEFINED - xxxxxxxx
The specified names referenced in the TEXT file being loaded
are never defined. $ is terminated with an errQr code of ,3.
DISK ERROR
An error has .occurred while reading or closing a file withfiletype MODULE. This message is generated by LOADMOD, andterminates with an error code of 3.
Examples:a~$ MYFILE
The standard order of search is used to locate a file with afilename of MYFILE and a filetype of EXEC, MODULE or TEXT.
If a file exists with filename MYFILE and filetype EXEC, the
t•

$

211

commands contained in it are executed.
Each command is
typed at the user·s terminal before it is executed. If
filetypes MODULE and TEXT or of MODULE only exist forfilename MYFlLE, the file with filetype MODULE is loaded
into core by LOADMOD and started by START at entry point
MYFILE. If only a TEXT filetype exists for filename MYFILE,
LOAD is issued to bring MYFILE into core. and START is
issued using entry point MYFILE.

b . $ OTHER SAME 1.436 5 A
If filetype EXEC is found for filename OTHER execution of
the EXEC file begins with the argument SAME replacing &1
wherever it appears in the EXEC file, 1,.436 replacing &2, 5
replacing '3. and A replacing
If no EXEC filetype exists
for filename OTHER but a filetype of MODULE or TEXT is found
the file is loaded into core and started at entry point
OTHER.
The fouruser arguments can beaccessed bydisplacements of 8, 16 1• 24, and 32, respectively!, from theaddress contained in general-purpose register 1 at the time
program OTHER is started~
t•

'4..

212

$

DEBUGGING FACILI~IES
A debugging tool is provided with eMS in the form of the
DEBUG command. This command allows the user. while at his
terminal!. to examine and change the contents of core
locations program status words, general-purpose registers,
the chann~l status word and the channel address word; todump portions of core on the offline printer; and to. stopand restart programs at any specified point or points.
Methods for using these DEBUG facilities are described inthis section.
i•l•

In addition to DEBUG. there are two commands that allow theuser to trace supervisor calls (SVC instructions) andtherefore. .the internal branches which are issued to thevarious
CMS
commands
andfunctions.
These
two
commands--SETOVER and SETERR--set certain overrides, orflags, which are checked whenever an SVC instruction is
executed and a return is issued from an SVC-called program.
Two types of overrides .may be set: normal and error.
Normal overrides are those which cause trace information to
be recorded
for SVC-called programs
executed without
encountering any error conditions.
Error overrides arethose which record information for SVC-called programs which
return with an error code in general-purpose register 15.
The S-ETOVER command sets both types of overrides. The SETERR
command sets error overrides only.
To clear overrides which have been set by the SETOVER and/or
SETERR commands. the CLROVER command may be issued.
Inaddition to terminating the recording of trace information,
CLROVER causes all information recorded up to that pOint tobe printed on the offline printer.
If the user wishes to terminate the recording of trace
information during the execution of one of his own programs
or of a CMS command (that is, -at a point when the CLROVER
command cannot be issued) he may do so by hitting ATTN twice(pausing each time for the keyboard to unlock) and typing
the letters KO followed by a carriage return. Processing
continues as before, but no further information is recorded
for SVC's executed. KO terminates overrides and causes
recorded trace information to be printed on the offlin~
printer.
If the user bas set overrides by issuing either or both the
SETOVER and SETERR commands and has. failed to clear theseoverrides they are cleared automatically and the recorded
information is printed on the offline printer when the user
logs out from the Control Program or when he issues a
RESTART request in the Debug environment.
l,Debugging Facilities

213

CLROVER
Purpose:
CLROVER clears overrides set by either or both the.SETOVER
and SETERR commands,.
It also cause~ all trace information
recorded up to that point to be printed on the offline
printer.
Format:
CLROVER
Usage:
This command terminates the recording of trace information
set by the SETOVER and/or SETERR commands and causes that
information to be printed on the offline printer..
If
CLROVER is not issued. the user may clear all currently
active overrides by issuing a KO command. Any overrides
which have been set but not cleared at the time the user
issues a REST~ request in the Debug environment or ends
his terminal session by logging out from the Control Program
are cleared automatically and the trace information isprinted o,ffline.
CLROVER cancels the effect of all SETOVER and SETERR
commands issued since the last'KO or CLROVER command wasissued, or since the user's last CMS login if neither a KO
nor a CLROVER has been issued durin9 the terminal session.
Once CLROVER is issued" no further trace information isrecorded until the user issues another SETOVER or SETERR
command.
A sample of the format in which trace information is printed
offline is given in Figure 15. A fixed amount of trace
information is printed for all error overrides; the amountfor normal overrides varies
depending on the options
specified with the SETOVER command. An explanation of all
possible fields which can appear in the printout is given
under ·Output- in this section.
Notes:a.

If a CLROVER command is issued when no overrides are
currently activel, it has no effect other than printing
the following 1ine on the offline printer:****NOTE--NORMAL- AND ERROR-OVERRIDES HAVE NOW BEEN CLEARED****b.

214

Any operands given with CLROVER are ignored.

CLROVERResponses:
None.
output:An explanation of each field appearing in the
trace information is given below.

printout of

SETTING ERROR-OVERRIDE TO PROVIDE A DYNAMIC TRACE OF(AND aS) SVC-CALLS.,••This message appears whenever SETERR is issued.
SETTING NORMAL- AND ERROR-OVERRIDES TO PROVIDE A
TRACE OF CMS (AND OS) SVC-CALLS,•••This message appears whenever SETOVER is issued.

CMS

DYNAMIC• •••• ERROR-OVERRIDE.
This message identifies the first line for each SVC-called
program which returns with an error code in general-purpose
register 15.
NORMAL-OVERRIDE:,
This message identifies the first line forprogram which issues a normal return.

each SVC-called

CALLER = xxxxxxxx
This information appears in thefirst .line for each
SVC-calle~
program.
It indicates the hexadecimal core
location (xxxxxxxx) of the SVC instruction whose execution
caused that program to be called.
CALLEE = 'xxxxxxxx
This information appears in thefirst line for each
SVC-called program. xxxxxxxx is the name of the called
program (if a CMS SVc is issued) or the number of the SVC(if an 0$ svc is issued).
SVC~OLD-PSW = xxxxxxxxxxxxxxxx
This information, givenin the first line
for each
SVC-called program, gives the contents of the SVC oldprogram status word. For an explanation of the SVC oldprogram status words and its use, see the IBM manual. ~System/360 Principles of Operation.

=

NRMRET
xxxxxxxx
This information, givenin the first line
for each
SVC-ca~led
program, gives the hexadecimal core location(xxxxxxxx) to which theprogram returns under normal
conditions (that is, when no error code is generated)I.

ERRET = xxxxxxxx
This information, appearing at the rignt margin of the firstline for each SVC-called program, gives the hexadecimal core
location (xxxxxxxx) to which the program returns if an error
code is generated during its execution.
CLROVER

215

GPRS BEFORE = xxxxxxxx,••• xxxxxxxx
Two lines of information appear with this message.
The
first line consists of the contents of general-purpose
registers 0-7: the second line gives the contents ofregisters 8-15 as they existed when control was passed to
the SVC-called program,.
FPRS BEFORE = xxxxxxxx~_.xxxxxxxx
This line of information gives the contents of the four
floating-point registers as they existed at the time control
was transferred to the SVC-called program.
GPRS AFTER = xxxxxxxx ••• xxxxxxxx
Two lines of information appear with this message.
The
first line gives the contents of general-purpose registers
0-1; tbe second line gives the contents of registers 8-15 asthey existed when a return was issued by the SVC-called
program.
FPRS AF-rER = xxxxxxxx .• _ • xxxxxxxx
This line of information gives the contents of the four
floating-point registers as they existed when a return was
issued by the SVC-called program.
PARM.-LIST = xxxxxxxx •.•• xxxxxxxx
This message is followed by one or two lines of theparameter list which existed at the time the SVC was
executed. See SETOVER under ·Debugging Facilities· for a
discussion of parameter lists and their use.
****NOTE--NORMALANDERROR-OVERRIDES HAVENOWBEEN
CLEARED****
This message appears whenever a CLROVER command is issued.
Example:
CLROVERThis clears all currently active overrides and cause any
trace information recorded up to that point to be printed on
the offline printer. See Figure 15 for a sample of the typeof information printed.
Error Messages:
None.

216

CLROVERSETTING HORIIlL- UID ERIIOR-OYEIIRIDES TO PROYIDE A DYJABIC TRACE OF CIIS (AID OS) SYC-C.lLI.S •••NOBBAL-OVERRIDE,CALLEB=00009514
PAS.-LIST = --SETO---YEB -FFFFFPFF
FFFFFFFFCALLEE=SETOYE8 SVC-OLD-PSII=000400CA60009516
FFFFFFFF
fFFFFFFF
FF"FFFFF!
FlFFFFFPFF'FPFFPF
PFF'FFFFFFPFFFFFP
FlFFPFFFBaBaBT=0000951A
EBRET=0000951A
PFFFFlFF'PPFFFFFFFFPPFlP
FlFFlPlP*****ERBOR-OYERRIDE.
CALLER=000057F2
GPRS BEfORE = E2C5E3D60000139C
00009386
00012000'PBS BEfOBE
00000000
00000000GPJiS AFTER
E2C5E3D60000139C
00000004
00000100FPRS AFTEB
00000000
00000000
PAliB. -LIST =--FIIII---S
FFFFOOOO
00000000

CALLEE=FU IS
SVC-OLD- PSII=000400cA400057P4
00000000
00005816
00009B10
E2C5E3D600009508
00000001
400057E800001180
00000000
00000000
00000000
00000000
0000139C
00000000
00000718
000C29DC
C6C9D5C9E2404040
000040A8
ooooouO
00000000
00000000
00000000
00000000--OYEJr--NB!BBT=000057P8EBBBT=0000S1p8
00005018
0003E8B840009540
000011BO
00000000
00000000
00000120
00000048
000026C£
00000006
00000000
00000000
5C40FlFP
F.FEPIFD--BIDE---!ODO--HOBaAL-OVERRIDE,CALLER=0000955A
PAB8.-LIST = --TIPL---IN---0.50-4BP1F315

CALLEE=TYPLIBSYC-OLD-PSI/=000400CA6000955C
0100960C
C200001A
D95E40B3
7EFOQBFO
17174040
40401517
17C54DD5

HRBBET=00009560
EiRET=0000954A
P461F04B--14 2 --08BR-5D5£40£3

NORBAL-OVERRIDE,CALLER=00009608
PARa.-LIST = --iAIT---RD---TIPL---IN--

CALLEE=iAITRDSYC-OLD-PSII=000400CA400096DA
01009774
E4000010--T!PL---IN-0100960C
C2000011
D95E40E3
1EF04El'O

HRBIIET=000096DE
ERBET=000096DE
01009386
D2000020
F461F04Jl--14 2 -*****EBROR-OVERRIDE.
CALLER=00009514
GPBS BEFCH
E2E3C1E3
00009B1000009386
00012000
FPBS BEFORE
00000000
00000000
GPBS AFTER
E2E3C1E3
00009B1000000004
00000100
PPIiS AFTEB
00000000
00000000
FARI!.-LIST =--STAT---E
FFFFFPFF
FFFFFFFFCALLEE=ST1TE
SVC-OLD-PSi=000400CA60009516
00000000
00000000
00009B10
E2E3C1E3
00009508
00000001
40009318
800094CO
00000000
00000000
00000000
00000000
00009B 1 000000000
00000778
00002A84
E2E3C1E3
C5404040
00002BDO
OOooono00000000
00000000
00000000
00000000--TEST---SISI---I
FFFFFFFF
FFlFFFFF
FPFFFFl!
P"FPFPPNB8RBT=00009511
EBRET=00e09S1A
000050A8
0003E8B860009580
00000001
OOOOOOOC
00000000
00000120
00000048
000026CE
00000001
00000000
00000000FFFIIFFP'FlIPI!1
PFFFPFFFFFPFFFFP**** *E IiRCR-OV BRRItE,
CALL );8=00005712
GPRS BEFORI! = E2E3C1E30000139C
00009386
00012000
FPBS BEFOBE = 00000000
00000000GPRS AFTER
E2E3C 1E30000139C
00000004
00000100
FPES AFTEB = 00000000
00000000
PARB.-LIST = --FIHI---SFFFPOOOO
00000000

CALLEE=FIBISSYC-OLD-PSI=000400CA400C57F400000000
00005816
00009Bl0
E2!3C1E3
00009508
00000001
4000571:8000(11BO
00000000
00000000
00000000OCOOOOOO
00001390
00000000
00000778
000029DC
c6C9D5C9E2404040
00004018
000COA1000000000
00000000
00000000
00000000--OVEB-

NB8RE'l:000057F8
EBlIET=000057 pa
000050A8
0003E8E840009540
000011BO
00000000
00000000
00000120
00000048
000026CE
00000006
00000000
00000000
5C40PFFFFPFEPFPD-llIDE---80Do--

lIOli/IAL-OVERRIDE,CALLER=0000972E
PARI!.-LIST = --TIPL---IN---YSIII--CALLEE=TYPLIN
5 VC-OLD- PSII=OOO 400CA 600(; 9730
01009631
C2C00021
00000010--STlT--

NR!BET=00009734
ERBET=0000972E--E T £---ST 5 -!'OlfIlAL-CVEBRItE,
CALLER=00009608
PARB.- LIST =--WAIT---RD---TIPL---IN

CALLEE=IIAITRDSVC-OLD-PSI =000 400C14000 .,I:DA
01009174
E4000014--TYl'L---li-0100960C
C2000011
D95E40E3
7EFC4EFO

NB!RET=000096DE
ERBET=000096DE
01009386
02000020
F461F04B--11 2--*****E6ROR-OVEBRIDE,CALLER=00009514
GPRS BEFOBE
E2E3C1E3
00009B1000009386
00012000FPRS BEFCRE
00000000
00000000GPRS AFTER
E2E3C1E3
00009Bl000000004
00000100FPRS AFTER
00000000
00000000
FAR!!.-LIST--STAT---E
FFFFF1FF
HFFFFFFCALLEE=STATESVC-OLD- PSI=000400CA60CC 9516
00000000
00000000
00009810
E2E3Cl!300009508
00000001
4000937E
SOOC94C000000000
00000000
00000000
00000000
00009Bl000000000
00000778
00002184
E2E3C1E3
C5404040
00002BDO
COOC01AO
00000000
00000000
00000000
00000000--SAI!E---LE ---FORT---R.lN -FFFFFFFF
FFFFFFFPFFFFFFFF
FFFFFFFF

NB!BET=0000951A
ERRET=0000951A
00005018
0003E8E8
60C09580
00000001
00000000
00000000
00000A2000000048
000026C1
00000001
00000000
00000000FFFFFPFFFFPFFFIF
FFFlPFF.
Fl'FUPFF*****ERROR-OVERRIOE,
CALLER=000057F 2
GPBS BEFCRE = E2E301E3
0000139C
00009386
00012000FPRS BEfORE
00000000
00000000
GP6S AFTER
E2E3C1E30000139C
C0000004
00000100
FPBS AFTER
00000000
00000000
PAR~.-LIST =--FIN1---5
FPFFOOOO
00000000

CALLEE=PIIiISSVC-OLD-PSII=000400CA400057F400000000
00005816
00009Bl0
E2E1C1E3
000095C8OCOOOOOl
400057E8000011BO
00000000
00000000OOOOOOOCOOCOOOOO
0000139C
00000000
00000778
000029DC
C6c9D5C9E2404040
00004018
OOOOOno00000000
00000000
00000000OOOCOOOO--OYEJr--

NB8BET=000057F8
EaRET=000057F8
000050A8
0003E8B840009540
000011£000000000
00000000
00000120
00000048
000026CE
000000C600000000
00000000
5C40FFFF
FFF£FPfD--BIDE---80DO--"OF I'JAl-CVEBIiI n,
CALL fR=0000972 E
PARlI.-LIST = --TYPL---IN-- FOR---TR1N--

CALLEE=TIPLIHSYC-OLD-PSV=000400CA60CC9130
01009631
C2000021
00000014--STAT-

HB!BET=00009734
EiBET=0000972E--E 51---8PLi--bOF!!Al-CVERlnr:f,
CALLfR=00009608
FARI'l.-LIST = --WAIT---RD---TIPL---IN--

CALLEE=V AIT BDSYC-OLD-PSV=OOO 400C140CC 91i0A
01009714
E4000013--T!PL---11-0100960C
C2000011
D95E40£3
7EPC4BFOIIB!RE'l=0000960E
EiRE'l=000096DE
01009386
D2000020
F561F04B--11 2--NORKAL-OVERRIDE.
CALLER=00009514
PARlI.-LIST = --STAT---E
FFFFFFFF
FFFFFFFFCALLEE=STAT E
SVC-OLD-PSII=00040OC160CC9!:16--FIGo---RE ---SCRI---(7-EFFEFFFF
l'FFFFPFF
fFFFFPFF
HUFFPF

HB!RBT=0000951A
BBBET=0000951A
FFUFIFF
000013IiO
FFFPPFFF
FFFFPlFF**** $EBROR-OVERRIDE.
CALLER=000057F 2
GPliS BEl'1JRI! = E2E3C1E30000139C
00009386
00012000FPFS BEPORE
COOOOOOO
00000000
GPliS AFTER
E2E3C1E30000139C
00000004
00000100
FPliS AFTER
00000000
00000000
PARrI.-LIST =--FINI---5
FFFFOOOO
00000000

CALLEE=FI US
SVC-OLD-PSII=OOO 400C14CCC57F400000000
00005816
00009810
E2E~C1E3
C0009508CC000001
400057E8000011BO
00000000
00000000
00000000
OOCCOOOO
0000139C
00000000
00000778
000029D<:
c6C9D5C9E2404040
00004018
OOOOOUO
00000000
00000000OOOOOOOC
oeccoooo-*
00000000--*

00000000.

00000000

00000000

00000000

00000000--*

00000000--*

00000000

00000000--F lGU--IIRBBET=000057F8
EBBET=000057F8
000050A8
0003E8B840009540
000011JlO
00000000
00000000
00000 A2000000048
000026CE
00000006
00000000
00000000
5C40FPlF'!PIPfFD--BE - --SCBI--hOF Hl-CVEEEHE,CALL ER=0000955 A
FAFlI.-LIST = --TIPL---IN---0.50-4BF4F815

CALLEE=TIPLI~SYC-OLD-PSII=000400CA60CC9!:5c
C200001A
D95E40E3
7EPC4BFO
40401517
17054 tPO

HR!8E'l=00009560
E8BBT=00009541
F 361F 04B--08 2---0001-5D5E40!3

IiOli8AL-OVEBRI DE,
CALL ER=OOO 096D8
PAS8.-LIST = --IIAIT---RO--TIPL---IN

CALLEE=VAITRDSYC-0LD-PSII=000400C1400096DA
01009774
E4000007--TlPL---IK010091:0C
c200001l
D95E40E3
71!FCUFOBBBRET=000096DE£BBET=000096DE
01009386
02000020
F361F04E--08 2 -00000000
0100960C
17174040

00000000--*
00000000****liOTE--NORrlAL- AIiO ERROR-OVERRIDES HAVE HOW BEEII CLE1RED**.*

Figure 15.

Sample offline printout of trace information
recorded by the SETOVER command
CLROVER217

DEBUG
Purpose:The purpose of the DEBUG command is to provide the user with
online facilities for debugging programs and to provide an
entry in CMS for handling external and program interrupts
and unrecoverable errors.
Format:I DEBUG ,Usage:
The facilites of DEBUG are made available to the user when
the DEBUG command is issued,. an external interrupt occurs, a
program interrupt occurs a breakpoint is encountered during
program execution, or an unrecoverable e~ror occurs. Once
DEBUG
has beenentered due
to anyof theabove
circumstances, tne user is said
to be in the Debug
environment. The only valid input in this environment is
the group of DEBUG requests discussed in this sectio~. Fiveof the requests--GO, IPL/, 1{X, RETURN. and RESTART--cause theuser to leave the Debu-:J environment. Which of these five
requests should be issued depends on the circumstances underwhich DEBUG is entered. Refer to the section dealing witheach request for a further discussion of its use.
l,When the Debug environment is entered. the -contents of all
general-purpose registers:, the channel status word and thechannel address word are saved so they may be examined andchanged prior to being restored when leaving the Debug
environment. If DEBUG is entered via an interrupt" the oldprogram status word for that interrupt is also saved. The
reque~ts which may be issued
in the Debug environment allow
the user to examine and change the contents of these control
words and registers as well as portions of the user's
virtual core.
Each ofthese requests
is describedindividually in the following sections.
i•

Notes:a.

KT

and KO are not recogniz~d in the Debug environment.

b.
The floating-point registers may not currently be
examined or changed in the Debug environment. To access thefloating-point registers!, the CP console functions DISPLAY
Yreg and STORE Yreg may be used.
Responses:
DEBUG ENTERED •••This message indicatesthat DEBUG

218

DEBUG

bas

been

enteredin---------------

response to the DEBUG command or due to an unrecoverable
error encountered during execution. Any DEBUG request may
be issued as soon as the keyboard is unlocked.
DEBUG ENTERED, EXTERNAL INT.
This message indicates that an external interrupt has caused
DEBUG to be entered and that the external old program status
word is saved.
Any DEBUG request may be issued as soon as
the keyboard is unlocked.
DEBUG ENTERED PROGRAM INT. PSW = xxxxxxxxxxxxxxxx
This message indicates that a program interrupt bas .caused
DEBUG to be entered. The program old PSW is save~, and its
contents typed in hexadecimal representation as indicated by
xxxxxxxxxxxxxxxx above. Any DEBUG request may be issued assoon as the keyboard is unlocked.
DEBUG ENTERED BREAKPOINT xx AT xxxxxx
This message is typed when
DEBUG is entered due· toencountering a breakpoint during the execution of a program.
The breakpoint is identified by the number assigned to it(xx) and by the hexadecimal core location (xxxxxx) at which
it is encountered. Any DEBUG request may be issued as soon
as the keyboard is unlocked.
INVALID DEBUG REQUESTThe user has' specified a request which is not valid in the
Debug environment or which includes the wrong number ofoperands. On.ly the requests discussed in this section are
valid.
Requests:inienever the keyboard is unlocked in the Debug environment,
any DEBUG- request may be issued. The following rules apply
when issuing DEBUG requests;(1)
The parameters,. or operands
separated by one or more blanks.

i•ofeach request

must be(2)
The character-delete symbol"
all
may be used to delete
individual
characters
in
an
input
line
and
n
character-delete symbols delete the preceding n charactersin the line.
(3)
The line-delete symbol;, ~,' may be used to delete itself
and all
preceding characters in
an inputline.
Aline-delete symbol cannot be deleted by a character-delete
symbol.

(4)
All
operands longer
than
eight
left-justified and truncated on the right.
(5)
All entries
the DEF request .•in the DEBUG

DEBUG

characters

symbol table arearecreated by219

(6) The DEBUG requests can be abbreviated byminimum of two characters, except for X,-:{ ~RESTART •Below is a list of all
minimum abbreviation.
REQUESTS

valid

BR
CA

CS
DE

CS~

DEF
DUMP
GO
GPR
IPL
KX
ORIGIN

220

requests andMinimum Abbreviation

BREAK
CAW

~:~

DEBUG

specifying a
and

RETURN"

DU
GO

GP
IP
KX

OR

PS~

PS

RESTART
RETURN

REST
RET

SET

SE
ST

STORE
TIN

TI

X

X

DEBUG

their

BREAK
Format:I
I
I BREAK I
I
I

symbolid
hexlocid is any decimal number between 0 and 15 inclusive
symbol is a name which has been assigned (using the DEF
request) to the core address at which a breakpoint
is to be set
hexloc is the hexadecimal core location (relative to thecurrent origin) at which a breakpoint is to be set
Usage:
This request enables the user to stop execution of a programatspecific instruction
location called
breakpoints.
Issuing the BREAK request causes only one breakpoint to be
set.
separate BREAK requests must be issued for eachbreakpoint desired. A maximum of sixteen breakpoints may bein effect at any given time, and any attempt to set morethan sixteen is rejected .•The first operand of the BREAK request specifies theidentification number assigned to the breakpoint being set.
It must be a decimal number between 0 and 15 inclusive. If
an identification number is specified which is the same as acurrently set breakpoint the previous breakpoint is cleared
and the new one is set.
l•

The second operand of the BREAK request indicates the core
address at which the breakpoint is to be set. If thisoperand contains any non-numeric characters, the DEBUG
symbol table is searched for a matching symbol entry. If amatch is found, the breakpoint is set at the core address towhich the symbol name is assigned provided that address ison an even (halfword) boundary. If no match 1S found in the
DEBUG symbol table"
or if the second operand contains only',
numeric characters, the current origin as established by
the ORIGIN request is added to the specified operand and thebreakpoint is set at the resulting core address provided
that address is on a halfword boundary.
The DEBUG program sets a breakpoint by saving the contentsof the byte located at the core address specified by thesecond operand of the BREAK request,. This byte is replacedby the byte EX where x is the hexadecimal equivalent of the
breakpoint identifier specified in the first operand. For
the breakpoint setting to have meaning, the core address
indicated by the second operand must be the location of an
DEBUG - BREAK

221'"

operation code. Thus;, when the location is encounteredduring proqram execution/I a program interrupt occurs because
all.values EO through -EF are invalid operation codes andcontrol is transferred to the Debug environment. In DEBUG
the invalid operation cQde is recognized as a breakpoint,
the original operation code is replaced, and a message istyped ident'ifying the breakpoint encountered.
Figure 16 gives the procedure normally used for setting
breakpoints. The program is loaded into core and DEBUG isissued to transfer control to the Debug environment sobreakpoints may be set prior to execution.
After thedesired breakpoint have been set" RETURN should be issued toreturn control to the CMS Command environment. Issuing the
START command causes program execution to·begin. Whenever a
breakpoint is encountered, a message to that effect is
typed, control, is returned to the Debug environment, and the
keyboard is unlocked to accept any DEBUG request except
RE~URN.
Issuing the GO request causes program execution tocontinue from a specified location or the location at which
the _breakpoint had been set.•
Notes:
a. A breakpoint is cleared
program execution~

when it isencountered during

b. To obtain the core addresses of instructions at which
breakpoints are to be set"a listing of the program(s) inassembler language mnemonics should be used together with aload map. Assembler language mnemonics ar.e obtained in
Fortran listings by specifying the LIST option when the
FORTRAN command is issued; see Figure 17,. To obtain a load
map. the TYPE option is specified in the LOAD command as
shown in Figure 15.
c. If the address specified for a breakpoint setting is ona halfword boundary" the byte at that address may notcontain an operation code. It is up to the user to makesure that breakpoints are set only at .operation code
locations.
Otherwise{, the breakpoint is not recognized
during execution and may generate other errors by overlaying
data or some part of an instruction other than the operationcode.
d.
No breakpoints should be set below hexadecimal core
location 100 since this area is reserved for hardware'control words, and does not contain executable code.•e. If BREAK specifies a core address at which a breakpoint
is currently active,. the second breakpoint is set at thatsame location.
When encountered during execution., theidentification number of the most recently set breakpoint is
typed. The second time this core location is reached during
program execution,
the identifier ofthe second-mostrecently set breakpoint is typed" and so on,. When DEBUG' has
222

DEBUG - BREAK

been entered due to a breakpointi,
issuing the GO request
without an operand causes execution to begin at the location
at which the breakpoint was encountered. If more than one
breakpoint has been set at this location;, the addi tional
breakpoint (s·) causes DEBUG to be re-entered,.
Responses:
If the BREAK request is correctly issued, the keyboard is
unlocked following a carriage return, and the system isready to accept another DEBUG request.
INVALID DEBUG REQUES~This response indicates that some
operands have been specified.

numberother thantwo

INVALID ARGUMENT
This message indicates that the breakpoint identification
number specified in the first operand is not a decimal
number between 0 and 15 inclusive,. or the second operandcannot be located in the DEBUG symbol table and is not avalid hexadecimal number.. If the second operand is intended
to be a symbol, a DEF. request must have been previously
issued for that symbol; if not, the operand must specify avalid hexadecimal core location.
INVALID CORE-ADDRESSThe core location indicated by the second operand is uneven(not on a halfword boundary) or the sum of the second
operand and the current origin value is greater than theuser's virtual core size. If the current origin value is
unknown, i t may be reset to the desired value by issuing the
ORIGIN request.
REPLACES OLD BREAKPOINT xx AT xxxxxx
This response indicates that the BREAK request just issued
specifies a breakpoint identifier (xx) which is aSSigned toa currently active breakpoint. The old breakpoint ·(at core
location xxxxxx) is cleared and the new breakpoint is set.
DEBUG ENTERED

BREAKPOINT xx AT xxx xxx
This message is given when a breakpoint is encounteredduring program execution. xx is the breakpoint identifier
andxxxxxx is the core address of the breakpoint. After themessage' is typed., the keyboard is unlocked to accept any
DEBUG request exc1.!pt RETORN .•Examples:a. BREAR 1 leC
The current origin value is added to 18C and the byte at theresulting core. address is saved and replaced by the byte
'El'. Refer to Figure 16 where the origin is set to 12000,
and the instruction at breakpoint 1 is set is the second
from the· last instruction shown in Figure 17. Note that the
DEBUG - BREAK

223

load map indicates that program PRIME is loaded -at 12000.
Setting the origin to 12000"
therefore, means that thestatement locations shown in the listing of program PRIME
may be used in setting breakpoints. When breakpoint 1 isencountered during program execution;, the message
DEBUG ENTERED

BREAKPOINT 01 AT 01218C
is typed.
b.

BREAK 3 AM

The byte at the address assigned to symbol AAA is saved andreplaced by the eE3·. In Figure 16 a DEF request is issued
which assigns symbol AAA to location 1A4 relative to thecurrent origin of 12000. Breakpoint 3 therefore sets at core
address 121A4. as indicated by the message
DEBUG ENTERED

BREAKPOINT 03 AT 0121A4
which is typed when the breakpoint
program execution.

224

DEBUG - BREAK

is encounteredduringprintf prime listing
FORTRAN IV G LEVEL 0 MOD 0"
FILE PRIME
0001
0002
0003
0004
0005
0006
0001
0008
0009
0010
0011
0012
0013
0014
0015
0016
0011
0018
0019
0020

DATE = 67080
CAMBRIDGE MONITOR SYSTEMPRIME NUMBER PROBLEM
C
100 WRITE (6.8)
8 FORMAT (27B PRIME NUMBERS FROM 1 TO
50/2X,. IH1/2X. IB2/2X.,lH3)
101 1=5
3 A=l
102 A=SQRT(A)103 J=A
104 00 1 R=3"J;,2105 L=I/K
106 IF (L*R-I) 1,.2.,4
1 CONTINUE
107 WRITE (6,,5)1
5 FORMAT (I3)2 1=1+2
108 IF (50-I}7~4,3
4 WRrrE (6,9)
9 FORMAT (14H PROGRAM ERROR)
1 WRITE (6,6)
6 FORMAT (4H END)
109 STOP

PRIME

END

PRIME

FORTRAN IV G LEVEL 0,. MOD 0
FILE PRIMEFORTRAN IV G LEVEL O. MOD 0
FILE PRIMELOCATION
000000000004000008

STA NUM LABEL

OP
BC
DC

DC

OOOOOC

STM

00001000001400001600001A
00001E
00002200002400002800002C
00016C
00017000017400017800011C
00011E
000182000184000186LM
LR

Figure 11.

L

ST
STM

BCR

A36

DC
DC
DC
L

L

LM
MVI
BCR
A20

L

LR
LR

BAL

CAMBRIDGEPRIMECAMBRIDGE
OPERAND
15,12(0,1"5)
06D7D9C9
D4C54040
14,121,12 (13)2,.3.40 (15)4,1313,36(0,15)
13,8(0,4)
3,,4 .• 0(13)15,200000000
00000000
00000000
13,4(0,13)
14,12(0,13)
2,12,,28 (13)12(13),255
15,14
15.160(0,13)
12,13
13,4
111.64(0,.15)

DATE = 67080
MONITOR SYSTEMDATE = 67080
MONITOR SYSTEMBCD OPERAND

A4
A20
A36

IBCOM#

Sample output created by a FORTRAN command in which
the LIST and SOURCE options are specified.

DEBUG - BREAR

225

load prime (type)

PRIME#PRIME

AT 12000
AT 12000
IHCFCOMH AT 122A8
SAVAREA AT 13210
VFIOCSAT 13110
IBCOM#AT 122A8FDIOCS# AT 12364
IBCSSQRT AT 132EOSQRTAT 132E0
IBCFCVTH AT 13390
ADCON#AT 13390
INT6SW
AT 143F1
FCVEO
AT 13E3A
FCVLOAT 13612
FCVIO
AT 13948
FCVCO
AT 1403C
FCVAO
AT 13582
FCVZO
AT 134DCIHCFIOSH AT 14410
FIOCS'AT 14410
IBCTRCB AT 14FA8IHCUATBL AT 15220
R;T=0.39/0.60
debug
DEBUG ENTERED•••ori9in 12000
break 1 18c
def aaa 1a4
break 3 aaa
returnR;T=O.02
start
EXECUTION BEGINS •••DEBUG ENTERED

BREARPOINT 01 AT 01218C
90
PRIME NUMBERS

FROM 1 TO 50

123
DEBUG ENTERED

BREARPOINT 03 AT 0121A4
Fi9ure 16.

226

Sample procedure for setting breakpoints

DEBUG - BREAKCAWFormat:CAW
Usage:
This request causes the contents of the channel address word
which existed at the time DEBUG was entered to be typed at
the terminal. The CAW. specifies the storage protection key
and the core address of the first channel command word
associated with the next or most recent START I/O,. The CAW
located in hexadecimal core location 48, is saved at thetime DEBUG is entered. It has the following format:
Bits

Contents

0-3

Protection key which is matched with a key in storage
whenever reference is made to main storage.

4-7

Not implemented; currently set to zeros.

8-31

Command address:, indicating
the hexadecimal core
location of the ~irst channel command word associatedwith the next or the most recent START I/O.

For a further discussion of the channel address word:, referto the IBM manual, IBM System/360 Principles of Operation.
Responses:
If the request is issued correctly" the contents of thechannel address word are typed in hexadecimal representation
at the terminal and" following a carriage return, thekeyboard is unlocked to accept another DEBUG request.. See
Figure 18 for an example of· response to the CAW request,.
INVALID DEBUG REQUESTThis response to the CAW request indicates that one or more
operands have been specified. Reissue the request in its
correct format.

DEBUG - CAW

227

CSW
Format:I

CSW

Usage:
This request causes the contents of the channel status word
which existed at the time DEBUG was entered to be typed at
the terminal. The CSW indicates the status of a channel oran input/output device or the conditions under which an I/O
op~ration has
been terminated.
The CS~ is formed in thechannel and stored in hexadecimal core location 40 when an
I/O interruption occurs.
If I/O interruptions have been
suppressed, the csw is stored when the next START 1/0 TEST
1/0 or HALT I/O instruction is executed.
The CSW is saved
when DEBUG is entered and has the following format:
l,

1•

1,

contents
0-3

Protection key moved from the CAW and used toindicate the protection key under which I/O wasstarted.

4-1

Not implemented; currently set to zeros.

8-31

Next command address--a pointer to the core locationeight bytes greater than the address of the lastchannel command word executed.

32-47

Status bits indicating the conditions in the device
or the channel that caused the CSW to be stored.

48-63

Residual count indicating the difference in thenumber of bytes specified in the last executedchannel command word and the number of bytes whichwere actually transferred.

Responses:
If the request is issued correctly, the contents of the CSW
are typed at the terminal in hexadecimal representation. A
carriage return is then issued and the keyboard is unlocked
to accept another DEBUG request. For an example of responseto the csw request see Figure 18~
INVALID DEBUG REQUESTThis response to the csw request indicates that one or more
operands have been specified. Reissue the request in its
proper format.

228

DEBUG - CSWDEFFornlat:DEF

symbol hexloc < bytecount > I
4symbolI

is the name to be assigned to the corederived from the second operand. hexloc

hexloc isaddress

the hexadecimal core location. relative to thecurrent origin" to which the name specified in thefirst operand ~s to be assigned

bytecount is a decimal number between 1 and 56 inclusive
which specifies the length attribute (in bytes) of
the symbol specified in the first operand.
usage:The DEF request allows the user to assign a symbolic name toa specific core address and to refer to that address inother DEBUG requests by the assigned name. The symbol nameis specified as the first operand of the DEF request. It
may be from one to eight characters in length, must containat least one non-numeric character. and the first characterof the symbol name should not be an asterisk. Any namelonger than eight characters wi11 be left-justified andtruncated on the right.
The second operand specifies a hexadecimal number which isadded to tne current origin as established by the ORIGIN
request. The sum of these two values is the core address towhich the symbol name is assigned.
The third operand is optional and. if given, must specify adecima.l number between 1 and 56 inclusive..
This number isthe length attribute in bytes of the symbol name.
If thethird operand is omitted" a default attribute of four bytes
is assigned.
When DEF is issued,. an entry is made in the DEBUG symbol
table indicating the symbol name, the core address to which
it is assigned, and the length attribute of the symbol.
Symbols remain defined until a new DEF request is issued forthem or until the user obtains a new copy of CMS by issuingan IPL request in the Debug environment or in the control
Program environment.
If DEF is issued spe~ifying
a symbol that has beenpreviously defined. the previous core address is replaced by
the more recent core address for that symbol in the DEBUG
symbol table. DEF requests specifying additional symbol
names for core locations to which a symbol name has already
DEBUG - DEF

229

been assigned cause additional entries in the DEBUG symbol
table so that multiple symbols may be assigned to the same
core address.
Notes:
a. Only sixteen symbols may
environment at any given time.

bedefined

in

the

Debug

b. Issuing a new ORIGIN request does not affect core
addresses to which previously defined symbols are assigned.
c. Symbols assigned using DEF are
the Debug environment.

defined for use

only in

Responses:
If DEF is issued correctly. a carriage return is given andthe keyboard is unlocked to accept another DEBUG request .•INVALID DEBUG .REQUESTThis response to DEF indicates that less than two or morethan three operands have been specified~Reissue therequest in its correct format.
INVALID ARGUMENT
This message indicates that the name specified in the first
operand contains all numeric characters. the second operandis not a valid hexadecimal number,. or the third operand is
not a decimal number between 1 and 56 inclusive.
INVALID CORE-ADDRESSThis response is given when the sum of the second operandand the current origin is greater than the user·s virtual
core size. If the current origin value is unknown., reset itto the desired value by issuing the ORIGIN request andreissue the DEF request.
16 SYMBOLS ALREADY DEFTNED
If this message is given, the DEBUG symbol table has been
filled and no new symbols may be defined until the current
definitions ~re cleared by obtaining a new copy of eMS.
However;, existing symbol may be assigned to a new core
lopation by issuing another DEF request for that symbol.
Examples:a. DEFINE IN1 12F5A
The current origin value is added to 12F5A and the symbol
IN1 is assigned to the resulting hexadecimal core address.
The default length attribute of 4 is assigned to symbol IN1,
and an entry for IN1 is made in the DEBUG symbol table.
b. DEFINE K 13 l2
The currently defined or1g1n is added
value 13, and the resulting address is
230

DEBUG - DEF

to the hexadecimalassigned the symbol

K. An entry for R is made in the DEBUG symbol
its length attribute is 12 bytes.

DEBUG - DEF

table. and

231

DUMP
Format:symbol 1
DUMP

ident

< hexloc 1osymbol 2
hexloc 2>

*

3

,
I

I
I

ident indicates the name by which the printout is identified
symbo11 is a name assigned (using DEF) toat which the dump is to begin
hexlocl is

the hexadecimal core location., relative to thecurrent origin,. at which the dump is to begin

symbol2 is a name assigned (using DEF) toat which the dump is to end
hexloc2 isthe core address

the core address

the hexadecimal core location,. relative to thecurrent origin~ at which the dump is to end* indicates that the

dump is to end at thethe user·s virtual core

last address of

Usage:
This request is used to dump the contents of all or part ofthe offline printer. The
the user's virtual core on
information has the heading ·ident FROM symbol1 TO symbol2"
where ident is the identifier specified as the first operandof the DUMP request.
The second and third operands specify the portion of core
which is to be dumped, and are optional. If omitted, thecore address specified in the most recent DUMP request is
used or, if no previous DUMP request has been issued, oneword (four bytes) of core is dumped starting at location o.
If the second and third operands are specified, the core
addresses to which they referare determined in thefollowing way.
If thesecond operandcontains any
non-numeric character, the DEBUG symbol table is searched
for a matching symbol entry. If a match is found the core
address to which that symbol name is assigned is used as theaddress at which the dump is to begin. If no match is found,or if the operand contains only numeric characters, thecurrent origin as established by the ORIGIN request is added
to the specified operand.
The resulting core address isused as the beginning address of the dump, provided it is
not greater than the user's virtual core size.
The core
address at which the dump is to end is given by the third
operand of the DUMP request.
If an asterisk is specifiedl,232

DEBUG - DUMP

for this operand. all of core from the starting address tothe end of core is dumped.
If an asterisk is not specified
as the third operand. the same procedure is used todetermine the ending address of the dump as that describedabove for the starting address.
Both addresses must bewithin the address range of the user's virtual core, and theaddress specified in the third operand must be greater thanthat specified in the second.
The first three lines of output from the DUMP request givethe contents of general-purpose registers 0-7 and 8-15, andthe floating-point registers 0-6.
Thereafter, the contentsof the specified portion of core are given, 32 bytes perline. The core address of the first byte in the line isgiven in the left-most column of the dump and is always aneven doubleword boundary,.
The alphameric interpretation for the 32 bytes is pri,nted to
the right of the specified hexadecimal locations.
Responses:

A carriage return is issued and the keyboard is unlocked toaccept another DEBUG request.
The requested information isprinted offline as soon as the printer is available,.
INVALID DEBUG REQUEST
No. two" or more than three operands have been specified in
the DUMP request. Reissue the request,. specifying one or
three operands.
INVALID ARGUMENT
This message is given if the address specified by the third
operand is less than that specified by the second operand or
the second and/or third operands cannot be located in the
DEBUG symbol table and are not valid hexadecimal numbers.
If either operand is intended to be a symbol, a DEF request
must previously have been issued for that symbol: if not.
the operand must specify a valid hexadecimal core location.
INVALID CORE-ADDRESSThe hexadecimal number specified in the second or third
operand" when added to the current origin. is greater thanthe user's virtual core size. If the current origin value
is unknown reset it to the desired value by issuing ORIGIN
and reissue the DUMP request.
i,

Example:DUMP NEUC 0000 05FO
The contents of core from locations 0000 to 05FO(each plus
the current origin) are printed on the offline printer andidentified by the heading NEUC. See Figure 19 for a sampleof this output, where the origin value is o.

DEBUG - DUMP

233

SEOC:PROII

000 TO

05FO

GR C-7
Gli 8-F'
PPREGS

ClIC5C2E400000004
OOOOOOCC

00009610
00000100
00000000

00009B10
C4C5C2E400000000

00000000
C74C4040
00000000

00000778
OCOOA3BO
00000000

000029AC
00000l.l0
00000000

000001:<0000026C!
00000000

000(0048
000013BO
00000000o CO 00 0
000020oece4e000060o CO 08 0
oeOCA 0o OOOCOOCOCEC

800094CO
000400CA
00OOO2ce
00040000OOOODOO\)
ooooocec
00003000OOOOOOOC

60009580
60009516
DC 000000
00002288
00000000
00000000
00000000
00000000

C 0000002
OOCOOO 05
0000A048
00C40000
00000000
00000000
00000000
00000000

60000050
6COODOC200000000OOOOBBOOOOOOOOOC
00000000
00000000
0000CFA2

020n81000000000
000 1f69E
00000000
ClIC5C2E400000000CCOOOOOO
010058CO

000013BO
00000000
00000000
0000BC2C
c14C4040
00000000
00000000
00EC07FC

PFOtOCee
FF040009
00000000
0004CO(C00016D1EOOOOOOOC
00000000
00000000

8003F29S
0000223EOOOOBDOO
OOCC05.1 C
00000000
00000000
00000000
00000000

0001CC
000120
OC0140000160OC01800001 AO
o CO 1C C
0(01EO
0002000(0.20o C0240000260000001FC
40001561
00OC29AC
00003 AAO
c 3D 30906
00009386
oooooooe
0000019C
03000000
CCOO0238
0407110 D500000000

00000000
OCOCA76C
00000009
C00400CA
00()09 E10
4COO57E8
OGOOOOOO
00000000
C3D6DSF1
00J0023C
00000000
OCOCOOOC

00040000
00009B10
900015611
400051P4C3D3D9D6000011BO
00000000
00000000
00000000
000026CE
00000000OCOOOOOOOOOCCCCC
00000000
C74CQCQC
000057f8
000C5CA8
400C9511C
0003EOOOOAooe • .:£C3D&ISf1
ooocecce
OOOCCCCC
00000000

CCO()OOCA
00000778
000CA438
000051 P80003E8B8OCOCOO06
00012000
6CCCOC82
00000000OA82CIIE4
enccoeoc
00000000

F04BFOF200000000
00000000

40F2P04B
00000000OOOOOOOC

P5P04ff500000000
oooocecc

F3151117
00000000
ccccocea* ••• D•• B. T.0.01.0.02 20.50.53 ••• **0.3& •••••••••••••••••••••••••••• *00000000
C4E2D2F 1
OCOCOOOO
00000000
C4E2D2FII
01060000
00000&10
CCOC19C0
00OO049C
CC0031FO
CC00237C
00000000eCFFFFFI'
00000& AS
98030038
ce22111 FO
5000078.F

000003PII
00001050
D9C4 D9 F1
o 180000C
OC001050
C3D91l3f1
00000400
00009EF600001A9C
000032P80000011e
00000000
00003810
00000000
41EOCO&O
C08!l4190
8756c04S

0000C3F90191CCC600000000
E3C1DiF100000000
ccocecec
OOOO;;C1S
000014CO
000CC4F90000SES800000£10
COOCCCCC
00003880
0000EAC8
98I1BCCF:<
C0409180
QOIlOCC':A

OC040000
C4f<I:2F2000 [0000
OOC C0000
C4!2£2F500000000
OOCC9ECO
000034C8
OOCCOOOO
000C051D
0000053D
000CAC78
00000571)
OCCCOOOO
1QQC12S950020789
Q7FCCCEA* ••••••••••••••••••••••• 4 ••• S •••• ** •••• COIl1 •• B••••• DSK1 •••••••• DSK2** •••••••• DSK3 •••••••• RDR1 •••••••• **PCH1 •••••••• PBN1 •••••••• IIP1 •••••* •••• IAP~ •••••••• DSK4 •••••••• D SK5*
* •••••••• DSK6 •••••••• CR!1 •••••••• ** •••• COIl1 •••••••••••••••••••••••• ** ••• 8 ••••••••••••••••••• 6 ••••••• H** ••••••• C••••••••••••••••••• 9 •••• •* •....••..•....•.••• 0 ••• 8 •••••••••

0002CO
OC02EO
00030.0o Co 3E C
00040.0
oe042eOC0440000 .. 60
0(04800004AO
OG04COo C0 4E 0
o C050 0
o CO 52 0
J CO ~ II 0
J CO 560

oco ~ 8 C

0005 AO
o CO ~c 00CO':EO

000110000 00012000 00012000
OO()O A56A 0000A238 C4C5C2E400000120 OCOOOO09 0000A3S0000026CE OOCOOOOC OOOOOOCO
0OOO1J9C 00000000 00005816
00012000 00(09508 OCOOOOO 1
0003POOO 00000000 00000000
0OOOO1E5 00020000 C3D6D5E220000001 £6C1C9£3 '104C4C4C
000500CO 00000000 OJOOOOOO
C5EIIC340 FOPOf040 POf5C6FO:>0000000 00000000 00000000*** DUPL.ICATE ceRE LOCATICNS ***OOOOJ2C4 g:i1At95E 40 E37EPO 4BPOf161
F04BF 3FE 15171700 00000000 00000000
00000000 OOOOOOCO 00000000 00000000*** DUPLICATE CORE LOCATION S • **OOOOOOCC' 00000000 00000000 OJOOOOOO
00091)000
C3 D6 D5F 1 0000C2EO C 19CGCC8
oe001 e5C 01920000 C4E2D2P3 OCOC1C50I)OOCOOC( OOOEOOOO
C7C)C8F1
0709 D5 P101810000
E3c1C7F2 OOOOCOOC oeoooooo
00001C50 019COOO8 C4 E2D2P6 00001050
OCuO()OOO C3 &6D5F1
0OO011EO 00009774
ooeo HF8 00002C98 OOGOBBBC OCG019CO
000C9828 00010408 00001A28 00000&00
00003504 oaaot! [;[0 00001EAO OCoeOE3c
OOOC19FO 00000525 OOCO 93Ab 00001(i60OeO(0778
00000545 000057cA OCJ010FF80000CC88 00009810 0000C569 0OO09DFC
0000 1A 58
00000585 OOOOBAEC 0000 BAFIISOCOOOO(i 05c0900 F C162D203 C1920000
4180C02C
41FOC05c 49409000 078F87SA
494C50ce 0701'8756 CJ34585J CuFb4940

Figure 19'.

234

* •........••...••........•..... ~. •* ..................................

* .........•........ 6 .............. ** ................................•........•* ................. DEBUG* ..........................................
*........................................ ** ................................... *..... 0 ..............................................

* ••••••••••• LEBO •••••••••••••••• ** •••••••••••••••••••••••• G.......

*CLRO •••••••••••••••• CLBO •••••• Y.** ................. •• r ••••.. ..... ** •••••• 0 ••••••••••••••••••••••••• ** .•.••.. V•••• COIiS •••••••••••••••••* •••••••• liAIT

COR1 •••• COR1 •••• ** ....•...••.......•......•....• DU·*IIP BEOC 000 05fO •••••••••••••••• *•................................ ** ..................................

* ..• u•••••••••••••••••••••••••••• ** ••••••••••••••• 8 •••••••••••••••••*......•..•...•. 0 •••••••••••••••• *•••••••••••••••• 4 •••••••• e_o•••••••* •••••••• A.I.& •••••••••••••• 2 • • • ** ••••• 0 ••• •• •••••• • 0 ••••• •.•.•. *••• 0 •• **. ••••••••••• 6.

. ........

Sample DUMP output from the offline printer

DEBUG - DUMP-

* ..................•• •• 11 ••• 5 ••• 8*

GO

Format:GO< symbol>
hexlocsymbol is a name that has been assigned by the DEF request
to the core address at which execution is to begin
hexloc is

the hexadecimal core location, relative to thecurrent origin~ at which execution is to begin

Usage:The GO request
causes the user toleave the Debug
environment and begin execution at a user-specified address
or at the address contained in bits 40-63 of the old PSW for
the interrupt which caused DEBUG to be entered. This PSW issaved when DEBUG is entered,. and is loaded as the current
PSW when GO is issued,. If an operand is specified in the GO
request r,
the instruction address portion of the PSW isaltered to contain the address indicated by that operand
before the PSW is loaded.
The core address indicated by the GO operand is determinedin the following
way.
If the operandcontains any
non-numeric characters. the DEBUG symbol table is searched
for a matching symbol I.!ntry. If a match is found" the core
address to which that symbol name is assigned is used as thelocation at which execution is to begin. and is moved to the
saved old PSW. If no match is found in the DEBUG symbol
table, or if the operand contains only numeric characters,
the current origin (as established by the ORIGIN request) isadded to the specified operand and the resulting address
moved to the PSW provided it is not greater than the user's
virtual core sizl.!.
1,

Prior to loading the PSW. the general-purpose registers,
channel address word, and channel status word are restored
to their contents as they existed when DEBUG was entered,or, if they have been modified by the user in the Debug
environment, to their modified contents.
The saved old PSW
is then loaded to become the current PSW, and execution
begins at the specified instruction address.
Notes:
a. GO should not be issued without
Debug environment has been enteredexternal" or program interrupt.
h. lihentime inan operand unless thedue to a . breakpoint,

an operand is specified, GO may be issued at any
the Debug environment, except when DEBUG has been

DEBUG - GO235

entered toit.

set breakpoints ina program prior

to startingc. If an operand is specified in the GO request, the address
to which it refers must be the core location of an operationcode.
Responses:
If GO is issued successfully, there is a carriage return andexecution coninues from the address contained in the loadedpsw.

INVALID DEBUG REQUESTThis response ~9:ndicates that more than one operand has been
specified in the ',GO request. Reissue the GO request in its
correct format.
INVALID ARGUMENT
An operand specifaed in the GO request cannot be located in,the DEBUG symbol table and is not a valid hexadecimal"number. If the operand is intended to be a symbol. a DEF
request must have been previously issued for that symbol: if
not!. the operand must specify a valid hexadecimal core
location.
INVALID CORE-ADDRESSThe address at which execution is to begin is not on a
halfword boundary (indicating that an operation code is not
located at that address) or the sum of the GO operand andthe current origin value is greater than the user's virtual
core size. If the current origin value is unknown, it may
be reset to the desired value by issuing the ORIGIN request.
INCORRECT DEBUG EXIT
The GO request has been issued without an operand when DEBUG
dhad not been entered due to a breakpoint, external"
or
program interrupt. The IPL ,• KX, or RESTART requests may be
issued, GO may be issued with an operand, or RETURN may be
issued if DEBUG had been entered via the DEBUG command.
Examples:a. GO
The old PSW for the interrupt that caused DEBUG to beentered is loaded as the current PSW, and execution begins
at the address specified in bits 40-63 of that PSW,.
b. GO INN

The DEBUG symbol table is searched for symbol INN and the~;address to which that symbol is assigned is loaded into bitst.l,{~·O:-63 of the old PSW prior to loading it as the current psw •., Control passes from the Debug environment and execution
begins at the core address to which symbol INN refers.

236

DEBUG - GO

c. GO 12345
The current or1g1n is added to location 12345 and theresulting address placed in bits 40-63 of the old PSW prior
to loading it as the current psw. Control is transferredfrom the Debug environment and execution begins at the
specified address.

DEBUG - GO

237

GPR

Format:GPR

reg1 < regN > I

reg1 is a decimal number from 0-15 inclusive, indicating thefirst or only general-purpose register whose contents
are to be typed.
regN is a decimal number from 0-15 inclusive, indicating thelast general-purpose register whose contents are to be
typed.
Usage:The GPR request is used to inspect the contents of one ormore general-purpose registers as they existed when DEBUG
was entered. If only one operand is given, the conten~s ofthe specified register are typed at the terminal..
If twooperands are given, the contents of the registers specified
by the first throuqh the second operand, inclusive, aretyped.
The first and second operands must be decimal numbers from
0-15, and the second operand must be greater than the first.
Responses:
If the request is issued correctly~ the contents ,of theregister (s) specified are typed at the terminal{, one perline. Following a carriage return, the keyboard is unlocked
to accept another DEBUG request.
INVALID DEBUG REQUESTThis message indicateshave been specified.
format.

that none or more than two operands
Reissue the request in its proper

INVALID ARGUMENT
This response is given if the operand(s) specified are notdecimal numbers between 0 and lSi, or if the second operandis less than the first.

Examplep:

a. GPR 8
The contents of general-purpose register 8 as it existed
when DEBUG was entered are typed at the terminal.
See
Figure 20.
b. GPR 5 15
The contents of general-purpose registers 5 through 15,
inclusive, are typed as they existed when DEBUG was entered,.
238

DEBUG - GPR

See Figure 20.
gpr 8002AIA88
gpr 5 15000A5DD8002AIA88
00009B38
002AIA88
00000100
80009670
B0009FBA
600095C2000llD40
0000550C
000095B8

Figure 20.

Examples of the GPR request

DEBUG - GPR

239

IPL
Format:
IPL
Usage:The IPL request causes control to transfer from the Debug
environment to the eMS Command environment.
IPL may be
issued any time the keyboard is unlocked in the Debug
environment regardless of the- circumstances by which DEBUG
is entered.
Responses:
CMS ••• VERSION nn LEVEL mm
This indicates that IPL has successfully executed andcontrol has passed from the Debug environment to the CMS
Command environment. The keyboard is unlocked to accept any
CMS command.
INVALID DEBUG REQUESTThis indicates that one or more operands have been specified
in the IPL request. Reissue the request in its correct
format.

240

DEBUG - IPLKXFormat:KX

Usage:The KX request closes all open files and I/O devices.
updates the user·s file directory, and reIPL's CMS.. This
request may be issued whenever the keyboard is unlocked in
the Debug environment:. regardless of the circumstances bywhich DEBUG is entered,.
Responses:
KILLING CMS EXECUTION • • •CMS ••• VERSION nn LEVEL mm
This indicates that RX has executed,. eMS has reIPL' ed. andand control has passed to the CMS command environment. The
keyboard is unlocked to accept any CMS command.
INVALID DEBUG REQUESTThis indicates that one or more operands have been specified
in the KX request.
Reissue the request in its correct
format.

DEBUG - KX

241

ORIGIN
Format:ORIGINI symbol
I hexloc

1
1

symbol is any name that hasby the DEF request

been assigned to a core address

hexloc is any hexadecimal core location between 0
end of the user·s virtual core

and theUsage:
This request allows the user to specify an origin, or baseaddress. which is added
to the hexadecimal locations
specified in other DEBUG requests.
For example, the ORIGIN
request enables users to specify instruction addresses
relative to program load points, rather than to 0, while
operating in the Debug environment. If the ORIGIN request
is not issued, all hexadecimal locations specified in DEBUG
requests are assumed to be relative to 0,.
lihen ORIGIN is issued!. the origin setting is determined in
the following way.
If the ORIGIN operand contains any
non-numeric characters!. the DEBUG symbol table is searched
for a matching symbol entry. If a match is found, the core
address to which that symbol name is assigned becomes thenew origin setting.
If no match is found in the DEBUG
symbol table, or if the operand contains only numericcharacters the address specified in the operand becomes theorigin setting.
j,

Any origin set by an ORIGIN request remains in effect until
another ORIGIN request or a RESTART request. is issued, or
until the user obtains a new copy of eMS. Whenever a new
ORIGIN request is issued, the value specified in thatrequest overlays the previous origin setting. If the user
obtains a new copy of eMS or issues a RESTART request, theorigin is set to 0 until a new ORIGIN request is issued,.
Responses:
If the request is issued
return and the keyboard isrequest.

correctly, there is a carriage
unlocked to accept another DEBUG

INVALID DEBUG REQUESTThis response indicates that the wrong number of operands
have been specified.
One and only Qne op~rand must be
specified.

242

DEBUG - ORIGININVALID ARGUMENTThe operand specified in the ORIGIN request cannot belocated in the DEBUG symbol table and is not a valid
hexadecimal number. If the operand is intended to be asymbol. a DEF request must have been previously issued forthat symbol: if not t•
the operand must specify a valid
hexadecimal core location.
INVALID CORE-ADDRESSThe address specified by the ORIGIN operand is greater thanthe user·s virtual core size.
Examples:a. ORIGIN 12000
The origin is set to the hexadecimal value of 12000. 12000
is added to all hexadecimal locations specified in other
DEBUG requests and the resulting core address is referenced.
b. ORIGIN XYZ5
The absolute address assigned to symbol XYZ5 (provided anentry for XYZ5 exists in the DEBUG symbol table) becomes thenew origin
setting.
This setting
is added
to allhexadecimal locations specified in other DEBUG requests:. andthe resulting core address is referenced.

DEBUG - ORIGIN

243

PSW
Format:PSW
Usage:
This request types the contents of the old program status
word for the interrupt that caused DEBUG to be entered. If
DEBUG was entered due to an external interrupt" the PSW
request causes the contents of the external old PSW to be
typed at the terminal. If a program interrupt caused DEBUG
to be entered, the contents of the program old PSW are
typed.
If DEBUG was entered for any other reason, thefollowing is typed in response to the PSW request:
01000000xxxxxxxx
where the 1 in the first byte means that external interrupts
are allowed and xxxxxxxx is the hexadecimal core address of
the DEBUG program.
The fields of the PS~ follow.
Bits

contents

0-1 System mask, indicating the sources which are allowed tointerrupt the cPU.
8-11

Protection key, used to determine
location may be written into.

12

ASCII flag, indicating whether ASCII-8 oris to be used.

13

Machine check flag,machine check occurs.

14

Wait state flag,
the wait state.

15

Problem state flag, set to 1 when the machine isoperating in
the problem state rather
than thesupervisor state.

16-31

Interrupt code, showing the source of the interrupt
for external interrupts or the cause of the interrupt
for program interrupts.

32-33

Instruction length code., indicating the length;, in
halfwords, of the instruction being executed when aprogram interrupt occurred (unpredictable for externalinterrupts).

34-35
244

which is

set

if

to

which is set to 1 when

Condition code,which

reflects

DEBUG - PSW

a givencore

EBCDIC code
1 wheneverathe CPU is in

the resultofaprevious arithmetic. logical, or I/O operation.
36-39

Program mask, indicating whether
program exceptions
are allowed tointerrupts.

or notcause

variousprogram

40-63

Instruction address, giving the location of the next
instruction to be executed for program interrupts' or of
the instruction last executed for external interrupts.

For a further discussion of program status words and their
IBM
System/360
use.,
refer
to
the
IBM
manual/.
Principles of Operation.
Responses:
If the request is issued correctly., the contents of theappropriate PSW are typed in hexadecimal representation at
the terminal, followed by a carriage return and an unlocked
keyboard. See Figure 18 for an example of response to the
PSW request.
INVALID DEBUG REQUES~This response indicates that the user has specified one ormore operands in the PSW request. Reissue the request in
its correct format.

DEBUG - PSW

245

RESTART
Format:RESTART
Usage:RES~ART
request is equivalent to the IPL request.
RESTART
causes control
to transferfrom theDebug
environment to the CMS Command environment. RESTART may be
issued any time the keyboard is unlocked in the Debug
environment, regardless of the circumstances by which DEBUG
has been entered.
~heIssuing RESTART causes a new copy of the CMS nucleus to bebrought into core from the system disk.
This new copy
overlays the user·s former copy of the nucleus. causing all
symbols which had been previously defined by DEF requests to
be cleared from the DEBUG symbol table.
Responses:
CMS ••• VERSION nn LEVEL mm
This response indicates that
RESTART has successfully
executed and control has passed from the Debug environment
to the CMS Command environment. The-keyboard is unlocked toaccept any CMS command.
INVALID DEBUG REQUESTOne or more operands have been specified in the RESTART
request. Reissue the request in its correct format.

246

DEBUG - RESTARTRETURN
Format:
RETURN
Usage:-rhis request is a meansof exitting from the Debug
environment to the CMS Command environment. It should be
used only when DEBUG has been entered by issuing the DEBUG
command.
When RETURN is issued" the general-purpose registers arerestored with the information they contained at the time
DEBUG was entered or, if the user has specified a change tothis information while in the Debug environment, with thechanged information. In either case, register 15, the error
code register, is set to zero. A branch is then made to theaddress contained in register 14, the normal CMS return
register. If DEBUG is entered by issuing the DEBUG command,register 14 contains the address of a central CMS service
routine and control transfers directly to the CMS Commandenvironment ..
Responses:
R;T=xx.xx/XX.XX
The Ready message followed by a carriage return and an
unlocked keyboard indicates that the RETURN request has
successfully executed and control has transferred from the
Debug environment to the CMS Commend environment. After thismessage is typed, the keyboard is unlocked to accept any eMS
command.
INVALID DEBUG REQUESTThis message is given if one or more operands have been
specified in the RETURN request. Reissue the request in its
correct format.
INCORRECT DEBUG EXIT
If DEBUG is entered due to a program or external interrupt,
a breakpoint, or an unrecoverable error, this message istyped in response to the RETURN request. To exit from the
Debug environment under the above circumstances,issue GO
with an operand, IPL"
or RESTART. The GO request may be
issued with no operand if DEBUG has not been entered due toan unrecoverable error.

DEBUG - RETURN

241

SET
Format:SETI CAW hexinfo
I CSW hexinfo
I PSW hexinfo
I GPR reg<hexinfo><hex info>
hexinfo <hexinfo>

CAW

the specified information is to be stored in thechannel address word that existed at the time DEBUG
was entered.

csw

the specified information, is to be stored in thechannel status word that existed at the time DEBUG
was entered.

PSW

the specified information is to be stored in the oldprogram status word for the interrupt that caused
DEBUG to be entered.

GPR

the specified information is to be stored in thegeneral-purpose register given as the second op~rand.

usage:The SET request is used to change the contents of control
and general-purpose registers which are moved from theirnormal locations when the DEBUG environment is entered. The
contents of these registers are restored when control
transfers from DEBUG to another environment.
If register
contents have been modified in DEBUG the changed contents
are restored.
t,

The register that is to be modified is specified as thefirst operand of the SET request"
and the information to beinserted in this register is given in hexadecimal format in
the hexinfo operand(s). Each hexinfo operand should be from
one to four bytes (that is, two to eight hexadecimal digits)
in length. If an operand is less than four bytes andcontalns
anunevennumberofhexadecimal
digits(representing half-byte information) the information isright-justified and the left half of the uneven byte is set
to 0;, as shown in Example b. If more than eight hexadecimal
digits are specified in a single operand. the information isleft-justified and truncated on the right, as shown in
Example d.
The number of bytes that can be stored. using the SET request
varies depending on the form of the request.
With the CAW
form, up to four bytes of information may be stored.. With
the CSW"
GPR,
and PSW forms,
up to eight bytes of
information may be stored, but these must be represented in
two operands of four bytes each.
When two operands of248

DEBUG - SET

----------------information are specified, the information is stored inconsecutive locations" even if one or both operands containless than four bytes of information, as shown in Example b.
The contents of registers that have been changed using the
SET request are not typed after the request has been issued.
To inspect the contents of these registers, the CAW" CSW.
PSW, or GPR requests are issued as needed.
Figure i7
contains examples of issuing these requests both before andafter SET has been issued.
Responses:
If the request is issued correctly"
a carriage return isissued and the keyboard is unlocked to accept another DEBUG
request.
INVALID DEBUG REQUESTThis response indicates that the wrong number of operands
have been specified. If the CAW is set, two operands must be
given. To set the CSW or the PSW, two or three operands are
required. TO set a GPR. three or four operands must be
given.
INVALID ARGUMENT
This message indicates that either the first operand is not
CAW, CSW, PSW or GPR. the first operand is GPR and thesecond operand is not a decimal number between 0 and 15
inclusive, or one or more of the hexinfo operands does notcontain hexadecimal information.
Examples:a.
SET CAW 1100
This example causes the two-bytes 1100 to be placed in thefirst, two bytes of the channel address word that existed
when DEBUG was entered.
See Figure 18. This new channel
address word is restored when an exit is made from the DEBUG
environment.
h.
SET CSW 001 00FF81
Since an uneven number of bytes is specified in the second
operand, a zero is placed in the left-frost half-byte" giving
0001. These two bytest, together with the three bytes givenin the third operand are placed as a single five-byte field
into the csw that existed when DEBUG was entered.
See
Figure 18.
This new channel status word is restored whenleaving the DEBUG environment.
c.
SET PSW 01000000 00012036
The contents of the entire program status word for theinterrupt that caused DEBUG to be entered are replaced bythese eight bytes of information.
See Figure 18. This PSW
becomes the current psw when an exit is made from the DEBUG
environment.

DEBUG - SET

249

d.
SET GPR 5 000012345
The contents of general-purpose register 5 are replaced with
the information given in the ,third operand. Since thisinformation is greater than eight hexadecimal digits. it isleft-justified and 'truncated on, the right. giving 000.012311.
See Figure 18. General-purpose register 5 contains this new
information when the general~purpose registers are restoredprior to leaving the DEBUG environment.

caw
00010FE8
set caw 1100
caw
11000FF8
csw
00010FF8OC000005
set csw 001 00ff8l
csw
000100FF81000005
psw
01000000000095B8
set psw 01000000 00012036
psw
0100000000012036
gpr 500007F68
set gpr 5 0000123Q5gpr 500001184
Figure 18.
Examples of the SET request, using otherrequests as appropriate to inspect contents both before andafter SET is issued

250

DEBUG - SET

STORE

Format:syrobol
STORE

hexinfo<hexinfo

hexlocsymbol is<hexinfo»I,Ia name assigned by the DEF request to the core
address at which the first byte of specified
information is to be stored

hexloc is the hexadecimal location relative to the current
origin where the first byte of information is to
be stored
hexinfo is any hexadecimal information, four bytes or lessin length, that is to be stored starting at theaddress specified by the first operand
Usage:
This request allows the user to store information in any
virtual core location. The location at which the information
is to be stored is specified by the first operand and isdetermined in the following way.
If the first operandcontains any non-numeric characters, the DEBUG symbol table
is searched for a matching symbol entry. If a match isfound,
the core address to which that symbol name isassigned is used as the address at which information is to
be stored. If no match is found in the DEBUG symbol table,
or if the first operand contains only numeric characters,
the current origin is added to the specified operand and theresulting core address is used, provided it is not greaterthan the user·s virtual core size.
The information to be stored is given in hexadecimal format
and is specified in the second through the fourth operands.
Each of these operands is from one to four bytes (that is,
two to eight hexadecimal digits) in length.
If an operandis less than four bytes in length and contains an unevennumberof hexadecimal
digits (representing
half-byte
information), the information is right-justified and theleft half of the uneven byte is set to 0 as shown in Example
b. If more than eight hexadecimal digits are specified in asingle operand, the informationis left-justified andtruncated on the right as shown in Example b.

A maximum of 12 bytes may be stored at one time using the
STORE request.
This is done by specifying three operands
after the location operand, each of which contains four
bytes of information. If less than four bytes are specified
in any or all of the operands, the information given isarranged into a string of consecutive bytes, and that string
DEBUG - STORE251

is stored starting at the location given in the first
operand. Stored information is not typed at the terminal.
To inspect the changed contents of core after a STORE
request, issue an X request as shown in Figure 21.
Responses:
If the request is issued correctly,
given and the keyboard unlocked torequest.

a carriage return is
accept another DEBUG

INVALID DEBUG REQUESTThis response to STORE indicates that less than two or morethan four operands have been specified. Reissue the request
in its correct format.
INVALID ARGUMENT
This message is given if the first operand cannot be locatedin the DEBUG symbol table and is not a valid hexadecimal
number. or information specified in the second, third,
and/or fourth operands is not in hexadecimal format. If thefirst operand is intended to be a symbol. a DEF request musthave been previously issued for that symbol: if not, theoperand must specify a valid hexadecimal core location.
INVALID CORE-ADDRESS
current origin value, when added to the hexadecimal
number specified as the first operand, gives an address
greater than the user·s virtual core s~ze,..
If the orl..gl.nvalue is unknown, reset i t to the desired value using ORIGIN
and reissue the STORE request.

~ 'IheExamples:a.
STORE 1202Q OACAThis causes the two bytes of information OACA to be stored
at the core address obtained by adding the current origin tolocation 1202Q. See Figure 21.

b.
STORE XYZ 134123Q567890 5CA14 B
Since the second operand in this example contains more thaneight digits. it is truncated on the right. giving 134123q5.
The third and fourth operands. containing an uneven numberofdigits.
become 05CA14 and OB
respectively.
Thiseight-byte string is then stored in the core address
indicated by symbol XYZ.
See Figure 21.
c.
STORE F12 FF.FFFFF'F FFFFFFFF FOF1F2F3This example causes 'the maximum number of bytes, 12,. to be. st.ored at location "F12.
If F12 is a previously-defined
symbol, the information is stored starting at the address towhich that symbol refers.
If no symbol F12 is defined, thecurrent origin is added to the hexadecimal number F12, andthe resulting address is used as the starting address into252

DEBUG - STORE

which the information is stored.

See Figure 21.

x 12024
E3D640C6

store 12024 Oaca

x 12024OACA40C6

x xyz 15
C2D8506300044120C2E04800C2E812
store xyz 1341234567890 5ca14 b

x xyz 151341234505CA140BC2E04800C2E812

x f12 13
F1EC4310A00141AOA002910FFO
store f12 ffffffff ffffffff fOf1f2f3
x f12 13

FFFFFFFFFFFFFFFFFOF1F2F3FO
Figure 21.
request to
storing

Examples of the STORE request, using the X
inspect the contents both before and after

DEBUG - STORE

253

TIN

Format:
TIN

CMS
DEB

Usage:The TIN request determines how DEBUG is to handle I/O in the
Debug environment, either by the normal eMS I/O routines orby DEBUG itself,.
TIN CMS allows CMS to handle the I/O for the Debug
environment when that environment is entered either by
typing DEBUG or by encountering a breakpoint (that is, when
the Debug environment is entered on purpose). This permits
input to be entered as normally in CMS, including theability to have input lines stacked in an EXEC file~ TIN CMS
is the default
mode of I/O operationin the Debug
environment.
TIN DEB accepts input to the Debug environment only from theterminal as it allows Debug to handle its own I/O. This is
the method used in previous versions of CMS.
Responses:
There are no responses to
unlocking of the keyboard.

254

this

DEBUG - TIN

request other

than

the

x
Format:~---~--~---~---------~-~---~-

symbol <

1
I
f
I
I

n
>
lengthX

hexloc < n >qsymbol is a name assigned by using the DEF request to thecore address of the first byte to be examined
hexlocis the hexadecimal core location relative to thecurrently defined origin of the first byte to be
examined

n is a decimal number from 1 to 56 inclusive, that specifies

the number of bytes to be examined
length is the length attributethe first operandof the syrobol

specified as

Usage:
This request is used to examine the contents of specificlocations in the user's virtual core, and causes contents tobe typed at the terminal in hexad·.!cimal form.
The first
operand of the request specifies the beginning address ofthe portion of core to be examined.
This address isdetermined in the following way.
If the operand contains
any non-numeric characters. the DEBUG symbol table issearched for a matching symbol entry. If a match is found,the core address to which that symbol refers is used as thelocation of .the first byte to be examined. If no match isfound, or if the first operand contains only numericcharacters, the current origin as established by the ORIGIN
request is added to the specified operand and the resulting
core address is used as the location of the first byte to be
examined. provided that address is not greater than theuser's virtual core size.
The second operand of X is optional.
If specified,it
indicates the number of bytes--up to a maximum of 56--whose
contents are to be typed. If the second operand is omitted.
a default value of 4 bytes is assumed unless the first
operand is a symbol; if it is, the length attribute which is
assigned to that symbol in the DEBUG symbol table is used as
the number of bytes to be typed.
Responses:
If the X request is correctly issued,. the information is
typed and, following a carriage return, the keyboard is
DEBUG - X

255

unlocked to accept another DEBUG request.
INVALID DEBUG REQUESTThis response indicates that no or more than two operands
have been specified in the X request.
Reissue the request
in its correct format.
INVALID ARGUMENT
This message is given when the first operand cannot belocated in the DEBUG symbol table and does not constitute avalid hexadecimal number or the second operand is not adecimal number between 1 and 56 inclusive. If the first
operand is intended to be a symbol. it must have been
defined in a previous DEF request; otherwise, the operandmust specify a valid hexadecimal number.
INVALID CORE-ADDRESSThe hexadecimal number specified in the first operand, when
added to the current origin, is greater than the cor~ sizeof the machine being used. If the current origin value is
unknown, reset it to the desired value by issuing ORIGIN andreissue the X request.
Examples:a. X XYZThe contents of core starting at the address to which symbol
XYZ is assigned are typed at the terminal. The number ofbytes typed is determined by the length attribute of symbol
XYZ as established in the DEF request for that symbol. See
Figure 22.

b. X OTHER 12
Twelve bytes of core are typed beginning with the core
address to which symbol OTHER has been assigned in aprevious DEF request. See Figure 22.

c. X 123
Since no byte count is specified, four bytes of core are
typed starting at the core address that is the sum of thecurrent origin value and the hexadecimal number 123. See
Figure 22.
d. X 123 32
Thirty-two bytes of core are typed, starting at the addressthat is the sum of the current origin value and thehexadecimal number 123. See Figure 22.

256

DEBUG - Xx xyz00CCD501
def other 120
x other 120670897000031A7150170004

x 123
7000031A

x 123 32
7000031A715017000492EE7004D2037000C3Ic5910C35447BOCOE25010C35458
Figure 22.

Examples of the X request

DEBUG - X

257

SETERR
Purpose:The SE~ERR command is used to trace transfers to and fromall SVC-called programs in which error conditions occur.
Format:SE'l'ERR
Usage:The SETERR command sets error overrides that cause trace
information to be recorded for all SVC-called programs that
return ~ith an error code in general-purpose register 15.
The following information is recorded.
(1) A basic line consisting of the core locations of the
SVC instruction and of the program which it called, thecontents of the SVC old program status word, and the core
locations to which the SVC-called program would return underboth normal and error conditions.
(2)
The contents of all general-purpose registers, both
before the SVC-called program is given control and after it
issues a return.

(3)
The contents of all floating-point registers both
before the SVC-called program is given control and after it
issues a return.
(4)
Two lines--16 words--of the parameter list which exists
at the time the SVC is executed. See Figure 23 for a sampleof the type of information recorded by the SETERR command,and the format in which this information is printed on theoffline printer.

The SETERR command causes the above trace information to berecorded for all SVC-called programs that return error
codes.
This information is not printed until the user
issues a CLROVER or a ~O command, a RESTART request in the
Debug environment, or logs out from the Control Program.
Traces initiated by the SETERR command may be terminated byissuing a CLROVER or a KO command,. Both CLROVER and KO
cause the trace information recorded up to the time they areissued to be printed on the offline printer.
Notes:a.
Issuing one or more SETERR commands when a SETOVER
command is active has no effect, since error as well as
normal overrides are set by SETOVER,.
258

SETERR

h. Issuing more than one SETERR command has no additional
effect other than causing the heading given under Output toappear in the trace information printout each time a SETERR
is issued.
c.

Any operands given in the SETERR co~roand are ignored.

Responses:
None.
Output:
SETTING ERROR-OVERRIDE TO PROVIDE A DYNAMIC
TRACE OF CMS (AND OS) SVC-CALLS • • •This message appears in the offline printout of
information at all points where SETERR commands
issued.

the trace
have been

Example:SETERR
This causes information such as that given in Figure 23 tobe recorded for all SVC-called programs which return anerror code in general-purpose register 15.
Error Messages:
None.

SETERR

259

SETTING ERROR-OVERRIDE TO PROYIDE A DINARIC TRACE OF CBS (AID OS) SVC-CALLS •••••••• ERROR-OVERRIDE,CALLER=000057F2
GPRS BEFORE = E2C5E3C50000139C
00009386
00012000
FPfiS BEFORE = 00000000
00000000GPRS AFTER
E2C5E3C50000139C
00000004
00000100
FPfiS AFTER
00000000
00000000
PARK.-LIST--FINI---S
FFFFOOOO
00000000

CALLEE=FINISSYC-OLD-PSW=000400CA400057F400000000
00005816
00009B10
E~C5B3C500009508
00000001
400057E800001180
00000000
00000000
00000000
00000000
0000139C
00000000
00000778
000029DC
C6C9D5C9E2404040
000040A8
OOOOOAlO
00000000OOCOOOOO
00000000
00000000--.

00000000

00000000--.

00000000--OYEB--

IB!BBT=o000057P8
018'1=0000511"800005018
0003B8B840009540
0000111000000000
00000000
00000120
00000048
000026CE
00000006
00000000
00000000
5C40FPPP.FFEIIID--IIDB---BODD--••••• EfiROR-OYERRIOE,
CALLER=000057F2
GPRS BEFORE = E2E3C1E30000139C
00009386
00012000
HRS BEFORE = 00000000
00000000GPRS AFTER = E2E3C1E30000139C
00000004
00000100
FPBS AFTER = 00000000
00000000
PARK.-LIST = --FINI---S
FFFFOOOO
00000000

CALLEE=FIHlS
SVC-OLD-PSW=000400CA400057F400000000
00005816
00009B10
E2E3(lB3
00009508
00000001
400051£8oooe 11BO
00000000
00000000
00000000
00000000
0000139C
00000000
00000718
OCOC29DC
C6C9D5C9E2404040
000040A80000011000000000
00000000
00000000
00000000--TEST--

HRBIET=000057P8
EBRE~000057~
000050A8
0003E888
40009540
000011&0
00000000
00000000
00000120
00000048
000026CE
00000006
00000000
00000000
5C40Fl"FP
l'l'l'BFl"FD--FOBT--••••• ERBOR-OVERRIDE.
CALLER=00009514
GPIiS BEFORE = E2E3C11!300009B1000009386
00012000FPRS BEFORE
00000000
00000000
GPIiS AFTER = E2E3C1E300009B1000000004
00000100!!PBS AFTEB = 00000000
00000000
PAR!I.-LIST = --STAT---E
FFFFFFFF
FFFFFFFFCALLEE=STATESVC-OLD-PSW=000400CA60009516
00000000
00000000
00009B10
E2!3C1E3
C0009508
CC000001
40009378
800094CO
00000000
00000000
00000000
00000000
00009810
COOOOOOO
00000778
00002A84
E2 E3C1 E3(5404040
00002BDO
ooooono00000000
00000000
00000000OOOCOCOO--TEST---SYSI---Ii
FFFFFFFF
fFFFFFFF
FFFFFFFF
FFFFFlFF

HIBBET=0000951A
EBBET=0000951A
000050A8
0003E8B860009580
00000001
00000000
00000000
00000A2000000048
000026CE
00000001
00000000
00000000FFllFPl1lFFIIllF
FFl"FFFFF
FFl"l"FFFF••••• EFBCR-CVEBBltE.
CALLEB=000057F2
GPBS BEFORE = E21!3C1E30000139C
00009386
00012000
FPES BEFOFE = 00000000
00000000GPRS APTER
E2E3C 1E30000139C
00000004
00000100FPRS AFTER
00000000
00000000
PARK.-LIST--FINI---S
FFFFOOOO
00000000

CALLEE=FINISSYC-OLD-PSV=000400CI.40Ce57F400000000
OC005816
00009B10B2£3(lE300009508
00000001
400057f8000C11BO
00000000
00000000
00000000OCOOOOOO
0000139COCCOOOOO
00000718
000029DC
E2404040
000040A8
CcceCAlO
C6c9D5C900000000
00000000
00000000
00000000--.

BB!lBE'f=000057F8
BBRET=000057F8
000050A8
0003E858
40009540
000011BO
00000000
00000000
00000120
00000048
000026CE
00000006
00000000
00000000
5C40FFFF
FFFEFFFD••••• EIiRCR-OVEBRICE,CALLER=000025C2
GPRS BEFORE
00000000
000C09EO
00000004
00000100FPRS BEFORE
00000000
00000000GPRS AFTER
00000000
0000091'4
00000004
00000100FPRS AFTER
00000000
00000000
PARM.-LIST--LOAO---f'!CD -00000000
00000000

CALLEE=LOADftOD 5VC-OLD-PSW=000400CA400C25(400009B10COOOOOOO
00000778
000009E8
D3404040
40404040
40009378
4cce2~8E
oooooooc
COOOOOOO
00000000
00000000
00005838
00000000
00000778
00002100
00001180
000026CE
00002FOC
00CCOE7C
COOOOOOOOCCOOOOO
00000000
00000000--L
fFOOOOOC--CPFU-OOOOOCOO
CCC400CA
5000E692
00000000BBBBET=000025C8
EBBET=000025F800000A2000000048
000007B 800000000
00000000
00000000OOOOOAFO
00000044
000026CE
00000001
00000000
00000000-- BC T1t-00011000
0000EE58
0800!~68••••• ERROR-OVERRIDE,CALLER=00009514
GPFS BEFCRE
00000000
00009B100000~386
00012000FPRS BEFORE
00000000
00000000
GPBS AFTER
I:3C9E2E3000115E80000F138
00001BA8FPES AFTER
00000000
00000000
PAR fl. - LIST--L
PPFPFPPFFFPFFFFPCALLEE=L
00000000
COC09508
00000(,0000011000
D3C9 E2 E300000000--TEST-PFPFFPFf

SYC-OLD-PSIi=000400CA50009516
00000000
0000981C
D3~(4C40
CCOOOOOl
40009378
800094CO
00000000
00000000OCC(OOOOOOCOOOOO
00000028
000002F800011470
000011E0
00000002
00000000
00000000
C(CCCOOC--SISI---Ii
FFFFFlFF
FFFFFFF!
fFFEFFFF

HBBRE'l'=00009511
EBBE'f=0000951A
00005018
0003E888
40009500
00000001
00000000
00000000
00000000
00000000
000026CEOOOOOOO~OOCOOOOO
00000000
FFEIFfF!
IPIFIIIP
FFPFFFFF
FFFFFFFF••••• E 6RCR-CVERRltE,
CALL ER=000057 F2GPRS BEPORE
00000000
0000139C
00009386
00012000
FPES BEFCF!
00000000
00000000
GPES AFTER
00000000
0000139C
C0000004
00000100
FPES AFTER
00000000
00000000
PARfl.-LIST--FINI---S!FFFOOOO
00000000

SV C-OLD-PSW=OOO 40CCA 40 C(5 7F 4CALLEE=FINIS(OOOCOOC
00005816
00009B10
D3404040
00009508
00000001
400057E8000C11BO
00000000OJOOOOOO
00000000
OCOCOOOO
0000139COCCOOOOO
0000077 8000029tc(6 C9 D5 C9E240ij040
000040UOOOCCUO
00000000
COOOOOOO
00000000
OOC(OOOOHBBBET=000057F8
EllRET=000057F8
0000501.8
000318£840009540
00001180
OOCOOOOC
00000000
00000120
00000048
000026CE
00000006
OOOOOOOC
00000000
5C40FIPF
IflElllD--F-BODD--.* ••tiOTE--NCE~AL-

00000000

00000000--.

00000000

00000000

00000000OOOOOO(lO--.

00000000--.

00000000--.

OOOOOOOC--TEST----LISt---FOB~-AND ERROR-OVERRIDES EAVE NOW BEEN CLEARED ••••

Figure 23.

260

--.

Sample offline printout of trace information
recorded by the SETERR command

SETERRSETOVER
Purpose:The SETOVER command is used to trace transfers to and fromsVC-called programs which are executed normally as well as
those in which error conditions are encountered.
Format:ISETOVERjSAMELAST<SAMEL~ST><option1 .. '•• optionN> I

leaves all options as set by the user's last
SETOVER command provided a CLROVER has not been
issued. If SAMELAST is not speci'fied or if CLROVER
has been issued. options are reset to theirdefault settings.
Any options specified after
SAMELAST replace these settings.

optionl ••• optionN
below.

are oneor

moreof theoptions

given

options:
GPRS

recordthe contents ofthe general-purpose
registers both before the SVC-called program isgiven control and after a return from that program
GPRSB
recordthe contents ofthe general-purpose
registers only as they exist before the SVC-called
program is given control
GPRSA
recordthe contents ofthe general-purpose
registers only as they exist after a return fromthe SVC-called program
The default option is that no general-purpose register
information is recorded .•FPRS

recordthe contentsof thefloating-point
registers both before the SVC-called program isgiven control and after
a return from that
program.
FPRSB
recordthe contentsof thefloating~point
registers only as they exist before the SVC-called
program is given control
FPRSA
recordthe contentsof thefloating-point
registers as they exist after a return from the
SVC-called prograro
The default option is that no floating-point register
information is recorded.
NOPARM

PARM1

no parameter list information is to be recorded
when a program is called by an SVC instruction
record one line (8 words) of parameter list
information when a program is called by an svc
instruction
SETOVER

261

The default option is two lines (16 words) of the parameter
list recorded when a program is called by an SVC instruction
NOWAITno information is to be recorded when WAIT iscalled by an SVC
WAITSAME record the same information for GPR·s, FPR·s, anduarameter lists when WAIT is called as thatrecorded for all other SVC-called programs
WAIT1
record one line (8 words) of the parameter list
when WAIT is called~AIT2
record two lines of the parameter list when WAIT
is called
The default option is that no GPR, FPR, or parameter list
information recorded when WAIT is called
DEFAULTcancel a1l current settings
to their default settings

and reset the options

Usage:The SETOVER command traces all internal branches which takeplace due to SVC, or supervisor call, instructions.
The
effect of the SETOVER command is to set overrides whichcause information to be recorded at the appropriate times.
Both normal and error overrides are set by the SETOVER
command.
The information recorded will vary:. depending on the type ofoverride. For both normal and error overrides, the core
location of the calling SVC instruction and the name of'thecalled program or routine are recorded, as well as thecontents of the SVC old program status word (that is, thatwhich was stored when the SVC was issued) and the core
locations of the normal and error returns from the called
program. In addition to this basic line, error overrides
recordthecontentsofthegeneral-purpose
andfloating-point registers before branching to the SVC-called
program and returning from it, and 16 words of the parameter
list which existed when the SVC was issued. For normal
overrides, the additional information recorded depends upon
the options specified by the user in the SETOVER command.
If no options are specified, the default options are used:
no general-purpose or floating-point register information,and 16 words of the pararoeter list are recorded for all
routines except WAIT.
For WAIT only the basic 'line of
information, common to both normal and error overrides" isrecorded. When the user does specify options, the default
settings are assumed initially. and options specified by theuser replace the appropriate default settings. If the user
specifies SAMELAST as his first option, the options remain
as they were set by the last SETOVER command issued provided
no CLROVER command has been issued, and any further options
given in the SETOVER comroand replace these previously set
options.
It is possible to issue two
262

or more SETOVER commands before

SETOVERissuing a KO or a CLROVER command. When additional SETOVER
commands are issued, the option settings are adjusted toreflect those specified in the most recent SETOVER command.
If SAMELAST is not specified as the first option in these
additional commands, the options are reset to their default
settings, and only those options specified by the user in
the new SETOVER command replace the default settings.
""

To terminate overrides set by the SETOVER command, the user
may issue a KO or a CLROVER command. Both CLROVER and KO
cause all trace information recorded up to the point they
are issued to be printed on the offline printer. CLROVER
can be issued only when the keyboard is unlocked to accept
input to the CMS Command environment,. To clear overrides at
any other point in system processing, KO must be issued. If
a user issues a RESTART request to the Debug environment or
logs" out from the Control
PrograF prior to clearing
overrides set by SETOVER and/or SETERR. the overrides arecleared automatcially and all recorded trace information isprinted on the offline printer.
Notes:
a. If SAMELAST is specified, it must be the first option
given and there must be no intervening CLROVER between the
two SETOVER commands.
b. If mutually exclusive options are specified, such as
NOPARM and PARM1, the last such option appearing in the
SETOVER command is used. For options which are not mutually
exclusive--GPRSandGPRSA, forexample--thelogicalcombination of the options is used.
In this case, theoption set by GPRS would be used since it includes the GPRSA
option.
c.
The number of lines of parameter list information
recorded for calls to the WAIT routine cannot exceed thatrecorded for other routines, (that is, the" PARM setting
governs the WAIT setting when the latter specifies thegreater number of lines to be recorded.
Responses:
None.
output:
SETTING NORMAL - AND ERROR-OVERRIDES TO PROVIDEDYNAMIC TRACE OF CMS (AND OS> SVC-CALLS... • •This message appears in the offline printout of trace
information at all points where SETOVER commands are issued.
A

Examples:a.
In

SETOVERaddition to

the

basic

information recorded

SETOVER

for

both
263

normal and error overrides, this example causes the default
information (no general-purpose or floating-point register
information and two lines of the parameter list) to berecorded for all normal overrides. For error overrides, thecontents of all general-purpose and floating-point registers
are recorded both before branching to the SVC-called programand after returning from it. as are two lines of theparameter list information.
A sample of the type of
information which is recorded is given in Figure 15.
h.
SETOVER GPRSB FPRSA NOPARM
In addition to the basic information, this example causes
the contents of the general-purpose registers to be recorded
before the SVC-called program is given control, and thecontents of the floating-point registers to be recorded
after a return is issued by that program for all normal
overrides. No parameter list information is recorded. For
calls to the
WAIT routine, only thebasic line of
information is recorded. The same information is recorded
for error overrides as that given in Example a.
See Figure
24 for a sample of the type of information which is recorded
for this example and the format in which it is printed.

c.
SETOVER SAMELAST PARMi WAIT2
Assume Example b had been issued prior to this example andno CLROVER had been issued between them. Since SAMELAST is
specified as the first option"
the settings for Example bwould be assumed initially. The NOPARM setting, however, isreplaced by the PARMI option specified above.
WAIT2 would
normally replace
the default option ofrecording noparameter list information for calls to the WAIT routine.
but since PARM1 has been specified, only one line of theparameter list for calls to WAIT is recorded. The same
information is recorded for error overrides as that given in
Example a. Refer to Figure 25 for a sample of the type of
information which is recorded by this example and the format
in which it is printed.
Error Messages:
E (00001)

The user has specified one or more invalid options,. Reissue
the SETOVER command making sure that all options are spelledcorrectly and that SAMELAST. if specified,is the first
option given.

264

SETOVERSETTING NORIIAL- AIiD ERROR-OVERRItES TO PROVIDE A DINAIHC TRACE OF ClIS (AID OS)

SYC-CALlS •••hORMAL-OVERRIDE,CALLER=00009514
GPRS BEFONE = E2C5E3D600009B1000009386
00012000fPRS AFTER = 00000000
00000000
PARII.-LIST = --SETO---VER --CALLEE=SETO YER S YC-OLD- PSIi=000400CA60009516
00000000
00000000
00009B10
E2C5E3D600009508
00000001
40009378
SCCe94CO
00000000
COOOOOOO
00000000
00000000--5A!E---LAST---PARft---1

IIRUET=0000951A
lRRB'l=OO 00951.&
000050A8
0003EBB8
60009580
00000001
00000000
00000000*****EEBOR-CVERRItE,
CALLER=000051P2
GPB5 BEFOBE
E2C5E3D60000139C
00009386
00012000
FPBS BEPORE
00000000OOOCOOOOGPRS AFTER
E2C5E3D60000139C
COC00004
00000100
FPB5 AFTER
00000000
00000000
PAR~.-LIST--FINI---5
FFFFOOOOOOCOOOOOCALLEE=FINISSVC-OLD-PSII=000400CA400e51F400000000
oe005S16
00009B10
E2C5E3D600009508
00000001
400057ES
OeOC11BO
00000000OOOOOOuO
00000000
OOCCOOOO
0000139C
00000000
00000718
0000291)C
E2404040
000040A8
cceCCAAO
C6c9D5c900000000OOCOOOOO
00000000
OCCCOOOO-lIAIT----2--5TA'I--

HB!RET=000057P8
BBBET=000057P8
000050A8
0003ES58
40009540
000011BO00(00000
00000000
00000.&2000000048
00C026CE
00000006
00000000
00000000
5C40FFFF"FEIIED--I!CDO--hOBMAL-CVERRII:E,
CALLER=C000955A
GPRS BEFORE = 00000004
000095FC
00009386
00012000FPRS AFTEB = 00000000
00000000
PARI'I.-LIST = -- TYPL---I N

CALLEE=TVPLIIi
SVC-OLD-P5W=000QOOCA60CC955C
OOGOOOCOCOOOOOOO
00009B10
E2c5E3I:600009508
00000001
40009376
6ceC954E
00000000
COCOOOOO
00000000
00000000
0100960C
C200001A
D95E40E3
7EFC4EFO

NRlIRET=00009560
EBBET=0000954A
000050A8
0003E8ES
1I0C096C20000960F
00000000
00000000
P461FC4B--11 2--NORMAL-OVERRIDE,CALLErl=0000CB4E
GPRS BEFOEE = 00000000
0000C858
C00001F800000009
FPRS AFTER = 00000000
OOOOOOOv
FARM.-LIST = --ATTN--CALLEE= ATT N
5VC-OLD-PSW=000400CA6CCCCB5e
OC000013
01C(9774
C000023£00000012
000095DC
000001f8
0000C658
0000C658
00000000
00000000OOOOOOOC
ceccceoo--LIFO-12000251--NOLL--

NR!RE'I=OCOOCB50
EFRET=0000A238
00000251
00000231
00000001
OOOOOOCOCOCOOOOC
00000000
000001E8000004CONORMAL-OVERRIDE,CALLER=000096D8
GPRS BEFORE = GCOOOOOO
000095DC
00009386
00012000FPRS AFTER = CCOOOOOO
00000000
EARII.-LIST = --WAIT---RDCALLEE=liAITRD
SV(;- OLD- PSW=000400CA400096DA
00000000
00000000
00009456
oec(CCOO(G009508(CCOOOOl
40009378
800094COOOOCOOCOOOCOOOOO
00000000
00000000
01009774
f4000012--TYPL---Ili--

NB!BET=000096DE
EBBET=COCC5tDE
0003E8ES
C00050A S
OOeOCEEO
00003218
00000000
00000000
01009366
D2000020~CHAL-CVEIiBHE,CALLER=00009514
GPBS BEFCRE = E2E3C1E300009B10
00C09386
00C12000FPRS AFTER = 00000000
00000000
PAtlM.-LIST = --STAT---E

CALLEE=5TATE
5YC-OLD-PSII=000400CA6CCC9516
OOCOOOO(
oecooooo
00009B10
E2E3C1E3
00009508
00000001
40009318
800094CO
00000000
00000000oooooooe
oececcoo--TE51---FORT---~1~ --NR!RE7=0000951A
EBRET=0000951A
000050AS
0003E85S
60009580
00000001
cecocooc
00000000
IFillFFI
000013£0*****EBROR-OVERRIDE,CALLER=000051F2
GPbS BEFORE
E2E3C1E30000139C
00009Jdb
00012000FPRS BEFORE
00000000
00000000
GPIiS AFTER
E2E3C1 n
0000139C
00000004
00000100
FPBS AFTER
eoccooooOOCOOOOO--S
FAEI'i.-LIST--FINI-FFFFOOOO
COOOOOOOCALLEE=FIN ISSYC-OLD-PSII=000400CA400057F400000000
00005816
00009B1C
E~E2C1E3
COC095CS
CCCOOOOl
400057E8000011BO
00000000
00000000OOOOOOOC
00000000
0000139C
00000000
00000778
OOCC~SDC
C6C905C9E2404040
000040A8
OOOOOIAO
00000000
00000000
aooooocc
OCCCO(OO--*

00000000

00000 000--*OOOOOOOC--'IES'I--

NR!RET=OC0057F8
EBRET=0000~7F8
COC050A8
0003E8B840009540
000011BO
00000000
00000000
COOOOA2000000048
000026Cl
00000006
coooeooo
00000000
5C401FFF
FFFEFFFD--108T--NORMAL-OVERRIDE,CALLER:0000955A
GPJiS BEFCBF = 00000004
000095FC
00009386
00012000
FPES AFTER = COCOOOOO
00000000
FAB~.-LIST =--TYFL---IN

00(000000(;009508
00000000
01009COC

SVC-OLD-P5W=000400CA6C00955C
00000000
00009B10
E~E3C1E3(CCOOOOl
40009378
8000954E
00000000OOOOOOOC
occeccoc
C2C0001A
D95E40E3
1EP04fFO

NR!RBT=00009560~BBET=0000954A
00C05CA 80003E8B8400096C2
0000960F
oocooeoc
00000000
F461F04E--09 2--~ORMAL-CVJ::RBIl:E,
CALLER=OOOOCB4EGPRS BEFORE = eC000011
0000CB5d
00000007
C0000009
FPRS AFTER = 00000000
OOOOOOO~
PARM.-LIST = --ATTN--CALL EE =A TTNS VC-OLD- PSW:000400C A6 000CE50
OOO()0002
01009174
00000231
00000010
000095DC
oooao lE80000C65f
OCCCC65E
OOOOOCCO
COOOOOOO
00000000
00000000
01000241'--NULL---LIFC--

NBeBET=0000CB50
BBBET=0000A238
0000024F
00000048
oeC00001
000032F800000000
00000000
COCOC1E800000400~CJi P.Al-(V EEl EILE,CALL E!1=OOO "9bDS
GPES BEFCr,E = 00000000
000095DC
OCC09386
00012000
FFiS AFTER = 00000000
OOOOOOOC
PAR~.-LIST =--WAIT---liD--

CALLEE=W AIT RI:
SY C-OLD-PSW =OOO~OOCA 4CCC HDA
00 000 00 C
CCC00000
00009458
00000000
0U009508
00000001
4000937E
eCCC94CO
00000000OJOOJOOO
0000000COCCCCCOO
01009/74
E4CJ0010--TVPL----1.--

NReRE7=OC0096DE
E6BET=000096DE
000050A8
0003F8S8COOOCEEO
000032F800000000
00000000
01009386
1)200CO~0

CALLER=OOO09514*****EBROR-OVERRIDE,
E2E3C1E3
GPRS BEFORE
00009B10i) ,)('0 9 386
000120;)0
C(OOGGOOFPIiS b EFOIlr;
COOOOOOO
E2E3c lE3
GPIiS AFTUi
00009810
00OOJOO4
CCOO0100
coeooooo
000COOOOFPR S AfTER--5T AT---f
fAH. -LIST
FFFFFFFF
r'FFFFFFFCALLEE=S'IATESYC-OLD-P5W=000400CA60009516
00(00000
00000000
0000913 1C
E:a3c lE3
COO095C840009378
800094CO
CCCOOOOl
00000000
COCOOOOO
00000000
00000000
000091310
OJOOOOOO
0000071 E
OCCCa84
E2E3C 11::3
C5404040
00002 BOO
COOOO lAO
OOOOOOOC
COOOOOOO
00000000
00000000--TE5T---SY5I---Ii
FFFFFFFF
FFFFF FFF
PFFFFFFF
PPfHH'F

NRI!BET=0000951A~BRET=0000951A
OOC050&S
0003E8B860009580
00000001
00000000
00000000
COCOOA2C
00000048
000026CF
00000C01
00000000
00000000PFFFFFFF
FFFPFFPPFFFiPFPip,.rlFFP

Figure 24.

00000000

CCCOOOO(,

00000000

CAlLEE:TYFLI~

Offline printout showing trace information
recorded by the SETOVER command with theoptions GPRSB, FPRSA, and NOPARM specified

SET OVER

265

SETTING NOR!!AL- AND ERROR-OVERRIDES TC PROYIDE A DYNAIIIC TRACE OF CIIS

(ANI: OS)

SVC-CALLS •••bOJiIlAL-CVERRIJ:E,
CALL ER=000C9514
GPRS BEFCBE
E2C5E3D600009B1000009386
00012000
FPBS AFTER = 00000000
00000000

CALLEE=SETOYE R SYC-OLO-P5W=0001i00CA 6CCC 9516
00000000
COOOOOOO
00009S10
E2C5E3D600009508
00000001
4000937€
8eCC911COOOOGOOOOCCCOOOOO
oooooooe
oeccecoo

NRIIRE'I=00009511
EBBET=0000951A
00005018
000318£860009580
00000001
OOCOOOOC
00000000*****EEhOR-CYERRICE,CALLER=000057F2
GPRS BEFORE
E2C5E3D60000139c
00009386
00012000FPRS BEFCRE
00000000
00000000GPRS AFTEIi
E2c5E3D60000139C
00000004
00000100FPRS AFTER
00000000
00000000FAIHI.-LIST = --FINI---S
FFFFOOOO
00000000

CALLEE=FINISSVC-OLD-PSW=000400CA400057F4OOOOOOOC
OC005816
00009810
E2C5E306
00009508
00000001
400057EE
OCe( 11S0
COOCOOOOGOCOOOOO
00000000
00000000
0000139C
00000000
0000077E
OOCC2SDC
C6C905C9E2404040
OOOOIlOlS
cocceAlO
00000000(DCOOOOO
00000000
00000000--CVHi--N6I1BET=0 0005718.EBRET=000057 F800005018
0003E8£8
1I0C0954C
00001180
00000000
00000000
COOOOA2e
00000048
000026CE
00000006
00000000
ooooeooo
5C40FFFF
FFFEFFFD--RIDE---1I0[U--NORM AL-O VERR IDE,
CA LLEIl=0000955 A
GPES BEFCBE
00000004
000C95FC
00009336
00012000<PRS AFTER = COOOOOOO
00000000

CALLEE=TYflIfi
SYC-OLD-PSW=000400CA6000955C
00000000
00000000
00009H1C
E~C~E3D6
C00095C8CCOOOOOl
40009378
8000954£
JOOOOOOO
00000000OOOOOOOC
OCCCOCOC

NBIIBET=00009560
EBRET=00ee954A
00e05018
0003E888
400096C2
00009601
OOeOOOO(
00000000~o E/';AL -0 YER HI!:E,
CA LL ER=OOO 096D8
GPFS BEFORE
00000000
000095DC
00009386
00012000
FPBS AFTER = 00000000
OOOCOOOOCALLEE= Ii AlT RD
SYC-OLD-PSli =000400Cl 4C CC 9 fOl
COOCOCOC
COCOOOvO
00009458
00000000
00009508
00000001
4000937E
8(CC94CO
COCOOOOOOOOJOOOOOOOOOOOC
ooocoooe

NRIIRE'I=OC0096DE
EBBET=000096DE
00005018
0003E8Ee
COOOCEZO
000C32F8
accooooe
00000000

hO B~A L-CYER H DE,
CALL ER= 000 09514
GPHS BEFORE
E2E3C1E3
00009B100000'1386
C0012000
FPES AFTER = 00000000
00000000

CALLEE=STATESVC-OLD-PSW=00040OCA6CCC5516
00000000
eooooooo
00009810
E2E3C1E3
00009508
000'>0001
40009378
eeCC94C0
cooooooe(OCOOOOOOOOOCOOO
00000000liBIIBE'I=0000951A
UBU=0000951 A
000050A80003£8B86000958e
00000001
00000000OOOCOOOO*****ERROB-OVERHIDE,CALLEB=OC0057F2
GPRS BEFORE
E2E3C1E30000139C
0000J386
00012000FPRS BEFORE
CCOOOOCO
00000000GPFS APTEE
E2E3C1E3
GGJG139C
0000000ij
00000100FPRS AFTERCOOOOOOO
COOG0000--FINI---S
FAHM.-LIST
FFFFOOOO
000COOOOCALLEE=F IN IS
SVC-OLD-l?SIi=000400CA400057F400000000
00005816
00009B10£~E3C1E3
COC0950E(CC00001
400057E800001180
00000000
00000000
00000000
00000000v000139C
00000000
0000077E
occe~5DC
CbC9D5CS
E2404040
00004018
000001AOOJOOOOOuOOOJOOOOOOOOOOOC
oeeeocoo

HBIIBET=Q00057f8
EBBE'I=eOOC57F6
eDCC5CA80003E8B8
40C09540
000011 EO
00000000
00000000
CO C0012 C
00000048
000026CI
00000006
ecoooooe
OOOCOOOO
5C40F1FF
IFFElfie--FOBT--

00000000

00000000

00000000(JOOJOOOOCALLEE=T~PLIN--*

00000000

00000000--TEST--

SVC-OLD-PSli=000400CA6CC(S~5C

NORMAL-OYERRIDE,CALLEB=0000955A
GPFS BEFCFE
000000J4
COOC95fC
J0009386
00012000FP ES AFTER= CCOCOOCO
OCJOOOOO

C00095Cb
00000000

E2£;C1E3
8000954£
ecceoooo

NBIIHE'I=00009560
EiBET=00COS54A
00005e18
0003E8B8400096C2
000096Cf
OOCOOOOO
00000000bC HiA 1-( YE RBILE,
CALL ER=000096 D8
GP6S BEFC~E
00000000
000095DC
CC009386
00012000FPFS AFTER = 00000000
acoroooo

CALLEE= iI AIT RD
SVC-OLD-!'SW=OOO 1I00CA 4CCC StDlOOOOOOOC
ooeooooo
00009458
00000000
00009508
00000001
4000937E
ECC(94CO
00000000
00000000
0000000C
accccooc

NRIIBET=000096DE
EBBE'I=0000960E
00005018
0003E8E8COOOCE&O
00003a'8
OOCOOOOO
00000000*****EEHCH-OYEBRIDE,CALLER=00009514
GPRS BEFO~E
E2E3C1E3
OOOC9Hl0
00C09386
00012000
FP6S BEfCEE
00000000
OCOCOOOC
GP BS AFTER
E2E3C 1 E 3
0G009Bl000000004
C0000100tPRS AfTEROOCOJCJDCOOOOOOO
PAhM.-LIST--STAT---E
FFFFFFfF
rFfFFFFFCALLEE=STATESVC-OLD-PS.=OOCqOOCA6CC(5~lE
aocooeoc
00000000
00009810
E2E3C1E3
OGOJ9508
00000001
4000937E
SCCCSQC'
coococec
COC00000
00000000
00000000
00009ill0
OiJOiJJOOO
000007713
OCCC2A84
E2E3clE3
C5404040
00002BDOCCC(CAAO
cooooooc
coeooooo
cooooooo
00000000--TEST---SYSI---N
FFFFFFFF
FFFFFFFF
FFFFFFFF
FfFFfFFf

NIiIlRE'I=0000951A
EIiBET=00009511
000050A8
0003E8ee
60C0958(;
00000001
00000000
00000000
COOOOA2000000048
00C026CE
00000001
OOOOOO~O
00000000FFFFFFFF
FFFFFFFF
FFFFHHUfUUF*****EBROH-OVERRIDE,CALLEd=C00057F~
GPRS BEFORE
E2E3C1E3
GJJ0139C
000093d6
OC012000
FP6S BEFOhE
0000)000OOOGOOOO~PRS AFTER
E2F3C1E3
COOC139C(C000004
00000100
FP6S AFTER
00000000OOOOGOOOPARII.-LIST--FINI---S
FFFFooeD
00000000

CALLEE=FINISSYC-OLD-PSW=000400CA400057F400000000
00005816
00009a1C
E~E2C1E3(OCOS506((000001
400057E8000011BO
00000000
00000000OOOOOOOCOCCCCCOO
e00013SC
eccoooOO
00000778
000029DC
CbC9t5C9£2404040
000040AE
CCCCC1AO
cooooooo
O~OOOOOOOOOOOOOC
oeceecoo

NBIIBET=000057F8
ERBET=00e057F8
CCC05CAS
0003E81!8
4000954C
000011EO
Oocoocce
00000000
00000 120000COGII8000026CE
00000006
OOCOOCOO
00000000
5C40ftff
FPlfJtft

Figure 25.

266

OOOCOCJC

00000000OOOJJOOO(CCOOOOl
00000000~OO()"OO

00009810
40009378
OOOOOOOC--*OOOOOOOC--P(,!'I--

Offline printout showing trace information
recorded by the SETOVER command with theoptions SAMELAST, PARMI, and WAIT2
specified (SAMELAST in this example refers
to the options as set in Figure 24)

SETOVERLANGUAGE PROCESSORS
The language processors supported in eMS are the same ones
used under
Operating System/360(OS): theseincludeAssembler (F), Fortran IV (G) I' and PL/I (F).
The language processors in CMS and OS are compatible at thesource language level as long as the macros and SVC's usedin an Assembler program are supported by CMS.
The object
modules (text decks) that are
output from the above
Operating System compilers may be executed under either CMS
or OS as long as the previous restrictions are adhered to.
There are two additional processors available as Type III
programs from the IBM Program Information Department: they
are SNOBOL, a string processing language, and BRUIN, aninterpretive language. BRUIN, Brown University Interpreter,
was adapted from the OS version of BRUIN developed at Brown
University, Providence;, Rhode Island.
BRUIN provides twomodes of operation: a desk calculator mode and a stored
program mode.

Language Processors

267

ASSEMBLE
Purpose:The ASSEMBLE command creates relocatable object programsfrom programs written in System/360 Assembler Language.
Format:I ASSEMBLE lfilename1 <* •• filenameN>«option1 ••• optionN»

I

1

I

A

I

filename

specifies
Additional
assemblies.

a

SYSIN
file tobefilenames
specify

optionis one or more
below .•of the assembler

assembled.
additional

options listed

Options:
DECK
NODECK

creates a TEXT file of the relocatable
programsuppresses the TEXT fileobjectLISTNOLIST

creates a LISTING file of the assembled program
suppresses
the LISTING
file
and
onlinediagnostics

XREF

NOXREF

includes a cross-reference symbol table in the
LISTING file
suppresses the cross-reference symbol table

NODIAG

types source statements containing errors at theterminal,
along withdiagnostic anderrormessages
suppresses typing of errors.

LTAPn
LDISK
PRINT

writes the LISTING file on the tape whose
symbolic address is TAPn
writes the LISTING file on the permanent disk
writes the LISTING file on the offline printerRENT
NORENT

checks the program for reentrance
suppresses the reentrance check

Usage:
The filetype SYSIN is assumed for all input files to the
ASSEMBLE command.
The file
must have
fixed-length,
SO-character records.
More than
one assembly may be
performed by specifying additional filenames, separated byblanks.
Any number of files may be specified, but thecommand must not exceed a single input line. Each file
268

ASSEMBLE

named is assembled separately in the order named.
output is controlled by a set of options.. The
list of options selected, enclosed in a set of parentheses,
follows the last"or only, filename specified with thecommand.
One
set of options governs
all assemblies
performed by one ASSEMBLE command. The options, specified
in any order, are separated by at least one blank.
A
default value is supplied for any option not included. The
default option values are:
DEeR LIST XREF DIAG NORENT LDISR~ssembler

Any combination of option values may be specified, but if
NOLIST is included" XREF" DIAG, LDISR, PRINT, and LTAPn are
ignored.
During an assembly, three work files are created, with the
filetypes SYSUT1, SYSUT2, and SYSUT3. Their filenames are
the same as the SYSIN file being assembled.
According tothe options specified;, files with filetypes LISTING and TEXT
may also be created"with the same filename,. At the
beginning of each assembly, any pre-existing files with anyof the above filetypes and the current filename are deleted,even if the set of options specified means they are not tobe replaced by the current assembly.
To save old copies of
LISTING and TEXT files" use ALTER to change their filenamesor the filenameof the SYSIN file
before assembly.
Insufficient space on the permanent disk for any of theassembler files causes termination
with an I/O error
message.
filename TEXT P1 is the file of machine-language code
created by the assembler.
This file can be loaded forexecution with the LOAD or $ commands, or punched in object
deck form on the cardpunch with the OFFLINE PUNCH command.
If NODECR is specified, this file is not created.
filename LISTING Pl is the file of source statements andassembled machine code produced by the assembler. This fileis not created if NOLIST is specified.
An external symbol
directory and a cross-reference symbol table are included,
unless NOXREF is specified.
Diagnostics and error messages
appear at the bottom of the LISTING filet, and, unless NODIAGis specified;, are typed at the terminal.
If PRINT is specified!, the LISTING file is printed on theoffline printer. If LTAPn is specified, the LISTING file iswritten on the tape whose symbolic addr,.!ss is TAPn in blocks
of ten 121-character records. If LDISK is specified, or novalue is specified, the LISTING file is written on thepermanent disk.
The SYSUT1"
SYSUT2, and SYSUT3
files created by theassembler and used as work files are deleted at the end ofeach assembly.
If they are not deleted because of anabnormal termination, they may be deleted with the ERASEASSEMBLE

269

command, or by reissuing the ASSEMBLE command.
The assembler searches the system macro libraries (SYSLIBMACLIB SY and OSMACEO MACLIB SY) for macro definitions.
Names of macros in these libraries may be obtained with the
MACLIB LIST command.
Additional macro libraries may becreated on the permanent disk with the MACLIB GEN command,and up to five of these additional libraries may be includedin the assembler search list at one time with the GLOBALASSEMBLER MACLIB command. The assembler accepts the first
definition for a macro it finds, allOWing-the user tooverride system macro definitions. If the user has a filecalled SYSLIB MACLIB or OSMACRO MACLIB on a disk thatprecedes the system disk in the order of search. thatlibrary is searched in place of the system library. See
GLOBALunder-Execution Controland
MACLIBunder"Libraries" for further information.
ASSEMBLE uses
SYSIN files.

the standard

order ofsearch tolocate theReponses:a.
ASSEMBLING: filename
This response is typed for theassemblies performed by a single
diagnostics for the assemblies.

second and subsequentcommand. It separatesb.

SYMBOLIC TAPE ADDRESS INCORRECTLISTING FILE WILL BE WRITTEN ON DISK. WRITINGON TAPE IS CANCELLED.
The option LTAPn was specified, and TAPn was not a valid
symbolic tape address.
The LISTING file is written on thepermanent disk.
c.
OUTPUT TAPE FULL. CHANGE IT AND HIT CARRIAGE RETURN.
An end of reel condition was detected on the tape unit for
the LISTING file. The tape has been rewound. Press ATTN toenter the CP environment, and ask the operator to mount a
When the operator replies that a new tape is
new tape.
mounted, return to CMS with ATTN, and issue a carriage
return. The assembly resumes where it was interrupted.
d.
READY THE TAPE UNIT AND HIT CARRIAGE RETURN.
The tape unit specified by LTAPn signalled not ready. Go to
CP with ATTN and ask the operator to ready the unit,. Whenhe replies that the unit is ready, return to CMS with ATTN,
and issue a carriage return.
The assembly begins orresumes.
e.

PERMANENT I/O ERROR ON TAPE
LISTING FILE WILL BE WRITTEN ON DISK~ WRITINGON TAPE IS CANCELLED.
Allor part of the assembly listing is being written on disk
as filename LISTING P5.
If any of the records weresuccessfully written on the specified tape before the error,
210

ASSE~BLEthey are missing from the disk LISTING file.
f •PLEASE READY THE PRINTER
This response should never occur
responsible system programmer.

under CP.

Notifythe

PERMANENT I/O ERROR ON ~HE- PRINTER, LISTING FILE
WILL BE WRITTEN ON DISK.
This response should never occur under CP.
Notifyresponsible system programmer.

the

g.

h.

PERMANENT I/O ERROR ON DISK, ASSEMBLY CONTINUESWITHOUT WRITING LISTING FILE ON DISK.
The assembly is completing without any LISTING file,. If alisting is necessary" execution may be cancelled with the KX
command.
The error may have resulted from insufficientspace on the permanent disk. Use the ERASE command tocreate more free space and try the assembly again,. If theerror recurs, notify the operator.
Note:
The error completion code returned on completion of the
ASSEMBLE command is the highest severity code returned by
the assembler for any of the assemblies performed by thatcommand.
References:
The System/360 instruction set is described in System/360
Principles of Operation. The assembler instructions andmacro language are described in IBM System/360 Operating
SystemAssembler Language.
Additional informationonassembler execution and messages may be found in IBM
System/360 operating
System Assembler (F)Programmer's
Guide. Note that the execution options in the Programmer's
Guide are different than those supported by eMS.
Examples:a.
ASSEMBLE RETURN
The file RETURN SYSIN Pi is assembled. Since no options are
The
specified. the default options govern the assemble.
following files are created:
RETURN LISTING Pi
RETURN TEXTPi
See Figure 24 for an example showing the on-line diagnostics
generated by the assembler.

b.
ASSEMBLE RETURN JOBA TESTi (RENT NOXREF NODIAG)
The file RETURN SYSIN Pi is assembled, and the resulting
object code is checked for reenterability. The listing fileis printed;, and is not saved on disk. The listing does notcontain a cross-reference symbol table. On-line diagnostics
are suppressed. RETURN TEXT Pi is created on the permanent
ASSEMBLE

271

disk. When the assembly is complete, the same operations
are performed for JOBA SYSIN P5. and then for TESTl SYSIN
P5.
Error Messages!
E(OOOOl)
FILE(S) TO ASSEMBLE UNDEFINED.
No filenames were specified with the ASSEMBLE command.
E(OOOOl)
AT LEAST ONE OF THE FILES TO ASSEMBLE DOESN'T
EXIST OR DOESN-T HAVE A CORRECT -TYPE- NAME.
Assemblies were started.
E(OOOOl)
AT LEAST ONE OF THE FILES TO ASSEMBLE HAS
INCORRECT RECORD LENGTH.
Sysin files must have fixed-length. SO-character records.
E(00004)
Minor errors
were detected during theassembly.
successful execution of the program is still probable.

but

E(OOOOS)Errors were detected in the assembled program, but execution
may still be possible.
E(00012)
Serious errors were detected in the
Successful execution is not probable.
E(00016)
Very serious errors were detected
Execution is impossible.

assembled

program.

in the assembled program.

E(00020)
PERMANENT I/O ERROR WHILE READING SYSIN FILE
filename UNABLE TO ASSEMBLE ALL THE FILE.
Files specified before t'he one named in the message havebeen assembled. The file named and subsequent ones have notbeen assembled. The file in which the error occurred must
be reentered before assembling it.
E(00020)
The assembler detected a catastrophic error such that it
could not continue processing. This may be an I/O error,
caused by insufficient free space on the permanent disk.
Free some space with the ERASE command, and retry theassembly. If the error recurs, notify the operator.

212

ASSEMBLE

~SSEMBLERLANGUAGE PROGRAMMINGPROGRAM NAMING

The normal entry point name of a program should be the sameas the filename of the TEXT file.
The program may then be
executed by the command$ filename
If the filename and entry point namefollowing sequence must be used:
LOAD filename
START entryname

are different,

the

PROGRAM ENTRY

When control is received by a user program, the address ofthe entry point is in register 15, which may be used for
immediate addressability.. Register 14 contains a return
address into the CMS nucleus, and must be saved. Register13 contains the address of an lS-word save area. Register 1
paints to a parameter list!, which contains any parameters
passed to the program by $ or START. The parameter list isaligned on a double word boundary, and each entry is foundin the high-order bytes of successive double words.
Alldata is in EBCDIC.
The first entry is always the entry
point name of the program being executed. The following
entries are the parameters passed to the program.
For
instance, after the command$ JOB10 5/7/68 21.37
register 1 points to a parameter list in the following
format.
PLIST

DS
DC
DC

DC
DC

OD

CLS'JOB10'
CLa'S/7/68'
CLS'21.37'
SX'FF'The last entry is always a double word with all bits set to
one which- serves as a delimiter. Any parameters longer thaneight characters are truncated to the eight high-ordercharacters.
PROGRAM EXIT

Return should always be to the address received in register
14. This gives control to eMS service routines which close
files, update the user's disk file directory, and calculate
and type the time used in execution.
CMS also inspects
register 15 for an error code.
If none is found,thecompletion message has the form "R; T=n.nn/x.xx xx/xx/xx".
If there is a value in register 15. the message is"E(nnnnn); T=n.nn/x.xx xx/xx/xx" where nnnnn is the error
code returned in register 15 and n.nn is the CMS CPU time inseconds used for execution. x.xx is the CP and CMS CPU time"
Assembler Language Programming273

and xx/xx/xx is the time of day in hours/minutes/seconds.
LINKAGE TO CMS COMMANDS AND ROUTINES

with few exeptions, all CMS linkages are made with one
supervisor call: SVC X'CA·. The address of a parameter listis placed in register 1 before the call:, and the first entryof the list always specifies the CMS command or function
being called. All registers are saved and restored by the
SVC-handling service routine, except register 15, which isused as an error return register..
The parameter list is always aligned on a double wordboundary. If a command is called!, the same parameters thatwould be typed to call the command are placed in successive
double words. For instance, a parameter list for ERASE
might appear as
PLIST

DS
DC
DC

CLB'ERASE'
CLS'.'

DC

CLS·WORKFILE'

OD

In this case all files with the filetype WORKFILE are erased
during execution of the program by the sequence
LA 1,PLISTSVC X'CA-

After the files are deleted, CMS returns control to the next
instruction after the SVC. Register 15 is set to zero toindicate that no error occurred. Should an error occur, a
response is typed and control passes to DEBUG. Parameter
lists for eMS routines. which are not commands, such as RDBUF
or WRBUF, are not uniform. complete explanations of theseparameter lists are found in ·CMS Nucleus Routines" later inthis' section and in the CMS Program Logic Manual.
To avoid going to DEBUG when an error occurs in a called
program. the programmer may specify an error return address
with each SVC. The address is placed in the four bytes
iBJInediately after the SVC.. Control goes to the address
specified on any error in the called program. For example
LA

1, PIST

SVC

X'CA-

nc

AL4(ERROUT)

LH

3,26(1)

Note that the address constant must include a length
specification to prevent alignment by the assembler.
In
this example, if the called program completes normally,
control is returned at the LH instruction. If any error
occurs, control goes to ERROOT. Errors are ignored by thesequence

274

Assembler Language Programming

SVC
pc

X·CA·
AL4(*+4)

Linkage Notes:
a. Commands that are not resident in the CMS nucleus may
also be called by the CMS SVC. but they are loaded athexadecimal location 12000.
This is also the default load
point for user programs.
Therefore, a higher load point
must be specified when the user's program is loaded.
A
complete list of disk resident commands may be obtained witha LISTF * MODULE SY" which also gi ves a rough idea of thecommand size, expressed in SOO-byte records.
b. A few CMS routines may be executed only by branching.
The addresses of these programs are listed in a nucleus
module under the entry point SYSREF. SYSREF is resolved as
an EXTRN in any user program. The displacement from SYSREF
to the desired address is obtained with the CMSYSRFF macro
instruction, which generates a series of EQU statements.
The name of each nucleus routine, with a D prefixed to it,
is equated to its displacement from SYSREF in the address
list. The following example shows how to get to the SCAN
routine in the nucleus,.
USERJOBCSECT
EXTRN SYSREF
L
L

BALR
LTR
BNZ

3!,=A(SYSREF)
15.DSCAN(3)
14,15
15,15
ERR $

CMSYSREF

In the expansion of CMSYSREF, DSCAN is equated to thedisplacement of the SCAN address in the SYSREF list. The
address is loaded into register 15 for the BALR. SCAN is aroutine to break up terminal line images in core into astandard CMS parameter list. For further information on
SCAN" see the CMS Program Logic Manual.

Assembler Language Programming

215

CMS MACROSThe macro definitions that are used by the Cambridge Monitor
System are contained in the files SYSLIB MACLIB and OS MACRO
MACLIB which reside on the system disk. SYSLIB MACLIB
contains the CMS macros which provide linkages to the CMS
I/O routines, and OS MACRO MACLIB contains the System/360
Operating System macros which have been changed to interface
with eMS.
Only the CMS macros are discussed in thissection. For a discussion of the OS macros supported, see·OS ~acros". To obtain a list of the names, size, andlocation of macro definitions in libname MACLIB, the command
MACLIB LIST libname may be issued.
To print out the actual
macro definitions, refer to the procedure described in
MACLIB under "Libraries".
The CMS macros described in this section deal primarily withlinkage to the CMS disk and terminal handling routines.
TYPE and TYPIN handle terminal I/O, and FCB, STATE, SETUP,RDBUF. WRBUF. CKEOF, ERASE and FINIS handle I/O to thepermanent disk. The offline unit record devices may beaccessed from an assembler language program by calling the
OFFLINE command, as explained previously under "Linkage to
CMS Commands and Routines".
The TYPE and TYPIN macros each set up a parameter list inline and issue a CMS supervisor call.
For disk I/O, theparameter list is set up in a constant area by the FCB (FileControl Block) macro, and the label of that macro is used
as a parameter of the WRBUF, RDBUF, SETUP and STATE macros
which issue CMS SVC instructions for linkage.
If anexisting file is to be read, STATE and SETUP must be
executed before the first RDBUF to initialize the first FileControl Block. Figure 26 shows a typical sequence of macros
for writing and reading disk files.
Notes:
a. The TYPE and TYPIN macros generate parameter lists inline with executing code.
If either macro is to be used
repeatedly,. it may be more efficient to set up a single
parameter list and 1ssue CMS SVc·s to call the routines
directly. See "Linkage to CMS Commands and Routines·.
b.

CMS closes user files on program completion.

c.
The CMS macros
alphabetical order.

276

d~scussed

in

CMS Macros

this

sectionareinSTMT SOURCE STATEMENT
1 BEGIN CSECTPRINT NOGEN2ESTABLISH ADDRESS ABILITY
3
BALR 12,0
USING *.12
4
INITIALIZE INPUTSTATE SINPUT " ERR1
5
FILE CONTROL BLOCKSETUP INPUT
9READ A RECORD
15 RD
RDBUF INPUT.ERROR=EOF
WRITE SAME20
WRBUF OUTPUT I, ERROR=ERR2
REPEAT TO END
25
B
RD
REALLY EOF?
26 EOF
C1<EOF ERR3
29
SR
YES.CLEAR ERROR RETURN
15.15
14
RETURN TO CMS
30 DONEBR
31 ERRl
TYPE 'FILE NOT FOUND'
45 ERRET LA
INDICATE ERROR RETURN
15,.1
46
B
DONE
47 ERR2
TYPE tERROR WRITING'
61
B
ERRET
'ERROR READING'
62 ERR3
TYPE
76
E
ERRET
77 INPUT FCB(FILE1" DCL) , BUFF1(FILE2,DCL);BUFF1
95 OUTPUT FCB
113 BUFFl DS
CL80
114
END
BEGIN
=CLStRDBUF'
115
116=CLS'WRBUP'=F'12t117
Figure 26
An example of CMS I/O macros in an assembler language
program. This program copies the file FILE1 DCL PSI' andass1gns the new copy the identifiers FILE2 DCL P5.
TheSTATE and SETUP macros are executed for the existing file toinitialize the File Control Block. These are not needed forthe output file., since it is being created.
The program
then alternates reading and writing records, until the RDBUF
at Statement 15 returns the end of file error code. Control
then goes to the CKEOF at Statement 26, which tests whether
end of file or some other error has occurred. If it is endof file" the error return register is cleared, and control
returned to CMS via Register ill. If an error occurs;, anappropriate response is typed. and a value is placed in
Register 15 to indicate to CMS that an error condition
exists. In any case, CMS closes both files when the program
is completed.

CMS Macros

211

CKEOF Macro
Purpose:The CREOF macro checks the return code from RDBUF for theend of file indication. Any other value is considered anerror.
Format:
label

CKEOF

erlabel1label

specifies a statement label.

erlabelspecifies an error-handling routine.

Usage:The label of the CREOF macro is normally the ERROR=
parameter of the RDBUF macro. CKEOF checks for a value of
12 in register 15. indicating end of file'. If any othervalue is present (including zero). CREOF branches to thespecified error routine.
ExamEle:RDBUF A17.ERROR=DONE

DONE
CONT

CREOF ERRR

ERRR

TYPE

-ERROR READING 1\17'

BR

14

..

This sequence of instructions
gives control to CKEOF
whenever register 15 is non-zero on return from RDBUF. If
the error return indicates end of file. execution continues
with CONT. If some other error has occurred. CKEOF branches
to ERRR. where a response is typed and control returned to
CMS. Note that the value in register 15 is typed by CMS only
if it is saved and restored around the TYPE macro. If thisis done ~egister 15 is displayed in the error completion
response:E(nnnnn)i T=n.nn/nn.nn hh.mm.ss

278

CREOF MacroCMSREG Macro
Purpose:The CMSREG macro equates symbolic names
registers and floating-point registers.

to general-purpose

Format:CMSREG
Usage:The CMSREG macro-instruction equates the following symbolic
names
to
the
corresponding
general-purpose
andfloating-point registers. This allows the symbolic names tobe used in place of the register designations.
General-Purpose Registers
RO
R1
R2
R3
R4

R5
R6
R7
R8
R9
Rl0
R11
R12
R13
R14
R15

EQU
EQU
EQO
EQU
EQU
EQU
EQO
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU

0
1
2
3
4

5

6
7
8
9

10
11
12
13
14
15

Floating-Point Registers
FRO
FR2
FR4
FR6

EQU
EQU
EQU
EQU

0
2
II

6

C~SREG

flJacro219

CMSYSREF Macro
Purpose:The CMSYSREF macro allows users to branch to routines in the
CMS nucleus which cannot be called by eMS SVC's.
Format:
CMSYSREF
Usage:The CMSYSREF macro instruction generates a series of EQU
statements which provide the addresses of various CMS
nucleus routines not available via a supervisor call. The
addresses of these routines are listed in a nucleus module
whose entry point is SYSREF. The name of each nucleus
routine;. with a D prefixed to it. is equated to its
displacement from SYSREF in the macro expansion.
Note:
In all programs in which the CMSYSREF macro is
SYSREF must be declared in an EXTRN statement.

called,Example:The following example shows how to call the SETCLK function.
SAMPROG

CSECT
EXTRN

SYSREFL
L

5. = A (SYSREF)
15, DSETCLK (5)14.15
15.,15
ERRET

BALR
LTR

BNZ
CMSYSREF

In the expansion of CMSYSREF., DSETCLK is equated to thedisplacement of the SETCLK routine in the SYSREF list. The
address is loaded into register 15 for the BALR
andregister 15 is checked for an error code after control
returns to SAMPROG.
SETCLK is a routine that saves thecurrent value of the timer for subsequent use. as describedin the CMS Program Logic Manual.
j,

280

CMSYSREF MacroERASE Macro
Purpose:The ERASE macro provides linkage to the ERASE command. whicherases the specified file from the user's permanent disk.
Forroat:<label>

ERASE

fcb

label

is an optional statement label.

fcb

is the label of theto be erased.

FCB which identifies the file

Usage:The ERASE macro allows thepermanent disk.

user toerase any fileon hisNote:
To erase a disk file with a filemode other than P~ the user
may set up a parameter list and call the ERASE commanddirectly. as explained under "Linkage to CMS Commands andRoutines".
Example:ERASE INPUT
The permanent disk file identified by the FeB labeled INPUT
is erased. For example. if the macro
INPUT FCB (INFILE.DATA). BUFF
has been issued. file INFILE DATA Pn is erased.

ERASE Macro

281

FCB Macro
Purpose:The FeB macro generates a eMS File Control Block, which
serves as a parameter list naming and describing disk files
for the eMS I/O routines.
Format:label I FCB I (filename, filet ype) "area I
label

is a statement
characters.

label ofseven or(filename,filetype) specify the name and type ofMode * is assumed.
area

less

the file.

is the label of the input or output areain the program.

Usage:A File Control Block is needed for each disk file referenced
in a program. The label assigned to the FCB macro is aparameter of the SETUP, RDBUF"
and WRBUF macros.
The FCBlabel with an S prefixed is a parameter of the STATE macro.
Before the FCB can be used for input files, the STATE and
SETUP macros must be executed.
No initialization is neededfor output files being created.
Included in the parameter list generated by FCB is an item
number field. This specifies the record of the file beingreferenced.
If unchanged, records are read sequentiallyfrom first to last, and written in the same order.. Records
are added to the end of existing files.
However, if anumber is specified in the itero number field, the item
specified is read or written. The field is a half word at
LABEL+26, where LABEL is the FeB state~ent label.
Example:INPUT FCB (INFILE,DATA),BUFF
Expansion ofthis macro
generates aparameter list
referencing INFILE DATA. Before a RDBUF macro can use this
FCB for input, the following sequence must be executed:
STATE SINPUT,ERRORSETUP INPUT
No initialization is needed for output. Data is read into
the area labelled BUFF unless a different area is specified
with RDBUF .•282

FCB MacroFINIS Macro
purpose:The FINIS macro provides linkage to the FINIS command" whichcloses the specified user file by clearing its entry fromthe active file table.
Format:< label >

FINIS

fcb

label

is an optional statement label

fcb

is theclosedlabel ofthe FCBnaming thefile tobe

Usage:The FINIS macro closes the permanent disk file identified by
the FeB whose label is given as an operand of the macro..
Note:eMS closes files automatically at program completion.
Example:FINIS INPUT
The permanent disk file identified by the FeB labeled INPUT
is closed. For example. if the macro
INPUT FCB (INFILE/.DATA) ,BUFF
is issued, file INFILE DATA Pn is closed.

FINIS Macro

283

RDBUF Macro
Purpose:RDBUF reads a record from a disk file.
Format:I <label> I RDBUF I fcb <,AREA=alabel><,ERROR=elabel> I
label

is an optional statement label

fcb

is the lahel of the FCB naming the file to be readalabelis the label of an input buffer.
area specified in the FeB is usedelabelis the entry of an error-handling routine.
omitted, errors, including endof file,ignored.

If omitted, theIf
areUsage:RDBUF returns one item each time it is executed. The item
returned is specified by the item number field of the FileControl Block at FCB+26. This number is incremented eachtime RDBUF is executed.
It may be set to any value,
allowing direct access to files.
The file read may have fixed or variable length records i• but
the buffer named AREA= must be large enough for the longest
record in the file. The buffer named with RDBUF overrides
that specified in FCB if it is different.
Each time RDBUF is executed, it links via a CMS SVC
instruction to a routine that returns control when therecord requested bas been read in. If no error occurs,
register 15 is set to zero on return. If an error or end of
file occurs, register 15 contains a code indicating the typeof error,. See Figure 21 for a list of RDBUF error returns.
If ERROR1 is supplied, control goes to that point on anerror. If no label is supplied, control returns immediately
following RDBUF. regardless of error.. Note that end of fileis always consid'ered an error.
An error handling routine
should start with the CREOF macro, to detect end of file ..

284

RDBUF Macro

COLE

MEANINGno errorfile type not foundbuffer area not in coredisk error
illegal mode letter
item nurober is 0
no core available
file not in correct format
buffer too small (truncated item)
file open for writing
incorrect number of items
end of filemode number invalid

o

1
2
3
4

5
6

1
8
9
11

12
13

Figure 27.

RDBUF error return codes(returned in register 15)

Example:
READA
NEXT

RDBUF INFIL,AREA=BUF,ERROR=EOF

EOF

B
READA
CREOF ERREAD

BUF
INFIL

DS
FCB

CL80

(ELIPR, DATA) " BUF

Assuming that the RDBUF macro is preceded by a STATE SINFIL
and a SETUP INFIL. this sequence reads successive items fromthe file ELIPR DATA Pn. Items are placed in BUF" andcontrol returned at NEXT. When end of file is reached,
control goes to EOF where CKEOF checks for a 12 in register
15. If any other value is in register 15, control goes to
ERREAD.

RDBUF Macro

285

SETUP Macro
Purpose:SETUP initializes the FCB with information frompermanent file directory.

the user's

Format:
label

SETUP

fcb

label

is an optional statement label

fcb

is the label of the FCB to be initialized

Usage:SETUP is executed following STATE to initialize the FCB.
Record length and record format (fixed or variable length)
are filled in. SETUP should not be executed if STATE
returns with an error code in Register 15 indicating thefile was not found in the directory.
Example:SETUP A17
This initializes the Filegenerated by the macro:
A17

286

FCB

Control(NAME.TYPE) I• . BUFFER

SFrUP Macro

Block which

has

been

STATE Macro
Purpose-:The STATE macro provides linkage to a CMS ,routine which
searches the user·s permanent disk directory for a specified
file.
Format:I<label> I STATE 1 Sfcblabel,error I
label

is an optional statement label

Sfcblabelis the label of the FCB being referenced with an
S prefixed to iterror

is the label
returnof a routine

to handle

an error

Usage:
STATE should be executed before any existing file isreferenced for input or output-.
STATE places the directory
address of the specified file in the FeB. From this entry,
SETUP initializes the FeB.
If the file specified is not found in the user·s file
directory, STATE returns control at the point specified by
the second parameter.
Note:
STATE is not needed for files being created.
Example:ENTER STATE SA11.ERROUT
This causes a search of the permanent file directory for the
file described by the FCB macro with the label A17. If it
is found. the address is filled in the FeB: if not. control
goes to ERROUT.

STATE Macro

287

TYPE Macro
Purpose:TYPE generates a parameter list and issues a CMS supervisor
call to type a line of terminal output.
Format:I
I
I ' 'message- (r)I <label> I TYPE I
I
II
I msglabel nIlength I
I
I
I
label

an optional statement label'message'the message to be typed

msglabel

the label of an area
typed is located(r)a registermessage arean

is a self-defining term
the message area.

lengththe label of a full or half word constantcontaining the length of the message area

where the message to becontaining thelengthofthegiving the length of

Usage:The maximum message length is 130 characters. If the actual
message is specified in single quote marks with the macro,
the length parameter is not used. If the label of an output
area is specified instead of the message itself, the length
must
be included.
Length may
bespecified asaself-defining term (a decimal number or an equated symbol),or as the label of a full or half word constant containing
the length. If length is not known until execution time,. a
register containing
the length
may bespecified inparentheses.
Notes:
a. Issuing a TYPE macro specifying the message to be typed
in single quotes is equivalent to issuing a CMSTYPE macro
specifying the same message.

h. The GEN macro is included in SYSLIB MACLIB for
the TYPE macro" and is not meaningful for use inprogram.

288

TYPE Macrouse bya userExamples:a.
ERR1
TYPE 'ERROR WHILE READING'
The message ERROR WHILE READING is typed at the terminal.
b.

TYPE MSG.LTH
MSG
DC
C' EXECUTION BEGINS,. '•• •LTH
EQU *-MSG
The message EXECUTION BEGINS ••• is typed.

TYPE Macro

289

TYPIN Macro
Purpose:TYPIN reads a line of input from the terminal.
Format:I <label> I TYPIN I

area <.lenqth><.ED=c>label

an optional statement label

area

the label of a 130-character input buffer

lengthan optional label to be assigned to athree-byte field of the parameter list where
the number of characters read is placedca one-character code specifying the editingof the input line to be performed by eMS
before returning control. If omitted. U is
assumed.

Editing Codes
U

interpret delete characters,. translate to upper
case. pad with blanks to 130 characters.

vinterpret
upper case ..

S

interpret delete charactersr, padto 130 characters.

deletecharacters,Tinterpret delete characters.

Xdo, not edit the line.

translatetowith blanks

Usage:TYPIN generates a parameter list and issues a eMS supervisor
call to read a line from the terminal.
The input area
specified must be 130 characters long.
The number ofcharacters read is filled into a thre~byte area in theparameter list. This number may be accessed b¥ specifying alabel as the second parameter of the macro. This number isalways the number of characters read, whether or not therecord has been padded to 130 characters with blanks.
~he

ED=parameter allows the user to select which of the eMS
editing functions are to be performed on the line.
The
delete characters (8 and e) have their normal eMS meaning
if U, V, S, or T is specified_
Alphabetic data istranslated to upper case if U or V is specified. The buffer
290

TYPIN Macroarea following the characters read is set to blanks (hex'40') if U or S is specified. The X option returns the line
exactly as typed. U is the default option.
Note:
The number of bytes read field is in the low-order threebytes of a full word. For example" if the label specified
is LAB. the number may beobtained by a LOAD HALF
instruction from LAB+1.
Examples:a.

RD

TYPIN BUFF1. LNGTHNEXT LH

2"LNGTH+1

BUFF1 DS
CL130
This sequence reads aline from the terminal into BUFFl.
Since no ED= option is specified, U is assumed.
Deletecharacters are interpreted, the length adjusted, lowercase
letters translated to uppercase!, and the buffer behind theline set to blanks before control is returned at NEXT,. The
LB instruction places the number of characters read into
Register 2.
b.

GET

TYPIN B,ED=X

B
DS
33F
This macro reads a terminal line into B.
The X option
indicates that no editing is to be performed on the line.

TYPIN Macro

291

WRBUF Macro
Purpose:The waBOF macro creates, updates, or expands disk files.
Format:l<label>I~RBUF'

fcb <,AREA=alabel><,ERROR=elabel> ,label

an optional statement label

fcb

a label referencing
output filealabelthe label of an area from which data is to be
writtenelabelthe label of an error-handling routine

the FCBdescribing theUsage:
normally is used to create, a new sequential file or to
add to the end of an existing file.
However, any record ofan existing fixed-length record file may be replaced byadjusting the item number field at FCB+26.

~BUF

~he

AREA= parameter may be omitted with WRBUF if specified
in the FCB. If specified in both places;, WRBUF takes
precedence.•
Control is normally returned with register 15 set to zero,
indicating error-free completion.
If an error occurs,
register 15 contains a code indicating the nature of theerror. and control is returned wherever specifi..ed by the
ERROR= parameter. If no ERROR= is included, errors are
ignored. See Figure 28 for a list of WRBUF error returns.
Example:WRBOF 17.AREA=ITEM,ERROR=QOIT
•
QUIT
BR
14
ITEM
DS
CL80
A17
FCB
(INTR,.JBH) ,ITEM
This sequence writes successive items into INTR JBH Pn,. On
an error control goes to QUIT" which returns to CMS. The
error code is printed in the CMS error completion response.

292

WRBUF Macro

Code

o
1

2
3
4

5
6
7
8
9
11

12
13
14
15
16
17
18
19

Meaning
no errors
filename missing
buffer area not in coredisk error
illegal mode letter
illegal mode number
no core available
skipping variable item
length not specif~ed
file open for reading
fixed or variable not set
mode SY illegal
disk is full
read-only file
item wrong length
F-V changed
65K length limit on itemno .• items more than 1 for V-format
no.. i terns equal zero

Figure 28.

WRBUF return codes returned in register 15

WRBOF Macro

293

OS MACROSThe OS macros that are used by the cambridge Monitor System
are contained in the file OSMACRO MACLIB SY, which resides
on the system disk.

a list of the names, sizer, and location of themacro definitions in OSMACRO MACLIB, the command MACLIB LIST
OSMACRO may be issued. To print the macro definitions,refer to MACLIB under wLibraries·.

'1'0 obtain

The OS macros supported under CMS are listed below.
Note that only the forms of the following macros used by thelanguage processors are supported under CMS. Programs
using os macros not listed or using. unsupported forms of thefollowing macros wi11 not run correctly under CMS.

os

ABEND
ANALYZASGNBFR
ASM'l'R'l'AB
ATTACH
A'I'TNINQ
BLDL
BREAKOFFBSP
BUFFER
BUFINOBUILDCALLCAMLS'I'
CANCELM
CATALOGCHAPCHECK
CHGN'I'RY
CHKPT
CHNGP
CHNGT
CIRE
CKREQ
CLOSE
CLOSEMC
CNTRL

COpyp
COPYQ
COPY'!'
COUN'I'ERDARDATES'fMP
DCB
DELETEDEQ
DETACHDEVTYPE

294

OS Macros

DFTRMLST
DIRECT
DLIST
DOM
DUMP
ENDRCU
ENDREADYENDSEND
ENQ
EOA
EOB
EOBLC
EOV
ERRMSGNOTEOACBOBTAINONLISTOPCTL
OPEN
OPTION
PAUSE
POINT
POLL
POLLIMITPOST
POSTRCVPOSTSEND
PROCESS
PRTOV
PUT
PUTX
RCVE ITA 2RCVEZSC3
RCVHDRRCVSEG
RDJFCBREAD
RELBUF
RELEASEfJJ
RELEX
RELSE
RENAMEREQBUF
REROUTERESERVERESETPLRETRIEVE
RETURNRJELINERJETABLRJETERM
RJEUSERRLSEBFR
ROUTE
SAEC
SAVE
SCRATCH
SEGLD
SEG'WTSENDHDRSENDITA2SENDSEGSENDZSC3SEQIN
SEQOUTSETSETL
SETPRT
SRIP

ESETL

EXCP
EXTRACTFEOV
FIND
FREEBUF
FREEDBUF
FREE MAIN
FREE POOLGETGETBUFGETMAIN
GET POOLIDENTIFYIECTDECBIHBERMACIHBGAMl
IHBGAM2IHBGAM3IHBINNRAIHBINNRBIHBOPLSTIHBRDWRDIHBRDWRKIHBRDWRSIHBRDWRT
IHB01
IHB02
INDEX
INTERCPTIOHALTLABELLERBLERPRT
LINK
LOAD

LOCATELOGSEGLOPENLPSTART
MODE
MSGTYPEOS Macros

295

SMFWTM
SNAP
SOURCE

SP1\R
SPIE

STAE
STARTLNSTIMERSTOPLNSTOWSYNADARSYNADRLSTERM
TERMTBLTEST
TI~E

TIMESTMP
TRACE
TRUNC
TTIf.~ER

TWAIT
WAIT
WAITR
WRITE
WRU
WTL

WTO
wrOR
XCTL
XDAP

The following os macros are defined in CMS but do not
perform a function as in OS. They are essentially no-ops(that is. they have no meaning in CMS and return an error
code when the SVC is issued).
ATTACH
CBKPT
DETACH
DEQ
DELETEEXTRACTENQ
IDENTIFY
STlfr1ER

For a discussion of the os macros themselves, refer to IBM
manual" C28-6647 IBM System/360 operating system supervisorand ~ Management Macro Instructions. For a description oftheuse ofthe OS
macrosin CMS
refer tothe
CMS Program Logic Manual.

296

Os MacrosCMS ROUTINES (FUNCTIONS)

Routines that can be called with the SVC X'CA' are called
functions.
These routines serve as the basic interface
between programs and the CMS nucleus.
The calling sequence for all routines is similar. There are
two parts of each calling sequence; the code to transfer
control to the eMS routine, and the parameter list. The
inline code always has the following form
LA
SVC
DC

l,PLIST
X'CA'
AL4(ERR)

put address of para~eter list into GRPl
transfer control to subroutine
address of error return if desired

normal return

Register 15 is the only register that is modified whencontrol is returned to the calling program. On a normal
return, register 15 contains zero q on an error return, it
contains an error code. The error codes are described in
the write-up of each routine. If an error return is
specified, the byte after the SVC instruction is zero andthe following three bytes are assumed to contain the addressof the error return.
If the error return address is
specified, the normal return is to four bytes after the SVC
instruction; otherwise, it is to the location after the SVC
instruction. If no error handling is to be ?rovided. it isrecommended that DC AL4(*+q) be used. otherwise an error
causes DEBUG to be entered.
The PLIST differs for each routine and is described insubsequent sections for each routine.
All functions can becalled directly as eMS commands although many functions
require a parameter list specified in hexadecimal and thus
should only be called from an assembly language program.
The following OMS commands directly call the equivalent CMS
functions and are described under the sections on eMS
commands:
ALTER, CLOSIO~ ERASE, FINIS, GENMOD, GLOBAL, LOAD,
LOADMOD, REUSE, OSE, START,$, DEBUG, EXEC,LOGOUT, IPL. BLIP, LINEND
See -Assembly Language Programming- for PLIST format.
The commands ALTER, ERASE, BLIP, and LINEND should be calledfrom an assembly language program as functions if it isdesirable to specify a character that cannot be typed from akeyboard.
The functions STATE and TAPEIO are useful as commands aswell as functions. When called as a function, ST~TE returns
the address of a copy of the file status table that can beused in further processing. When called as a function,eMS Routines (Functions)

297

TAPE10 reads or writes a tape record.
The use of thefunctions as commands is described under the section on CMS
commands. The PLIST for the functions below are described in
the following section.
ATTN
CARDIOCONWAITCPFUNCTN
ERASE
FINIS
HNDINTHNDSVC
POINT
PRINTRRDBUF
STATE
TAPE 10
TRAP

TYPE
WAIT
liAITRD
WRBUF

298

stacks a line for terminal input
Reads and/or punches cards
Waits for terminal I/O to finish
Issues CP-67 console functions from CMS
Erases filets)
Closes file(s)Sets or clears I/O interrupt return addresses
Sets or clears SVC handling addresses
Sets read or write pointerPrints line
Reads item(s) from disk
Queries file status
Handles tape I/O
Sets external interrupt address
Writes to terminal without carriage return
Waits for interrupt
Reads terminal
Writes item(s) on disk

C~S

Routines (Functions)

ATTN Function
Purpose:The ATTN function stacks a line into the input buffer.
Calling Sequence:
PLIST

DS

DC
DC

DC
DC

BUFF
LBUFF

DC

EQU

OD

CLStATTN t
CL4 t order eALl (LBUFF)
AL3(BUFF)

LIFO or FIFO

Ctline t* - BUFF

Usage:The line that is stacked is unstacked and used when a callto WAITRD is made to read a line from the typewriterconsole. Any number of lines may be stacked for subsequent
use as terminal input. When the input stack is empty. thekeyboard is unlocked to receive typewriter input.

ATTN Function

299

CARDIO Function
Purpose:CARDIO function punches a card from the specified 80
byte area,. or reads a card (or prints a line) into thespecified 80 (or 132) byte area.

~heCalling Sequence:
PLIST

CLSX'flag'

DC

DC
DC

DC

DC

AL3(buffer)
H'no. bytes to be read'
H'O'
no. of bytes read

Error Codes:
E(OOOOl)
E(00002)
E(00003)
E(00004)300

CARDRD or CARDPH
X'OO-: standard reader
X'80': non-standard reader or
extended PLIST

End of file
Unit Check
Unknown error
Not operational

CARDIO Function

CONWAIT Function
Purpose:The CONWAIT function ~aits for all stacked reads and writes
to finish from the console typewriter.
Calling Sequence:
PLIST

DS
DC
DC

OD
CLS·CONWAIT·
CL4-CON1-

Usage:
CONWAIT is called as a standard CMS function.
'CON1' corresponds to the console typewriter.

The device id

Error Returns:
None.

CONWAIT Function

301

CPFUNCTN Function
Purpose:The CPFUNCTN function transmits console functions
without leaving the virtual machine mooe.
Calling Sequence:

PLIST

DS

OF

DC
DC
DC
DC

CLS - CPFUNCTN'-

CLS-NOMSG e This parameter may be omitted
CLn·CP command stringX-FF e fence

Error Codes:
E(OOOOl)No CP command string present

E(00004)

INVALID CP REQUESTE(OOOOS)BAD ARGUMENT

E(xxxxx)

Any other error codes are from the
CP console function specified.

302

CPFUNCTN Function

to CP-67

ERASE Function
Purpose:The ERASE function erases the specified file(s).
Calling Sequence:

PLIST

DS

OF

DC

CLS'ERASE'

DC

DC

CLS'
CLS'

DC

CI.2'

•
•

•

called routine
filename or *filetype or*mode or *Error Codes:
E (00001)
E(00002)EC00004)

First character of mode illegal
File not found
Disk error

ERASE Function

303

FINIS Function

Purpose:The FINIS function closes the specified file(s).
Calling Sequence:

PLIST

DS
DC
DC
DC
DC

OD
CLS'FINIS',
CLS'
,
CLS'
•
CI..2'

called routine
filename or *filetype or* *mode letter or

Note:
FINIS does not update the directory on the disk.
Error Codes:
E(OOOOl)

E(00002)
E (00003)
E(OOOOlJ)

E(00006)

304

Invalid filename
Invalid filetype
Disk error
Invalid mode
File not open

FINIS FunctionHNDINT Function
Purpose:The HNDINT function sets the CMS I/O interrupt handlingroutines to transfer control to a given location for an I/O
device other than those normally handled by CMS. or clears
such transfer requests.
Calling Sequence:
PLIST

DS
DC
DC

IODEV

DC

OF
CLS'HNDINT,tcalled routine
CL4'SET' or CL4'CLR'
function
NAME, NUMBER. ADDRESS,
ASAP/WAIT-FLAG,KEEP/CLEAR-FLAG

X" FFFFFFFF'

end of list

Macro IODEV:The IODEV macro
12-byte field:

sets

up thefollowing

information ina

NAME = Symbolic device name (1st 4 letters)
NUMBER = Hexadecimal device address
ADDRESS = Symbolic address of interrupt-handler tobe invoked. If address = 0, interrupts
are ignored when received.
ASAP/WAIT-FLAG:
ASAP = Invoke interrupt-handler iwmediately
WAIT = Invoke interrupt-handler only when
WAIT is called
KEEP/CLEAR-FLAG:REEP = Retain interrupt-handling between CMS
commands
CLEAR = Clear interrupt-handling after each
CMS command. CLEAR is the default.
Example:IODEV

NEWD. 381;, MYCODE" ASAP,. KEEP

Usage:
When an interrupt is received and processed by' 10INT' " itpasses control to the interrupt-handler as follows:
Register 0,,1
2,3
4

14
15

I/O OLD PSW
CSW
Device address
Ret-.urn address to IOINT
Address of interrupt-handler

HNDINT Function305When processinq is complete. the interrupt-handler must
return to IOINT via register 14,. with Register 15 as
follows:
means SUCCESSFUL HANDLING
R15 = oNonzeromeans ANOTHER INTERRUPT EXPECTED .•R15
The generalfollow.

procedures for

1.
The program must
HNDINT SET.

CMS I/O

handling using

initialize handlingto be

HNDINT

done via

2.
~hen I/O
to the appropriate device is to be done"
system-mask must be set OFF by SSM instruction andappropriate SIO given.

3. When SIO is performed satisfactorily,
can be set to allow all interrupts.

the
the

the system-mask

4a. If ASAP is specified~ the interrupt-handler is invoked
as soon as the interrupt is fielded by CMS IOINT.
The
interrupt-handler returns to IOINT which returns to users
program.
4b.
If ASAP is not
specified. IOINT retains
information until the CMS WAIT function is called.

needed5.
'When the program needs the int"errupt to have been
received. the CMS WAIT function is called.. If the interrupt
has not yet been received. CMS goes into the WAIT state
until IOINT fields and processes the interrupt in the normalway.

If the interrupt has been received and processed (forexample. on ASAP). WAIT returns to the caller with thenecessary internal flags cleared.
If the interrupt has been received but not yet processed asunder the WAIT option rather than ASAP, CMS WAIT calls IOINT
to invoke
the desiredinterrupt-handler. clears
thenecessary flags, and returns to the caller.

6.
~henfinished. the user program should clear theinterrupt-handling scheme through the HNDINT CLR call. If
the KEEP option is used. the interrupt-handler remains
intact in core.
Error Code:E(OOOOl)

306

Incorrect parameter list

HNDINT FunctionHNDSVC Function
Purpose:The HNDSVC function initializes the SVC-interrupt handler totransfer control to a given location for a specific SVC
number--other than X'CA w or 202--or clears such previous
handling.
CallinQ Sequence:

DS
PLIST

DC

DC
DC

•

DC

OF
CLS·HNDSVC·
called routine
CL4·SET· or CL4'CLR'
function
AL1(SVC-number).AL3(SVC-handler)

X'FFFFFFFF'

end of listusage:At entry to a non-CMS
conditions exist:

SVC-handling routine

the following

Registers
0-11 and 15 as they were at SVC tirre
12
address of SVC-handler routine
13
address of SVC save area
14
return address to SVCINTThe SVC save area has the following fonnat:
Eytes

Contents

0-63
64-71
72-95
96-175*FPR 0caller·s registers 0-15
SVc-old-PSW
floating-point registers 2~4.6*
80 bytes for use by SVC-handler
is saved elsewhere by CMS.

Notes:a.

For CLR the address fields are irrelevant.

h.
Individual SVC-numbers may be added or cleared at
different times but should all be cleared before terminationof the command.
Error Codes:
EC00001)
EC00002)
E (00003)

Incorrect PLIST
SVC-number replaced another of the same number
SVC-number cleared was not set

HNDSVC Function

301

POINT Func.tion
Purpose:The POINT function sets the read pointer and/or
pointer at a specified item number.

the write

Calling Sequence:
PLIST

OS
DC
DC
DC
DC

DC
DC

OD
CLS'POINT'
,
CLS,
CLS'
•
CL2'
•,
H'
H'

called routine
filename
filetypemode or *write pointerread painterUsage:
This routine sets the read or write pointer in the filestatus table to a value provided by the caller. Zero leaves
the pointer unchanged; a value of H'-1'(X'FFFF') sets thewrite pointer to the last item number plus one.
Error Codes:
E(OOOOl)
E(00002)308

File specified does not exist
First character of mode illegal

POINT Function

PRINTR Function

Purpose:The PRINTR
printer.

function writes

a line oftext onthe offline

Calling Sequence:
PLIST

DS
DC
DC

DC

00
CLS·PRINTR·
A(bufsiz)buffer area
buffer size
F· •Notes:
a.
The first byte of the buffer is used for carriage
control and is not printed. The carriage controls are:CL1- •
CLl·O·
CLl'l·
CL1·_·
CLl'.CL1,e n -single spacedouble space
page ejecttriple space
write, no space
skip to channel nb. Machine CCW OP code carriage
assembler are also accepted.

controls as usedby thec. The buffer size should not exceed 133 bytes.
If thebuffer size is 1. only the carriage control function will
occur.
Error Codes:
Ee00001)
E(00002)EC00003)
E(00004)
E(OOOOS)

Printer unit check
Illegal carriage control
Incorrect parameter list
Not operational
Unknown printer error

PRINTR Function

309

RDBUF Function
Purpose:The RDBUF function reads an item
file.

of information from a disk

Calling sequence:
PLIST DS OD
DC CLS ' RDBUF'·
DC CLS' ••,DC CLS'
DC CL2' ,DC H'
DC A (userarea),
DC F'
DC CL2'F'
,
DC H'
•
DC F'

called routine
filename
filetypemode or*item number
pointer to input buffer
number of bytes in buffer
fixed-variable flag (F or V)
number of items to read
number of bytes actually read

Notes:
a. All errors except error 8 cause the function call to beaborted. On error code 8 that portion of the item that fits
in core is read.
b. The number of bytes in the user area divided by the
number of items (that is. the same logical record length)
must be constant for a fixed-length-record file.
Error Codes:
E(OOOOl)
E(00002)
E(00003)
E (00005)
E(00007)
E(OOOOS)
E(00009)
E(00011)E(00012)E(00013)310

File not found
User's memory address is illegal
Disk malfunction has occurred
Number of items equal zeroFile not written with WRBUF therefore it
cannot be read
User's memory area too small for item
File open for writing and therefore
cannot be read
Number of items greater than 1 for variablelength file
Item number specified does not exist (EOF)
Variable file has invalid displacement in
Active File Table

RDBUF Function

STATE Function
Purpose:The STATE function provides a copy of the FST (file status
table) block for the' file specified in the parameter list .•Calling Sequence:

PLIST

DS
DC
DC
DC
DC

PRETN

DC
DC

OD

CLS'STATF e
•
CLS'
CLS·

eL2'
CL2'
A(*)

,

e
t

called routine
filenatre
filetypemode letter or *unusedaddress of copy of FST
block returned

Notes:
a. PRETN is set to the location of a copy
status table entry if the file is found.

of thefile

b. Mode * means that the £irst file found with name andtype specified is used. The standard order of search isused.
Error Cedes:
E(00001)
E(00004)

File specified doesnet exist
First character of mode illegal

STATE Function

311

TAPEIO Function
Purpose:The TAPEIO function
positions a tape.

reads

or writesataperecordorCalling Sequence:
PLIST

COUNT

DS
DC
DC
DC
DC
DC
DC
DS

00
CLS'TAPEIO"
CLS'function'
CLq'deviceid'
XL1'modeset'
AL3(buffer)
F'size'F

Symbolic tape address
7~track mode set
Buffer address
Buffer size
Number of bytes read

Functions are:

BSF
BSR
FSF
FSR
READ
REWINDRUN
WRITE'WRITEOF
WTM
ERG

backspace one filebackspace one record
forward space one fileforward space one record
read one record
rewind the tape to load point
rewind and unload the tapewrite one record
write a tape markwrite a tape markerase a gap

Device ID's are:
TAP1 or TAP2 corresponding to 180 or 181
The modeset code is one byte of the form
DD~MM011

with the following interpretation

DD
00
01
1,0
11

7 track density
I 200
I 556
I 800
I SOO

MMM

I
I
I
1
I
I
I
t
I

000
001
010
011
100
101
110
111

312

Function
not used
not used
set density,
not usedeven parity,
set density,
set density,
set density,,,

odd parity" converter on!. translator off
converter off,,, translator off
even parity, converter off, translator on
odd parity" co~verter off, translator off
odd parity. converter off" translator on

TAPEIO Function

Usage:
The function TAPEIO is used to read, write or move magnetic
tape~ If
the WRITE function is used, the number of bytes
indicated is written..
If the READ function is used.,
information is moved into the buffer and the number of bytes
read is stored into COUNT. If a tape mark is read" thefunction returns with error code 2.
Notes:
a. A mode set of X·OO· causes the default mode bit of X·B3·
to be used.
b. A rnode set of X·B3' indicates density
converter off, and translator off.

800, parity odd,c.
A mode of X·93' indicates density
converter on, and translator off.

800, parity

odd,

Responses:
TAPn NOT READY YET
The tape has been attached but it is not in a ready status.
(OK - READY NOW)
The tape is now ready for use.
Error Codes:
E(OOOOl)INVALID ·TAPEIO READ' PARAMETER-LIST
An invalid parameter list was specified for reading tape .•E(OOOOl)INVALID 'TAPEIO WRITE' PARAMETER-LIST
An invalid parameter list was specified for writing tape.
E(00002)
An end of file or end of tape has occurred.
E(00003)
A permanent I/O error has occurred while reading or writing.
E(00004)

An illegal symbolic device id was specified.
E(OOOOS)TAPn NOT ATTACHED
The tape unit has not been attached to the virtual machine .•Refer to ·Operating Considerations - Tape Procedures·.
E·(00006)
TAPn IS FILE PROTECTED
The tape contains a file-protect ring.
be written on.

Therefore it can not

TAPEIO FUnction313

E(00001)
TAPn - SERIOUS TAPE ERROR ATTEMPTING function
An unrecoverable tape error has occurred while attempting
the specified function.

314

TAPEIO Function

TRAP Function
Purpose:The TRAP function sets a user·s return for an externa1
interrupt. This return overrides the call to DEBUG on an
external interrupt.
Calling Sequence:
PLIST

DS
DC
DC

on
CLSeTRAp·

ACtrapsubr)

where trapsuhr is the location transferred to on an externalinterrupt. If the parameter trapsubr is a zero, the returnis reset to go to DEBUG on an external interrupt.
Usage:The user·s interrupt routine should set a flag which should
be examined by the main line program.
After the flag is
set this routine should return to the location specified in
GPR14 on entry. All other general registers can be used as
desired. The main line program should periodically examine
the trap flag to determine whether an external interrupt has
occurred.
l•Error Returns:
None.

TRAP Function

315

~YPE

Function

Purpose:tt'he TYPE function types an output message on the console.
Terminal blanks (if any) are not deleted and no carriage
return is added.
t•Calling sequence:
DS

PLIST

DC

DC
DC
DC
DC

OF
CLS-TYPEAL1(1)AL3(MSG)
C·codeAL3 (EMSG-MSG)

terminal number
address of output message
code B or K (see below)
mess~ge length (in bytes)

MSG

DC

C- message to be typed without carriage
return-

EMSG

EQU

*

where the write codes are:B = move line to free storage before typing
K = type line from the specified location
Note:
The output message must be from 1-130 bytes in length.
Error Codes:
E-t-O.OQ.Ol)

Invalid terminal number

E(00002)
bytes

Length316

of output message

TYPE Function

not between 1

and 130

WAIT Function
Purpose:The ~AIT function awaits
specified devices.

aninterrupt

from oneofthe

Calling sequence:
PLIST

DS

OF

DC

CL8·~AIT·DC

CL4·deviceid·

DC
INTDEV

DS

where the deviceid is CON1, DS1<1, PCHl, RDRl,
PRN1. TAP1" or TAP2
Usage:
When one of the specified devices causes an interrupt, thedeviceid is stored in the word INTDEV and control returns tothe calling program.
Error Returns:
E(OOOOl)

Invalid deviceid specified

WAIT Function

317

'WAITRD Function
Purpose:The WAITRD function reads an input message up to 130 bytes
in length into a qiven buffer from a console and waits forcompletion of the input message.
Calling Sequence:
PLIST

OF

DS
DC
DC
DC

CLS·WAITRD·
AL1(l)
AL3(INPBUF)

DCC ·code'terminal number
address of 130-byte
input buffer
U, v~ S~ T, or X
(sef~

INPBUFDS

D~low)

byte count of input
message is stored
here

DC

CL130

130 bytes (or more)
input buffer

An input line can be edited as f01lows: Use the 'at sign' ato delete the previous character, or the 'cent sign' ¢ todelete an entire line up to and.including the cent sign.
Conventions for U#V~

S, T, or X are:

U performs editing. upper-case translation andblank fillingv'performs editing and upper case translation
S performs editing and blank filling
T performs editing only
X leaves input line exactly as is

Notes:
a. If the user has stacked input con.mands, WAITRD accepts
the first stacked input message and moves it to thespecified buffer.
b.
The input
buffer is zero-filled before
initialized, and must be at least 130 bytes long.
Error Codes:
E(OOOOl)

E(00002)

318

Invalid terminal number
Read-type invalid (not U~ V., SI, T, or X)

WAITRD Function

read

is

WRBUF Function

Purpose:The WRBUF function writes one item of information into thefile whose name is specified by the filename and filetypeparameters. If the file does not exist when this function
is first called. a new file is opened and assigned the given
name and type. WRBUF automatically packs fixed-length items
into an SOO byte buffer and writes this 800 byte buffer onto
the disk when required.
Calling Sequence:
PLIST

DC

DC
DC

DC

CLS-WRBUF e
e
CLS,
CLS'
,
CL2'

DC

H'

•

DC
DC
DC
DC

A(

)

F'
CL2'
H'

,
,
e

filename
filetypemode must be specified
not *
item number (0 if next item)
user's buffer address
number of bytes
fixed-variable flag, F or V
number of items to write(0 treated as 1 item)

Note:
The number of bytes in the user area divided by the numberof items (that is, the same logical record length) must be
constant for a fixed-length-record file.
Error Codes:
E(00001)
E(00002)EC00003)
E(OOOOIl)
EtOOo-05)
E(00006)

E(OOOO?)E(OOOOS}
EC000091

E(OOOlO)
E(OOOll)
E(00012)E(00013)E(00014)E(00015)E(OOOl6)
E(OOOl1)

File name or file type not specified
User memory address not in user area
Disk error. The disk might be read-only.
First character of mode illegal
Second character of mode illegal
Attempted to write item whose number
exceeds 65533
Attempt to skip over unwritten variablelength item
Number of bytes not specified
File already active for reading
Maximum number of CMS files (3500) reachedF-V flag not F or V
Mode S (system) is illegal
Disk already full
Goes to KILLEXF instead of returning tocallerAttempt to write a not yet formatted disk
Length of this item not same as previous
Characteristic (P-V Flag) not same asprevious
Variable length item greater than 65K bytes
WRBUF FUnction319

E(00018)
E{00019)320

Number of items greater than 1 for variablelength file
Maximum number of data blocks per file(16060) reached.

WRBUF Function

FORTRAN
Purpose:The FORTRAN command compiles programs written in FORTRAN IV
into machine code, andprovides program listings anddiagnostics.
Format:IFORTRAN I filenamel ••• filenameN «optionl ••• optionN»1

I

F

I

I

filename is the name of a FORTRAN file to be compiled. Up
to 32 separate compilations may be performed byadding filenames separated by blanks.
option is one or more of the eight compiler options.
options:
MAP

includes tables of FORTRAN variables, NAMELIST.
FORMAT statements in the LISTING file.
NOMAP suppresses the tables of variables.

and

DECK generates the TEXT file of object code.
NODECK suppresses the TEXT file.
LIST includes a listing of object code in assembler language
mnemonics in the LISTING file.
NOLIST suppresses the object code listing.
SOURCE includes the source program in the LISTING file.
NOSOURCE suppresses the listing of the source program.
BCD is used if the source program is punched in Binary Coded
Decimal.
EBCDIC is used if the source program is punched in Extended
Binary Coded Decimal Interchange Code.
GO forces compiler processing to completion despite source
statement errors.
NOGO terminates compiler processing when serious errors aredetected.
PRINT prints the LISTING file on the offline printer, anddeletes it.
NOPRINT suppresses printing of the LISTING file.
DIAG types source program errors at the terminal.
NOD lAG suppresses typing of source program errors.

FORTRAN321

usage:The FORTRAN command compiles
files of FORTRAN source
language into machine-language object code. Input files
must have a filetype of FORTRAN and a record length of 80
characters. Up to 32 files may be compiled by one commandby listing the filenames. and each file may contain any
number of routines. each delimited by an END statement.
Each file processed generates one object deck and one
listing.. replacing any previous output files for the same
program.
FORTRAN uses thesource files.

standard order of search

for locating the

The options governing compiler operation and output are
specified in any order in a set of parentheses following thelast filename. One set of options governs all compilations
performed by one command. Each of the eight options has adefault value which is selected when none is specified. The
default values are
NOGO DIAG EBCDIC DECK NOSOURCE NOMAP NOLIST NOPRINT
Any combination of options is valid. but the result ofspecifying more than one value for a single option isunpredictable.
Unsupported or
misspelled options
areignored~If no options are specified. the parentheses are
not necessary. No filenames options,. or comments should beplaced following the closing parenthesis.
l•Diagnostic and error messages produced by the compiler areplaced in the LISTING file (see -output-) I, and" unless the
NODIAG option is speci£ied~ are typed out at the terminal.
The compiler, error messages have two formats, depending on
when the error is detected (see Figure 29). Statements inwhich an error is detected during the statement scan, suchas a syntax error. are typed out immediately. followed by aline with a $ beneath each point at which an error was
detected. The pointer line is followed by the error codesand explanations, numbered from left to right. If an error.
such as an undefined label. is not detected until statement
scanning is completed. the error message is typed" followed
by a list of the labels or variables in error.
If source statement errors are detected. CMS terminates thecompilation with a message and an error code of 32. If the
GO option is specified,. eMS does not terminate processing,although for some conditions the compiler terminates itself.
When processing is completed under the GO option. any error
completion code is the greatest error severity code assignedby the compiler (see -Error Messages·).
Source files read through the offline card reader forcompilation may be punched in either Binary Coded Decimal(BCD)" or Extended Binary Coded Decimal Interchange Code322

FORTRAN(EBCDIC).

If BCD is used, the BCD option must be specified.

FORTRAN Options
The FORTRAN command does not produce a listing file, unlessrequested.
All diagnostics are printed on the console,
unless suppressed by the option NODIAG,. To obtain a FORTRAN
listing file, the options SOURCE, MAP, or LIST must be
specified, and only those options requested are included in
the listing file.
If a listing file is produced, thediagnostics are included.
If only the option NODIAG is
specified, a listing file is produced containing only the
FORTRAN diagnostics.
The PRINT option directs the listing
to the printer and prints only those parts of the listing
requested by SOURCE, MAP, or LIST.
If PRINT is the only
option specified;. only the diagnostics are printed.
TEXT Identification
The characters appearing in columns 13-16 of TEXT files
generated by FORTRAN are as shown below. They are followed
by a sequence number in columns 77-80:
a. for a
subroutine--thesubroutine name

first

four

lettersoftheb. for a main program--the first four letters of thefilename if it is physically the first deck in the file:otherwise. the letters -MAIN.
The letters used for columns 73-76 of a TEXT file also
appear in the middle of the first line of each LISTING page.
In addition. the name of the file appears at the beginningof the second line of each page in the LISTING file.
OutputFiles with the designation wfilename TEXT P5" and "filename
LISTING P5-, where wfil.ename w is the name of' the FORTRAN
input file, are produced for each file compiled. If NODECK
is specified, the TEXT file is suppressed.
The object program in the TEXT file is identical to that
produced by a compiler under the Operating System. andobject decks may be loaded and executed under eMS or OS.
The entry point for the first main program in the file isthe Same as the filename. Subsequent main programs in thesame file all have the entry point MAIN. Subroutines havethe entry point specified in the SUBROUTINE statement,
regardless of their position in the file.
Under the default options (NOSOURCE NOMAP NOLIST) the
LISTING file contains diagnostic messages. and a statementof object program size in bytes (see Figure 30). Statements
in which errors were detected are always included, witherror messages in the same format as they are typed at the
FORTRAN

323

terminal.
If MAP is specified. a table of addresses is generated foreach of seven classifications of variables used in thesource program. The classifications are COMMON. EQUIVALENCE,NAMELISTi' FORMAT, scalar and array variables, and called
subprogram names.
If LIST is specified. a listing of the object program isgenerated.
with relative
addresses"
and
instructionstranslated into assembler language.
The PRINT option causes the LISTING file to be printed on
the offline printer, and then deleted.
If NOPRINT, thedefault option, is specified, the LISITING file is saved on
the pe:t:'Dlanent disk l,
and may be printed with the OFFLINEPRINTCC command or typed out at the terminal with the PRINTF
command.
Notes
a. Previous LISTING and TEXT files with the same filenameas the current FORTRAN input file are deleted, although insome cases they may not be replaced because of different
options or an error termination.
b. If multiple files or a file with multiple routines arebeing compiled, the GO option should be specified to prevent
an error termination of
one compilation deleting allcompilations requested.
Refer~ftces:

The FORTRAN command executes the System/360 Operating System
FORTRAN IV (G) compiler. For information on the FORTRAN IV
language, see IBM System/360 FORTRAN IV Language (C28-6515)
and IEM System/360 Operating System FORTRAN IV Library:
Mathematicaland Service
Subprograms (C28-6810).
For
information oncompiler operationand messages,
see
IBM System/360 operating System
FORTRAN IV(G and H)
Programmer-s Guide (C28-6817), information in this guide on
Operating System job control language and data management is
not applicable under CMS; the LOAD, NAME=, and LINECNT=
options are not supported.
Responses:
Source statement errors and compiler messages are typed at
the terminal unless NOD lAG was specified.
If GO was
specified, or if no errors were detected, there is no
response. except the Ready message or an error completion
code. The following responses should not occur:

324

FORTRANREADY THE PRINTER.
I/O ERROR ON PRINTER. • PRINT' OPTION CANCELLED.
A 'LISTING'· DISI< FILE WILL BE CREATED.

If either appears at thesystem programmer.

terminal"

notify_the responsible

Examples:a.
see Figure 29
A file. FAC FORTRAN P5, is to be compiled.
No options are
specified, so the set ofdefault options govern thecompilation. At statement OOQ1 the compiler detects threeerrors at the points indicated by the $'s in the succeeding
line. Error 01) refers to the left $, error 02) to the $ inthe center, error 03) to the $ under the 5.
(The number in
the 'On)' being the ordinal occurance of the error).
Explanations of the error codes are found in the rEM
System/360
OperatingsystemFORTRAN IV(G and H)
Proqrammer·s Guide. CMS cancels the cowpilation and supplies
the error code E(OOOOS).
fortran fac
READE (5,177) ANS(I)

0041

$

$

01) IEY0021 LABEL$
02) IEY0041 COMMA
IEY0221 UNDEFINED LABEL

03)

771
E(OOOOS); T=5.42/5.98 11.40.56
Figure 29. FORTRAN compilation with errorsh.
see Figure 31
The same file as in the above example is to be compiled, but
the SOURCE. MAP,. and NOLIST options are specified.. Assume
that the errors flaqged above have been corrected. The filecompiles correctly this time.
fortran fac (source map nolist )Ri T=5.75/6.27 11.44.57

Figure 31. FORTRAN compilation with optionsc.
see Figure 32
Three files are to be compiled: FAC FORTRAN P5, TEST FORTRAN
P5, and PRACTICE FORTRAN P5.
No errors are detected during
any of the compilations. Maps of variables are included ineach of the three LISTING files, which are automaticallyprinted offline. and erased from the disk.

FORTRAN325

fortran fac test practiceCOMPILING: TES-r
COMPILING: PRACTICE
R; T=5.90/6.69 11.44.06
Figure 32. Multiple FORTRAN compilations
Error Messages:
F(OOOOl)TOO MANY LEFT PARENTHESIS.
More than one left parenthesis was found in the command. No
compilation was started.
E(OOOOl)
LEFT PARENTHESIS MISSING.
An
unbalanced
right parenthesis
compilation was started.

wasdetected.

NO

E(OOOOl)NO FILE TO BE COMPILED IS DEFINED.
No filename was specified in the command.
No compilation
was started.
UNABLE TO COMPILE MORE TH1\N 32 FILESIN ONE RUN. PLEASE SPLIT YOUR REQUEST.
More than 32 filenames were specified in the command,. Enter
in groups of less than 32 in two or more commands,. No
compilation was started.
E(OOOOl)E(OOOOl)

AT LEAST ONE OF THE FILES TO BE COMPILED
DOESNeT EXIST OR DOESN'T HAVE A 'FORTRAN'
TYPE NAME.
"filename FORTRAN *" was not found in the file directory.

AT LEAST ONE OF THE FILES TO BE COMPILED HASLOGICAL RECORD LENGTH DIFFERENT OF 80 BYTES.
Recreate the file with SO-byte records.. The EDIT command
truncates overlength records to 80 bytes. No compilation wasstarted.
E(OOOOl)

E(00004)
Possible errors were detected in the
successful execution is possible.
ECOOOOS)Errors were detectedfail.

source program"in the source program.

but

Execution may

E(00012)
Serious errors
were detected
Execution is impossible.

in

the

sourceprogram.

E(00016)
Terminal errors were detected
Compilation was terminated,.

in

the

sourceprog~am.

E(00016)326

ERROR WHEN LOADING THE IEYFORT MODULE.
FOR'l'RAN

Loadin9 of the compiler failed;
Retry the command.

no compilation was started.

E(00032)COMPILATION CANCELLED DUE TO SOURCEPROGRAM ERROR(S).
CMS canceled processing.
Correct the source program,specify the GO option.

FORTRANor

327

FORTRAN PROGRAMMING'~SEQOElfi'IAL

I/O","A"llsequential files used or created by FORTRAN
nave file identifiers in the following format:

programs

1 Filename
Filetype I
1
I-F~I-L-E~-- -"""'-----,
FTxxFyyy t
1______ ______ 1
xx is the data set reference number, from 01-14.
yyy

is a sequence number, beginning
distinguish multiple files underreference number.

with 001 used tothe same data set

If a file is being created by a FORTRAN
filemode is Pl.
For input to a FORTRAN
filemode of P is accepted.

programl,
program,theanywith the exception of terminal input and output, all files
are kept on the permanent disk or on tape. Existing input
files must conform to the record formats described below.
Output files are created by the FORTRAN program, and neednot be defined before execution. If output files alreadyexist, the new output is appended to the existing file.
Data set reference number 5 is reserved for terminal input
records of SO characters or less.
Number 6 is reserved forterminal output records of 120 characters or less.
The
terminal is also addressed by statements of the form "READb,list" and "PRINT b,list" where b is a FORMAT statement
number.
The FORMAT for a PRINT statement must allow aleading space for a carriage-control character, or the firstcharacter of the record is lost.
The carriage-control
character does not have to be filled in. however. Output
records generated by a statement of the form "PUNCH b;,list"
are placed in a file on the permanent disk under theidentifiers FILE FT07F001 Pl. Actual punching out of cards
may be performed later with the OFFLINE PUNCH command.
Data set reference numbers 11 and 12 are reserved for tape
I/O. Number 11 corresponds to TAPl at virtual address lS0,
and number 12 corresponds to TAP2 at virtual address 181.
Before number 11 and/or 12 are used, virtual 180 and/or 181
mustbeattached
totheuser'svirtualmachineconfiguration, or I/O errors occur.
With the exception of data set reference numbers 6,.8 1,12. and14, whichallow 133-character records, anddata setreference number 9. which allows 140-character records. a1lfiles must contain SO-character fixed-length records. The
implied record format and device for each data set reference
328

FORTRAN Programming

number is shown in Figure 33.
The sequence field of the filetype is always 001 unlessmultiple files are referenced under the same data set
number. There is no limit to the number of files which may
be created or referenced under the same number, but only one
may be referenced at a time. The first used must have thefiletype FTxxF001"
the second FTxxF002"
etc. The END FILE
statement closes the file currently in use, and the next
READ or WRITE specifying the same data set reference number
refers to a file with a reference number one larger. The
REWIND statement -repositions· the files to the first one
used in that program under that data set reference number(see Figure 34). The BACKSPACE statement is supported undereMS for tape data sets only.
A facility for defining a correspondence between a CMS filewith unique identifiers and a FORTRAN data set reference
number has been provided in the DEFINE subroutine. Refer tothe description in SYSLIB TXTLIB.

FORTRAN Programming

329

Figure 33. Summary of record formats and I/O statements forsequential FORTRAN files

330

FORTRAN Programming

Notes to Figure 33
a. The file identifiers for each of the files are

FILE FTxxFyyy
where xx is the data set
sequence number.

reference number, and yyy

is theb. The sequence number is 001, except when multiple files
are referenced under the same data set reference number.
c. No file identifiers are shown for reading data set
reference number 5 or writing number 6. since these numbers
address the termina1 for input and output, respectively~ No
file identifiers are shown for data set reference numbers
11, 12, 13. and 14, as these numbers address virtual tapes
180-183. respectively.

* Data set reference numbers 13

be used,and 183.

as there are noand 14 should not currently
definitions in eMS for tapes 182

FORTRAN Programming

331

,

~~-~~-~~-~---~~~~--------~-----~--~-~~~-~~-----~--~--- --FORTRANSTATEMENT

NAME

FILE
TYPE

MODE

FILE

FT04F001

Pl

20 WRITE (3,100) B
30 END FILE 3
40 READ (q.100.END=50) B

FILE
FILE
FILE

FT03FOOl
FT03FOO1
Fr04FOOl

PI
PI
P1

WRITE (3,100) B
GO TO 40
50 END FILE 3
52 REWIND 3

FILE

FT03F002

PI

FILE

Fl'03F002

P1

75 READ (3,.100) B•

FILE

FT03FOOI

PI

I

I
I
I
I
I
I
I
I
I

r

REAL*8(S)100 FORMAT (S (G10 .. 8/. 6X»
S DO 20 I=1 t• 4S
10 READ (1$;.100) B•

1J4(terminal output)

82 PRINT 200, B
STOP

Figure 34.
statements

Files

referencedbysequential

FORTRAN

I/O

Notes to Figure 34
Statement 10 reads the first 45 records of the existing file
FILE FT04F001 Pl. At statement 20, these records are placedin a new file FILE F'r03FOOl Pl,.
This file is closed by the
END FILE statement at 30, and the next time data set
reference nurober 3 is used, at statement 44, a second new
file ~s created: FILE FT03F002. After the REWIND statement,
data set reference number 3 is again associated with thefirst file created: FILE FT03F001.
Note that the PRIN'r
statement requires a different FORMAT statement, whichallows for a carriage-control character.

332

FORTRAN Programming

DIRECT ACCESS I/O
All direct-access files used or created by FORTRAN programs
have file identi'fiers in the following format:

I

Filename

I

Filetype,

1------------1------------1
I
FILE
1
DAxx
,
I

I

I

xx is the data set reference number, from 01 through 08,.
If the file is being created by a FORTRAN program,filemode is Pl.
For input to a FORTRAN program"filemode of P is acceptable.

the
any

Direct access refers only to those files which are used with
the FORTRAN lanq,uaq.e DEFINE FILE statement.
(Note thedistinction between the CMS library DEFINE subroutine in
SYSLIB. TXTLIB wllich is referenced
by a
CALL DEFINE
statement, and the FORTRAN language statement DEFINE FILE.)
Files used sequentially are not considered direct-accessfiles,. even though they reside on disk.
Unlike the sequential data set reference numbers, thedirect-access number does not imply any record length. This
information is supplied by the DEFINE FILE s·tatement within
the FORTRAN program.
All files are on the permanent disk.
The same data set reference number may not be used for botha sequential and a direct-access file in the same program,nor may a single file be referenced by both methods in thesame program. Different access methods may be used for thesame fileby different
programs, provided
the file
identifiers are changed.
The number of records specified in the DEFINE FILE statement
should be realistic. If a new file is being created, thespecified number of records are blanked out on the permanent
disk before the first record is written.. Specifying an
unnecessarily larqe number of records wastes disk space,.
Although the FIND statement is supported, there is no need
to use it in a time-sharing environment,. I/O overlap isachieved through sharing of CPU time among the virtual
machines. Use of the FIND statement actually slows down
execution of the FORTRAN
program slightly. since two
operations must be carried out instead of one.
An example of direct-access I/O is shown in Figure 35.

FORTRAN Programming

333

FORTRAN
FILE(
I
TYPE
NAME
STATEMENT
1I
f
I 100 FORMAT (16, 2X,A20,. 4G13. 6)
DEFINE FILE 1 (200, 80 ,E ,R3l
I
I•
1
5 READ (1·J ,100) MNNO •• NAME,TOTS
I
DAOl
FILE
I
WRITE
(l·J!,
100)
30
MNNO" NAME, NWl'OTS
I
I
STOP
I
I

,
t

MODE

I
I

,
,

i

Figure 35. Filestatements

referenced

by

I
I
I

P1

1

,
I

1

direct-access FORTRAN

I/O

Note to Figure 35
The DEFINE
FILE statement describes
a fileof 20080-character records. If this file had not existed before
program execution, 200 records of 80 blanks would have been
written on the permanent disk. Statements 5 and 30 read andwri te the Jth record,. where J has been assigned an integer
value less than 201.
TERMINAL OUTPUT
Terminal output can be
FORTRAN programs:
(1)

(2)

produced in eitherof twoways in

WRITE (6,FS) A~B,C
PRINT FS,ABC

where FS is a format statement number.
In versions of CMS, up to 1.58 alphameric information
printed at the terminal by using either the A-format or theHollerith format had the first character of each line
blanked out. This has now been modified, and the firstcharacter is used as a format control character in a manner
analogous to that used in OFFLINE PRINTCC. This control
character has the following meaning:
character

•

•

• + •

to'

Actionline, carriage returnline
carriage return!. line,
carriage returnNote. Lines not followed by a carriage return have the linethat follows them typed immediately behind them. if blanks
are required, nonprinting characters should be included.

334

FORTRAN Programming

FORTRAN FILES
The defined FORTRAN logical files are as follows:
Logical file
1-4
5
6
7
8

Record description
BO-character records
80-character sysin records
130-character sysout records
80-character records
133-character records withcarriage control(To print logical unit file B" the OFFLINEPRINTCC command must be issued.)
The subroutine DSDSET can be called to allow a user tochange the record format and the logical record length for
FORTRAN ·disk files~
Thus, a user is no longer confined torecords of 80, 13~, or 133 bytes in length (see the DSDSET
Subroutine for a description of DSDSET in SYSLIB TXTLIB).
A facility has been added to change the identifier FILE
FTxxFyyy required for FORTRAN disk file reads and writes. A
call to the DEFINE subroutine is required to change thecorrespondence between a eMS file and a FORTRAN data set
reference number.
Refer to the writeup on the DEFINE
routine.
FORTRAN write statements can be used to create disk files
with a name of FILE FTOxFOOy, where x is the logical unit
number and y is the logical file number. The first time awrite is issued to logical unit x, logical file 1 iswritten. After an ENDFILE to logical unit x, subsequent
writes to logical unit x before a REWIND will write into
file FTOxF002. This file is a separate disk file from file
FTOxF001.
Additional logical files can be written byissuing an END . FILE to the previous logical file;, and thencontinuing to write onto logical unit x.. If a file alreadyexists when the write statement is issued, the lines written
are appended to the existing file. To append information toan existing logical file 2, firstwrite onto logical file1 and issue an END FILE x, orread the file until the end file condition is reached,then write into logical file2, whichdata on the end of the existing file.

appends totheAfter a rewind to alogical unit, subsequent writes
overwrite the existing file. Only logical file 1 (that is,file FTOxF001) can be overwritten. There is no way tooverwrite into logical file 2, etc. An overwrite does not
shorten the file length: thus. information in a file which
is not overwritten remains in the file.. Writing over an
FORTRAN Programming335

existing file can lengthen the file. and thus eliminate all
the original information in the file. To write a completely
new file. an existing file must first be erased. either by
issuing the ERASE command or by calling the ERASE routine.
A tape facility for FORTRAN programs is available where
logical units 11-14 are the standard logical tape units.
These units correspond to symbolic devices TAP1-TAP4. and tovirtual devices 180-1a3. A tape file can be written in oneof the following five tape formats:type 1:
type 2:type 3:type II:
type 5:fixed-record size, unblocked
fixed-record size. blocked
variable-record size,. unblocked
variabl~record size. blocked
undefined-record size, no blocking

The default settings are as follows:
Virtual
DeviceSymbolic
DeviceLogical
Uni,t

Block
Size

180
1lJl
182
183

TAPl
TAP2
TAP 3
TAP4

11
12
13
14

133
800
1330

80

Format
Type
I
I

2
2

Logical Record
Length
80
133
80
133

Unless otherwise set by a call to TAPSET, the mode settingfor 7-track tapes is for 800 bpi, odd parity, converter on,
and translator off. For 9-track tapes. the mode setting is
ignored. Refer to TAP SET Subroutine.
Note. TAP 3 and TAP4 are not currently defined
therefore do not use logical units 13 and 14.

in

CMS/,

I/O FORMAT CONVERSIONA FORTRAN reread facility is available to perform a core I/O
format conversion. To use this facility,
a call to the
REREAD routine must be made to specify the logical unit
number.
The logical unit may be any unit from 1 to 99
except unit 5, 6, or 7.
A WRITE statement must be issued
before the READ statement for rereading the specified
logical unit number. The FORTRAN statement
CALL REREAD(n)sets the reread unit to logical unit n with a default record
size of 140 bytes. This may be changed by specifying therecord size ,as a second parameter in the call to REREAD" forexample, CALL REREAD (99,80). Refer to the subroutine
description in the REREAD Subroutine writeup. To read therecord from the reread unit a second or subsequent time, a
REWIND n statement must be
executed before the READ
statement. If a reread is issued without executing a REWIND
statement.
an END
OF FILE
condition results.
Any
336

FORTRAN Programming

input/output statements for other logical units can beissued between a write and a read on the reread unit.. The
reread unit or the blocksize can be changed by another callto the REREAD routine.
Notes:
a. Each FORTRAN file can containbe computed.

any number of routines tob. A eMS narnelist facility is available for obtaining input
to a FORTRAN program in free format without specifying
variable names. Refer to the writeup on NLSTON/NLSTOF for amore detailed description of this namelist facility.
c.
The supported data
set reference numbers, device
assignments, or record formats at a particular installation
may vary from those described. Check with the responsible
system programmer.
d. Since different FORTRAN programs using the same data set
reference number reference the same CMS file identifiers,
files should not be left on the permanent disk under FORTRAN
format identifiers. If a FORTRAN program is to be executed
repeatedly, it is advisable to create an EXEC file renaming
execution-time files both before and after execution. An
example of such a file might be MYSTRUP EXEC Pl, containing
ALTER MSTR LIST P1 FILE DA02 P1
ALTER CHANGES LIST P1 FILE FT04R001 P1$ FORTMSTR
ALTER FILE FT04FOOl P1 CHANGES DONE P1
ALTER FILE DA02 P1 MSTR LIST P1
The command $ MYSTRUP then renaroes the files, executes the
FORTRAN program, and changes the identifiers again on
completion.
e.
The FORTRAN subroutines are found in SYSLIB TXTLIB.
Descriptions of the subroutines can be found in the' section
called SYSLIB TXTLIB. The extended error messages in SYSLIBTXTLIB give the user a traceback with registers 14.,15,,0, and
1 and the entry point. A standard fixup is taken andexecution attempts to continue. At program completion asummary of errors is typed to the terminal. The nonerror
message subroutines can be found in CMSLIB TXTLIB. Theseroessages give the error number and a brief description. To
use
this,
ratherthanthestandard
error-message
subroutines. GLOBAL T CMSLIB SYSLIB must be issued.

FORTRAN Programming

331

PLI
The following options relate to the eMS control of
output. Abbreviation for each option appears in pari

Purpose:The PLI comma
language intoand diagnostic

PUNCH (PU)outputs the TEXT file onto the offli:
option D must be in effect.

PRINT

outputs the LISTING file onto theprinter. A copy of the LISTING fi1
placed onto the user's disk.

(P)

Format:NOPRINT (NP) no LISTING file is produced.

PLI

NODIAG

fnamel ••• fname(NDG) compiler diagnostics
user·s terminal.

If neither P nor NP i-s specified"
onto the user·s permanent disk.

arenot tvpedthe LISTING file

option l ..• opt
Usage:
Option$:

SIZE
SIZE

nnnR
128R

s
C

I

LC
LC

nn
50

0
0

nn
00

s

SM
SM

cci,cc01 1 72Es

2includeE
suppressL

includesmnemonj
suppressNS

NL

The PLI command compiles files of PL/I source langmachine-language object code.
Input files must
filetype of PLI and a record length of SO character1]

The options governing compiler operation and ou
specified in any order in a set of parentheses foIllast filename. Any combination of options is val
conflicting options are specified, the last specifi
is used. Unsupported or misspelled options are
One set of options governs all compilations perform
command. Each of the options has a default value
selected when none is
specified.
These defa
underlined in ·Options· above.
For a complete discussion of PL/I usage, refe~
System/360 operating System
PL/I(F) Programmex(C28-6594) and
IEM System/360
Operating Syst
Subroutine Library computatienal Subroutines (C28introduction to PL/I is provided in Manual C28-680
Primer.
Responses:

NA

includef
suppresf

NoneE

include~Error Messages:NE-file.
suppref
Dictior

A

X
NX

338

includE
file.
suppresf

E (0004)
Warning messages have been included in
Successful execution is probable.

the LIST]E(OOOS}
Error messages have been included in the LISTING j
compilation was completed with errors, and exec\
fail.
340

PLI

E(00012)
Severe error messages have been included
file. Successful execution is improbable.
E(00016)
Compilation terminatedimpossible.

in theabnormally. Successful

LISTING

execution is

E(00026)
FILE TO BE COMPILED. UNDEFINED,.
No file with the specified filename and filetype of PLI canbe located on disk. Check to see that such a file exists
and then reissue the PLI command.
E(00026)
FILE(S) TO BE COMPILED. NOT SPECIFIED.
No filenameCs) was (were) specified in the PLI
Reissue the command in its proper format.

command.

E(00026)
FILE BAS INCORRECT RECORD LENGTH.
The source code to be compiled is not in 80-byt~
format and cannot be processed.

recordE(00026)
SYNTAX ERROR IN OPTION LIST.
Verify format of option list in COMMAND line.
E-C00027)
Cf!lJ5 NUCLEUS ERROR.
ReIPL the CMS system disk.
E(00028)
An error was encountered in attempting
file for the program being compiled.

PLI

to punch

the TEXT

341

PL/I PROGRAMMINGCOMPILATION NOTES:a.
Themain procedure
must
OPTIONS(MAIN) option stated.

becompiled

with

the

b.
Compiler diagnostics must be examined carefully -- do
not attempt to execute a program that has not compiled
successfully.
c.
Conversion subroutines are noted as "warnings" in thecompiler diagnostics. This does not indicate an error andshould not affect the execution of the procedure; it merely
notifies the user of costly conversions.. The warnings may besuppressed by the FE option.
d.
The compiler produces a file "name TEXT Pi" from the
input file "name PLI Pi", except in the event of "terminal"
compiler errors.
PL/I LIBRARY
CMS uses the PL/I Version 4 Subroutine Library. The PL/I
libraryiscalled PLILIBTXTLIB.
Three
additional
subroutines have been added to the library: IHECMS, lHECLOK,
and IHEFILE.
LOADING A PL/I PROGRAM
Before loading a PL/I program, it is necessary to designatethat the PL/I library is to be used (the default library is
the FORTRAN library called SYSLIB).
This may be done
immediately before loading. or automatically at login via
the PROFILE EXEC, by the following eMS command:
GLOBAL TXTLIB PLILIB
warning: If the loader indicates that
IBExyz are undefined. the PL/I library
designated.

names of the form
was not correctly

EXECUTING A PL/I PROGRAM
A
PL/I program may be loaded and executed in a similarmanner to all the other language processors.
The only
restriction is that the START entryname, if used!, must be
IHECMS which is a special initialization routine thattransfers control to the user·s main program. This routine
is automatically invoked under all other circumstances,.

The three common techniques are
LOAD progl <prog2 ... ,.>(XEQ)LOAD prog1 <prog2 ••• >
START
342

PL/I Programming

LOAD progl <prog2 ••• >GERMOD progl

•
progl

PASSING PARAMETERS TO A PL/I PROGRAM
The CMS
Command Processor automaticallyconverts allparameters on a command line into a series of 8 character
fields (left-justified and padded with blanks, or truncatedas necessary). These parameters may be passed to the PL/I
main procedure that is illustrated in the form below.
progl:PROCEDURE (PARMS) OPTIONS (MAIN);DECLARE PAR~S CHAR(*) VARYING;

When usingparameter passing,only
techniques described below may be used.

the

two

loading

LOAD prog1 <prog2 ••• >START IHECMS parm1 parm2 parm3 •••LOAD progl <prog2 ••• >GENMOD prog1•
progl parm1 parm2 parro3 • '••Note. The varying character string PARMS contains theIts length isconcatenation of the specified parameters .•always amultiple of eight (or null, if no parameters are
specified).
TERMINAL I/O
Terminal input/output can best be performed by using the
PL/I DISPLAY
or DISPLAY/REPLY
cOIrmands.
Thoughthe
DISPLAY/REPLY facilities deal only with character strings.
all possible uses can be accomplished by the following
techniques:

1.

Character I/O
For
simple character
strings,
facilities are convenient to use.

the

DISPLAY/REPLYa.

Output message only:
DISPLAY (message);
Example: DISPLAY (-HELLO THERE-);b.

Output message followed by response:
DISPLAY (message) REPLY (response);
Example: DISPLAY (-ENTER YOUR NAME') REPLY (INPUT):
PL/I Programming343

where INPUT is declared to be a character variable.
c.

Input only:
DISPLAY (.. .) REPLY (response):
Example: DISPLAY (e . ) REPLY (input):where INPUT is declared to be a character variable.
2.

NonformatSimple I/O
For input/output tbat is not a simple character string.
the PL/I conversions often work adequately.
Examples:3.

a.

DISPLAY (VARIABLE);
Where VARIABLE can be any simple variable (thatisi•integer.
floating-point,characterstring~etc.).
it is converted to a character
string by the default format. and printed.

b.

DISPLAY ("THE VALUE OF N IS' II N):
The value of N is converted to a character string.
concatenated with the message -THE VALUE OF N IS·.
and printed.

c.

DISPLAY ('ENTER VALUE OF N') REPLY (INPUT):N = INPUT:
The number entered is accepted as a character
string and converted to a nUmber by the N=INPUT
statement.
If
INPUT
contains
anillegalrepresentation for a number. a CONVERSION error
results.

Full PL/I Format Capabilities
The full PL/I format capabilities can be used bycreating formatted strings using the GET STRING and PUT
STRING commands. Regular PL/I input/output utilizes
the LIST or EDIT mode format control.

a.
A typical output statement might be
PUT FILE(SYSPRINT) EDIT (A, B, C) (F(8.0), F(S,O), F(1,.2»:
To accomplish the same function to the terminal
STRING(OUTPUT) EDIT (Ai. B. C) (F(8,O), F(8,O). F(7.2»:
DISPLAY (OUTPUT);
where OUTPUT is declared to be a sufficiently long
character string.
PUTb.
A typical input statement might be
GET·FILE(SYSIN) EDI-r (A. B t• C) (F(S,O). F(8,O) .• F(7(,2»:To accomplish t~~ same function to the terminal:
DISPLAY (' .) REPLY (INPUT):GET STRING ( INPUT) EDIT (A. .B, C) (F ( 8 • 0), F ( 8 • 0), F (7 • 2 ) ) :where INPUT is declared to be a sufficiently long
character string.
344

PL/I Programming

I/O VIA FILES
Extensive input/output file capabilities are available in
PL/I. At present. CMS has very limited support for PL/I file
I/O. Those capabilities are briefly described here.

1.

File Names
A reference to a file in PL/I requires the use of afilename. A filename of DATA in PL/I corresponds to a
CMS file named FILE DATA.
Thus. the. standard PL/I
files SYSPRINT and SYSIN correspond to the CMS files
FILE SYSPRINT and FILE SYSIN. respectively.

2.

File Declarations

ALL files must be declared. since PL/I learns thecharacteristics o~files under OS/360 from either PL/I
declarations or DD cards, and CMS does not use DD
cards. The general form for a declaration is .
DECLARE filename FILE <STREAM/RECORD> <EXTERNAL/INTERNAL><PRINT> ENVIRONMENT (F(n»;where n is the length of each record in the file.
Recommended declarations for SYSPRINT and SYSIN are
DECLARE SYSPRINT FILE STREAM PRINT ENVIRONMENT (F(121»);
DECLARE SYSIN FILE STREAM ENVIRONMENT (F(aO»:
Since SYSPRINT is used by PL/I to record execution
errors, it is necessary that this file be declared even
if it is not explicitly used in the program. To insurethat this condition is satisfied, the following default
declaration is used if there is no user declaration for
SYSPRINT:DECLARE SYSPRINT FILE STREAM PRINT ENV (F(80»:3.

File Operations
At present only SEQUENTIAL files can be processed undereMS, though either the STREAM or RECORD form can beused. The following commands may be used:a.

OPEN
There is no real need for using OPEN, as the first
GET/PUT or READ/WRITE to a file causes it toautomatically open.
Since the OPEN routine is
dynamically loaded, there is usually a noticeable
pause when an OPEN occurs.

h.

GET/PUTAll forms of GET/PUT can be used-- of course, thefile must have been declared as STREAM.

c.

READ/WRITE
Only the SEQUENTIAL

forms

PL/I Programmingof

READ/WRITE can

be

345

used--the file must have been declared as RECORD.
d.

CLOSE
Before a file is switched from GET to PUT, PUT to
GET, READ to WRI-rE, or WRITE to READ, it must be
CLOSED.

Note. Files are not automatically erased: therefore writing
into an already existing file results in appending records
to the end of the original file or rewriting the records
depending upon the position of the· file's Write Pointer as aresult of the file's previous usage.
The PL/I CLOSE
statement resets the W.rite Pointer to the beginning of thef'ile so that later PUT or WRITE statements will overwrite
the previous records.
Most eMS commands, such as EDIT,
leave the Write Pointer at the end of the file so that later
PL/I PUT or WRITE statements will cause records to be
appended to the end of the file. There is one exception--thefile SYSPRINT is automatically erased at the beginning ofexecution.
warning. Although the OPEN statement is not needed, due tothe significant overhead associated with implicit OPENs(caused by GET" PUT, READ, WRITE). it is recommended that
all files be OPEN'ed explicitly. at the beginning, by asingle OPEN statement. The form of the OPEN statement is
OPEN FILE(filel), FILE(file2). FILE(file3), ••• ;Of course, it is not necessary nor advisable. to OPEN any
files that are not used in the program!. including SYSIN andSYSPRINT.
ERROR RECOVERY
PL/I attempts to catch all execution errors such as invalid
conversion, program interrupts, and input/output errors" andprints an appropriate message on SYSPRINT,. The message thatis placed into the FILE SYSPRINT is also transferred to theuser's terminal.
Occasionally the message Interrupt in Error Handler occurs.
This means that PL/I has been unable to recover from anerror condition. There, are three main causes for thatphenomenon: (1) the compiler .has generated incorrect code or
there is a malfunction of a library routine--that is, systemerror, (2) a subscript has exceeded its bounds and destroyedsome arbitrary area of memory--usually a part of the
program, or (3) parameters have been passed incorrectly(that is~ scalar insteadof array) causing incorrect
addresses to be uS.ed. The second problem can be avoided byenabling the SUBSCRIPTRANGE check by making the firststatement of each subroutine(SUBSCRIPTRANGE):

346

PL/I Programming

PL/I
catches all
programinterrupts, including
thebreakpoints set by the DEBUG routine.
Therefore" if you
wish to set breakpoints in a PL/I environment"
it isnecessary to disable the SPIE that PL/I uses to trap allinterrupts. The SPIE can be disabled by using the special
CMS library function IHESPOF (SPIE off). and enabled by thefunction IHESPON (SPIE on). Breakpoints should be placed sothat they are triggered after the SPIE has been disabled.
OTHER LIMITATIONSAt present
several PL/I
system-dependent capabilities
malfunction under CMS--the TIME and DATE built-in functions
and certain types of ON-conditions do not operate correctly.
There may be other similar temporary limitations. The user
should try to avoid using these facilities.
SYSIN/SYSPRINT TO USER'S TERMINAL
Occasionally. it is desirable to use the full PL/I GET/PUT
LIST, EDI'!', and DATA facilities wi th the user's terminal.
Furt:lermore. it is often desirable to have programs that canuse the terminal for testing with small quantities of data,
but later use files for large-scale runs. A facility has
been added to CMS-PL/I to specify that the SYSIN/SYSPRINT be
directed to the user's terminal rather than files.
It isstill necessary for the user to declare the SYSIN andSYSPRINT files. whether he is using files or the terminal.
There are two mechanisms availableof operation.
1.

for activating this mode

If the first parameter passed to a PL/I program is(TYPE). it is trapped by the interface routine andremoved from the parameter list. and the typewriter
SYSIN/SYSPRINT mode is turnedon.
The remaining
parameters, if any, are passe~ to the PL/I mainprocedure.
Examples:LOAD prog ••• ,.
START IHECMS (TYPE)
orprog (TYPE)
~here

2.

prog is a MODULE created by GENMOD.

It
may
be
desirabletoselectively
switchSYSIN/SYSPRINT from files and terminal.
The CMS-PL/I
library routine IHEONNL (online) causes all future
SYSIN/SYSPRINT requests to refer to the user's console;
the routine
IHEOFFL (offline) causes
all future
SYSIN/SYSPRINT requests to refer to the files FILE
SYSIN and FILE SYSPRINT. The most recent IHEONNL or
IHEOFFL negates the effect of any previous mode.
PL/I programming

341

Note that the normal precautions concerning GET/PUT apply.
In particular, if both SYSIN and SYSPRINT are to be used, it
is recommended that they be opened simultaneously by thestatement
OPEN FILE(SYSIN), FILE(SYSPRINT):
Notes:
a. SYSIN and SYSPRINT are STREAM input/output files: as aresult;. they do not always respond to the terminal as theuser m~ght expect. In particular, a PUT statement merely
places information into an output buffer: the buffer is not
actually printed until the buffer becomes full, or, until a
PUT with the SKIP option is encountered.. Therefore, thesequence
PUT LIST ('READY'):
PUT SKIP LIST ('ENTER ARGS·):
GET LIST (A,B,C):
PUT SKIP LIST ('THANK YOU'):
prints 'READY' and then request AI,B, and C input before
printing 'ENTER ARGS'(which is still in the current print
buffer).
The 'ENTER ARGS' message is not printed until
after reading the arguments!
Ways toovercome this problem
are useDISPLAY andDISPLAY/REPLY instead of GET/PUT, or place a PUT SKIP: after
each PUT statement.
h. If an explicit OPEN is used for SYSIN, the stream input
mechanism of PL/I will request
the first input line
immediately even though a GET statement has not beenencountered yet. That input line is saved and used forlater GET statements. This is not usually a serious program
but can be confusing if output was expected prior toentering input. Therefore the sequence:
OPEN FILE (SYSIN), FILE (SYSPRINT):
PUT LIST ('ENTER ARGS');
PUT SKIP:GET LIST (A,B,C):
would unlock the keyboard to accept an input line before
printing -ENTER ARGS' even though the PUT SKIP was used (seeNote 1). This is due to the explicit OPEN for SYSIN.
For very similar reasons, the CALL IIlEONNL statement, if
used, must precede the OPEN FILE (SYSIN), otherwise thesyst'~m will attempt to read the first line from FILE SYSIN.
There are several ways to overcome this problem:(1) useDISPLAY and DISPLAY/REPLY instead of GET/PUT. or (2) do not
explicitly open SYSIN but let first GET statement cause
348

PL/I Programming

implicit open.
PL/I SUBROU'IINES
Three subroutines have been added to the PL/-I library for
use under CMS.
Two of these--IHECLOK and IHEFILE---were
written to assist users attempting to write monitor-type
programs in PL/I.

PL/I Programming

349

IHECMS--PL/I Initialization Routine
Purpose:IHECMS performs the CMS-dependent initialization and passes
parameters to the primary PL/I initialization subroutine,IHESAP.
Calling Sequence:
IHECMS is automatically loaded
subroutines.

with the PL/I initialization

Internal Entries:
The following CMS PL/I library
the IHECMS subroutine.

functions are entries within

IHESPOF turns PL/I SPIE off
IHESPON turns PL/I SPIE on
IHEONNL SYSIN/SYSPRINT to terminal
IHEOFFL SYSIN/SYSPRINT to file
IHEDBUG transfer control to CMS DEBUG

350

PL/I Programming

IHECLOR--PL/I Clock Routine

Purpose:IHECLOK reads the CP virtual chronolog clock and returns thedate-, time of day, elapsed virtual and total time.
Calling Sequence:
CALL IHECLOR ( CLOCK ):where CLOCK isbelow.

a PL/I

structure in

the form

illustrated

DECLARE 1 CLOCK,
2 DATE CHAR(S)!,/* date in form 01/21/69 */2 TIME CHAR (8) I'/* time of day in form 21.14.34 */2 VIRTUAL TIME FIXED BIN(31,O).
/* elapsed v:rtual time in timer units */2 TOTAL TIME FIXED BIN(31,0):/* elapsed total cpu time in timer units */DATE and TIME contain actual slashes(/) and periods ( .• ) as
illustrated in the examples above. The PL/I SUBSTR function
can be used to rearrange the DATE and TIME and/or remove thepunctuation.
VIRTUAL TIME and TOTAL TIME are bina,ry integers.
They
represent elapsed time charged for cpu usage running under
problem state (virtual time) and elapsed time charged for
total cpu usage (total time). To convert from timer units
to hundredths of seconds, divide by 768 or X'300.
Bothtimes areincreasing numbers:
the normal
360 timer
decreases.
Example:TESTCLK:TESTCLK:PROCEDURE OPTIONS (MAIN):

TES00010

PROCEDURE OPTIONS (MAIN);DECLARE IHECLOR ENTRY (1~ 2 CHAR(S), 2 CHAR(8),2 FIXED BIN (31,0). 2 FIXED BIN (31,,0»:
DECLARE 1 CLOCK STATIC,.
2 DATE CHAR(S).
2 TIME OF DAY CHAR (8) I,
2 VIRTUAL-TIME FIXED BIN (31,0),
2 TOTAL CPU_TIME FIXED BIN (31,0):LOOP:
DISPLAY (-BEFORE CLOCK.-):CALL IHECLOK (CLOCR):DISPLAY (. AFTER 'CLOCK.. - ) :DISPLAY (DATE);DISPLAY (TIME OF DAY):DISPLAY (VIRTUAL_CPU_TIME);DISPLAY(TOTAL_CPU_TIME):GO TO LOOP:

END:
PL/I Programming

351

IHEFILE--PL/I File Access Routine
Purpose:IHEFILE converts
corresponding CMSWRBUF.

PL/I file access requests
commands S-rATE. ERASE" FINIS,

into
RDBUF"theandThe user should be familiar with the operations of theabove-named CMS file system routines. and the error codes
produced by them.
Calling Sequence
CALL IHEFILE ( FCB ) ;where FeB (File Control Block) is
form illustrated below.

a PL/I structurein theDECLARE 1 FCB,
2 COMMAND CHAR ( 9 ) i, /*CMS command desired */2 FILENAME CHAR(S) /* CMS filename */2 FILETYPE CHARCS) /* CMS filetype */2 CARD NUMBER FIXED BIN (31,0).
/*

record number - RDBlJF/WRBUF only */2 STATUS FIXED BIN(31.0),/* CMSr,.!turn code -o means OK */2 CARD BUFFER CHAR(80);/* 80 byte record to be read or written */The SO-byte record need notnecessarily be a single
character string. The next 80 bytes of the structure (after
STATUS) are used, whatever they may be.
Therefore, binary
integers, character strings, floating-point numbers. etc.
can be used in the following ways:(1)

adding them to structure in place of CARD_BUFFER,(2)

defining another structure positioned on top of
CARD_BUFFER/, or(3)

converting all information into a concatenatedcharacter string and separating out on input by
SOBSTR.

CARD NUMBER must be set for RDBUF/wRBUFusage; it is ignored
for STATE" ERASE, and FINIS.
If sequential writing or
reading is to be done, the PL/I program must increment the
CARD NUMBER or set it to zero.
During writing. if the cardalready exists, it is replaced by the new card. If the carddoes not exist (that is, the file is being expanded), theposition of the end-of-file is moved and the new card added
to the file.
STATUS is352

the CMS return codefor the last

PL/I Programming

IHEFILE issued

using that FeB.
For example, return code 12 from RDBU~
indicates an attempt to read beyond the current position of
the end-of-file (see example that follows).
ExampleThe example below does the following:a.

Erases the file TEST1 DATA if it already existed.

b.

Creates a file TEST1 DATA consisting of 25 records:
each record contains a character string representing
the square of the card number (that is, the third cardin the file contains the number 9).

c.

The file is closed via FINIS.

d.

Assuming the number of cards in the file is unknown,
the program attempts to read through the file until thestatus indicates that the end-of-file was reached.

e.

The file is then read backwards (that is, starting at
the last card, then next to last" etc .. ).

f.

The file is closed.

PL/I Programming353

printf testfil p1i
PROCEDURE OPTIONS(MAIN)jTESTFIL:DECLARE 1 FeB STA-rIC.~
2 COMMAND CHAR (81.
2 FILENAME CHAR(S) INITIAL ( 'TEST1') r,
2 FILETYPE CHARCS) INITIAL('DATA').
2 CARD NUMBER FIXED BINC31,., 0),
2 STATUS FIXED BINC31:,O)I'
2 CARD_BUFFER CHAR(SOJ;
COMMAND='ERASE';
CALL IHEFILE( FCB ):COMMAND = 'WRBUF';
DO J

END;

= 1 TO 25;
CARD_BUFFER = J*J;CARD NUMBER = J;
CALL-IHEFILE( FCB );DISPLAY (J I "' J*J) :COMMAND = 'FINIS'; CALL IHEFILE( FCB ):COMMAND = 'RDBUF-:

00 J = 1 BY 1;
CARD NUMBER = J:
CALL-IHEFILE( FCB ):IF STATUS ,= 0 THEN GOTO END_OF_FILE;DISPLAYCCARD_BUFFER);END:
END OF FILE:DISPLAYC'STATUS = '11STATUS);

JMAX=J-l;
00 J= JMAX TO 1 BY -1;

CARD NUMBER = 1:
CALL-IHEFILE( FCB );DISPLAY(CARD_BUFFER);END;
COMMAND = 'FINIS'; CALL IHEFILE( FCBDISPLAY('THATS ALL.'):END;
Ri T=0.08/0.38 20.04.10

35fJ

PL/I Programming)j

SNOBOL **Purpose:The SNOBOL command compiles source programs
SNOBOL into SPL/l, and executes SPL/1 programs.

writteninFormat:I SNOBOL I filename«option1_ •• optionN»

filename

specifies a files
with the filetype
SNOBOL to be compiled.
or with the
filetype SPL1 to be executed.

option1 ••• optionNare one or more of thedescribed below.

compiler options

Options:
OFFLINE

specifies that information normally placed in the
LISTING file is also to be printed offline.

ONLINE

specifies that information normally placed in the
LISTING file is to be typed out at the terminal.

NOLIST

suppresses the LISTING file, but does
either of the above options.

SPL1

specifies that the file named with the command is
an SPL1 file to be executed, and not a SNOBOL file
to be compiled .•not affectIn addition to the options
above, execution is also
controlled by control cards within the source file. These
cards must begin with a hyphen in column 1, and appear as
shown below.
-LIST ON

resumes the listing of the SNOBOL
in the LISTING file.

-LIST OFF suppresses the listing of
program in the LISTING file.

thesource program
SNOBOL

source-SEQUENCE causes columns 13-80 of the source file records tobe ignored by the compiler,. allowing card sequencenumbers.
inthe-EJECT

inserts a
carriage-control character
LISTING file to skip to a new page.

-DECK

generates a file filename PUNCH P1 containing the
SPL/l output in a special abbreviated format.

SNOBOL355

suppresses execution of the compiled program.

-NOGO-MEMBER=name identifies theroutine.
-DATA

following

cards

as an

SPL/l

marks the end of input to the compiler. This card
·must be present l• whether any data cards follow ornot.

-ASSEMBLY OFF suppresses listing of
LISTING file as they areThis is the default value.

SPL/l programs in theloaded for execution.

-ASSEMBLY ON includes the listing of SPL/l programs in the
LISTING file as they are loaded for execution .•-TRACE

causes all strings referenced
by theprogram to be listed in the LISTING file.

user'sUsage:The SNOBOL command uses two separate programs to compile andexecute SNOBOL programs. The SNOBOL compiler is itself a
SNO~OL programthat translates SNOBOL into SPL/l1, a morebasic
string-processing
language,.
The
SPL/l
assembler-interpreter executes SPL/l proqrams interpretively(performing the requested operations for the user's proqram,
rather than translating his program into machine language).
The compiler and assembler-interpreter use several files,
described below. In each case, ftfilename ft is the filename
specified with the SNOBOL command.
ftfilename SNOBOL Pl ft is the input to the SNOBOL compiler.
It may consistof a SNOBOL programor program andsubroutines t,
a mixture of SNOBOL and SPL/l programs., or
entirely of SPL/l programs which have already been compiled.
SNOBOL subroutines must begin with a SUBROUTINE statement
and end with an END card.SPL/l programs must be precededby a -MEMBER= statement to be handled by the compiler. A-DATA card must close input to the compiler, whether datacards follow or not. The SNOBOL file may also contain theother control cards listed above.
-filename SPLl Pl- is the output from the SNOBOL compiler,
and is input tothe SPL/l assembler-interpreter.
Ifsubroutines are included in the SNOBOL compiler input, eachgenerates a separate SPLl file, with the subroutine nameused as a filename. An SPL1 file may be executed without
compilation by specifying the SPLl option..
-filename LISTING Pl- is a listing file cr~ated by both thecompiler and the assembler-interpreter,.
According to theoptions specified and the control cards included, it may
contain any, or alIi, of the following information:
A
356

listingofthe SNOBOLSNOBOL

sourceprogram.

includingdiagnostic
detectedmessages immediately

A listing of theexecution.

following any

SPL/1 program as

it waserrorsloaded for

Any output generated by a SNOBOL PRINT statement in the
program.
A message explaining any error completion.

Output generated byprogram requested it.

the

TRACE

subroutine,.

if

the

"filenaroe PUNCH Pl- is created if a -DECR control card isencountered in the program.
This file is similar to the
SPLl file,. except that comment cards are deleted and a
special abbreviated format is used. It is generally about
one-third the size of the SPLl file for the same program.
"filename anyname Pl- is the general identifier used forfiles referenced by name from a SNOBOL program. "filename"is the name of the program, and anyname is the name used forthe file within the program, (see "Input/Output" under"SNOBOL Programming·).
If the compiler detects an error" a diagnostic message isplaced in the LISTING file, and a HALT instruction isinserted in the SPLl file. Compilation continues to the-DATA card, but execution is
terminated at the HALT
instruction.
Notes:a.
CMS SNOBOL differs in some significant ways from other
SNOBOL implementations.
-SNOBOL
Programming" describes
briefly the I/O subroutines of CMS SNOBOL"
but does not
attempt to define the language,. The user should be familiar
with the manual listed under -References",.
h.
SNOBOL accepts any of the 256 EBCDIC bit patterns as
data, but names and labels are restricted to letters andnumb~rs,andseveralinstallation-dependent
specialcharact'~rs •Responses:
The SNOBOL command gives no responses, unless the ONLINE
option is specified.
In this case" information normallyplaced in the LISTING file is also typed out at theterminal.
References:CMS
SNOBOLusers
shouldCMS SNOBOL User's Manual.
SNOBOL

have

a

copy

of

357

Examples:a. SNOBOL SORT4
The file SORT4 SNOBOL PI is compiled into SPL/I. A listingis created as SORT4 LISTING Pl. and the SPL/l program issaved as SORT4 SPLI Pl. As soon as compilation is complete,
the SPL/I assembler-interpreter receives control to executethe program.
b. SNOBOL SORT4 (SPLl ONLINE NOLIST)
This command executes the file SORT4 SPLI PI, created in theprevious example. ONLINE causes any output normally placedin the LISTING file to be typed out. NOLIST suppresses theplacing of the same output in the LISTING file.
Error Messages:
E(OOOOB)This
isageneralerror
code
returnedbytheassembler-interpreter for mosterrors.
An explanatory
message is found in the LISTING file.
E(OOOl6)

There was insufficient room in core storage for an SPLl fileduring loading. or more than three levels of subroutine
nesting were attempted •• * SNOBOL is a Type III program available
Program Information Department.

358

SNOBOLfrom theIBM

SNOEOL PROGR~~ING
SUBROtrl'INESCMS SNOBOL includes a subroutine feature. which may be usedin two ways. System subroutines are provided and are calledby using the name of the subroutine as a SNOBOL statement.
User-written subroutines are created and called by the
SUBROUTINE,. CALLI. and RETURN
system subroutines.
The
general format for using system subroutines is shown below.
i•

label

subname(argl ••••• argN)«where»label

is an optional statement label.

subnameis the name of the subroutine.

argl,•••• i.argN

are string names orsubroutine.

whereis an optional statement label specifying thesubroutine statement at which execution is tobegin.

literals passed

to theNo blanks may separate the subroutine name and the leftparenthesis. The system subroutines are described below.
grouped according to usage.
INPUT/OUTPUT
PRINT (string) writes the string specified on the LISTING
file. A literal of fewer than 63 characters may be
specified instead of a string name.
READ(string) reads successive items from the SNOBOL input
file into the string specified,. These items followed
the -DATA card in the input stream.
PUNCH (string) writes the string specified into -filename
PUNCH Pl-. where filename 1S the name of the program.
The string specified must be 80 characters or less inlength. A literal of fewer than 63 characters may also
be specified.
GET (stringl.string2)
PUT (stringl.string2)
CLOSE (stringl)
EJECT (stringl)
are used to access files on disk or the user's
terminal. The filename of the file referenced is always
the same as the name of the program being executed,.
-stringlspecifies
the filetype
of
the
file
referenced. This operand may also be expressed as aliteral. For example. if TESTl is a SNOBOL program
SNOBOL Programming359

being executed, and the string DATA contains SAMPL,
either of the following statements would read an itemfrom the file TEST1 SAMPL PI:
LABL GET(DATA~NUMS)LABL GET ( • SAMPL' , NUMS )GET and
PUT both
open files
automatically, if
necessary, but if the same file is to be written andread" a CLOSE must be issued between the operations.
(This does not apply to the terminal.)

Except for the terminal and the LISTING file. record
size is always 80 characters. The LISTING file has
120-character
records,
plus acarriagecontrolcharacter. Size of a terminal record is always thenumber of characters written or read.
A literal offewer than 63 characters may replace string2in a PUTstatement.
The terminal is accessed by specifying a filetypeconsisting of blanks. This may be done in three ways:
by specifying a string containing from one to eightblanks" by specifying a literal blank, or byomitting
tbe first operand. The following three statements all
read one record from the terminal into the string IN:

LAB GET (TERMINAL. IN)
GET ( • ./# IN)
GET(,IN)
The first assumes that the string TERMINAL contains
only a series of blanks. The CMS delete charactershave their usual effect, and all input is translated touppercase. A line consisting of only a carriage returncauses an I/O error and program termination. If awhole line is deleted by t ,• another read is issued.
The EJECT statement causes a carriage-control characterto be placed in a file. forcing a page eject when thefile is printed,. EJECT (LISTING) forces the LISTING file
to skip to the top of a page. Any file for which an
EJECT
is
the
first
statement
issuedhasacarriage-control character prefixed to each item as itis written out.
This character is returned as thefirst character of strings read back in from such a
file.
SUBROUTINE GENERATIONSUBROUTINE(arg1, •••• argN) must be the first statement ofuser-written subroutines.
An END card must conclude
the subroutine.
The name by which the subroutine iscalled must be placed in the label field of the
SUBROUTINE statement. This name is also used for the
filename of the SPLl file generated by the compiler for360

SNOBOL Programmingthe subroutine.
The SUBROUTINE statement may also
include an unconditional branch. An example of a
SUBROUTINE statement is
SORT SOBROUTINE(STRING~FIELD,NUM)/(PROCESS)

This statement caUses the SNOBOL compiler to generate afile SORT SPLl Pl, which is loaded whenever thissubroutine is called by the name SORT.
On receiving
control, execution would begin at the statement labeled
PROCESS. If the transfer had been omitted, execution
begins at the first statement of the subroutine.
STRING, FIELD, and NOM are the strings received asarguments by the subroutine.
RETURN (dummy) is used to return control from a subroutine
to the calling program. If RETURN is executed in a main
program, all files are closed, and control is returnedto the eMS Command evironment.
• dummy· is a dummy
string name which roust be included.
LINKAGESCALL (string, argl, ••• , argN) is used to call ,a subroutine
generated by
the SUBROUTINE
statement.
·string W
specifies a string containing the name of the called
subroutine, or may be a literal specifying the callee.
warg l,•••• ,argN W
are thestrings
passed tothesubroutine. Their names are independent of those usedin the SUBROUTINE statement, and matching is done
positionally.
A CALL statement may also 'include astatementlabel,.
and anunconditionaltransfer
specifying a return point. A call to the SORT routine,
described above, might appear as

The strings TEXTl"CHARl, and LENGTH are passed to thesubroutines as STRING, FIELD, and NOM, respectively.
On return, control goes to the statement labeled SEM.
Only three levels of nested CALLS are permitted, but up
to that depthl' CALLs may be recursive.
XCTL(name) overlays the currently executing SPL/l programwith the specified SPLl file, and starts executing thenew program. ·name· specifies a string containing thename of the called SPLl file, or i t may be a literal.
No arguments may be passed.
DEBUGGING AIDS
TR~CE_ON(dummy)

TRACE_OFF (dummy)
are used to turn the TRACE option on and off.
The
TRACE option may also be enabled by the -TRACE control
card. wdummy· is a dummy string name which must be
SNOBOL Programming361

present.
When the TRACE option is in effect,. thecontents of each string are placed in the LISTING fileeach time it is referenced. The assembler-interpreter
location counter value is included with each string.
The counter value refers to statement numbers in theassembler-interpreter
listingobtained
when
the-ASSEMBLY ON control card is used.
TIME (name)returns the current timer value in hundredths of asecond in the strinq specified.
Under CP. the timer
value is elapsed virtual CPU time since LOGON. It isuseful for comparative timings of programs.

362

SNOBOL Programming

BRUIN **Purpose:The
BRUIN
Interpreter.

commandinitiates

the

Brown

University

Format:BRUIN
Usage:The BRUIN environment is entered.
When the character >(greater than) is printed and the keyboard unlocks. theinterpreter is ready to accept a command.
A BRUIN commandshould thenbe entered
immediately following
the >character.
To leave BRUIN and returnissue the BRUIN command
CANCELto the CMS

command environment,

References:
BRUIN was developed at Brown University. Providence, Rhode
Island. For information on BRUIN and its commands~ refer tothe document CMS BRUIN User·s Manual.
Responses:
BRUIN
As the result of a null line being entered, the interpreteris confirming that the user is in the BRUIN environment .•BRUIN READY
The BRUIN environment
accept commands.

has been entered,. and it

is ready to

RiT=xx.xx/XX.XX hh.mm.ss.xx
The CMS command environment has been entered, where thefirst xx.xx is the CMS CPU time used in seconds!. and thesecond xx.xx is the total CPU time used.
For other responses:. refer to the references above.
Error Messages:
None.

**

BRUIN is a Type I I I program
Program Information Department.

BRUIN

availablefrom theIBM

363

UTILITIESThis section
contains those
CMS commands
which areutilitarian in function.
They include SORT, which sorts adisk file: COMPARE, which compares two disk files. record byrecord; TPOOPY, which copies a tape; MODMAP, which types out
the load map of an existing MODULE file: CNVT26, whichconverts 026 code to 029: and CVTFV, to convert fixedrecords to variable.
To dump files to tape or cards from disk, TAPE DUMP or DISKDUMP can beused, respectively~ To loadtape files
selectively, issue TAPE SLOAD: otherwise issue TAPE LOAD toload through n tapemarks. To load card images from a tapecreated by 05/360,. use OSTAPE.
To test terminal transmission" use ECHO.
out disk
files in hexadecimal.
use
respectively.

364

Utilities

To

print or typeor DUMPF

DUMPD

CNVT26
Purpose:The CNVT26 command converts a BCDle (026) card-image file to
EBCDIC (029), using the scientific character set.
Format:
CNV'l'26

filename

filetypeIfilename filetype is the file to be converted.
Usage:The specified file is searched for by the standard order ofsearch. It is converted using the scientific character set,
the old file 1S erased,. and the new file is given theoriginal name, type, and mode.
CNVT26 creates the work file BCDEBC UTILITY with the same
filemode as the file being converted.
If a file with theidentifier BCDEBC UTILITY already exists, it is erased.
Example:CNVT26 EASY FORTRAN
The file EASY FORTRAN is converted fro1l' BCDIC to EBCDIC;, theold file is erased, and the new file is given the orl~inal
name.
Error Messages:
E(OOOOl) FILE NOT FOUND
The specified file does not exist.
E(00002)
FILENAME(S) MISSING
Either the filename and/or the filetype were not specified
with the command. Reissue the command correctly.

CNVT26365

COMPARE

CVTFV

Purpose

Purpose:The COMPAB

The CVTFV command converts a
to variable-length records.

Format:file with fixed-length x

Format:, COMPAR
CV'l'FV
Osage:

1 filename filetype «T»Ifilename filetype is the file to be converted.

If the filcorrespondfrom the f
the second
the end of
The maximl
characters,
Responses:
EOF FILE n
The end ojeither 1 0]
NOT EOF FI]This messc
reached on

FILES HAVE'!'he files 1
size or thE(T) specifies that all trailing blanks are to be deBlanks and data in columns 73 to 80 are to be deleusage:CVTFV is particularly useful for incorporation of care
into SCRIPT files. If (T) is specified and the file coof SO-character records (a normal card file) II bytes 13
each card image aredeleted;, regardless of COl'!
Therefore, to convert card files without loss of info:rin columns 73-80, do not use the (T) option.
The standard order of search is used to locate the fil
old file is erased, and the new file is given the o:rname l• type,• and mode.
CVTFV creates a work file with a filetype of CVT~ afilename and mode of the specified file. If a file aexists with the same identifier as the work file,erased.
Example:PARAMETER 1:
Insufficier
RECORDS AlU
The record~cannot be (CVTFVUSERGUIDMEMO (T)The file USERGOIDMEMO is converted from fixedrecords to variable-length records.
If the file c(
80-character records,. columns 73-80 are deleted.
Error Messages:

Error Messa
E(OOOOl),E(xxxxx),E(OOOOl) FILE NOT FOUND
The specified file does not exist.
E(00002)
INCORRECT FORMAT
A T was not specified between the parentheses.

Examples:a. compare
The files 1:J
FORTRAN fivariable; t
366

E(00003) INCORRECT FORMAT
Either a filename and/or a filetype was not specifiE
the command. Reissue the command correctly.

368

CVTFV

E(00004) FILE IS ALREADY VARIABLE
The specified
file contains variable
therefore it cannot be converted.

CVTFV

lengthrecords.

369

DISI{
Purpose:The DISR command punches specified disk files on cards in a
special format. and can reload these card files onto disk
storage.
Format:I DISI{ I DUMP filename filetype <filemode> II

1 LOADI

DUMP specifies that a file is to be punched out.
filename filetype <filemode> specify the file to be punched.
LOAD specifies that one or more card files are toand saved on the user's permanent disk.

be readThe DISK card format is

I Columns I Content

1~~~--~~~--~-~-~---~----~----~----

1

2-4
5
6-55
56-51
58-16
77-80

a 12-2-9 punchI
I
blank. or N for EOF 1
file dataI
blankI
filename"type,.mode I
sequence number
1

CMS

Usage:For a
DISK DUMP
operation. filename,filetype " andoptionally filemode are specified. If the filemode isomitted!. all disks are searched. Only one file is punchedout by a command.
The file may have either fixed orvariable-length records. After all data is transferred. an
end-of-file card is punched with an N in column 5. This card
contains directory information, and must remain in the deck.
The original disk file is retained, unless the mode isdelete-after-reading.
The DISK LOAD operation reads any number of decks punched by
DISI{ DUMP.
File designations are obtained from the cardstream. and may not be specified with the command.
Any
existing file with the same designation as one of these in
the card stream is erased and replaced. DISK LOAD loads
files only onto the P disk.
Files to be310

loaded by a DISKLOAD command must be

DISI{

read byCP-61 as a single deck before the command is issued.. An
identification card with CP-61USERID in columns 1-10 and theuser·s identification starting in coluren 13 must precede thedeck.
Notes:a.

Data is punched in Extended BCD Card Code.

b.
Each filepunched out ispreceded
identification card containing the USERID.

by

a

CP-61

Responses:
DISK DUMP gives no response except the Ready message.
filename filetype filemode
DISK LOAD gives this response for each file encountered in
the input deck. The Ready message is typed after transfer iscompleted.
SYSTEM I/O ERRORCP ENTERED, REQUEST PLEASE
This message indicates that an unrecoverable I/O error has
occurred on a spooled direct-access device. ReIPL CMS andissue the DISK command again.
Examples:a.
DISK DUMP PROeS TXTLTB P5
The specified file is punched out. Each card contains CMS
in columns 2-4, file datain columns 6-55, and thecharacters PROCS TXTLIB P5 in columns 58-76. The cards aresequenced 0001, 0002, etc. in columns 11-80. The last card
contains an N in column 5.
DISI< LOAD
If the deck produced in the previous example has been readby CP-67. the disk file PROCS TXTLIB P5 is erased.
A newfile is created with the data on the cards;, and receives thedesignation PROCS TXTLIB P5.
The following response is
typed:PROCS TXTLIB P5
The Ready message is then issued to indicate completion.
b.

Error Messages:
E(OOOOl)

CORRECT FORM IS:-DISK DUMp· FILENAME FILETYPE FlLEMODE
OR -DISI< LOADThe format of the command was incorrect.
No cards
punched or read. Issue the command again.

were

E(00002)
FATAL PUNCH ERROR.
Indicates an I/O error on the card punch. This message
should never occur under CP-67.
Notify the responsible
DISK

371

systero programmer.
E(00003)
FATAL DISK ERROR.
AN I/O error on the disk occurred.
A DISK DUMP operation
may be retried. For a DISK LOAD operation, notify theoperator to enter the card deck again before retrying thecommand. If the error recurs, notify the operator.
E(00004)
FATAL READER ERROR.
Indicates an I/O error on the card reader or an empty
reader. If the reader was not empty. notify the responsible
system programmer.
E(00005)
ILLEGAL CARD IN DISK LOAD DECK.
A card was encountered in the input to DISK LOAD that was
not punched by DISK DUMP. A CP-67 output identification
card may have been left in the deck. or the wrong deck may
have been read. The deck being read at the time of the error
has been flushed. and will have to be reread before retrying
the command. No permanent file has been created.
E(00006)
END CARD ~ISSING FROM DISK LOAD DECK.
Physical end of data for a DISK LOAD was encountered without
reading the end-of-file card eN in column 5). The filecreated on disk does not have the correct designation. It
may be accessed under (DISK) (TFILE) P3. Note that the modeis delete-after-reading. so an ALTER or COMBINE must be
issued before inspecting the file.

312

DISK

DUMPD

Purpose:The DUMPD command prints the contents of one direct-accessrecord. specified by a CCHHRR address~ in hexadecimal on theprinter.
Format:I . UMPD I

,ccu

cc

<hh

<rr»

,

ceu is the device address,
cc hh

rr is theprintedcylinder~track.

and record number

to be

Usage:
The contents ofthe specified record is
printed inhexadecimal on the printer. If cc hh rr is not specified,or if one record has been printed, DOMPD requests anotherrecord address. To terminate DUMPD, issue a carriage returnwith no characters on the line.
Responses:
CC HH RR

Specify another cylinder, track (head), and record number.
If another record is not desired" issue a carriage return.
CORRECT FORM IS: DUMPD UUU CC HH RR
OR: DUMPD UUU WITH THE CCHHRR ENTERED ON REQUEST
No parameters were specified with DUMPD.
I/O ERROR ON DISR UNIT XXX,
= xxx .••• XXXI' SENSE = xxx ••• xxx
An I/O error occurred~ Check to see if
is outside the file boundaries.
CSW

SIO
510

the record address

CONDITION CODE 1
ERROR ON DISK UNIT xxx,

CSW = xxx ••• xxx,, SENSE = xxx .••• xxx.
An invalid device address was specified.

DUMPD

313

OUMPF
Purpose:The DUMPF command types the contents ofspecified file in hexadecimal.

all or partof aFormat:----------~--~-----~-----------~-------~-----~-~-IDUMPF I filenameI

filetype

I

<nl

•

n2

*

<n3»
80

filename filetype specify the file to be typed
n1 is the record number of the first record to be typed.
n2 is the record number of the last record to be typed.
n3 is the maximum number of characters of a record
typed, if the records are to be truncated.

to be

Usage:
The filenaroe and filetype must be specified.
If the firstrecord number and last record number are omitted. or
specified with asterisks, the entire file is typed out. An
asterisk in the first record or end record fields specifies
the beginning or the end of the file. respectively.
The number of bytes specified is printed or,if the numberof bytes is not specified. the full record is printed. If a
byte count is specified, the first record number and lastrecord number fields must be filled (either explicitly orwith asterisks).
The standard order of search is used to locate the file. In
the case of files with duplicate filename and filetype. only
the first file found is typed out.
Error Messages:
E(OOOOl) CORRECT FORM IS: 'DUMPF' FILENAME FILETYPE STARTLINEENDLINE LINE-LIMIT,
WHERE 'STARTLINE', 'ENDLINE', AND 'LINE-LIMIT' ARE
OPTIONAL .•E(00002) DISK ERROR
E(00003) FILE NOT FOUND

374

DUMPF

DUMP REST
Purpose:DUMPREST dumps the contents of the user·s permanent
onto tape, and can reload a disk from such a tape.

disk

Format:DUMPRESTA message is typed. requesting one of the following replies:
DUMP

.(D)

RESTORE (R)specifies that the contents of thedisk are to be copied on tape.

permanent

specifies that the permanent disk is is to beformatted. and contents of the mounted tape are
to be copied onto it.

Usage:The user's tape must be mounted at virtual device address
181 before the command is issued.
The disk address isalways virtual 191.
For both DUMP and RESTORE operations,the command positions the tape at the load point with a
REWIND.
'In the DUMP operation;, data on the permanent disk is copied
to the tape one track at a time. including all directories
and pointers. A RESTORE operation copies these records backto a disk in exactly the same locations.
The disk is
automatically set to eMS format, so a new or different disk
pack may be used.
Note:
RESTORE may not be valid if
virtual disk 191
has beenoperation.

the location of the user's
redefined since
the DUMP

Responses:
SPECIFY -DUMp· OR 'RESTORE :This Irlessage is typed. without a carriage return, as soon as
the command is issued.
When the keyboard unlocks, enter
DUMP or RESTORE, or just D or R, to specify the operation.
A reply error causes the response to be repeated.
DUMP/RESTORE MOVED nnn CYLINDERS.
THERE WERE nnn RECOVERABLE TAPE ERRORS.
This message is typed at the completion of the requested
transfer. If the number of cylinders specified is not equal
to the size of the virtual disk, an irrecoverable I/O error
DUMPREST

375

caused early termination.
Examples:a.

DUMPRESTSPECIFY 'DUMP' OR 'RESTORE': D
DUMP/RESTORE MOVED 005 CYLINDERS.
THERE WERE 000 RECOVERABLE TAPE ERRORS.
The contents of the user's permanent disk have been dumped
to tape. No errors occurred.

h.

DUMPRESTSPECIFY 'DUMP' OR 'RESTORE': restore
DUMP/RESTORE MOVED 005 CYLINDERS.
THERE WERE 000 RECOVERABLE TAPE ERRORS.
The contents of the user's permanent disk have been replacedby the contents of the dump tape.
No errors occurred.
Error Messages:
None. I/O errors are retried ten times.
If no recovery ismade. the second response shown above is typed.

376

DUMPRESTECHO
Purpose:The ECHO command
entered lines.

tests terminaltransmission by

retyping

Format:I
I 1J
I ECHO I <S
,
I X

I

,

1

<nn»1

U

The delete characters (ai, t ) are interpreted
lowercase letters are changed to uppercase.

S

Delete characters are interpreted but nouppercase translation is made.

X

No change is made in the line.

nn

Number of times line is1.

retyped.

t,

and any

lowercase to

The default value is

Usage:
When the ECHO command is issued, the Echo environment isentered and each line typed by the user is repeated by theterminal the specified number of times.
If no options, or an invalid option, are specified, U and 1
are assumed.
An entered line is interpreted according tothe option specified, if any, and then typed out n number oftimes. The keyboard is then unlocked to accept another line.
Control is returned to the CMS command environment by typing
RETURN as the first word of a line with no leading blanks.
Notes:
a.
If the X option is in effect, RETURN must be enteredwithout error to be recognized (delete characters and linend
are not interpreted).
b.
The Ready message
following
the RETURN request,
indicates that the user has left the Echo environment andentered the eMS command environment.
t•

Responses:
START CONSOLE TESTThe first line may be entered whenafter this message is typed.

ECHO

the keyboard

unlocks377

END CONSOLE TESTThe RETURN to OMS has been requested and accepted.
Examples:a.

echo u 2
START CONSOLE TEST
echo retypes any entered lines .•ECHO RETYPES ANY ENTERED LINES,ECHO RETYPES ANY ENTERED LINES,
returnEND CONSOLE TEST
R: T=O.15/0.32 10~14.40

h.

echo sSTART CONSOLE TEST
incgtIncluding Deletionssl. Backspaces, & special charac1
Including Deletions, Backspaces, & special characters,
ReturnEND CONSOLE TEST
R: T=O.3S/0.5B 10.11.36

c.

echo x 3
START CONSOLE TEST
Except in the X modet
Except in the X mode¢
Except in the X mode¢
Except in the X modet

returrGln
returran
returran
returrin
returnEND CONSOLE TEST
R; T=O.S7/1.02 10~20.30
Error Messages:
None.

318

ECHO

FORMAT
Purpose:The FORMAT command is used to initialize a disk area in the
CMS format,. to count the number of cylinders on a disk, orto write ~ label in the first 6 bytes of record 3 of the
disk.
Format:I
I
I FORMAT
I
I

m<ALL >< (NOTYPE)>1

C

L

R

<SYS>
nn

I
I
I
I

m

specifies the logical mode letter of the user's
disk area that is to be initialized. Any files on
this disk are erased.

ALL

specifies that all tracks of the specified disk
area are to be initialized. If omitted. the first
three records of Cylinder 0, Track 0 are skipped.

C

specifies that the command is a check only"
cylinders are to be counted, but not erased.

L

specifies that a label only is to be written on
the disk. No formatting is to take place.

nn

specifies that only the firstbe formatted.

R

is the same as C, but expands
bit-mask (PQMSK) to recompute
cylinders actually on the disk.

SYS

is used with FORMAT P R SYS to truncate disk
counts to leave room for the CMS nucleus aswritten by IPLDISK (on either 54 cylinder 2314 or
203 cylinder 2311).

(NOTYPE)

specifies that the format is to continue without
requesting any responses from the terminal.

andnn cylinders are toor reduces thethe number ofOsage:The disk mode must be specified. According to the option
selected!. the user's disk area is initialized by writing a
new home address and four records on each 2311 track, or
fifteen records on each two 2314 tracks. Any previous dataon the disk is erased.

FORMAT

379

Unless ALL is specified, the first three records of Cylinder
0, Track 0 are skipped. The ALL operand should be specified
in the FORMAT command whenever an unformatted disk area isaccessed for the first time, and is not normally needed
thereafter,. 1\ 6-byte label may be written in record 3 of thedisk.
If C is specified, data on the disk is not erased, and files
are preserved.
If L is specified, a '6-byte label may be written on cylinder
0, track 0, record 3 of the disk, preceded by eMS=. For the
T-disk, th~ label CMS=TDISK is always used.
A read-after-write check is made as the disk is formatted.

If nn isformatted.

specified,

only

the

first

nn

cylindersare

If R is specified, the number of cylinders are recomputed
and the PQMSK expanded or reduced accordingly. If SYS is
specified with the R. there is room left for the eMS nucleus
written by IPLDISK.
If (NOTYPE) is specified, there is no pause for YES or NO tocontinue formatting (see -Responses·).
Note:
If FORMAT is the first command issued after IPL, user files
are destroyed, regardless of the options specified. Enterthe LOGIN UFD command, or just hit RETURN before entering
FORMAT.
Responses:
m(ccu): nnn CYL
The number of cylinders formatted is typed
which disk was initialized.

out, indicating** FORMAT WILL ERASE ALL YOUR M-DISK (ccu) FILES **** DO YOU WISH TO CONTINUE? ENTER ·YES· OR -NO·:
This is typed out so the user can verify that the command
was issued correctly.
If so, YES causes the FORMAT to
begin; if not, NO causes a return to CMS without altering
the contents of the disk.
If (NOTYPE) is specified, this
response is not made.
FORMATTING M-DISK (ccu) •••This is typed after a YES is entered to inform the user thatformatiing is taking place.
m (ccu): n FILES, n REC IN USE, n LEFl' (of n), FULL (n eYL)
This is typed at the completion of a FORMAT M C to indicate
the counts returned frore the check.

380

FORMATExamp1e:
format p
P-DISR: 010 CYL.
The permanent disk is initialized by writing home addresses
and four blank CMS records on every track. Any files aredestroyed. The response indicates that the user's permanent
disk under CP consists of ten cylinders.
Error Messages:
E(OOOOl) PLEASE SPECIFY DISK: PERMANENT (P) OR TEMPORARY (T)The first parameter specified was not P or T.
E(00002) CONDITION-CODE 1 ON SIO IN FORMATTING DISK (BAD)
The condition code after Start I/O was issued indicates theoperation was not accepted.
Notify the operator.
E(00002) CONDITION-CODE 2 ON SIO IN FORMATTING DISK (BAD)
The condition code ·after Start I/O was issued indicates thechannel was busy.
This should not occur under CP. Notify
the system operator.
E(00002) CONDITION-CODE 3 ON SIO IN FORMATTING DISK (BAD)
The condition code after Start I/O was issued indicates thedevice addressed is not operational. Notify the operator.
E(00003)
UNEXPECTED UNIT-CHECR IN FORMATTING DISK
A unit check occurred. Notify the operator •.
E(00004) CE and DE NOT FOUND TOGETHER (VERY STRANGE)
Channel end and device end did not occur correctly. Notify
the operator.
E(OOOOS)Same as E(00002),
command.

exceptthat Cwas

specifies withtheE(00006) CE and DE NOT TOGETHER CHECKING NO. CYLINDERS
except that c was specified with -theSame as E (00004) ,.
command.
E(00007)
UNEXPECTED UNIT-CHECR NO. CYLINDERSSame as E(00003), except that C was specified withcommand.
E(OOOOS)NO T-DISK AVAILABLE.
The T parameter was specified, but
T-disk attached to hiro.

thethe user does not have aE(OOQ09) UNRECOGNIZABLE DASD DEVICE
device to be formatted is not either a 2311 or a 2314.

~heE.( 00010)
DISK. READ-ONLY
The disk is read-only, and therefore cannot be formatted.

FORMAT

381

E(OOOll)
YES was not typed in
ERASE ••• response.

as theresponse to the*FORMAT WILL

E(00012) DISR NOT ATTACHED
The disk specified is not attached to the user.
E(00013) FORMAT P R FAILURE
Data-loss would result if theare unchanged.

command executed.

The counts

E(00014) FORMAT P R SYS FAILURE
The disk is smaller than that required for use of
option. The counts are unchanged, and the user's
preserved.

382

FORMAT

the SYS
data isMAPPRT
Purpose:
MAPPRT creates, and optionally prints, a filemap of entry points in the CMS nucleus.

containing a

Format:

MAPPRT

I

A

I

£

I<N

ON

<OFF»
NO

A

creates the file CMS-NUC ALPHABET Pi, containing thenucleus entry points listed in alphabetic order.

N

creates the file CMS-NUC NUMERIC Pi" containing
nucleus entry points listed in numerical order.

C

creates the file CMS-NUC ALPHANUM Pl,
the A and N orderings.

ONtypes the file at the terminal.

OFF

prints the file on the offline printer.

NO

specifies that no output is requested,.

thecontaining both

Usage:The MAPPRT command creates a file on the user's permanent
disk containing' a list of entry points and their addresses
in core,. In conjunction with a listing of the CMS routines,
this information allows the system programmer to examine or
temporarily modify the nucleus in storage.
The first option specifies the format of the list,.
The
entry points are listed in alphabetic order if A is
specified. If N is specified, they are listed in the orderin which they appear in core,.
If no option, or C, is
specified,. both types of list are combined in a single file.
The fileIll.lme of the file created is always CMS-NUC. The
filetype is ALPHABET" NUMERIC, or ALPHANUM" depending on theoption specified. See Figure 36 for examples of the three
types of format.

MAPPRT

383

printf ems-nue alphabet
ABEND
ACTTABACTTAlALTER
ASMADDR
BATCH
BATSWT
BCKSPACE
BDEBUGBUFFERCARD PH

AT ODSB8
AT 01208
AT 01210
A-r 000'00
AT OOB30
AT 00000
AT OB5DC
AT OnSB8
AT OD4E4
AT OB8FO
AT On808

printf ems-nue numeric
ALTER
BATCH
ERASE
OFFLINESYSCTLTAPEIONUCON
USFL
STADDR
TBLNG
LSTADRLOCCNT

AT 00000
AT 00000
AT 00000
AT 00000
AT 00000
AT 00000
AT 00100
AT 00108
AT 00110
AT 00118
AT 001C4
AT 001ea

printf ems-nue alphanum
ABEND
ACTTABACTTAlALTER
ASMADDR
BATCH
BATSWIBCKSPACE
BDEBUGaUFFERCARDPH

AT OnSB8
AT 01208
AT 01210
AT 00000
AT 00B30
AT 00000
AT OBSDC
AT OnSBSAT OD4E4
AT 0~8FO
AT 00808

ALTER
BATCH
ERASE
OFFLINESYSCTLTAPEIONUCON
USFL
STADDR
TBLNG
LSTADR

AT 00000
AT 00000
AT 00000
AT 00000
AT 00000
AT 00000
AT 00100
AT 00108
AT 00110
AT 00118
AT 001C4

Figure 36.
Samples of the three types of nucleus map
files created by MAPPRT. Only the first few entries of eachare shown

384

MAPPRT

The second option specifies whether or not the file is to be
typed or printed. ON specifies output on the terminal r, andOFF specifies output on the offline printer..
If no second
option,. or NO. is specified t, no output occurs. The file isalways left on the permanent disk, whether or not output isr~quested.

Notes:a.
If only one or two addresses are needed, the N option
avoids the CPU time needed for an alphabetic sort of theentry points. Any address can be obtained by using the
LOCATE request in the EDIT environment.
MAPPRT should only be issued after CMS
initialized by IPL ccu, since MAPPRT uses tables
the nucleus loader.

b.

has been
set up by

Responses:
None. except under the ON option when the file is typed out.
Examples:a.
MAPPRT
With no options specified, both the default options aretaken. The file CMS-NUC ALPHANUM P1 is created, containing
both an alphabetic and a numeric listing of the nucleus
entry points.
b.
MAPPRT C OFF
The same action is taken as in the above example;.
file is printed on the offline printer.

and theError Message:
None.

MAPPR'r

385

MODMAP
Purpose:The MODMAP command types the load map associatedspecified MODULE file on the console typewriter.

with theFormat:
MOD MAP
filenamefilename I

is the filename of a file whose filetype is MODULE

Usage:The loader table;, which was in use at the time the GENMOD
was issued to create the MODULE, is typed on the console
typewriter.
Notes:a.

Transient area module load maps cannot be printed.

b. Any MODULE files created with the GENMOD (NOMAP) command
do not contain a load map.
Responses:
LOAD MAP UNAVAILABLE
The MODULE file was created with the
GENMOD, or is a transient area module.
FILE NOT FOUND
The module file cannot be found.

386

MODMAP(NOMAP) optionofOSTAPE
Purpose:OSTAPE creates CMS files from tapes produced by systems
by the 05/360 IEBPTPCH
other than CMS---for example.
utility ..
Format:JOSTAPEI <filetype <filename»
I
I
SYSIN
05TAPE(optionl ••• optionN

filetype
SYSIN

Filetype of the newly created files.
The default filetype.

filename

Name of the newly created file. Has
for NPDS files ..
The default filename,.

OSTAPE
PDS
NPD5

COLl
NeOLl

I
1

meaning only

Indicates that the tape contains many members of apartitioned data set, each preceped by wmember
name xx-.
Indicates that the tape does not contain manymembers of a partitioned data set;, each precededby -member name xx-.
Indicates that column 1 contains data. Data istaken from columns 1-80.
Indicates that column 1 contains carriage control
information. Data is taken from columns 2-81.

TAPx
TAP2

The x indicates the tape unit number.
Tape 2 is the default tape unit number.

END

Indicates that the END card means end of themember ..
Indicates that 'the END card does not mean the endof the member.

MAXTEN

Indicates that a maximum of ten files is to beread at one time. This is useful for long data
sets.
Indicates that ten is not to be the maximum numberof files to be read at one time.

NMAXTEN
Usage:OSTAPE creates eMS files from tapes produced by systems'
other than eMS. The tape must be 1n unblocked card image
format. It may be unlabeled,. or may have a standard OS/360
label.
A tape produced by the 05/360 IEBPTPCB utility may be used.
OSTAPE

387

OSTAPE assumes the file is going to the P disk.
Responses:
FILE

filename filetype COPIEDTEN FILES PROCESSEDMAXTEN has been specified and ten files have been copied.
Examples:a. OSTAPE (PDS TAP1 MAXTENThis reads a tape from drive 180 that was produced
IEBPTPCH of a PDS source file. ten members at a time.

byb.

OSTAPE DATA PAYROLL (COLlThis reads an unblocked card image tape fromcreates a single file called PAYROLL DATA.

drive 181 andError Messages!

E(00002)

TWO ADJACENT TAPE MARKS ENCOUNTERED

E(00003)
TAPE ERROR
Warning that a parity error
processed anyway.

388

ha

OSTAPE

occurred;

the record

is

SORT
purpose:SORT arranges the records from file 1 into fileascending order according to specifi~d sort fields.

2

inFormat:I SORT

filename1 filetypel filename2 filetype2 I

filenamel filetypel is the input file to be sorted..
filename2 filetype2

is the output filesorted records.

that contains

theUsage:The records-are sorted in EBCDIC order from filel to file2.
If duplicate records are found, they are written onto file2
in the order in which they are encountered in file1. All
records must be of fixed length to be sorted.
Filel and file2 must have unique identifiers, as SORT cannot
write the output back into the input file (file1). If theoutput file already exists;. the old file can be erased;, thesort can be terminated. the existing file can be appended
with the output, or a new output file can be specified,.
Once the SORT command is issued, it asks for the sort fields
to be defined via the following message:*ENTER SORT FIELD DEFINlTIONSThe sort fields are defined by typing pairs of numbers.
separated by blanks, where each pair is the starting andending character position of a sort field within each input
record and the leftmost pair is the major sort field. The
total number of pairs of sort field definitions that can beentered is limited only by the maximu~ number of charactersthat can be typed on one line and by the maximum number ofcharacters in the defined sort fields.
The total number of characters on which thebe sorted must not exceed 254 characters .•records are to

The sorting operation takes place with two passes of the
input file.
Pass one creates an ordered pointer table incore storage. Pass two uses the pointer table to read the
input file in a random manner and write the output file.
Therefore. the size of c'ore storage and the size of the sortfield is the limiting factor on the number of records thatcan be sorted at anyone time. An estimate of the maximum
number of records that can be sorted can be made by using
the following formula:
SORT

389

NR=

16000014 + NC

where NR is the maximum number of input records and NC is
the total number of characters in the defined sort field.SORT uses the standard order of search to find the file. The
sorted 'file is placed on the same disk from which the file
to be sorted was obtained.
Responses:* ENTER SORT FIELD DEFINITIONSDefine the character positions on which the records are to
be sorted. Type pairs of numbers., separated by blanks,
where each pair is the starting and ending character
position of a sort field within each input record.
*OUTPUT FILE ALREADY EXISTS, TO APPEND ITt, HIT RETURN ..
*TO ERASE OLD FILE, TYPE • ERASE' • *TO QUIT, TYPE'·QUIT' ,ELSE ENTER NEW FILNAM/FILTYP.
File2 already exists. Erase the old file" terminate thesort" or specify a new output file.
XXXX RECORDS READ ON PASS1.
The total number of records readxxxx.

from theinput fileis

Example:SORT CLASS MEMO ALPHCLAS MEMO*ENTER SORT FIELD DEFINITIONS
1
10
25
28
66 RECORDS READ ON PASS1.
R; T=O.30/1.06
15.06.47
The 66 records in file CLASS MEMO are sorted on positions
1-10 and 25-28. The sorted output is written into the newly
created file ALPHCLAS MEMO.
Error Messages:
E(OOOOl)*INPUT FILENAME/FILETYPE NOT DEFINED.
Both the filename and filetype were not specified for file1.
E(00002)*OUTPUT FILENAME/FILETYPE NOT DEFINED.
Both the filename and filetype were not specified for file2.
E(00003)
An endingfield.

*INCOMPLETE SORT FIELD PAIR DEFINITION.
character position was not specified for

E(00005)*INPUT FILE DOES NOT EXIST.
The file specified as filet does not exist.

390

SORT

a sortE(00006)*INPUT FILE IS NOT FIXED LENGTH FORMAT.
The records in filel are not fixed length. therefore~ theycannot be sorted.
E(00010)CANNOT ERASE INPUT FILE
The identifiers for file1 and file2 are the same--they must
be unique. as the input file cannot be erased .•

SORT

391

STAT
Purpose:The STAT command is used to (1) type out statistics on how
many records of the user's disk areas are currently in use,
(2) execute a routine to compact information in the disk
management tables, (3)indicate whether the disk is a 2311
or 2314~ or (4) indicate whether the disk is read-write orread-only.
Format:I STAT 1 <mode
1
I
*
I
?
I

<?»

,,
.1

mode specifies that only statistics for the disk
specified mode are to be typed out.

*

specifies that statistics on allout (read-only and read-writel.

disks are to be typed

If no operand is specified, statistics
disks are typed out.
?

with theon allread-write

specifies that additional information for the requested
disks is desired: that is, whether it is a 2311 or
2314 and whether it is read-write or read-only. As thefirst operand, specifies that a . brief status of all
logged-in disks is desired.

Usage:The STAT Command gives a count of the records in use on thespecified user- s
disks"
thenumber offree records
remaining" the percentagt.! of assigned records in use, andthe number of cylinders assigned to the user. Disk records
are always 800 bytes long.
If a ? is specified, the device type (2311 or 2314) and thedisk status (read-only or read-write)
is typed along withthe above information.
If a -? is specified as the only parameter, a brief statusof all logged in disks is typed: ie., ceu mode, R/O or R/w.
l,

Responses:
X-DISK (CeU): nnnn RECORDS IN USE" nnnn LEFT
FULL (nnn CYL.)This response is given for the disk specified.

392

STArr

(of nnnn), n

ccu x status
This response is given for each logged in disk when "thebrief mode is requested. The x is the disk model, and thestatus is either R/Ot, or blank for R/w.
Example:stat
P-DISK (191): 0111 RECORDS IN USE" 0229 LEFT (of 1000);, 111
FULL (025 CYL.)
T-DISK (192): 0000 RECORDS IN USE;. 0040 LEFT (of 0040) ;, 00'
FULL (001 CYL.)
options are
specified., statistics
Since nofor allread-write disks are typed out.
stat ?
191 P
193 A"P R/O
196 B,P R/O
19A S
R/O
The brief statistics are typed showing
currently logged in disks.

the statusof allformat.

Issue itError Messages:
E(OOOOl) INCORRECT ·STAT· PARAMETER-LIST
The command was entered in the incorrectagain.

E(00002) ** Z-DISK (ccu) NOT CURRENTLY LOGGED IN **The device
specified is
not partof yourconfiguration. Issue the console function LINK or
LOGIN Z ccu.

machinethe CMS

E(00003) ** NO READ-WRITE DISK(S) CURRENTLY LOGGED IN **The STAT-was isssued with no parameters. but no READ~WRITE
disks are currently logged in.

STAT

393

TAPE
Purpose:The TAPE command copies files from disk to taper, recopies
such tapes to the permanent disk, writes tape marks,
positions the tape, and scans the tape for file !dentifiers.
Format:
DUMP

LOAD

filename< n >filetype<filemode>

I
I
I

,
,

TAPE
REWINDSCAN < n >
SKIP
< n >
SLOAn filename filetype
WRITEOF <n>
DUMP

specifies that a disk file ismounted tape.

< TAPn > I
TAP2
< n

I
I
I

>

to be written

onto thefilename- filetype <filemode> specify the file to be written.

*

means all filenamer, all filetypes,
specified mode.

or all files of the

LOAD nspecifies all files on the mounted tape before thenext n tapemarks are to be copied on to thepermanent disk. n defaults to 1.

REWIND

positions the tape at the load point.

SCAN ntypes out the identifiers of the files that exist
on the tape in a tape-dump format until the next ntapemarksare encountered. n defaults to 1~

SRIP npositions the tape after thedefaults to 1.

SLOAD nscans the tape between the next n tapemarks forthe specified a·filename filetype a and loads it onto
the permanent disk. n defaults to 1.

next n tapemarks.

n

WRITEOF n writes n tapemarks at the point where the tape iscurrently positioned. n defaults to 1.
TAPn specifies the symbolic tape unit of the tape to be
written, loaded. or positioned.
TAP2 is thedefault, which corresponds to tape address 181.

394

TAPE

Usage:Filename and type" or asterisk. must be specified for a TAPEDUMP command.
Files may contain fixed or variable-length
records. The specified file is first copied on to a disk
utility file, then to the tape moUnted at virtual device
address 181.
TWo end-of-file marks are written after thedate transfer for safety, but the tape is backspaced overthem for subsequent DUMP operations. ~he last record of thetape file is flagged and contains directory information for
TAPE LOAD.
The TAPE LOAD command copies any number of files from thetape to the permanent disk. The filenames and filetypes are
obtained from the tape'l and may not be specified with thecommand. The filemode of all files is Pl.
Any existing
file on the permanent disk with the same designation as oneof the tape files is erased and replaced. Whenever a flagged
directory record is encountered on the tape, the file being
written on disk is closed, and a new file is started.
Reading continues to the n tapemark written by TAPE WRITEOF.
The TAPE REWIND command positions thepoint.

tape reel at the load

The TAPE SCAN command reads through n tapemarks and typesout the identifier of the files on the tape.
If twoadjacent tapemarks are encountered. TAPE SCAN terminates,.
The TAPE SKIP command positions the tape after the next ntapemarks encountered,. skipping the file at the current
position. Use of the TAPE WRITEOF and TAPE SKIP allows
access to individual files or groups of files.
The TAPE SLOAn co~mand scans the tapetapemarks for the specified file andpermanent disk with mode Pl.

between the next nloads it onto the

The TAPE ~RITEOF command writes n tapemarks wherever thetape is currently positioned. The tapemark is recognized by
TAPE LOAD as end of file.
Responses:
filename filetyp~ P1 LOADED.
TAPE LOAD gives this response as each file copied from tapeis completed. This response is followed by the Ready message
after the last file.
DUMPING •••Disk files are being dumped to tape andare typed out as they are dumped.

their identifiers

TAPn NOT READY YET
The tape is attached. but not physical1y~ in a ready status.

TAPE

395

(OK - READY NOW)
The attached tape has been readied and can now be used.
Notes;a.
The TAPE command can be used with a 7-track
density 800 BPI, converter on, ano translator off.

tape,

b.
The {EXEC) form of the LISTF command is usefulcopying all files, or groups of related files.

c.

for

The TAPE command does not handle Irultivolume files.

d.
TAPE DUMP and TAPE LOAD are valid even if the size or
location of the virtual disk is redefined between thecommands.

e.
Tape records written by ~APE DUMP are 805 bytes long.
The first character is a binary 2 (hex '02'),
followed by
the characters CMS and a blank (hex '40'), followed by 800
bytes of file data packed without regard for logical record
length. In the final record. the character N replaces theblank after OMS. and the data area contains directory
information (see program logic manual).
f.
Under CP-67, all tape units must be attached to the CMS
user before any tape I~O can occur. Refer to WOperating
Considerations--Tape Procedures w for information on theattachment of tapes.
Examples:a.
TAPE REWINDTAPE DUMP FILEA TEXT P5
TAPE DUMP FILEB TEXT P5
TAPE ~ITEOF
TAPE REWIND
This series of commands copies two user files to tape.
(Inthis and the following examples. the Ready message following
each command is omitted-.) The initial TAPE REWIND positions
the tape at the load point.
FILEA is then copied,. followedby the fla9ged directory record. The next record is thefirst of FILEB. TAPE WRITEOF places a tapemark after the
directory record of FILEB. and the final command repositions
the tape to the load point again.
TAPE SKIPTAPE DUMP SYSLIB MACLIB SYTAPE WRITEOF
TAPE REWIND
Asswning the same tape is mounted as in the previous
example, this series of commands copies SYSLIB MACLIB onto
the tape after the tapemark following FILEB. A tapemark is
written following the directory record of SYSLIB, and thetape is rewound to t-he load pOint.
b.

396

TAPE

c.
TAPE LOAD
Again using the same tape, this command erases FILEA fromthe disk, and rep1ace it with the tape copy. When the
directory record is processed. the following response is
typed:FILEA
TEXT
P1 LOADED.
Note that the mode is now P1. Because there is no tapemark
following FILEA" FILEB is read and replaces the disk copy of
FILEB. The response
FILEB
TEXT
P1 LOADED.
is followed by the Ready message when the tap ema rk is
encountered.
Another TAPE LOAD command would now copy SYSLIB MACLIB onto
the permanent disk as SYSLIB MACLIB P1. SYSLIB MACLIB SY on
the system disk would not be erased.
Error Messages:
E(00001)
INVALID TAPE COMMAND FUNCTION OR PARAMETER LIST.
The format of the command was incorrect, or the operation
specified was unknown. Retry the command. No operation was
performed.
E(00001)
FILE NOT FOUND.
The file specified with TAPE DUMP
operation was performed.
Check theretry the command.

was not found.
file designationNo
andE(00002)
FATAL TAPE ERROR WHILE WRITING.
An I/O error occurred which could not be corrected by ten
retries. Notify the operator to replace the tape.
Thismessage is also issued for errors during tape control
operations (REWIND, WRITEOF, SRIP). If TAPE SKIP was issued
at a point beyond which no tapemarks existed, the tape went
to end of reel. A subsequent DUMP, SKIP, or WRITEOF resultsin this message.
E(00002)

TAPn IS FILE PROTECTEDFATAL TAPE ERROR WHILE WRITING.
The ring is not in the tape, therefore writing cannot occur.
E(00002)

TAPn NOT ATTACHEDFATAL TAPE ERROR WHILE WRITING.
The tape is not attached, therefore it cannot be used.
Refer to ·Operating Considerations--Tape Procedures" forinformation on tapes.
E(00002)DISK ERROR WHILE READING.
An I/O error occurred while the file was being transferred
to or from the disk utility file. Retry the command. If
the error recurs. notify the operator. If the file wasdelete-after-reading;. see note 2 under COMBINE.
E(00003)
FATAL DISK ERROR.
An I/O error occurred, or, for a

DISK LOAD, the disk may be

TAPE

391

filled. To retry the command. reposition the tape with a
TAPE REWIND and the necessary number of TAPE SKIP commands.
If the error recurs, notify the operator.
E(00003)
DISK ERROR WHILE WRITING.
An I/O error occu·rred during transfer of the file to or fromthe disk utility file l, or the us.er's disk is full. Retrythe command. If the error recurs, notify the operator. If
the filemode was delete-while-reading, see note 2 under
COMBINE,. Note b.
E(00004)
FATAL TAPE ERROR WHILE READING.
An I/O error occurred. A tapemark may not be at the end of
the tape. Reposition the tape and retry the command. If theerror recurs" and the file has not been loaded, part of thefile may be recoverable under the designation (DISK) (TEMP).
See E(00006).
E(OOOOS)TAPE IS NOT IN -TAPE LOAD- FORMAT.
A tape record was read which was not written by TAPE DUMP .•The wrong tape is mounted, or reading has continued past theend of TAPE DUMP output because no tapemark was read.
E(00006)
ENDING RECORD OF FILE MISSING.
A tapemark or end of reel was encountered before the flagged
directory record of the current file.
Part of the file may
be recoverable under the designation (DISK) (TFlLE) P3.
Note that the mode is delete-after-reading, so an ALTER or
COMBINE command must be issued before inspecting this file.

398

TAPE

TAPEIO
Purpose:The TAPEIO command executes appropriate tape I/O commands.
Format:I
I
I,

TAPEIO I<TAP1>
function

I

TAPl corresponds to device 180.
TAP2 corresponds to device 181.
is specified.

TAP2

is assumed if no tape

Functions are as follows:
BSF
BSR
ERG
FSF
FSR
REWINDRUN
WRITEOFWTM

to backspace one file
to backspace one record
to erase a gap
to forwardspace one file
to forwardspace one record
to rewind the tape to load point
to rewind and unload the tapeto write a tape markto write a tape mark

Usage:The tape on the specified device is moved a single record orfile, is rewound and/or unloaded, a tape mark (end of file)is written~ or a gap is erased.
J

Notes:
a. The modeset is set to X·FF', therefore,
9-track tapeswith density 800, odd parity, and converter ~ off can be
manipulated with the TAPEIO command. If other'modes of tapes
are to be used, TAPEIO should be called as a function froman
Assembly
Languageprogram(see·eMS
NucleusRoutines--TAPEIO-).
b. The R~IND and RUN functions indicate completion before
the physical operation is completed.
Thus a subsequent
operation to the same physical ,device may encouter a ·device
busy· situation.
c. The TAPEIO command is identical to the TAPEIO function
except that TAPEIO READ and TAPEIO WRITE cannot be executedfrom the command level at a terminal. If either of these is
attempted, an appropriate error and error code are given(see below).

TAPE I 0

399

Responses:
TAPn NOT READY YET.
The specified tape has been attached but it is not readyyet. The following message is received when the tape drive
is in a ready status.

(OK - READY NOW)
The attached tape is now ready for use.
Error Messages:
E(00001)

An invalid function was specified.
E(00002)
An end of file or end of tape has been reached.
E(00003)
A permanent I/O error has
the tape.

occurred while reading or writing

E(00004)
An invalid symbolic tape unit was specified.
ECOOOOS)TAPn NOT ATTACHED.
The specified tape is not attached, therefore
cannot occur.
E(OOOOS)Same as prev'ious message i• but
first time this error occurs.

the message only

the function

prints theE(00006)
TAPn IS FILE PROTECTED.
The specified tape contains no file-protect ring, therefore
the tape cannot be erased or written on.
E(00001)
TAPn - SERIOUS TAPE ERROR ATTEMPTING function
An unrecoverable tape error has occurred on the tape while
attempting the specified function.

400

TAPEIOTAPRINT
Purpose:TAPRINT copies files from a specified tape to the offline
printer. The files must be LISTING files created by the
WRTAPE or ASSEMBLE commands.
Format:I TAPRINT I<TAPn> I-~-~--~~----~~-----

TAPn is either TAP1 or TAP2. specifying which tape is to becopied. If omitted:. TAP2 is assumed.•
UsagE;:TAPRINT prints tape files in the special format written by
the LTAPn option of the ASSEMBLE 'command and by the WRTAPE
command. Printing starts wherever the tape is positioned
when the command is issued~and continues until two
consecutive end of file marks are encountered.
Single end
Onof file marks are ignored, except for a message..
completion, the tape is rewound.
Responses:
EOF READ ON TAPE

A single end of file wascontinue.

read on the tape.

Printing will

PLEASE READY THE PRINTER
This message should not occur under CP.
END OF TAPE
Two consecutive end-af-file marks were encountered.
tape is being rewound, and control is passed to the
Command environment.

The
CMS

PERMANENT I/O ERROR ON TAPE.
An I/O error occurred. The command is terminated.
Example:TAPRINT TAP1

All the files up to the first two consecutive end-of-filemarks on the tape mounted on TAPl (at .180) are assumed to be
LISTING files and are printed on the offline printer.
Error Messages:
E (00001)

SD1BOLIC TAPE ADDRESS INCORRECT-.

The symbolic tape address specified was not TAPl or TAP2. No
action was performed.
TAPRINT401

TPCOPY
Purpose:The command TPCOPY is used to copy tape files.
Format:TPCOPY

TAP!
<TAP1

•

TAPo
<TAP 2

•

n

< 1

•

YES

I
I
I

< no »»*

TAPi is the input sy-.nbolic tape unit
TAPo is the output symbolic tape unit
n is the number of files to be copied and ranges from 1-9.
YES types out a summary of each file copied.
specified. no summary is assumed •If YES is not• specifies the- default is to be taken for each parameter.
Usage:
1-track tapes are read and written at 800
converter on, translator off.

bpi, odd parity,

If TAPi and TAPo are not specified. TAPl and TAP2
assumed, which correspond to 180 and 181 respectively.

are

If n is not specified. the default is one file to be copied.
The maximum record size is 4096 characters.
Note:
If TAPE DUMP was issued to write files from disk to tape andthat tape is to be copied l• the input tape unit is tape 181
or TAP2. Therefore TAP2 should be specified as the first
operand with TPCOPY.
Responses:
SUMMARY OF COPYThe YES parameter was specified with TPCOPY,. therefore
summary of the copy of each file is typed out.
FILE xxx
The xxx _is
the tape.

the sequence number of the fileabeing copied on

xxxxxxxx RECORDS, LENGTH = xxxxx BYTESThe number of records on TAPi and the maximum length of each402

TPCOPY

are specifi·ed.
xxxxxxxx,RECORDS COPIED
The xxxxxxxx is the number of
TAPo.

records copied from

TAPi toSUMMARY COMPLETE
Tbe summary typeout has terminated.
TAPE READ ERROR; BYPASS? (YES/NO)An error has been encountered whi1e reading the tape.. The
keyboard is unlocked for either a YES or NO response,. If
YES is entered, TPCOPY skips the error record, and cont.inues
reading_ If NO is entered. error code 1 is returned and
TPCOPY terminates.
SUMMARY TABLE OVERFLOW; SUMMARY CANCELLED
The summary has been canceled.

Error Messages:
E(OOOOl)TAPE WRITE ERROR: TERMINATING.

E(OOOOl)ILLEGAL FILE COUNT FIELD:
The number of files specified to be copied was less than one
or more than nine.

E(00003)

SAME UNIT REQUESTED FOR INPl1I' AND OUTPUT:

TPCOPY403

WRTAPE
Purpose:WRTAPE copies fixed-length format files from disk to tape·.
If thefiletype is
LISTING, assembler
and compiler
carriage-control codes are translated to machine cod.es.
Format:IWRTAPEI fname ftype

fname ftype specifies the file to be copied.
Usage:WRTAPE copies files from any disk to TAP1. Records areblocked in groups of ten" and the record format must be of
fixed length less than 256 bytes. No end of file is written
on the tape, and the tape is not rewound when the commandcompletes.
Although WRTAPE handles any file of the format describedabove. it is specially designed for LISTING files created by
the ASSEMBLE and FORTRAN commands.
These files contain acarriage control code for the offline printer as the first
byte of each record. WRTAPE translates the code into amachine code for the printer. Files are written on the tapein the same format as if the ASSEMBLE command had been
specified withthe (LTAPn)
option.
Thisformat is
acceptable to the TAPRINT command.
Notes:
a. WRTAPE does not write an end of file on the tape oncompletion, nor does it position the tape past any existing
files.
Use thefacilities of the TAPE
command for
positioning. To mark an end of file for TAPRINT, write two
end-of-file marks .•h.

Under CP. the tape must be attached by the operator.
expects TAP1,. addressed at 180, which should bespecified when you request the operator to attach the tape.

WRTAPEc.
Tape files written withrereading with TAPE LOAD.

WRTAPE are

Responses:
None.

404

WRTAPEnot suitableforExampie:
WRTAPE PROG LISTING
The file
PROG LISTING P5
is copied to
tape
with
carriage-control codes translated to machine codes, andrecords blocked in groups of ten.
If this is to serve as
input to the TAPRINT command, the following commands should
be issued:
TAPE WRITEOF
TAPE WRITEOF
TAPE REWIND
l•Error Messages:
E(00002) PARAMETER ERROR
Two parameters (filename and filetype) were not specified.
E(00003) VARIABLE LENGTH FILEWRTAPE does not handle files with variable record length.
E(00004) FILE NOT FOUND
No file with the specified filename and filetype was found.
E(OOOOS) FA~AL ERROR
An error occurred while reading the file from disk.
E(xxxxx) TAPE ERROR
A tape error occurred which
error code is unpredictable.

could not

WRTAPEbe recovered.

The

405

CONTROL COMMANDSThis section contains eMS commands that are used to control
the user·s environment at the console.
The BLIP command changes the character used to notify theuser of every two CPU seconds of execution time.
The
CHARDEF command allows the user to redefine the logicalcharacters, such as the character delete, line delete,
logical backspace, and logicaltab characters. LINEND
redefines the logical carriage return or line-end character.
SYN allows a user to define his own synonyms for commands.
CPFUNCTN allows CP console functions to be issued from CMS.
IPL loads a new copy of CMS into memory. KO, KT, and KX areused to kill overrides, typing, and execution respectively.
RT restores typing once it has been terminated by KT. LOGIN
sets up the user's permanent files for this terminal
session; LOGOUT updates the files on the P-disk and removes
the user from CMS; and RELEASE frees a disk when the user
has finished with it.

406

Control Commands

BLIP
Purpose:The BLIP command causes a string of from one to eightcharacters to be typed periodically during CMS operation.
The BLIP characters are typed out after every two seconds ofCPU execution and give the user an indication of theexecution time of his program.
Format:
BLIP

chars

<count>1(OFF)

chars is the character to be typed out, andcount is a digit from one to eight. indicating the number of
BLIP characters.
(OFF) sets BLIP to nothing so that there is no indication
after each two seconds of CPU execution.
Usage:The default setting of the BLIP characters is a sequence ofnonprinting characters--uppercase shift,. lowercase.
If it
is is desired to have a printed recording of the executionof a program, the BLIP characters should be changed toprinting characters (for example. a single dot).
Notes:
a. If the count parameterassumed.

is defaulted.

a count of

1 ish. If the first parameter is zero or if both parameters aredefaulted
the BLIP
characters arereset totheir
nonprinting default setting.•
l•c. If noncharacter codes are desired. the eight bytes for
the BLIP characters can be specified in hexadecimal in an
Assembly Lang~age Program.
Error Returns:
None.

BLIP

407

CHARDEF
Purpose:CHARDEF redefines the logicalcorrespond to hardware functions.

characters

in

CMS

that

Format:
CHARDEF.1

I

I functionI
code<replacement character> 1

Ifunction code:
B signifies the EDIT logical backspace character.
C signifies the character-delete symbol.
Ldenotes the line-delete symbol.

T signifies the EDIT logical tab character.
replacement characteris the character to be used for the
specified function. If a replacement
character is not specified, there isno symbol for that function.

Usage:The predefined characters in CMS for the character-delete
symbol and theline-delete symbol are thea and ~
respectively. If a character is not specified with either
CHARDEF C or CHARDEF L. there is no delete symbol for acharacter or a line.
The predefined logical tab character and backspace characterin EDIT are the I and the ~ respectively. If B or T is
specified, EDIT and CEDIT commands cause reference to bemade to the redefined symbols each time either editor is
invoked.
The function symbols that are redefined remain in effectuntil (1) eMS is reIPLeed, or (2) another CHARDEF command isissued. or (3) the user logs out of CP.
Note:
CHARDEF does not redefine the logical characters for CP-61.
Examples:a•
CHARDEF C ?
The character-delete symbol is now defined
can be used as a normal character.

408

CHARDEF

as?

The

a

b.

CBARDEF L

The line-delete symbol no longer exists.
used as a normal character.

Thet

can beError Message:
E(OOOOl)

Illegal function code was specified.

CHARDEFQ09

CPFUNCTN
Purpose:The CPFUNCTN command transmits console fUnction commands toCP-61 without leaving the virtual mode of operation.
Format:CPFUNCTNCP<NOMSG>

stringNOMSG is an optional argument to turn off typing of
ARGUMENT and INVALID CP REQUEST messages.

BAD

string is a CP-61 console function.
Usage:CPFUNCTN is provided to allow CP-67 console fUnctions to beissued from CMS and to be incorporated in EXEC files.
Examples:a. CPFUNCTNXFER OOD to CSCl
Executes an· XFER console function.

b. CP
NO~SG
DETACH
OOE
Executes a DETACH command. If OOE is not
the BAD ARGUMENT message is not typed.•a valid address.

Error Messages:
E(OOOOl)FUNCTION MISSING
No string was specified with the command.

E(00004)
INVALID CP REQUEST
string is not a proper CP-67 console function.
E(OOOOB)BAD ARGUMENT
The arguments supplied are not proper forthe specified console function.

E(xxxxx)
Any other error codes are dependent on theparticular console function designated.

410

CPFUNCTN

IPL
Purpose:IPL causes
a new
copy
initial-program loaded.

of

the

CMS

nucleus

to

be

is to

be

Format:, IPL I <devadd> I
devaddis the
IPL'ed.

address ofthe disk

device that

Usage:
This command performs the same action as the IPL console
function. If a devadd is specified, CMS gives the IPL toCP, which IPL's the specified device.
If no operand is included in the IPL command, IPLDEV in the
nucleus is checked to see what copy of CMS the user had beenusing (that is, if CMS had been IPL'ed by name or device).
This same copy of CMS is then brought back into core, andthe user receives a new copy of the version of CMS he had
been using.
Response:
CMS ••• VERSION nn ,LEVEL rom
This response indicates that a new copy of the nucleus has
been loaded and that control has transferred to the CMS
Command environment.
Example:ipl
CMS ••• VERSION nn LEVEL rom
A new copy of the CMS nucleus has been initial-program
loaded and the keyboard is unlocked to accept any CMS
command. If the user IPL'ed 190 originally, that copy of CMS
has been brought back in: if he IPL'ed eMS by name, the·saved ft system has been reloaded.
Error Messages:
None.

IPL

411

1(0
Purpose:The 1(0 command may be issued during the execution of acommand or user program to stop the recording of trace
information.
Forroat:
KO
Usage:The KO command causes recording of trace information,
initiated by the SETOVER orSETERR commands, to be halted.
KO differs from the CLROVER command in that it may be used
to clear overrides during the execution of a program. In
order for the KO command to be recognized, it must beentered after interrupting program execution by hitting ATTN
once to transfer to the CP environment, and a second time totransfer control to eMS.
Typing1(0 then causes all
overrides to be cleared, and no further trace information isrecorded.
Program
execution continues to
its normal
completion, and all recorded trace information is printed on
the offline printer.
Notes:
a. Entering KO as a normal eMS command has no effect. KO
has meaning only after two attention interrupts have been
generated during command or program execution.
b. If the keyboard does not unlock following the second
attention interrupt, internal processing is probably taking
place which does not allow interrupts from the multiplexer
channel.
As soon as this processing is conpleted. thekeyboard is unlocked and KO may be entered.
c. The character-delete symbol
and line-delete symbol
not valid when issuing the KO command.
d. Issuing the KO command has no effect unless
SETOVER command has been issued previously.

area SETERR or

Example:KO
Assuming that ATTN had been hit twice before typing KO" eMS
stops recording trace information, and, at the completion of
the currently
executing program,all recorded
trace
information would be recorded on the offline printer.

412

KO

Error Messages:
None.

KO

413

KT
Purpose:The KT command causes all terminal output generated by the
CMS command or user program in progress to be suppressed.
Format:
I<T

Usage:The KT command is used to stop terminal typeout from an
executing CMS command or user program. In order to enter
the KT command meaningfully. ATTN must be hit once tointerrupt execution
and transfer
control to
the CP
environment. and then a second time to transfer control to
CMS.
Program execution continues but the keyboard is
unlocked to accept user input.
Typing KT at this pointcauses all further terminal output from the executing
command or user program to be intercepted and suppressed.
Execution continues to normal program completion, when the
Ready message is typed out and normal terminal output
resumes.
Notes:
a. Entering KT as a normal eMS command has no effect. KT
has meaning only after two attention interrupts have been
generated during program execution.
b. If the keyboard does not unlock following the second
attention interrupt. internal processing is probably taking
place which does not allow interrupts from the multiplexer
channel.
As soon as this processing is completed, thekeyboard is unlocked and KT may be entered.
c.
(t)

The character-delete symbol (a) and line-delete symbol
are not valid when issuing a KT command.

Example:KT

Assuming that ATTN had been hit twice before typing KT:, eMS
would intercept and suppress any terminal output generated
by the program in progress.
Error Messages:
None.

414

KT

KX
Purpose:The XX command causes the execution of any CMS command oruser program to stop, closes any open files and I/O devices"reIPL's CMS, and returns the user to the CMS commandenvironment.
Format:RX
Usage:In order for the xx command to be recognized, it must be
issued after interrupting program execution by hitting ATTN
once to transfer to the CP environment, and a second time totransfer control to OMS.
Issuing the RX command then closes
any open use~ files and signals CP that the user has no more
I/O for offline devices.
After updating the user's file
directory, KX reIPL's eMS from the same device as it wasini tially IPL· ed"
and the user is returned to the CMS
command environment.
Notes:
a. Entering RX as a normal CMS command has no effect. KX
has meaning only after two attention interrupts have been
generated during program execution.

h. If the keyboard does not unlock following the second
attention interrupt, internal processing is probably taking
place which does not allow interrupts from the multiplexer
channel.
As soon as this processing is completed the
keyboard is unlocked and KX may be entered.
c.

Thecharacter-delete symbol

(a)

and

line-delete symbol(t) are not valid when issuing a KX command.

Response:

CMS ••• VERSION nn LEVEL mm
This response is typed whenever KX is interpreted, as eMS isreIPL' ed. The CMS command environment is then entered,.
Error Messages:
None.

KX

415

LINEND
purpose:The LlNEND command defines the logical line-end character tobe used~ in addition to the carriage return (new line).
Format:I LINEND I <c>c is the redefined logical line-end character,. If c is not
specified;. there is no line-end character defined, and thecarriage return is the only line delimiter.
Usage:The logical line-end character permits a number of logicalinput lines (each separated by the line-end character) to be
typed on a single physical input line. The physical input
line is terminated by a carriage return. Logical input
lines are terminated by the line-end character or by the
carriage return. Each call to read a line from the terminal
returns the logical input line. Subsequent calls to read aline from the terminal returns the logical input line which
was given following the previous logical input· line. The
line-end character can be used to input logical lines
whenever a physical line is input from the typewriter,whether to eMS or to a program. In addition, logical lines
can be input and stacked by use of attention to CMS (double
attention if from CMS and running under CPl. See ~erminal
Usage--Attention Interrupt-.
Notes:a.
The defined line-end character is the I, unless theLINEND command has been issued to redefine the character.
b. If the command LINEND is issued without any parameters,
only the carriage return is used as the line delimiter.
c. When a physical input line is read, it is scanned andprocessed according to the specifications in WAITRD.
Iflowercase to uppercase conversion is specified, the complete
physical input line is translated.
Thus, all logical input
lines are translated according to the initial specification.
d. The redefined line-end character stays in effect until
either CMS is IPL'ed again or LlNEND is reissued.
e. LINEND does not redefine
for CP-67.
f.
416

The

pound sign (#, isthe logical line-end character
also the logical

LINENDtab character.

LINEND takes precedence over the logical tab character .•Examples:a. LINEND!
The. line-end character is set to the exclamation mark (!).
b. LINEND
There is no longer a defined line-end character, therefore,
only the carriage return is used as a line delimiter in eMS.

Error Messages:
None.

LINEND

417

LOGIN
Purpose:LOGIN causes the user·s files on a specified disk to beeither saved or deleted. as specified, or bypasses theexecution of the PROFILE EXEC file.
Format:1 LOGIN I NOPROF

I UFO
I <No-UFD>
I NO_UFD
< UFD
>
I ccu
NO UFOIZ<,Y <fn <ft <fm»>
I
P
I

I
I
I
I
I
I
I

UFD indicates that the user's file directory <and hence all
existing disk files)
are to be saved.
(This is thedefault parameter .• )NO UFD indicates that the user's file directory is not to be'saved" effectively clearing his disk area and all
files stored on it.
NO-UFD has the same effect as NO UFD.

NOPROF indicates that the user's PROFILE EXEC file is not to
be executed.
ccu indicates the address of the disk that is to be used.
ccu must be a nonzero, hexadecimal number not toexceed 6FF.
Z indicates the mode of the disk

•Y

indicates the disk forread-only extension.

(that is!, P,T,A,etc.) •which this

disk

is

to be

a

fn <ft <fm»indicates on a read-only disk the files whose
directories are to be brought into core.

Usage:The LOGIN command may be issued at any time from the CMS
Command environment. If an operand is specified with LOGIN,
it must be either UID, NO UFO;, NO-UFD, NOPROF, or ccu. If
UFD is specified" the user's file directory, and hence allof his P-disk files, are maintained as they presently exist.
If NO_UFD or No-UFD is specified, the user file directory iscleared and all P-disk files are, in effect, erased.. If
NOPROF is specified r•
the execution of the PROFILE EXEC
418

LOGIN

feature is inhibited. In particular, NOPROF is used if the
PROFILE EXEC is to be bypassed or contains errors. If no
operand is specified, either 191 or the last disk that wasused as the P~disk is logged in as if LOGIN ccu were
specified. If tbe LOGIN command is not issued as the first
CMS . command after IPL· ing,. LOGIN UFD is assumed and all
existing P disk files saved.
LOGIN ccu allows the user to specify the device that hewishes to use. Z, if specified, is the mode of the disk--thedefault mode is Pi if Z is specified, Y may be specified todescribe this disk as a read-only extension of the Z-disk.
The user may also specify fn and, optionally, ft and fro toallow his use of only that specific file.
Notes:
a. If a user links to another Z-Disk and he already has a
Z-Disk. he must either reIPL eMS to read in the new file
directory, or issue LOGIN ccu.
Otherwise,. the old file
directory exists in core and the file directory of the newdisk is overwritten.
NO UFO or No-UFD performs the same functions as
P, that is, it obtains a "clean" file directory;
however~ it does not physically format the disk.
Therefore,
if the disk is already formatted correctly, this is a fastermethod of clearing the file directory.
h.

LOGIN

FORMAT

c'. If LOGIN ccu is issued as the first command and ccu is
not 191;. the normal 191 P-disk is not logged in. Therefore,
if 191 and ccu are both needed, LOGIN 191 first, then issue
LOGIN ccu.
d.
If a user wishes to login a disk which is normally
READ-WRITE in a READ-ONLY status;. he can do so by making thedisk a READ-ONLY extension of itself (for example, LOGIN 191
P,P).
Responses:** Z (eeU) IS READ-ONLY **The device specified as ceu is a read-only disk, therefore
writing is not allowed on the device. This response is only
a warning.
** CCU REPLACES Z (CeO) **This response is typed following a LOGIN ccu command. It
indicates that the device specified by the first ccu has
replaced that specified by the second ccu.
** ceu ALSO = Z-DISK **This response informs the user that the device ccu for which
he has just issued a LOGIN. is also defined as his Z-Disk.
This response is only a warning.

LOGIN

419

Examples:a.
LOGIN
The user's file directory for 191 is rEad into core.
b.
LOGIN NOPROF
The user's 191 file directory is read into core: however"the file PROFILE EXEC is not automatically executed.

c.
LOGIN 195 A,P
Disk 195 is ,logged in as A-disk"
and this is, defined
READ-ONLY extension of the user·s P-disk.

as a

d.
LOGIN 197
Disk 191 is logged in as the user's P-disk--it replaces thedisk previously defined as the P-disk.
Error Messages:.*

E(OOOOl) **z (CCU) FILE DIRECTORY UNREADABLE
Check that the correct disk is mounted. If so,
FORMAT P command.

issue theEC00002) **z (CCO) NOT ATTACHED **No Z-disk is attached to the user's virtual machine.
system operator.

NotifyE(00003) ** Z '(ceu) NOT -RECOGNIZABLE DEVICE-TYPE ••The attached ccu device is not a 2311"
2314, orcontact system operator.

2303.

E(00004) ** LOGIN NO UFO FAILED BECAUSE Z (CCU) IS READ-ONLY
A LOGIN NO_UFD erases files" therefore it may not be issued
for a READ-ONLY disk.
E(OOOOS) •• Z(CCU) OLD (1961 ERA) 2311 DEVICE ADDRESSES ••The disk specified is of the pre-1967 type that is
no longer supported by CMS.
E(00001) **CCU ALREADY ACCESSED AS Z-DISR (READ-WRITE).*•• -RELEASE CCU Z- IF DESIRED , RETRY ••The disk that you have just logged in as ccu is alreadyattached to you as a Z-disk.
These two descriptions areincompatible •• * LOGIN NO OFD FAILED; TRY -FORMATZ ALL- ••This message may appear as a second line to errors 1,2,,3, or
5. The disk needs to be formatted.

420

LOGIN

*.

LOGOUT
Purpose:The LOGOUT command compacts the user·s file directory,
executes any CMS command specified as an operandi, and logs
out of CMS" transferring control to the CP environment ..
Format:LOGOUT1<anycom>1

anycom is any CMS command
Usage:The LOGOUT command is not. required when use of OMS has been
completed. If issued. however, it causes a compacting
routine (identical to that which is called when the STAT C
command is issued) to be called. This routine reorganizes
the user·sfile directory. eliminatingblank entries
resulting from files which have been erased during thecurrent terminal session.. In addi tion, LOGOUT executes anyeMS command specified as its operand (LISTF. for example, toobtain a ·list of the newly organized file directory)~
Finally-. the Ready message is typed.. indicating in seconds
the CPU time used during this terminal session for CMS
execution as well as C~S and CP execution. The reviseduser-file directory is written out to disk, and control istransferred to the CP environment.
Notes:
a. Given the fact that the user-file directory is updated
on disk after the completion of each CMS command. it is notnecessary to LOGOUT from CMS to ensure that the user·sfiles
be saved.
b·. In order to log out from the CP-67/CMS system without
using the LOGOUT command,. ·hit ATTN once to transfer control
to CP and type LOGOUT to log out from the Control Program.
c. Even if the LOGOUT command is issued in eMS, it is also
necessary to log out from the Control Program. The CMSLOGOUT command can be bypassed, but the CP logout commandmust be issued to log off the system and disconnect the.telephone line.
Responses:
Ri T=xx.xx/xx.xx hh.mm.ss
CP ENTERED, REQUEST. PLEASE.

This message is typed whenever

the LOGOUT command is issued

LOGOUT421

in the eMS Command environment.
The first xx.xx is thetotal CPU time in seconds for CMS execution.
The second
xx.xx represents the total CPU time in seconds for CMS and
CP. These times are total times for- the terminal session.
The keyboard is then unlocked to accept any CP console
function.
Examples:a.

logoutR; T=18.32/43.21 12.15.28
CP ENTERED, REQUEST~ PLEASE.
The compacting routine is called, the indicated message istyped at the terminal. and control transfers to the CP
environment, where the keyboard is unlocked to accept any CP
console function.
b.
logout listf
The compacting routine is called. the LISTF command typesout the contents of the reorganized user-file directory/, thelogout message is typed,. and control transfers to the CP
environment. where the keyboard is unlocked to accept any
console function.
Error Messages:
None.

422

LOGOUT

RELEASE
Purpose:The RELEASE command frees an active
longer needs it.

disk when theuser nodisk

toFormat:I RELEASE I ccu mode «DETACH»
ccu

isthe device
released.

addressofthethat isbemode is the mode of the disk to be released.
(DETACH) means that the released disk is also to be DETACHED
from user's virtual machine (the equivalent of theconsole function DETACH).

The RELEASE command allows a user to release an active disk
when he no longer needs it. By specifying the (DETACH)
option" the disk may also be removed from the user's virtual
machine configuration in the same way as by the console
function DETACH.
RELEASE is useful in conjunction with the console function
LINK and the CMS command LOGIN,. when multiple disks are used
and/or users share disks on a ~D-ONLY basis.
Responses:
None.
Examples:a~
RELEASE 195 T
This command causes T-Disk 195 to be released by the user.

b. RELEASE 191 P (DETACH)
This command causes the P-Disk 197 to be released by theuser. It also detaches it from the user·s virtual machine
configuration so that it is no longer available to him.
Error Messages:

E(00001) INVALID -RELEASE- PARAMETER-LIST
The command was entered in incorrect form.
command format and reenter it.

Check

the

E(00002) NO ACTIVE-DISK-TABLE FOUND FOR GIVEN MODE
The disk mode specified is incorrect. Reissue the command

RELEASE423

with the correct mode.
E(00003) GIVEN DISR-NUMBER DOESN'T MATCH DEVICE-TABLE
The disk specified is incorrect. Reissue the command.

424

RELEASERT

Purpose:The RT command
restores the typeout
previously suppressed by the KT command.

at

the

consoleFormat:RT
Usage:The RT command restores console typeout from an executing
CMS command or user program that was previously suppressedby the KT command.
In order to enter the RT command
meaningfully. ATTN must be hit once to interrupt execution
and transfer control to the CP environment, and then hit asecond time to transfer control to CMS. Program execution
continues but the keyboard is unlocked to accept user input.
Typing RT at this point causes all further console output
from the executing command or user program to be typed out.
Execution continues to normal program completion.
Notes:a.
Entering RT as a normal CMS command has no effect. RT
has meaning only after two attention interrupts have been
generated during program execution.
b.
If the keyboard does not unlock following the second
attention interrupt. internal processing is probably taking
place which does not allow interrupts from the multiplexer
channel.
As soon as this processing is complete~. thekeyboard is unlocked and RT may be entered.
c.
The character-delete symbol (8) and line-delete symbol(,) are not valid when issuing an RT command.
Example:RT
Assmning that ATTN had been hit twice before typing RT eMS
restores any console output generated by the program inprogress.
i•Error Messages:
None.

RT

425

SYN
Purpose:The SYN command allows the user to specify
names to be used with or in place of thecommand names.

his own command
standard system

Format:I SYN ,<filename <filetype <filemode»<Coptionl ••• optionN»>
I
I
SYN
*
filename"

filetype,

and filemode are the identification of
the file
containing theuser-defined synonyms to be
used by CMS.

Options:
P

PUSER

STD
NOSTD
MIN
EXACT
CLEAR

Prints the standard system abbreviations anduser synonyms currently defined.
Prints only the user 'synonyms currently
defined,.
Stanaard system abbreviations are to be used.
This is the default value.
Standard system abbreviations are not to be
used.
Use minimum number of characters specified to
identify commands. The default value.
Use exact number of characters specified to
identify commands.
Clears any previously defined
set up by SYN.

synonym table

Usage:The SYN cOBmand permits user-defined names to be used either
alone, or in conjunction with the standard eMS systemabbreviations--that is. it permits the user to modify thecommand names acceptable to his own environment.
User-defined synonyms are located in a file identified as"filename filetype filemode" ,in the format shown in note 2
and the first example below.
If filetype is omitted. afiletype of SYN is assumed; if filemode is omitted, a modeof * is assumed. meaning any disk. If no file is specified,
no user-defined synonyms are set
up. and the systemabbreviations are used in themanner defined by the
specified options.

426

SYN

All options are specified between a pair of parentheses. The
default options are STD (use standard abbreviations) and MIN(allow a minimum number of characters to represent a
command). NOSTD f1a9s the standard system abbreviations as
unusable; MIN accepts abbreviations as long as the minimum
number of characters specified in the abbreviation table arepresent; EXACT accepts only the entry as specified.•
SYN can also be used to print out the list
abbreviations currently acceptable.

of synonyms andNotes:
a. SYN with no additional parameter is the same as SYN (P),that is. it types a listing of system and user abbreviations
currently in effect.
b.
The user synonym file -filename filetype filemode w
consists of SO-byte fixed-length records in freeform format
with columns 13-80 i9nored. The format for each record is1, system-commandII
1user-synonym 'count

1______________ 1

1_____

where count is the number of characters necessary for thesynonym to be accepted. If omitted /• the entire synonym must
be entered (see the first example below). SYN builds a tablefrom the contents of this file to use for command synonyms.
Responses:
SYSTEM ABBREVIA~IONS FLAGGED -NOT IN USEA request has been made to print the system abbreviations
while a previous NOSTO is in effect.
NO USER SYNONYM TABLE CURRENTLY IN USE
A request has been made to print the user-defined synonym
table while no such table has been defined by a SYN command.
Examples:a.

edit abb syn
NEW FILE
INPUT:
erase delete 3
combine copy

EDIT:
file
This creates a file ABB SYN which is a synonym table. In thefirst record of the file the count field is 3. This meansthat DEL. DELE. DELET. or DELETE are acceptable as the ERASE
command. However, with no count specified in the next line,'only COpy is acceptable as the COMBINE command.
SYN

421

b.
SYN
Types a list of the system abbreviations
currently in effect.

and user synonymsc.

SYN ABB (P)sets the synonym list found in file ABB SYN as well as thestandard system abbreviations as acceptable-- and prints
these at the console.

d.
SYN (PUSER)
Prints the contents
acceptable to CMS.

of theuser

synonym tablecurrentlye.
SYN ABB (NOSTD)
Allows the synonyms in file ABB SYN to be accepted by thesystem, and flags the standard system abbreviations as
unacceptable.
f.
SYN ABB (NOSTD MIN)
Only the synonyms specified in ABB SYN are acceptable.
However. a DELE is valid for ERASE as the minimum DEL ispresent.
g.
SYN ABB (NOSTD EXACT)
Only the synonyms specified in ABB SYN are acceptable.
However, DELETE must be entered to be accepted as ERASE.
Error Messages:
E(OOOOl)
INCORRECT 'SYN' PARAMETER-LIST
Invalid or mutually exclusive options were specified r•
is. P and PUSER. MIN and EXACT. STD and NOSTD).

(that

E(00002)
NO "ABBREV·IATIONS AT ALL (ABBREV NOT IN NUCLEUS)
The system being used does not support synonyms.
E(00003)
GIVEN USER SYNONYM FILE NOT FOUND
File "filename filetype filemode" was not found.
E (00004)

USER SYNONYM FILE BAD (MUST BE BO-BYTE FIXED RECORDS)

E (00005)

FAULTY DATA IN USERSYNONYM FILE

E(xxxxx)DISK ERROR READING USER SYNONYM FILE
code from RDBUF is returned as xxxxx.

42B

SYN

The error

LIBRARIESCMS provides
two types of libraries--macroand text(subroutine). Macro libraries are searched for missing
macros durin9 assemblies. The system macro libraries arecalled SYSLIB MACLIB SY and OSMACRO MACLIB SY.
SYSLIB
MACLIB contains the CMS macros, and OSMACRO MACLIB contains
the os macros (from SYS1.~~CLIB, ReI. 15/16).
Text libraries are searched for missing subroutines orundefined filenames during the LOAD. USE. or REUSE command.
The system text libraries are called SYSLIB TXTLIB SY,CMSLIB TXTLIB SY. PLILIB TXTLIB SY. and SSPLIB TXTLIB SY.
SYSLIB TXTLIB contains the FORTRAN library, CMSLIB TXTLIB
contains the non error wessage FORTRAN subroutines, PLILIBTXTLIB contains the PLl library and PL1 subroutines, and
SSPLIB TXTLIB contains the FORTRAN Scientific Subroutine
Package. TXTLIB allows up to 1000 entries per library.
To generate. add to, delete. or replace in macro or text
libraries .. use MACLIB or TXrrLIB respectively.
To specify
that certain libraries are to be used in addition to or inplace of the system libraries, use GLOBAL, which allows up
to ei9ht TXTLIBs to be specified.

Libraries

429

MACLIB
Purpose:The MACLIB command (1) generates a macro library, (2) adds,
deletes. or replaces macros in an existing library,()lists the name, size. and location of macro definitions in amacro library, or (4) compacts a macro library.
Format:libname filenamel, •• '. filenameN

1

GEN

IMACLIBADD libname filenamel ••• filenameN

I
I
I
I
1

REP libname filename1 ••• filenameN
DEL libname macronamel ••• macronameNCOMP libname
PRINT libname
LIST libnameGEN

generates the macro library ftlibname ft frommacro definitions in the specified file(s),.

the

ADD

adds the macro definitions from the specified
file(s) to the existing macro library ftlibname ft •REP

deletes the existing macro and adds the new copy

DEL

deletes thedictionary.

COMP

compacts the macro librarythat have been deleted.

PRINT

creates a file called ·libname MAP Pl ft containing
the name, size, and location of the macros in-libname-, and offline prints the MAP file.

LIST

types out the dictionary
specified by ftlibname ft •libnaroe

specifies the filename of a macro library.

specified

macro

entry

from

the

and removes the macrosofthe macrolibrary

filename1 •.•• filenameN specify the macro definition files tobe used in generating. adding" or replacing in themacro library -libname ft • The~r filetype must be
ASP360 or COpy,. Replace requires the filename tobe identical to the macro in the library.
macronamel,. '•• macronameN specify the macros to be DELeted.
Usage:A macro library is a file that has a filetype of MACLIB andthat contains macro defini'tions and a dictionary.
A macrolI30

MACLIBdefinition isa groupof 05/360
assembler language
statements identified by a unique name and used as an
expansion for a source statement in an 05/360 assembler
language program. The dictionary is generated by the MACLIB
command and is made up of macro definition names, theindexes or locations of the macro definitions within thelibrary. and the size or number of card images in each macrodefinition.
To be accessible to the MACLIB command, a macro definition
must first exist on disk in a macro definition file..
A
macro definition file is a file that contains card images ofmacro definitions written in
the System/360 Assembler
language, according to the rules for defining macros. A
macro definition file must have a filetype of ASP360.
The MACLIB Command functions are:
PRINT, and COMP.

GEN,

ADD, LIST,

DELr,

REP,

The GEN form of the MACLIB command creates a macro library
and assigns the identifier wlibname MACLIB Pl- to it. This
macro library is generated from the macro definitions in thespecified macro definition file(s) having a filetype of
ASP360 or COPY.
The ADD form of the MACLIB command appends the macrodefinitions from the specified macro definition files to theend of the existing macro library. As in the GEN form, thespecified macro definition files must have a filetype of
ASP360 or COPY, and the specified libname must have a
filetype of MACLIB.
The LIST form of the MACLIB command types out the name,index, and the size of each macro definition in thespecified library.
For an example of the output from the
MACLIB LIST command see Figure 31, which lists the CMS
system macro library SYSLIB MACLIB.

MACLIB

431

mac lib list syslib

INDEX

SIZE

MADTYPE

2
12
54
83
104
119

10
42
29
21
15
11

-rSTPA
CMS
CMLST
DJCB
BRETURNBCLOSE$ EXECSwr
SYSOUT
R; T=O.08/0.59

812
823
840
854
811
891
898
908
11.23.41

11
17
14
23
14
7
10
19

M~CRO

CMSTYPECMSAVECMSREG
MADCALL~ADDPL

Figure 31.

Example of MACLIB List command

The DEL function removes from the MACRO
the name of the specified macro.

library directory

The COMP function removes any previously deleted macros fromthe library.
The PRINT function creates the file "libname MAP P1" fromthe specified library and prints it on the offline printer.
The REP function replaces the existing code of the specified
macro,. with the new code from the ASP360 or COpy file of thesame name.
Notes:
a. The MACLIB command does not check the macro definitions
for errors: it assumes that the definitions are correct andthat the card images conform to the assembler language input
format.
b. Each specified ASP360 file may contain one or more macrodefinitions.
c. If a MACLIB file is being generated and a macro libraryalready exists with the same identifier ("libname" MACLIB
P1), it is erased and replaced by the library generated with
the MACLIB GEN command.
d. No checking for duplicate macro names between the ASP360
files and the existing MACLIB file is performed. The ASP360

432

MACLIBfiles are added to the end of the existing MACLIB file.
e. To print the contents of a macro definition. use the
PRINTF command and specify the index number as the starting
location and (index+size-l) as the ending location of themacro definition. For an example of PRINTF that prints the
CMSTYPE macro definition,. see Figure 38.
printf syslib maclib 73 86
MACRO
CMSTYPE &MESSAGE&LABELLA
1,TYP&SYSNDXSET PARAMETER LISTSVC
X·CAISSUE CALL TO TYPLIN
BC
15.TRA&SYSNDXBRANCH AROUND PARAMETER LISTDSOF(ALIGNMENT)
TYP&SYSNDX DC CL8-TYPLI-N·
COMMAND NAME
DC
ALl(1)CONSOLE NO.
DC
AL3(MES&SYSNDX)LOC. OF MESSAGE
DC
c·n·
RED INK.FIXED-LOCATION-MESSAGE
DC
AL3(L·MES&SYSNDX)LENGTH OF MESSAGE
MES&SYSNDX DC C&MESSAGEACTUAL MESSAGE
TRA&SYSNDX DS 08~LABELMEND

R: T=O.05/0.48
Figure 38.

11.30.52

Printout of the CMSTYPE macro definition using PRINTF

f.
A macro can be replaced by -filename ASP360". where
filename is the same as the macro name being replaced. The
replacement can also contain one or more macros none ofwhich have the same narne as the macro being replaced.
Responses:
None.
Examples:a.
MACLIB GEN LSLIB MACl MAC 2
The macro library LSLIB MACLIB is generated from the macrodefinitions in the MAC1 ASP360 and MAC2 ASP360 files. If
the file LSLIB MACLIB P1 already exists, it is erased andthe new file is generated.
b.
MACLIB ADD LSLIB IOSUB
The macro definitions in the file IOSUB ASP3~O are added tothe end of the existing macro library LSLIB MACLIB.
c.
MACLIB LIST SYSLIBThe names of the macro definitions in SYSLIB MACLIB
printed out along with each IDacro definition's index
size (see Figure 31)~

MACLIB

are
and

433

Errbr Messages:
E(OOOOl)INVALID MACLIB COMMAND FUNCTION OR PARAMETER LIST.
An incorrect form of the MACLIB command was given, or, theparameter list is invalid. Reissue the command with thecorrect format.

ERROR WHILE WRITING
E(00002)
An error occurred while writing the library on disk. The
library is closed and the command terminated. All of the
input card images that were processed before the error
occurred are included in the file "libname" MACLIB.
E(00003)
ERROR WHILE READING
An error occurred while reading the disk.. The library is
closed and the command terminated. If the GEN. or ADD formof MACLIB had been issued, all of the input card images thatwere processed before the error occurred are included in thefile wlibname~ MACLIB.

E(00004)
INPQT FILE NOT IN CORRECT MACRO FORMAT.
The ASP360 file is not in correct macro format--the card
images are out of order, the macro name is longer than eightcharacters, there is a blank in column 10, or a MEND card is
missing from a macro definition. The library is closed andthe command terminated.
All of the input card images thatwere processed before the error occurred are included in thefile wlibnaroe· MACLIB.
E(OOOOS)xxxxxxxx DOES NOT EXIST.
IGNORED.
An ASP360 or COpy input file does not exist. Check to seethat the specified file has a filetype of ASP360 or COPY.
E(00006)
MACLIB FILE SPECIFIED DOES NOT EXIST.
The specified library file does not exist--check to see thatthe specified libname has a filetype of MACLIB.
E(00001)
MACLIB FILE SPECIFIED NOT IN CORRECT FORM.
The specified libname is not a valid MACLIB file as createdby the MACLIB command.
E(00009)xxxxxxxx NOT FOUND IN DICTIONARY.
The macro xxxxxxxx does not exist in the specified macro
library. The MACLIB command is terminated. The macros in
the ASP360 files that were in front of the macro xxxxxxxx
have been replaced in the macro library.
E(00010)REPLACEMENT FILE NOT FOUND.
The specified filename does not exist with a
ASP360 or COPY.

filetype ofE(OOOll)
MACRO ALREADY EXISTS IN MACLIB
The specified macro already exists in the macro library, it
is not added again.

434

MACLIBTXTLIB
Purpose:The TXTLIB command (1) generates a text library, (2) adds toan existing text library:, (3) deletes from an existing text
library, or (4' lists. the entry points and control section
names, the location, and the size of the TEXT files included
in tb~ text library.
Format:
GENERATETXTLIBG

libname filename1.

ADD
A

libname filename1 ••• filenameNI• •filenameN

DELETED

libname csectname1,••• csectnameN

PRINT
P

libname

LIST
L

libnameGcreates the text library "libname wfrom the specified file(s).

ADDA

adds the contents of the specified file(s)to the existing text library "libname w •DELETE

deletes from the text library "libname"the specified control sections (csects).

GENERATE

D

creates the file wlibname MAP Pi" containing
a list of the entry points and control section
names of the TEXT files in the library. theirlocation. and the size of the TEXT file.

PRINT
P

LIST

provides the same information as PRINT, but the
information is typed out at the terminal insteadof being generated into a MAP file.

Llibnameis the name of the text library to be generated.
added to. printed. or listed. The filetype ofof libname must be TXTLIB.

filenamel.,.,.filenameN
specify the file(s) to be used ineither generating or adding to a TXTLIB file.
Their filetype must be TEXT.
csectnamelI• • •

csectnameN

specify the csectfs) to be deleted
TXTLIB

435

from a TXTLIB ·file. Entry points which are notcsectnames are ignored.
Usage:

A text library isa file that has a filetype of TXTLIB andthat contains a dictionary and the relocatable object codefrom TEXT files. The dictionary is created by the TXTLIB/
command which contains the entry points and control. section
namps, their location, and the size of each TEXT fileincluded in the text library. The relocatable object code
in T~XT files can be created by the Assembler, FORTRAN, or
PLI compiler.
There are five forms of the TXTLIB corrmand:
DELETE, PRINT, and LIST.

GENERATE, ADD,The GENERATE form of the TXTLIB comroand generates a text
library from the specified file(s)and assigns to thatlibrary the identifier wlibname TXTLIB Plw.
If a filealready exists with the identifier "libname TXTLIB Pi", theexisting file is erased. and the new file is created.
The ADD form of the TXTLIB command appends the contents ofthe specified TEXT files to the end of the existing text
library.
The DELETE forro of the TXTLIB command removes the specified
control sections frore the file "libname TXTLIB"~
If a
TXTLIB file has two control sections with the same name,only the first one is deleted (unless the csectname is given
twice in the argument list).
The order of the csectnames
given in the command argument is immaterial.
The PRINT form of the TXTLIB command generates the file-libname MAP Pl- on the permanent disk.
If a file alreadyexists with the same identifier, it is erased and the new
file created. The wlibname MAp w file contains the same
information as that in the dictionary of the specified text
library and is in the format of a list of entry points andcontrol section names that reside in the text library. theirlocation or index in the file, and their size in number ofcard iIPages.
The LIST form of the TXTLIB command types out the contentsof the dictionary at the terminal and does not generate thefile wlibnawe MAP Pl-. For an exarople of the TXTLIB LIST
command, see wLibraries w• The pound sign (I)indicates thefirst control section name in the file.
Both the PRINT and LIST forms of TXTLIB type out a statement
indicating the total number of entry points and control
section names that currently exist in the TXTLIB file.
For the usage of text libraries, see the GLOBAL command and"Operating Considerations--Library Usage-.
436

TXTLIBNotes:a. Each TEXT file that is to be included in the TXTLIB file
must consist of one or more control sections with an END
card image following each control section. This format is
automatically generated by the ASSEMBLE, PL/I, and FORTRAN
commands.
h. With the TXTLIB ADD command, the TEXT files are added tothe end of the existing TXTLIB file,and no checking for
duplicate entry
points orcontrol section
names isperformed.
c.
The total number of control section names and entry
points in the TXTLIB file cannot exceed 1000.
When thismaximum number is reached, an error message is typed out.
The text library created includes all the text files entered
up to (but not inciuding) the one that caused the overflow.
Responses:
xxx ENTRYS IN LIBE
When TXTLIB is issued, the contents of the dictionary of thespecified text library are typed out (see Figure 39). The
number of entries xxx in the text library are typed out wheneither TXTLIB LIST or TXTLIB PRINT is issued.
txtlib list a
ENTRY INDEX
LLHS#
2
LLHS
SUBD#
23
SUBD
SUB1
W#
47

w

SIZE
21
24
11

1 ENTRYS IN LIBE
R~

T=O.28/0~41

Figure 39.

14.13.12

Example of the TXTLIB LIST command

Examples:a. TXTLIB G SSP MEGOP MEG OPS
The file SSP TXTLIB P1 is generated from the files MEGOPTEXT, MEG TEXT, and OPS TEXT.
If SSP TXTLIB P1 alreadyexists, it is erased and the new file created.
b. TXTLIB ADD SSP MYROUT
The contents of the file MYROUT TEXT are added to theexisting file SSP TXTLIB. No checking for duplicate entries
is performed.

c. TXTLIB DEL A SUBDThe control section SUBn' in

text library

TXTLIB

A is

deleted.
431

TEXT LIBRARIESThis section covers the libraries
missing subroutines or undefined
execution of LOAD. USE, or REUSE.

that are searchedfilenames during

The libraries and their contents are outlined below.
TXTLIB

CONTENTSSYSLIB

FORTRAN library

CMSLIB

Nonerror message FORTRAN subroutines

PLILIB

PL/I library and subroutines

SSPLIEFORTRAN scientific subroutines

440

Text Libraries

for
the

SYSLIB 'I'XTLIBThe library SYSLIB TXTLIB contains the FORTRAN Library as
well as a number of CMS library subroutines. Refer to Form
C28-6596,. OS/360 FORTRAN IV Library Subprograms - for a
description of the routines from the FORTRAN library,. Thissection contains the descriptions of the subroutines written
for use under CMS.
The subroutines described are:Entry Point

Description

BLIP

Notifies user of executing program

TRAP

sets a user's
interrupt

NLSTON/NLSTOF
CPNMON/CPNMOF

returnfromanexternal

Allows free format I/O with NAMELISTDEFINE

Equates a data set reference number with a
CMS file and allows that file to be accessedat random

DSDSET

Changes record format and length for FORTRAN
disk files

GETPAR

Obtains parameters from eMS commands

ERASE

Removes a specified file from the disk

LOGDSK

Closes all open files and updates the P-disk

RENAME

Changes the identifiers of disk files

TAP SET

Changes default settings
tape units

REREADREREADV

Rereads a record with different formats

of FORTRAN logicalThis library provides extended
error messages.
These
include a traceback with registers 15,14,0, and 1 and theentry point location.
A standard fixup is taken, and asummary of errors is typed at prograro coropletion.

SYSLIB TXTLI~

441

BLIP Subroutine
Purpose:The BLIP subroutine causes a string of from one to eightcharacters to be typed on the console periodically duringeMS operation. The BLIP characters are typed out after
every two seconds of CPU execution and give the user anindication of the execution time of his program.
Calling Sequence:
CALL BLIP (·character-, count)
The count parameter roust be an integer from one
indicating the number of BLIP characters .•to eight

CALL BLIP (ee)If the count is defaulted, a count of one is assumed.
CALL BLIP (0)If the first parameter is a zero, the BLIP characters arereset to their nonprinting default setting (a space followed
by a backspace).
CALL BLIP (OFF)If the first parameter is (OFF). the BLIP function is turnedoff--that is"there is no indication every two seconds ofCPU execution.

Usage:The default setting of the BLIP characters is a sequence ofnonprinting characters. If it is desired to have a printed
recording of the execution of a program, the BLIP charactersshould be changed to printing characters (for example, asingle dot).
Error Messages:
None.

442

BLIP

NLSTON/NLSTOF Subroutines
CPNMON/CPNMOF Subroutines
Purpose:The NLSTON/NLSTOF
subroutines allow a user
to inputvariables to a FORTRAN program in a free format mode without
specifying the variable names, as is required with thenormal NAMELIST feature of FORTRAN.
Calling Sequence:
CALL NLSTON
To set the namelist feature to the free format mode.
CALL NLSTOF
To set the namelist feature to the norroal FORTRAN mode.
Usage:
Under the normal namelist mode, the variable name and an
equal sign must be specified with the value for eachvariable. In addition, the name of the list preceded by anampersand (&) must be specified before the values for thevariables are specified, and the terminating marker &END
must be specified after the values for the variables are
specified (see Figure 40).
Under the free format namelist mode., each variable is
specified in the same order as indio~ted in the namelist
statement. where each variable is deliroited by a comma or atab (see Figure 41).
To use this namelist feature, the routine NLSTON must be
called. This causes the free format mode to be in effect.
Read-and-write statements are then issued in the standardway.
To return to the normal mode, a call to NLSTOF should be
made. Thus, one can go from one to the other as desired.
Note:
CPNMON/CPNMOF are equivalent to NLSTON/NLSTOF.
Examples:&name a=l., b=2., c=3.
&end
Data specified under the standard name list mode.
1., 2., 3.

Data specified under the free format namelist mode.

NLSTON/NLSTOF

443

printf normal fortran* * 12

REAL*4A
INTEGER B
DIMENSION C(3)NAMELIST/LIST1/A,B,C
READ (S,LIST1)
WRITE(6.LIST1)
STOP
END
R; T=0.OS/0.1S 10.02.33$ normal
EXECUTION BEGINS •••&listla=l.,b=2., c=3., 4.,~&end&LISTl
A= 1.0000000 ,B=
2,C= 3.0000000 ,4.0000000 ,S.OOOO&END
R; T=0.32/1.02 10.10.4Q

Figure ·40.

Example of a normal NAMELIST function

printf freefrm fortran* * 12

REAL*4A
INTEGER B
DIMENSION C(3)NAMELIST /LIST1/ A,B,C
CALL NLSTON
READ(S,LIST1)
WRITE(6,LIST1)
STOP
END
R; T=0.03/0.48 10.11.56$ freefrm
EXECUTION BEGINS •••1,2,3,4,S&LISTl&END
A=1.000000 ,B=
2,C=3.0000000 ,4.0000000 ,5.0000
R; T=O.28/0.58 10.12.22

Figure 41.

444

Example of a free form NAMELIST function

NLSTON/NLSTOF

DEFINE Subroutine
Purpose:The DEFINE subroutine defines Fortran disk files that may beaccessed randomly and makes a correspondence between a eMS
file and a Fortran logical unit number.
Calling Sequence:
CALL DEFINE (dsrn, name;, type, recno, recsiz, <&n»
where
dsrn

is

the FORTRAN data set reference number
associated withthe defined
CMS file.
parameter must be a four-byte integer orvariable.

to be
This
int~gernameisthe filenaroe of theeight-bytes in length.

CMS

file

and it

must

be

type

is

the filetype of theeight-bytes in length.

eMS

file

and it

must

be

recno

must be a four-byte integer variable.
Each filedefined should use a different variable for recno.
This parameter indicates which record of the file isto be read or written.

recsizis a four-byte integer or integer variable that
contains the record length. All records must be thesame length.
If the file already exists, the valueof this parameter is reset by the DEFINE routine.
The maximum recsiz is 256K.

Usage:
DEFINE is used to make a correspondence between a CMS fileand a FORTRAN data set reference number, such that theidentifiers FILE FTxxFyyy are not required for FORTRAN disk
file reads and writes. Records may then be read or written
using a standard FORTRAN statement. Records can be accessed
either sequentially or randomly using the sequential I/Ostatements. Before each READ or WRITE statement the record
number must be set to the record wanted. After the executionof the READ or WRITE statement, the record number is
automatically increroented to point to the next record in thefile.
Thus, to READ or WRITE a file sequentially, thevariable for recno must be initially set to one before any
READ or WRITE statement is executed.
All c.ontrol operations
are ignored; however, resetting the variable for recno to
one is equivalent to rewinding the file, and setting thevariable for recno to recno+l is equivalent to skipping one
record.
Records may

be read andwritten without closing
DEFINEthe file.
445

Thus updating in place is easily accomplished.
For accessing FOR~RAN di$k files randomly. the normal
FORTRAN IV direct access 1'/0 statements should be usedinstead of the DEFINE subroutine.
Notes:a.
The user should remember that each READ or WRITE
statement increments the record number by at least one. If
the format statement indicates several records to be read or
written. the record number is incremented accordingly.
h.
Unformatted READ or WRITE statements may
only one record per statement.
c. Each different file should
recno.

read or write

use a different variable ford. A second call to DEFINE with the same dsrn undefines theold data set and associates the dsrn with the new data set.
e.

A maximum of 20 files may be defined for random access.

f.

Programs using DEFINE should not
PUNCH, PRINT, or READ statements.

use theunformatted

Error Messages from the CALL to DEFINE:
ILLEGAL DSRN SPECIFIED FOR DEFINEThis means that dsrn is specified asthan 99.

0, 5, 6, 7, or greater

ILLEGAL PARAMETER FOR DEFINEThis means that name or type was not specified, or, that thefirst byte of this filename is X~OO·.
TOO MANY DEFINE FILES
Maximum number of different files is 20.
DATASET DOES NOT HAVE FIXED LENGTH RECORDS
Error Messages during program execution:
DIRECT ACCESS RECORD NO.=O
This means that the record number variable for recno was set
to zero.
FATAL ERROR DURING DIRECT ACCESS READ (WRITE)
A fatal disk error occurred during the reading or writing ofa defined file and no ERR exit was specified in the user's
program.
EOF DURING DIRECT ACCESS READ
The record pointer variable for recno was set to a number
larger than the number of records in the file, and no END

446

DEFINEexit was specified in the user's program .•Example:The program below
uses CALL
sequentially and DSRN4 directly.

10

NUM=l
J=l
CALL DEFINE(2,·X
CALL DEFINE(q,·ABC
READ(4,10) K
WRITE(6,10) K
WRITE(2,10) K
FORMAT(1H ,1Q)
NUM=3
J=2
READ (4,10) K
WRITE (6,10) R
WRITE (2 .. 10) K
NUM=2
READ(4,10) K
J=3
WRITE(6,10) 1<
WRITE (2,10) 1<
STOP
END

DEFINE

DEFINEtoaccessDSRN2','Y',J,80)','DEFGHIJK',NUM,80)

441

DSDSET Subroutine
Purpose:The DSDSET subroutine enables a user to change the record
fo~at and logical record length for FORTRAN disk files.
Calling sequence:
CALL DSDSET (dsrn# blksize, recfm, lrecl)
where
dsrn is the FORTRAN data set reference number that is used
to reference the specified logical unit. This
number must be from 1-14 with exception of 5;, 6,
and 7.
blksizerecfm

is the byte count for the maximum size ofphysical records to be read or written on
specified unit.
isa type number from 1-5 ind1cating
format. The type numbers are:1) fixed record size, unblocked2) fixed record size, blocked3) variable record size, unblockedq) variable record size, blocked5) undefined record size, no blocking

the

the
the

recordlrecl is the byte count of the logical record to be read or
written. It is used for record format types 1-4.
For type 2 records, blksize must be an integral
mUltiple oflrecl; refer to
IBM System/360
Operating System FORTRAN IV (G and H) Programmer's
Guide (C28-6817) for a discussion of lrecl andblksize for variable type records.
Usage:A call to DSDSET is madeto change the default settings fordata reference numbers 1-14 with the exception of 51, '6, and7. If it is not required to change the association of adata set reference number with a symbolic tape unit, a callto DSDSET can be made instead of a call to TAPSET.. The
default settings for FORTRAN disk files are as follows:

q48

DSDSETData Set
Reference Number
1
2
3
4
8
9

10

Block
Size

Format
Type

80
80
80
80
133
80
80

1
1
1
1
1
1

1

Logical Record
Length
80
80
80
80
133
80
80

Notes:The default settings for FORTRAN logical units 5. 6. and 7
cannot be changed. Logical unit 5 is the sysin device toread from the terminal. and logical unit 6 is the sysout
device to write on the terminal. The default settings are
as follows.:
Data Set
Reference Number
5
6
7

Block
Size

Format
Type

80

1

120
80

1

DSDSET

1

Logical Record
Length
80
120
80

449

ERASE Subroutine
PUrpose:The ERASE subroutine removes
directory.

a filefrom theuser's fileCalling Sequence:
CALL ERASE (fname. ftype!, <fmode»
where
fname is the filename of the file to be erased.
ftype is the filetype of the file to be erased.
fmode is the filemode of the file to be erased.
Usage:ERASE is used to erase a filethe file directory).

(that is, to remove

it from

Examples:a. CALL ERASE (., ABCe

I, e DEF')

CALL EXIT
END

This sequence causes the reference tofrom the file directory.
b. REAL*8 NAME,TYPE
DATA NAME/'ABC'/,TYPE/eDEF
CALL ERASE (NAME,~YPE)

CALL ·EXIT
END
This sequence causes the file ABC
file directory.

450

ERASE

ABC DEF to be removed'/

DEF to be erased from the

GETPAR Subroutine
Purpose-:The GETPAR subroutine obtains the. parameters specified when
the command or program was called from eMS.
Calling Sequence:
CALL GETPAR (name, nurober <., -RITE-> <,&last»wherename is the variable (real*8) that is to take the value ofthe parameter indicated by the argument "number".
numberis the parameter number (inter*4) in the initial
parameter list of the parameter desired: it may be
any nonnegative value, with zero indicating thecommand or program name on initial entry. If number
exceeds the number of parameters in the string. no
parameter is passed, and control passes to statement-last- if &last is specified.

-RITE'

is an optional literal which causes the current
parameter to be right-justified in its doubleword
field, with leading blanks supplied. This is usefulin reading numeric parameters.

&last isan optional statement label to which control ispassed if "number w exceeds the number of parametersspecified.

Usage:
If GETPAR is called with item number equal to zeror,thecommand name or program entry is returned. If the error
return is not specified and the parameter corresponding to
the item number was not specified, the routine returns
without storing any parameter.
Note that blanks are not
returned for an unspecified parameter.
Example:CALL GETPAR (PARAM (I)~ I, '100)
Parameter I is stored in the array PARAM if it
specified: otherwise, control passes to statement 100.

GETPAR

was

451

LOGDSK Subroutine
Purpose:The LOGDSK subroutine closes all open files
file directory onto the permanent disk.

and writes the

Calling Sequence:
CALL LOGDSKUsage:The user should call LOGDSK during the execution of his
program if he wants to cause new or modified files to bepermanently written onto the permanent disk before thecompletion of the program and the return to the eMS commandenvironment.
Error Exit:
If the directory cannot be written out, the virtual machine
is put in disabled wait state and control is passed to CP.

452

LOGDSR

RENAME Subroutine
Purpose:The RENAME subroutine allows a file identifier to be changed
from within a FORTRAN program.
Calling Sequence:

CALL RENAME (aldfn, oldft, newfn, newft)
where
oldfn is the filename of the file to be changed.
oldft is the filetype of the file to be changed.
newfn is the filename to be given to the file.
newft is the filetype to be given to the file.
Usage:
is used to change the file identifiers of a file fromwithin a FORTRAN program.

RENAME

ExamEles:, , 'DEF

a. CALL RENAME (-ABC
CALL EXIT, , 'NEW, , 'DEF')

END

This program takes theidentifiers to NEW DEF .•

ABC

DEF

' / ,TYPE/'DEF'/,.NTYPE/'DEF

'/

file

and

changesitsb. REAL*8 NAME, TYPE" NNAflJE" NTYPEDATA NAME/' ABC
DATA NNAME/'NEW'/

CALL RENAME (NAME,TYPE,NNAME,NTYPE)
CALL EXIT
END
This program also changes file ABC DEF to NEW DEF.

RENAME

453

REREAD Subroutine
Purpose:The REREAD subroutine provides a facility for rereading arecord with different format statements without performing
any input/output operations.
Calling Sequence:
CALL REREAD (dsrn, <blksize»
wheredsrn specifies any data set reference number fromexcept unit 5~ 6, or 7.
blksize specifies thethe blocksize
bytes.

1 to 99.

blocksize for the reread record. If
is omitted. it is defaulted to 140

Usage:A call to REREAD is made when it is desired to specify areread unit or to change the data set reference number orthe blocksize.
To read a record from the reread unit asecond or subsequent time, a REWIND n statement must be
executed before the READ statement: if a subsequent reread
is issued w~thout executing a REWIND statement, an END OF
FILE condition results. Any input/output statements can beissued between a write and a read on the reread unit.
Error Returns:
None .•

454

REREADTAPSET Subroutine
Purpose:The TAP SET subroutine changes the default settings
FORTRAN logical tape units.

for theCalling Sequence:
CALL TAPSET (tapno, dsrn, <blksize>,. <trodeset>,<recfm>. <lr-Jcl»
wheretapno is an integer from 1-4 indicating the virtual tapeunit TAP1, TAP2, TAP3, or TAP4 corresponding to device
address 180, 181, 182. or 183.
dsrn is the FORTRAN data set reference number that is used
to reference the specified tape unit. This nuwber must
be from 1-14 with the exceptions of 5, 6. and 7.
blksize is the byte count for the maximum size of thephysical records to be read or written on the definedunit.
modeset is a code number for setting the mode mask for
7-track operations. The mask is ignored on all 9-track
operations.
The code numbers range from 1-15 in groups of 5. Codes
1-5 are for 800 bpi:, 6-10 for 556 bpi. and 11-15 for
200 bpi. Within each group of 5, the mode setting is
as follows:
1)
2)
3)
4)
5)
recfm

odd parity, converter on, translator off
odd parity. converter off. translator on
odd parity, converter off, translator off
even parity, converter off, translator oneven parity, converter off, translator off

is a type number from 1-5 indicating
format. The type numbers are:therecord1) fixed-record size, unblocked2) fixed-record size
blocked3) variable record s~ze, unblocked4) variable record size, blocked5) undefined record size, no blockingl•lrecl is the byte count of the logical record to be read or
written. It is used for record format types 1-4. For
type 2 records, blksize must be an integral multiple oflrecl; refer
to IBM System/360
Operating System
FORTRAN IV (G and H) Programmer's Guide (C28-6817) fora discussion of lrecl and blksize for variable type
TAP SET

455

records.
If the parameter blksize, modeset, recfm, or lrecl is zeroor omitted, the parameter is defaulted to that which waspreviously-set, or defaulted for the tape unit.
Usage:FORTRAN data set reference numbers 11-14 are the standard
logical tape units.
These units correspond to symbolicThedevices TAP1-TAP4. and to virtual devices 180-183~
default settings are as follows:
Vir
Dev

Sym
Dev

180
181
182
183

TAP1
TAP2
TAP3

Data Set
Ref

TAP4

Blk Modeset
Code
Size

11

80

12
13
14

133
800
1330

1
1
1
1

lrecl
1

80

1
2
2

133
80

133

The parameters blksize, modeset, recfm, and lrecl areassociated with the dsrn.. If a call to tapset is made withthese settings defaulted" the settings previously associatedwith the dsrn will still be in effect. If a call to TAP SET
associates a tape unit with a dsrn which is ,alreadyassociated with a tape, the tape previously associated withthat dsrn will not be associated with any logical unit. If
a call to 'TAPSET associates a tape unit with a dsrn
different from that with which it was previously associated,
the previous dsrn will be associated with disk files. If acall to TAPSET associates a tape unit with a dsrn which waspreviously associated with a disk file, a read or write tothat dsrn will be directed to the tape unit.
If the blocksize is defaulted, thetyped at the terminal or on sysout.

following message

is

TAPSET-BLKSIZE IS ZERO OR NEGATIVE; DEFAULT USED.
If the logical record length parameter is defaulted, thefollowing message is typed at the terminal or on sysout:
TAPSET-LRL IS ZERO OR NEGATIVE:

DEFAULT USED.

Note:
In the current eMS, TAP3 and TAPq are not defined, therefore
data set reference nurobers 13 and 14 should not be used.
Return Message:
TAPSE~-ONLY ONE ARGUMENT; CALL IGNORED.
The tape number, tapno. and the data set reference number,
dsrn, are required parameters. If a call to TAPSET is made456

TAPSETwith only one argument, the routine returns without altering
the settings for FORTRAN logical tape units.
Error Exits:(program terminates)

ABEND 1TAPESET-INVALID TAPE NUMBER: TERMINATING.
Only tape numbers 1-4 are legal paraweters.
ABEND 2TAPSET-DSRN IS GREATER THAN 14: TERMINATING.

ABEND 3

TAPSET-DSRN OF ZERO IS ILLEGAL: TERMINATING.

ABEND 4TAPSET-MODESET CODE IS GREATER THAN 15; TERMINATING.
Only the modeset codes from 1-15 are legal .•ABEND 5TAPSET-RECFM CODE IS GREATER THAN 5: TERMINATING.
Only the record format type numbers from 1-5 are legal.
ABEND 6TAPSET--DSRN5, 6

1,

AND 7 ARE

TAP SETILLEGAL FOR TAPE UNITS.

457

TRAP Subroutine
Purpose:The TRAP subroutine sets a user's return for an externalinterrupt. This return overrides the call to DEBUG on an
external interrupt.
Calling Sequence:
CALL TRAP (extrap)
where extrap is the name of an external routine
transferred to on an external interrupt.

which isCALL TRAP (0')
If the argument to TRAP is zero,
return is reset to go to DEBUG.

interrupt

the external

Usage:The interrupt routine should set a flag which should be
examined by tne main line program. After the flag is set,
the interrupt routine should issue a RETURN to the executing
program. The main line program should periodically examine
the trap flag to determine whether an external interrupt has
occurred.
Example:The following sample program illustrates the use of the TRAP
procedure, using a FORTRAN pseudo sense switch as the flagfor communicating between the interrupt routine and the mainline program.

10
20
30
100
200
300

458

EXTEFNAL EXT RAPCALL TRAP (EXTRAP)
fortran testtrao
CALL SLITE (0)T=2.23 15:26:58
DO 10 K=1,10000
CALL SLITET(2.1)$ testtrap
IF (1. EQ.1) GOTC 20
EXECUTION BEGINS. '••IF (1.NE.2) GOTO 30
50 TIMES
IF (~OD(R,50) .EQO)WRITE(6.100)K
100 TIMESCONTINUE
150 TIMESWRITE (6,200)
200 TIMES
250 TIMESSTOPWRITE (6,300)
300 TIMESSTOPeFORMAT(lX,11S-,TIMES·).
END OF RUNFORMAT(" END OF :RUN')
IHC0021 STOP
0
FORMAT (\. SENSE LITE ERROR'-)END
SUBROUTINE EXTRAPCALL SLITE(2)RETURNEND

TRAPCMSLIB (Non-Error-Message FORTRAN Library)
The library CMSLIB TXTLIB contains the non-error message
FORTRAN subroutines. To specify that these subroutines areto be used, issue the command
GLOBAL T CMSLIB SYSLIBThe routines contained in CMSLIB TXTLIB are listed below.
IHCFCOMH
IBCOM#FDIOCSI
INTS~iTCH

IHCCOMH2SEQDASD
IHCDIOSE
DIOCS'IHDFIOSH
FIOCS#IHCFINTH
ARITH#ADJSwrCH
IHCTRCBIHCERRM
DEFINEREREADREREADVIXCCMSCMSFORTR
The entries DEFINE, REREAD, REREADV, IXCCMS,
and CMSFORTR
are included in both SYSLIB TXTLIB and CMSLIB TXTLIB:, since
they are dependent on whether the extended error message or
non-error message subroutines are used.

CMSLIB459

PLILIB--PL/I Library
The library needed for PL/I execution is PLILIB. It resides
on the system disk. To specify that this library is to be
used, issue the command
GLOBAL TXTLIB PLILIB

460

PLILIBSSPLIB--FORTRAN Scientific Subroutine Library
SSPLIB is a text library residing on the system disk that
contains Version 2 of the FORTRAN scientific Subroutine
Package. For further information on these subroutines, refer
to System/360 scientific Subroutine Package--Application
Description (H20-0205).

SSPLIB

461

MACRO LIBRARIESSYSLIB--System Macro Library
The system macro library of CMS is called SYSLIBMACLIB and it resides on tbe system disk,. This
macro library is used by the ASSEMBLE command to
expand undefined macros.
For a discussion of the eMS macros in
MACLIB, refer to ftASSEMBLE--CMS Macros-.

SYSLIB

OSMACRO--OS Macro Library
OSMACRO MACLIB contains the OS macros. For a
discussion ofthese, refer
to -ASSEMBLE--OS
Macros,ft •To generate additional macro 1ibraries and modify them. see
the MACLIB command.
To specify that only certain macro
libraries are to be used during ASSEMBLE, see the GLOBAL
command.

462

Macro Libraries

CP-61 CONSOLE FUNCTIONS
To communicate with the Control Program (CP) and to simulate
the computer conso1e
the usercan issue CP console
functions.
These console functions allow the user toperform such operations as: initially loading the desired
system (that is, CMS>, dumping core selectively, closing out
files on unit record devices, displaying core and machineconditions, communicating with the operator in the computerroom, as well as with other users, querying the number ofusers on the system as well as other parameters, controlling
messages typed on his terminal, and beginning program
execution at a certain core location. The user also has theability to simulate the System/360 console system reset key,
to cause the Control Program to simulate an externalinterrupt, to replace specified parts of core, to readyspecified I/O devices, and to release the virtual machine.
Additional I/O devices can also be added to a specificvirtual machine and then be released for use by anothervirtual machine. The user can direct his spooled output to aparticular device, he can purge spooled input and output
files" and he can place his terminal in a dormant state, so
as to receive messages when he is not actively using theterminal .•l,

The Control Program environment is entered on the completionof thelogin procedure(see "Terminal
Usage-Logging
Procedures") •After the message READY AT xx. xx'. xx ON
xx/xx/xx is typed at the user·s terminal, where xx,.xx.xx is
the time of day and xx/xx/xx is the date, the keyboard is
unlocked and the Control Program is then ready to accept
console fUnctions. By typing IPL CMS or IPL 190, the user
loads the Cambridge Monitor System and he can begin issuing
CMS commands.
To load other operating systems,
type IPL
xxx, where xxx is the address of that operating system's
systems residence device: the terminal then becomes theoperator·s console for that operating system.
To reenter the Control Program from CMS, or other system
environment, the user must hit ATTN once.
This causes the
keyboard to unlock on the 21lJl. 1050, and TTY 33 or 35, andpermits the Control Program to ~ccept console functions. If
ATTN is hit again while in the Control Program, the keyboard
unlocks for an input line to be entered, such as a CMS
command or a line of data for the program being loaded andexecuted: control is thentransferred to the environment
from which the control program was entered.
For instance,
if the CMS command ASSEMBLE LOOPX had been issued, then ATTN
was hit twice and PRINTF LOOPX LISTING entered, the assembly
would continue, and as soon as it terminated, the LISTING
file would be typed out. If there is no desire to enter an
input line once the keyboard has unlocked, hit carriage
return and then control is transferred (as above), to theenvironment from which the Control Program was entered.. The
console function BEGIN is also used to leave the Control
Program: it causes control to transfer either to theConsole Functions463

environment from which CP was entered, or to a specific core
location. if one is specified,. See the CP BEGIN command formore details.
CONSOLE FUNCTION DESCRIPTIONS
CP console functions are issued in the Control Program
environment. Input can be entered in either uppercase or
lowercase. Enterinq input in lowercase enables the user todistinguish the input from the output. since all output is
typed in uppercase.
The Control Program has a character-delete symbol and aline-delete symbol, both of which are the same as thedefault characters in CMS.
The AT character (2) deletes
the immediately-preceding character from the input line anditself. It may be used repetitively to delete a strinq ofcharacters. The cent character (¢) or shift K (left bracket)
on the teletype, deletes all preceding characters in theline and itself. A character-delete symbol Ca) cannot be
used to delete a line-delete symbol ce). Note that if thecharacter-delete and line-delete symbols are redefined in
CMS, they are not redefined in CP.
The Control Program also has a logical carriage return orline-end character to allow,multiple console functions to be
typed on one line. The logical line-end character is the #and it cannot be changed. If the logical line-end characteris redefined in eMS via the LINEND command, it does not
redefine it for CP-67.
--One or more blanks must be used to delimit operands
arguments specified with the console functions.

or

A console function is accepted and executed if a carriage
return occurs and the keyboard is unlocked, unless theconsole function
caused control
to pass
to anotherenvironment, in which case the response is that of the newenvironment. If a console function is rejected, the message
INVALID CP REQUEST is typed.
If invalid operands are
specified with a console function, the roessage BAD ARGUMENT
xx is typed, where ~x is the argument number.
If only one
operand is specified and it is invalid, the console function
is not executed. If multiple operands are specified, andpart of them are invalid, the valid operands specified
before the first invalid operand are executed properly. If
a null line is entered to CP (that is, a carriage returnwith no previous characters in the line) the confirming
message CP is typed.
The console functions that arelisted below.

464

available for theConsole Functions

user areCONSOLE FUNCTIONS
BEGIN

initiates execution at either a specified core
location or at the location specified on thecurrent PSW (which is normally the location fromwhich the Control Program was last entered)

CLOSE

releases the spooling areas from the specified
multiplexer devices, and the actual I/O operationis performed for any output

DETACHremoves the attached device whose address is
specified frow. the virtual machine configuration

DISCONNcauses the terminal to be
virtualmachine, while
continues to run

DISPLAY

types out in hexadecimal the contents of thevirtual machine·s core storage, general-purpose
registers, floating-point registers, and/or PSW

DUMP

prints in hexadecimal on the virtual printer thecontents
ofcore
storage,general-purpose
registers, floating-point registers, and/or the
PSW

disconnected from thethe virtual
machine

EXTERNAL

simulates an external interrupt on the virtual
machine and returns control to that machine

IPL

causes the Control Program to simulate an Initial
Program Load sequence on a specified device, andclears all virtual storage to zeros.

IPLSAVE

causes the Control Program to simulate an Initial
Program Load sequence ona specified device
without first zeroing core.

LINK

attaches the specified device to the requester's
virtual machine, based on information contained in
the CP-61 User Directory

LOGOUT

removes the user from the system by releasing thevirtual machine and any attached devices, byclearing the temporary disk area, and by closing
the spooling areas

MSG

sends a specified message to a specific user

PURGE

allows the user to delete all spooled files (notcurrently processed for output) from his virtual
printer or punch, or to delete all his spooled
input for his virtual card readers without reading
the data

QUERY

types out

the number of users logged on or dialed,
Console Functions

465

the identification and terroinal address of theusers loqged on, theterminal address of a
specific logged-on user (or a message that he is
not logged on), the log roessage sent by theoperator, the number of spooled input and output
files currently held by CP for the user, or theamount of connect, virtual CPU, and total CPU
times used since login.
READY

simulates
addressa device end

for theRESET

simulates thecontrol panel

SET

allows the user tosave the card file in his
virtual card reader, to control the messages andwarnings typed at his terminal, and to control his
running status

SLEEP

allows the user to place his terminal in a dormant
CP mode such that he may receive messages without
hitting carriage return

SPOOL

allows the user to direct his spooled output to a
specific unit record device at the computing
facility and to control the nature of reading
spooled input files

STORE

replaces the contents of specified locations incore
storaqe,
general-purpose
registers,
floating-point registers, and the PSW

XFER

controls the passing of files between users

466

Console Functions

system reset

key

specified virtualonthesystemBEGIN
Purpose:BEGIN initiates execution ateither a specified core
location or at the location specified in the current PSW<which is normally the location from which the Control
Program was last entered).
Format:

I
I

BEGIN
B

<hexloc>

hexloc is the hexadecimal core location at
is to be9in.

which execution

Usage:BEGIN transfers control to the specified hexadecimal core
location. If a hexadecimal core location is not specified,execution resumes from the location contained in the current
program status word (PSW)--thisis normally from the
1ocation at which the Control Program was last entered,unless the PSW was previously changed. For example. if theConsole Program had been entered from CMS by hitting ATTN.
and BEGIN is issued without specifying a core location" eMS
is entered at the location from which it was left.
Responses:
BAD ARGUMENT xx
An invalid hexadecimal core location was specified
argument number xx. Correct the request and issue again.

inAny other response will be that of the new environment.
Examples:a.
b
Execution resumes
entered.

at thelocation fromwhich CPwas lasth.
b 15000
Control is transferred to hexadecimal core location 15000.

BEGIN

467

CLOSE

Purpose:
CLOSE releases the spoolingmultiplexer devices. and theperformed for any output.

areas f'rom the specified
actual I/O operation is

Format:
CLOSE

devaddC

devadd is the device address of the virtual card reader,card punch, and printer. which are normally OOC,
OOD. and OOE, respectively, for CMS.
Usage:In releasing the spooling areas for the virtual card punchor printer, CLOSE punches or prints the contents of thespooling area on the real device when that device becomes
available. The printed output is preceded by one page whichcontains the user·s identification, the date, and the timeof day.
The punched output is preceded by one card which contains
the user's identification. the date. and the time of day, inthe following format:
columns 1-10
columns 13-20
columns 25-32
columns 37-44
columns 49-80

CP67USERID
user·s id, left-justified
date hnm/dd/yyl
time (hh.mm.ss)
asterisks (*)

This punched ID card is in thethe input identification card
card reader input for users.

correct format to be used as
required by CP for spooled

In releasing the spooling area for the virtual card reader,
CLOSE assuroes that the user has read all the cards he wantsfrom the current card deck and frees the spooling area. If
another command to read a card is then executed, CP returns
either the first card of the next deck it has read for thatuser (if any), or reader-not-ready.
Notes:a.
CLOSE OOE must be given after the DUMP console function
has been issued.
h.
Logging out from CP automatically issues a CLOSE forthe virtual card reader. printer, and punch and releases all
468

CLOSE

spooling areas.
Responses:
BAD ARGUMENT xx
An invalid device was specified in argument number xx.
Examples:c e
The spoolingreleased,.

area forthe virtual

CLOSE

printer isprinted and469

DETACH
Purpose:
DETACH removes the specified
virtual machine configuration.

attached

devicefromtheFormat:
DETACHDE
devaddrI
1

devaddrspecifies theaddress of a device
that hadpreviously been attached to the virtual machine.

Usage:
DETACH removes the specified device from the user's virtual
machine configuration for the current session. DETACH is
also used in conjunction with the console function ATTACH,
which can only be issued by the CP operator. Once a device
has been ATTACU'ed to a virtual machine (see "Console
Function Applications" for a discussion of attaching I10
devices), the responsibility is left to the user to remove
or detach the specified device from his configuration.. Aslong as the device is attached to him" it is unavailable foruse by any· other user.
DETACH removes the specified device from the configuration.
As soon as the device is detached, the message DEV devadd
DETACHED is typed out at the terminal and the device is free
for use by other users.
Also, a message is automatically
typed out to the CP operator specifying the device that is
free. If the device address detached is that of a tape
dri ve,. the tape is rewound and unloaded.
Responses:a.
BAD ARGUMENT xx
An invalid argument was specified.
b.
DEV devadd DETACHED
The specified device address is no longer usable.
device must be attached again for further use.

Thec.
NONEXlsTENT UNIT
The specified unit does
configuration. Either it
attached.

not exist in the virtual machine
has been detached or it never was

410

DETACHExamples:a.

DETACH 181
console function:
detach 181
response:
DEV 181 DETACHED
Unit 181 is detached from the virtual machine configuration.
h. DET OOC
The spool reader
machine.

OOC

is removed

DETACHfrom

the users

virtual471

DISCONN
purpose:DISCONN causes the terminal to be disconnected from thevirtual machine, and the virtual machine continues to run.
Format:DISCONN 1<anything> I

anything is any nonblank character string that signifies thephoneline isnottobe hung
up
upon
DISCONN-ecting
Usage:
nISCONN causes the terminal to be disconnected from thevirtual machine.
The virtual machine continues to run as
though the user had issued BEGIN.
Any "writes" to theterminal (virtual console) are ignored. The virtual machine
is automatically logged out if a "read ft is attempted fromthe terminal, or if the virtual machine goes into thedisabled wait state. The DISCONN'ected virtual machine runs
with low priority in Q2 of the dispatcher.
If the <anything> option is selected, the line is notdisabled.
The terminal can then be used to LOGIN withanother userid, or to DIAL into a mUltiaccess system.
At alater time, auser can ftreconnect"with his
DISCONN·ected machine simply by following the normal login
procedure. This reconnection can be made from any terminal.
The message:
RECONNECT AT xx/xx/xx ON xx/xx/xx
is printed upon reconnect ion and the terminal is placed inconsole function mode,.
To continue running the virtual
machine, a BEGIN is required,.

472

DISCONN

DISPLAY
Purpose:DISPLAY types in hexadecimal the contents of the virtua1
machine'scorestorage"general~purpose
registers.
floating-point registers"
i:lnd/or program status word. For
virtual 360/67 on1y. DISPLAY also types the contents of thecontrol registers.
Format:II
1

DISPLAY
D

I,

hexlocI <hexloc> <hexloc1-hexloc2> <Lhexloc>

1 <Lhexloc1-hexloc2> <Greg> <Greg1-reg2>
I <Yreg> <Yreg1-reg2>
I <Xreg> <Xreg1-reg2>
I <PSW>is interpreted the same as Lhexloc.

hexlocl-hexloc2 is interpreted the same as Lhexloc1-hexloc2.
Lhexloc

displays in hexadecimal the contents
specified hexadecimal location hexloc.

ofLhexloc1-hexloc2 displays in hexadecimal the contents of thespecifiedhexadecimal
locations
hexloc1-hexloc2.
Greg

displays in hexadecimal thegeneral-purpose register reg,an integer ranging from 0-15.

Greg1-reg2

displays in hexadecimal the- contents ofgenreal-purpose registers regl-reg~, wherereg1 must be less than reg2, and each reg
must be an integer ranging from 0-15.

Yreg

disp1ays the contents of-the floating-point
register reg, where reg is an integer
rang~ng from
0-7. If reg is odd, it isadjusted to the preceding even integer.
The contents are displayed in hexadecimal
in two forms: the internal format and the Eformat.

Yreg1-reg2

disp1ays the contents of the floating-point
registers regl-reg2. where reg1 must be
less than reg2 and each reg must be an
integer ranging from 0-7. If reg1 and~of
reg2 is an odd integer. each is adjusted tothe preceding even integer..
The contents
are displayed in hexadecimal in two forms:
the internal format and the E format,.
DISPLAY

contents of
where reg is

473

Xreg

displays in hexadecimal the contents of thecontrol register reg, where reg is an
integer ranging from 0-15.
Applies tovirtual 360/61 only.

Xreg-reg2

displays in hexadecimal the contents ofcontrol registers reg1-reg2, where reg1
must be less than reg2, and each reg must
be an integer ranging from -0-15. Applies
to virtual 360/61 only.

PSW

displays as twohexadecimal words thecontents of the program status word (PSW).

Usage:
Before the sp~cified contents of core storage is displayed,alignment is made to the nearest fullword boundary.
The
output is
typed in multiples
of afullword (eighthexadecimal characters) and all information is displayed inhexadecimal.
When DISPLAY is issued" the arguments can be combined in any
order desired, separated by one or more blanks, and up to
one input line in length. If neither G, Y, X, nor L precedes
the -specified number" - L is assumed. If an invalid argumentis specified, a m'~ssage is typed out and the console
function terminates. If any valid arguments were specified
before the invalid one, they are executed properly.
Notes:
a. The contents of core, the registers:. and the PSW are notaltered by issuing DISPLAY.
b.

No imbedded blanks are permitted within an argument .•c. Xreg or Xreg1-reg2 is an invalid argument if the virtual
machine is not a System 360/Model 61.
Responses:
The specified information is typed out.
BAD ARGUMENT xx
An invalid argument was specified.
If valid arguments were
specified before the first invalid one they were executed"
properly.
Examples:a. display 112402
L 12400 = 9208F11E
The core storage location 12403 is adjusted to the nearest
fullword boundaryt' 12400"
and one fullword is displayed in
414

DISPLAYhexadecimal.
h. display 12000-12010
L 12000 = 05C050EO C7EE5830 CBB65833 00385030 CBOE1821
The contentsof hexadecimal
location 12000-12010
isdisplayed in hexadecimal in multiples of fullwords.
d~splay 91
G
1 = 00011C98
The contents of general-purpose register 1 ishexadecimal.

c.

displayed ind. d 91-5
G
1 = 00011eg8 00008990 00008B40 00000082 00000400
The contents of qenreal-purpose registers 1-5 are displayedin hexadecimal.
e. d xO
X
0=00016C80
The contents fo control
hexadecimal.

registeroaredisplayedinX
4 FFOOOOOO 00000000 F08000FF
The contents fo control registers 4-6 arehexadecimal.

displayedinf. d x4-6

g. d x2
BAD ARGUMENT 01
The virtual machine iscontrol registers.

not a 360/67,

therefore it

has noh. d y2Y
2 = 0004560000000000.14627299646232350 E-78
The contents of floating-point register 2 are displayed inhexadecimal in two forms: the internal format and the Eformat.

i. d y1-6
Y
0 = 1230000000000000.76468411134357709 E-56
Y
2 = 0004560000000000.14627299646232350 E-78
Y
4 = 000000AB11100000.88057543452313567 E-82
Y
6 = 0099999999990000.51817011330519540 E-71
The contents of floating-point registers 0, 2, 3, 6 aredisplayed in hexadecimal in two forms: the internal format
and E format, after the specified register 1 is adjusted tothe preceding even integer o.

j. d psw
PSW= 00000000 80001374 The contents of thestatus word (PSW) are displayed in hexadecimal.

programk. d g1-4 140-50 y4 psw x2-4
G
1 = 00011C98 00008990 00008B40 00000082
L
40 = 00011CeO OCOOOOOO 00011CBO FFFFFFFF 7FFFDCCE
Y
4 = 0000000000000000.00000000000000000 E 00
DISPLAY

475

PSW= 00000000 80001374
X
2 = 0003AC28 00000000 FFOOOOOO
The contents of general-purpose registers 1-4, hexadecimal
locations 40-50, floating-point register 4, the program
status word, and control registers 2-4 are all displayed inhexadecimal with one console function.

476

DISPLAYDUMP

Purpose:DUMP prints in hexadecimal on the virtual printer thecontents
of corestorage. general-purpose
registers.
floating-point registers, and/or the program status word.
For virtual 360/61 only, DUMP also prints the contents ofthe control registers.
Format:DUMP
DU

I <hexloc> <hexloc1-hexloc2> <Lhexloc>

I
I
I
1
1

1 <Lhexlocl-hexloc2> <Greg> <Greg1-reg2>, <Yreg> <Yreg1-reg2>
I <Xreg> <Xreg1-reg2>

I <psw>
hexlocis interpreted the same as Lhexloc.

hexloc1-hexloc2 is interpreted the same as Lhexloc1-hexloc2.
Lhexloc

dumps in hexadecimal the contents ofhexadecimal location hexloc.

Greg

dumps in hexadecimal the contents of thegeneral-purpose register reg, where reg isan integer ranging from 0-15.

Greg1-reg2

dumps in hexadecimal the contents of thegeneral-purpose registers reg1-reg2" wherereg1 must be less than reg2, and e:.lch reg
must be an integer ranging from 0-15.

Yreg

dumps the contents of the floating-point
register reg. where reg is an integer
ranging from 0-7. If reg is odd. it isadjusted to the preceding even integer.
~he contents
are dumped in hexadecimal in
two forms: the internal format and the Eformat.

Yreg1-reg2

dumps the contents of the floating-point
registers regl-reg2. where reg1 roust be
less than reg2" and each reg must be an
integer ranging from 0-7. If reg1 and/or
reg2 is an odd integer. each is adjusted tothe preceding even integer. The contents
are dumped in hexadecimal in two forms:
the internal format and the E format.

Xreg

dumps in hexadecimal the contents of thecontrol register reg. where reg is an
integer ranging frolTl 0-15.
Applies to
DUMP

the

477

virtual 61 only.
Xregl-reg2

dumps in hexadecimal the contents of thecontrol registers reg1-reg2, where reg1
must be less than reg2, and each reg must
be an integer ranging from 0-15. Applies tovirtual 61 only.
'dumps as two hexadecimal words the contentsof the program status word (PSW).

PSW

Usage:
Before the specified contents of core storage is dumped,alignment is made to the nearest fullword boundary.
The
output is printed in multiples
of a fullword (eighthexadecimal characters) and all information is dumped inhexadecimal.
prints the specified
information on the virtual
printer,. In order for cp to close the virtual printer (torelease the spooling area) and print the dumped informationon the real printer, the console function CLOSE OOE must be
issued.
CLOSE need only be issued once for the printerafter all the variations of DUM.P have been given.
DUMP

When DUMP is issued, the arguments can be combined in any
order desired"separated by' one or more blanks, and up to
one input line in length. If an invalid argument is
specified!. a message is typed out and the console function
terminates,. If any valid arguments were specified before
the invalid one. they are executed properly.
Notes:
a. The contents of core storage" the registers, and the PSW
are not altered by issuing any form of DUMP.
b.

No imbedded blanks are permitted within an argument.;.

c. Xreg or Xregl-reg2 is an invalid argument if the virtual
machine is not allowed to run in Model 61 mode.
Responses:
After the completion of valid
keyboard is unlocked.

DUMP

consolefunctions"the

BAD ARGUMENT xx
An invalid argument was specified.
If valid arguments were
specified before the invalid
one
they were executed
properly.
l,

418

DUMP

Examples:a.

dump g1-15
dump yO-6
dUlllp 0-80
dump psw
close OOe
General-purpose registers 1-15.
floating-point registers O.
2, 4,. and 6, core storage locations 0-80, and the program
status word are dumped on the virtual printer. To close thevirtual printer and print on 'the real device,·close OOe·
was issued. The dump output is shown in Figure 42 .•h.

dump xO-1S
BAD ARGUMENT 01

The virtual machine is not a System 360/Model 61; therefore
it has no control registers •....................................................................................................................................

•••••••••• * •••••••• ****.* .................~~~........**i......i** ••• •••••••••••••••••••••••••••••••••••••••••••••• ** ••••••••• •••••••••••••••••••••••••• ** •••••••••••••••••••••••••••••••••••••••••••••••• 11 • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •.. ••••• •••••••••••••••••• •••• ••• ••••••••••• ................. • ** .......................................................................
...... •••••••••• ••• ••••••••••••••••••••• ••• •••••• ** ••• * ............................................* .................................
CP610SERID

BOYD

21.04.42o = 00000000

00000000lluOOOOOO
CJD6n5F1
0000C1'18
o ceooo 1e
CCOOOOOO
00000218
II 000(142
OOOOOOOc
000001190
COOOC658
1l000C65E
40002114
8 = 000001114
000001100.00000000000000000 E 00
C = 0000000000000000
2 = 0000000000000000.OOOCOOOOOOOOOOOOO E 00
.000ilOJOOOOOOOOOOO E 00
4 = OOOOOCOOOOOOOOOOY.OOOOOOOOCOOOOOOOC E 00
I> = 0000000000000000
Y
60000050
020JFB1000001380nOOOGec
80031'296
C = 0000C658
OOOOCEE 0000032F8
boeODoe2(OOoeooo
00000000
FF040009
00002231<
400096Dl
00000005
20 = 000400Cl
00000000
COOOED1 C
00000000
00000000OOOOBooO
ocoooooo
000001FS'Ie = 00000208()()~OB800
00000000
00040CCC
000C051 C
00002288
00040000
0000llC2C
6C = 00·040001l
00008BOO
00000000
00008C2C
00040000
00000510
00002288
00040000
8e = OOOCOOOO
PSli= FFO 60000 0000223E

G
G
Y
Y

Figure 42.

* .•F •••••••• 8- •• £ •••••• :1: ••••••• 2e.

•.... • 0 ••••• - . . . . . . . . . . . . . . . . . . . . .

* ........... 8 •••••••••••••••••••• ** .••..•. H •••••••••••••••••••••••••••••• ••••••••• ••• ~DLE•• 0 ••••••

Output £rom DUMP console function

DUMP

419

EXTERNAL
Purpose:
EXTERNAL simulates an external interrupt on themachine and returns control to that machine.

virtualFormat:
EXTERNAL
E

Usage:
On a real machine. an external interrupt is a means by which
the central processing unit responds to signals from theinterrupt key on the computer console.
EXTERNAL simulates
this external interrupti, which is then reflected to thevirtual machine. and control is returned to that machine.
If the user had previously IPL'ed CMS, the Debug environmentof eMS is entered from the Control Program,.
Responses:
DEBUG ENTERED, EXTERNAL INT.
eMS was previously IPL'ed,.
When the external
occurred. the Debug environment was entered.

lISO

EXTERNAL

interrupt

IPL
Purpose:IPL causes the Control Program to simulate an Initial
Program Load (IPL) sequence on a specified device .• Core iszeroed before the IPL, and all pages of the virtual machine
are freed.
Format:
IPL
I

CMS

CMS
devaddspecifies that a saved copy of the Cambridge Monitor
System is to be brought into core.

devadd specifies the address of the device to be IPL'ed.
Usage:IPL simulates the IPL button on the computer console byzeroing core on the virtual machine and causing a record to
be read from the specified I/O device and executed.
During the login procedure of CP when the message
READY AT xx.xx.xx ON xx/xx/xx

is typed out, where xx.xx.xx is the time of day and xx/xx/xx
is the date, CP is ready to accept any console function. By
iSsuing IPL CMS or IPL 190 r,
the Cambridge Monitor System(eMS> is loaded, and the CMS command environment is entered.
The IPL 190 console function loads in a copy of the nucleus
which resides on disk 190. Periodically, a copy of thisnucleus is saved by a CP utility called SAVESYS. This saves
the nucleus at a point at the end of the IPL sequence,
thereby allowing shared pages of the nucleus and faster
response time. The IPL CMS console function loads in thissaved copy of the CMS nucleus.
This means that if thenucleus on 190 has been modified s'ince the last copy was
saved, the versions referenced by IPL 190 and IPL CMS are
different.
Responses:
BAD ARGUMENT xx
An invalid device address was specified.
ERROR DURING IPL SIO
CP is unable to· load from the specified device.
If the card
reader had been specified, check to see that cards had beenread into the virtual card reader by the computer operator.

IPL

481

UNABLE TO IPL SPECIFIED UNIT TYPE
The specified unit could not be IPLeed. Check to see if thespecified-device address is included in the virtual machine
configuration.
Any other responses are those of the new environment that isbeing loaded.

482

IPL

IPLSAVE
Purpose:Same as IPL except the existing core is not cleared.
the console function IPL for further information.

See

Format:I IPLSAVE

Iccut

Usage:IPLSAVE is used to perform an Initial Program Load sequence
without clearing core. For example. it would be used tobring a program such as a stand-alone dump into high core
without disturbing the current contents of core.
Note:
For examples on IPLSAVE. see IPL.

IPLSAVE

483

LINK
Purpose:LINK attaches the specified device to the requestor's
virtual reachine. based on information contained in the CP-67
User Directory.
Format:I
I LINK luserid xxx yyy <W.!!> «NOPASS»
PASS=
password
I
I
I*
useridThe name of the user ·owning· the device xxx.
* denotes that you are linking to yourself,.

An

xxx

·owner's·The
hexadecimal

address

in

yyy

~he

assigned intheW

Write access mode is requested.

R

Read access mode
default value.

(NOPASS>

Used only if
the desired
device).

PASS=

virtualhexadecimal address torequestor·s virtual machine

devicebe

only is requested.

This

is theno special password is required foraccess mode (that is,a"public"

password this form can only be use when LINK is(that is.
executed by a virtual console function
from CMS>. The password is not print suppressed.

usage:LINK allows attachment of directory-defined virtual disks to
the requestor·s
virtual machine. The device
must bedescribed in the CP-67 User Directory under the name anddevice address (userid.xxx) specified.
If the userid is that of the requestor, no password isrequired. and rules governing access are the same as prevail
at LOGIN tirre. If you are linking to yourself, the default
access is read-write: if you are linking to another user,
the default access is read-only.
If the LINK is to some other userid. a password
desired access must be provided (see Responses).

for theIn general. any number of users can link simultaneously to a
device in read-only l11ode.. Only one user can have access to a
device if the first link has write access. If a read-only

484

LINK

link exists. and a write request is issued, the link is madein read-only mode.
Note:
If a user links to another disk as ccu and he already has adisk ccu, he must either reIPL CMS to read in the new file
directory. or issue LOGIN ccu.
Otherwise. the old file
directory exists in core and the new disk is clobbered.
Responses:
ENTER PASSWORD:
Type the required password. By convention. devices specified
as public have the password ALL.
A null line defaults to
ALL.
BAD ARGUMENT
Missing or invalid arguments. Error code is 08.
SET TO READ ONLY
The user has requested andError code is 00.

been granted

read-only access.

SET TO WRITE
The user has requested and been granted
Error code is OQ,.

read-write access.

FORCED READ ONLY
The user has requested write access but because read-only
links exist, read-only access is forced. Error code is 36.
NONEXISTENT UNIT
Device xxx not found inis 12.

the specified directory. Error code

ALREADY ATTACHED
Requestor already has a device yyy. Error code is 16.
BAD PASSWORD
The supplied password is not valid. or
sharable. Error code is 20.

the device

USER LOGGING IN
userid is in process of logging in. Try
code is 24.

again later,. Error

is notDEVICE IN USE
A write link exists. LINK denied. Error code is 28.
UNIT NOT READY
The required physical volume is not mounted.
operator. Error code is 32.
UNIT NOT DASDI
Device xxx must be a DASDI

Notify system

device for LINK. Error
LINK

code is485

44.
USER NOT ON SYSTEM
userid is not in the directory. Error code is 40.
UPDATING DIRECT
The system DIRECTORY is being modified: attempt a LINK again
when the DIRECTORY is completed. Error code is 48.

Example:CP LINK USERA 195 196 R PASS= READPASSThe user links to USERA·s 195 .disk as his own 196 in aread-only mode. The password is given on the same line, so
it is not print suppressed.

486

LINK

LOGOUT
Purpose:LOGOUT removes the user from the system by releasing thevirtual machine and any attached devices, clearing the
temporary disk area, and closing the spooling areas.
Format:LOGOUT
LOG
anything<anything>II

If any nonblank character string is specified withLOGOUT, the telephone line is not hung up and theterroinal reroains connected to CP for another user
to login or dial in.

Usage:LOGOUT logs the user off the system. The temporary disk
area is cleared and all spooling areas are closed. If thereis output in the spooling areas, it is printed or punched ona real device when that device becomes available, as in
CLOSE.
Because of
the finality ofabbreviation accepted is LOG.

thiscommand,

the

only

If -anything- is specified, a LOGOUT occurs in the normalmanner but the communication line is not disabled.
Upon
completion of the LOGOUT procedure, the ·CP-61 online·
message indicates that another login or dial can proceed.
Responses:
LOGOUT AT xx.xx.xx ON xx/xx/xx
The user is removed from the system. The xx.xx.xx
time of day and the xx/xx/xx is the date.

is theCP-67 ONLINE xxxxxxxxxxxx
xxxxxxxxxxxx CP-61 ONLINE
CP-61 ONLINE
If one of the above roessages is typed out after the LOGOUT
message. a nonblank character string was specified withLOGOUT; therefore the terminal remains connected to CP for
another user.

LOGOUT

487

MSG
Purpose:MSG sends a specified message to a specific user.
Format:

I
1

MSG
M

useridCPline

useridCPline 1

I

specifies to whom the message should be sent.
specifies that the message is sent to the systems
operator whatever his useri1 might be.
For thisreason no user should have the id of CP; CPxxxxxx
is acceptable though.
is the message to be sent to the specified user.

Usage:MSG allows the users to communicate with the CP operator in
the computer room as well as with other users.
The
specified user must be logged on the system before a message
can be sent to hiro.
If a specified user is not logged on~
the message USER NOT ON SYSTEM is typed out but is not held
until he logs on.
Amessage that is sent by MSG is in this format
FROM userid: line

The message is typed out at the specified user's terminal
when the terminal is not ready for input.
If the terminal
is waiting for input. the message is held until a carriage
return occurs.
Responses:
userid NOT RECEIVING
The user has suppressed
Console Function SET).

his

receiving of

messages(see

USER NOT ON SYSTEM
The specified user was not logged on the system soroessage was not sent to him. The message is not saved.

theExample:msg CP please attach a tape drive to 181
The message ftplease attach a tape drive to 181 ft is typed out
at the system operator·s terminal.

488

MSG

PURGE

Purpose:PURGE allows the user to delete all spooled files still inthe spooling area from his vi~tual printer or punch. or todelete all his spooled input for his virtual card readers
without reading the data.

Format:1

READER
R
PRINTER

,

PUNCH
PO

I

PURGE
P

I
I
I

1

I
I
I

,

P

I

Usage:
If the user determines that he does not require either his
spooled print output or his punch output, or if he wishes topurge all his input reader files, the PURGE command can beissued.
Responses:
BAD ARGUMENT xx
An invalid device type was specified.

xx FILES PURGED
This is the nOrIl}al response" where xx is the number of files
actually purged or the word NO. if there were none to purge.
Examples:a.

purge pun
NO FILES PURGED
There were no punch files
user.

awaiting spooled output

for theh.

purge r
02 FILE PURGED
The two spooled input files for the user have been deleted.

PURGE

489

QUERY
Purpose:QUERY types out the number of users logged on or dialing,
the identification and terminal address of the users logged
on, the terminal address of a specific logged on user (or amessage that he is not logged on), the' log messages set by
the CP operator, the number of spooled input and output
files currently held by CP for the user, or the amount ofconnect, virtual CPU, ~nd total CPU time used since login.
Format:

QUERY
Q

FILE

(F)

LOGMSG

(L)

t
1
I
I
I
I

FILES
LOGMSG
NAfIlES

1
I
I
I
I
I

USER

use rid
TD1E

types the number of spooled input and output
files currently held by CP for the user,.
types out theoperator ..

message of the day

set by the

NAMES (N)types out the userid
all users on CP.

USER

types out the number of virtual machineusers I, and the number of users attached tovirtualmachines using
the CP-67
DIAL
facility ..

(U)and terminal addre~s ofuse rid

types out the userid and the terminal address
where the user is logged in;, or gi ves USERNOT ON SYSTEM.

TIME

types out the CONNECT,VIRTCPU, and TOTCPU
time used so far in this terminal session forthis user ..

Usage:QUERY is used to determine the number of users logged on or
dialing r, who they are" and what thei~ terminal address is,'what the log message, is l, the number of current spooled f,iles
for this user, and the amount of time (connect and CPU) thathas elapsed for this user since login.. This informatiol')gives an idea of the system load. as well as any pertinent
information about the system. The log message is normallythe message that types out once the user has logged on under
CP.
490

QUERY

Responses:
BAD ARGUMENT xx
An invalid argument was specified.
nnUSERS; rom DIALED
If the USER argument was specified., this message indicatesthat nn virtual machines are logged in and that mm users
have dialed other virtual machines.
userid - xxx, userid - xxx •If the NAMES argument was
displayed four to a line,.

specified, current

userid - xxx
This.is the response to wQ
on.

userid·"USER NOT ON SYSTEM
This is the response tologged on to CP-61.

wQ

userid w ,

users

are

if that user is logged

if that user

is notFILES: xx RDR. xx PRT., xx PUN
The number of spooled files for this user is printed.
xxxxx • '. ,. xxxxx
This is the log message obtained as a
the LOGMSG argument.

result of specifying

Examples:a.

query user

04 USERS; 06 DIALED
Four users are logged on the system. Six
other virtual machines.
h.

users have DIALED

q names
OPERATOR -009, APL - 023, CJOHNSON - 024
A list of current users logged on the system is typed out on
the terminal.

q logmsg
TS DOWN AT 12 SHARP
The log roessage TS DOWN AT 12 SHARP, set by the operator, istyped out.
c.

d.

q files

FILES: 01 RDR, 06 PRT, NO PUN
The number of separate spooled files for the user is shown-.
It is a total for all virtual card reader, printers or
punches.

QUERY

491

e.

q temp21
TEMP21 - 032

q temp 4
OSER NOT ON SYSTEM

11'92'QUERY

READY
Purpose:READY simulates aaddress.

deviceend

for thespecifiedvirtualFormat:READY
devadddevaddspecifies a virtual device address. such as 191.

Usage:
On a real machine a device end is caused by the completionof an I/O operation ata device or, on some devices,. bymanually changing the device from the not-ready to readystate. A device end normally indicates that the I/O device
has become available for another operation. READY simulates
this device end without having to complete an I/O operation
or without making a device not-ready.
Responses:
BAD ARGUMENT xx
An invalid device address was specified.
NONEXISTENT UNIT
The specified unit does
configuration.

not exist

in thevirtual machine

Example:READY 191
A device end is simulated for
191.

READY

the device whose

address is493

RESET
Purpose:RESET simulates thepanel.

system reset key on

the system ,control

Format:

1

1

RESET
RE

Usage:RESET places the virtual machine in a stopped state andresets all pending I/O interrupts. All error conditions arereset. The system is automatically reset by IPL.
Responses:
None.

494

RESET

SET
Purpose:SET allows the user to save the card file in his virtualcard reader, to control the messages and warnings typed at
his terminal and to control his running status.
Format:CARDSAVE ONCARDSAVE OFF
MSG

OFF
ON

SET

RUN ONOFFWNG ONOFFCARDSAVE ON saves the card file in the virtual card reader
so that it can be reread.
CARDSAVE OFF erases the card file in the virtua'l card reader
once the reader has been closed.
MSG

OFF

MSG

ON

specifies that no messages are to be typed
terminal.
specifies that all message are to be typed
terminal.

at theat theRUN ON allows the user to activate the ATTN button causing aread ofa CP console
function without
stopping his virtual machine.
When the CP
function is typed in, it is immediately
executed and the virtual machine resumes
execution.
RUN OFFplaces the user in the normal CP environment
such that when ATTN is hit, the virtual
machine stops.
WNG ON

specifies that all warnings are to be typed at theterminal.
WNG OFF specifies that no warnings or messages are to be
typed at the terminal.
Usage,:SET CARDSAVE ON does not erase the cards in the virtual card
reader once the reader has been closed. Therefore, the SETCARDSAVEON allows the same virtual card input to be read
repeatedly from the beginning of the file. The operation iseffective for all the user·s virtual card readers.
SET

495

SET CARDSAVE OFF is the normal mode of operation for thecard reader. Once a virtual input file has been closed, it
is lost.
To reread the file, it must be physically read
into CP-67 again by the operator or via XFER.
The normal mode of operation for messages and warnings typed
at the terminal is MSG ON and WNG ON, respectively.. Any
messages directed to a user or broadcast by the operator are
typed at the terminal whenever the terminal is not ready for
input.
A
warning s.ent
by theCP operator
printsimmediately, regardlessof what is occurringat theterminal. If MSG OFF is specified. only warnings from theoperator type at the terminal. and any messages sent byanother user or the operator are lost.
If either a MSG OFF or WNG OFF has been specified, and theuser wishes to resume receiving either messages or warnings,
the MSG ON and/or WNG ON command must be issued.
If WNG OFF is specified, no warnings or messages will evertype on the terminal.
If WNG OFF and MSG ON are both set,
only messages will type on the terminal. SET WNG OFF should
be used with discretion.

The normal mode of operation for running is RUN OFF. When
ATTN is hit, the virtual machin·e stops running" and theterminal waits for a CP console function. In a multiaccessvirtual machine,
this isan unacceptable
method ofoperation; there~ore SET RUN ON can be issued to CP to allow
the virtual machine to continue running when ATTN is hit.
When RUN OFF is issued after RUN ON had been previously set,
the virtual machine continues to run until ATTN is hit: ,thiscauses the machine to stop for input. The SET RUN OFF mode
is automatically set if the user gets an -idle- virtual
machine, that is, with the message
CP ENTERED. REQUEST., PLEASE.

Responses:
BAD ARGUMENT xx
An invalid argument was specified.
Examples:a.
SET CARDSAVE ON
The virtual input file
reader is closed.
b•
SET MSG OFF
No messages will type atthe operator.

is saved andnot erased,

the terminal, only

warnings fromc.
SET RUN ON
The virtual machine iF-mediately continues execution.
496

SET

once theIf theuser now activates the ATTN key. a CP readvirtual machine continues to run.

S~

occurs, but his"7

SLEEP
Purpose:SLEEP allows the user to place his terminal in a dormant Cp
mode such that he may receive messages without hitting
carriage return.
Format:SLEEP
Usage:
If the user does not expect to be using the terminal for awhile, the SLEEP console function places the terminal in astate to receive messages. The user's virtual machine is
not run, but he is still accounted for connect time. The
terminal can be -awakened- by activating the ATTN key which
returns the user to CP for more input.
Responses:
None.
Examples:sleep
The terminal is placed in a dormant state to receive
messages. ·Warnings- set by the operator are not affected.
If the user has done a SET MSGOFF he does not, of course,
receive messages, only warnings, if they are issued.

498

SLEEP

SPOOL
Purpose:The SPOOL console function allows the user to direct his
spooled output to a specific unit record device at thecomputing facility and to control the nature of reading
spooled input files.
Format:xxx<ON yyy>
<OFF>

SPOOL
SP

ccc

<CONT><OFF>

xxx is the virtual device address from which output is to be
directed to the specific real device" yyy.
yyy is the real device address of the desired output unit.
It can only be a printer or punch address.
ccc is the virtual device address of the card reader that is
to have continuous spooled input.
Usage:
When printing or punching files from virtual devices, theoutput is written to disk or ·spooled""
until the physicaldevice is available for use. If there are multiple printersor punches, the first available device is used for the
output. To control the spooled output direction, SPOOL canbe issued specifying the virtual device address and the real
device to which the output should go.. The virtual and real
device types must be the same; in other words the virtual
punch cannot be directed to the real printer.
To discontinue the directed spooling and return to normal
spooling, issue SPOOL, specifying the virtual device address
and OFF.
SPOOL
also
controls
thevirtualcardreadingcharacteristics.
When multiple physical card decks havebeen spooled onto dis_k by CP, a user must close each file
before the next file can be read. For continuous virtualcard reader input such that the card reader does not have to
be closed between each file, the SPOOL command can be issued
specifying the virtual card reader address and CONT,. The
virtual machine receives an end-of-file indication only
after the last card of the last spooled input file has beenread.
To terminate thecontinuous reading of files,
SPOOL

issue SPOOL,
499

specifying the virtual card reader address and OFF.
Notes:
a.
continuous reading of input files should not be ineffect with SET CARDSAVE ON, as an unending ·wrap-around·
input file will exist.
h.
Directed output is useful--andnecessary if, forinstance, an installation has two printers. one with a PN
train and another with a TN train. If the user has script
output to produce,. he may specify the desired output
printer, perform his printing, and then return his printerto normal spooling.
Reponses:BAD ARGUMENT xx
This indicates that an error in specification has been made,such as invalid virtual address, invalid real address:. orconflicting device types.
Examples:a.

spool e on 30
be9in
CMS

script report (offline center)
RiT=05.21/06.03 12.22.13<-----ATTN key hit
cp<-----confirmation of environment
sp e off
The SPOOL console function is issued to CP to direct thevirtual printer OOE output to the real printer 030. BEGIN
returns control to CMS, where REPORT SCRIPT is formatted
offline. ATTN is hit to go to CP,. and the directed output
of printer OOE is terminated. Normal spooling now occurs on

OOE.
h.

spool c cant
begin
CMS

offline read * *OFFLINE READ A FORTRANOFFLINE READ B FORTRANOFFLINE READ CALC FORTRAN
RiT=02.01/02.78 12.34.56<-----ATTN key hit
cp
query files
FILE: - NO RDR, 00 PRT, NO PCB
spool c off
The SPOOL command is issued to read multiple spooled input
files as if they were continuous. Control is transferred toeMS by BEGIN. and the spooled input files are read.. ATTN is
hit to return to CP and the spooled files are queried.
500

SPOOL

Input spooling is then returned
reading.

to normal for noncontinuous

SPOOL

501

STORE
Purpose:STORE replaces the contents of specified locations in corestorage,general-purpose
registers,
floating-point
registers, and the program status word, and for virtual
360/61, in control registers 0~2,4,and 6.
Format·:

STORE
ST

Lhexloc<Lhexloc hexinfol ••• hexinfoN><Greg hexinfol ••• hexinfoN><Yreg hexinfol,••• hexinfoN><Xreg hexinfol. '•• hexinfoN><PSW<hexinfol> hexinfo2>

hexinfol ••• hexinfoN stores the hexadecimal values
hexinfol....
hexinfoNinsuccessive fullword locations
starting
athexadecimal
location hexloc.

Greg

hexinfol ••• hexinfN

stores thehexadecimal values
hexinfol...
hexinfoNinsuccessive
general-purpose
registers. startingat theregister specified
by r~g.
The parameter reg must be an
integer ranging from 0-15, andsuccessive
valuesofregcannot exceed 15.

Yreg

hexinfol ••• hexinfoN

storesthe hexadecimal values
hexinfol...
hexinfoNinsucessive
floating-point
registers, startingat the'register specified
by reg.
The parameter reg must be an
integer between 0 and 6, andsuccessive
valuesofregcannot exceed 6. If reg is an
odd integer, it is adjusted tothe preceding even integer.

Xreg

hexinfol. ,. ,.hexinfoN

storesthe hexadecimal values
hexinfol ••hexinfoNinsuccessive control registers
startingattheregister
specified
by
reg.
The
parameter reg
must bean
integer ranging from 0-15, andsuccessive
valuesofregcannot exceed 15. Only control
,It

502

STORE

registers
0-2-4-6
canbemodified by STORE; all theother control registers aresupposed to have a zero value.
Applies
to virtual
360/61
only.
PSW<hexinfo1>

hexinfo2

storesthe hexadecimal values
hexinfo1 and hexinfo2 in thefirst and second words of the
program status word.
If onlyhexinfo2 is specified, it isstored in the second word of
the PSW.
The interrupt code
is set to zero. The hexinfo1
andhexinfo2 must be separated
by one or more blanks,.

Usage:The smallest group of hexadecimal values that can be stored
is one full word and alignment is made to the nearest
fullword boundary. If the hexadecimal value being stored isless than a fullword (eight hexadecimal characters), it isright-adjusted in that word and filled in with high orderzeros.
The options can be combined in any order wanted, separated
by one or more blanks, up to one full line in length, andissued in a single STORE console function. L. G, or Y mustbe specified or the options are invalid.
If invalid arguments are specified, a message is typed out
and the console function terminates. If there are any valid
arguments before
the invalid one, they
are executed
properly.
Responses:
BAD ARGU~ENT xx
An invalid argument was specified.
If there were any valid
arguments before the invalid
one, they were executed
properly. The console function terminated on the invalid
argument.
ILLEGAL CREG 0
An attempt to load control register
nonzero, the register is not loaded.

0,with bits

26-31

ILLEGAL PSW
An attempt to load the PSW with bits 0-4 nonzero,. when thevirtual machine is a System 360/Model 61 running in extended
PSW mode (bit 8 of control register 6 set to 1).
Thismessage is just a warning: the PSW is modified and a programinterrupt occurs with ·specification exception- on theexecution of the next instruction.
STORE

503

Examples:a.

d 1201112010 = 4110DOIC

L

st 112011 519
d 12011
L
12010= 00000579
A full word at core storage location 12011 is displayed
after alignment is made to the nearest fullword boundary
12010.
The hexadecimal number 519 is right-justified.
filled in with zerOS;f and then stored in a full word.
beginning at location- 12010. That word is displayed again
to reflect the changed value.

b.

d g5-8G

5=00000400

OOOOOOOC

0000049C

00000004

st g5 123 456 aa

d 95-8G 5=00000123
00000456
OOOOOOAA
00000004
The contents of general-purpose registers 5-8 are displayed.
The hexadecimal numbers 123 1f 456, and AA are right-justified
in separate words, filled in with zeros and then stored ingeneral-purpose registers 5, 6, and 7.
The contents ofregisters 5-8 are then displayed- to show their storedcontents.

c.

d psw
PSW

= 00000000

80001374

st psw 55555
d psw
PSW
= 00000000
00055555
The contents of the PSW are displayed. The hexadecimal
number 55555 is right-justified, filled with leading zeros,then stored in the second word of the PSW;, and the interrupt
code is set to zero. The Psw is displayed to reflect thechange.
d.

d psw

PSW

= 00000000

80001314

st psw 111111 12000
d psw
PSW
= 00111111
00012000
The contents of the PSW are displayed. The hexadecimal
numbers 111111 and 12000 are stored right-justified in thefirst and second words of the PSW, and the interrupt code in
the first word is set to zero. The PSW is then displayed toreflect the change.

504

STORE

e.

d xO
X

o = 00016C80

st xO 123456
ILLEGAL CREG 0
d xO
X
0 = 00016C80
The contents of control register o are displayed: an attempt
is made to store a wronq value in it; the contents of theregister are not modified.

f.

d psw x6
PSW
= 03060000 00000000
X
6 = F08000FF
st psw 12345678 12345618
ILLEGAL PSW

d psw
PSW
= 12345618 12345618
The contents of the PSW
and control register 6 aredisplayed, the hexadecimal numbers 12345618 12345618 arestored in the PSW. and since the virtual machine is inextended mode. the warning ILLEGAL PSW is issued.

g.

st psw 3060000 0
st x6 fOOOOOff

d psw x6
PSW
= 03060000 00000000
X
6 = FOOOOOFF
st psw 12345618 12345618
d psw
PSW
= 12340000 12345618
Now the virtual machine is not in extended mode, therefore,
the psw is modified without warning.

h.

d xO

BAD ARGUMENT 01
The virtual machine is not a System 360/Model 61.

STORE

505

XFER
Purpose:XFER controls the passing of files between users.
Format:I
I
1 XFERI
X

TO userid*

devaddOFF

devadd specifies the address of the device from which all
succeeding output is to be either transferred or
normally written out.
Avirtual punch or
printer output may be XFER'ed.
To

useridTO *turns on the transfer mode.
Userid is theeight-character user identification of the userthat is to receive the transferred file.

specifies that the recipient ofuser issuing the command.

OFF terminates the transferring
userid.

of allthe transfer

is thefurther output

toUsage:XFER controls the passing of files between users. When thetransfer mode is turned on by specifying TO userid, any
succeeding output written to devadd is placed in the card
reader of userid. For userid to receive the transferredfiles on his disk, userid must read them onto his files.
that is, by issuing commands 'such as OFFLINE READ filename
filetype" OFFLINE READ *. or DISK LOAD.
To turn the transfer mode off, the option OFF must be
specified. Any succeeding output to the devadd is written
onto disk as in normal spooling, and put on the real device
when that device is free.
A second XFER command issued
turns off the XFER to theuserid is invalid.

to change userid automaticallyprevious userid, even if the

If the user XFER'ed to is currently logged onreceives the following message:** CARDS XFERED BY userid **where userid is the transferring user.
The user XFER'ing the file receives the message:** CARDS XFER'D TO userid **
506

XFER

to CP-61, hewhere userid is the receiving user.
Notes:
A user may do an XFER to himself to allow him to read a card
file he created. (using OFFLINE PUNCH or DISK DUMP) without
requiring opeD~tor intervention and with a considerable
saving in card handling.
Responses:
BAD ARGUMENT xx
An invalid argument was specified.
NONEXISTENT UNIT
The specified device does not exist and is invalid.
DEVICE BUSY
Spooled output is in operation forshould be issued to clear the status.

thepunch.

A

close

UPDATING DIREc-r
The system DIRECTORY is being modified: attempt the XFER
after the DIRECTORY is created. The XFER command has notbeen accepted.
Examples:a.
xfer d to userl
The transfer mode is turned on. Any succeeding
device OOD is placed in the card reader of USERI.

output tob.
xfer doff
The transfer mode is turned off. Any succeeding output tovirtual OOD is written on the real device.
xfer d to userA4USERALJ NOT IN DIRECTORYUSERA4 does not exist; therefore cards are not transferred
to him. Any active transfer mode is turned off.

c.

d.

CP

<-----environment confirmationx d to user20
begin
CMS
disk dump document script
R;T=02,.19** CARDS XFEReD BY USER4 **offline read prog2 datain
Output device OOD is transferred to USER20. Control isreturned to eMS by issuing BEGIN to CP, and the file
DOCUMENT SCRIPT is transferred to the card reader of USER20
in disk dump format. Meanwhi1e, cards were XFER'ed to thisuser by USER4, and he reads them onto his disk.

XFER

507

CONSOLE FUNCTION APPLICATIONS':.- _,Console functions give the facilities of a computer console
r:.c.t:o each
virtual machine,.
and theyshould beused~accordin9Iy.
It is through these functions that a virtual
machineis loaded.
displayed,.
dumped. altered,.
andcontrolled by the user.
Consolefunctions havevarious uses.
Some oftheapplication areas are described below. such as debugging.
initializing CMS. and attaching/detaching additional I/O
devices.
Debugging. Console functions are very useful for debugging
purposes. The CP environment can be entered at any time andthe, contents of core storage,. the registers. and the PSW,j displayed.
dumped. or alterel.. Execution can be started
again by issuing BEGIN. withor without a specified
hexadecimal location.
If the CP environment has been entered from CMS and the user
desires to enter the Debug environment of CMS. he can issue
EXTERNAL,.
The EXTERNAL console
function generates anexternal
interrupt andcauses DEBUG
to beenteredimmediately.
Initializing eMS. If at any time the user destroys his copyof CMS. a new copy can be loaded 'again by issuing IPL'CMS or
IPL 190.
All pending interrupts are reset and CMS isstarted anew.
If I/O errors occur on the disk when logging in to eMS. thefile directory from the permanent disk has probably beenread into core incorrectly. 00 NOT LOG OUT. Enter CP byhitting ATTN once and issue IPL C~S or IPL 190 to initialize
CMS.
'Attaching/Detaching Additional I/O Devices. If an I/O device
such as a tape drive, is needed that does not belong to thevirtual machine configuration. the user must communicate
with the CP operator that he wants a.device attached with a
specified address. such as 181. As soon as the device is
attached by the operator. the message DEV devadd READY istyped out at the terminal. The specified device address can
now be used.
The user can continue using the terminal while he is waiting
for a device to be attached r• as long as he does not addressthat device.
Once the device
is attachedand theappropriate message is typed out. the specified device isdedicated to the one user.
There is no tape-label checking performed by CP.
to the operator to mount the correct tape.
The responsibility is508

left to the user toConsole Function Applications

It is updetach or remove

the specified device from his configuration. As long as thedevice is attached to him. it is unavailable for use by anyother user. By issuing DETACH devadd,. the device is removed
from the virtual machine configuration and the message
DEV devadd DETACHED
is typed out at the terminal. A message is automatically
typed out to the operator specifying the device that is
free. If the detached device address is that of a tapedrive. the tape is rewound and unloaded.
Transferring Files. Any files up to 132 characters inlength. -fixed or variable, can be transferred between users
by issuing the XFER console function. output written to the
XFER'ed device is placed in the card reader of the specified
user. CMS commands i• such as OFFLINE PUNCH for card-image
records, OFFLINE PRINT for printer files, and DISK DUMP for
variable-length records. can be used to write output to the
XFERted device.
Controlling Spooled Input/Output. Spooled input and output
remain on the disk until the user reads or closes the input_
filet. or until the physical device is available for output.
To r'~move all spooling areas for a particular device. issue
the PURGE console function. To determine how. many spooled
files currently exist. issue--QUERY FILE. To direct spooled
output to a particular device
rather than the firstavai'lable one. issue SPOOL..
To concatenate spooled input
files so that many physical decks can be read continuously
as if they were one, issue the SPOOL console function.
specifying CONT for the card reader.

Console Function Applications509

CP-61 MESSAGESThe following CP-61 messages are directed to a user in
response to a machine malfunction or operator intervention.
When the operator attaches a device to a user, the message:
DEV XXX A~ACHED
is typed at the user·s terminal.
If the user has placed the terminal in sleep state themessage istyped immediately, otherwise it
is typedfollowing the next carriage return.
Should the operator detach a device, the message
DEV XXX DETACHED
is similarly typed.
Should a machine check occur and the user's machine isenabled for machine checks, the message*.MACHlNE CHEeR** - CP ENTERED, REQUEST PLEASE
is printed at the user·s terminal and the user's machine isplaced in console function mode. One must reIPL should thisoccur.
If the user's machinemessage:is noten~bled.* MACHINE CHECR *.

is printed at theremains unaltered.

user's terminalforinterrupts, theand theuser's machine

If an error is encountered on a system disk, such as a
T-disk, the message:**SYSTEM IOERROR*. CP ENTERED, REQUEST PLEASE
is typed at the user's .terminal and the user's machine isplaced in console function mode.
The message
CONNECT=xx.xx.xx VIRTCPU=xxx.xx.xx TOTCPU=xxx.xx.xx
is typed at the user's terminal if the operator does an ACNT
CP console function. No change occurs in the user's machine
status except that connect, virtual, and total times arereset to zero.

510

CP Messages

OPERATING CONSIDERATIONSOFFLINE PROCEDURES
To read cards into a user's file. the OFFLINE READ commandis used. The first card in a deck to be read must be thecontrol card
CP61USERID userid
where the user's ID is punched beginning in column 13 (thatis, two spaces between CP61USERID and the user's ID).
Cards are read by the OFFLINE READ command in CMS and a file
is formed ~hich is referred to by its, filename and filetype.
The control card
OFFLINE READ name type mode
specifying the filename and filetype;, should be placed
before each set of cards which is to form a file where"name" is the filename. "type'" is the filetype, and "mode"is the filemode. If the "mode" is not specified, each fileis entere~ into the user's file directory with mode Pl.
When a user wishes to have a deck of cards read in offline,
he should give the deck to the CP operator and request that
his deck be read into CP. If the user was logged in before
the deck was read by CP. the following message is typed at
the console:**CARDS HAVE BEEN READ*.
If the deck was read.by CP before the' user logged in, the-following message is typed at the console, as soon as theuser logs on:
FILES: - xx RDR. xx PRT /• xx PCB
When the deck has been read by CP. the user should issue the
CMS command
OFFLINE READ •to cause eMS to re~d the cards and form the desired files.
If the deck is read by CPt but, the CMS command OFFLINE READ
is not issued, the files are not written onto the user's
disk.

Offline Procedures

511

TAPE PROCEDURES
A facility is available for attaching magnetic tapes to a
virtual machine. The selection of a physical tape drive ismade by the CP operator, and the virtual device address ischosen by the terminal user.
The eMS TAPE command requiresthat the tape have a,ddress 181. The TAPEIO function and the
TPCOPY command associate the device names TAPl and TAP2 withthe device addresses 180 and 181, respectively.
To have a tape attached to your virtual machine, send amessage to the CP operator asking him to mount a tape foryou as a specified device address. When the tape is mounted
and ready for use. the system automatically types themessage
DEVICE xxx ATTACHED
Since there are only a limited number of tape drives
available for use by CMS users# a user should not keep atape attached to his machine any longer than he is using it.
To release a tape from a virtual machine, enter the CP
environment and type the CP console function
DETACH devadd
When a user logs out
automatically detached.

512

of

CP,

all attached

Tape Procedures

devicesareLIBRARY USAGEeMS has two types
libraries.

of libraries--macro

libraries andtext

Macro Libraries.
A macro; library is created by the MACLIB command: it is afile that has a filetype of MACLIB and that contains macrodefinitions and a dictionary. A macro definition is a groupof assembler-language statements identified by a unique name'and used as an expansion of a source statement in· anassembler~languaqe program. The dictionary
generated by the
MACLIB command is made up of macro definition names, indicesor locations of the macro definitions within the library,
and the size in number of card iJllages in each macrodefinition ..
Both the user and the system may have macro libraries.. eMS
provides two macro libraries that reside on the systems
disk: SYSLIB MACLIB and OSMACRO MACLIB.
SYSLIB MACLIB
contains the CMS macros, and OSMACRO MACLIB contains the OS
macros supported under CMS. The user can generate his own
libraries on his permanent disk by issuing the MACLIB
command.
Macro libraries are searched during the ASSEMBLE command for
missing macrodefinitions..
Normally
the only
macro
libraries searched are SYSLIB MACLIB and OSMACRO MACLIB. inthat order. Once macro libraries have been generated by1·theuser. there are two methods by which the userfs MACLIB files
can be searched for missing macro definitions.
The first method is by issuing the GLOBAL 'ASSEMBLER command.
This command names from one to five ~ACLIB files that are to
be searched for missing macro definitions.
If the files
SYSLIB MACLIB and OSMACRO MACLIB are to be searched inaddition to the user·s MACLIB files, SYSLIB and OSMACRO mustbe specified as two of the five libnames in the GLOBALASSEMBLER command.. The MACLIB files are searched in theorder in which they are named. The GLOBAL macro libraries
remain in effect until another GLOBAL ASSEMBLER command isissued" or the CMS nucleus is reinitialized,. or the user
logs out of CP.
The second method is by generating a SYSLIB MACLIB file oran OSMACRO MACLIB fi1e on a disk that precedes the systems.
disk in the standard order of search. The ASSEMBLE. command
normally searches for the file SYSLIB MACLIB and OSMACRO
MACLIB for missing macro definitions.
TO terminate the searching of all MACLIB files, including
SYSLIB MACLIB and OSMACRO MACLIB, the GLOBAL ASSEMBLER
command can be issued with no libnames specified.

Library Usage

513

Text Libraries
A text library" created by the TXTLIE command" is a filethat has a filetype of TXTLIB and that contains a dictionary
and the relocatable object code from TEXT files~
The
dictionary is created by the TXTLIB command and contains
control section names. the entry points. their location, andthe size of each TEXT file inc1uded in the text library.
Both the user and the system may have text libraries. eMS
provides four text libraries which reside on the systems
disk; they are SYSLIB TXTLIB, CMSLIB TXTLIB,PLILIB TXTLIB.
and SSPLIB TXTLIB. SYSLIB TXTLIB contains the standard IBM
OS/360 FORTRAN G library routines: CMSLIB TXTLIB contains
the nonerror message FORTRAN subroutines; PLILIB TXTLIB
contains the standard PL/I library; and SSPLIB TXTLIB
contains the Scientific Subroutine Package. The user can
generate his own text libraries by issuing the TXTLIB
command,.
Text libraries are searched by the LOAD, USE, and REUSE
commands to find missing subroutines, undefined names,. and
TEXT files not found_ Normally the only text library
searched is SY,SLIB TXTLIB.. To search either CMSLIB TXTLIB,
PLILIB TXTLIB. or SSPLIB TXTLIB. the GLOBAL command should.be issued. If text libraries have been generated by theuser. there are three methods by ·which the user's text
libraries can be searched during the·LOAD, USE, and REUSE
commands .•The first method is by issuing the GLOBAL LOADER command.
This command names from one to eight TXTLIB files that are
to be searched for missing subroutines. If the file SYSLIBTXTLIB is to be searched in addition to the user's TXTLIB
files. SYSLIB must be specified as one of the eight libnamesin the GLOBAL LOADER command. The TXT LIB files are searchedin the order in which they are named. If the GLOBAL LOADER
command has been issued and the user wishes to terminate theuse of his TXTLIB files, the GLOBAL LOADER command can beissued specifying SYSLIB. To terminate the searching of all
TXTLIB files. issue GLOBAL without specifying any TXTLIB
files. The GLOBAL text libraries remain in effect until
another GLOBAL LOADER command is issued, the LOAD command isissued with the LIBE or SLIBE option, the CMS nucleus isreinitialized, or the user logs out ofCP.
The second

method is by issuingthe LOAD commandwith the

LIBE option and specifyi'ng the text libraries to be used. If

the file SYSLIB TXTLIB is to be searched along with theuser's text libraries;. SYSLIB must be specified as one of
the libnames.
The LIBE option with the LOAD commandoverrides the effect of the GLOBAL LOADER command for that
LOAD and any following USE or REUSE cOll11l1ands,.
The third method is by generating a SYSLIB TXTLIB file on adisk that precedes the systems disk in the s·tandard order of514

Library Usage

search. LOAD, USE, and REUSE normally search for the file
SYSLIB TXTLIB for missing subroutines or TEXT files notfound. If a user file has the identifier SYSLIB TXTLIB i t
is used in place of the system text library.

Library Usage

515

RECOVERY PROCEDURES
The recovery procedures discussed here deal with error
recovery as well as general recovery from user problems.
The recovery procedures are as follows:
errors during
LOGIN, errors specified by the E(xxxxxl message, recoveringfrom the system going down,. reinitializing CMS, file space
full, and general recovery procedures.
Errors during CMS Login
CMS
LOGIN
is
defined asreading
into
core
the
user-file-directory from the specified disk.
Login isinitiated after the CMS- startup message by: 1) entering anull line, 2) issuing the eMS command LOGIN, 3) invoking any
valid CMS command or function.
Errors that might occur
duringthelbgin
procedureare~a)P-disknotattached--contact CP systems operator; b) file-directory
unreadable--total catastrophe, issue FORMATP ALL: c)i~valid device type--only 2311 or
2314 devices are allowed;d)hardwareI/O
error
attempting
to
read
the
file-directory--real hardware problems.
If I/O errors occur during the CMS LOGIN NO UFD command,issue FORMAT P to reinitialize the p~rmanent disk.
Iferrors occur during FORMAT P, issue FORMAT PALL.
Errors Specified by the E(xxxxx) Message
Any error conditions that occur during a CMS command are
typed out with an E(xxxxx) message when the command is
terminated. The xxxxx is the error code number and it isexplained in that command's description.
If files werepermanently written
out or updated before
the error
condition occurred, the most current files are reflected in
the user-file-directory, when the time (T=xx.xx) is typed
out;. unless otherwise stated by that command's description.
Recovering from the system's Going Down
If the system goes down while using CMS, the files on thetemporary disk are lost. and the files on the permanent disk
are as current as they were when the last Ready message(R;T=xx.xx) or error message (E(xxxxx);T=xx.xx) was typed
out,. with one exception.
If an EXEC command had been
issued. the files used by the CMS commands that had finishedexecution before the system went down are reflected in thecurrent user-file-directory,. even though no time (T=xx.xx)
was specified between the commands. Except in the case of
EXEC. the user-file-directory is always updated on disk
when.!ver the time ('I'=xx.xx) is typed at the terminal.
If a file is being edited or created by EDIT or CEDIT when
the system goes down, it may not be completely lost. Issue
a LISTF, and see if the EDIT or CEDIT work files (INPUT1)
FILE or (INPUT2) FILE exist. If they both exist,. take the516

Recovery Procedures

longer of the two if you are creating or adding to the file,or take the shorter file if you are deleting many -lines, andthen proceed as below: if they both exist and are the samelength. issue a.PRINTF or OFFLINE PRINT for both work files
to see which work file has the latest copy of the file beingedited. and then proceed as below: if only one work file
exists then proceed as below. Note that EDIT only uses one
work file--(INPUT1) FILE.
ALTER the filename and/or filetype of the appropriate work
file.
Then issue EDIT for the ALTER'ed file and beginediting., as this file contains the latest copy of the filethat wap being edited when the system went down.
If no work file exists, all input and changes made since thelast FILE or SAVE request have been lost. To prevent the
updated or new file from being lost;, issue the FILE or SAVE
request frequently.
Reinitializing CMS
If DEBUG is entered CMS can be reinitialized as follows:(1) the CMS IPL command can be issued from the DEBUG
environment or the CMS command environment;. (2) ATTN can behit. and IPL eMS or IPL 190 issued to CP.
(3) RESTART can beissued from the DEBUG environment to reIPL the CMS nucleus,or (4) KX issued in DEBUG"
which updates the user directoryand IPL's the CMS nucleus.. Issuing KX to DEBUG is the only
way among the previous three methods of reinitializing CMS
to permanently update files that have been modified or
created since the last T=xx.xx message.
l,

If CMS does not work as it should., it could be that the copyof CMS in the virtual machine has been destroyed by the user
(no user can get to or alter another user's virtual machineor core storage).
The user should either (1) enter theControl Program by hitting ATTN and issue IPL CMS to reload
CMS" or (2) issue IPL to the CMS command environment.
The command IPL. LOGIN and FORMAT can be - issued at any timein the CMS comm~nd envlroment and not just at the beginning.
1•

File Space Full
If 99~ of the user·s filespace is full. an error message istyped out and the user is logged out of eMS. Issue IPL CMS
to CP and"if at all possible, erase some files. If there_is still not sufficient space available on the disk, dump
all or part of the files onto tape with the eMS commands
TAPE DUMP, and then erase those files on disk. Whenever thefiles on tape are needed, the commands TAPE LOAD (if TAPE
DUMP'created the tape) could read them back onto disk. If
t~e user stillneeds more filespace" he should contact thesystem administrator for more disk space.

Recovery Procedures

517

General Recovery Procedures
If it is not clear which environment has been entered(, hit
carriage return and the response confirms which environmenthas been entered.
To kill execution of a command or program in CMS,. ATTN
should be hit twice and KX entered. To kill a type out ineMS. ATTN should be hit twice and RT entered. To killoverrides in eMS. ATTN should be hit twice and KO entered.
If all of the files on the permanent disk are to be erased.
the command LOGIN NO UFO should be issued instead of ERASE **.

If errors persist in an executing program, use the DEBUG
command or. if the program is written in FORTRAN, use the
FORTRANG
Debugpackage(see
IEM
system/360:
FORTRAN IV Language, C28-6515).
If transmission errors occur. issue the ECHO command, using
each of the options U, S, and X to test the transmission ofdata between the terminal and the computer.

518

Recovery Procedures

CHANGING OBJECT PROGRAMSFiles which contain relocatable object code and have a
filetype of TEXT can be read into core storage and havelinkages resolved by the LOAD, USEI' and REUSE commands.
Five types of cards can be added to a TEXT file. These are
the Set Location counter (SLC), the Include Control Section(ICS), the Replace (REP)" the ENTRY, and the LIBRARY cards.
These are used to set the core location where LOAD begins
placing the file in core, to make corrections and additions
to the relocatable object code in core once the file isloaded, to specify entry points, and to specify referencesthat are not to be resolved.
These cards can be added to
the TEXT file(s) which have been OFFLINE PUNCH'ed and canthen be read back in, or they can be added using the SPLIT
and COMBINE commands or the EDIT command.
The filetype
column 1 andthe file.

REPS automatically places a 12-2-9 punch inbegins placing the user·s data in column 1 ofChanging Object Programs

519

Set Location counter (SLC) Card
The Set Location counter Card "sets the location counter usedwith the loader.
The file loaded in after the SLC card isplaced in core beginning at the address set by this SLC
card. The SLC card has the format shown in Figure 43.
Itsets the location counter in one of three ways:a.
With the absolute address
number in columns 7-12.

specified asa hexadecimalb.
With the symbolic address already defined as a program
name or entry point. This is specified by a symbolic namepunched in columns 17-22.
c.
If both a hexadecimal address and a symbolic name are
specified, the absolute address is converted to binary andadded to the address assigned to the symbolic name; theresulting sum is the address to which the loader's location
counter is set. For example, if OOOOF8 was specified incolumns 7-12 of the SLC card image and GAMMA was specified
in": columns 17-21, where GAMMA has an assigned address of
006100 (hexadecimal), the absolute address in columns 7-12
is added to the address assigned to GAMMA giving a total of
0061F8. Thus, the location counter would be set to 0061F8.
If there are blanks in both columns 7-12 and 17-22, or thesymbolic name has not yet been defined, the response INVALIDCARD xxx •• ,.xxx is typed out--or", depending on whether the
LOAD option SINV or PINV was specified, is written in thefile LOAD MAP. If only the symbolic aduress is to be used,columns 7-12 must be left blank or all zeros.
If only theabsolute address is to be used, columns 11-22 must be left
blank.

520

Changing Object Programs

I COLUMN I

I

CONTENTS~~~~-~~~~-~~-~~---~-~-~~~-~---~~-------------~-~----~-----~---~--

I
I

I

f
I
I
I
I
,

1

2-4

I
"'

I

I
I

5-6

,

7-12

I
I
I

I

I
I
I 13-16
I

1 11-22
I

I
I
I
23
I
I
I 24-72I
1 73-80

I

Load card identification (12-2-9). Identifies
this as a card acceptable to the loader.
SLC

,

1
I
I
I
I
I
I

Identifies the type of load card.

BLANR
HEXADECIMAL ADDRESS to be added to the valueof the symbol, if ~ny. in columns 17-22. Mustbe right-justified in these columns, with unused
leading columns filled in with zeros.

1
I
I,

BLANK

SYMBOLIC NAME whose assigned location is usedby the loader. Must be left-justified in thesecolumns. If blank. the address in the absolute
field is used.
BLANR
May be used for comments or left blank.

1
1

Not used by the loader. The user may leave theseblank or insert program identification for his own
convenience.

Figure 43.

Format of an SLC card

Changing Object Programs

521

Include Control Section (ICS) Card
The ICS card changes the length of a specified control
section or defines a new control section. It should be used
only when REPLACE cards cause a control section to be
increased in length. The format of an ICS card is shown in
Figure 44. An ICS card must be placed at the front of thecard deck or TEXT file.

~~~~~--~-~----~--------------------~-----------------~ -----------I

CONTENTSCOLUMN-----~------~----------------------------------------~-~---~-----

I
I
I
I
I

,
I
1

1

2-4
5-16

17-22

Load card identification (12-2-9). Identifies
this as a card acceptable to the loader.
Identifies the type of load card.

ICS
BLANK

CONTROL SECTION NAME--Ieft-justified in thesecolumns.

23

BLANK

24

• (comma)

25-28

29

HEXADECIMAL LENGTH IN BYTES of the control
section. This must not be less than the actual
length of the previously specified control
section. Must be right-justified in thesecolumns with unused leading columns filled inwith zeros ..

BLANK

30-12

May be used for comments or left blank.

13-80

Not used by the loader. The user may leave theseblank or insert program identification for his
own convenience.

Figure 44..

522

I
I
I
I
I
I
I
I
I

Format of an ICS card

Changing Object Programs

Replace (REP) Card
A REPLACE card allows instructions and constants to bechanged and/or additions made. The REP card must be punchedin hexadecimal code.
The format of a REP card is shown in
Figure 45. The data in columns 11-10 (excluding the commas)
replaces what has already been loaded into core, beginningat the address specified in columns 1-12. REP cards areplaced in the card deck either (1) immediately preceding thelast card (END card) if the text deck does not containrelocatable datasu~hasaddress constants,or (2)
immediately precedi'ng the first RLD (relocatable dictionary)card if there is relocatable data in the text deck.
If
additions made by REP cards increase the length of a control
section, anICS card, which defines the total length of thecontrol section, must be placed at the front of the deck.

I

CONTENTSCOLUMN,,-------------------------------~--------------------------------Load card identification (12-2-9). Identifies
1
I
I

I
I
I
I

t

I
I

this as a card acceptable to the loader,.

I
I
I

Identifies the type of load card.

REP
5-6

BLANK

1-12

HEXADECIMAL STARTING ADDRESS of the area to be
replaced as assigned by the assembler. Must be
right-justified in these columns with unused
leading columns filled in with zeros.

13-14
15-16

t

,

BLANK
ESID --EXTERNAL SYMBOL IDENTIFICATION·- thehexadecimal number assigned to the control
section in which replacement is to be made. The
LISTING file produced by the compiler indicatesthis number.

11-72

BLANK

73-80

Not used by the loader. The user may leave theseblank or insert program identification for his
own convenience.

I

Figure 45.

Format of a REP card

Changing Object Programs

I

I
I
I

1

A maximum of 11 four-digit hexadecimal fields,
separated by commas., each replacing one previously
loaded halfword (two bytes). The last fieldmust not be followed by a comma.

1

I
I

523

Entry Card
ENTRY
statement specifies the first instruction to ,beexecuted. It can be placed before, between, or after object
modules or other control statements. The format of the ENTRY
statement can be seen in Figure 46. The Wexternalname w is
the name of a control section or an entry name in the input
deck. It must be the name of an instruction, not of data.

"'~'r'l'he

ENTRY
Figure 46.

externalname

Format of an ENTRY card

The loader selects the entry point for the loaded program in
the following ways:a.

From the paramter list on the START command.

b.

From the last ENTRY statement in the input.

e c.
~

From the first assembler- or compiler-produced END
statement that specifies an entry
point if no ENTRY
statement is in the input.

d.
From the first byte of the first control section of theloaded program if no ENTRY statement and there is noassembler- or compiler-produced END statement specifying anentry point.
Example:ENTRY GO
GO is defined as the external name of the first
ie'instruction to be executed when the program is loaded.
~where

The address of the instruction, indicated by the symbolic
name GO, is specified by the loader as the starting point of
the program when it is executed.

J):524

Changing Object Progra~sLibrary Card
The LIBRARY statement -can be used to specify the never-call
function.
The
never-callspecifies
those
externalreferences that are not to be resolved by the automatic
library call during any loader step. It is negated when adeck containing the external name referred to is part of the
input-to the loader. The format of the-LIBRARY card can beseen in Figure 41.
The -.- specifies the never-call
function: the -external reference- ~efers to an externalreference that may be unresolved after input processing. It
is not to be resolved. Any additional external references
within the subscript must be preceded by a comma. The
LIBRARY statement can be placed before, between, or after
object decks or other control statements.
LIBRARY

Figure 41.

• (external reference)

Format of the LIBRARY card

Example:LIBRARY • (SINE)• specifies the never-call function.
SINE is an external reference in the output.
As a result, if SINE is unresolved
no automatic library call is made.

after input processing,

Changing Object Programs

CMS BATCH MONITOR
The Batch Monitor
can be run froma terminal likeconversational CMS.
The Batch Monitor permits use of the
FORTRAN (G),ASSEMBLER (F). and PL/I
(F) compilers.
Temporary work files, referred to as FORTRAN logical files,
are stored on disk and should be of limited size. The Batch
Monitor's permanent disk is erased and CMS is re 9 IPLed
whenever a JOB card i's processed.
SAMPLE BATCH JOB
Source, object" or data cards included in the job stream arestored as separate CMS files. Each file is identified by afilename and filetype. FORTRAN, ASSEMBLE, and TEXT control
cards indicate the filetypes FORTRAN, SYSIN, and TEXT.
respectively. If unspecified, the filename is chosen by thesystem,.
Whena FORTRAN file is compiled or a SYSIN file isassembled, an object module is generated as a file with afiletype of TEXT and the same filename as the source file.
Data files to be read as a FORTRAN logical unit must be
identified as FILE FTOnFOOl where n is 1, 2, 3, 4, or 8.
Files created by writing on one of the above FORTRAN logicalunits are identified, in the same way. These files may be
PRINT'ed or PUNCHeed using the appropriate control card andspecifying the filename and filetype,.
Execution of object modules (TEXT files) is initiated by the
GO control card. The control card causes all TEXT files tobe loaded into core. Execution begins at the entry point
specified in the GO control card or at the first program
encountered in the job stream.
If a program interruption
occurs during program execution, the programmer gets acomplete core dump and the job is terminated. Data cards
following the GO control card can be read as FORTRAN logicalunit 5 (sysin). Any data cards following the GO control
card which are not read are ignored. An example of a CMS
Batch job deck is shown in Figure 48.

526

CMS Batch Monitor

Standard Job Card//jobname JOB// userid acctno.
// FORTRAN••
Fortran Program 1 Source Code

Fortran END card
Fortran Program 2 Source Code'Fortran END card// ASSEMBLE ABLE
Assemble Program 1 Source CodeAssembler END card
Assembly Program 2 Source CodeAssembler END card
/ / PUNCH ABLE SYSIN// TEXT
Object Module/ / GO

Data Cards// PRINT FILE FT01FOOl// ASSEMBLE ABLE (NOLIST)
Second Version o£ Assembly Program ABLE
Assembler END card// GO ABLE
Figure 48.

Sample CMS Batch stream

CMS Batch Monitor

527

CMS BATCH CONTROL CARDS
A deck to be submitted for CMS Batch must have an OS/360
standard job card., The second card must be ~ /useridacctno.. The control cards for eMS Batch specify a procedurename together with optional parameters. Control cards musthave / / in columns 1 and 2, and column 3 must be blank.
Procedure names and parameters are each separated by one ormore spaces. ~he CMS Batch control cards are described in·subsequent sections.
To simplify the transition from an 05/360 job to a eMS Batch
job, selected OS/360 control cards are translated into eMS
Batch control cards to perform the corresponding functions.
The OS/360 procedure names which are recognized, and the CMS
Batch control cards they are equivalent to. are specified
below.
OS Procedure Name

Batch Control Card

FORTRAN// FORTRAN// FORTRAN// TEXT// TEXTLARGFORT
LINKEDITLINKOBJ
LINKSRCEXECUTE
DI5KEXECASSEMBLE/ / TEXT// GO/ / GO// ASSEMBLE// ASSEMBLE// PUNCH// PUNCH

ASEMLINI<PUNCH
TPPCHOBJ
Notes:a.
The only OS/360 // EXEC cards that are recognized byeMS Batch are the ones specified above: all other OS/360
contro1 cards are ignored.
b.

Only one job step per procedure call is allowed.

c.
A list of CMS Batch control cards can be found"igure 49 (see following sections for specific formats).

528

eMS Batch Monitorin/ / ASSEMBLE/ / COMMAND//

CP/ / DATASET/ / FORTRAN/ / GO/ / PRINT/ / PUNCH/ / TEXT

Figure 49.

CMS Batch control cardseMS Batch Monitor

529

// ASSEMBLE
Format:I // ASSEMBLE 1 <filename>«optionl ••• optionN»

I

I

I

I·

filename specifies the name of the file which contains the
cards following the // ASSEMBLE control card up to
the next control card. The filetype is SYSIN.

•

If no parameters are specified. achosen by the system and the default
taken.

filename is
options are

Options:
LIST creates the LISTING file.
NOLIST suppresses creation of the LISTING file.
creates the cross-reference symbol table within the
LISTING file.
NOXREF suppresses the creation of the symbol table. This
option was
the NOLIST
ignored if
option is
specified.

XREF

RENT

causes the assembler to generate messages in the
LISTING file if nonreentrant coding is found in theassembled program.
NORENT suppresses the generation of messages in the LISTING
file ifnonreentrant coding is foundin theassembled program.

Usage:All cards following the // ASSEMBLE control card up to thenext control card are assumed to be Assembly Language source
cards.
These cards are read and stored as a file andtranslated using the F-level Assembler and the specified
options.
The source cards may contain any number ofroutines, each delimited by an END statement. If a filenameis specified, the source cards are stored as a file withthis filename and the filetype of SYSIN. If filename is not
specified, the system chooses a unique name.
The options
specified govern the translation of the source cards. Any
combination of options may be specified in any order.
An assembly generates a LISTING and a TEXT file..
The
LISTING is automatically written out on sysout.
The TEXT
file (that is, object module) can be punched using a //PUNCH control card. The filename of the TEXT file is thesame as the filename of the Assembly Language source file.
Object modules are loaded into core and executed when the //530

CMS Batch Monitor

GO control card is specified.
output:LIST provides a listing of the assembled machine-language
code,. together with the source statements and an external
symbol directory.
XREF includes
listing.

across-reference

symboltable

RENT includes messages in the listingcoding found in the assembled program.

for

Diagnostic
listing.

theand error

messages

appear at

with

the

nonreentrant
end oftheNote:
The assembler searches the eMS macro lib~aries.
SYSLIB
MACLIB and OSMACRO MACLIB, for macro definitions. Additional
macros may be included with the source program.
References:
For information on the Assembly Language. see IBM 08/360
Assembler Language (C28-6514) and Assembler ! Proqrammer·s
Guide (C26-3156) .. For information on the System/360 machine.
see IBM Systero/360 Principles of Operation (A22-6821).

CMS Batch Monitor'

531

// COMMAND
Format:I // COMMAND I anycmscommandl
anycmscommandany valid CMS command~ay

be executed except

CPFUNC'I'N.

Usage:The // COMMAND enables any CMS command to be entered andprocessed within the BATCH job stream. thereby enabling theuser to perform operations not directly possible under
Batch. For example, he could create EXEC files and execute
them or use· the other eMS language processors in addi tioD
to FORTRAN and ASSEMBLER,.
l,

Examples:a.
/ / COMMAND PLI PROGA
This causes the compilation
PL/l (F) compiler.

of the file

PROGA PLIby theh.
//COMMAND EXEC FORTCLG TEST1.
This causes the file FORTCLG EXEC to be executed. and would
pass the argument TEST1 to it.
The file, FORTCLG EXEC would
have been previously entered via the // DATASET FORTCLG EXEC
card.
Note:
The CPFUNCTN command cannot be issued.

532

eMS Batch Monitor

// CP
Format:~~~~----------~-----------------~

II
I // CPI
I
I

MSG
userid line
XFER Doff
to use rid

I
I
I

Usage:The // CP card enables the user either to send messages orto transfer his punched output. If Batch is running in a
disconnect mode, the user may send decks to be processed,
and, via the // CP XFER, he may receive his punched decks
back at his own virtual machine.
Examples:a.
// CP XFER D TO MINE
This causes all subsequent punched output
user MINE.

to be sent to theh.
/ / CP MSG CP YOU MAY DISCARD MY OUTPUT
The message YOU MAY DISCARD MY OUTPUT is
operator·s console.

eMS Batch Monitor

typed onthe533

// DATASET
Format:I // DATASET
filename filetype

filename

filetypel

specifies the identifier to be given to
the file
which contains
the cards
following the // DATASET control card to
the next control card.

Usage:
The cards following the // DA~ASET control card up to thenext control card are read and stored as a file.
If thefile identifier is of the fQrm FILE FTOnF001, the file canbe read as a FORTRAN logical unit.
Examples:a. // DATASE~ FILE FT01FOOlb. // DATASET QUIET EXEC

534

eMS Batch Monitor

// FORTRAN
Format:I // FORTRAN
I

l<filename>«optionl ••• optionNl> I

1 * '~---------------------------------~-------------~-

filename

specifies
thenameof the file whichcontains the cards following the // FORTRAN
control card up to the next control card. The
filetype is FORTRAN.

*

If no parameters are specified, a filename ischosen by the system and the default options aretaken.

Options:
MAP includes tables of addresses of FORTRAN variables in the--LISTING file.
NOMAP suppresses the tables of variables.
LIST includes a listing of object code in Assembly language
mnemonics 1n the LISTING file.
NOLIST suppresses the object code listing.
BCD causes the source program to be interpreted using the
Binary Coded Decimal code.
EBCDIC causes the source program to be interpreted using the
Extended Binary Coded Interchange Code.
Usage:All cards following the // FORTRAN control card up to thenext control card are assumed to be FORTRAN source code.
These cards are read and stored as a file and compiled using
the FORTRAN-G compiler under the specified options.
The
source cards may contain any number of routines!. eachdelimited by an END statement.
If a filename is specified,
the source cards are stored as a file with this filename anda filetype of FORTRAN. If filename is not specified, thesystem chooses a unique name.
Any combination of options
may be specified in any order.
A compilation generates a LISTING and a TEXT file. The
LISTING file is automatically written on sysout.
The TEXT
file can be punched using a // PUNCH control card.
The
filename of the TEXT file is the same as the filename of the
FORTRAN source file.
TEXT files are loaded into core
control card is specified.

and executed when the // GOeMS Batch Monitor535

output:
MAP produces atable of addresses foreach of theclassifications of variables in the source program
COMMON, EQUIVALENCE!, NAMELIST, FORMAT, scalar variables, andcalled sUbprogram names.
LIST provides a listing of the object program with relative
addresses
and
instructions translated
into
assembly
language.
Diagnostic and error messages produced by the compiler areplaced in the LISTING file and printed on sysout.
Notes:a.
Source cards can be punched in either Binary Coded
Decimal (BCD) or Extended Binary Coded Decimal Interchange
Code (EBCDIC). If BCD code is used, the BCD option must be
specified for the compilation.
b.
The entry point for the first main program is the sameas the filename. Subsequent main programs have the entry
point MAIN. The entry point for subroutines are specified
in the SUBROUTINE statement.
c.
Data can be read from sysin using FORTRAN logical unit
5 and written onto sysout using FORTRAN logical unit 6.

d.

Only FORTRAN logical units 1-6 and 8 may be used.
FORTRAN logical files are defined as follows:
Logical File

The

Record Length80-character records
SO-character sysin records
130-character sysout records
133-character records withcarriage control

1-4
5
6
8

e.
An ID is punched in columns 73-80 of object decks. For
subroutines, the first four letters of the subroutine nameare used in columns 13-76. For main programs the first four
letters of the filename are used if i t is the first deck in
the file, otherwise MAIN is used. Columns 71-80 contain asequence number.

f.

Information in the IBM system/360 Operating System Job
Control Language is not applicable under CMS. The LOAD,
NAME=, and LINECNT= options are not supported.
References:
For information on
System/360
FORTRANthe
IV

FORTRAN
Language

IV language, see(C28-6515), and536

eMS Batch Monitor

IBM
IBM

System/360 Operating System FORTRAN IV Library: Mathematicaland S~rvice
Subprograms. For information·
on compiler
operation and messaqes, see IBM system/360 Operating System
FORTRAN IV (G and H) Programmer·s Guide.
.

eMS Batch Monitor

537

// GO
Format:I // GOI

I <entry point> I
I default entry point I

entry point specifies the name of a control section or entry
point to which control is passed at execution
time.
default entry point is the beginning of theencountered in the job stream.

first program

Usage:// GO causes all TEXT files to be loaded into core. together
with the required modules from SYSLIB TXTLIB. and proper
linkages to be established between the program modules.
Programs are loaded at X'12000· and may extend to X·3DOOO'.
A load map containing the location of control sections andentry points of programs loaded is created and printed on
sysout. After loading. execution is begun by transferring
control to the entry point.
Data cards following the / / GO control card can be read from
FORTRAN programs using logical unit 5. Data cards not readare ignored. output written onto FORTRAN logical unit 6 iswritten onto sysout and printed.
Note:
An entry point must be either a control section name or an
entry point name.
It may not be a filename unless thefilename is identical to a control section name or an entry
point name.
Examples:

a.

// GO

h.

// GO ENTRY1

Error Messages:
EC00001)

DEFINED MORE THAN ONCE -xxxxxxxx

EC00002) OVERLAY ERROR
The files being loaded have run out of core.
E(00003) REFERENCE TABLE OVERFLOW
There are too many entries for the entry
section names in the reference table.
538

eMS Batch Monitor

points or control

E(00004)

The

THE FOLLOWING NAMES ARE UNDEFINED -xxxxxxxx

names xxxxxxxx

arereferred toandhave never

been

EC00005J NAME IS UNDEFINED - xxxxxxxx
name xxxxxxxx specified as an entry
exist.

point does

notdefined.

The

eMS Batch Monitor

/ / PRINT. Format:I // PRINT I filename filetype ,filename filetype specifies the name of the file to beprinted on sysout.
Usage:
Each line of the specified file is truncated to 130
characters and printed on sysout.
The first character of
each line of a LISTING file is used as a printer carriage
control character.
'These carriage
follows:

controlcharacters

CHARACTEREBCDICACTION

"

.

as

"0·

FO

space 1, priDt line~ space 1

"1"

Fl

skip to new page, print line, space 1xx

any character other than the above isused as a CCW// PRINT FILE FT01F001
Error Message:

540

interpreted

print line .and srplaee 1

Example:E(00003}

are

FILE NOT FOUNDeMS Batch Monitor

// PUNCH

Format:I j / PUNCH

I filename

filetype I

filename filetype the identifier of the file to be punched
Usage:

Files with records up to SO characters in length are punched
into an aO-column card.
Examples:a.

/ / PUNCH PROG1 'rEXT

The file PROGl TEx-I' is punched.

h.
// PUNCH FILE FT01FTOOl
The FORTRAN logical file 1 is punched.
Error Message:
E(00002)

FILE NOT FOUNDeMS Batch Monitor

541

// TEXT

Format:// TEXT
Usage:
The cards following the // TEXT control card up to the next
control card are read and stored as a file.
A uniquefilename is chosen by the system and the filetype is TEXT.
Example:// TEXT542

eMS Batch Monitor

RUNNING THE eMS BATCH MONITOR

Setup
CMS Batch accepts an input stream from either the card
reader or from tape. The punched output can go to tape or
to cards and the printed output can go to tape or to theprinter. The tape assignments are as follows:
Symbolic
Address

VirtualAddress

contents

Track

TAPS

185

SYSIN

9

Tap6

186

SYSOUT

9

TAP7

187

PUNCH

9

If the SYSIN tape is not attached to the BATCH machine, thesystem assumes that the input stream comes from the card
reader.
If the PUNCH tape is not attached, the systemwrites the PUNCHeed output to the online punch. If the
SYSOUT tape is not attached, the printer is used.
Unlabeled tapes are used. The SYSIN tape consists of
unblocked card images. The PUNCH tape consists of unblocked
card images, but each job is a separate file where the firstrecord contains the job number and the programmer's name.
The SYSOUT print tape consists of unblocked 133-character
records.
Each job is limited in number of minutes of execution timeand number of lines of printed output. These limits may bereset by the system programmer. The default settings are
five minutes and 5000 lines.
Using CMS BATCH
To run the eMS BATCH stream,a.

LOGIN to CP as the BATCH user.

h.

IPL the Batch Monitor·s Nu-cleus"c.

Issue the START command.

d.
Optionally, ATTN may be hit to enter CP"
and DISCONN
may be entered to run BATCH in the disconnect mode.
When a job is canceleda message is writ.ten on SYSOUT
indicating this to the prog·rammer, along with an explanation
as to why this was done.
The following messages may be
printed:l,a.
TIME LIMIT EXCEEDEDThe running time of the job exceederl the allowable executioneMS Batch Monitor543

time.
b•
OUTPtn' LIMI-r EXCEEDEDThe number of output lines
output,.

exceeded the allowable length ofNotes:a.
Each job is limited to minutes of execution time andlines of printed output.
If either of these limits is.
exceeded. the job ~s canceled. These limits may be set by
the system programmer at your installation.
b.
When an end of file is encountered on the input device.
the message END OF INPUT STREAM is typed on the console. An
enabled-WAIT PSW is loaded" and, a DEVICE END interrupt on
the input device reinitiates batch operations. Thus, a job
may be XFEReed to BATCH, and BA-rCH processes it.
c.
An accounting card is punched for every job that Batch
runs. This card is spooled to the virtual machine whose
userid is OPERATOR. and is punched out in the CP accountcard format.
Example:The login procedure for using the Batch Monitor is
cp-67 online
1 cmsbatch

xd.65 qsyosu

ENTER PASSliiORD:READY AT 13.32.38 ON 09/08/69
CP
ipl ccu
READY

start
where ccu is the address of
copy of the BATCH nucleus.

the disk containing an IPL'able

Optionally, the ATTN key may be hit once to enter CPr and
DISCONN may be typed in. The terminal is then free for use
by another virtual user~ while BATCH continues to process
its job stream. or waits for a stream to be XFER'ed to it.

544

CMS Batch Monitor

GLOSSARY
Terms with specific meanings
below in alphabetical order.

in CP

and CMSare described

ACTIVE DISK TABLE. A table residing in the user's copy of
the CMS nucleus which contains an entry for each of thesix d~sks that the user may access with CMS.
ACTIVE FILE TABLE.
A table residing in the user·scopy of
the CMS nucleus which contains an entry for each ofthat user's currently opened files.
ARGUMENT. Any alphameric information, not exceeding eightbytes in length, the address of which is to be passed
to a program at the time it begins executing or to a
CMS command.
ATTENTION INTERRUPT. A signal to the system which· effects atransfer of control between the Control Program andother environments. The terminal keyboard is unlocked,
regardless of current processing. and the input line isprocessed by the environment in control.
ATTENTION KEY. A key on the terminal which, when hit,causes an attention interrupt. This key is labeled
ATTN on the 2141. and RESET LINE on the 1050.
CARD IMAGE.
An 80-character logical record in which eachcharacter corresponds positionally to the columns of apunched card.
CARRIAGE RETURN. The signal which indicates to the system
the termination of a line of input from the terminal.
This signai is transmitted on the 2141 by hitting the
key labeled RETURN: on the 1050, it is transmitted
either by holding down the ALTN CODING key while
hitting the 5 key" or (if the 1050 is equi.ppedwith theAutomatic EOB special feature) by hitting the RETURN
key.
CHARACTER-DELETE SYMBOL.
A character appearing on theterminal keyboard which, when hit n times, deletes thepreceding n characters and itself from the input line.
Currently defined as the Q character, but can be
redefined in ~S by the CHARDEF command.
CMS

FUNCTION.
A routine available to the CMS commandprograms for the handling of internal processing. suchas accessing and updating disk file directories orhandling disk and terminal I/O.

eMS NUCLEUS. The core-resident portion of CMS of which eachuser receives a copy at the time he issues an IPL 190
or IPL CMS console function.

GLOSSARY

545

CONSOLE FUNCTION. A software facility whereby the user, at
his terminal. can simulate a function he would normally
be able to perform at a 360 console. The command
facilities of the Control Program are referred tocollectively as CP console functions.
CONTROL SECTION. A block of coding that can be relocated,
independent of other coding,
without altering or
imparing the operating logic of the other coding.
CP/CMS SYSTEM. A time-sharing systero in which the Cambridge
Monitor System (eMS) runs as the operating system of avirtual machine created by the Control Program (CP) '.
CPU

TIME. The period of tiroe during which the central
processing unit of the computer is actively engaged in
the processing of instructions.

DEFAULT ENTRY POINT.
The core location at which execution
begins if no starting location is specified;eitherthat given in the first nonblank operand of an END card
image or, ifal! END operands are blank, the beginningof the first labeled control section of the loaded
program(s).
ENTRY POINT. Any symbol in a control section which can beused by other control sections to effect a branch
operation or a data reference.
ENVIRONMENT. That portion of the CP/CMS system which has
control at the time an input line is transmitted fromthe terminal, and which processes that input line to
Only a subset of all
determine its acceptability.
possible input is acceptable in any given environment.
ERROR

MESSAGE.
The
message
WE(xxxxxl;T=xx.xx/xx.xx
hh.mm.ss·, where xxxxx is the error code returned ingeneral-purpose register 15, the first xx.xx is thevirtual CPU time in seconds, and the second xx.xx is
the total CPU time in seconds used since the last Readyor Error message.
Any
information typed at theterminal which explains the meaning of the error code
may also be considered part of the error message.

FILE DIRECTORY.
A table for each disk file storage area
which indicates the file identifier"file size, andlocation of each file stored in that area.
For
example, the system file directory contains informationfor each file stored on the system disk.
FILE IDENTIFIER.
A three-part designation which uniquely
identifies each file stored on disk,.
This identifierconsists of a filename (any descriptive t.erm), a
filetype (indicating file contents) " and a filemode(indicating file location).

546

GLOSSARYINPUTLINE.
All information, up to a maximum of 130
characters in length., typed by a user between the time
the typing element of his terminal comes to rest
following a carriage return until another carriage
return is issued.

LINE-DELETE SYMBOL.
A character appearing on
the terminal
keyboard which"when hit, deletes
all preceding
characters in the input line and itself.
currently
defined as the ¢ character,. but can be redefined by the
CHARDEF command in CMS.
LINE-END CHARACTER.
A character appearing on the terminal
keyboard which. when hit" causes a logical end of the
input line so that information typed before and after
this character is interpreted as if entered on separatelines (that is, a logical carriage return). Currently
defined as the # character, but can be redefined by the
LINEND command.
LINKAGE.
The resolving of external
control sections at load time.

references

betweenLOAD MAP. A file containing the core locations of control
sections and entry points of programs loaded into core.
MACRO

LIBRARY. A disk file(whose filetype is MACLIB)
containing macro definitions in assembler language
source code and a dictionary of the name, size" andlocation of each macro definition within the file.

NULL LINE.
An input line consisting of a carriage returnissued as the first and only information after thetyping element of the terminal has come to rest
following a previous carriage return.
OFFLINE DEVICE. A device whose I/O is temporarily stored ina spooling area by the Control Program; namely,. thecard reader, printer. and card punch.
ONLINE.
Any operation performed at a
actively connected to the computer.

terminal whichis

OPERAND. Any field, delimited by one or more blanks r, which
may be specified in a command
request, or console
function. The operands are distinct from the command.
request, or console functi'on name.. which is always thefirst field specified.
t•

OUTPUT. Any message or information typed by the system (asopposed to the user) at the terminal. This term is also
used to refer to information punched onto cards.
printed on the printer. or written out on magnetic
tape.
OVERRIDE.

A flag set internally
GLOSSARY

to indicate whether or not547

the userhas
information.

requestedtherecording

of

trace

PAGING AREA. A secondary storage area on disk which is
assigned to a particular virtual machine. and is used
for temporary storage ofby the Control Program
portions of core belonging to that virtual, machine. inorder to allocate main storage dynamically among thevarious users.
PARAMETER LIST. A string of doublewords used whenever a CMS
command or function is called by an SVC instruction.
The format of the parameter list varies depending on
the command or function being called, but always
contains the name and operands of that command or
function.
PERMANENT DISR. A disk area allocated to each user (at thetime he is authorized to use the CP/CMS system) on
which stored files are retained until the user requests
that they be deleted.
READ-ONLY. An indication that the user may have access tothe contents of a disk, but may perform no WRITE
operations to that area (that is, he may only READ it).
READY MESSAGE. The message wR:T=xx.xx/xx.xx hh.mm.ss· which
is typed as a response indicating the successful
completion of a CMS command and a return to the CMS
command environment. The first xx.xx is the virtual CPU
time and the second xx.xx is the total CPU time inseconds used since the last ready or error message.
REQUEST. Input acceptable only to an environment
unique to a specific CMS command.
RESPONSE. Any nonerror
the terminal.

message typed out by

which isthe system at

SPOOLING AREA. Any disk area used by the Control Program totemporarily hold input from the offline card reader or
output to the offline card punch or printer.
SYSTEM DISK.
A disk area containing the CMS
nucleus" ofwhich each user receives his
own copy, and the
disk-resident portion of CMS, which is shared by allusers.
SYSTEM FILE.
Any file residing on the system disk
opposed to the user·s permanent or temporary disks.

as

TEMPORARY DISK.
A disk area allocated to the user at thetime he logs into the Control Program, on which stored
files are retained only for the duration of theterminal session.

548

GLOSSARYTERMINAL SESSION. The period between a user's completed
login to CP until he logs out from CP.
(Note that new
copies of the CMS nucleus may be obtained during aterminal session.)TEXT

LIBRARY. A user or system file. whose filetype is
TXTLIB, which is composed of TEXT files containing
relocatable object code and a dictionary indicating thelocation and size of each of these TEXT files within
the library.

TOTAL CPU TIME. The time required to execute the virtual
machine's instructions plus the overhead of CP for
running that virtual machine.
TRACE INFORMATION,.

Data (such as the contents of various
registers and parameter lists) recorded by the system
to enable the user to trace transfers to and from
SVC-called programs.

UNIT RECORD DEVICE.
USER

A card-reader, card punch, or printer.

FILE. A file residing on the user's permanent
temporary disk as opposed to the system disk.

or

USERID. Any combination of from one to eight characterswhich uniquely identifies auser to the Control
Program.
VIRTUAL CPU TIME. The time required to execute the virtual
machine's instructions,. This time includes no overheadof CP.
VIRTUAL MACHINE. A functional simulation of a computer andits associated devices.
The
Control Program, bycreating several virtual machines and allocating the
hardware facilities of a single computer among them,creates an atmosphere in which the users of the virtual
machines may each function independently and withdifferent operating systems.
VIRTUAL MEMORY. The amount of core that the virtual machine
has--this need not be the same as the memory of thereal machine or the memory of any or all other virtual
machines.

GLOSSARY549

APPENDIX A: CONTROL PROGRAM CONSOLE FUNCTIONSEach of the CP-67 console functions that can be
the terminal user is described below.

issued by

BEGIN

begins execution at the specified address or., if
no address is given. at the location at w~ich
execution was interrupted.

CLOSE

releases the spooling areas containing input
from the card reader or output to the printer orcard punch.

DETACHremoves the specified device
virtual machine configuration.

DIAL

is used in place of LOGIN to connect a user's
terminal witha virtualtelecommunications
operating system ora virtual time-sharing
system.

DISCONN

allows a user to disable the terminal and leave
his virtual machine running.

DISPLAY

types at the terminal the- contents of thespecified register(s)~ core
location(s), or
program status word.

DUMP

printsthecontentsofthespecifiedregister (s) " core location (5) " or 'program status
word on the offline printer.

from theuser'ssimulates an external interrupt tocausing control to pass
DEBUG' command.

the virtualto the CMS

IPL

simulates the Initial Program Loadthe specified unit.

sequence on

IPLSAVE

simulates the Initial Program Load sequence on
the specified unit, but does not zero corefirst.

LINK

attaches virtual disks dynamically.

LOGOUTreleases the user's virtual machine. including
his temporary disk area, and closes any spoolingareas which have not been released.

MSG

types the specified message at the ter~inal of
the person whose USERID is specified.

PURGE

erases spooled input or output files by device.

QUERY

types out either thenumber of logged-in anddialed users;, the names of logged-in users;, theEXTERNAL~achine,550

Appendix Anumber of current spooled
files. or the current clock
used.

input and output
time and CPU time

READY

simulates a device end for the specified unit.

RESET

si·mulates the system reset key on the 360
console by resetting any pending I/O interrupts.

SET

controls the saving of virtual card reader
files. the operation of the virtual machine evenwhen in the CP environment. and the typing of
messages at the terminal.

SLEEP

places the terminal
receive messages.

SPOOL

directs spooled output andof spooled input.

STORE

replacesthecontentsofthespecifiedregister(s). core location(s). or program
atus
word with the specified information.

XFER

controls the passing of files between users.

inAppendix· Aadormantstate

tocontrols the reading

551

APPENDIX B: CMS Commands---

The commands that
described below.

can

be

issued byauser

to CMSare

ALTERchanges all or part of the identifier (filename,filetype. and filemode) of a file stored on theuser·s permanent or
temporary disk without
altering the contents of the file.

ASSEMBLE

converts assembler language source code into
relocatable object code using the 05/360 F level
assembler.

BLIP

causes a specified string of characters to be
typed at the console every two seconds of CPU
execution.

BRUIN

invokes the Brown University .Interpreter, inwhich the user has a desk-calculator mode and astored-program mode. BRUIN is available as a
Type III program.

CHARDEFredefines thecharacter-delete symbol,
theline-delete symbol"
the logical tab character,and the logicalbackspace character~ which
default to the i . ¢, I, and I respectively.

CLOSIOsignals the Contr.ol Program that I/O to offline
unit record equipment has been completed andthat the spooling areas for this I/O may beprocessed.
CLOSIOisgenerallyissuedautomatically by the commands which access unit
record equipment.

CLROVERthe SETERR and/or
clears overrides set by
SETOVER commands, and causes all recorded trace
the offline
information to
be printed on
printer.

COMBINEcopies the specified file(s), concatenating themin the order given, into a new file, which isplaced on the user's permanent or temporary disk
and assigned the specified identifier.

COMPARE

compares two disk files.

CPFUNC'l'N

issues CP console functions without leaving CMS.

CNVT26

converts BCDIC files to EBCDIC.

CVTFV

converts filesof fixed-lengthvariable-length records.

DEBUG

allows the user to stop and restart programs at
specified points. and to inspect and change the552

APPENDIX B

records

tocontents of registers,
core
hardware control words online.

locations,

and

DISK

causes a CMS disk file to he punched out or readin from cards which are in CMS card format.

DUMPD

prints the contents of a direct-access record,
specified by a CCHHRR address, in hexadecimal on
the printer.

DUMPF

types the contents of all, or partof
specifie.d file in hexadecimal on the console.

DUMPREST

dumps the contents of an entire disk to magnetic
tape, or restores the contents of an entire disk
from magnetic tape,.

ECHO

tests terminal line transmission by repeating as
typeout whatever is typed in by the user.

EDIT

allows the user to create files on disk, tomake changes
to existing
files fromhis
terminal, and to peruse the contents of files.

ERASE

deletes the entry for a specified file(or
files) from the appropriate directory, rendering
the file inaccessible to the user,
and freeing
the disk area containing that file~

EXEC

executes a file containing one or more eMS
commands, allowing a sequence of commands to be
executed by issuing a single command.

FILEDEF

allows the user to specify the I/O devices which
are used by his program. This command is not
currently
supportedby theCMS
languageprocessors.

FINIS

closes the specified file(or files) by writing
the last record of that file on disk, updating
the user-file-directory and removing the entry
for that file from the user·s table of active
files.

FORMAT

prepares the user·s permanent or temporary disk
area for eMS use by writing blank records overthe currently stored infor~ation.

FORTRAN

converts FORTRAN language
source code into
reiocatable object code using the OS/360 FORTRAN
G compiler.

GENMOD.

creates a nonrelocatable core-image file on theuser·s permanent disk, which is a copy of thecontents of core between two given locations.

i,

APPENDIX B

a

553

GLOBAL

specifies macro definition
libraries to ·besearched during the assembly process or text
libraries to be searched when loading files
containing relocatable object code.

KO

clears overrides previously set by the SETOVER
or SETERR
commands. and causes
all trace
information recorded by these commands to beprinted on the offline printer.

KT

stops typeout at the terminal for the durationof the currently executing command or user
program.

KX

terminates the currently
executing program,
updates the user-file-directory, reIPL's CMS andreturns control to the CMS command environment.

LINEND

redefines the logical line-end character whichallows multiple commands to be entered on one
line. The default is the #.

LISTF

either types out at the terminal the identifier.
size and creation date or change date of thespecified disk file(s). or creates a file on theuser·s permanent disk containing information foruse by the EXEC and/or $ commands.

LOAD

reads the specified TEXT file(s)-~containing
relocatable object code--from disk or a library,loads them into core. and establishes the proper
linkages.

LOADMOD

reads a MODULE file--which is in nonrelocatablecore-image form--from disk, and loads it into
core.

LOGIN

causes the user·s permanent disk files to beeither saved or deleted, as specified. andallows a specified disk to be logged-in as theP-disk. If LOGIN is not issued, the files are
saved.

LOGOUT

compacts the user-file-directory, executes any
CMS command specified as an operand, and logs
out of CMS, transferring control to the Control
Program.

MACLIBgenerates, adds
to, replaces,deletes, orcompacts macros in a specified macro library, or
types out the contents of the dictionary of thatlibrary.

MAPPRTtypes or creates a file containing the load map
associated with the eMS nucleus.

554

APPENDIX B

MODMAPtypes the load map associated with a core-image
MODULE file on the console.

OFFLINE

creates disk files from card input, prints a
disk file on the offline printer, or punches adisk file on cards.

OSTAPE

creates disk files from card images on tape.

PLI

converts
PL/I
language source
code
into
relocatable object code, using the OS/360 PL/I F
compiler.

PRINTFtypes at the terminal the contents ofpart~ of a specified disk file.

RELEASEreleases a disk from a user's
when he has finished using it.

REUSEreads the specified TEXT fileCs)--containing
relocatable object code--from disk, and loads
them into core,establishing linkages withpreviously loaded files and changing the default
entry point of these files to that of the first
file specified in the REUSE command.

RT

restores typing
at the terminal
previously suppressed by KT,.

SCRIPTtypes orprints out the contentsof thespecified file, formatting it, as indicated, bycontrol words contained in the text.

SETERR

sets
error
overrides
which
cause
trace
information to be recorded for each SVC-called
program which returns with an error code in
general-purpose register 15.

SETOVERsets normal and error overrides which cause
trace information
to be recorded
for all
SVC-called
programs--both those
which
are
executed normally. and those which return anerror code in general-purpose register 15 .•SNOBOL

converts a card-image file in Snobol source
language into SPL/l interpreter language andexecutes SPL/1 programs. SNOBOL is available asa Type III program.

SORT

arranges records of a diskorder and writes the sorted
file.

SPLIT

copies the specified portion of a card-image
file" and either creates a new file or appends
it to a second s.pecified card-image file.
APPENDIX B

all, orvirtual machine

that

was

file in ascending
output into a new

555

START

begins execution of the loaded program(s) at the
specified or default entry point and passes theaddress of a string of user arguments to theprogram(s).

STAT

types
statistics regarding
the amountofpermanent and/or temporary disk space used, orcompacts the user-file-directory.

STATE

tests whether a file exists.

SYN

allows the user to specify his own command
abbreviations to be used with, or in place of,the standard system abbreviations.

TAPE

writes the contents of C~S disk files of any
type or size onto magnetic tape, or restores
these files by writing them from tape onto disk.

TAPEIO

writes a tape mark on magnetic tape,gap on the tape" or moves the tape.

TAPRINT

copies LISTING files from tape to printer.

TPCOPYcopies tape files.

TXTLIBgenerates, adds to, or deletes modules in a
specified text library, types out the contentsof the dictionary for that library, or creates afile containing a list of entry pOints andcontrol section names contained in that library.

UPDATE

updates the specified disk file with a filecontaining control cards, where each control
card
indicates
whethertheinformation
immediately following it is to be resequenced,
inserted" replaced!. or deleted.

USE

reads the specified TEXT file(s)--containing
relocatable object code--from disk and loads
them into core,establishing linkages withpreviously loaded files,.

WRTAPE

copies files
to tape.

$executes a file containing one or wore CMS
commands" or loads into core a file which is ineither core-image form or relocatable object
code and begins execution of that file.

556

of fixed-length records

APPENDIX B

erases afrom disk

~PPENDIX

C: DEBUG REQUESTS

BREAK

specifies a core location at which acurrently loaded into core is to beduring its execution.

CAW

types out the contents of the channel address
word as it existed when DEBUG was entered,.

CSW

types ou~ the contents of the channel status
word as it existed when DEBUG was entered,.

DEF

enters the specified symbol in the DEBUG symbol
table, allowing it to be used thereafter inother DEBUG requests to refer to a specific core
location.

DUMP

prints out the contents of the specified portionof core on the offline printer.

GO

begins execution either at a specified location
or at the point where execution was interrupted
when the DEBUG environment was entered,.

GPR

types out
the contents
general-purpose register(s)the time DEBUG was entered.

IPL

performs an initial program load sequence on theversion of the CMS nucleus which has been savedby CP.

RX

terminates the currently-executing program: andlogs out froID CMS, transferring control to the
CP environment.

ORIGINestablishes a -base- address which is added to
all hexadecimal locations specified in other
DEBUG requests.

PSW

types out the contents of the old program status
word which was saved at the time DEBUG wasentered.

RESTART

reinitializes the CMS system, leavingin the CMS Command environment .•RETURN

returns the user from the DEBUG
the OMS Command environment.

SETchangesthecontentsofthespecifiedgeneral-purpose register, channel address word.
channel status word, or program status word by
replacing them with the specified information.

STORE

changesthecontents
APPENDIX C

ofof theas theytheprogram stopped

specifiedexisted at

the userenvironment tospecified

core
557

location by
information.

replacing

them

with

specified

TIN

Selects which environment is
I/O, CMS or DEBUG.

xtypes atthe terminal the contents
of aspecified or assumed number of bytes of core,
starting at the specified location.

558

APPENDIX C

to handle terminal

APPENDIX D: EDIT REQUESTSThe EDIT requests are described below in alphabetical order.
These are the only valid input to the Edit environment,
although some of the requests affect the format of the input
to the Input environment.
BACKSPACE

defines a logical backspace character for use inboth the Edit and Input -environments..
Thedefault character is %.

BLANK

places blanks in the indicated columns of theline at which the internal pointer is currently
positioned.

BOTTOM

positions the pointer after the last line of the
file.

BRIEF

causes the brief mode of the Edit environment to
be entered, in which lines found or altered by
Edit requests are not autoroaticalily typed out.

CHANGE

replaces a specified
currently in the filestring of information.

DELETE

deletes the specified number of lines from thefile, starting with the line at which thepointer is currently positioned.

FILE

writes the edited file on the user·s permanent
disk and transfers from the-Edit environment to
the CMS Command environment.•

FIND

scans each line of the file, starting at theline immediately following the one at which thepointeriscurrently
positioned,foracolumn-dependentmatch withthespecified
information.

INPUT

transfers the user fromthe Input environment.

INSERT

inserts the specified line of information into
the file immediately after the line at which thepointer is currently positioned.

LOCATEscans the contents of the file, starting at theline immediately following the one at which thepointer
is currently
positioned, forthespecified string of information.

NEXTmoves the pointer forward in
number of lines specified.

OVERLAY

replacescharacters in
APPENDIX D

string of information
with another specified

the Edit environment to

the file

the line

for theat whichthe559

pointeris currently
positioned
nonblank character(s) specified.

with

the

PRINT

types out the contents of a specified number oflines, starting with the line at which thepointer is currently positioned.

QUIT

transfers from the Edit environment to the CMS
Command environment without saving the edited
file.

REPEAT

repeats the following BLANK or
the specified number of tiRes.

RETYPE

replaces the contents of the line at which thepointer is currently positioned with the line of
specified information.

SAVE

writes the edited file on the user·s permanentor temporary disk and returns to the Input
environment.

SERIALestablishes whether identification information
is to be placed in each line of the file and, if
so, specifies that identification information.

TABDEF

defines a character which is to 'be recognized as
the logical tab character in the Edit and Input
environments. The default character is #.

TAB SETestablishes the internal or logical tab settings
which are to be used in both the Edit and Input
environments.

TOP

positions the pointer to a null line which
precedes the first line of information at the
beginning of the file.

UP

repositions the pointer the specified number oflines above the current line.

VERIFYcauses the verify mode of the Edit environment
to be entered, in which the contents of lines
foundoraltered by
Edit
requests
areautomatically typed out.

ZONE

specifies theand CHANGE ..

560

columns to

APPENDIX DOVERLAY request

be scannedby LOCATE

APPENDIX E: SCRIPT CONTROL WORDS
Page Layout.BM nspecifies the number of lines to be allowed forthe bottom margin of each page (the default
value is' 3) ,.

.HM nspecifies the· numb~r of lines to be skipped
between the heading and the first line of text,
excluding the forced space (.TM),(the default
value is 1).

.PL n

specifies the number of lines to bepage, (the default value is 66).

.T~n

typed on a

specifies the number of lines, including theheader line to be allowed for the top margin ofeach page, (the default value is 5).
i,Page Control.CP ncauses a page eject to occur if less than thespecified number of lines remain on the current
page •• HE heading causes the next line to be used as a headerline, and to be typed at the top of eachsubsequent page.

.PA nstarts the next line on a new pagel, with n as
the page number. If n is omitted, sequential
numbering of pages is assumed.

.PN

controls
both external
and internal
numbering of the file being printed.

page

Spacing• DS

douhlespaces the infQrmation being typed out •.SP ninserts the specified number of carriage returns
before typing the next line~• S8

singlespaces the information being typed out •Paragraph Layout.IN nindents the leftof spaces.

side of the p'rintout.LL nspecifies the line length
default value is 60).

.OF nindents the following lines n spaces from theleft margin, except for the first line which
Appendix En numberin characters!.

(the

561

follows this command.
.TB

specifies the tab stops to be assumed for thefollowinglines
when convertingthe
TAB
character into the appropriate number of spaces.
(The default values are 5, 10, 15"
20, 25, 30.
35, 40, 45, 50, 55~ 60, 65, 70, 75.)

.UN n

forces the immediately following line to start n
spaces further left than the position currently
set by .IN.

Formatting Modes.BR

information
causesa break,meaning thatappearing before and after the .BR request is
typed on separate lines.

.CEcenters the next line between the left and rightmargins .•.cocancels a previous .NC. causing output lines tobe formed by concatenating input lines andtruncating at the nearest word to the specified
line length. It does this by shifting words ,toor from the next input line. The resulting line
is as close to ,.LL as possible without exceeding
it.

.FI

cancels a previous • NF (or • NC and/or '. NJ) ,causing concatenation and right justification of
output lines •• FOsame as .FI.JU

cancels a previous .NJ (or part of a
.NF)
causing right justification of output lines. It
does this by padding lines with extra blanks tohave an even right margin.

.NC

stops words
line,.

.NF

causes lines to be typed exactly as they appear
in the file. It is the same as issuing both .• NC
and .NJ.

.NJ

stops padding lines with blanks tojustification.

from shifting toor fromthe next

cause rightSpecial Features
.CM

562

causes the remainder of the line to be ignored,
allowing comments to be stored within the SCRIPT
file.

Appendix E

.RD nissues the specified number of reads to theterminal to allow user input to be inserted in
the printout.

Manuscript Layout.AP name

appends the contents of the specified
file to the file just printed.

.IM name

inserts the contents of the specified SCRIPT
file into the printout of another SCRIPT file,.

Appendik E

SCRIPT

563

APPENDIX F: CMS FUNCTIONS
ATTN

stacks a line into the input buffer.

CARDIO

reads or punches a card
specified 80-byte area.

from

the

CONWAITwaits for all stacked reads and writes
wfinish w from the console typewriter.

to

CPFUNCTN

transmits console functions to CP-67
leaving the virtual machine mode.

ERASE

erases the specified file(s) '.

FINIS

closes one or more specified files.

BNDINT

sets the CMS I/O interrupt handling routines totransfer control to a given location for an I/O
device other than those normally handled by CMS,
or clears such transfer requests.

HNDSVC

initializes
the SVC
interrupt handlertotransfer control to a given location for a
specific SVC number (other than X·CA' or 202),or clears such previous handling.

POINT

sets the read pointer and/or theat a specified item number.

PRINTR

outputs lines on a printer.

RDBUF

reads an item of information from a disk file

STATE

provides a copy of the FST (fileentry for the file specified.

TAPEIO

reads. writes. or moves magnetic tape.

TRAPsets a user's return for an external interrupt.
This return overrides the call to DEBUG on an
external interrupt.

TYPE

types anoutput message
Terminal blanks (if any) are
carriage return is added.

WAIT

wait state is entered to await an interrupt fromone of the devices specified.

WAITRD

reads an input message up to 130 bytes in length
into a given buffer from a console and waits forcompletion of the input message .•WRBUF

writes one item of information into the filespecified. If the file does not exist, a new

564

Appendix F

into

or

without

write pointerstatus table)on theconsole.
not deleted and nofile
is opened
andgiven thespecified
identifier. It automatically packs fixed-length
items into an 800-byte buffer and writes this800-byte block onto the disk.

Appendix F

565

APPENDIX Ql
FUNCTIONSFORMAT

OF

COMMANDS"REQUESTS.

Below is a key to the symbols used
formats in this appendix:

AND

CONSOLE

to represent

command

UPPERCASE

information given in capitals must be
typed exactly as shown"
although it may
be enteredin eitheruppercase or
lowercase.

lowercaselowercase information designates thecontents of a field" and does not in
itself constitute meaningful input.

( )parentheses must be typed as shown when
any of the information appearing withinthem is specified
a period designates the beginning of a
Script Print control word" and must be
typed as showna hyphen must be typed where shown,,, andmust not be offset by blanks/a slash denotes any string delimiter"
which does not appear in the string"other than blank.

*

an asterisk. specified where shown"indicates the universality of an item or
items

The following
typed:

are l09ical symbols

only, and should

not be< >brackets indicate
be omitted< >< >

successive brackets enclose items which"if specified, may appear in any order«nested brackets indicate items which. if
specified" must appear in the order
shown

»

information which may

an ellipsis indicates that t.he preceding
item(s) may be repeated more than oncein succession
1
2
3
N

566

these suffixes indicate first" second"
third" and Nth items respectively
Appendix Gunderlining indicates the value which isassumed if none is specified.
When nounderlined item appears in bracketed < >information. ·the default value is ~.
stacked items!. not enclosed in anything,indicate that only one item may be
specified.
All lowercase symbcls used in this appendix are described inalphabetical order below.
anycomarg
cceu
defentdefseteditfn
entry
eof
first
fm
fn
ft
hex info
hexlocid
intloelastsetlengthlibname
line
n

name
nolineno
norec
newfm
newfn
newft
nextloc
oldfm
oldfn
oldft.
optionreg
seqsetmarstringsymbolsyslibany eMS command
any user argument to be passed to a program
any text character appearing on the 2741
keyboard
device addressdefault entry point
default option settings
filename specified in EDIT commandan entry point or control section nameend of file
first occurrence of the specified item foundfilemodet"ilenaroe
filetypea fullword or less of hexadecimal information
hexadecimal core location
an aiphameric identifier
core
location at which
processing wasinterrupted
core location specified in last DUMP request
in the Debug environment
inherent length attributethe filename of a librarya group of position-dependent 2741 charactersa decimal number
saved system nameline number not typed
no formatting of first three disk records
new filemodenew filename
new filetypenext available load location
old fileroodeold filename
old filetype
an option of· the indicated command
the number of a register (in decimal)
sequential page numbering
original margin or tab settings
any group of 2741 charactersa name for which a DEF request has been
issued in the Debug environment
system text
library, unlessotherwise
Appendix G

567

typeout
useridspecified by an option or previous command
type out informatdon at the terminal
identifier-'by which; user logs in to CP

Note. For abbreviations /• see -CMS Commands· ..

** BRUIN and SNOBOL are available as Type III programs.

568

Appendix G

CMS COMMANDS
ALTER

oldfn

oldft

•

•

ASSEMBLE

fnt ••• fnN

BLIP<char> <n>
1

oldfm

newfn

newft

newfm

*

*

*

*

«option1 ••• optionNl>

«OFF»
BRUIN

**
CEDIT

<fn>

CHARDEF

C

ft

E<Char>LT

CLOSIOREADER
RDR
PRINTER< OFF >
ON

PR'l'
PUNCH
PU

CLROVERCNVT26fn

ft

COMBINE

newfn

newft newfm oldfn1 oldftl
oldfnN oldftN oldfmN

COMPARE

fn1

CPFUNCTN<NOMSG>

cpcommand

CVTFV

fn

«T»

ftl

ft

fn2

oldfmlft2

Appendix G

569

DEBUGDISKDUMP fn ft fro
LOAD

DUMPD

ccu

cc

DUMPF

fn

ft

<hh

<rr»

nl

n2

« *

*
end

beg

n3
80

»

DUMPREST

ECHO

<

S
X

< nn >

>

1

U

EDIT

<fn>

ERASE

fn

ft

ft

*

•

< fm >

EXEC

fn

<argl

... argN>

FILEDEFddname< dsrn-•device
CLEAR
DUMMY

*
FINIS

fn

•

ft

•

P

fro
<

>

< (NOTYPE) >
ALL
C
>
L
nn
R <SYS>T

FORTRANfnl ••• fnN

510

*

first

FORMAT<<def1 ••• defN»< (option1

Appendix G... optionN) >GENMOD

entry 1 «entry2 > <NOMAP»>. nextloc
1m!

GLOBALASSEMBLER MACLIB(m)<libnamel ••• libnameN>
LOADER'TXTLIBSYSLIB
(T)

PRINT

IPL
KO
KT
KX
«fn

ft

*

*

LISTF

LOAD

< fm »>*«optioni ••• optionN) >pT

fni ••• fnN< (option1<libname1

LOADMOD
LOGIN

optionN)libnameN»
syslib<fro>

fn

NOPROF< .!!E!! >OFO
NO-OFD

NO

ccu

>

< UFD
NO OFDZp

LOGOUT<,Y <fn <ft <fm »><any com>

Appendix G

571

MACLIBGEN

libname fn1
fnN
libname fn1
fnN
LIST libname
REP libname fn1
fnN
DEL
libname macroname1
COMPACT libname
PRINT libname
ADD

A

MAPPRT

ON

< N

<OFF

C

.. " macronameN»NO

MODMAP

fn

OFFLINE

PUNCH
PUNCHCCPUNCHDT

PRINT
PRINTCC

fn

ft

<fro>
first

fn

ft

< fm >*Pi

PRINTUPCPRINTVLRPRINTPLIREADOSTAPE< filetype
SYSIN

PRINTFfn

ft<filename»OS'l'APE

< n1

-*

n2

>

-*

RELEASE

ccu fmode < (DETACH) >REUSE

fn1 ••• fnN(option1< n3... optionN)>length«option1

optionN)<libname1 ••• libnameN»
RT

SCRIPTfn«option1 ••• optionN»

SETERR

572

Appendix G

SETOVER<SAMELAS-r<option1 ••• optionN»

defsetSNOBOL

fn«option1

SORT

fn1

ftl

SPLIT

fn1

ftl

START

<entryoptionN)>

ft2

fn2
fn2

ft2

id1
n1

<id2 >n2
eof<arg1 ••• argN»*
defent
P

STAT

<

T

>

C

P and TSTATE

fn

< fro >

ft

P

fro >

< (option1 ••• optionN) >

SYN

< fn

TAPE

DUMP

fn

ft

<fm>

* -*
-<n>

P1

LOAD

•

ft

1

REWIND
SCAN
<n>
SRIP
<n>
SWAD
fn ft
WRITEOF <n>
TAPEIO

BSF
BSR
ERG
FSF
FSR
REWINDRUN
WRITEOF
WTM

<

TAPn
TAP 2

>

<n>

< TAPl >TAP2Appendix G

573

TAPRINT<TAPl >TAP 2

TPCOPY< TAPiTAPl> <-r'APo >TAP 2*
TXTLIB*

GENERATE>< n
1< YES >

NO*
libname fn1

fnN

libname fn1

fnN

G

ADD
A

PRINT

libnameplibnameLIST
L

DELETE

libname

CSect 1<<... CSectND

UPDATE

USE

fn1

fn1

«

ftl
SYSIN

fn2
fn1

~RTAPE

fn

ft

$

fn

<argl

.... argN>

Appendix G»>

UPDATE... fnN < (option1<libnartle1

574

ft2

(P)

.fn1

optionN).. e·-

libnameN»>DEBUG REQUESTS

BREAK

symbolhexloc

n

CAW
CSW
DEF

symbolhexlocid< hexloc1.

symbol1

DUMP

0

< n >
4
symbol 2
hexloc2 >

*

3

GO

symbol< hexloc >intlocGPRregl<reg N>IPL
KX.oRIGINsymbolhexlocPSWRESTART
RETURN
SET

CliW
CSW

PSW
GPR

hexinfohexinfohexinforeg<hexinfo><hexinfo>
hexinfo <hexinfo>

Appendix G575

5"l'ORE

symbolhexinfo<hexinfo <hexinfo»

hexlocTIN< CMS >
DEBx

symbolhexloc

576

<

<

n
length.

nAppendix G>>

EDIT REQUESTS

BACR

< c >
~

BACKUP
UP

<N>
1

U

BLANK

1ine

B

BOTTOM
BO
BRIEF
BR
CHANGE/stringl/string2/

C

< n*
1

DELETE
D

*

G
»
first

n

< /string/ >
1

FILE

<

fn.

>

editfn
FIND

line

F

INPUT
I

INSERT

line

I

LOCATEL/string/

NEXT

< n >

N

!
Appendix G

577

line

OVERLAY0

PRINT
P

LlNENO

n

< 1

<

L

»

nolineJlo

QUIT
Q

REPEAT

< N >

!
line

RETYPE
R

SAVE

< fn

editfn>SERIAL
SER

id
< n
(NO)
10

TABDEF
TABD

<

TABS~

< nl

TABS

c

>

>

#

... nN >setmar

TOP
T

UP
U

BACKUP
VERIFY
VER
ZONE
Z

578

< n >

!
< n >
12

nl
1

n2
truncalAppendix G

CONTROL PROGRAM CONSOLE FUNCTIONS

BEGIN
B

<hexloc>
intloc

CLOSE

ccu

C

DETACH
DE

ccu

DIAL

SystemD

DISCONN<anychar>DISPLAY<hexloc><hexlocl-hexloc2><Lhexloc>

D<Lhexlocl-hexloc2><Greg><Gregl-reg2><Xreg><Xregl-reg2><Yreg><Yreql-reg2><PSW>

DUMP
DU

<hexloc><hexlocl-hexloc2><Lhexloc><Lhexlocl-hexloc2><Greg><Gregl-reg2><Xreg><Xregl-reg2><Yreg><Yregl-reg2><PSW>

EXTERNAL
E

IPL
I

IPLSAVE

name
ccu
name
ccu

Appendix G

579

LIN}{
LI

userid•xxx

LOGOUT
LOG<anyehar>

MSG
M

useridCP

PURGE

READER
R
PRINTER

P

yyy

W
R

line

P

PUNCH
PU

QUERY
Q

FILES
F
LOGMSG
L

NAMES
N

TIME
T
USERS

<userid>U

userid
READY

ceu

R
RESET
RE
SET

CARDSAVE<ON>OFF

MSG OFFMSG ONRUN ONRON OFF
SLEEP

580

Appendix"G< (NOPASS) >SPOOL

xxx

<ON

yyy>

OFF
SP

ccc

<CONT>
OFF

STORE
ST

<Lhexloc hexinfo1 ••• hexinfoN><Greg hexinfo1

hexinfoN><Xreg hexinfo1

hexinfoN><Yreg hexinfol

hexinfoN>

<PS~

XFER

hexinfo1

hexinfo2>

ccu TO useridX

ccu OFF*

Appendix G

581

SCRIPT CONTROL WORDS

.AP

fn

appends file

.BM

<n>
1

bottom margin set to n

fn

.BR

causes a break.CEcenters following line

.CM

line

.co
.cp

-line- is a comment
concatenates linesnnew page if n lines are not left
on current page.DS

doublespacing.FI

concatenates and right-justifies<each line.FOsame as

~FI

.HE

line

-line- becomes the heading on
subsequent pages.8Mnheading margin set to n

.IM

fn

imbeds file fn in the file at point
specified

.IN

<n
>
setmarindents lines n spaces starting in
the following line

.JU
.LL

582

causes right justification of lines<n >60

line length set to n

Appendix G

.NCturns off concatenation.NF

turns off concatenation and rightjustification.NJ

turns off right justification

.OF

<n
>
setmaroffsets lines n spaces. to the rightstarting with second line following

.PA

<n
>
seq

page eject with n as next page number

.PL

<n>

sets length of output pages to n

66

.PN

ON
OFF
OFFNO

determines if external and/or interna1
page numbering is to occur

.RD

<n>
1

allows n lines to be input fromthe terminal during output<n>causes n carriage returns

.sp

!
.S5
.TB

singlespacing<n, ••• nN
5, 10, 15

.TM

<n>

75

>

sets physical tabs that
correspond to logical tabs

top marqin set to n

5

.UN

n

starts fol1owing line n spaces to theleft of current margin

Appendix G

583

APPENDIX H: CP-61 MACHINE CONFIGURATION

CP-67 is structured to run on an IBM System/360 Model 67.

CP-67 MINIMUM CONFIGURATION

2067-1 or 2067-2 Processing Unit
Recommended feature:#4434 Floating Storage Addressing (Model 1 only>

2365

Processor storage

2860

Selector Channel

2810

Multiplexer Channel

1052

Printer-Reyboard

1403

Printer

2540

Card Read Punch

Three 2311 Disk Storage Drives or 2314 Direct Access Storage Facility(2 Disk Storage Modules minimum)
2400

Nine-Track Magnetic Tape Unit, 800 or 1600 bpi

2702 or 2703 Transmission Control or
2101 Data Adapter Unit

584

Appendix H

TERMINALS SUPPORTED BY CP-67 AS OPERATOR·s CONSOLE

1051/1052 Model 2 Data Communication System
Features and Specifications:
Data Set Attachment (#9114)
IBM Line Adapter (#11-647)
Receive Interrupt (#6100 or RPQ E27428) required
Transmit Interrupt (17900 or RPQ E26903) required
Text Time-out suppression ('9698) required
1056

Card Reader

2741(-1.-2) communication Terminals
Features and Specifications:
Data Set Attachment (#9114)
Data Set -Attachment (#9115)
IBM Line Adapter (#4635. '4647)
Dial-Up (13255)
Receive Interrupt (#4708) required
Transmit Interrupt (17900) or Transmit
Interrupt Control (RPQ E40681) required
Print Inhibit (#5501) desirable

Line control for teletypewriter terminals. compatible with
the IBM Telegraph Terminal Control Type II Adapter (8~level
ASCII code at 110 bps).

• The customer is responsible for terminal compatibility
with this program. IBM assumes no responsibility for the
impact that any changes to the IBM supplied products orprograms may have on terminals provided by others.

Appendix B·

585

TRANSMISSION CONTROL UNITS SUPPORTED BY CP~61
2101

Data Adapter Unit

Terminals

2101 Adapter

8-level ASCII r•
110 bps •7885• The customer is responsible for terminal compatibility with this program .•IBM assumes no responsibility for the impact that any changes to the IBM
supplied products or programs may have on termdnals provided by others.
2102

Tr~nsmission

Terminals

8-level ASCII
110 bps.

ControlTerminal
Control Base

Terminal
ControlLine
Adapter

9696 or 7935

4615, 9684, 8200**

3233

9691 or 7935

1912

3233

** Feature 8200 on the 2102 is equivalent to the 2141 Break feature#8055 and the Type 1 Break RPQ E46765 on the 2102.
2103

Transmission Control

Terminals

Line Speed
OptionLine
Set

Terminal
Control

2141s,. 1050

4818

3205/64619, '4696, 8200***1505

8-level ASCII,
110 bps.

4811

3205/6

1905, 1912

1505

Line
Bases

*** Feature 8200 on the 2703 is equivalent to the 2141 Break feature#8055 and the Type I Break RPQ E53115 on the 2703.

586

Appendix H

OTHER DEVICES SUPPORTED BY CP-67
Additional Devices Utilized by CP-67
2301
2303

Drum Storage
Drum Storage

2870 Multiplexer Channel with 16990, .6991, #6992.1(, 2. 3 Selector Subchannels

DEVICES USED ONLY BY AN
MACHINE AND NOT. BY CP-67

OPERATINGSYSTEM IN

2321

Data Cell Drive

2400

Magnetic Tape Units

2250
2260

Display Unit
Display StationA

VIRTUAL

2860 Selector Channel with
.1850 Channe1-to-Channel Adapter
2780
1130

Data Transmission Terminal
Computing System

Appendix H

587

APPENDIX I: DEVICES SUPPORTED BY eMS

Core size:

Minimum 256K or up in multiples ofax (up to 16M virtual)1052 Printer-KeybOard
Six

2311 Disk Storage Drives or2314 Direct Access Storage Facility(2 disk storage modules minimum)

2540 Card Reader/Punch
1403 PrinterTwo

2QOO series tape drives. nine or seven track
200~

556, 800 or 1600 bpi(one nine track"588

80.0 ·or 1600 bpi required for installation)

Appendix I

INDEX$ •••• '••• 210
Abbrevi·ations ••••••• 46.47;.426,427,428
Abend ••• _ ••• 294.384,457
Active 'disk table •••••.•• 423
Administrator ••••••• 37
ALTER ••••••• 6,1.2,46/,50 1.52.53.67,110,1.72
269~297,337.372.384~398.438

Ampersand ......... 7,175,179.i80,443
ApI ........ 27 f, 32. 491
Asp360 ........ ,•• 63 64,67 .1.03 430.431., 432
433,, 43q
Assemble,......... 46,1.74,,192, 193,194,,197
268~269, 270.271, 272.401, 404,431
462 f, 463,513
Assembler •••••••• 5.173.174, 192,.193 f,194
211,222, 267.268, 269.270, 211,212
273~274, 275,276, 277,309, 321,324
j,f•404~431~432,436~513

Assembler conventions .......... 273-275
Attaching devices ........ 470,484.508
Attn ......... 4.6~7,11.12~15, 17~28~30~36
44~45~213,270,298~ 299.412.414,Q15
421~425, 463.467, 495.496. 497,Q98
500.,508
BACKSPACE .......... 69
Batch ••••• _.2,5.6.384
Batch control cards .......... 528
Batch operation ••••• '•• 5q.3
Batch setup •••••••·543
BEGIN ..........467
Begstack ••••••• 186
BLANK ••
71.
Blip~ ....... 18S.297,406#407~441.4q.2
Blocksize ••••••• 108,337~454~q.56
BOTTOM ••••••• 72
BREAK ••••••• 221
Breakpoint ••.•••.••• 186, 218,219. 221.222
I. . . . . .

213~224,226~235~236~247,254

BRIEF ••• ,•••• 73
Bruin ........ 40.267,363
Carriage control ........ 120
CAW ......... 227
csw ••• '..... 228
C Disk ........ 37.42
Cedit ••••• ~.40.54,60~408.516
CHANGE ........ 74
Changing object programs,........ 519
Channel programs ••••••• 1.
Character delete •••• '•••• 28 f• 32,34.,63, 219
408~412~414.415~Q25~Q64

Chardef ... ~ •••• ~34,6S~ 66#69#96~ 406,408
409
CLOCK routine ••••••• 3S1
INDEX

589

CLOSE ••••••• 468
Closio ••••••• 46,50,55.56~297
CLROVER,••• '••••• 213,214 .215. 216,217, 258
1

261~262,263,264,412

CMS Bate:l Moni tor •••••• '. 526
CMS Commands ••••••• 552
CMS Functions ••••••• 297-298,564
CMS Login~ •••••• 30-31
CMS Login errors •••••• ,.516
CMS Macros ••••••• 216~271
CMS Routines ••••••• 297-298
Cmslib ........ 193,337.429,.440,459,514
CMSLIB TXTLIB ••••• ,•• 459
Cmsnuc ••••••• 383,384,385
Cmsysref.~~._ •• 215,280
Cnvt26 ......... 40~364.365
Cobol ••••••• 63,64.65
Column dependent •••• '••• 19,84
COMBINE ••• ~ ••• 57
Comma •• '•••.•• 325,,443
Command abbreviations •••• ,••• 46
Command conventions ••• ,•••• 48,49,62.566
COMPARE ••• '.
366
Compilers ••••••• 5.173,267
Configuration ••••••• 1.2, 4.5,17,328,393
423.465,470,471.482,493,508,509
Console functions ••••••• 461-507,550
Console fUnction applications ••••.••• 508
Console functions descriptions ••••••••
462
context editor ••••••• 60-66
Control commands. '" •••• '. 406
Conventions ••••••• 27~34, 35~37,38~39,40
41 , 42" 4 3 , 4 4 • 4 5 , 6 2 , 6 8 " 82 • 318
Conversational ......... 1~2.4,5.16
Core image ........ 47 48,173,,189,190,191
202
CP Login ........ 27-30
CP Messages ••••••• 510
CP-61 Configuration ••••••• 584
Cpfunctn ••••••• 43.45.46.298,302.406.410
Cpnmon7cpnmof •••,...... 441,443
Cp67userid ••••••• 119.120.371.468,511
Cvtfv ••••••• 364.368
Cvtutl ••••••• 368
Dataphone. '•••••• 16,17,24:.26,,27
Dataset ........ 446
Ddname ••••••• l07.108,109.110.111
DEBUG ••••• '•• 218
Debug requests ••••••• 557
Debugging facilities ••••••• 213
DEF ••••••• 229
DELETE ••••.••• 76
Delimiter ••••••• 48,62,273.416,417
Density ........ J12,313,396.399
Desk calculator ........ 363
I• • •

t,

590

INDEX

Detach ••••• _ •• 4~33,294.296. 410.423,465
470~471.508~509~510.512

Devices supported by CMS ••••••• 588
Diagnostic ••••••• 268 i• 322i, 323. 339.357
bial •••••••• 1.4.16,25.27~32~ 33.472.487
490
Dialing ••••••• 25,27,32~33.36.490
Dictionary •••••••• 338. 339~430. 431,434
436~437.438.513.514

Direct access 1/0 ••••••• 333
Disconn __ ••••• 465.472
Disconnect ••••••• 24.421
Disconnecting ••••••• 33.472
DISK,••• '. '.... 370
Disk area,full ••••••• 517
Disk modes ••••••• 37
DISPLAY •• '••••• 473
Dsdset •••••.•• 335,441.448,,449
Dsname ••••••• l08.109~111
DUMP ........ 232.478
Dump/restore ........ 375,.376
Dumpd ......... 364,,373
Dumpf. ,... ,..... 364,374
Dumprest ••••••• 8~11~12~375.376
Echo ........ 43.44.45.364~377.318
EDIT •••• '.... 59
Edit requests •••• ~ •• 559
Editor ... _ •••• 54~60~63~408
Environments ........ 17!.19, 43,. 44" 45
Environment conventions. '••• ,••• 113-45.61
Erase •••••••• 6.11~45~50.67. 105,106~170
179
Error overrides ••••••• 214.215.216.263
EXEC ....... ,.175
EXEC control w~rds ... _ •••• 181-187
EXEC features ••••••• 179-181.188
Extended error message subroutines(FORTRAN) ••••••• 4111
EXTERNAL,•• '••••• 480
FILE ••••••• 11
File access routine.,••• ,••• 352
File conventions ••••••• 37-42
File creation ••••••• 50
File identifiers ••••••• 38 i• 39.40
File 1/0 ••••••• 345
File maintenance ••••••• 50
File manipulation ...... '•• 50,51
File modes ••••••• 40
File sizes ........ 41
Filedef ......... 101.108 .109,,110.111
FIND .......... 79
FINIS. '....... 112
1

FORMAT. '....... 319

FORTRAN .... ,•••• 321
Fortran conventions •••• '...... 328-337;,441
459
INDEX

591

Fortran files ••••••• 335
Fortran Scientific Subroutine Library ••••Ie • • '••461

Genmod ••••••• 46,173.189.190.191.202.203
297,343. 3Q..1,. 386
Get/put ••••••• 345,347~348
Getbuf ....
295
Getmain.~ ••• 4.295
Getpar ••••• ~.441,451
Getpool ••••••• 295
Global •• ~ •••• 14~91, 174,181.181,188,192
193,194" 195,.198, 200.210, 297,337
I• • • •342,429,436,459.460~462.513.514

GO. '••••• ,. 235
GPR ...... ,•• 238
Hndirtt .......... 298,305.306
Hndsvc ......... 298,301
Initialization routine,••.• '•••• 350
INPUT ••• '•• ,•• 81
INSERT,••,.82
Interpreter ••••• ~.267~363
I pI,. ,....... 4, 8 , 30 , 45. 21 a!. 220 , 229 , 236, 240
246~241~ 291.380, 385,406. 411,463
465,,481,.482,483,.494,,508
Ip~disk ........ 319,380
Iplsave ........ 483
Isam .• '•• I. Ie • • 1
Keyword •.• '...... 180,181,181
Ko ......... 44~213.214,218,258,263.406,412
413
Kt •••• ,••• 6~12,44,124.218,406.414,425
K~ ......... 6~12, 44,218~220,236, 241,271
406,415
Language processors ••••••• 267
Libraries~~ ••••• 173,114.1B8.192,193.194
195~196~ 198.199~ 200,201~ 210,276I• • • •294;429,436.440,462~513,514

Libraries. macro ••••••• 429.513
Library usage •• I." ••• 192-194,196-199,429
513
Line delete.,••••••• 2B.32;,34. 63.219,408
409,412,414,415.425~464

Line end ••••••• 6,34,35y41.66,96~406,416
417 1,464
Linend •••• ~.4.6,8~35.47,96~ 188,291,317
406,,416,417.464
Line pointer '•• __ •••• 60
LINK .... ,e '• • 484
Listf •••••••• 6.8.11" 12~14.40,45~ 46~50
114,,115, 116"117,, 115:.116, 117,178
275,396,421,422.516'LOAD ••• '. ,. '•• 196
Loader ....... ~ •• 192, 193.194,195. 198,199I.

200~205,342~385.3861514

Loadmod ••• ~ ••• ~41, 113.114,189, 190,202
203.201,210,211,212,297
592

INDEX

LOCATE.; ••• ,••• 84
Login ••••••• 5,8116.21.21.28~29.32.36.41
45,117.188.214,342.380~393,406,418
419~420, 423~463. 466~472, 481~484

485 .. 487,,490,516
Logging procedures '•• ,••••• 27- 31
Logical backspace •••••• \. 66
Logical linend ••••• ~.41fi
Logical tab ••••••• 65
LOGIN ••••••• 418
Logrosg. '.... '••• 15,490,491
Logout. '•• \•••• 15',.27 , 30,33,,45,,297.406,421
422,465,487
Machine configuration ••••••• 5
Maclib •••••••• 125, 192~193,194, 195.210
276.288. 294,396, 397,429, 430.431
432.433,434,462,513
Macro 1.l1:>raries ••••••• 430.462,513
Map •••••••• 8~12,40,115.126, 189.190,196
191.198. 199,200. 202,204. 205.208
209~222, 224.321, 323.324. 325,364
383,384,386,430.432.435,436.438
Ma pprt •••• '•• e 383 • 384 , 385
Memo,•••••••• 51,63. 64.65,75,95. 101.103
120,.124,368,390
Messages: Machine malfunction oroperator intervention. ,e • • • • • 510
Mini disks ••••••• 37
Modeset ••••••• 312.399.455~456~457
Modmap ••••
364,386
Module •••••• ~47,48, 105,115.113.114,189
190,202~ 210,211, 212.215. 280,326
347,364.386
Msg ••••••• 4,45,289,316.465,488,495,496
Multiaccess •••••••• l,4,27.32, 33~36,412
496
Multiaccess systems ••••••• 32.33
Nlston/nlstof ••••••• 331,443,444
Normaloverride ••••••• 215
Nucleus •••••••• 2,6,30,37~47. 48,176,193
194,246. 213,274, 215,280, 291,341
379,380, 383,384, 385,399, 411,428
481,513,514
Nucon ••••••• 207,384
OFFLINE ••••••• 118
Offline procedures •• ~ •••• 511
Operand substitution ••••••• 210
ORIGIN ••••••• 242
OS Macros ••••••• 294-296
OSMACRO MACLIB ••••••• 462
Osmacro •••••••• 192,193.194, 270,276.294
429,462,513
Ostape ••••••• 364,387,388
OVERLAY ••••••• 87
Overrides ••••••• 97, 124,133,152,151,194
213,214, 216,258, 262,263, 264,284
I• • •

INDEX

593

315,406.412,458
PL/I ••••••• 188.261. 338.340.342.343.344
345,346. 341.348. 349,350, 351.352
353,354.437.440.460.514
Pli •••••••• 63.64. 65.67.91.103,191,338
339.340,341,342.354,436
PL/I conventions ••••••• 342-354.460

Plilib ••••••• 188~342.429.440.460.514
PLILIB TXTLIB •• ~ •••• 460
Plist ••••••• 213,214.297.298.299.300.301
302.303,304-319.316 i 317.318,319
Pqmsk ••••••• 319.380
PRINT· ••••••• 89
Printcc •••••••• 50, 118.119,120. 122,123
128,324,334,335
Printf •••••••• 6,11,13.45.46, 50.116,124
125,126; 128.177. 178.119. 197.225
324,354,384,433.444,463
Priority ••••••• 116,472
Privilege class ••••••• 2
PROFILE EXEC •••.•••• 188,342.418.419,420
Program execution ••••••• 173-114
Pseudo chronolog device ••••••• 351
PSW" •••••• 244
Purge ••••••• 463,465,489.509
Query ••••••• 4,1,15,465.490.491~492.500
QUIT ••••••• 90
Q2 ••••••• 412
Rax ••••••• 1.27,32
Rdbuf ••••• _.119.181,274,216.211.278.282
284,285,298.310.352.353,354.428
Read/only ••••• .;.37
Read only,disks ••••••• 41
Read/write ••••••• 37,345
READY ••••••• 493
Reconnect ••••••• 412
Recordformats ••••••• 63.64
Recovery procedures ••••••• 516
Reinitializing.Cl-1S ••••••• 511RELEASE ••••••• 423
Relocatable •••••••• 173.192,196. 197.199
201.204.208.268~436,514

REPEAT ••••••• 91

Reps ••••••• 64~65.67,103
RESTART ••••••• 246
RETURN ••••••• 241
RETYPE ••••••• 92
RESET ••••••• 494
Restrictions ••••••• 40.261
Reuse.~ ••••• 40.173. 174.189,192,193.194
195.191, 204,205. 206,208. 209,291
429,440.514,515
RT ••••••• 425
SAVE ••••••• 93
Savesys ••••••• 481
Script ••••••• 8,12,45. 46,48.51.54.59,60
594

INDEX

63.65.66.67.75. 95.101.103,120.124
121.128. 129.130. 131.132. 133,134
135.136. 131,138. 139,140, 141.142
143.144. 145.146. 147.148, 149.150
151,152. 153,154. 155,156. 157.158
159,160. 161.162. 163,366, 368.500
501
Script control words ••••••• 131-159.561
Search for commands ••••••• 47,37
Sequential 1/0 ••••••• 328
SERIAL ••••••• 94
SET ••••••• 248,495
SETERR ••••••• 258
Setover •••••••• 213,214.215, 216,258,261
262,263.264,265,266,412
Sleep ••• ~ ••• 466,498.510
Snobol •••••••• 40,64,65,103, 267,355,356
351.358.359,360,361,362
SNOBOL conventions ••••••• 359-362
Sort ••••••• 114.361,364.385,389.390.391
Spl/l ••••••• 355,356,357.358.361
Split ••••••• 50,60.~64,165.166,326
Spl1 ••••••• 40.65.67,355,356,357.358,360
361
Spool ••••••• 466,411,499,SOO,501,509
Spooling areas ••••••• 509,468,490.499
SSPLIB TXTLIB ••••••• 461
START ••••••• 206
Stat ••••••• 46,392.393,421
STATE ........ 206
Statistics ••••••• 392,393
STORE ••••••• 251,502
stow ••••••• 295
String processing ••••••• 356
Subscript ••••••• 346
SVC ••••••• 5,201,213,215.216,258.261,262
274.275, 276.284, 296.297. 298,307
433
SVC override.tracing ••••••• 258,261.214
Svcfree ••••••• l10
Svcfret ••••••• 110
SVC handling ••••••• 214.307
SYN ••••••• 426
Synonyms ••••••• 46.47.406,426,421.428
Sysin •••••••• 5.8.12, 52.63,64,65, 67,97
103,121, 166,168, 169,110, 111,268
269,270, 211,212, 335,344, 345,346
347.348,387.449
Syslib •••••••• 125, 192.193,194. 195.198
199,200, 210.276, 288,329, 333,335
337,342, 396.391. 429,431. 432.433
440,441,459.462.513.514,515
SYSLIB MACL1B ........ 462
SYSL1B TXTLIB ••••••• 441
Sysout ••••••• 335.432.449,456
Sysprint ••••••• 344,345.346,347.348
INDEX

595

Sysref ••••••• 275,280
System failure ••••••• 516
Tabbing ••••••• 18,21,97
Tabdef ••••••• 65,68,96
Tabs ••••••• 18,21,67,79,82,92,97,98
TABSET ••••••• 97
TAPE ••••••• 394
Tape procedures ••••••• 512
Tapeio •••••••• 297, 298,312,313, 314,384
399.400.512
TAPRINT ••••••• QOl
Tapset ••••••• 336,441,448,455,456,451
Tdisk ••••••• 37,41,42,58,380,381,393,423
510
Teletype usage ••••••• 24-26,35
Terminal I/O ••••••• 343
Terminal session ••••••• 6,7,15
Terminal usage ••••••• 16
Teminals supported as consoles ••••••••S8S
Text libraries ••••••• 440,514
Timesharing ••••••• 1,2,61,333
Tin ••••••• 220,254
TOP ••••••• 99
Totcpu ••••••• 15,30,490,510
Tpcopy ••••••• 364,402,403,512
Transferring files."•••••••• 509, 506,310
118
Txtlib ••••••• 40,115.192,193,194,195,196
191,198, 199,200, 201,204, 208,329
333,335, 331,342, 311,429, 435,436
431,438, 439,440, 441,459, 460,514
515
Typing conventions ••••••• 34,35,65
UP ••••••• 100
UPDATE ••••••• 168
Updating,files ••••••• 168-112
Updlog ••••••• l10,172
USE ••••••• 208
Userid ••••••• 2,3,4, 27,28,29,32,119,121
122,371, 412,484, 485,486, 488,490
491,506,501,511
User synonym ••••••• 421
VERIFY ••••••• l0l
Virtual core ••••••• 3.
Virtual machines ••••••• l,2,3,410
Virtcpu ••••••• 15,30,490,510
Wng ••••••• 495,496
Wrtape ••••••• 401,404,405
X ••••••• 255
X and Y•••••••• I02
Xfer ••••••• 3,4, 119,410,466,496,506,501
509
ZONE ••••••• I03
1052 usage ••••••• 18,19,20,21,35
2141 usage ••••••• 11,18,35
596

INDEX

GH20-0859-0

s:o
:::l

;::to

Q

en

-<

it
3

c

C>

International Business Machines Corporation
Data Processing Division
1133 Westchester Avenue, White Plains, New York 10604(U.S.A. only]
IBM World Trade Corporation
821 United Nations Plaza, New York, Naw York 10017(International]

READER'S COMMENT FORM
Control Program-67/Camhridge Monitor System
User's Guide

GH20-0859-0

Please comment on the usefulness and readability of this publication, suggest additions anddeletions, and list specific errors and omissions (give page numbers). All comments and suggestions become the property of IBM. If you wish a reply, be sure to include your name and address.

COMMENTS

fold

fold

fold

fold

• Thank you for your cooperation ;\;0 J)(l~tage necessary jf mailed in the U.S.A.
FOLD ON TWO LINES, STAPLE AND !\1AIL.

GH20-0859-0

YOUR COMMENTS PLEASE .••Your comments on the other side of this form will help us improve future editions of this publication. Each reply will be carefully reviewed by the persons responsible for writing and publishing this material.
Please note that requests for copies of publications and for assistance in utilizing your IBM
system should be directed to your IBM representative or the IBM branch office serving yourlocality.

fold

fold

........................................................................................................................
FIRST CLASSPERMIT NO. 1359
WHITE PLAINS, N. Y.

BUSINESS

REPLY

MAil

NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATESPOSTAGE WILL BE PAID BY •.•IBM Corporation
1133 Westchester Avenue
White Plains, N.Y. 10604
Attention: Technical Publications...................................................................................................................... :
fold

fold

llIIDOO®

International Business Machines Corporation
Data Processing Division
1133 Westchester Avenue, White Plains, New York 10604[U.S.A. only]
IBM World Trade Corporation
821 United Nations Plaza, New York, New York 10017[International]