SC24 5286 0_VM_SP_CMS_for_System_Programming_Release_5_Dec86 0 VM SP CMS For System Programming Release 5 Dec86

User Manual: SC24-5286-0_VM_SP_CMS_for_System_Programming_Release_5_Dec86

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

DownloadSC24-5286-0_VM_SP_CMS_for_System_Programming_Release_5_Dec86 SC24-5286-0 VM SP CMS For System Programming Release 5 Dec86
Open PDF In BrowserView PDF
--

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

Virtual Machine/
System Product

eMS forr

Slfs~em

rP>rrog]rrammoD1lg

Release 5
SC24-5286-0

I",

,,'

,"

.,'I!

I",i,,:.l

r,'

"

I

1 , 1 ••

,1',(',.

First Edition (December 1986)
This edition, SC24-5286-0, applies to Release 5 of IBM Virtual Machine/System
Product (VM/SP) (program number 5664-167) unless otherwise indicated in new
editions or Technical Newsletters. It contains material formerly found in the
VM/SP System Programmers Guide, SC19-6203 and the VM/SP eMS User's Guide,
SC19-6210. Changes are made periodically to the information herein; before using
this publication in connection with the operation of IBM systems, consult the
latest IBM System/370, 30xx, and 4300 Processors Bibliography, GC20-0001, for the
editions that are applicable and current.
Summary of Changes
For a detailed list of changes, see page "Summary of Changes" on page 379.
Changes or additions to the text and illustrations are indicated by a vertical line
to the left of the change.

References in this publication to IBM products, programs, or
services do not imply that IBM intends to make these available in
all countries in which IBM operates. Any reference to an IBM
licensed program in this publication is not intended to state or
imply that only IBM's licensed program may be used. Any
functionally equivalent program may be used instead.
Ordering Publications
Requests for copies of IBM publications should be made to your IBM
representative or to the IBM branch office serving your locality. Publications are
not stocked at the address given below.
A form for readers' comments is provided at the back of this publication. If the
form has been removed, comments may be addressed to IBM Corporation,
Information Development, Dept. G60, P.O. Box 6, Endicott, New York, U.S.A.
13760. IBM may use or distribute whatever information you supply in any way it
believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 1986

- ,. ':'-")
l')r '-"'l',""'1 (!";"--.J
1

U \..jUl..

This publication describes reference information about the functions of the
Conversational Monitor System (CMS) component of VM/SP. The
information is intended for system programmers, system analysts, and
programming personnel. Knowledge of Basic Assembler language and
experience with programming concepts and techniques are prerequisites to
using this publication.
This publication is one of a set of reference manuals for VM/SP system
programmers. The other books in the set include:
o
o
o
o
o

VM/ SP CP for System Programming
VM/ SP Group Control System Command and Macro Reference
VM/ SP Transparent Services Access Facility Reference
VM System Facilities for Programming
VM Diagnosis Guide

The order numbers for these books and related publication can be found
under "Bibliography" in the back of this manual.
Some of the topics discussed in this publication are:
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o

Processing abends
Handling interrupts
Using storage
Developing and executing programs
Linkage conventions
Updating programs
Developing commands and messages
Developing as programs
Developing VSE programs
Using VSAM functions
Tailoring your CMS system
Using the batch facility
U sing auxiliary directories
Understanding assembler virtual storage requirements
CMS macro library

After the appendices, the following sections are available to help you use
this manual more easily:
o
o
o
o

"Summary of Changes"
"Glossary of Terms and Abbreviations"
"Bibliography"
"Index"

Preface

111

1v

VM/SP eMS for System Programming

Chapter 1. IntrouucinG crllS . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The CMS Command Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Preferred Filetypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Program Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..

1
1

2
3
4

Chapter 2. Proccooill[J Abcndo . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Abend Exit Routine Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
CMS Abend Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Chapter 3. Handline Int3i'rupto in CIH8 . . . . . . . . . . . . . . . . . . . . . D
SVC Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Internal Linkage SVCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Other SVCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Input/Output Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Terminal Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Reader/Punch/Printer Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
User-Controlled Device Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Program Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
External Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Machine Check Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 1. Using StoraGe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Structure of CMS Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
Structure of DMSNUC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User and Transient Program Areas . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing CMS Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GETMAIN Free Storage Management . . . . . . . . . . . . . . . . . . . . . . . .
DMSFRE Free Storage Management . . . . . . . . . . . . . . . . . . . . . . . . .
DMSFRE Service Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Codes from DMSFREE, DMSFRES, and DMSFRET .........
Storage Protection Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CMS Handling of PSW Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

15
15
21
23
23

Chapter 5. DevelopinG Pror:;rnn:ls under CI1;IS •.......•••....••
Program Linkage (SVC Handling) .........'....................
Register Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ,.........
Parameter LIsts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Common SVC Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Search Hierarchy for SVC 202 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dynamic Linkage/SUBCOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Returning to the Calling Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The CMS Subset Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assembling Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Executing Programs .......... ".............................
Executing TEXT Files ...... : . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

'.13
43
43
46
48
54
59
61
64
65
66
67

Contents

V

24

27
35
37
38
39

Resolving External References ..............................
Controlling the CMS Loader ...............................
Creating Program Modules .................................
The Transient Program Area ...............................
Creating EXEC Procedures .................................
CMS Macro Instructions ....................................
Disk File Manipulation ...................................
Terminal Communications .................................
Unit Record and Tape I/O ..................................
Handling Interrupts ......................................
System Product Editor Interface to Access Files in Storage ..........
CMS Interface for Display Terminals ...........................
The CONSOLE Macro ....................................
The DISPW Macro .......................................

68
68
71
'72
73
75
75
84
85
85
86
88
90
93

Chapter G. Updating Source Profjrnms Using Cn1S •••••••••••• 95
The UPDATE Philosophy .................................. 95
Update Files ............................................ 96
Sequencing Output Records ................................ 99
Multiple Updates ....................................... 102
Multiple Updates with XEDIT ............................. 107
The VMFASM EXEC Procedure ............................ 109
Updating EXECs and Macros ............................. . 110
The STK Option ....................................... . 111

vi

113

Chapter 7. Developincr Commando and n·1emJage Files . . . . . . . .
Using the Parsing Facility .................................
Advantages of the Parsing Facility .........................
Advantages of DLCS ....................................
Overview .............................................
Supported CMS Commands ...............................
Coding Your Own Command Syntax with DLCS ..............
DBCS and the Parsing Facility ............................
Examples: Using the Parsing Facility .......................
Creating and Distributing Your Own CMS Commands ..........
Using Message Repository Files .............................
Overview of Creating and Using a Message Repository .........
Rules for Making Your Own Repository .....................
Substitution in Messages ................................
Dictionary Substitution .................................
Creating Your Own CMS Messages ........................
Creating Your Own HELP Files ...........................
Making Your Messages Available to Others ..................
Creating Immediate Commands .............................

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

Chapter fl. Developing OS Programs under cn~s ............
Using OS Data Sets in CMS ................................
OS Simulated Data Sets ............ ~ ....................
Restrictions for Reading OS Data Sets ......................
The ACCESS Command .................................
The FILEDEF Command ................................
Creating CMS Files from OS Data Sets .....................
Using CMS Libraries .....................................

. 157

VM/SP eMS for System Programming

.
.
.
.
.
.
.

113
113
113
114
116
117
130
131
144
145
146
148
151
151
153
154
154
154

159
160
161
161
162
169
171

/

Macro Libraries (MACLIBs) ...............................
TEXT Libraries (TXTLIBs) ................................
OS Module Libraries and CMS LOADLIBS ...................
The LKED Command ....................................
OS Data Management Simulation .............................
Handling Files that Reside on CMS Disks ....................
Handling Files that Reside on OS Disks ......................
Simulating OS Supervisor Calls ............................
OS Macros ............................................
Access Method Support ..................................
Reading OS Data Sets Using OS Macros .....................
OS Tape Volume Switching .................................

172
181
183
186
188
188
189
189
191
199
203
204

Chapter D. Developing VSE ProgrnmG under Cll,lS . . . . . . . . . . . .
Entering the CMS/DOS Environment ..........................
DL/I in the CMS/DOS Environment .........................
Using DOS Files on DOS Disks ..............................
Reading DOS Files ......................................
Creating CMS Files from DOS Libraries .....................
The ASSGN Command .....................................
Assigning System Logical Units ............................
Compiler I/O Assignments ................................
Manipulating Device Assignments ..........................
Listing I/O Assignments ..................................
Virtual Machine Assignments .............................
The DLBL Command ......................................
Entering File Identifications ..............................
Clearing and Displaying File Definitions .....................
Using DOS Libraries in CMS/DOS ............................
The SSERV Command ...................................
The RSERV Command ...................................
The PSERV Command ...................................
The ESERV Command ...................................
The DSERV Command ...................................
The DOSLKED Command .................................
DOS Core Image Libraries ................................
Using Macro Libraries .....................................
Creating CMS MACLIBs .................................
The MACLIB Command ..................................
Manipulating MACLIB Members ...........................
The MACLIST Command .................................
The GLOBAL Command ..................................
System MACLIBs .......................................
VSE Assembler Language Macros Supported ....................
Assembling Source Programs ................................
Link-editing Programs in CMS/DOS ...........................
Linkage Editor Input ....................................
Linkage Editor Output: CMS DOSLIBs ......................
Executing Programs in CMS/DOS ............................
Executing DOS Phases ...................................
Search Order for Executable Phases .........................
Making I/O Device Assignments ............................
Specifying a Virtual Partition Size ..........................
Setting the UPSI Byte ...................................

207
208
210
211
212
213
214
215
216
217
217
218
218
219
220
220
221
222
222
223
224
225
225
225
225
227
230
231
235
235
236
238
240
241
242
243
244
244
245
246
247

Contents

VB

Debugging Programs in CMS/DOS .........................
U sing EXEC Procedures in CMS/DOS ......................
Hardware Devices Supported ...............................
VSE Supervisor and I/O Macros Supported by CMS/DOS .........
Supervisor Macros .............................. ; ......
Declarative Macros (Sequential Access Method I/O Macros) .....
Imperative Macros (Sequential Access Method I/O Macros) .....
VSE Transient Routines ................. ~ .................
EXCP Support in CMS/DOS .................... ~ ...........
VSE Supervisor Control Blocks Simulated by CMS/DOS ..........
CMS/DOS User Considerations and Responsibilities .............
VSE System Generation and Updating Considerations ..........
VM/SP Directory Entries ................................
When the VSE System Must be Online ......................
Performance ..........................................
Execution Considerations and Restrictions

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

Chapter 10. U sine; 11cCCSG n~ethod Serviccs and VSArlI under CDfl:S
nnd eMS/DOS ....•.....
Executing VSAM Programs Under CMS ........
The AMSERV Command ............................
AMSERV Output Listings ............................... .
Controlling AMSERV Command Listings ............
Manipulating OS and DOS Disks for Use with AMSERV ......
Data and Master Catalog Sharing ......... '................ .
Disk Compatibility ................................
Allocating Space ....................................... .
Using VM/SP Minidisks ................................. .
The LISTDS Command ...........................
Using Temporary Disks ................................. .
Defining DOS Input and Output Files ...................
Using VSAM Catalogs .................................. .
Using Job Catalogs ............................
Catalog Passwords ...................................... .
Verifying A Catalog Structure ............................ .
Defining and Allocating Space for VSAM files ................ .
Using Tape Input and Output ............................
Defining OS Input and Output Files .......................... .
Allocating Extents on OS Disks and Minidisks ............... .
Using VSAM Catalogs .................................. .
U sing a Job Catalog ..................................... .
Catalog Passwords ..........................
Verifying a Catalog Structure ............................ .
Defining and Allocating Space for VSAM files .. '.............. .
U sing Tape Input and Output ............................. .
Using AMSERV under CMS ................................ .
The DEFINE and DELETE Functions ..............
The REPRO, IMPORT, and EXPORT (or EXPORTRA/IMPORTRA)
Functions ........................... '................ .
Writing EXECs for AMSERV and VSAM .............
ISAM Interface Program (TIP) .............................. .
VSE/VSAM Macros Supported .............................. .
Obtaining the VSE/VSAM Macros .............
0

0

••••••••••

0

••

0

0

••••

0

••••

•••••••

0

0

0

••

••••

0

••

•••••

0

••

0

0

0

••••

•••••

••••

0

0

0

••••••

0

••

•••••

•••••••••

0

0

•••••••••••

0

••••••••

0

0

viii

VM/SP eMS for System Programming

•

••

0

•••••••

••••

0

••••

247
247
249
249
250
258
267
268
269
269
270
270
271
271
272
272
273
274
276
277
277
278
279
280
280
281
281
283
284
285
288
289
289
290
292
294
295
296
299
299
300
300
303
304
305
307
309
310
311
311

I
I
I
I
I·
I
I
I
I
I
I
I
I
I

VSE Supervisor Macros and Logical Transients Support for VSAM
OSjVSAM Macros Supported in CMS .........................
OSjVSAM Error Codes ...................................
Hardware Devices Supported ................................

312
312
316
319

Ch:'lptCl' 11. r.l'~lilol'h1~ Your Crl18 Syotcnl . . . . . . . . . . . . . . . . . . .
Saving the CMS System ....................................
Saved System Restrictions for CMS .........................
Using the System Profile, SYSPROF EXEC, for Tailoring ..........
What the System Profile Does .............................
Invoking the IPL CMS Command ...........................
How to Save a Named System ..............................
How to Create or Change SYSPROF EXEC ...................
How to Bypass the System Profile ..........................
Setting Up a Protected Application Environment ...............
What the System Profile Can Do for Installations ..............
Sharing File Directory Information ...........................
The SAVEFD Command ..................................
Putting File Directory Information into Shared Storage .........
Usage Notes ...........................................
Messages and Return Codes ...............................
Sharing EXECs and Editor Macros ...........................

321

Chaptc~:...· 12. uoinG th'c CE.J8 Batch :i?acility . . . . . . . . . . . . . . . . . .
Install,ing the CMS Batch Machine ...........................
Resetting the CMS Batch Facility System Limits .................
Writing Routines To Handle Special Installation Input ............
BATEXIT1: Processing User-Specified Control Language ........
BATEXIT2: Processing the Batch Facility jJOB Control Card .....
EXEC Procedures for the Batch Facility Virtual Machine ..........
Data Security under the Batch Facility ........................
Improved IPL Performance Using a Saved System ................

333

334
335
335
335
335
336
336
336

.ch~l::r(;:)r 1:3. ULiinC; l .. u::iliary Directories
...................
Adding an Auxiliary Directory ...............................
Generating the Auxiliary Directory .........................
Initializing the Auxiliary Directory .........................
Establishing the Proper Linkage ...........................
Creating an Auxiliary Directory ..............................

339
339
339
340
341
342

321
322
322
322
323
325
325
327
327
328
328
329
330
330
331
331

CIU121tCl' Id. Vntlcl'st.:uulin[; ASSc.Glbler Virtual Storage
~:Jqt-!il'C111ClltG
• • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • 345
Overlay Structures ........................................ 345
Pre structured Overlay ................................... 346
Dynamic Load Overlay ................................... 347

APP:JIUli::8S

i:.PPclldi:: iL ,::;1',;18 Ivlam.'o Library

Appcndi::

n.

. . . . . . . . . . . . . . . . . • . . . . . . . 351

Snn1plc Tcrnlinal Session for

as

Progralnlners

A::'lL:Jcndi:: C. Sarnplc ri'ol.·lnillul Session for DOS Pl'ogl'UInn'lerS

... 355

.. 3Gl

Contents

IX

Appendhr D. Sample Terminal Session Using Access r/lethod
Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
Summary of Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Structural Changes ......................................
Technical Changes for VM System Facilities for Programming ....
Summary of Changes for the VMjSP System Programmer's Guide ..

379

379
381
383

Glossary of Terms anel Abbreviations . . . . . . . . . . . . . . . . . . . . . arm
Abbreviations ............................................ 389
Glossary ................................................ 391
BibliograIlhy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . aD5
Indel: . . • . . . . . . . . . . . . . . . . . . . • . . . . . . . . . . . . . . . . • . . . . . . .::101

x

VM/SP C:r\1:S for System Programming

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.

CMS Storage Map 1 .................................... 18
CMS Storage Map 2 .................................... 19
CMS Storage Map 3 .................................... 20
Devices Supported by a CMS Virtual Machine ............... 22
Register Contents When Called Routine Starts ............... 45
PSW Fields When Called Routine Starts .................... 45
SVC 202 High-Order Byte Values of Register 1 ............... 49
CMS Command Processing ............................... 57
SVC 202 Processing .................................... 58
FSCB Format ......................................... 75
A Sample Listing of a Program that Uses CMS Macros ......... 83
Updating Source Files with the UPDATE Command .......... 100
An Update with a Control File ........................... 106
Sample REXX Program 1 ............................... 135
Sample REXX Program 2 ................................ 136
Sample Assembler Program 1 ............................ 138
Sample Assembler Program 2 ............................ 140
as Terms and CMS Equivalents ......................... 158
CMS Commands that Recognize as Data Sets on as Disks ..... 159
Creating CMS Files from as Data Sets .................... 171
Sample MACLlST Screen ............................... 177
Simulated as Supervisor Calls ........................... 189
CMS/DOS Commands and CMS Commands with Special Operands 209
Sample MACLlST Screen ............................... 232
VSE Macros Supported by CMS .......................... 237
Physical laCS Macros Supported by CMS/DOS .............. 250
SVC Support Routines and Their Operation ................ 250
CMS/DOS Support of DTFCD Macro ...................... 259
CMS/DOS Support of DTFCN macro ...................... 261
CMS/DOS Support of DTFDl Macro ...................... 261
CMS/DOS Support of DTFMT Macro ...................... 263
CMS/DOS Support of DTFPR Macro ...................... 264
CMS/DOS Support of DTFSD Macro ...................... 265
Options of OS/VSAM Macros Supported in CMS ............. 313
VSE/VSAM to OS/VSAM Error and Return Code Mapping for
OPEN Errors ........................................ 316
VSE/VSAM to OS/VSAM Error and Return Code Mapping for
CLOSE Errors ....................................... 318
DATA Management Request Error Return Code Mapping ...... 319
Parameters Passed to SYSPROF EXEC .................... 326
An Overlay Structure .................................. 346
New VM/SP System Programming Manuals for VM/SP Release 5 380

Figures

Xl

Xll

VM/SP eMS for System Programming

I
I

r. ---------- ------- ---- - - - - - --- - - -- ----------------------------.------------------

l
The Conversational Monitor System (CMS), the major subsystem of VM/SP,
provides a comprehensive set of conversational facilities to the user.
Several copies of CMS may run under CP, thus providing several users with
their own time sharing system. CMS is designed specifically for the VM/SP
virtual machine environment.
Each copy of CMS supports a single user. This means that the storage area
contains only the data pertaining to that user. Likewise, each CMS user
has his own machine configuration and his own files. This makes
debugging simpler because the files and storage area are protected from
other users.
Programs can be debugged from the terminal. The terminal is used as a
printer to examine limited amounts of data. After examining program data,
the user can enter commands on the terminal that will alter the program.
This is the most common method used to debug programs that run in CMS.
CMS, operating with the VM/SP Control Program (CP), is a time sharing
system suitable for problem solving, program development, and general
work. It includes several programming language processors, file
manipulation commands, utilities, and debugging aids. Additionally, CMS
provides facilities to simplify the operation of other operating systems in a
virtual machine environment when controlled from a remote terminal. For
example, CMS creates and modifies job streams and analyzes virtual printer
output.
Part of the CMS environment is related to the virtual machine environment
created by CPo Each user is completely isolated from the activities of all
other users, and each machine where CMS executes has virtual storage
available to it and virtual storage managed for it by CPo The CP commands
are recognized by CMS. For example, the commands allow messages to be
sent to the operator or to other users and allow virtual devices to be
dynamically detached from the virtual machine configuration.

The eMS Command Language
The CMS command language offers terminal users a wide range of
functions. It supports a variety of programming languages, service
functions, file manipulation, program execution control, and general system
control. The CMS commands that are useful in debugging are discussed in
the VM Diagnosis Guide manual. For detailed information on all other
CMS commands, refer to the VM/SP CMS Command Reference.

Chapter 1. Introducing CMS

1

~[juHu~0)C)Jt:.D~UfJllCj G~v~8
c:::::-:-_===-----:=:-~_

.... _._ ...... _. ~=-==--===-=-.~:~~=:.~=

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . _. . . ._. . . . . . . - - - - - . - - - - - - - - - . . J

The File System
The Conversational Monitor System interfaces with virtual disks, tapes,
and unit record equipment. The CMS residence device is a read-only,
shared system disk. Permanent user files may be accessed from up to 25
active disks. CMS controls logical access to these virtual disks while CP
facilities manage the device sharing and virtual-to-real mapping.
User files in CMS are identified with three designators:
o

A filename

o

A filetype implying specific file characteristics to the CMS file
management routines.

o

A filemode describing the location and access mode of the file.

User files can be created and changed directly from the terminal with the
VM/SP System Product Editor (XEDIT). XEDIT provides extensive context
editing services. File characteristics such as record length, record format,
tab locations, and serialization options can be specified. See VM/ SP
System Product Editor Command and Macro Reference for more information
on XEDIT.
The size of user files is determined by the blocksize (BLKSIZE). For disks
with a blocksize of 800 bytes, a single user file is limited to a maximum of
65,533 records and must reside on one virtual disk. The file management
system limits the number of files on the virtual disk to 3400. When a
blocksize of 512, 1024, 2048, or 4096 bytes is specified, a single user file is
limited to a maximum of 231_1 CMS records and must reside on one virtual
disk. The maximum number of data blocks available in a variable format
file on a 512-byte blocksize mini disk is about 15 times less than 231_1. This
number is the maximum number of data blocks that can be accessed by the
CMS file system due to the 5 level tree structure. The maximum number of
files on anyone disk is limited by the file management system to 231_1.
However, the actual number of files on a disk is limited by the available
disk space and the size of the user's files.
When you access a read-only disk, a hyperblock mapping table (HYPMAP)
is built. When you access a read/write disk, a hash table complex
(HASHTAB) is built. (For further details on HYPMAP and HASHTAB, see
the VJ\lI/SP Data Areas and Control Block Logic Volume 2 (CMS) manual.)
These two tables decrease the paging overhead when searching for files.
However, the hyperblock mapping table is not built if the hyperblocks for
the disk do not span three or more pages. The hash table is not built if the
hyperblocks for the disk do not span two or more pages.
CMS automatically allocates compiler work files at the beginning of
command execution on whichever active disk has the greatest amount of
available space, and CMS deallocates them at completion. Compiler object
decks and listing files are normally allocated on the same disk as the input
source file or on the primary read/write disk, and are identified by

2

VM/SP eMS for System Programming

combining the input filename with the filetypes TEXT and LISTING. These
disk locations may be overridden by the user.
Virtual disks may be shared by CMS users. This capability is provided by
VM/SP to all virtual machines. Specific files may be spooled between
virtual machines to accomplish file transfer between users. Commands
allow such file manipulations as writing from an entire disk or from a
specific disk file to a tape, printer, punch, or the terminal. Other
commands write from a tape or virtual card reader to disk, rename files,
copy files, and erase files. Special macro libraries and text or program
libraries are provided by CMS, and special commands are provided to
update and use them. CMS files can be written onto and restored from
unlabeled tapes via CMS commands.

Caution: Multiple write access under CMS can produce unpredictable
results.
Problem programs that execute in CMS can create files on unlabeled tapes
using any record length and blocksize; the record format can be fixed,
variable, or undefined.

IPreierred FileRl'pes
CMS has a list of preferred filetypes. This list consists of filetypes that are
frequently searched for, but rarely found on your disk. The list of preferred
file types is as follows:
EXEC
MODULE
CMSUTl
AUTOSAVE
XEDTEMP
XEDIT
SYSUTl
TEXT

The active disk table (ADT) contains a byte signalling which preferred
filetypes are on the disk. Before scanning the file management tables for a
file, this byte is examined to see if any files of the desired type are present
on the disk. This process avoids searching for a file that is not on the disk;
therefore, improving system performance.
For example, if you are looking for a file with one of the preferred filetypes
and the byte in the ADT indicates that the filetype is not on the disk, then
you will avoid searching the disk for the file.
Performance may be improved by keeping preferred filetypes together on
separate disks.

Chapter 1. Introducing CMS

3

~u-u~~1QJ(~QJcnuuCj C~~JJ~)

. . ..

[.~:~ ~::

-:--~

. . -...--:--:--:--._-------_._._-_.-_. _--_.__. _ ._-_._._-_. _---..__. _ ._ . . ---. _.- -. _. . _._._ . ._ . -._-. -_._- . -_._. . _._. . __. . . -------.-.. . _. _-_._-_. _._. ._--_._--""]

--.-.-~.=.-

Program Development
The Conversational Monitor System includes commands to create, compile,
modify, and correct source programs; to build test files; to execute test
programs; and to debug from the terminal. The commands of CMS are
especially useful for OS and VSE program development, but the commands
also may be used in combination with other operating systems to provide a
virtual machine program development tool.
eMS uses the OS and VSE compilers via interface modules. The compilers
themselves normally are not changed. To provide suitable interfaces, CMS
includes a certain degree of OS and VSE simulation. For OS, the
sequential, direct, and partitioned access methods are logically simulated.
The data records are physically kept in the chained fixed-length blocks, and
they are processed internally to simulate OS data set characteristics. For
VSE, the sequential access method is supported. CMS supports VSAM
catalogs, data spaces, ~nd files on OS and DOS disks using the Access
Method Services portion of VSE/VSAM. OS Supervisor Call functions such
as GETMAIN/FREEMAIN and TIME are simulated. The simulation
restrictions concerning what types of OS object programs can be executed
under CMS are primarily related to the OS/PCP, MFT, and MVT Indexed
Sequential Access Method (ISAM) and the telecommunications access
methods. Functions related to multitasking in OS and VSE are ignored by
CMS. For more information, see "OS Data Management Simulation" on
page 188 and "Chapter 9. Developing VSE Programs under CMS" on
page 207.

4 VM/SP eMS for System Programming

When CMS abnormally terminates, the following steps are taken:
1.

After checking for any SPIE, STXIT PC, STAE, or STXIT AB exits that
apply, CMS calls DMSABN, the abend recovery routine.

2.

Before typing out any abend message at the terminal, DMSABN, the
abend recovery routine, checks for any abend exit routines, set by the
ABNEXIT macro.

3.

If a list of exit routines exists, the current abend exit routine (that is,
the last one set) gains control. If no abend exit. routines exist, CMS

abend recovery occurs.

Abend E,dt Routine Processing
An abend exit routine may be established to intercept abends before CMS
abend recovery begins. You must provide the proper entry and exit linkage
for this abend exit routine. See the ABNEXIT macro in the VM/SP eMS
Macros and Functions Reference for details on the register contents when
the routine receives control.
The abend exit routine receives control with the nucleus protect key and is
disabled for interrupts. Information about the abend is available to the exit
routine in the DMSABW CSECT in DMSNUC. The address of this area is
passed to the exit routine via register 1. In addition to the information
currently available in DMSABW, a fullword specified on the ABNEXIT
macro contains information for the exit's own purposes. ABUWRD is the
name of the fullword containing the information the user enters in the
UWORD parameter of the ABNEXIT macro.
An abend exit routine may choose to avoid CMS abend recovery and
continue processing normally. To do this, the exit must issue the
ABNEXIT RESET macro. This tells CMS to clear the abend condition.
The exit routine may also return to CMS to continue abend processing.
If the exit routine returns to CMS and another abend exit routine exists, it

is given control next. Each exit on the list is given control in sequence
until all the exits have been given control or until an exit chooses to avoid
CMS abend recovery, by issuing ABNEXIT RESET, and continues
processing.
If a program check occurs in the exit routine and ABNEXIT RESET was
not issued in this exit routine, DMSABN gives control to the next exit

Chapter 2. Processing Abends

5

.._..... _.....:~-=-J
routine on the list. If no other exit routine exists, CMS abend recovery
occurs.
You cannot set or clear abend exit routines in an abend exit routine. You
can reset an abend exit routine only in an exit routine.

eMS Abend Recovery
If no abend exit routine exists or if the abend exit routine returns to CMS
to continue abend processing, DMSABN types out the abend message
followed by the line:
eMS

This line indicates to you that the next command can be entered.
Options available to you are:
o

Issue the DEBUG command. DMSABN passes control to DMSDBG to
make the facilities of DEBUG available. DEBUG's PSW and registers
are as they were at the time the recovery routine was invoked. In
DEBUG mode, you may alter the PSW or registers. Then, type GO to
continue processing, or type RETURN to return to DMSABN·.
DMSABN continues the abend recovery.

o

Issue any command (other than DEBUG). DMSABN performs its abend
recovery function and passes control to DMSINT to execute the
command that was typed in.

The abend recovery function performs the following, in sequence:
1.

Clears the console input buffer and program stack.

2.

Terminates all VMCF activity.

3. Reinitializes the work area stack for reentrant CMS nucleus modules.

6

4.

Reinitializes the SVC handler, DMSITS, and frees all stacked save
areas.

5.

Clears the auxiliary directories, if any. Invokes "FINIS * * *", to close
all files, and to update the master file directory.

6.

Frees storage, if the DMSEXT module is in virtual storage.

7.

Zeroes out the MACLIB directory pointers.

8.

Frees the CMS work area, if the CMS subset was active.

9.

Frets the RLDDATA buffer, used by the CMS loader to retain
relocation information for the GENMOD process, if it is still allocated.

VM/SP eMS for System Programming

./

10. Issues the STAE, SPIE, TTIMER, and STAX macros to cancel any
outstanding OS exit routines. Frees any TXTLIB, MACLIB, or LINK
tables.
11. Calls with a purge PLIST, all nucleus extensions that have the
"SERVICE" attribute defined.
12. Drops all nucleus extensions that do not have the "SYSTEM" attribute.
Also drops any nucleus extensions that are in type user storage.
13. Drops all SUB COM SCBLOCKS that do not have the "SYSTEM"
attribute.
14. Frees console path and device entry control blocks.
15. Drops all storage resident execs that do not have the "SYSTEM"
attribute.
16. Clears all immediate commands that are not nucleus extensions with
the "SYSTEM" attribute; returns all associated free storage.
17. Calls DMSCLN to zero out the userword of the SRPI command.
18. Calls DMSWITAB to delete all windows and vscreens that do not have
the "SYSTEM" attributes.
19. Resets the storage keys for the whole virtual machine, except the
nonshared pages, according to FREETAB. Saves the setting for
KEYPROTECT.
20. Zeroes out all FCB, DOSCB, and LABSECT pointers.
21. Frees all storage of type user.
22. Restores the setting for KEYPROTECT.
23. Zeroes out all interrupt handler pointers in IOSECT.
24. Turns the SVCTRACE command off.
25. Closes the virtual punch and printer; closes the virtual reader with the
HOLD option.
26. Reinitializes the VSE lock table used by CMS/DOS and CMS/VSAM.
27. Zeroes out all OS loader blocks, and frees the FETCH work area.
28. Cleans up the CMS IUCV environment based on the existence of the
CMS id block.
29. Clears all ABNEXIT set and returns storage.

Chapter 2. Processing Abends

7

__-._-.. -.

L~._-_-_---_--_-----------------------------.-_._-_-_-

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

30. Computes the amount of system free storage that should be allocated
and compares this amount with the amount of free storage actually
allocated. Types a message to the user if the two amounts are unequal.
31. Issues a STRINIT and releases any pages remaining in the flush list via
a call to DMSPAGFL, if all storage is accounted for.
After abend recovery has completed, control passes to DMSINT at entry
point DMSINTAB to process the next command.

8

VM/SP eMS for System Programming

r----.--.--.--..--- ---.---.--..-.----..--.---.-.-- -.- --- . --.--.------.--.-..--.--.-.. -..--------- -..-.----.. --.--..--------------..---------.-----.. ---..-0-.--.-.-------..-.---------------.-II

L
CMS receives virtual SYC, input/output, program, machine, and external
interruptions and passes control to the appropriate handling program.

SVC Inierrupts
The Conversational Monitor System is SYC (supervisor call) driven. SYC
interruptions are handled by the DMSITS resident routines. Two types of
SYCs are processed by DMSITS: internal linkage SYC 202 and 203, and any
other SYCs. The internal linkage SVC is issued by the command and
function programs of the system when they require the services of other
CMS programs. (Commands entered by the user from the terminal are
converted to the internal linkage SVC by DMSINT). The OS SYCs are
issued by the processing programs (for example, the Assembler).

Internal Lin!cage SVCs
When DMSITS receives control as a result of an internal linkage SYC (202
or 203), it saves the contents of the general purpose registers, floating-point
registers, and the SYC old PSW, establishes the normal and error return
addresses, and passes control to the specified routine. (The routine is
specified by the first 8 bytes of the parameter list whose address is passed in
register 1 for SYC 202 or by a halfword code following SYC 203.)
For SYC 202, if the called program is not found in the internal function
table of nucleus (resident) routines, then DMSITS tries to call in a module
(a CMS file with filetype MODULE) of this name via the LOADMOD
command. If the program was not found in the function table, nor was a
module successfully loaded, DMSITS returns an error code to the caller.
To return from the called program, DMSITS restores the calling program's
registers, and makes the appropriate normal or error return as defined by
the calling program.
See pages 48 and 52 for more details on SYC 202 and SYC 203.

Chapter 3. Handling Interrupts in CMS

9

Other SVCs
The general approach taken by DMSITS to process other SVCs supported
under CMS is essentially the same as that taken for the internal linkage
SVCs. However, rather than passing control to a command or function
program, as is the case with the internal linkage SVC, DMSITS passes
control to the appropriate routine. The SVC number determines the
appropriate routine.
In handling non-CMS SVC calls, DMSITS refers first to a user-defined SVC
table (if one has been set up by the DMSHDS program). If the user-defined
SVC table is present, any SVC number (other than 202 or 203) is looked for
in that table. If it is found, control is transferred to the routine at the
specified address.
If the SVC number is not found in the user-defined SVC table (or if the
table is nonexistent), DMSITS either transfers control to the CMSDOS
shared segment (if SET DOS ON has been issued), or the standard, system
table (contained in DMSSVT) of OS calls is searched for that SVC number.
If the SVC number is found, control is transferred to the corresponding
address in the usual manner. If the SVC is not in either table, then the
supervisor call is treated as an abend call.

The DMSHDS initialization program sets up the user-defined SVC table.
The user can provide his own SVC routines by using the HNDSVC macro.

Input/Output Interrupts
All input/output interruptions are received by the I/O interrupt handler,
DMSITI. DMSITI saves the I/O old PSW and the CSW (channel status
word). It then determines the status and requirements of the device causing
the interruption and passes control to the routine that processes
interruptions from that device.
DMSITI scans console facility device entries (CDEV) until it finds one
containing the device address that is the same as the interrupting device. If
a matching device is found and a CONSOLE 'path' is waiting for an
interrupt:
1.

The wait field is cleared in the device entry,

2.

The wait bit is turned off in the I/O old PSW, and

3. DMSITI returns control to the console facility by loading the I/O old
PSW.
If no path is waiting, the interrupt is considered unsolicited and DMSITI
checks for a user-defined interrupt handling routine. If DMSITI finds one,
it passes control to the routine. Otherwise, if the device also exists in a
console CDEV entry, DMSITI checks if any I/O was done and if an EXIT

10

VM/SP eMS for System Programming

,/

l_·_.._._.

.=-=:::'=-=":'~:":~~":':"~-=~~=~::':~.':"-'-"::":"":.::':~::"'=:_~'

....-- -.-- --.. -.-_.. _
. -.-_.. -_.-_
...._
... _.. ..-.....-.. -.-.. -- --...---.-.----....--.-------..- - - - - - - -.. --.. - ..-.- ----::J

routine is specified. If an EXIT can be called, DMSITI turns off the PSW
wait bit, loads the PSW, and exits.
If no console path performed I/O or no exits were called, the interrupt for
the virtual console is passed to the system routine (DMSCITA) found in the
CMS device table (DEVTAB). For dialed devices, the unsolicited interrupt
is ignored. If fulls ere en CMS is on, attention interrupts for the virtual
console are passed to a fullscreen read routine instead of DMSCIT A.

The device table (DEVTAB) contains an entry for each device in the
system. Each entry for a particular device contains, among other things,
the address of the program that processes interruptions from that device.
When the appropriate interrupt handling routine completes its processing,
it returns control to DMSITI. At this point, DMSITI tests the wait bit in
the saved I/O old PSW. If this bit is off, the interruption was probably
caused by a terminal (asynchronous) I/O operation. DMSITI then returns
control to the interrupted program by loading the I/O old PSW.
If the wait bit is on, the interruption was probably caused by a nonterminal
(synchronous) I/O operation. The program that initiated the operation most
likely called the DMSIOW function routine to wait for a particular type of
interruption (usually a device end). In this case, DMSITI checks the
pseudo-wait bit in the device table entry for the interrupting device. If this
bit is off, the system is waiting for some event other than the interruption
from the interrupting device; DMSITI returns to the wait state by loading
the saved I/O old PSW. (This PSW has the wait bit on.)
If the pseudo-wait bit is on, the system is waiting for an interruption from
that particular device. If this interruption is not the one being waited for,
DMSITI loads the saved I/O old PSW. This again places the machine in the
wait state. Thus, the program that is waiting for a particular interruption
is kept waiting until that interruption occurs.
If the interruption is the one being waited for, DMSITI resets both the
pseudo-wait bit in the device table entry and the wait bit in the I/O old
PSW. It then loads that PSW. This causes control to be returned to the
DMSIOW function routine, which, in turn, returns control to the program
that called it to wait for the interruption.

Terminal Interrupts
Terminal input/output interruptions are handled by the DMSCIT module.
All interruptions other than those containing device end, channel end,
attention, or unit exception status are ignored. If device end status is
present with attention and a write CCW was terminated, its buffer is
unstacked. An attention interrupt causes a read to be issued to the
terminal, unless attention exits have been queued via the ST AX macro. The
attention exit with the highest priority is given control at each attention
until the queue is exhausted, then a read is issued.

Chapter 3. Handling Interrupts in CMS

11

Device end status indicates that the last I/O operation has been completed.
If the last I/O operation was a write, the line is deleted from the output
buffer and the next write, if any, is started. If the last I/O operation was a
normal read, the buffer is put on the finished read list and the next
operation is started.
If the read is caused by an attention interrupt, the line is first checked to
see if it is an immediate command (user-defined or built-in). If it is a
user-defined immediate command, control is passed to a user specified exit,
if one exists. Upon completion, the exit returns to DMSCIT. If it is a
built-in immediate command (HX, for example), appropriate processing is
performed by DMSCIT.

Unit exception indicates a canceled read. The read is reissued, unless it
had been issued with ATTREST = NO, in which case unit exception is
treated as device end.

Reader/Punch/Printer !nterrupts
Interruptions from these devices are handled by the routines that actually
issue the corresponding I/O operations. When an interruption from any of
these devices occurs, control passes to DMSITI. Then DMSITI passes
control to DMSIOW, which returns control to the routine that issued the
I/O operation. This routine can then analyze the cause of the interruption.

User-Controlled Device Interrupis
Interrupts from devices under user control are serviced the same as CMS
devices except that DMSIOW and DMSITI manipulate a user-created device
table, and DMSITI passes control to any user-written interrupt processing
routine specified in the user device table. Otherwise, the processing
program regains control directly.
To handle unsolicited device interrupts, you may specify the EXIT
parameter for the OPEN request of the CONSOLE macro instruction. If
you specify this parameter, do NOT define an interruption routine via the
HNDINT macro for the same device. Use of the CONSOLE macro with the
use of HNDINT should be mutually exclusive. If for some reason there is
both a CONSOLE EXIT and an HNDINT routine for the same device, the
HNDINT routine overrides a CONSOLE EXIT only in the case of an
unsolicited interrupt.
The console facility supports multiple applications for a single device
whereas HNDINT only allows one application to handle all interrupts from
a specific device. Because it is difficult to tell what application is doing I/O
last, the console facility helps CMS keep track of what application is doing
I/O or what application handled interrupts last.

12

VM/SP eMS for System Programming

,~.~-.-

I

---------..------------.-.--.-----------.-. __._--------_._-------_.

.•...

__ _---------------_
..

......

_-- .-

.]

The CONSOLE macro supersedes an HNDINT routine when the interrupt is
solicited. In most cases, a CONSOLE WAIT and CONSOLE READ can be
issued instead of coding an HNDINT routine to handle all interrupts.
Therefore, if you want to perform I/O to a 3270 device, you should use the
CONSOLE macro instead of the HNDINT macro.

Program Interrupts
The program interruption handler, DMSITP, receives control when a
program interruption occurs. When DMSITP gets control, it stores the
program old PSW and the contents of the registers 14, 15, 0, 1, and 2 into
the program interruption element (PIE). (The routine that handles the
SPIE macro instruction has already placed the address of the program
interruption control area (PICA) into PIE.) DMSITP then determines
whether or not the event that caused the interruption was one of those
selected by a SPIE macro instruction. If it was not, DMSITP passes control
to the DMSABN abend recovery routine.
If the cause of the interruption was one of those selected in a SPIE macro
instruction, DMSITP picks up the exit routine address from the PICA and
passes control to the exit routine. Upon return from the exit routine,
DMSITP returns to the interrupted program by loading the original
program check old PSW. The address field of the PSW was modified by a
SPIE exit routine in the PIE.

External Interrupts
An external interruption causes control to be passed to the external
interrupt handler DMSITE. If CMS IUCV support is active in the virtual
machine and an IUCV external interrupt occurs, control is passed to the
user exit specified on the HNDIUCV or CMSIUCV macro. If the user has
issued the HNDEXT macro to trap external interrupts, DMSITE passes
control to the user's exit routine.
If the interrupt was caused by the timer, DMSITE resets the timer and
types the BLIP character at the terminal. The standard BLIP timer setting
is two seconds, and the standard BLIP character is uppercase, followed by
the lowercase (it moves the typeball without printing). Otherwise, control
is passed to the DEBUG routine.

Machine Check Interrupts
Hard machine check interruptions on the real processor are not reflected to
a CMS virtual user by CPo A message prints on the console indicating the
failure. The user is then disabled and must IPL CMS again to continue.

Chapter 3. Handling Interrupts in CMS

13

14 VM/SP OMS for System Programming

,----------

©-~~~~r ri!I' (~§"lnJJ,1 @(~Jr~~'

L

. _ - - - -

The most important thing to remember about eMS, from a debugging
standpoint, is that it is a one-user system. The supervisor manages only
one user and keeps track of only one user's file and storage chains. Thus,
everything in a dump of a particular machine relates only to that virtual
machine's activity.

Stor~ge

Structure of Cf.1S

Figures 1, 2, and 3 on pages 18, 19, and 20 describe how CMS uses its
virtual storage. The pointers indicated (MAINSTRT, MAINHIGH, and
FREELOWE) are all found in NUCON (the nucleus constant area).
The sections of CMS storage have the following uses:
o

DMSNUC (X'OOOOO' to ANUCEND). This is the nucleus constant area.
It contains system control blocks, pointers, flags, and other data

updated by the various system routines.
..

Low-Storage DMSFREE User Free Storage Area (ANUCEND to
X'OEOOO'). This area is a free storage area where user requests to
DMSFREE are allocated.

o

Transient Program Area (X'OEOOO' to X'lOOOO'). Since it is not
essential to keep all nucleus functions resident in storage all the time,
some of them are made "transient." This means that when nucleus
functions are needed, they are loaded from the disk into the transient
program area. Such programs may not be longer than two pages
because that is the size of the transient area. (A page is 4096 bytes of
virtual storage.) All transient routines must be serially reusable since
they are not read in each time they are needed. See "User and
Transient Program Areas" on page 23 for more details on the transient
program area.

•

Low-Storage DMSFREE Nucleus Free Storage Area (X'lOOOO' to
X'20000'). This area is a free storage area where nucleus requests to
DMSFREE are allocated. The top part of this area contains the dummy
hyperblocks for the S- and Y-disk. Each block is 48 bytes long. This
area may be followed by the file status tables for the S2 filemode files of
the system disk.
If there is enough room, the FREETAB table also occupies this area,
just below the file status tables, if they are there. Each entry in the

Chapter 4. Using Storage

15

L

FREETAB table is one byte long. Each byte represents one page (4K or
4096 bytes) of defined storage.
•

User Program Area (X'20000' to Loader Tables or CMS Nucleus,
whichever has the lower value). User programs are loaded into this
area by the LOAD command for text decks or by the LOADMOD
command for modules. Storage allocated by means of the GETMAIN
macro instruction is taken from this area, starting from the high
address of the user program. In addition, this storage area can be
allocated from the top down by DMSFREE, if there is not enough
storage available in the low DMSFREE storage area. Thus, the usable
size of the user program area is reduced by the amount of free storage
that has been allocated from it by DMSFREE. See "User and Transient
Program Areas" on page 23 for details on the user program area.

o

Loader Tables (Top pages of storage). The top of storage is occupied
by the loader tables, which are required by the CMS loader. These
tables indicate which modules are currently loaded in the user program
area (and the transient program area after a LOAD command). The size
of the loader tables can be varied by the SET LDRTBLS command.
However, to successfully change the size of the loader tables, the SET
LDRTBLS command should be issued immediately after IPL. If SET
LDRTBLS is not issued immediately, high storage may be fragmented.

G

CMS Nucleus (NUCALPHA to NUCOMEGA). The CMS nucleus
contains the reentrant code for the eMS nucleus routines and the
system S-STAT and Y-STAT. If there is not sufficient room to contain
the S-STAT in this area, it is placed in low DMSFREE nucleus storage.
If there is not sufficient room to contain the Y-STAT in this area, the
Y-disk is accessed using the ACCESS command.

If the size of the user's virtual machine is defined below the end of the CMS
nucleus (refer to label NUCSIGMA in Figure 1 on page 18), it is not
possible to IPL by device name. You cannot IPL by device name because
the CMS nucleus is too large to be loaded into the user's virtual storage.
Therefore, the user can only IPL by system name (such as, IPL CMS). The
loader table is placed immediately below the CMS nucleus.

On the other hand, if the size of the user's virtual machine is defined above
the ending location of the CMS nucleus (refer to Figure 2 on page 19 and
Figure 3 on page 20), the user may IPL by either device name or system
name.
IPLing by device name:
The S-STAT, Y-STAT, and the loader table are placed above the CMS
nucleus. If there is not enough room to contain the' S-ST AT above the
CMS nucleus (NUCSIGMA), it is placed in low storage. Likewise, if
there is not sufficient room for the loader table above the CMS nucleus
(NUCSIGMA), the loader table is placed below the nucleus. Any
leftover free space above the nucleus is placed on the high DMSFREE
chain.

16

VMjSP eMS for System Programming

(c~tfJ8 8·~@G'8[JG
------------------------------------------ ---]

r--------------------

IPLing by system name:
The shared copy of the S-STAT, Y-STAT, and nucleus is used~ If there
is sufficient room, the loader table is placed above the S-ST AT and
Y-STAT (NUCOMEGA). If there is insufficient room to place the loader
table above the S- and Y-STAT, the loader table is placed below the
nucleus. Any leftover free space above the S- and Y-STAT
(NUCOMEGA) is placed on the high DMSFREE chain.

Chapter 4. Using Storage

17

Virtual Storage

I

I

NUCOMEGA

S-STAT and V-STAT
(Shard)

NUCSIGMA

_...

CMS Nucleus
(Shared)

--

OS Simulation, EXEC, EXEC 2, AEXX, XEDIT, CMS
interrupt handlers, file system, free storage
management, loader, device I/O, debug.
Storage Key" X'O'

NUCALPHA

End of Storage
~-------------------------------------,
System Loader Table

VMSIZE

(Size Determined by SET LDRTBLS command)
Storage Key = X'F'

·1

DMSFAEE requests when no more low'storage is available
Storllge Key = X'E' or X'F'
FAEELOWE _ ...... [ -

~se:;,o:on:f ~er-;o;:m:re:- -

--

-~

.\ "

~~.
-~

-

-

-

Storage Key = X'E'
- - -- -- GETMAIN requests

MAINHIGH

-

MAINSTAT

----------------

"

~'ser

Storllge Key .. X'E'

Storage Key

DECB

I

The User's Progrllm
(Program is locllted viII the LOAD command)

X '20000'

Control Blocks in Free Storage

Proi}ra'm
Area·"

CMSSAVE

II

LDAST

II

CMSCB

II
II

AFT

II

FSTB

I

ADT

=X'E'

Low Storage DMSFREE Nucleus Free Storage
Area. The upper part of this area may contain the
S-STAT followed by the FREETAB, If there Is
enough room,

I

Storage Key = X'F' .•

X'l0000'

Transient Program Area
Storage Key = X'E'

X'EOOO'

Low Storage DMSFREE User Free 5torllge Area

I

$torllge Key .. X'E'
ANUCEND
DMSNUC
System Control Blocks, flags constants, and pointers
Storage Key =X'F' •

X'O'

• The page starting at DMSNUCU containing OPSECT, SUBSECT,
DBGSECT, DMSERL, TSOBLKS, USERSECT, and free storage
has a Storage Key'" X'E'.

Figure 1.

18

eMS Storage Map 1. CMS virtual storage usage when the eMS nucleus is larger than the
user's virtual storage. In this case, you must IPL by system name (VMSIZE is less than
NUCSIGMA). The arrows indicate that MAINHIGH is extended upward and FREELOWE is
extended downward.

VM/SP CMS for System Programming

Virtual Storage
\

S-STATa~d

NUCOMEGA (VM SIZE)

V-STAT
(Shared - if IPL'i by system name)
NUCSIGMA
CMS Nucleus
(Shared - if IPL'd by system name)
.1-

OS simulation, EXEC, EXEC 2, REXX, XEDIT, CMS
interrupt handlers, file system, free storage
management, loader, device I/O, debug.

....

Storage Key - X'O'
System Loader Table
(Size Determined by SET LDRTBLS command)
Storage Key .. X'F'

NUCALPHA

. r-

DMSFREE requests when no more low storage is available

FREELOWE

-~

MAINHIGH

~

Storage Key .. X'E' or X'F'

---:1'- ,
------------------::;-pO::;u:,:':,::.~

Storage Key" X'E'

GETMAIN requests

'
USe'r
PrOgram
Area \,

r-

Storage Key = X'E'
MAINSTRT

I

Control Blocks in Free Storaae -

DECB

ICMSSAVE

~-------------------.
The User's Program

II

LDRST

II

AFT

II

II

CMSCB

II

FSTB

I

ADT

I

(Program is located via the LOAD command)
Storage Key" X'E'

X'20000'

X'l0000'

'Low Storage DMSFREE Nucleus Free Storage
Area. The upper part of this area may contain the
S-STAT followed by the FREETAB.lf there Is
enough room.
Storage Key = X'F'

1,:///

Transient Program Area
Storage Key .. X'E'
X'EOOO'
Low Storage DMSFREE User Free Storage Are'a

ANUCEND

Storage Key" X'E'
DMSNUC
System Control Blocks, flags, constants, and pointers

X'O'

Storage Key .. X'F' •
• The page starting at DMSNUCU containing OPSECT. SUBSECT.
DBGSECT. DMSERL. TSOBLKS. USERSECT. and free storage
has a Storage Key • X'E'.

Figure 2.

eMS Storage Map 2. Virtual storage usage when the user's virtual storage is equal to the eMS
nucleus. The user may IPL by system name or device. In addition, this figure shows the case
where there is insufficient room to place the loader table above S-STAT and Y-STAT. The arrows
indicate that MAINHIGH is extended upward and FREELOWE is extended downward.

Chapter 4. Using Storage

19

...... ". . .". , .. "._.... ___________________._____ ..........._._ .......__ ........... __ ....... _. __..____. ___-=-______. ________________1

L

Virtual Storage

VM SIZE

System Loader Table
(Size Determined by SET LDRTBLS command)

~

_____________

~~~~~2:

DMSFREE requests

I

Storage Key" X'E' or X'F'
NUCOMEGA

I
S-STAT and Y -STAT
(Shared - if IPL'd by system name)

...

J

NUCSIGMA

.-

CMS Nucleus
(Shared - if IPL'd by system name)
OS simulation, EXEC, EXEC 2, REXX, XEDIT, CMS
interrupt handlers, file system, free storage
management, loader, device I/O, debug.

.1.0

Storage Key .. X'O'
NUCALPHA

DMSFREE requests when no more low storage is available
__________

FREELOWE

.
MAINHIGH

~t~a2! ~y..:X":;'.!!r!'!'

Unused portion of User Program Area

--

--------------------Storage Key" X 'E'

GETMAIN requests

MAINSTRT

User
Progr;::m
Area

-------------------Storage Key = X'E'

The User's Program
(Program is located via the LOAD command)

Storage Key

X '20000'

Control Blocks in Free Storage
LDRST

II

AFT

II

ICMSSAVEII CMSCB

II

FSTB

I

DECB

II

ADT

= X'E'

Low Storaga DMSFREE Nucleus Free Storage
Area. The upper part of this area may contain the
S-STAT followed by the FREETAB,lf there Is
enough room.
Storage Key = X'F'

X'l0000'
Transient Program Area
X'EOOO'

Storage Key

= X'E'

Low Storage DMSFREE User Free Storage Area

ANUCEND

Storage Key = X 'E'
DMSNUC
System Control Blocks, flags, constants, and pointers
Storage Key = X'F' •

X'O'

• The page starting at DMSNUCU containing OPSECT, SUBSECT,
DBGSECT, DMSERL, TSOBLKS, USERSECT, and free storage
has a Storage Key = X'E',

Figure 3.

20

eMS Storage Map 3. eMS virtual storage usage when the user's virtual storage is larger than
the eMS nucleus. The user may IPL by system name or device. In addition, this figure shows the
case where there is sufficient room to place the loader table above S-STAT and Y-STAT. The
arrows indicate that MAINHIGH is extended upward and FREELOWE is extended downward.

VMjSP eMS for System Programming

/'

Structure of DMSNUC
DMSNUC is the portion of storage in a CMS virtual machine that contains
system control blocks, flags, constants, and pointers.
The CSECTs in DMSNUC contain only symbolic references. This means
that an update or modification to CMS, which changes a CSECT in
DMSNUC, does not automatically force all CMS modules to be recompiled.
Only those modules that refer to the area that was redefined must be
recompiled.
USERSECT (User Area)

The USERSECT CSECT defines space that is not used by CMS. A
modification or update to CMS can use the 18 fullwords defined for
USERSECT. There is a pointer (AUSER) in the NUCON area to the user
space.
DEVTAB (Device Table)

The DEVTAB CSECT is a table describing the devices available for the
CMS system. The table contains the following entries·
0
0
0

0
0
0

0

1 console
26 disks
1 reader
1 punch
1 printer
16 tapes
1 dummy

You can change some existing entries in DEVTAB. Each device table entry
contains the following information:
o
o
o
o
o

Virtual device address
Device flags
Device types
Symbol device name
Address of the interrupt processing routine (for the console).

The virtual address of the console is defined at logon time. The ACCESS
command can dynamically alter the virtual address of the user disks in
DEVTAB. The virtual address of a tape can be reassigned to any of the
addresses given in DEVTAB (TAPO - TAPF) by using CMS commands
and/or macros. Changing the virtual addresses of the reader, printer, or
punch in DEVTAB has no effect. Figure 4 describes the devices supported
by eMS.

Chapter 4. Using Storage

21

C~v~8 8~fJ)l/ogG
L ....-=:-:-........................ ____ ._._._.____ ._. _____ ... ___ .__ ._~.===_:===~.::_=-::-:-~~~.:::=~._--~~::~: ...~:~.-~:.- ..~.::-. _:_.:.~~--.--.~:_:~-~::J

Virtual
IEI'll: Device Type
3210, 3215, 1052,
3066, 3270
2314, 2319, 3310,
3330, 3340, 3350,
3370, 3375, 3380

2540,
2540,
1403,
3211,
4245,
2401,
2415,
3411,
3480,

2501,
3525
1443,
3262,
4248,
2402,
2420,
3420,
8809,

Figure 4.

22

3505
3203,
3800,
3289-4
2403,
3410,
3430,
3422

Virtual
Acldrcnn\":
cuu!

Symbolic
Nnn1.c (defuult)
CON1

Device Une
System console

190
1912
cuu
cuu
192
cuu
cuu
cuu
19E
cuu
cuu
cuu
cuu
cuu
cuu
cuu
cuu
cuu
cuu
cuu
cuu
cuu
cuu
cuu
cuu
cuu
OOC
OOD
OOE

DSKO
DSK1
DSK2
DSK3
DSK4
DSK5
DSK6
DSK7
DSK8
DSK9
DSKH
DSKI
DSKJ
DSKK
DSKL
DSKM
DSKN
DSKO
DSKP
DSKQ
DSKR
DSKT
DSKU
DSKV
DSKW
DSKX
RDR1
PCH1
PRN1

CMS System disk (read-only)
Primary disk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Minidisk (user files)
Virtual reader
Virtual punch
Line printer

180 - 187,
288 - 28F

TAPO - TAP7,
TAP8-TAPF

Tape drives

Devices Supported by a eMS Virtual Machine

*

The device addresses shown are preas sembled into the CMS resident
device table. These need only be modified and a new device table made
resident to change the addresses.

1

The virtual address of the system console may be any valid multiplexer
address.

2

191 is the default user-accessed A-disk unless it is dynamically changed
by an ACCESS at CMS initial program load (IPL).

VM/SP eMS for System Programming

L __ .__ ._._

User and Transient Program Areas
Two areas hold programs that are loaded from disk. These areas are called
the user program area and the transient program area, as discussed on page
15. (See Figures 1, 2, and 3 on pages 18, 19, and 20 for a description of CMS
storage use.) A summary of CMS modules and their attributes, including
whether they reside in the user program area or the transient area, is
contained in the VM/ SP CMS Command Reference.
The user program area starts at location X'20000' and extends upward to
the loader tables. Generally, all user programs and certain system
commands are executed in the user program area. Because only one
program can be executing in the user program area at anyone time, it is
impossible (without unpredictable results) for one program executing in the
user program area to invoke, by means of SYC 202, a module that will also
be executed in the user program area.
The transient program area is two pages long, extending from location
X'EOOO' to location X'FFFF'. It provides an area for system commands that
may also be invoked from the user program area by means of an SYC 202
call. When a transient module is called by an SYC, it is normally executed
with the PSW system mask disabled for I/O and external interrupts.
A program executing in the transient program area may not invoke another
program intended to execute in the transient program area. Thus, a
program executing in the transient program area may not invoke the TYPE
command.
DMSITS starts the programs to be executed in the user program area
enabled for all interrupts, but DMSITS starts the programs to be executed
in the transient program area disabled for all interrupts. The individual
programs may have to use the SSM (Set System Mask) instruction to
change the current status of its system mask.

Managing eMS Storage
You can allocate free storage by issuing the GETMAIN or DMSFREE
macros.
Storage allocated by the GETMAIN macro is taken from the user program
area, starting after the high address of the user program. Storage allocated
by the DMSFREE macro can be taken from several areas. First, DMSFREE
requests are allocated from the low address free storage area. Otherwise,
DMSFREE requests are satisfied from the unused portion of the user
program area.
There are two types of DMSFREE requests for free storage: requests for
USER storage and NUCLEUS storage, specified in the TYPE parameter of
the DMSFREE macro. These two types of storage are kept in separate 4K
pages. It is possible for storage of one type to be available in low storage,
while no storage of the other type is available.
Chapter 4. Using Storage

23

C-.

------------.-------'--:._':::--~-:-.:_:-~=.~-'------

.

-,--------------.-,._-------,-----.---,--------.-------~~-.~~::::_::=_~-~.

GETMAIN Free Storage Management
All GETMAIN storage is allocated in the user program area, starting after
the end of the user's actual program. Allocation begins at the location
pointed to by the NUCON pointer MAINSTRT. The location MAINHIGH
in NUCON points to the highest address of GETMAIN storage.
The STRINIT function initializes pointers used by CMS for simulation of
OS GETMAIN/FREEMAIN storage management. In the usual CMS
environment, that is, when execution is initiated by the LOAD and START
commands, CMS calls the STRINIT macro as part of the LOAD preparation
for execution. In an OS environment established by CMS, such as OSRUN,
CMS' executes the STRINIT function. This should not be done by the user
program. In any case, the STRINIT macro should be issued only once in
the OS environment, preceding the initial GETMAIN request. In addition,
the STRINIT function makes any pages that were allocated by GETMAIN
available to be released by the CMS page manager.
The STRINIT Macro

The format of the STRINIT macro is:

[label]

STRINIT

[TYPCALL = {~XrR}

1

where:
label

is any valid assembler language label.

TYPCALL ={SVC }
BALR
indicates how control is passed to DMSSTG, the routine that
processes the STRINIT macro. Since DMSSTG is a nucleus-resident
routine, other nucleus-resident routines can branch directly to it
(TYPCALL = BALR). Routines that are not nucleus-resident must use
SVC linkage (TYPCALL = SVC) . .If no operands are specified, the
default is TYPCALL = SVC.
When the STRINIT macro is executed, both MAINSTRT and MAINHIGH
are initialized to the end of the user's program in the user program area.
The end of the user's program is the upper boundary of the load module
created by the CMS LOAD and INCLUDE commands. This upper boundary
value is stored in the NUCON field LOCCNT. When the user's program
begins execution, the STRINIT macro is executed and the LOCCNT value is
used to initialize MAINSTRT and MAINHIGH. During execution of the
user's program, the LOCCNT field is used in CMS to pass starting and
ending addresses of files loaded by OS simulation (see Notes below). As
storage is allocated from the user program area to satisfy GETMAIN

24

VM/SP eMS for Sys'tem Programming

'J' "\

,1':,[
\ J~.)~ ~''')':~'II)LJ~
'J'
" .• 'J LJ.J I,..
' .. _ " _
l._ ~_

L....:...--.:_. . _ . . __ . _._...___. ____ ._____.____ . __ __ ____ ._.__ ___ .. . . _. __.__, '
:~

~~

~

~

~

_.~_

'-..J

, _ _.. _ __ _ _' ,: ____ . .____

:~_J

requests, the MAINHIGH pointer is adjusted upward. Such adjustments
are always in multiples of doublewords, so that this pointer is always on a
double word boundary. As the allocated storage is returned, the
MAINHIGH pointer is adjusted downward.
The pointer MAINHIGH can never be higher than FREELOWE.
FREELOWE is the pointer to the lowest address of DMSFREE storage
allocated in the user program area. If a GETMAIN request cannot be
satisfied without extending MAINHIGH above FREELOWE, GETMAIN
takes an error exit, indicating that insufficient storage is available to
satisfy the request.
The area between MAINSTRT and MAINHIGH may contain blocks of
storage that are not allocated but are available for allocation by a
GETMAIN instruction. These blocks are chained together, and the first
block is pointed to by the NUCON location MAINLIST. Refer to Figures 1,
2, and 3 on pages 18, 19, and 20 for a description of CMS virtual storage
usage.

Notes:
1.

Reissuing the STRINIT macro during execution of an OS program, or
issuing the STRINIT macro without having done a CMS LOAD is not
advised. The value in LOCCNT has not been appropriately set. This
may cause a storage management failure.

2.

A high level language may issue a STRINIT. In this case, a user should
not issue an additional STRINIT.

The format of an element on the GETMAIN free element chain is as
follows:

0(0)

4(4)

FREPTR -- pointer to next free
element in the chain, or a
if there is no next element
FRELEN -- length, in bytes, of
this element
Remainder of this free element

The maximum amount of storage that can be obtained via the GETMAIN
macro is determined by one of the following formulas:
VMSIZE < 512K:
(largest block of the user program area available) - 10 pages
VMSIZE > = 512K:

Chapter 4. Using Storage

25

r,-';,.rVJD
\:.::;7Lv ~)

nr'r:-")r"1n(-~('\

I:.~)~c.lu Cj~J'-;

(largest block of the user program area available) - (12 pages + 2
additional pages for each 256K of virtual storage over 512K)
Releasing Storage

Storage allocated by the GETMAIN macro instruction may be released in
any of the following ways:
1.

A specific block of such storage may be released by means of the
FREE MAIN macro instruction.

2. Whenever any user routine or eMS command abends (so that the
routine DMSABN is entered) and the abend recovery facility of the
system is invoked, all GETMAIN storage pointers are reset.
3. Issuing a STRINIT macro releases all allocated GETMAIN storage.

26

VM/SP eMS for System Programming

(~L~;]8 8'~«)[j'CJ~J(J
~---

. --.. -- . --.-.--- . -.----. -. --------.--~. ------ -----~. . . --.--~ . -.. :---.-----~.- . ,.--:.....-~. - .. -'"~=--==~-=::~~~~:..:.:..:..=-:...:..:=-:..:...:.:--~~~--. . -"'-~

I DMSFRE Free Storage Management
The DMSFREE Macro

The DMSFREE macro allocates CMS free storage. The format of the
DMSFREE macro is:

DMSFREE

[ label]

DWORDS= {

n }

(0)

[,TYPE = {USER

[ ,MIN = { (~) } ]
}]

NUCLEUS

[,ERR= {la~dr}]
[,AREA = {~?ci1}]
[,TYPCALL= {~x~R}l

where:
label

is any valid assembler language label.

DWORDS={

n}

(0)

is the number of double words of free storage requested. DWORDS = n
specifies the number of doublewords directly and DWORDS = (0)
indicates that register 0 contains the number of doublewords
requested. Do not specify any register other than register O. The
register number for register 0 cannot be expressed as an equated
symbol.
CMS returns, in register 0, the number of doublewords allocated and,
in register 1, the address of the first byte of allocated storage.

MIN=

{(~)}

indicates a variable request for free storage. If the exact number of
double words indicated by DWORDS operand is not available, then the
largest block of storage greater than or equal to the minimum is
requested. MIN = n specifies the minimum number of doublewordsof
free storage directly. MIN = (1) indicates that the minimum is in
register 1. Do not specify any register other than register 1. The

Chapter 4. Using Storage

27

C~JJ~) 8~C)r8[jG

r--:- .
actual amount of free storage allocated is returned to the requestor by
general register O.

TYPE = {" USER
"}
" NUCLEUS
indicates the type of CMS storage requested: USER or NUCLEUS
ERR = {~addr}
is the return address if any error occurs. laddr is any address that
can be referred to in an LA (load address) instruction. The error
return is taken if there is a macro coding error or if there is not
enough free storage available to fill the request. If the asterisk (*) is
specified for the return address, the error return is the same as a
normal return. There is no default for this operand. If it is omitted
and an error occurs, the system abends.

AREA= "{LOW}
HIGH
indicates the area of CMS free storage requested. LOW indicates any
free storage below the user areas, depending on the storage requested.
HIGH indicates DMSFREE storage above the user area. If AREA is
not specified, storage is allocated wherever it is available.
TYPCALL ={ SVC }
BALR
indicates how control is passed to DMSFREE. Since DMSFREE is a
nucleus-resident routine, other nucleus-resident routines can branch
directly to it (TYPCALL = BALR). Routines that are not
nucleus-resident must use SVC linkage (TYPCALL = SVC).
The FREELOWE pointer in NUCON indicates the amount of storage that
DMSFREE has allocated from the high portion of the user program area.
These pointers are initialized to the beginning of the loader tables.
The pointer FREELOWE is the pointer to the lowest address of DMSFREE
storage in the user program area. As storage is allocated from the user
program area to satisfy DMSFREErequests, the pointer FREELOWE is
adjusted downward. As the allocated storage is returned, this pointer is
adjusted upward. Such adjustments are always in multiples of 4K bytes so
the pointer is always on a 4K boundary.
The pointer FREEL OWE can never be lower than MAINHIGH.
MAIN HIGH is the pointer to the highest address of GETMAIN storage. If
a DMSFREE request cannot be satisfied without extending FREELOWE
below MAINHIGH, DMSFREE takes an error exit, indicating that
insufficient storage is available to satisfy the request. Figures 1, 2, and 3
on pages 18, 19, and 20 show the relationship of these storage areas.
The FREETAB free storage table is usually kept in nucleus low FREE
storage. However, the FREETAB may be located at the top of the user

28

VM/SP eMS for System Programming

«~~lfJS ~~'~O[/8~G
-

-]

program area. This table contains a code indicating the use of that page of
virtual storage. The codes in this table are as follows:
USERCODE (X'Ol')

The page is assigned to user storage.

NUCCODE (X'02')

The page is assigned to nucleus storage.

TRNCODE (X'03')

The page is part of the transient program area.

USARCODE (X'04')

The page is an unassigned page in the user
program area.

SYSCODE (X'05')

The page is none of the above. The page is
assigned to system storage, system code, or the
loader tables.

Other DMSFREE storage pointers are maintained in the DMSFRT CSECT,
in NUCON. The four chain header blocks are the most important fields in
DMSFRT. The four chains of unallocated elements are:
o
o
o
o

The
The
The
The

low storage nucleus chain
low storage user chain
high storage nucleus chain
high storage user chain

For each of these chains of unallocated elements, there is a control block
consisting of four words with the following format:

0(0)

POINTER -- pointer to the first
FBD (free block descriptor)
in a cache of FBDs used to
describe the first "nll free
blocks of storage for the
particular chain.

4(4)

NUM -- the number of elements on
the chain.

8(8)

MAX -- a value equal to or
rreater than the size of the
argest element on the chain.

12(C)

FLAGS- SKEYFlag
Storage
byte
key

TCODEFREETAB
code

Unused

where:

POINTER
points to the first FBD (file block descriptor) in a cache of FBDs used
to describe the first "n" free blocks of storage for the particular chain.
"n" is 10 for the high user chain, 9 for the high nucleus chain, 6 for
the low user chain, and 6 for the low nucleus chain.

Chapter 4. Using Storage

29

NUM
contains the number of elements on this chain of free elements. If
there are no elements on this free chain, this field contains all zeroes.

MAX
is used to avoid searches that will fail. It contains a number not
exceeding the size, in bytes, of the largest element on the free chain.
Thus, a search for an element of a given size is not made if that size
exceeds the MAX field. However, this number may actually be larger
than the size of the largest free element on the chain.
FLAGS
The following flags are used:
FLCLN (X'80') -- Clean-up flag. This flag is set if the chain must be
updated. This is necessary in the following circumstances:
o

If one of the two high-storage chains contains a 4K page that is
pointed to by FREELOWE, that page can be removed from the
chain and FREELOWE can be increased.

o

All completely unallocated 4K pages are kept on the user chain,
by convention. Thus, if one of the nucleus chains (low-storage or
high-storage) contains a full page, this page must be transferred to
the corresponding user chain.

FLCLB (X'40') -- Destroyed flag. Set if the chain has been destroyed.
FLHC (X'20') -- High-storage chain. Set for both the nucleus and user
high-storage chains.
FLUN (X'lO') -- Nucleus chain. Set for both the low-storage and
high-storage chains.
FLPA (X'08') -- Page available. Set if there is a full 4K page
available on the chain. This flag may be set even if there is no such
page available.
SKEY
contains the one-byte storage key assigned to storage on this chain.
TCODE
contains the one-byte FREETAB table code for storage on this chain.
There are four caches of FBDs, one for each of the chains. The FBDs are
chained together at initialization time from the head pointers found in the
DMSFRT CSECT described above.
Each of the FBDs in the cache has the following format:

30

VM/SP eMS for System Programming

_ .J

~-------

4 bytes

0(0)

POINTER -- pointer to the next FBD in the
chain unless it is the last FBD in the
cache in which case it points to the
next block of free storage in the chain
or is zero.

4(4)

SIZE -- size of the free block in bytes

8(8)

FBDFREE -- pointer to the free block
that this FBD is describing.

The FBDs in the cache always remain chained together, and when they do
not describe a free block, the fields SIZE and FBDFREE are zero. When
the cache is full, the forward pointer POINTER in the last FBD in the
cache points to the next free block that contains the following fields:
 8

An unexpected and unexplained error has occurred in the free
storage management routine.

Storage Protection Keys
In general, the following rule for storage protection keys applies: system
storage is assigned the storage key of X ' FO ' , while user storage is assigned
the storage key of X ' EO '. This is the storage key associated with the
protected areas of storage, not to be confused with the PSW or CAW key
used to acc~ss that storage.
The specific key assignments are as follows:
o

The NUCON area is assigned the key of X'FO', with the exception of the
last page containing the OPSECT and TSOBLOKS areas and user free
storage, which have a key of X'EO'.

o

Free storage allocated by DMSFREE is broken up into user storage and
nucleus storage. The user storage has a protection key of X'EO', while
the nucleus storage has a key of X'FO'.

o

The transient program area has a key of X'EO'.

o

The CMS nucleus code has a storage key of X'OO'. In saved systems,
this entire segment is protected by CP from modification even by the
CMS system, and so must be entirely reentrant.

o

The user program area is assigned the storage key of X'EO', except for
those pages which contain nucleus DMSFREE storage. These latter
pages are assigned the key of X'FO'.

o

The loader tables are assigned the key of X'FO'.

The SET KEYPROTECT Command

The SET KEYPROTECT command controls the resetting of user keys,
X'EO', when a DMSFRET occurs. The format of the SET KEYPROTECT
command is:

SET

38

VM/SP eMS for System Programming

KEYPROTect

{ON
}
OFF

((~M8 8'l(Ou~E1[JG
___

r-.----=~:__=:._=~-~=_.:=_--~

_

~:_~~_~_:.~=__~~~~=:~~~ _=__~==~~-~~~-=_-=-~==_~-.::===~_==:::__==~_._____________

---.------------=--=-.J

When you issue SET KEYPROTECT ON, the storage keys for the whole
virtual machine, except the non shared pages, are reset according to
FREETAB. Then whenever a DMSFRET occurs, the user keys are reset.
SET KEYPROTECT OFF does not cause the user keys to be reset when a
DMSFRET occurs. (SET KEYPROTECT OFF is the default setting.) If an
ABEND occurs, the storage keys of the virtual machine are reset according
to FREETAB and the setting for KEYPROTECT is maintained.
To check the setting of KEYPROTECT, issue:
QUERY KEYPROTECT

Note: If user programs set keys, they must restore the keys to their
original settings. If there are programs that depend on CMS resetting user
keys, SET KEYPROTECT ON to insure that the user keys are set properly.

eMS Handling of PSW Keys
The CMS nucleus protection scheme protects the CMS nucleus from
inadvertent destruction by a user program. This mechanism, however, does
not prevent you from writing in system storage intentionally. Because you
can execute privileged instructions, you can issue a LOAD PSW (LPSW)
instruction and load any PSW key you wish. If this occurs, there is nothing
to prevent your program from:
o
o
o

Modifying nucleus code
Modifying a table or constant area
Losing files by modifying a CMS file directory

In general, user programs and disk-resident CMS commands are executed
with a PSW key of X'E', while nucleus code is executed with a PSW key of
X'O'.
There are, however, some exceptions to this rule. Certain disk-resident
CMS commands run with a PSW key of X'O', because they have a constant
need to modify nucleus pointers and storage. The nucleus routines called
by the GET, PUT, READ, and WRITE macros run with a user PSW key of
X'E' to increase efficiency.
Two macros, DMSKEY and DMSEXS, are available to any routine that
wishes to change its PSW key.
The DMSKEV Macro

The DMSKEY macro may be used to change the PSW key to the user value
or the nucleus value. The format of the DMSKEY macro is:

Chapter 4. Using Storage

39

[ label]

DMSKEY

{NUCLEUS [,NOSTACKJ I
USER [,NOSTACK ] I
LASTUSER [,NOSTACK]
RESET}

I

where:
label

is any valid assembler language label.
NUCLEUS
causes the nucleus storage protection key to be placed In the PSW,
and the old contents of the second byte of the PSW are saved in a
stack. This option allows the program to store into system storage,
which is ordinarily protected.
USER
causes the user storage protection key to be placed in the PSW, and
the old contents of the second byte of the PSW are saved in a stack.
This option prevents the program from inadvertently modifying
nucleus storage, which is protected.
LASTUSER
The SVC handler traces back through its system save areas for the
active user routine closest to the top of the stack. The storage key in
effect for that routine is placed in the PSW. The old contents of the
second byte of the PSW are saved in a stack. This option should be
used only by system routines that should enter a user exit routine.
(OS macro simulation routines use this option when they want to
enter a user-supplied exit routine. The exit routine is entered with the
PSW key of the last user routine on the SVC system save area stack.)
NOSTACK
This option may be used with any of the above options to prevent the
system from saving the second byte of the current PSW in a stack. If
this is done, then no DMSKEY RESET need be issued later.
RESET
The second byte of the PSW is changed to the value at the top of the
DMSKEY stack and removed from the stack. Thus, the effect of the
last DMSKEY NUCLEUS, DMSKEY USER, or DMSKEY LASTUSER
request is reversed. However, if the NOSTACK option was specified
on the DMSKEY macro, the RESET option should not be used. A
DMSKEY RESET macro must be executed for each DMSKEY
NUCLEUS, DMSKEY USER, or DMSKEY LASTUSER macro that
was executed and that did not specify the NOSTACK option. Failure
to observe this rule results in program abnormal termination. CMS
requires that the DMSKEY stack be empty when a routine terminates.

40

VM/SP eMS for System Programming

L -________

___ ._______________ .______ ._._ . . __ __ .__ ___ . . .:.___ ____ __
_~.~

~.

~~.

~~

~_~

~~

I,G~~'J~j G'~\Qu'Cl~J\J
__ __ _____.__.___

.~~:~:.:._-

~~_~

~:_.:.._-~

~:_J

Note: The DMSKEY key stack has a current maximum depth of seven for
each routine. In this context, a "routine" is anything invoked by an SVC
call.
The DMSE}(S Macro

The DMSEXS, "execute in system mode," macro allows a routine executed
with a user PSW key to execute a single instruction with a nucleus PSW
key. The single instruction may be specified as the argument to the
DMSEXS macro, and that instruction is executed with a nucleus PSW key.
This macro can be used instead of two DMSKEY macros.
The format of the DMSEXS macro is:

[label]

DMSEXS

op-code ,operands

The op-code and the operands of the Basic Assembler Language instruction
to be executed must be given as arguments to the DMSEXS macro.
For example, execution of the sequence,
USING NUCON,O
DMSEXS OI,OSSFLAGS,COMPSWT

causes the 01 instruction to be executed with a zero protect key in the
PSW. This sequence turns on the COMPSWT flag in the nucleus. It is
reset with
DMSEXS NI,OSSFLAGS,255-COMPSWT

The instruction to be executed may be an EX instruction.
Note: Programs that modify or manipulate bits in CMS control blocks,
however, may hinder the operation of eMS causing it to function
ineffectively.

Register 1 cannot be used in any way in the instruction being executed.
Whenever possible, CMS commands are executp.d with a user protect key.
This protects the CMS nucleus in cases where there is an error in the
system command that would otherwise destroy the nucleus. If the command
must execute a single instruction or small group of instructions that modify
nucleus storage, then the DMSKEY or DMSEXS macros are used so that
the system PSW key is used for as short a period of time as possible.

Chapter 4. Using Storage

41

(G~JJ8 §~Q)L~@OG
L___ ._~ ___________________ .__________________.__-__. ________________.__________ . _____

42

VM/SP eMS for System Programming

-==-_-:--::--==-=--==-===--:J

Program

lin~(age

(SVC Handling)

Program linkages, in CMS, are made by a supervisor call instruction, SVC
202. DMSITS (INTSVC) is the CMS system SVC handling routine. The
general operation of DMSITS is as follows:
1.

The SVC new PSW (low-storage location X'60') contains, in the address
field, the address of DMSITS1. The DMSITS module is entered
whenever a supervisor call is executed.

2.

DMSITS allocates a system save area and user save area. The user save
area is a register save area (or work area) used by the routine, which is
invoked later as a result of the SVC call.

3.

The called routine is called (via a LPSW or BALR).

4.

Upon return from the invoked routine, the save areas are released.

5.

Control is returned to the caller (the routine that originally made the
SVC call).

Register Usage
When calling a CMS routine, Rl must point to a valid parameter list
(PLIST) for that program. On return, RO mayor may not contain
meaningful information. For example, on return from a call to FILEDEF
with no change, RO contains a negative address if a new FCB (file control
block) was set up. Otherwise, RO contains a positive address of the already
existing FCB. R15 contains the return code, if any. The use of registers 0
and 2 through 11 varies.
When a command or routine is called by SVC 202, the registers contain the
following information:

Chapter 5. Developing Programs under CMS

43

Register Contents

o

Points to an extended PLIST if the command is:
e
o
•
o

called from the terminal,
called from a REXX program,
called from an EXEC 2 EXEC, or
an Enhanced Connectivity Facilities on VM/SP call (see
SENDREQ in the VM/ SP IBM Programmer's Guide to the
Server-Requester Programming Interface for VM/SP,
SC24-5291).

The EPLIST contains addresses referring to the extended
command as it was initially entered by the user.
1

Points to a parameter list of successive doublewords. The first
entry in the list is the name of the called routine or program.
Any successive doublewords may contain arguments passed to
the program.

13

Contains the address of a 24-fullword save area, which you can
use to save your caller's registers. This save area satisfies
standard OS and DOS linkage conventions. You do not need to
use it in CMS, since the SVC routines save the registers.

14

Contains the return address of the SVC handling routines. You
must return control to this address when you exit from your
program.

12 and 15 Contain your program's entry point address. You can use this
address to establish immediate addressability in your program.
Most CMS routines use R12 as a base register. You should not
use R15 as a base address, since all CMS SVCs use it to
communicate with your programs.
On return from a routine, register 15 contains:

Return Code Meaning
No error occurred
<0
Called routine not found
>0
Error occurred

o

If a CMS routine is called by an SVC 202, CMS saves and restores registers
o through 14.

Figure 5 shows how registers are set up when the called routine is entered.

44

VM/SP eMS for System Programming

___ '-:.J

Ren-istel'G TIer:;istQr
2
Same as
See note
caller
1

Rcr.;iGtel'G

nc~iGter

Register

RegiGtcl'

Rcaister

3 - 11

12

13

1,1

15

Not
defined

Address
of called
routine

Address
of user
save
area

Return
address
to
DMSITS

Address
of called
routine

sve 203

Same as
caller

Not
defined

Not
defined

Address
of called
routine

See note
2

Address
of called
routine

Other

Same as
caller

Same as
caller

Same as
caller

Address
of called
routine

Address
of user
save
area

Return
address
to
DMSITS
Return
address
to
DMSITS

Type

sve 202

Figure 5.

0-1

Same as
caller

Register Contents When Called Routine Starts

Notes:
1.

If a nucleus extension or subcommand processor, register 2 has address of
SCBLOCK.

2.

Depends on the function being invoked.

Figure 6 show how the PSW fields are set up when the called routine is
entered.
Cnlletl Type
sve 202 or 203 -Nucleus Resident
sve 202-Nucleus
Extension
Module
sve 202 or 203 -Transient Area
Module
sve 202 or 203 -User Area
Module
U ser-handled
OS-VSE -Nucleus resident
OS-VSE -Transient area
module

SYStClll lVIasli:: Storage ICey
Disabled
System

Pl'oblClll Bit
Off

See note 1

See note 1

Off

Disabled

See note 2

Off

Enabled

See note 2

Off

Enabled
Disabled

User
System

Off

Disabled

System

Off

Off

Figure 6.PSW Fields When Called Routine Starts

Chapter 5. Developing Programs under CMS

45

[D)G\JG~(Q)[])UuuQJ rrQ[D~~8uuuG ~%U(~G~'

CWJS

r_._____._______. __. .___.__. __.__.____.____.____________:____._______. .__ . __. _______. _. . . . . . .
Notes:
1.

User defined by using the NUCEXT function.

2.

User defined by using the CMS GENMOD command or the CMS SET
PROTECT command.

Parameter Lists
Tokenized PLiST

For a tokenized parameter list, the symbolic name of the function being
called (B-character string, padded with blank characters on the right if
needed) is followed by extra arguments depending on the actual routine or
command being called. These arguments must be "tokenized." Every
parenthesis is considered an individual argument, and each argument may
have a maximum length of eight characters. However, no error condition
results. R1 contains the address of this parameter list.
eMS commands look for a token of eight X'FF's to find the end of the
PLIST.
See page 51 for an example of a tokenized PLIST.
Extended PLiST

For an extended parameter list (EPLIST), no restriction is put on the
structure of the argument list passed to the called routine or command.
The first non-blank character, left parenthesis, or right parenthesis
following the command is treated as a delimiter. This delimiter determines
where the pointer to the start of the argument is.
An extended PLIST has two forms, as illustrated below.

The First Form of the Extended PLIST: In the first form, RO points to
the following parameter list:
(a)

(b)
(c)

(d)

DC
DC
DC
DC

A(COMVERB)
A(BEGARGS)
A(ENDARGS)
A( 0)

where the first three addresses are defined by:
COMVERB EQU *
DC C'cmdname'
BEGARGS EQU *
DC C'
ENDARGS EQU *

name of command
argument list

and where:
(a)
46

is the beginning address of the command.

VM/SP eMS for System Programming

... ·1

(b)
(c)

is the beginning address of the argument list.
is the address of the byte immediately following the end of the
argument list.
may be used to pass any additional information required by individual
called programs. If this word is not used to pass additional
information, it should be zero so that programs receiving optional
information via this word may detect that none is provided in this
call.

(d)

See page 51 for an example of an extended PLIST.

Notes:
1.

These four words can be moved to some location convenient for the
command resolution routines or convenient for some other program
executed between the caller's sve 202 and entry to the program that the
parameter list is intended. For this reason, the called program may not
assume additional words following word 4, or the called program may not
assume that the storage address of these 4 words bears any relationship to
other data addresses.

2.

For function calls in the System Product Interpreter, two additional
words are available. See the VM/ SP System Product Interpreter
Reference for more information on function calls and the two additional
words.

The Second Form of the Extended PLIST: The second form of an
extended PLIST is used by Enhanced Connectivity Facilities on VM/SP (see
SENDREQ in the VM/SP IBM Programmer's Guide to the Server-Requester
Programming Interface for VM/SP, SC24-5291). The second form provides a
way for a routine to:
o

Pass up to 64K-1 bytes of arbitrary data and 32K-5 bytes of parameters
to another routine

o

Receive up to 64K-1 bytes of arbitrary data and 32K-5 parameters from
another routine.

In the second form, RO points to the following parameter list:
(a)
(b)
(c)
(d)

DC
DC
DC
DC

A(commandname)
F
(reserved)
F
(reserved)
A(CPRB)

where:
(a) is
(b) is
(c) is
(d) is

the address of the name of the program being called
unused
unused
the address of the connectivity program request block (CPRB).

If your routine is being called by another routine, you can verify that your
routine is being called using the second form of an extended PLIST. Check
Chapter 5. Developing Programs under CMS

47

r::-:-_-==~·

____ ......................
the contents of A(CPRB)
CPRB.

+ 4. This address should contain the characters

If you want to call another routine using the second form of an extended
PLIST, see SENDREQ in the VM/SP IBM Programmer's Guide to the
Server-Requester Programming Interface for VM/ SP, SC24-5291.

Common SVC Calls
SVC conventions are important to any discussion of CMS because the
system is driven by SVCs (supervisor calls). SVCs 202 and 203 are the most
common CMS SVCs.
SVC 202

SVC 202 is the most commonly used SVC in the CMS system. It is used for
calling nucleus-resident routines, nucleus extensions, and routines written
as commands (for example, disk resident modules).
A typical coding sequence for an SVC 202 call is the following:
LA
SVC
DC

Rl,PLIST
202
AL4(ERRADD)

First, load the address of the parameter list into Rl and then issue an SVC.
The "DC AL4(address)" instruction following the SVC 202 is optional and
may be omitted if you do not expect any errors to occur in the routine or
command being called.
If the DC statement is included and the return code (RI5) contains a
nonzero value after returning from the SVC call, control passes to the
address specified in the DC unless the address is equal to 1. In the above
example, control would go to the instruction at the label ERRADD.
If the address is 1, return is made to the instruction following the "DC
AL4(1)" instruction. DMSITS determines whether this DC was inserted by
examining the byte following the SVC call. If the byte is nonzero, the
statement following the SVC 202 is an instruction. If the byte is zero, the
statement following the SVC 202 is either "DC AL4(address)" or "DC
AL4(1)".

If you want to ignore errors, you can use the sequence:
LA
SVC
DC

Rl,PLIST
202
AL4(l)

Whenever an SVC 202 is issued, the contents of general purpose registers 0
and 1 (RO and Rl) are passed to the called routine. Rl points to an
8-character string, which may be the start of a tokenized PLIST. This
character string contains the symbolic name of the routine or command
being called. The called routine decides whether to use the tokenized

48

VM/SP eMS for System Programming

/

, :J-').('"
II"(-.)~J\:.ln~;),
r'-j' Ul
~rj\'-J
r<)r,"!'':'-Jf'h'''}r
',cJ
,_1' \
.-,U '_
J
u
u ,.1
l.J ~_, u l l .J
u
\".__
'-.

..

[:=_::.~~-=:~-:-:~.-.,,:-_ _~:::-:-~: :::~~::-=~~-~~_'~~~:~~~.:~:=-=~:':'_:'='~'':'''~:

__ --':_

:~_ ,._~:,_"._

n
nr',')" 1. ',,\f 1 ;I~:\.'J(.~)
',_J.Jl \ _J',.-'U
' • ...JLJ'J " __

.... _. __.__':'.~_"':_,_:.:__.. __.. __ ..___ .._:~_.. _. __._. ___ ,:. . . .::,_ .. __..___. ,... ____ .. __ ., .,_" __.___ ,. ,_ .. ____ J

PLIST or the extended PLIST (one of two forms) by examining the
high-order byte of Rl. The SVC handler only examines the name and the
high-order byte of Rl.

Note: Although an extended PLIST is provided, the called routine might
not be set up to use it.
When a program gets control, it checks the value of the the high-order byte
of RI to determine what environment (EXEC, command line, etc.) it was
called from and if an extended PLIST is available. Then the program may
take appropriate action. CMS only places these values in the high-order
byte for the convenience of the program.
The following values may be found in the high-order byte of register 1:
E::tl3!!d~~l

PLIST
Pointer in
llcfjiGter O?

Value

IVlcnninG

X'OO'

The call did not originate from an EXEC
file or a command typed at the terminal.
(The SVC handler translates the value
X'04' to X'OO' before entering the called
program.)
Either the call is from an EXEC 2 EXEC
or the System Product Interpreter when
"ADDRESS COMMAND" is specified, or
the call is an Enhanced Connectivity
Facilities on VMjSP call (see SENDREQ
in the VMj SP IBM Programmer's Guide
to the Server-Requester Programming
Interface for VMj SP, SC24-5291). You can
tell by checking the form of the extended
PLIST, see "Extended PLIST" on page 46.
(The SVC handler translates the value
X'03' to X'OI' before entering the called
program.)
See "Dynamic LinkagejSUBCOM" on
page 59.
Used by the System Product Interpreter
for external function calls.
The command was invoked as an
immediate command. This setting should
never occur with SVC 202.
The command was called as a result of its
name being typed at the terminal, by the
CMDCALL command to invoke the
command from EXEC 2, or from a System
Product Interpreter EXEC when
"ADDRESS CMS" is specified.

X'OI'

X'02'
X'05'
X'06'

X'OB'

Figure 7 (Part 1 of 2).

No

Yes

Yes
Yes
Yes

Yes

SVC 202 High-Order Byte Values of Register 1

Chapter 5. Developing Programs under CMS

49

E:::rtended
PLIST
Pointer in
Register O?

Value

MeaninrJ

X'OC'

The call is the result of a command
invoked from a CMS EXEC file with
"&CONTROL" set to something other
than "NOMSG" or "MSG".
The call is the result of a command
invoked from a CMS EXEC file with
"&CONTROL MSG" in effect (indicates
that messages are to be displayed at the
terminal).
The call is the result of a command
invoked from an CMS EXEC file with
"&CONTROL NOMSG" in effect.
This is an end-of-command call from
DMSINT (CMS console command
handler). See the NUCEXT function in
the VM/ SP CMS Macros and Functions
Reference for details.
This is a service call from DMSABN
(abend) or from NUCXDROP. See the
NUCEXT function in the VM/ SP CMS
Macros and Functions Reference for
details.

X'OD'

X'OE'

X'FE'

X'FF'

Figure 7 (Part 2 of 2).

No

No

No

No

No

SVC 202 High-Order Byte Values of Register 1

Some CMS commands work differently when called from different
environments. An assembler language program can simulate the various
environments (listed in Figure 7 under "Meaning") by using the
appropriate high-order byte.
For example, to call the ERASE command from an assembler program and
to suppress error messages, the program uses a high-order byte of X'OE'.
This simulates a call from a CMS EXEC with "&CONTROL NOMSG" in
effect.
Some CMS commands can take advantage of an extended PLIST if it is
supplied. For example, the FILEDEF command uses the extended
parameter list when processing the DSN qual1[.qual2 ... ] parameter. The
following program shows how to set up an extended parameter list and call
FILEDEF. The high-order byte, X'OI', in the program example simulates a
call from an EXEC2 EXEC or the System Product Interpreter when
"ADDRESS COMMAND" is specified.

50

VMjSP eMS for System Programming

~jGi'J(3~O[')OuuU [Ju'(0UuJ~luullG o..~u··ucJ~)uJ (G~tfJ~)

_

c====-==-=-=..:-=--:::=...:_-_=.~~~=~~~..:.:==~-_~=~=-·:..:_~=::::·~=~:~~~·~ ..:_-_--._::=:~=_==-_~:=.=:=-:= .===~":'::==-=~=":~~~~~. ~~:~=~_":':~~==":':":=--:J

SAMPLE

CSECT

*
*
*

ISSUE 'FILEDEF SYSIN DISK A A A DSN G.TEMP.DATA.LIBRARY'

PLIST

*
*
*
EPLIST

COMVERB
BEGARGS
ENDARGS
*
*

REGEQU
USING *,R12
LR
R12,R15
LA
RO,EPLIST
LA
RI,PLIST
ICM
RI,B'IOOO' ,=X'OI'
SVC
202
AL4(l)
DC
BR
R14
DS
OF
DC
CLS'FILEDEF '
CLS'SYSIN'
DC
DC
CLS'DISK'
DC
CLS'A'
DC
CLS'A'
CLS'A'
DC
CLS'DSN'
DC
CLS'G.TEMP.D' NOTICE THAT THIS IS TRUNCATED
DC
BUT FILEDEF WILL USE THE
EXTENDED PARAMETER LIST
BELOW.
2F'-1'
DC
A (COMVERB)
DC
A(BEGARGS)
DC
DC
A(ENDARGS)
A(O)
DC
DC
C'FILEDEF '
EQU
*
DC
C'DISK A A A DSN G.TEMP.DATASET.LIBRARY'
ENDARG POINTS ONE CHARACTER
*
EQU
PAST THE END OF THE
PARAMETER LIST.
END

Refer to page 43 for a description of the contents of R12, R13, R14, and R15.

BVC 202 Return Codes: On return from SVC processing, register 15
contains one of the following return codes:

o

No errors occurred.

-1

A CP command with this name was not found.

-2

An attempt was made to execute a CMS command while in CMS subset
mode. This would have caused the module to be loaded in the user
area.

-3

A CMS command issued from EXEC was not found with this name, or
an invalid function occurred when the SET or QUERY command was
issued from EXEC with IMPCP active.

-4

The LOADMOD failed.

Chapter 5. Developing Programs under CMS

51

r~.J)c:'?\7c~~CDLJ)Duu£D [;)rOQW'f:luuuD ~.%ll(~Q~~ (~l~~QS:)

. --.-------..-.------.--.--.. - .

-.-.-~::-:-::=.===~::-=~-

-5

-.---------.---.:---:.::-:-~'-:---.-.--

. -.--.--..-------." ·'·1

A LOADMOD was issued in the wrong environment (for example, the
module was generated by the GENMOD command with the as option,
and LOADMOD was attempted with DOS = ON specifi~d).

SVC 203

sve 203 is called by eMS macros to perform various internal system
functions. It is used to define sve calls when no parameter list is provided.
For example, DMSFREE parameters are passed in registers 0 and 1.
A typical calling sequence for an sve 203 call is:
SVC
DC

203
H'code'

The halfword decimal code following the sve 203 indicates the specific
routine being called. DMSITS examines this halfword code taking the
absolute value of the code using a LPR instruction. The first byte of the
result is ignored, and the second byte of the resulting halfword is used as
an index into a branch table. The address of the correct routine is loaded,
and control is transferred to it.
It is possible for the address in the sve 203 index table to be zero. In this

case, the index entry contains an 8-byte routine or command name, which is
handled in the same way as the 8-byte name passed in the parameter list to
an sve 202.
The sign of the halfword code indicates whether the programmer expects an
error return. If an error return is expected, the code is negative. If the
code is positive, no error return is made. The sign of the halfword code has
no effect on determining the routine called since DMSITS takes the
absolute value of the code to determine the routine called.
Since only the second byte of the absolute value of the code is examined by
DMSITS, seven bits (bits 1-7) are available as flags or for other uses. For
example, DMSFREE uses these seven bits to indicate such things as
conditional requests and variable requests. Therefore, DMSITS considers
the codes X'3' and X'259' to be identical and handles them the same as X'-3'
and X'-259', except for error returns.
When an sve 203 is invoked, DMSITS stores the halfword code into the
NUeON location eODE203 so the called routine can examine the seven bits
made available to it.
All calls made by sve 203 should be made by macros with the macro
expansion computing and specifying the correct halfword code.

52

VM/SP eMS for System Programming

[DG'\JG~I1)~)Uu·~u
[~=--.:.:==~.:.~_.

[Ju'CGUu'c}u·u·uS

_.. __._.-_.._____.______-_. . _..._.--_. _. . -_.-._.-_-_-.-_--.--.---.... __
~

::.-.:~.

~~~.

__..:_._.

-.:.~_~..:

..

[L%l)(LJG~·
_.~~~

.. ___

.(CLtJS
._. _. .

.~~=_

~

~J

User-Handled SVCs

The programmer may use the HNDSVC macro to specify the address of a
routine that processes any SVC call for SVC numbers 0 through 200 and 206
through 255. If the HNDSVC macro is used, the linkage conventions are as
required by the user-specified SVC-handling routine. You cannot specify a
normal or error return from a user-handled SVC routine.
OS and VSE Macro Simulation SVC Calls

CMS supports selected SVC calls generated by OS and VSE macros by
simulating the effect of these macro calls. DMSITS is the initial SVC
interrupt handler. If the SET DOS command has been issued, a flag in
NUCON indicates that VSE macro simulation is to be used. Control is then
passed to DMSDOS. Otherwise, OS macro simulation is assumed and
Dr.1SITS passes control to the appropriate OS simulation routine.
DMSDOS acquires the specified SVC code from the OLDPSW field of the
current SVC save area. Using this code, DMSDOS computes the address of
the routine where the SVC is to be handled.
Many CMS/DOS routines (including DMSDOS) are contained in a
discontiguous shared segment (DCSS). Most SVC codes are executed
within DMSDOS, but some are in separate modules external to DMSDOS.
If the SVC code requested is external to DMSDOS, its address is computed
using a table called DCSSTAB. If the code requested is executed within
DMSDOS, the table SVCTAB is used to compute the address of the code to
handle the sve.
Invalid SVC Calls

There are several types of invalid SVC calls recognized by DMSITS.
1.

Invalid sve number. If the SVC number does not fit into any of the
classes described above, it is not handled by DMSITS. An error
message is displayed on your terminal, and control is returned directly
to the caller.

2.

Invalid routine name in SVC 202 parameter list. If the routine named
in the SVC 202 parameter list is invalid or cannot be found, DMSITS
handles the situation in the same way as it handles an error return
from a legitimate SVC routine. You receive an error code of -3.

3.

Invalid sve 203 code. If an invalid code follows SVC 203 inline, an
error message is displayed on your terminal and the abend routine is
called to terminate execution.

Chapter 5. Developing Programs under CMS

53

Search Hierarchy for SVC 202
SVC 202 Entered from a Program

When a program issues SVC 202 and passes a routine or command name in
the parameter list, DMSITS searches for the specified routine or command.
(In the case of SVC 203 with a zero in the table entry for the specified
index, the same logic must be applied.)
As soon as the routine or command name is found, the search stops and the
routine or command is executed. Figure 9 on page 58 and the following list
describe the search order.
1.

DMSITS determines if the specified name is known dynamically to CMS
through the SUBCOM function. This step is executed only if the
high-order byte of Rl contains X'02'.

2.

DMSITS searches for a nucleus extension routine with the specified
name.
Note: This step is skipped if the high-order byte of register 1 contains
X'03' or X'04'. X'03' indicates that an extended PLIST is provided. X'04'
indicates that a tokenized PLIST is provided. X'03' and X'04' are
translated to X'Ol' and X'OO', respectively, by the SVC interrupt handler
before the called program is entered.

3.

DMSITS searches for a routine with the specified name in the transient
area.

4.

DMSITS searches for a nucleus-resident command with the specified
name.

5.

DMSITS searches currently accessed disks for a file with the specified
name and a filetype MODULE. CMS uses the standard search order (A
through Z). If this search is successful, the specified module is loaded
(via the LOADMOD command) and control is passed to the storage
location now occupied by the command. The table of active (open) disk
files is searched first. An open file may be used ahead of a file that
resides on a disk earlier in the· search order.

6.

DMSITS calls
a.

DMSPKT to search the translation tables for the specified name. If
found, DMSITS searches for a routine with the valid translation by
repeating steps 2 through 5.
Note: This step is skipped if this SVC call is not from DMSINT or
DMSCSF.

54 VM/SP eMS for System Programming

L_~~.

___ .____.__ .____ ._.: __ .. _~.__ .__ .~__.___ .. _.. _ ..__... -':"" __ ._'. __ ~:'... _.___._ ......._. " ... _... _. __ ... _.... ____ ~__.__ ._: __ ~~_~~~_.~ __.~_::._:=~~:: __-_.::~. __. _- _:. __ .__.__ ~:~::~-':'J

b.

DMSINA to search the synonym tables for the specified name. If
found, DMSITS searches for a routine with the valid synonym by
repeating steps 2 through 5.

If all searches fail, then an error code of -3 is issued.
Commands Entered from the Terminal

When a command is entered from the terminal, DMSINT processes the
command line and calls the scan routine to convert it into a parameter list
consisting of 8-byte entries.
As soon as the command name is found, the search stops and the command
is executed. Figure 8 on page 57 and the following list describe the search
order.
1.

Search for an EXEC with the specified command name: 1
a. DMSINT searches for an EXEC in storage. If an EXEC with this
name is found, DMSINT determines whether the EXEC has a USER,
SYSTEM, or SHARED attribute. If the EXEC has the USER or
SYSTEM attribute, it is executed.
If the EXEC has the SHARED attribute, the INSTSEG setting is
checked. When INSTSEG is ON, all accessed disks are searched
and the access mode of the Installation Discontiguous Shared
Segment (DCSS) is compared to the mode of an EXEC with that
name that resides on disk. If the access mode of the DCSS is equal
to or higher than the disk mode, the EXEC is executed. Otherwise,
the EXEC on disk is executed.

b.

2.

DMSINT searches accessed disks for a file with the specified name
and filetype· EXEC. The table of active (open) disk files is searched
first. An open file may be used ahead of a file that resides on a disk
earlier in the search order.

DMSINT calls
a. DMSPKT to search the translation tables for the specified name. If
found, DMSINT searches for a routine with the valid translation by
repeating step 1.
b. DMSINA to search the synonym tables for the specified name. If
found, DMSINT searches for a routine with the valid synonym by
repeating step 1.

3.

DMSINT executes SVC 202, passing the scanned tokenized parameter
list, with the command name in the first eight bytes of the PLIST
pointed to by register 1 and the extended PLIST address in register O.

If implied EXEC is not in effect (SET IMPEX OFF), skip steps 1 and 2.
Chapter 5. Developing Programs under CMS

55

M8vG~(i)~d)UfJuf:~

[JrOCJG'ouuuG

QJr;uC~GfJ1

CL1!JS

.

[------.=-::-::-~==:==-==:=====-=-=.~.~.~==.==-:::::::.=.:=~ ~~:::~=:--~~:~=::-.::=-=.:::=~~==---==-=:-.--.--.

_._.. "-"'- .__ .- .

DMSITS performs the search for SVC 202 as described above in "SVC
202 Entered from a Program."
4.

DMSINT searches for a CP command with the specified name, using the
CP DIAGNOSE instruction. 2

5. If all of these searches fail, DMSINT displays the error message:
Unknown CP/CMS Command

2

If implied CP is not in effect (SET IMPCP OFF), skip step 4.

56 VM/SP CMS for System Programming

[--_....-

... _--

- - . - -- --- ._--

Read line from
terminal
("name ... ")

Expand the line b
inserting EXEC in
front of the
command name;
ie. 'EXEC name'

name is now a
real name from
a translation or
synonym table
No

Issue SVC 202
(See SVC 202
subroutine)

Notes:

1. If the command SET IMPEX OFF
hos been executed, implied EXEC
is not in effect.
2. This EXEC must exist in storage
or on DASD.

Poss line to CP
for processing

No

No

3. A -3 return code indicates SVC 202
processing did not find the command.

4. If the command SET IMPCP OFF
has been executed, implied CP is
not in effect.

Display
UNKNOWN
CP/CMS
COMMAND

Yes

Display Ready

~------------------------------------------------~ ~~~~a~:dew;:h
RC~-O

Figure 8.

CMS Command Processing

Chapter 5. Developing Programs under CMS

57

Figure 9. SVC 202 Processing

Command Search Function

SUBCOM provides a function that lets you invoke a command (from a
program) that is resolved according to the CMS command search hierarchy.
That is, the command is resolved just as though the command was entered
from the terminal. This SUBCOM function is named CMS. This command
search function checks the IMPEX and IMPCP settings of CMS SET.

58

VM/SP eMS for System Programming

[--

The CMS SUBCOM function is defined during system initialization at IPL
and remains defined during the entire CMS session.
To pass a command to the CMS SUBCOM function, the user should define
PLISTs as follows:
PLIST
EXPLIST

BEGARGS
ENDARGS

DS
DC
DS
DC
DC
DC
DC

OF
CL8'CMS'
OF
A(PLIST)
A(BEGARGS)
A(ENDARGS)

DS
DC
EQU

OF
C'command to be invoked'

A( 0)

*

Register 1 must contain the address of PLIST and a high order byte of X'02'.
Register 0 must contain the address of the extended PLIST. Having
established the PLIST and register information the user issues an SVC 202.
The X'02' in the high order byte of register 1 indicates that this is a call to
a previously defined SUBCOM.

Dynamic Linkage/SUBCOM
It is possible for a program that is already loaded from disk to become

dynamically known by name to CMS for the duration of the current
command; such a program can be called via SVC 202. In addition, this
program can also make other programs dynamically known if the first
program can supply the entry points of the other programs.
To become known dynamically to CMS, a program or routine invokes the
create function of SUBCOM. To invoke SUBCOM, issue the following
calling sequence from an assembler language program:
LA
SVC
DC

R1,PLIST
202
AL4(ERROR)

SUBCNAME
SUBCPSW

DS
DC
DC
DC

OF
CL8'SUBCOM'
CL8'narne'
XL2'0000'

SUBCADDR

DC
DC

AL2(O)
A(O)

DC

A(O)

PLIST

COMMAND NAME
SYSTEM MASK, STORAGE KEY,
ETC.
RESERVED
ENTRY ADDRESS, -1 FOR
QUERY PLIST
USER WORD

SUBCOM creates an SCBLOCK control block containing the information
specified in the SUBCOM parameter list. SVC 202 uses this control block
to locate the specified routine. All non-system SUBCOM SCBLOCKS are
released at the completion of a command (that is, when CMS displays the
ready message). A SUBCOM environment may be defined as a system
SUBCOM by setting a X'80' in the first byte of the interruption code field of

Chapter 5. Developing Programs under CMS

59

the PLIST. See VM/SP Data Areas and Control Block Logic Volume 2
(eMS) for a description of the SCBLOCK control block.
When a program issues an SVC 202 call to a program that has become
known to CMS via SUBCOM, it places X'02' in the high-order byte of
register 1. Control passes to the called program at the address specified by
the called program when it invoked SUBCOM.
The PSW in the SCBLOCK specifies the system mask, the PSW key to be
used, the program mask (and initial condition code), and the starting
address for execution. The problem-state bit and machine-check bit may be
set. The machine-check bit has no effect in CMS under CPo The EC-mode
bit and wait-state bit cannot be set. They are always forced to zero. Also,
one 4-byte, user-defined word can be associated with the SUBCOM entry
point and referred to when the entry point is subsequently called.
When control passes to the specified entry point, the register contents are:
R2
RI2
RIa
RI4
RI5

Address of SCBLOCK for this entry point.
Entry point address.
24-word save area address.
Return address (CMSRET).
Entry point address.

You can also use SUBCOM to delete the potential linkage to a program or
routine's SCBLOCK, or you can use SUBCOM to determine if an
SCBLOCK exists for a program or routine.
To delete a program or routine's SCBLOCK, issue:
DC
DC
DC

CL8'SUBCOM'
CL8'program or routine name'
8X'OO'

To determine if an SCBLOCK exists for a program or routine, issue:
DC
DC
DC
DC

CL8'SUBCOM'
CL8'program or routine name'
A(O) SCBLOCK addressed as a returned value
4X'FF'

Note that if 'SUBCOM name' is called from an EXEC file, the QUERY
PLIST is the form of PLIST that is issued.
To query the chain anchor, issue:
DC
DS
DS

CL8'SUBCOM'
CL8
AL4

DC

AL4(l)

(contents not relevant)
Will receive chain anchor
contents from NUCSCBLK
Indicates request for anchor

Note that the anchor is equal to F'O' if there are no SCBLOCKs on the
chain.

60

VM/SP eMS for System Programming

/'

L_.-. ____ ...~ .. _._____ .. __. __ ...

1

Note: If you create SCBLOCKS for several programs or routines with the
same name, they are all remembered, but SUBCOM uses the last one
created. A SUBCOM delete request for that name eliminates only the most
recently created SCBLOCK making active the next most recently created
SCBLOCK with the same name.

When control returns to CMS after a console input command has
terminated, the entire SUBCOM chain of SCBLOCKs is released. None of
the subcommands established during that command are carried forward to
be available during execution of the next console command.
SUBCOM Function Return Codes

Return codes from the SUBCOM function are:

o

Successful completion. A new SCBLOCK was created, the
specified SCBLOCK was deleted, or the specified program or
routine has an SCBLOCK.

1

No SCBLOCK exists for the specified program or routine. This is
the return code for a delete or a query.

25

No more free storage available. SCBLOCK cannot be created for
the specified program or routine.

Returning to the Calling Routine
When the called routine finishes processing, it returns control to DMSITS.
Then DMSITS returns control to the calling routine.
Return Location

The return is accomplished by loading the original SVC old PSW, which
was saved at the time DMSITS was first entered, after possibly modifying
the address field. The address field modification depends upon the type of
SVC call and upon whether the called routine indicated an error return.
For SVC 202 and 203, the called routine places a zero in register 15
indicating a normal return and a nonzero code in register 15 indicating an
error return. If the called routine indicates a normal return, DMSITS
makes a normal return to the calling routine. If the called routine
indicates an error return, DMSITS passes the error return address to the
calling routine, if one was specified. If no error return address was
specified, DMSITS abnormally terminates.
For an SVC 202 not followed by "DC AL4(address)" or "DC AL4(1)", a
normal return is made to the instruction following the SVC instruction and
an error return causes an abend. For an SVC 202 followed by "DC
AL4(address)", a normal return is made to the instruction following the DC
and an error return is made to the address specified in the DC, unless the
address is equal to 1. If the address is 1, return is made to the next

Chapter 5. Developing Programs under CMS

61

[Q)Gt'7G~(i)~]UUu[j ~"2)~1~g!r8UuuG n.mucJG[j" ~L0~S)
c=.___ ._____.____________._______._.__________.____________._._________._____._.__________________________

~:::==========_==J

instruction after the "DC AL4(1)" instruction. In either case, register 15
contains the return code passed back by the called routine.
For an SVC 203 with a positive halfword code, a normal return is made to
the instruction following the halfword code and an error return causes an
abend. For an SVC 203 with a negative halfword code, both normal and
error returns are made to the instruction following the halfword code. In
any case, register 15 contains the return code passed back by the called
routine.
For OS macro simulation SVC calls and user-handled SVC calls, no error
return is recognized by DMSITS. As a result, DMSITS always returns to
the calling routine by loading the SVC old PSW that was saved when
DMSITS was first entered.
Register Restoration

Upon entry to DMSITS, all registers are saved as they were when the SVC
instruction was first executed. Upon exiting from DMSITS, all registers are
restored to the values that were saved at entry.
The exception to this is register 15 for SVC 202 and 203. Upon return to
the calling routine, register 15 always contains the value that was in
register 15 when the called routine returned to DMSITS after it had
completed processing.
Modification of the System Save Area

If the called routine has system status so that it runs with a PSW storage
protect key of 0, it may store new values into the system save area.
If the called routine wishes to modify the location where control is to be
returned, it must modify the following fields:

o

For SVC 202 and 203, the called routine must modify the NRMRET and
ERRET (normal and error return address) fields.

o

For other SVCs, the called routine must modify the address field of
OLDPSW.

To modify the registers that are returned to the calling routine, the fields
EGPR1, EGPR2, through EGPR15 must be modified.
If this action is taken by the called routine, the SVCTRACE facility may
print misleading information, since SVCTRACE assumes that these fields
are exactly as they were when DMSITS was first entered. Whenever an
SVC call is made, DMSITS allocates two save areas for that particular SVC
call. Save areas are allocated as needed. For each SVC call, a system and
user save area are needed.

When the SVC-called routine returns, the save areas are not released. They
are kept for the next SVC. If the routine invoked by the SVC called the
parsing facility, any storage allocated by the parsing facility for parsing

62

VM/SP eMS for System Programming

L..:........____ _ _ _
...._..._... _... _... _.
~

results is released upon return. At the completion of each command, all
SVC save areas allocated by that command are released.
DMSITS uses the system save area to save the .value of the SVC old PSW at
the time of the SVC call, the calling routine's registers at the time of the
call, and any other necessary control information. Since SVC calls can be
nested, there can be several of these save areas at one time. The system
save area is allocated in protected free storage.
The user save area (DSECT EXTUAREA) contains 12 doublewords (24
words) allocated in unprotected free storage. DMSITS does not use this
area at all. It simply passes a pointer to this area (via register 13). The
called routine can use this area as a temporary work area or as a register
save area. Each system save area has one user save area. The USAVEPTR
field in the system save area points to the user save area.
The exact format of the system save area can be found in the VMj SP Data
Areas and Control Block Logic Volume 2 (CMS). The most important fields
and their uses are as follows:

Field

Usage

CALLER

(Full word) The address of the SVC instruction that resulted
in this call.

CALLEE

(Doubleword) 8-byte symbolic name of the called routine.
For OS and user-handled SVC calls, this field contains a
character string of the form SVC nnn, where nnn is the SVC
number in decimal.

CODE

(Halfword) For SVC 203, this field contains the halfword
code following the SVC instruction line.

OLDPSW

(Doubleword) The SVC old PSW at the time that DMSITS
was entered.

NRMRET

(Fullword) The address of the calling routine where control
is passed in case of a normal return from the called routine.

ERRET

(Fullword) The address of the calling routine where control
is passed in case of an error return from the called routine.

EGPRS

(16 Fullwords, separately labeled EGPRO, EGPRl, EGPR2,
EGPR3, ... , EGPRI5) The entry registers. The contents of
the general purpose registers at entry to DMSITS are stored
in these fields.

EFPRS

(4 Doublewords, separately labeled EFPRO, EFPR2, EFPR4,
EFPR6) The entry floating-point registers. The contents of
the floating-point registers at entry to DMSITS are stored in
these fields.

,.
Chapter 5. Developing Programs under CMS

63

SSAVENXT

(Fullword) The address of the next system save area in the
chain. This points to the system save area being used, or
will be used, for any SVC call nested in relation to the
current one.

SSAVEPRV

(Full word) The address of the previous system save area in
the chain. This points to the system save area for the SVC
call in relation to where the current call is nested.

USAVEPTR

(Full word) Pointer to the user save area for this SVC call.

The eMS Subset Environment
When you issue the XEDIT subcommand:
ems

the editor responds:
eMS subset

and your virtual machine is in CMS subset mode. When in subset mode,
you can issue any valid CMS subset command, that is, a CMS command
that is allowed in CMS subset mode. The commands that are not allowed in
the CMS subset environment are commands that execute in the user area.
You can also issue CP commands. To return to edit mode, you use the
special CMS subset command, RETURN. If you enter the Immediate
command HX, your editing session terminates abnormally and your virtual
machine returns to the CMS environment.
When entering CMS subset mode either for a single command or until the
string 'RETURN' is entered, the following processing is done to ensure that
the previous environment is preserved. Upon entry to subset, a check is
made to determine if this entry would constitute a recursion, if so, return
code 1 is returned.
1.

ST AE, SPIE, and STAX information is saved and then cleared.

2.

The OS environment settings are saved and then cleared so that any
module that issues an OSRESET based on these flags will not do so.

3.

The read and write pointers from any currently opened files are saved.

4.

All files are then closed by a 'FINIS * * *', but files with a filemode of 3
are not erased.

5.

Any FSTs that were built by a previous call to STATE are saved.

If the entry to subset was just for the execution of a single command, the
entry message is suppressed and the next command is executed immediately.
But, if the request was to enter CMS subset for an indefinite duration, an

64

VM/SP OMS for System Programming

[

_ _ _ . _ _ _ _ •••. _ _ ••••• u

................_ .••.••.

~._

...•_

..........

_ . • • • • . _ •. _

•••. _

• . h _ . • . • _ _ _ • • . _ _ • _ _ _ . • _ • • • • • • • _ _ . _ . _ _ _ •• _ . _ •• _ . _ _ _ _ _ _ _ _ _ • _ _ . _ . _ _ • _ _ _ •

announcement of entry to the CMS subset environment is made. This is
done so that a strict differentiation from the strict command environment is
given.
The principle difference in subset is the restriction that any command
executed may not use any storage other than DMSFREE storage and the
transient area. This protects programs which may be running in the USER
AREA. Also, any ready message issued from subset is in the abbreviated
form (i.e. identical to SET RDYMSG SMSG) so that program timing
information is not affected for the command currently in progress at the
time of subset entry.
Upon termination of CMS subset mode any settings or values that were
saved upon entry to subset are restored.

Assembiing Programs
To assemble assembler language source programs into object module
format, you can use the ASSEMBLE command, .and specify assembler
options on the command line. For example:
assemble myfile (print

assembles a source program named MYFILE ASSEMBLE and directs the
output listing to the printer. All of the ASSEMBLE command options are
listed in the VM/SP CMS Command Reference.
When you invoke the ASSEMBLE command specifying a file with the
filetype of ASSEMBLE, CrdS searches all of your accessed disks, using the
standard search order, until it locates the specified file. When the
assembler creates its output listing and text deck, it creates files with
filetypes of LISTING and TEXT, and writes them onto disk according to the
following priorities:
1.

If the source file is on a read/write disk, the TEXT and LISTING files

are written onto that disk.
2.

If the source file is on a read-only extension of a read/write disk, the

TEXT and LISTING files are written onto the parent disk.
3. If the source file is on any other read-only disk, the TEXT and LISTING
files are written onto the A-disk.
4.

If none of the above choices are available, the command is terminated.

In all of the above cases, the TEXT and LISTING files have a filename that
is the same as the input ASSEMBLE file.
The input and output files used by the assembler are assigned by FILEDEF
commands that CMS issues internally when the assembler is invoked. If
you issue a FILEDEF command using one of the assembler ddnames before

Chapter 5. Developing Programs under CMS

65

you issue the ASSEMBLE command, you can override the default file
definitions.
The ddname for the source input file (SYSIN) is ASSEMBLE. If you enter:
filedef assemble reader
assemble sample

then the assembler reads your input file from your card reader and assigns
the filename SAMPLE to the output TEXT and LISTING files.
You could assemble a source file directly from an

as disk by entering:

filedef assemble disk myfile assemble b4 dsn os source file
assemble myfile

In this example, the CMS file identifier MYFILE ASSEMBLE is assigned to
the data set OS.SOURCE.FILE and then assembled.
LISTING and TEXT are the ddnames assigned to the SYSPRINT and
SYSLIN output of the assembler. You might assign file definitions to
override these defaults as follows:
fi1edef listing disk assemble listfile a
flledef text disk assemble textfile a
assemble myfile

In this example, output from the assembly of the file, myfile ASSEMBLE, is
written to the files, ASSEMBLE LISTFILE and ASSEMBLE TEXTFILE.
The ddnames PUNCH and CMSLIB are used forSYSPUNCH and SYSLIB
data sets. PUNCH output is produced when you use the DECK option of
the ASSEMBLE command. The default file definition for CMSLIB is the
macro library CMSLIB MACLIB, but you must still issue the GLOBAL
command if you want to use it.

Executing Programs
After you have assembled or compiled a source program, you can execute
the TEXT files that were produced by the assembly or compilation. You
may not, however, be able to ~xecute all ,your as programs directly in CMS.
There are a number of execution-time restrictions placed on your virtual
machine by VM/SP. You cannot execute a program that uses:
•
•
•
•
•

66

Multitasking
More than one partition
Teleprocessing
IS AM macros to read or write files
The PSW EC mode bit

VM/SP eMS for System Programming

The above is only a partial list of restrictions you might be concerned with.
For a complete list of restrictions, see the VMjSP Planning Guide and
Reference.

Executing TEXT Files
TEXT files, in CMS, are relocatable and can be executed simply by loading
them into virtual storage with the LOAD command and using the START
command to begin execution. For example, if you have assembled a source
program named CREATE, you have a file named CREATE TEXT. You can
issue the command:
load create

that loads the relocatable object file into storage. Then, to execute it, you
can issue the START command:
start

In the case of a simple program, as in the above example, you can load and
begin execution with a single command line, using the START option of the
LOAD command:
load create (start

When you issue the START command or LOAD command with the START
option, control is passed to the first entry point in your program. If you
have more than one entry point and you want to begin execution at an
entry point other than the first, you can specify the alternate entry point or
CSECT name on the START command:
start create2

When you issue the LOAD command specifying the filename of a TEXT file,
CMS searches all of your accessed disks for the specified file.
If your program expects a parameter list to be passed (via register 1), you
can specify the arguments on the START command line. If you enter
arguments, you must specify the entry point:
start

*

narnel

When you specify the entry point as an asterisk (*), it indicates that you
want to use the default entry point.
Defining Input and Output Flies

You can issue the FILEDEF command to define input and output files any
time before you begin program execution. You can issue all your file
definitions before loading any TEXT files, or you can issue them during the
loading process. You can find out what file definitions are currently in
effect by issuing the FILEDEF command with no operands. You can also
use the FILEDEF operand of the QUERY command.

Chapter 5. Developing Programs under CMS

67

~1r:~\7~)~O[-vDUl}fj fDL"O['JG 8uu'Uf) ~nuucJc~G~ Gr\~s
1

.

..

....--:-:---.--:--:1

[::~~:.:~~~~~::-"- ~-:-:~~:~~-==_~===::-::~~=~===.~:=~~"'::"=-'::-~~-=" ~=:~~~----.-.-.----.-.~-.----~----

Resolving External References
The CMS loader loads files into storage as a result of a LOAD or INCLUDE
command. When a file is loaded, the loader checks for unresolved
references. If there are any, the loader searches your disks for TEXT files
with filenames that match the external entry name. When it finds a match,
it loads the TEXT file into storage. If a TEXT file is not found, the loader
searches any available TXTLIBs for members that match. If a match is
found, it loads the member;
If there are still unresolved references, for example, if you load a program
that calls routines PRINT and ANALYZE but the loader cannot locate
them, you receive the message:
The following names are undefined:

PRINT
ANALYZE

You can issue the INCLUDE command to load additional TEXT files or
TXTLIB members into storage so die loader can resolve any remaining
references. For example, if you did not identify the TXTLIB that contains
the routines you want to call, you may enter the GLOBAL command
followed by the INCLUDE command:
global txtlib newlib
include print analyze (start

A failure to resolve external references might occur if you have TEXT files
with filenames that are different from either the CSECT names or the entry
names. You must explicitly issue LOAD and INCLUDE commands for these
files.
At execution time, if there are still any unresolved references, their
addresses are all set to 0 by the loader; so any attempt to address them in a
program may result in a program check.

Controlling the CMS Loader
The LOAD and INCLUDE Commands

The INCLUDE command has the same format and option list (with one
exception) as the LOAD command. The main difference is that when you
issue the INCLUDE command the loader tables are not reset. If you issue
two LOAD commands in succession, the second LOAD command cancels the
effect of the first and the pointers to the files loaded are lost.
Conversely, the INCLUDE command, which you must issue when you want
to load additional files into storage, should not be used unless you have just
issued a LOAD command. You may specify as many INCLUDE commands
as necessary following a LOAD command to load files into storage.
/'

68

VM/SP eMS for System Programming

~

lDGuG~co~)a~u~ ~·)G'(o~UG·'C:1ulnG QJu'~(Jc::[j' !(~~\fJ~~
.
__ ___

. -.. ---- . --..-..----.-. ------.--.---------------------.. -----.---.-----.---... -..---. --.--.--.. -.---.. .-

~._-:.~: _.=_~.=- ~::_=~=._:.~-:-~-~:-:::~=~

=~_:..=

~:'::~J

The LOAD and INCLUDE commands allow you to specify a number of
options. You can:
o

Change the entry point to which control is to be passed when execution
begins (RESET option).

o

Specify the location in virtual storage at which you want the files to be
loaded (ORIGIN option).

o

Control how CMS resolves references and handles duplicate CSECT
names (AUTO, LIBE, and DUP options).

o

Clear storage to binary zeros before loading files (CLEAR option).
Otherwise, CMS does not clear user storage.

o

Save the relocation information from the text files (RLDSAVE option).
If the RLDSAVE option is not specified on the LOAD and INCLUDE
commands, the relocation information will not be saved for the fi~es
being loaded into storage.

o

Save history information from the text files (HIST option). If the HIST
option is not specified on the LOAD or INCLUDE commands, history
information (comments) is not saved for the files being loaded into
storage.

When the LOAD and INCLUDE commands execute, they produce a load
map, indicating the entry points loaded and their virtual storage locations.
You may find this load map useful in debugging your programs. If you do
not specify the NOMAP option, the load map is written onto your A-disk in
a file named LOAD MAP A5. Each time you issue the LOAD command, the
old file LOAD MAP is erased and the new load map replaces it. If you do
not want to produce a load map, specify the NOMAP option.
You can find details about these options under the LOAD command in the
VM/ SP CMS Command Reference.
Loader Control Statements

In addition to the options provided with the LOAD and INCLUDE
commands that assist you in controlling the execution of TEXT files, you
can also use loader control statements. These can be inserted in TEXT
files, using the CMS editor. The loader control statements allow you to:
o

Set the location counter to specify the address where the next TEXT file
is to be loaded (SLC statement).

o

Modify instructions and constants in a TEXT file, and change the
length of the TEXT file to accommodate modifications (Replace and
Include Control Section statements).

o

Change the entry point (ENTRY statement).

Chapter 5. Developing Programs under CMS

69

L . ___ .______ ._____ _

•

Nullify an external reference so that it does not receive control when it
is called, and you do not receive an error message when it is
encountered (LIBRARY statement).

These statements are also described under the LOAD command in the
VM/ SP eMS Command Reference.
Determining Program Entry Points

When you load a single TEXT file or a TXTLIB member into storage for
execution, the default entry point is the first CSECT name in the object file
loaded. You can start execution at a different entry point by specifying the
entry point on the LOAD (or INCLUDE) command with the RESET option.
load myprog (reset beta

where BETA is the alternate entry poin~ of your program, or you can
specify the ~ntry point on the START command line:
start beta

When you load multiple TEXT files (either explicitly or implicitly by
allowing the loader to resolve external references), you also have the option
of specifying the entry point on the LOAD, INCLUDE, or START command
lines.
If you do not specifically name an entry point, the loader determines the

entry point for you according to the following hierarchy:
1.

An entry point specified on the START command

2.

The last entry specified with the RESET option on a LOAD or
INCLUDE command

3.

The name on the last ENTRY statement that was read

4.

The name on the last LDT statement that contained an entry name that
was read

5.

The name on the first assembler- or compiler-produced END statement
that was read

6.

The first byte of the first control section loaded.

For example, if you load a series of TEXT files that contain no control
statements and do not specify an entry point on the LOAD, INCLUDE, or
START commands, execution begins with the first file that you loaded. If
you want to control the execution of program subroutines, you should be
aware of this hierarchy when you load programs or when you place them in
TXTLIBs.
An area of particular concern is when you issue a dynamic load (with the
OS LINK, LOAD, or XCTL macros) from a program, and you call members

70

VM/SP eMS for System Programming

[)GUG~6~)Duu~ ~J[['(QtJ[iC}uX;)8
L_.::

~~._~-_

.____

._._~.

____._n.__________...:

. ---.... ------

~~ =~-=-===~~=--=---====-==..::~=:::~:::= ~--

-.------.--~---

o.auuCC]8r/

----.----------.. . .-.-_-

C~JJ8

u._ --.---.-- --- -----,

of CMS TXTLIBs. The CMS loader determines the entry point of the called
program and returns the entry point to your program. If a TXTLIBmember
that you load has a VCON to another TXT LIB member, the LDT card from
the second member may be the last LDT card read by the loader. If this
LDT card specifies the name of the second member, CMS may return that
entry point address to your program rather than the address of the first
member.

Creating Program Modules
When your programs are debugged and tested, you can use the LOAD and
INCLUDE commands, in conjunction with the GENMOD command, to
create program modules. A module is a file whose external references have
been resolved. In CMS, these files must have a filetype of MODULE.
To create a nonrelocatable module file, load the TEXT files or TXTLIB
members into storage and issue the GENMOD command:
load create analyze print
genmod process

The module is generated at the virtual storage address where it is loaded.
In this example, PROCESS is the name of the module file, and it has a
filetype of MODULE. You could use any name; if you use the name of an
existing MODULE file, the old one is replaced.
To execute the program composed of the source files CREATE, ANALYZE,
and PRINT, enter:
process

If PROCESS requires input and/or output files, you have to define these
files before PROCESS can execute properly. If PROCESS expects
arguments passed to it, you can enter them following the MODULE name.
For example,
process testl

If you want to call your own programs or CMS program modules using SVC
202 instructions, you must be careful not to execute a module that uses the
same area of storage that your program occupies. If you want to call a
module that executes at location X'20000', you can load the calling program
at a higher location. For example,
load create (origin 30000

As long as the MODULE file called by CREATE is no longer than X'lOOOO'
bytes, it will not overlay your program.
You can also use the LOAD and GENMOD commands to create a
relocatable CMS module file. However, you must specify the RLDSA VE
option in the LOAD command:

Chapter 5. Developing Programs under CMS

71

[]G\7G~(D[]IDuuS~l [)~1V[~[i18[jlruEi ~ . %U(~G[' (~~v18
r-----------.-----:~=_=_=~~.-----:-~.-.----------~_:_:_:=. ~

. . :.:~_~:.:.:... :.:~:::~:.:~:._.=~~_====.~==____ ===::_:_==___:~-=-:-::-~=.==_====._._._ ..J

load progone (RLDSAVE
genmod progtwo
The relocatable CMS module file may now be established as a nucleus
extension by issuing the NUCXLOAD command:
nucxload progtwo
Relocatable CMS module files may also be used with the LOADMOD
command (for example, when issued as a command from the console). No
relocation is performed when the LOADMOD command is used. Relocation
is performed only when loaded by NUCXLOAD.
You can use the LOAD, INCLUDE, and GENMOD commands to create a
module that includes history information (comments) from the text file
used. For example:
load progone (HIST
include progtwo (HIST
genmod
The generated module contains the comments that were in the text files
progone and progtwo.
Note: Many CMS disk-resident command modules execute in the user
program area. That is, if you call a CMS command that runs in the user
program area, you must be certain that it does not overlay your own
program. Some CMS command modules issue the STRINIT macro or were
created using the STR option of the GENMOD command.
Both cause the user area storage pointers to be reset. The reset condition
may cause errors upon return to the original program (for example, when
OS GETMAIN/FREEMAIN macros are issued in the user program).
The CMS commands that execute in the user program area or that reset the
user area storage pointers are identified in the VM/ SP CMS Command
Reference.

The Transient Program Area
To avoid overlaying programs executing in the user program area, you can
generate program modules to run in the CMS transient area, which is a
two-page area of storage reserved for the execution of programs that are
called frequently. Many CMS commands run in this area, which is located
at X'EOOO'. Programs that execute in this area run disabled.
To generate a module to run in the transient area, use the ORIGIN TRANS
option when you load the TEXT file into storage, then issue the GENMOD
command. For example,
load myprog (origin trans
genmod setup (str

72

VM/SP eMS for System Programming

L~_'

.--.- -..

-----=:~.~:

___________________ . __._. ___ .. _._. ______ .____..:_. . _... __...-. ________
"" _.:: __________ __:___________ __
~

~ ~_:_.

____

.~_~-~_:...._=_~~=:=.~.:J

Note: If a program running in the user area calls a transient routine in
which a module was generated using the GENMOD command with the STR
option, the user area storage pointers are reset. This reset condition could
cause errors upon return to the original program (for example, when OS
GETMAIN/FREEMAIN macros are issued in the user program).
The two restrictions placed on command modules executing in the transient
area are:
1.

They may have a maximum size of 8192 bytes (the size of the transient
area).

2.

They must be serially reusable. When a program is called by an SVC
202 and if it is already loaded into the transient area, it is not reloaded.

The CMS commands that execute in the transient area are identified in the
VM/SP CMS Command Reference.

Creating EXEC Procedures
Depending on how you code your programs and EXECs, you can choose
whether or not they will be recognized for translation into other languages.
CMS only recognizes translations for commands entered from the command
line (or with ADDRESS CMS from REXX or &PRESUME
&SUBCOMMAND CMS from EXEC 2). CMS does not translate your
command name or keywords if you SET TRANSLATE OFF or if you invoke
the command from another program using SVC 202 (or with ADDRESS
COMMAND from REXX or &PRESUME &COMMAND CMS from EXEC 2).
For more information on command translation, refer to "Chapter 7.
Developing Commands and Message Files" on page 113.
During your program development and testing cycle, you may want to
create EXEC procedures to contain sequences of CMS commands that you
execute frequently. For example, if you need a number of MACLIBs,
TXTLIBs, and file definitions to execute a particular program, you might
have an EXEC procedure as follows:

Chapter 5. Developing Programs under CMS

73

L

___________________._______ __________._______________________. _ _
~.

-::~~

=_===~_:::=J

/* EXEC to set up environment to run program TESTA */
signal on error
'GLOBAL MACLIB TESTLIB OSMACRO OSMACR01'
'ASSEMBLE TESTA'
'PRINT TESTA "LISTING'
'GLOBAL TXTLIB TESTLIB PROGLIB'
'ACCESS 200 E'
push 'OS.TEST3.STREAM.BETA'
'FILEDEF INDD1 E DSN ?'
'FILEDEF INDD2 READER'
'FILEDEF OUTFILE DISK TEST DATA A1'
signal off error
'LOAD TESTA (START'
select
when rc = 100 then do

end
when rc

200 then do

end
otherwise
exit rc
end
Error:
say 'Error occurred on line' sigl':' sourceline(sigl)
exit rc

The "signal on error" control statement in the EXEC procedure ensures
that if an error occurs during any part of the EXEC, the remainder of the
EXEC does not execute, and the "Error:" displays the line number where
the error occurred as well as the actual command which gave the error.
Note: For the FILEDEF command entered with the DSN ? operand, you
must stack the response (using "push") before issuing the FILEDEF
command.

When your program is finished executing, the REXX special variable RC
indicates the contents of general register 15 at the time the program exited
(the "Return Code"). You can use this value to perform additional steps in
your EXEC procedure. Additional steps are indicated in the preceding
example by ellipses.

74

VM/SP eMS for System Programming

~JGt7(3~([)~")auutJ ~·Ju·OUu·8u-lru8
c-----------------·... ---·--·_----·--------.-·----··-.-.-.------------.-----. ---.--.. ---_-._-.--_"_ __

QJu"u([JGu

J

G~U'JS

- .--.. - ----------.----.::.:::1

eMS Macro Instruciions
There are a number of assembler language macros distributed with the
CMS system that you can use when you are writing programs to execute in
the CMS environment. These macros are in the macro libraries CMSLIB
MACLIB and DMSSP MACLIB, which are normally located on the system
disk.
o
o

CMSLIB MACLIB contains macros from VM/370.
DMSSP MACLIB contains macros that are new or changed in VM/SP.

Note: When assembling programs that use CMS macros, both of these
libraries should be identified via the GLOBAL command. DMSSP
should precede CMSLIB in the search order.
There are macros to manipulate CMS disk files, to handle terminal
communications, to manipulate unit record and tape input/output, and to
trap interruptions. These macros are discussed in general terms here. For
complete format descriptions, see the VMj SP eMS Macros and Functions
Reference.

Disk File Manipulation
Disk files are described in CMS by means of a file system control block
(FSCB). The CMS macro instructions that manipulate disk files use FSCBs
to identify and describe the files. When you want to manipulate a CMS file,
you can refer to the file by its file identifier, specifying 'filename filetype
filemode' in quotation marks, or you can refer to the FSCB for the file,
specifying FSCB = fscb, where fscb is the label on an FSCB macro.
To establish an FSCB for a file, use the FSCB macro instruction specifying
a file identifier. For example,
INFILE

FSCB

'INPUT TEST AI'

You can also provide, on the FSCB macro instruction, descriptive
information to be used by the input and output macros. If you do not code
an FSCB macro instruction for a file, an FSCB is created in-line (following
the macro instruction) when you code an FSREAD, FSWRITE, or FSOPEN
macro instruction.
The format of an FSCB and a description of each of the fields are listed
below.
Label
FSCBCOMM DC

CL8'

Figure 10 (Part 1 of 2).

,

Description
File system command

FSCB Format

Chapter 5. Developing Programs under CMS

75

L ____________________________________

_._ .. _.. J

Label

,
,
,

FSCBFN

DC

CL8'

FSCBFT

DC

CL8'

FSCBFM

DC

CL2'

FSCBITNO DC

H'O'

FSCBBUFF DC

A'O'

FSCBSIZE DC

F'O'

FSCBFV

DC

CL2'F'

FSCBFLG

EQU

FSCBFV+l

FSCBNOIT DC

H'l'

FSCBNORD DC

AL4(O)

FSCBAITN DC

AL4(O)

FSCBANIT DC

AL4(l)

FSCBWPTR DC

AL4(O)

FSCBRPTR DC

AL4(O)

Figure 10 (Part 2 of 2).

Description
Filename
Filetype
Filemode
Relative record number (RECNO)
Address of buffer (BUFFER)
Number of bytes to read or write
(BSIZE)
Record format - F or V (RECFM)
Flag byte
Number of records to read or
write (NOREC)
Number of bytes actually read
Extended FSCB relative record
number
Extended FSCB relative number
of records
Extended FSCB relative write
pointer
Extended FSCB relative read
pointer

FSCB Format

The FSCBAITN, FSCBANIT, FSCBWPTR, and FSCBRPTR fields are only
generated in the FSCB when the extended format FSCB is requested
(FORM = E is coded on the FSCB macro instruction). In this case, the
FSCBITNO and FSCBNOIT fields are reserved fields. Extended format
FSCBs must be used to manipulate files larger than 65,533 items. The
labels shown above are not generated by the FSCB macro. To reference
fields within the FSCB by these labels, you must use the FSCBD macro
instruction to generate a DSECT.
FSCBCOMM: When the FSCBFN, FSCBFT, and FSCBFM fields are filled
in, you can fill in the FSCBCOMM field with the name of a CMS command
and use the FSCB as a parameter list for an SVC 202 instruction. (You
must place a delimiter to mark the end of the command line.)
FSCBFN, FSCBFT, FSCBFM: The filename, filetype, and filemode fields
identify the CMS file to be read or written. You can code the fileid on a
macro line in the format 'filename filetype filemode', or you can use register
notation. If you use register notation, the register you specify must point
to an IS-byte field in the format:
FILEID

76

DC
DC
DC

VM/SP eMS for System Programming

CL8'filename'
CL8'filetype'
CL2'filemode'

[Dc:rJG~([)~JDuuO l")u~V&Ju'8ulJuG
(~=-=~~:~--=-=~=~=--=~~.=--.=-=:~.:.-:..:~~:~--==-~--=-=.::~~==--==:~

GJDucJeu'

G~v'JS

. _-- . - -.. _- --.- - - - - - - - - - - - - - ------------------'

The fileid must be specified either in the FSCB for a file or on the FSREAD,
FSWRITE, FSOPEN, or FSERASE macro instruction that references the
file.

FSCBITNO: For an FSCB without the FORM = E option, the record or
item number indicates the relative record number of the next record to be
read or written. It can be changed with the RECNO option. The default
value for this field is O. When you are reading a file, a 0 indicates that
records are to be read sequentially beginning with the first record in the
file. When you are writing a file and the file already exist, a 0 indicates
that records are to be written sequentially beginning at the first record
following the end of the file. If the file is a new file, begin writing at record
1.

For an FSCB generated with the FORM = E option, the FSCBAITN field
contains the record or item number. The FSCBITNO field is reserved.
Whenever you read discontiguous files in CMS (that is, files with missing
records), the input buffer will be filled with the appropriate number of
bytes. Be aware that the flag byte in the FSCB may not reflect whether the
input buffer contains generated data items from RDBUF.

FSCBB UFF: The buffer address, specified in the BUFFER option,
indicates the label of the buffer where the record is to be written from or
where the record is to be read into. You should always supply a buffer
large enough to accommodate the longest record you expect to read or
write. This field must be specified either in the FSCB or on the FSREAD or
FSWRITE macro instruction.
FSCBSIZE: This field indicates the number of bytes that are read or
written with each read or write operation. The default value is O. If the
buffer that you use represents the full length of the records you are going
to be reading or writing, you can use the BSIZE option to set this field
equal to your buffer length. When you are writing variable-length records,
use the BSIZE operand to indicate the length of each record you write.
This field must be specified.
FSCBFV: This two-character field indicates the record format (RECFM) of
the file. The default value is F (fixed).
FSCBFLG: The flag byte is X'20' indicating an extended FSCB is
generated when the FORM = E option is coded on the FSCB macro
instruction.
FSCBNOIT: For an FSCB without the FORM = E option, this field
contains the number of whole records to be read or written in each read or
write operation. You can use the NOREC option with the BSIZE option to
block and deblock records.
For an FSCB generated with the FORM = E option, the FSCBANIT field
contains the number of whole records to be read or written. The
FSCBNOIT field is reserved.

Chapter 5. Developing Programs under CMS

77

FSCBNORD: Following a read operation, this field contains the number
of bytes actually read, so if you are reading a variable-length file, you can
determine the size of the last record read. The FSREAD macro instruction
places the information from this field into register O.
FSCBAITN: The alternate record or item number indicates the 'relative
record number of the next record to be read or written in an extended FSCB
format. See the description of the FSCBITNO field for the usage of this
field.
FSCBANIT: This field contains the alternate number of whole records in
an extended FSCB format. See the description of the FSCBNOIT field for
the usage of this field.
FSCB WPTR: The FSPOINT macro instruction uses this field to contain
the alternate write pointer for an extended FSCB during a POINT
operation.
FSCBRPTR: The FSPOINT macro instruction uses this field to contain
the alternate read pointer for an extended FSCB during a POINT operation.
Using the File System Control Block (FSCB)

The following example shows you how to code an FSCB macro instruction
to define various file and buffer characteristics and how to use the same
FSCB to refer to different files:
FSREAD 'INPUT FILE Al' ,FSCB=COMMON,FORM=E
FSWRITE 'OUTPUT FILE Al',FSCB=COMMON,FORM=E

COMMON
SHARE

FSCB
DS

BUFFER=SHARE,RECFM=V,BSIZE=200,FORM=E
CL200

In the above example, the fileid specifications on the FSREAD and
FSWRITE macro instructions modify the FSCB at the label COMMON each
time a read or write operation is performed. You can also modify an FSCB
directly by referring to fields by a displacement off the beginning of the
FSCB. For example,
MVC

FSCB+8,=CL8'NEWNAME'

moves the name NEWNAME into the filename field of the FSCB at the
label FSCBFN.
As an alternative, you can use the FSCBD macro instruction to generate a
DSECT and refer to the labels in the DSECT to modify the FSCB. For
example,

78

VM/SP eMS for System Programming

· '---'-"'--'~~

LA
RS,INFSCB
USING FSCBD,RS
MVC
INFSCB
NEWNAME

FSCBFN,NEWNAME

FSCB 'INPUT TEST AI' , FORM=E
DC
CL8'OUTPUT'
FSCBD

In the above example, the MVC instruction places the filename OUTPUT
into the FSCBFN (filename) field of the FSCB. The next time this FSCB is
referenced, the file OUTPUT TEST is the file that is manipulated.
Reading and Writing eMS Disk Files

CMS disk files are sequential files. When you use CMS macros to read and
write these files, you can access them sequentially with the FSREAD and
FSWRITE macros. However, you may also refer to records in a CMS file by
their relative record numbers. So you can, in effect, access records using a
direct access method.
If you know the record you want to read or write, you can specify the

RECNO option on the FSCB macro instruction or on the FSOPEN,
FSREAD, or FSWRITE macro instructions. When you use the RECNO
option on the FSCB macro instruction, you must specify the exact record
number. For the FSOPEN, FSREAD, or FSWRITE macro instructions, you
may either specify the exact record number:
WRITE

FSWRITE FSCB=WFSCB,RECNO=IO,FORM=E

or specify the register containing the record to be read:
WRITE

FSWRITE FSCB=WFSCB,RECNO=(S),FORM=E

When you want to access files sequentially, the FSCBITNO field of the
FSCB must be 0 for an FSCB without the FORM = E option. For an
extended FSCB, the FSCBAITN field must be o. This is the default value.
When you are reading files with the FSREAD macro instruction, reading
begins with record number 1. When you are writing records to an existing
file with the FSWRITE macro, writing begins following the last record in
the file.
To begin reading or writing files sequentially beginning at a specific record
number, you must specify the RECNO option twice: once to specify the
relative record number where you want to begin reading, and a second time
to specify RECNO = 0 so reading or writing will continue sequentially
beginning after the record just read or written. You can specify the
RECNO option on the FSREAD or FSWRITE macro instruction, or you
may change the FSCBITNO or FSCBAITN field in the FSCB for the file, as
necessary for the FSCB form.
For example, to read the first record and then the 50th record of a file, you
could code the following:

Chapter 5. Developing Programs under CMS

79

..___________ .__ ._._.__ . ___.__.____._._.. _.. ____ ~_._.~______ ...__ . .__.______._..___ ._J

READl

READ50

RFSCB
WFSCB
COMMON

FSREAD FSCB=RFSCB,FORM=E
FSWRITE FSCB=WFSCB,FORM=E
LA
5,RFSCB
USING FSCBD,5
MVC
FSCBAITN,=F'50'
FSREAD FSCB=RFSCB,FORM=E
FSWRITE FSCB=WFSCB,FORM=E

FSCB 'INPUT FILE Al',BUFFER=COMMON,BSIZE=120,FORM=E
FSCB 'OUTPUT FILE Al' ,BUFFER=COMMON,BSIZE=120,FORM=E
OS
CL120

FSCBD

In this example, the statements at the label READI write record I from the
file INPUT FILE Al to the file OUTPUT FILE AI. Then, using the DSECT
generated by the FSCBD macro, the FSCBITNO field is changed because an
extended FSCB is being used.
FSCBAITN field is changed because an extended FSCB is being used and
record 50 is read from the input file and written into the output file.
The "update-in-place" facility allows you to write blocks back to their
previous location on disk. The "update-in-place" attribute of a CMS file is
indicated by the filemode number 6.
Reading and Writing Variable Length Records

When you read or write variable-length records, you must specify
RECFM = V either in the FSCB for the file or on the FSWRITE or FSREAD
macro instruction. The read/write buffer should be large enough to
accommodate the largest record you are going to read or write.
To write variable-length records, use the BSIZE = option on the FSWRITE
macro instruction to indicate the record length for each record you write.
To read variable-length records, register 0 contains, on return from
FSREAD, the length of the record read.
The following example shows how you could read and write a
variable-length file:
READ

FSREAD 'DATA CHECK Al' ,BUFFER=SHARE,BSIZE=130,
ERROR=OUT,FORM=E
FSWRITE 'COPY DATA Al' ,BUFFER=SHARE,BSIZE=(O),FORM=E
B
READ

When you update files of variable-length records, the replacement record
must be the same length as the origin.al record. An attempt to write a
record shorter or longer than the original record results in truncation of
the file at the specified record number. No error return code is given.

80

VM/SP eMS for System Programming

r.-.u. . ----.. . . -... -.. -.----.....
~

End-ol-File Checldng

You can specify the ERROR = operand with the FSREAD or FSWRITE
macro instruction so an error handling routine receives control in case of
an error. In CMS, when an end of file occurs during a read request, it is
treated as an error condition. The return code is always 12. If you specify
an error handling routine on the FSREAD macro instruction, the first thing
this routine can do is check for a 12 in register 15.
Your error handling routine may also check for other types of errors. See
the macro description in the VMjSP eMS Macros and Functions Reference
for details on the possible errors and the associated return codes.
Opening and Closing Files

Usually, CMS opens a file whenever an FSREAD or FSWRITE macro
instruction is issued for the file. When control returns to CMS from a
calling program, all files accidentally left open are closed by CMS.
Therefore, you do not have to close files at the end of a program.
For a minidisk in 512-, lK-, 2K-, or 4K-byte block format, a file may be open
for concurrent read and write operations and an FSCLOSE need not be
issued when switching from reading to writing, or vice versa. For example:
LA
READ

3,2

FSREAD FSCB=UPDATE,RECNO=(3),ERROR=READERR,FORM=E

FSWRITE FSCB=UPDATE,RECNO=(3) ,ERROR=WRITERR,FORM=E
LA
3,1(3)
B
READ

UPDATE

FSCB

'UPDATE FILE A1' ,BUFFER=BUF1,BSIZE=80,FORM=E

When you are running long running applications or running disconnected,
include several FSCLOSE macros to each file referenced. This insures that
changes to the file are reflected on the disk in the event that the user is
forced off the system. This consideration is important when running on
512-, lK-, 2K-, or 4K-byte block disks since the disk directory is not updated
until all of the files on the disk are closed.
If you want to read and write records from the same file on an 800-byte
block format minidisk, you must issue an FSCLOSE macro instruction to
close the file whenever you switch from reading to writing. For example:

Chapter 5. Developing Programs unde'r CMS

81

READ

LA
3,2
FSREAD FSCB=UPDATE,RECNO=(3),ERROR=READERR
FSCLOSE FSCB=UPDATE

FSWRITE FSCB=UPDATE,RECNO=(3),ERROR=WRITERR
FSCLOSE FSCB=UPDATE
LA
3,1(3)
B
READ

UPDATE

FSCB

'UPDATE FILE Al' ,BUFFER=BUF1,BSIZE=80

To execute a loop to read, update, and rewrite records, you must read a
record, close the file, write a record, close the file, and so on. Since closing
a file repositions the read pointer to the beginning of the file and the write
pointer at the end of the file, you must specify the relative record number
(RECNO) for each reaq and write operation. In the above example, register
3 is used to contain the relative record number. It is initialized to begin
reading with the second record in the file and is increased by one following
each write operation.
When you use an EXEC to execute a program to read or write a file, the file
is not closed by CMS until the EXEC completes execution. Therefore, if
you read or write the same file more than once during the EXEC procedure,
you must use an FSCLOSE macro instruction to close the file after using it
in each program, or you must use the FSOPEN macro instruction to open it
before each use. Otherwise, the read or write pointer is positioned as it was
when the previous program completed execution.
Creating New Files

When you want to begin writing a new file using CMS data management
macros, there are two ways to ensure that the file you want to create does
not already exist. One way is to issue the FSST ATE macro instruction to
verify the existence of the file.
A second way to ensure that a file does not already exist is to issue an
FSERASE macro instruction to erase the file. If the file does not exist,
register 15 returns with a code of 28. If the file does exist, it is erased. See
Figure lIon page 83 for an illustration of a sample program using CMS
data management macros.

82

VM/SP eMS for System Programming

[JG~JG~([D~3au1[J ~)u'O[Jr/8Uliu9 [~Ju'u(JGu~ C~JS
c --.------------.-----.. ---- .. --- -.. -.-.-.-.-.- . --.-- ---.-- -.---.-----.---.------.-.-.. ---..-..

LINE

~~.-.-.--.-------._=_----------------.---=.--------------1

SOURCE STATEMENT

BEGIN

CSECT
PRINT NOGEN
USING *,12
ESTABLISH ADDRESSABILITY
LR
12,15
ST
14,SAVE
LA
2,8(,1) R2=ADDR OF INPUT FILEID IN PLIST
LA
3,32(,1) R3=ADDR OF OUTPUT FILEID IN PLIST
* DETERMINE IF INPUT FILE EXISTS
FSSTATE (2),ERROR=ERR1,FORM=E

2

*

* READ A RECORD FROM INPUT FILE AND WRITE ON OUTPUT FILE
RD
FSREAD (2),ERROR=EOF,BUFFER=BUFF1,BSIZE=80,FORM=E
FSWRITE (3),ERROR=ERR2,BUFFER=BUFF1,BSIZE=80,FORM=E
B
RD
LOOP BACK FOR NEXT RECORD

**

COME HERE IF ERROR READING INPUT FILE
4
EOF
15,=F'12'
END OF FILE ?
C
ERROR IF NOT
BNE
ERR3
15,0
ALL O.K. - ZERO OUT R15
LA
EXIT
GO EXIT
B
* IF INPUT FILE DOES NOT EXIST
ERR1
WRTERM 'FILE NOT FOUND' ,EDIT=YES
EXIT
B

**

IF ERROR WRITING FILE
ERR2
LR
10,15
SAVE RET CODE IN REG 10
5
LINEDIT TEXT='ERROR CODE .... IN WRITING FILE' ,SUB=(DEC,(10))
B
EXIT

*

* IF READING ERROR WAS NOT NORMAL END OF FILE
ERR3
LR
10,15
SAVE RET CODE IN REG 10
5
LINEDIT TEXT='ERROR CODE .... IN READING FILE',SUB=(DEC,(10))·
*
14,SAVE
LOAD RETURN ADDRESS
EXIT
L
RETURN TO CALLER
BR
14
*
BUFF1
DS
CL80
SAVE
DS
F
END

Figure 11 (Part 1 of 2).

A Sample Listing of a Program that Uses eMS Macros

Chapter 5. Developing Programs unde-r CMS

83

L. ........_____ .____ .__._ _ _.______ ... __ ......... _._ .

· _...._........ J

Notes:
The program might be invoked with a parameter list in the format: progname INPUT FILE
Al OUTPUT FILE AI. This line is placed in a parameter list by CMS routines and addressed
by register 1 (see note 2).
2

The parameter list is a series of doublewords, each containing one of the words entered on
the command line. Thus, 8 bytes past register 1 is the beginning of the input fileid. 24 bytes
beyond that is the beginning of the second fileid.

3

The FSREAD and FSWRITE macros cause the files to be opened. No open macro is necessary.
CMS routines close all open files when a program completes execution (except CMS EXEC
files).

4

The return code in register 15 is tested for the value 12, indicating an end-of-file condition. If
it is the end of the file, the program exits. Otherwise, it writes an error message.
The dots in the LINEDIT macro are substituted, during execution,
register 10.
.

Figure 11 (Part 2 of 2).

with the decimal value in

A Sample Listing of a Program that Uses eMS Macros

Terminal Communications
There are four CMS macros you can use to write interactive,
terminal-oriented programs. They are RDTERM, WRTERM, LINEDIT, and
WAITT. RDTERM and WRTERM only require a read/write buffer for
sending and receiving lines from the terminal. The third, LINEDIT, has a
substitution and translation capability.
When you use the WRTERM macro to write a line to your terminal you can
specify the actual text line in the macro instruction, for example:
DISPLAY

WRTERM 'GOOD MORNING'

You can also specify the message text by referring to a buffer that contains
the message.
The RDTERM macro accepts a line from the terminal and reads it into a
buffer you specify. You could use the RDTERM and WRTERM macros
together, as follows:
WRITE
READ

84

REWRITE

WRTERM 'ENTER LINE'
RDTERM BUFFER
LR
3,0
WRTERM BUFFER, (3)

BUFFER

DS

VM/SP eMS for System Programming

CL130

UJGUG~(D~)DuuCJ ~)u'ogG'~]U'~lS rr.~uue]G[i·

(- -- - - -_. -.

--- - _.- _. -.-.- - _. -: : ---------..- - - - - - - - -_.- _._- . -.- -..- - - - -_.- - ~.

.-==-~~-.---

(GWJS

. -.- -._._ . _. - ---_._.- -_._-_._- -_._._.- -_. _-_._ . _.- - -. ---_._- - -_._-_. _._.-

.--~-]

In this example, the WRTERM macro results in a prompting message. Then
the RDTERM macro accepts a line from the terminal and places it in the
buffer BUFFER. The length of the line read, contained in register 0 on
return from the RDTERM macro, is saved in register 3. When you specify a
buffer address on the WRTERM macro instruction, you must specify the
length of the line to be written. Here, register notation is used to indicate
that the length is contained in register 3.
The LINEDIT macro converts decimal and hexadecimal data into EBCDIC,
and places the converted value into a specified field in an output line.
There are list and execute forms of the macro instruction, which you can
use in writing reentrant code. Another option allows you to write lines to
the offline printer. The LINEDIT macro is described, with examples, in
VM/SP eMS Macros and Functions Reference. Figure 11 on page 83 shows
how you might use the LINEDIT macro to convert and display CMS return
codes.
The WAITT (wait terminal) macro instruction can help you to synchronize
input and output to the terminal. If you are executing a program that reads
and writes to the terminal frequently, you may want to issue a WAITT
macro instruction to halt execution of the program until all terminal I/O
has completed.

Unit Record and Tape 1/0
CMS provides macros to simplify reading and punching cards (RDCARD
and PUNCHC), and creating printer files (PRINTL). When you use either
the PUNCHC or PRINTL macros to write or punch output files while a
program is executing, you should remember to issue a CLOSE command for
your virtual printer or punch when you are finished. You can do this
either after your program returns control to CMS, by entering:
cp close e
or -cp close d

or you can set up a parameter list with the command line CP CLOSE E or
CP CLOSE D and issue an SVC 202.
The tape control macros, RDT APE, WRTAPE and T APECTL, can read and
write CMS files from tape, or control the positioning of a tape.

Handling Interrupts
You can set up routines in your programs to handle interruptions caused by .
I/O devices, by SVCs, or by external interruptions using the HNDINT,
HNDSVC, or HNDEXT macro instructions.
With the HNDINT macro instruction, you can specify addresses that are to
receive control when an interruption occurs for a specified device. If the

Chapter 5. Developing Programs under CMS

85

[iJ)G~G~(iJ)[J)Hn1@J ~fi1Q)QW'@rruus MUuC0]en ~M§
1

c _________ .____________

=-:======-_._____.__._________. _____ ______. . _____. _______________._.___.______=:::J
~.

WAIT option is used for a device specified in the HNDINT macro ,
instruction, then the interruption handling routine specified for the device
does not receive control until after the WAITD macro instruction is issued
for the device.
You can use the HNDSVC macro instruction to trap supervisor call
instructions of particular numbers, if, for example, you want to perform
some additional function before passing control or you do not want any
SVCs of the specified number to be executed.
The CP EXTERNAL command simulates external interruptions in your
virtual machine; if you want to be able to pass control to a particular
internal routine in the event of an external interruption, you can use the
HNDEXT macro instruction.

System Product Editor Interface to Access Files in Storage
CMS uses the SUBCOM facility to allow a number of CMS commands to
use an XEDIT interface to access files in storage. Applications can read or
write specific records without having to go to disk or use the program stack
to transfer the data to or from XEDIT. This improves performance.
CMS uses the XEDIT interface for processing the FILELIST, HELP,
MACLIST, PEEK, and SENDFILE commands. The interface is invoked by
specifying the XEDIT option on the LISTFILE, MACLIB, or NAMEFIND
commands. This option may only be specified from the XEDIT
environment.
When using this interface from an application program, only the extended
parameter list can be used, and the high-order byte of of register 1 must
contain X'02' to indicate SUBCOM is being used.
The application can invoke this interface via SVC 202 or via a BALR
instruction. Because XEDIT is a nucleus-resident routine, other
nucleus-resident routines can branch directly to it while routines that do
not reside in the nucleus use SVC linkage. When using an SVC 202,
register 1 must point to the FSCB where the name of the routine being
invoked is the first token. The high-order byte of register 1 must also be
X'02'. When usingBALR, the calling program can determine the entry
point it wants by using SUBCOM. In this case, register 1 points to the
FSCB and register 2 points to the SCBLOCK. The address of the the
SCBLOCK has been returned from SUBCOM.
The routines available, their entry point names, and error return codes are:
o

DMSXFLST - This routine returns the characteristics of a file (RECFM,
LRECL, etc). It also ensures that the file is in the XEDIT ring. The
return codes are:

o
24

86

File is in the XEDIT ring
Incomplete fileid specified

VM/SP eMS for System Programming

c--_·_·__· __ ·_· · __· : . . . ._...... -............. --_._._._ ............ _. . -.__.. .
28

[~~GU(:;~C)~JUur~~J

lJu1tDOu"c:lu'ul1S

llJu!)[JSG' G~uJS

. -.

:..-=:~~=~:==-==::.~:~::.===:-=:..:~==-::.=::.::.:.===~~===-=~~.=~.=:-:-.=J

File is not in the XEDIT ring

Note: Return codes are similar to those for EST ATE.
•

DMSXFLRD - This routine transfers one record from XEDIT storage to
the calling program. If RECFM = F, it may transfer more than one
record. The return codes are:

o
1
2
5
7
8
11
12

READ performed
File is not in the XEDIT ring
Invalid buffer address
Number of items equals zero
RECFM is not 'F' or 'V'
Buffer is too small (records truncated)
Number of items is not equal to one for V-file
End of file

Note: Return codes are similar to those for FSREAD.
o

DMSXFLWR - This routine transfers one record from the calling
program to XEDIT storage. If RECFM = F, it may transfer more than
one record. The return codes are:

o
2
7
8
11
13
14
15
16
18
28

WRITE performed
User buffer address equals zero
Skip over unwritten records
Number of bytes is not specified
RECFM is not 'F' or 'V'
No more space is available
Number of bytes is not integrally divisible by the number of item
Item length is not the same as previous
RECFM of 'F' or 'V' is not the same as previous
Number of items is not equal to one for V-file
File is not in the XEDIT ring

Note: Return codes are similar to those for FSWRITE.
o

DMSXFLPT - This routine moves the current line pointer to a record
specified by the calling program. If you specify the read and write
pointer as all ones (X'FFFFFFFFX'), the current line pointer is
returned in the FSCB. The return codes are:

o
1
2

POINT performed
File not found
Invalid FSCB

Note: Return codes are similar to those for FSPOINT.
When the interface is used, XEDIT determines if a file is in the XEDIT ring
(active in storage) and does the processing required. The files in the XEDIT
ring are always open. New files may be added to the ring with the XEDIT
subcommand. Files in the ring may be closed with the FILE or QUIT
subcommands.
Chapter 5. Developing Programs under CMS

87

The current line pointer serves the function of both the read and write
pointers of the CMS file system. If RECNO = 0 is specified in a call to
DMSXFLRD, the data is transferred to the calling program starting at the
current line pointer. Transfer is stopped when the specified number of lines
has been transferred or when end-of-file is reached. The current line
pointer is advanced by one for each record transferred to the calling
program. If the current line pointer was at the end-of-file when
DMSXFLRD was called, no data is transferred and an end-of-file condition
is returned.
If RECNO = 0 is specified in a call to DMSXFLWR, new records are written
starting at the line pointed to by the current line pointer. These new
records replace any existing records or add new records if at the end-of-file.
The current line pointer is advanced to the line following the last line
written at the end of the operation. Note that writing to a record in the
middle of a V-format file does not result in truncation of the file from that
point as it would in the CMS file system. Truncation (or spilling when SET
SPILL ONIWORD) may occur if the file is in V-format and the LRECL of
the file is less than the length of the record(s) being written. No message is
issued and the return code is o.

eMS Interface for Display Terminals
CMS has an interface allowing it to display large amounts of data in a very
rapid fashion. This interface for 3270 display terminals (also 3138, 3148, and
3158) is much faster and has less overhead than the normal write because it
displays up to 1760 characters in one operation instead of issuing 22
individual writes of 80 characters each (that is, one write per line on a
display terminal). Data displayed in the screen output area with this
interface is not placed in the console spool file.
The console facility provides a CMS macro interface to full-screen I/O that:
o
C)

provides screen coordination and
provides an architecturally independent I/O interface.

Use the console facility instead of the DIAGNOSE code X'58' interface or
the DISPW macro.
The console facility provides improved usability for writing 3270 I/O
applications. The CONSOLE macro performs I/O operations such as:
•
•
•
•

building the channel command word (CCW),
issuing DIAGNOSE code X'58' or Start I/O (SIO) instruction,
waiting for the I/O to complete, and
checking any error status from the device.

Applications must construct a valid 3270 data stream to write to the screen,
and a 3270 data stream is returned when a CONSOLE READ is performed.

88 VM/SP eMS for System Programming

r

. ... _.- --- ------_ . __. _--_._-- .----- ---. _. __.-

~-:.

lOc:r~e~O[JQJ J[J LJ~\)Uu'(Ju~ruS ~Ju'ilck~GJ (GGtJ~3
---.
- -------,
--------~:-~---.:-~~~:~- -~-.-:.:..-~-.~~--=:..:::--~:=~--~::.:~~~.=-.~.

The CONSOLE macro allows programs to open 'paths' to a display device.
A path is a unique name that distinguishes one application from another
and allows the console facility to coordinate the use of the screen. For
example, if an application is writing to the screen, the CONSOLE macro
tells it that another 'path' has updated the screen lastly, and, therefore, the
screen must be reformatted. Because of this, full-screen applications do not
have to rewrite the entire screen every time a write is done.
Screen coordination can be done only for applications using the console
facility. Because some application still issue their own DIAGNOSE code
X'58', you must reformat the screen. This avoids mixing data from two
different applications on the screen. Refer to "The CONSOLE Macro" on
page 90 for more details.
The CONSOLE macro provides the following functions:
o

OPEN/CLOSE - Opening and closing a specific path to the console.

o

READ/WRITE - Reading and writing buffers that have 3270 data
streams built by the application. In order to write to the screen,
applications must construct a valid 3270 data stream. When a read is
performed, the data is returned in the user's buffer. The CMS console
facility issues the DIAGNOSE code X'58' for the virtual console or a
Start I/O (SIO) for dialed devices, builds the CCW for READ and
WRITE requests, tests conditions after I/O, and gives the result of the
I/O operation to the application.

o

EXCP - Performing READ or WRITE I/O operations using CCWs that
applications supply. An application must supply its own CCW if it uses
the EXCP function. This function is intended for use with dialed
devices.

o

WAIT - Wait for an I/O interrupt from the console device.

o

QUERY - Getting information about the device attributes (DIAGNOSE
code X'24' and DIAGNOSE code X'8C'), or if the path is opened, getting
information about a specific path and its associated device. The user
should provide a buffer for this information and then map the
information using the CQYSECT mapping macro. For information
about the CQYSECT macro, refer to

The four formats of the CONSOLE macro instruction are:
Standard format
It is not reentrant.
List format (MF = L)
Generates a parameter list, but does not generate code to execute
the function. The parameter list is generated in-line and usually
register notation cannot be used.

Chapter 5. Developing Programs under CMS

89

[Q)GnJG~(»[]DuuQJ

ru (Q)gu C}uuuS tDuu(JGu CLlfJ8
1

1

1

L __________ . _____._._. _.~_______________.__.______.__. _.._. ___.____ ..._. . ______. _. ____ .___ . . ______.

Complex List format (MF = (L,addr[,label]))
Generates a parameter list, but does not generated code to
execute the function. The parameter list is generated in an area
that you specify.
Execute format (MF = (E,addr))
Generates code to execute the function.
Note: For the detailed formats of the CONSOLE macro, see VM/ SP eMS
Macros and Functions Reference.

The CONSOLE Macro
An Example of Using the Console Facility

•

OPEN a path with the optional BUFFER parameter.

o

Get information about the device from the buffer.

o

Build a 3270 data stream.

e

Issue the CONSOLE WRITE with the EW option.

•

Issue the READ with the WAIT option.

o

Check the return code.

•

If the return code from READ or WRITE is not 0, issue a QUERY to
determine what happened.

•

CLOSE the path.

Opening a Path

In order to use the CMS console facility for I/O, you must first open a
'path'. You can do this by issuing the OPEN parameter of the CONSOLE
macro.
When you open a path, the console facility allocates storage containing
information about I/O activity for the application. A path entry is
associated with a device when you specify the CONSOLE OPEN parameter.
If the device does not already have paths opened to it, storage is allocated
for a new device entry and any existing device entries are linked to it.

90

VM/SP eMS for System Programming

r-·-·---······ .. ·..--··--·-·-··-------·-·---·-·--·--·---------.-.-------.--.--------.. -.-.......-.-----.--.-..----.---.-.-------------]

Querying a Path

You can use the CONSOLE QUERY to obtain information about a path and
its associated device or to obtain information about a virtual device even if
paths are not opened to it. To do this, you must also specify the BUFFER
parameter. You can map the information returned by the CQYSECT macro.
(See VM/SP Data Areas and Control Block Logic Volume 2 (CMS) for more
information.) CQYSECT contains length equates that an application can
use to obtain the size buffer needed.
Initially, when an application opens a path, it can specify a buffer that
contains path and device information and is mapped by CQYSECT. This
information is very useful at initialization time since it contains
DIAGNOSE code X'24' information, and, depending on the device, it
contains DIAGNOSE code X'8C' information. Then, the application can
obtain the device type and characteristics and can use the appropriate
routines to build data streams.
Writing to and Reading from a Path

The console facility keeps track of the application that owns the screen by
keeping a field in the device entry (CDEV) for the address of the path entry
that performed the last I/O operation. If one application currently owns the
screen and another application wants to perform I/O, the second application
must gain control of the screen by reformatting it with an erase/write (EW),
an erase/write alternate (EWA), or, in some cases, a write structure field
(WSF). Therefore, applications should begin I/O processing with one of
these operations.

Warning: Until all applications use the console facility instead of
issuing a DIAGNOSE code X'58', there is a possibility of seeing data
from two different applications mixed on the screen. An erase/write
(EW) must be issued so that the current application can gain total
ownership of the screen. If CP breaks in and writes a screen or if
another application using the console facility writes a screen, the
console facility can detect this situation and issues return code 32. If
you get return code 32, issue an erase/write or an erase/write alternate.
However, the console facility can not always detect who wrote to the
screen when applications modify PSW s in low storage and issue their
own DIAGNOSE X'58'. In this case, if you get mixed data on the
screen, you will have to press the CLEAR key or issue a command that
causes an erase/write. The VMFCLEAR command can be issued by an
application before exiting their program to accomplish this. Another
alternative for applications running in full-screen CMS would be to
write an EXEC to issue a SET FULLSCREEN SUSPEND command,
then invoke their full-screen program, and when processing completes
they can resume fullscreen CMS by issuing SET FULLSCREEN
RESUME.
Most full-screen applications will wait for input and then read the data. To
accomplish this, you can issue a CONSOLE READ with the WAIT option,
o~ you can issue a CONSOLE WAIT followed by a CONSOLE READ. The

Chapter 5. Developing Programs under CMS

91

[]GtlG~(iJ)rr]DrUQJ rro~~~@~UuS (LBUUC)JG~1 C~~8

c _____________________________________ _

_______________________.--1

CONSOLE READ with the WAIT option has a performance advantage
because it issues only one Supervisor Call (SVC) instead of two.
If you receive a return code 1 on an I/O operation, you should issue an
explicit WAIT. Do not specify a READ with the WAIT option. A
disconnect is detected before any READ options are checked. When you
specify a READ with the WAIT option, a WAIT is not issued and control is
immediately returned to the application with return code 1.
If an application performs linemode I/O or calls routines that perform
linemode I/O, it should issue a CMS WAITT macro to coordinate linemode
and full-screen I/O. This allows the I/O to complete before issuing any
console full-screen operations.
1/0 Advantages

Applications can become much less dependent on low-level device
architecture by using the console facility. In the past, applications not only
had to construct data streams, but they had to build the channel command
word (CCW), determine the type of device (dialed or virtual console) and set
up for DIAGNOSE code X'58' or 3270 SIO, and check the channel status
word (CSW) to determine what action should be taken.
In addition, the applications would have to change whenever new devices
were introduced.
With the console facility, the application only needs to:
o

build a data stream,

o

issue a CONSOLE call, and

•

check a return code.

The CSW error checking and retrying of I/O is much more elaborate in the
console facility than what many applications do today. This gives
applications a better chance for completing a successful I/O options.
Building Your Own CCW

The CONSOLE EXCP parameter allows applications that still want to build
their own CCWs to do so. However, no CCW error checking is performed
so the CONSOLE module cannot determine the type of I/O requested and
cannot coordinate the use of the screen as effectively as with the READ or
WRITE functions.
The EXCP parameter is not recommended for the virtual console since the
application has to know the internal I/O processing performed in the
CONSOLE module. However, if you use this function carefully, you can
chain several CCWs. The first CCW in the string should be an EW, EWA,
or WSF to reformat and to gain control of the screen.

92

VM/SP eMS for System Programming

,/

· -.- .__ . - -------_. ---_. __ .._.-

_._._--_. __ .. _._-._ .. -_..... ---

-~~::-]

Completing an 1/0 Operation

When the console facility returns control to the application after an I/O
operation, the application can check the return code and continue
processing. If more information is needed about the I/O just performed, a
CONSOLE QUERY can be issued. The CONSOLE QUERY shows the CSW
after I/O, the sense data (if any), the last CCW executed, and all the device
information obtained by DIAGNOSE code X'24' and DIAGNOSE code X'8C'.
Closing a Path

Before exiting your program, paths that are no longer needed should be
closed. Close processing releases storage for the path entry. If this was the
only path opened to the associated device, the device entry storage is
released as well. When releasing a device entry, a CP RESET command is
only issued for dialed devices.

The DISPW Macro
Although the CONSOLE macro is the preferred interface for full-screen I/O,
the DISPW macro may be used to generate a calling sequence for the CMS
display terminal interface module, DMSGIO. DMSGIO creates a channel
program and issues a DIAGNOSE code X'58' to display the data. DMSGIO
is a TEXT file that must be loaded to use DISPW.
The format of the CMS DISPW macro is:
[ label]

DISPW

bufad

[ ,LINE =

{~ }][ ,BYTES ={;~;;} 1

[ ,ERASE = YES]
[,CANCEL=YES]

where:
label

is an optional macro statement label.
bufad
is the address of a buffer containing the data to be written to the
display terminal.

LINE= {~}
is the number of the line, 0 to 23, on the display terminal that is to be
written. Line number 0 is the default.

Chapter 5. Developing Programs under CMS

93

[D)Gt7G;~(][~)O~u§~ [JL"(])[jr@~uuD L~ullCJ0[j' (~rJJ8
L=-:"~==-~_~=~_~=~:::'

_________.__.____._ . "._._, __. _ ._, _._._ "_ , ._"" _ . __ ._._. __.===-.-__
~._.,,

BYTES =

=====_==-_=~-=---==-=-_._._.

_ ._._. ._. ____.]

{nnnn}

1760
is the number of bytes (0 to 1760) to be written on the display
terminal. 1760 bytes is the default.
ERASE=YES
specifies that the display screen is to be erased before the current data
is written. The screen is erased regardless of the line or number of
bytes to be displayed. Specifying ERASE = YES causes the screen to
go into "MORE" status.
CANCEL=YES
causes the CANCEL operation to be performed. The output area is
erased.
Note: It is advisable for the user to save registers before issuing the
DISPW macro and to restore them after the macro because the modules
called by the DISPW macro do not save the user's registers. The DISPW
macro saves and restores register 13.

94

VM/SP eMS for System Programming

1-------------------..---.---..--.-.----. -.- . -.. - - - -.--- -.- - . - - .- ---.-.-.-.---' .-.-. -.---.------.--.-----------------..----.------.--.---.- . --.--..-.-.-.- . -----..--------. --------..---.-----

L

(c:ln~ri'n~i (~, IU\p(~~irfri~1 ~(o\o,;(c(:, 1:'\i(oI2';~fii~~, IU~::-flii~1 (CllVil~
As you test and modify programs, you may want to keep backup copies of
the source programs. Then you can always return to a certain level of a
program in case you have an error. eMS provides several approaches to
the problem of program backup. The method you choose depends on the
complexity of your project, the changes you want to make, and the size of
your programs.
The simplest method is to make a copy of the current source file under a
new name. You can do this using either the COPYFILE command or the
editor.

The UPDATE Philosophy
While the procedures outlined above for modifying programs are suitable
for many applications, they may not be adequate in a situation where
several programmers are applying changes to the same source code. These
procedures also have the drawback of not providing you with a record of
what has been changed. After using the editor, you do not have a recordof
the lines that have been deleted, added, replaced, and so on, unless you
manually add comments to the code, insert special characters in the
serialization column, or use some technique that records program activity.
The UPDATE command and the XEDIT UPDATE option provide a way for
you to modify a source program without affecting the original. UPDATE
produces an update log, indicating the changes that have been made. Both
UPDATE and XEDIT have the capability of combining multiple updates at
one time, so that changes made by different programmers or changes made
at different times can be combined into a single output file.
The UPDATE command and the XEDIT UPDATE option are the basic
elements of the VM/SP updating scheme. Although the input filetypes used
by the UPDATE command default to ASSEMBLE file characteristics,
neither the UPDATE command nor the XEDIT UPDATE option is limited
to assembler language programs. Also, is it not limited to system
programming applications. You can use it to modify and update any
fixed-length, 80-character file that does not have data in columns 73
through 80.

Chapter 6. Updating Source Programs Using CMS

95

L ._......_. ____.____..__ ._._____.. ___.._..__ .___ . ____ .... _._..___ ._._ .

....___. _._. ___ ._._. _. . _. _____ .__.___., ______._,__

:~==_:_..::.=_~_=:...

________. ___________.____ ., .._, ____.__ . ___._________.__ .___1

Update Files
A simple update involves two input files:
o

The source file, which is the program you want to update

o

An update file, usually created by XEDIT, containing control
statements describing the changes you want to make.

The control statement file usually has a filetype of UPDATE. For
convenience, you can give it the same filename as your source file. For
example, if you want to update the file SAMPLE ASSEMBLE, you would
create a file named SAMPLE UPDATE using the XEDIT UPDATE option.
To apply the changes in the update file, you issue the command:
update sample

The default values used by the UPDATE command are filetypes of
ASSEMBLE and UPDATE for the source and update files, respectively. If
you are updating a COBOL source program named READY COBOL with an
update file named READY UPDATE, you would issue the command:
update ready cobol a ready update a

After an UPDATE command completes processing, the input files are not
changed; two new files are created. One of them contains the updated
source file, with a filename that is the same as the original source file but
preceded by a dollar sign ($). Another file, containing a record of updates
is also created; it has a filename that is the same as the source file and a
filetype of UPDLOG. For example:
Source Files

Output Files

SAMPLE ASSEMBLE

$SAMPLE ASSEMBLE

SAMPLE UPDATE

SAMPLE UPDLOG

READY COBOL

$READY COBOL

READY UPDATE

READY UPDLOG

Now, you can assemble or compile the new source file created by the
UPDATE command.
Creating an Update File

You can create an update file using the XEDIT UPDATE option. Using
XEDIT, you do not need to enter the control statements in the UPDATE
file. They are generated automatically by the editor. For example:
xedit ready cobol a (upd

96

VM/SP eMS for System Programming

-.. _--- --'--' ._- --.. -.-.-..

r-------

UJ[Jc]c:.1'~au·uo 8oQJuy~e [)u'OOG'C1uuuS
-- _._- ---.-

---------~:==--.---

--:-=-~~:::-.::::~-==:-------------=-=-~::::~=:.==]

specifies that a file called READY COBOL is to be edited and all updates to
the file are placed in a separate file called READY UPDATE along with the
appropriate control statements.
The XEDIT UPDATE option expects source files to have sequence numbers
in columns 73 through 80. Before you can create an UPDATE file you must
use the XEDIT SERIAL subcommand to sequence your files. To generate
these sequence numbers, you should issue:
serial all

prior to issuing a FILE or SAVE subcommand when you are editing a file.
Alternately, you can preface sequence numbers with a three character
identifier, usually the first three characters of the filename. If you issue:
serial on

XEDIT writes sequence numbers in columns 76 through 80 of your file.
Columns 73 through 75 contain the first three characters of the filename. If
SERIAL ON is specified, you must also specify the NOSEQ8 option on the
XEDIT command to tell the editor to expect a sequence of numbers only in
columns 75 through 80. For example:
xedit ready cobol a (upd noseq8
Using an Existing Update File

If an update file already exists for a given source file and you wish to
either:
1.

browse the source file with the updates applied or

2.

continue updating the source file

issue the same XEDIT command that you entered when you created the
update file. For example:
xedit ready cobol a (upd

applies all updates contained in READY UPDATE to the source file
READY COBOL and displays the resulting file on the screen. Any updates
created during this editing session are added to those already contained in
READY UPDATE. Again, all control statements are automatically
generated by XEDIT. More information about the XEDIT UPDATE option
can be found in the VM/SP CMS Command Reference.
UPDATE Control Statements

The control statements used by the UPDATE command are similar to those
used by the as IEBUPDTE utility program or the DOS MAINT program
UPDATE function.
Each UPDATE statement must have the characters ./ in columns one and
two, followed by one or more blanks. The statements are described below.

Chapter 6. Updating Source Programs Using eMS

97

.-.....___ . ___ . _._._.........._.._........ _..._.._._.. _.___.________:J

SEQUENCE Statement: This statement tells the UPDATE command you
want to number or renumber the records in a file. Sequence numbers are
written in columns 73 through 80. For example, the statement:
./ S

1000

indicates that you want sequence numbering to be done in increments of
1000 with the first statement numbered 1000. The SEQUENCE statement is
convenient if you want to apply updates to a file that does not already have
sequence numbers. In this case, you may want to use the REP (replace)
option of the UPDATE command, so that instead of creating a new file
($filename), the original source file is replaced:
update sample (rep

INSERT Statement: This statement precedes new records that you want
to add to a source file. The INSERT statement tells the UPDATE command
where to add the new records. For example, the lines:
./ I 1600
TEST2 TM
BNO

HOLIDAY,X'02'
VACATION

HOLIDAY?
NOPE
VACATION
0

0

0

insert two lines of code, following the statement numbered 00001600, into
the output file. The inserted lines are flagged with asterisks in columns 73
through 80. The INSERT statement also allows you to request that new
statements be sequenced. See "Sequencing Output Records" on page 99.

DELETE Statement: This statement tells the UPDATE command which
records to delete from the source file. If your update file contains:
0/ D

2500

then only the record 00002500 is deleted. If the file contains

0/ D

2500

2800

then all the statements from 2500 through 2800 are deleted from the source
file.

REPLACE Statement: The REPLACE statement replaces one or more
records in the source file. It precedes the new records you want to add. It
is a combination of the DELETE and INSERT statements. For example, the
lines
0/ R 38000 38500
PLIST
DS
OD
DC
CL8'TYPE'
DC
CL8"
DC
CL8'FILE'
DC
CL8'A1'
DC
8X'FF'

replace the existing statements numbered 38000 through 38500 with the new
lines of code. As with the INSERT statement, new lines are not
automatically resequenced.

98

VM/SP eMS for System Programming

/'

COMMENT Statement: Use this statement when you want to place
comments in the update log file. For example, the line:
oj

*

Changes by John Jo Programmer

is not processed by the UPDATE command when it creates the new source
file, but it is written into the update log file.

Sequencing Output Records
The UPDATE command expects source files to have sequence numbers in
columns 73 through 80. If you use the XEDIT subcommand SET SERIAL to
sequence your files, the sequence numbers are usually written in columns
76 through 80; columns 73 through 75 contain a three-character identifier
that is usually the first three characters of the filename. If you want an
eight-character sequence number and you are editing the file, you must use
the subcommand:
serial all

prior to issuing a FILE or SAVE subcommand. Or, you can create an
UPDATE file with the single record:
oj S

and issue the UPDATE command to sequence the file.
If you use the UPDATE command with a file that has been sequenced using
the default values of XEDIT, you must use the NOSEQ8 option. Otherwise,
the UPDATE command cannot process your input file. The command:
update sample (noseq8

tells UPDATE to use only columns 76 through 80 when it looks for
sequence numbers. Figure 12 shows the four files involved in a simple
update.

Chapter 6. Updating Source Programs Using CMS

99

L_ ... _. ______ ._._______ .__. __ ... __ .. ______ ....

The Source File, SAMPLE ASSEMBLE
SAMPLE

CSECT
00000100
USING SAMPLE,R12
00000200
LR
R12,R15
00000300
ST
R14,SAVRET
00000400
LINEDIT TEXT='PLEASE ENTER YOUR NAME'
00000500
RDTERM NAME
00000600
LINEDIT TEXT='PLEASE ENTER YOUR AGE'
00000700
RDTERM AGE
OOOOOSOO
LINEDIT TEXT='HI, •••••••••• , YOU JUST TOLD HE YOU ARE ••••• ',x00000900
SUB=(CHARA,NAHE,CHARA,AGE),RENT=NO
00001000
L
R14,SAVRET
00001100
BR
R14
00001200
EJECT
00001300
NAME
DC
CL130"
00001400
DC
CL 130' ,
AGE
00001500
SAVRET
00001600
DC
F'O'
REGEQU
00001700
~_______________________________________________________________________________
EUD
00001800 - - - - J

The Update File, SAMPLE UPDATE

./ *

SAM00010
REVISION BY DLC
./ R 500
SA800020
SA800030
LINEDIT TEXT='HHAT"S YOUR NAHE?',DOT=NO
. / p. 700 1000
S1M00040
xSAM00050
LINEDIT TEXT='HI, •••••••••• , ENTER THE DOCNAHE',
51M00060
SUB= (CHARA, NAME)
51M00070
RDTERH nAME
5AM00080
HVC
DOCFN,NAHE
51M00090
LA
1,PLIST
5AM00100
SVC 202
5A"00110
DC
AL4 (ERROR)
5AM00120
RETURN
EQU
*
51M00130
. / I 1200
51800140
ERROR
EQU
*
5AM00150
WRTERH 'FILE NOT FOUND'
51M00160
B
RETURN
5A800170
./ D 1500
5A800180
. / I 1600
5A"00190
PLIST
DS
OD
5A800200
DC
eL8'TYPE'
CL8' ,
51800210
DOCFll
DC
SAM00220
CLS'FILE'
DC
5A800230
DC
CL8' Al '
5A800240 - - - - J
L-________________________________________________________________________________
DC
8X'FF'

Figure 12 (Part 1 of 2).

100

Updating Source Files with the UPDATE Command

VM/SP eMS for System Programming

lLDr)JJlJ~U[(UCJ 8@GJu'c(;) ~)[j-'(fj)~[j'8uuuG
c·-· .--.-...-..--.......----.. -.... ----...-----......-----.-.-.-.---.. ----.--.. --......--.--.-.. -.. --- ..-.--.. --.-------... --..----.. -.- ..-... --..--.--.---.---.---------.-------=:1

The Record of Updates Pile, SAMPLE UPDLOG

-,
UPDATING 'SAMPLE
ASSEMBLE Al' WITH 'SAMPLE
OPDATE
OPDATE LOG -- PAGE
Al'
11
. / • REVISION BY DLC
1
. / R 500
1
DELETING •••
LINEDIT TEXT='PLEASE ENTER YOUR NAME'
000005t) 01
INSERTING •••
LINEDIT TEXT='WHAT"S YOUR NAHE1',DOT=NO
. / R 700 1000
DELETING •••
LINEDIT TEXT='PLEASE ENTER YOUR AGE'
000007001
RDTERM AGE
000008001
LINEDIT TEXT='BI, •••••••••• , YOO JUST TOLD HE YOO ARE ••••• ·,x00000900'
SUB=(CHARA,NAHE,CBARA,AGE),RENT=NO
00001000,
INSERTING •••
LINEDIT TEXT='BI, •••••••••• , ENTER THE DOCNAME',
x········1
SOB= (CBAHA, NAME)
RDTERM NAME
HVC
DOCPN,NAHE
LA
1,PLIST
SVC 202
DC
AL4 (ERROR)
EQO
•
RETORN
• / I 1200
INSERTING...
ERROR
EQO
•
WRTERM 'PILE NOT POUND'
B
RETORN
. / D 1500
DELETING...
AGE
00001500,
DC
CL 130' •
. / I 1600
INSERTING...
PLIST
DS
OD
DC
CLa'TYPE'
CLa'
,
DOCPN
DC
DC
CLa'PILE'
DC
CLa'Al'
ax'pp'
DC

........,,

········1,
........
........
,
········1,
........
........
,,
........
,
........
,
.········1
.......,,
,
........
,
........
,,
........
........
,,
........
........,

The Opdated Output Pile, $SAHPLE ASSEMBLE
SAMPLE

RETORN
ERROR

NAHE
SAVRET
PLIST
DOCPN

CSECT
USING SAMPLE,R12
LR
R12,R15
ST
R14,SAVRET
LINEDIT TEXT='WHAT"S YOUR NAME1',DOT=NO
RDTERH NAME
LINEDIT TEXT='HI, •••••••••• , ENTER TH~ DOCNAME',
SUB=(CHARA,NAME)
RDTERM NAME
MVC
DOCPH,NAME
LA
1,PLIST
SVC 202
DC
AL4(ERROR)
EQU
•
L
R14,SAVRET
BR
R14
EQU
•
WRTERM 'PILE NOT POUND'
B
RETURN
EJECT
DC
CL130"
DC
plOt
DS
OD
DC
CLa'TYPE'
DC
CLa"
DC
CLa'PILE'
DC
CLa l Al'
DC
aXlpp'
REGEQU
END

Figure 12 (Part 2 of 2).

000001001
00000200,
00000300,
00000400,

........,
x········,
........
,
........
,
........
,
........
,
........
,,
........
........,
........
,,
........
........,
........
,,
........
........
,,
........
........,
00000600,

00001100,
00001200,

00001300,
00001400,
00001600,

········1

00001700,
00001800,

,

Updating Source Files with the UPDATE Command

Chapter 6. Updating Source Programs Using CMS

101

(lJl [»vJClliD ~uQ1

S(Q)M ~~CG

r ~"(Q)QJ ~1@Uu\)S

L ...__._______.

--_.:.._------_._ _._--_._--_._J

The INSERT and REPLACE statements allow you to control the numbering
increment of records that you add to a source file. Notice, in Figure 12 on
page 100 that inserted records have the character string '********' in
columns 73 through 80. If you want sequence numbers on the inserted
records, you must do two things:
1.

Include a dollar sign ($) on the INSERT or REPLACE statement,
optionally followed by operands indicating how the records should be
sequenced.

2.

Use the INC option on the UPDATE command line. If you use the CTL
option, you do not have to specify the INC option. The CTL option is
described below, under "Multiple Updates."

For example, to sequence the records added in Figure 12 on page 100 the
control statements would appear as:
.j
.j
.j
.j

R
R
I
I

509 $
700 1000 $
1200 $
1600 $

and you would issue the UPDATE command:
update sample (inc

The UPDATE command sequences inserted records by increments of 10. If
you want to control the numbering (for example, inserting more than 9
statements between two existing statements), you can specify an alternate
sequencing scheme:
.j I

1800 $ 1805

5

Records introduced following this INSERT statement are numbered
00001805, 00001810, 00001815, and so on. (If the NOSEQ8 option is in effect,
then the records would be xxx01805, xxx01810, and so on, where xxx is the
three-character identifier used in columns 73 through 75.)

Multiple Updates
If you have several UPDATE files to apply to the same source, you may
apply them in a series of UPDATE commands. For example, if you have
updates named FICA UPDTUP1, FICA UPDTUP2, and FICA UPDTUP3 to
apply to the source file FICA PLIOPT, you could do the following:
1.

Update the source file with FICA UPDr;rUP1:
update fica pliopt a fica updtup1

2.

102

Update the source file produced by the above command with the FICA
UPDTUP2:

VM/SP eMS for System Programming

,,.,,,"

lD~j(~E)'~auru~ S()~~uJC:3 ~-J[j~O~[/C1UlrilS
[L--_.-_--_-_-_--_.-_.--_-_._.-.-_
...._.-._ _-_-.. -....-- ----.----.---.. ----.-..... --. -..--. .... .........

..-=~=-=~:=:.~~.::..=.:..~=-~::~.~.:::.::.:.:..::.-::..-=::.~.:..=.=-==-_==.:..~~.:...::.::::.::=:::--==.::~~=:J

update $fica pliopt a fica updtup2

3.

Update the new source file with FICA UPDTUP3:
update $$fica pliopt a fica updtup3

This final UPDATE command produces the file $$$FICA PLIOPT, which is
now the fully updated source file. This method is cumbersome, however,
particularly if you have many updates to apply. They must be applied in a
particular order. Therefore, the UPDATE command provides a multilevel
update scheme, which you can use to apply many updates at one time, in a
specified order.
To apply multilevel updates, you must have a control file, which by
convention has a filetype of CNTRL and a filename that is the same as the
source input file. Therefore, to apply the three update files to FICA
PLIOPT, you should create a file named FICA CNTRL.
The Control File

A control file is actually a list. It does not contain any actual update
control statements (INSERT, DELETE, and so on), but rather it indicates
what update files should be applied, and in what order. In the case of a
multilevel update, all the update files must have the same filename as the
source file. Therefore, only the file types need be specified in the control file
to uniquely identify the update file. In fact, since all your update files
specified in a control file must have filetypes beginning with the characters
UPDT, you need only specify the unique part of the filetype. The control
file for FICA PLIOPT, named FICA CNTRL, may typically look like the
following:
TEXT MACS PLILIB
FICA3 UP3
FICA2 UP2
FICAI UPI

The first non-commentary record in the control file must be a MACS
record. The second field in this record must be "MACS", and it may be
followed by up to 29 macro library names (subject to the character limit of
the line). Every record in the control file must have an "update level
identifier." In this example, the update level identifiers are TEXT on the
MACS record, FICA1 for the UP1 record, and so on. The update level
identifier may have a maximum of five characters. See the "The STK
Option" on page 111 for more details about the "update level identifier."
The UPDATE command only uses the MACS record and the update level
identifier under special circumstances. These are described later under
"The VMFASM EXEC Procedure" on page 109. For now, you only need to
know that these things must be in a control file in order for the UPDATE
command to execute properly.
Then, to update FICA PLIOPT, issue the UPDATE command as follows:
update fica pliopt (ctl

Chapter 6. Updating Source Programs Using CMS

103

c=._______.____ .___._. ___. _. . ________ .__._________._. __.__ _______.
~

._-_._-------------_._----J

When you use the CTL option and you do not specify the name of a control
file, the UPDATE command looks for a control file with the filetype of
CNTRL and a filename the same as the source file. From the control file, it
reads the filetypes of the updates to be applied. In this example, the
UPDATE command searches for the file FICA UPDTUPl and if found,
applies the updates; then UPDATE searches for FICA UPDTUP2, and
applies those updates, if any. Last it searches for FICA UPDTUP3, and
applies those updates.
Notice that the updates are applied from the bottom of the control file,
toward the top. This becomes important when an update is dependent on a
previous update. For example, if you add some lines to a file in FICA
UPDTUP1, then modify one of those lines in FICA UPDTUP2, it is
important that UPDTUPl was applied first.
Alternate Ways of Naming the Control Files

The example above, showing FICA CNTRL and UPDTxxxx files, illustrates
a naming scheme using the UPDATE command defaults. You can override
the defaults for the control file's filename and filetype.
For example, if you name a control file GROUPA CNTRL, you can specify
the name of the control file on the UPDATE command line. Then to update
FICA PLIOPT using the GROUPA CNTRL control file, issue the following
UPDATE command:
update fica pliopt a groupa cntrl (ctl
AUX Files

The two levels of update processing shown so far may be adequate for your
applications. There is, however, an additional level or step in the update
structure that the VM/SP procedures use and that you may want to use
also.
These techniques may be useful when you have more than one set of
updates to apply to a source program. For example, you may have two
groups of programmers who are working on different sets of changes for the
same source file. Each group may create several update files and have a
unique control file. When you combine these changes, you could create one
control file or you can use what are known as auxiliary control files.
The updating structure for auxiliary control files is based on conventions
for assigning filenames and filetypes. If a control file contains an entry
that begins with the characters "AUX", the UPDATE command assumes
that the file "fn AUXnnnn" contains a list of filetypes, not UPDATE
control statements. For example, if the file SAMPLE ASSEMBLE is being
updated with a control file that contains the record:
TESTl AUXLIST

104

VM/SP eMS for System Programming

[!JJ~jiJcT~Uu'uU SOQj[j'CG fJ [j"QJO[jIE1ulfuG
c=----.-----.-.. -.. ----.----.--.---..--... ---.. -.......----....-.---..-..--... -.. -.......-.. -. - ...-..... -..--.. --....--... :.:.: ........---.-.. --.-..--... ---.. -- ------... ------- .-_.. ----. -- ....... ----......._ . . -......--]

Then SAMPLE AUXLIST does not contain UPDATE control statements. It
contains entries indicating the {iletypes of the update files, all of which
must have the same filename, SAMPLE.
Let's expand the example to see how this structure works. We have the
source file, SAMPLE ASSEMBLE. The file SAMPLE CNTRL contains the
entries:
TEXT MACS
3676 AUXLIST

The file, SAMPLE AUXLIST may look like the following:
TESTI
FIXLOOP
BYPASS

The files:
SAMPLE TESTI
SAMPLE FIXLOOP
SAMPLE BYPASS

all contain UPDATE control statements (INSERT, DELETE, and so on) to
be, applied to the file SAMPLE ASSEMBLE. As with control file
processing, the updates are applied from the bottom of the AUX file, so the
updates in SAMPLE BYPASS are applied first, then the updates in
SAMPLE FIXLOOP are applied, and so on. For an illustration of a set of
update files, see Figure 13 on page 106.

Chapter 6. Updating Source Programs Using CMS

105

___. _______._____===__________.__________.____. ___________.____.___.______________1
REPORT CNTRL

TEXT
UP2
LIST
UP1
TEXT

MACS
UPDTPROC
AUXLlST
UPDTREP1
AUXFIX

REPORT
UPDTPROC

REPORT
UPDTREP1

LU
ll .. .
. /R .. .
./0 .. .

REPORT
AUXLlST

REPORT
AUXFIX

W
/I •••
./0 .. .
./R .. .

REPORT
RTNB

REPORT
FIXIN

LU
ll ...
. /R ...
. /0...

"W
'" WII. .
W/I
...
REPORT
FIXOUT

./R ..•
./0 ...

update report assemble a (ctl)
UPDATING 'REPORT ASSEMBLE A1' WITH 'REPORT RTNA A1'.
UPDATING WITH 'REPORT RTNB A1'.
UPDATING WITH 'REPORT UPDTREP1 A1'.
UPDATING WITH 'REPORT FIXOUT A1'.
UPDATING WITH 'REPORT FIXIN A1'.
UPDATING WITH 'REPORT UPDTPROC A1'.

R;

Figure 13.

An Update with a Control File

106 VM/SP eMS for System Programming

REPORT
RTNA

. /R...

./R .. .

./0...

./0 .. .

QJ~3[~ci~Ouu[J S~~(!Ju'cGe ~Ju~([)qjG'clrrtfMJ
c=----.--.---.---..-----.-.--.. ---..-..-... ----.- . ---.-------------.-----.-.-....--.----.. .---.-------.. -.. --....

-.... _. _... n_._ ...___. ___. ____ . __.__.____ ]

Since the updating scheme uses only filetypes to uniquely identify update
files, it is possible to use the same control file to update different source
input files. For example, issue the following command when using the
control file REPORT CNTRL shown in Figure 13 on page 106:
update fica pliopt a report cntrl (ctl

The UPDATE command begins searching for updates to apply to FICA
PLIOPT, based on the entries in REPORT CNTRL. It searches for FICA
AUXFIX, which may contain entries pointing to update files; then it
searches for FICA UPDTREPl, and so on.
As long as all updates and auxiliary files associated with a source file have
the same filename as the source file, the updates are uniquely identifiable.
Therefore, the same control file can be used to update various source files.
VMjSP takes advantage of this capability in its own updating procedures.
By maintaining strict naming conventions, updates to various CP and CMS
modules are easily controlled and identified.
A control file may point to many AUX files in addition to many UPDT files.
You can modify a control file when you want to control which updates are
applied to a program. You may have several control files, and specify the
name of the control file you want to use on the UPDATE command line.
There is a lot of flexibility in the UPDATE command processing. You can
implement procedures and conventions for your individual applications.

Multiple Updates with XEDIT
The XEDIT CTL option creates multiple updates to a source file. First,
create a control file listing the updates to be applied to a source file.
Initially, you might have only the MACS record and one UPDATE filetype
specified. For example, you can create a file called FICA CNTRL that
contains:
TEXT MACS PLILIB
FICAl UPDTUPl

Next, specify the control file name that you have created after the XEDIT
CTL option. For example:
xedit fica pliopt (ctl fica

The editor searches for an update file called FICA UPDTUPI and applies
all updates contained in this file. If the update file does not exist, XEDIT
creates a file called FICA UPDTUPI which will contain all changes made
to the source file during the editing session in addition to the required
control statements.
If you wish to add another level of updates to your source file, insert a new
update filetype in your control file after the MACS record, for example:
TEXT MACS PLILIB
FICA2 UPDTUP2
FICAl UPDTUPl

Chapter 6. Updating Source Programs Using CMS

107

L _ _ _.

__.___________ .__.____ ._.__.___._______.___ ._______.__._--_._._--J

Then, XEDIT your source file again, specifying the CTL option, for
example:
xedit fica pliopt (ctl fica

XEDIT applies all updates contained in FICA UPDTUPI to the source file
FICA PLIOPT. After the resulting file is displayed, any additional updates
and the necessary control statements are automatically inserted in another
update file called FICA UPDTUP2, consistent with control file processing
from the bottom up.
Auxiliary control files can also be used with XEDIT. You can make your
control file point to AUX files that contain the filetypes of the actual
update files, or you can combine AUX files and update files in a single
control file. XEDIT begins applying updates from the bqttom up in the
control file and references the AUX files indicated. Any updates to the
source file produced during the editing session are inserted in the topmost
update filetype specified in either the control file or in the last AUX file
encountered using the 'bottom up' processing rule. More information about
the XEDIT CTL option can be found in the VM/SP System Product Editor
Command and Macro Reference.
Preferred Level Updating

There may exist more than one version of an update, each applicable to
different versions of the same module. For example, you may need one
version of an update for an unmodified base source module and another
version of that update if that module has been modified by a licensed
program. The AUX file used to update a particular module must then be
selected ,based on whether or not a licensed program modifies that module.
The AUX files listing the updates applicable to modules modified by a /
licensed program are called "preferred AUX files" because they must be
used if they exist rather than the mutually exclusive updates applicable to
unmodified modules. Using this preferred AUX file concept, every module
in a component can be assembled using the one CNTRL file applicable to a
user's configuration.
A single AUX file entry in a CNTRL file can specify more than one filetype.
The first filetype indicates a file that UPDATE uses only on one condition:
the files that the second and subsequent filetypes indicate do not exist. If
they do exist, this AUX file entry is ignored and no updating is done. The
files that the second and subsequent filetypes indicate are preferred because
UPDATE does not use the file that the first filetype indicates. Usually, the
preferred files appear later in the CNTRL file in a format that causes them
to be used for updating.
UPDATE scans each CNTRL file entry until a preferred filetype is found,
until there are no more filetypes on the entry, or until a comment is found.
(A character string less than four or more than eight characters is assumed
to be a comment.)

108 VM/SP eMS for Systein Programming

[---------_._-- ._._. -.---_. __
. --'---'-.-.---------------.-.--..

...._. . _._-_._. . _-_.__._-_.
__.-=-.-._-----------_._._ . _.-,

--------~-------=-.:::-----------------------_

The VMFASM EXEC Procedure
If you are an assembler language programmer and you are using the
UPDATE command to update source programs you may want to use the
VMFASM EXEC procedure. VMFASM is a VM/SP update procedure. It
invokes the UPDATE command and uses the ASSEMBLE command to
assemble the updated source file.
If you are not an assembler language programmer, you may wish to create
an EXEC similar to VMFASM that calls one of the language compilers to
compile an updated source file, instead of calling the assembler.

When you use VMFASM, you specify the source filename, the filename of
the control file, and optionally, parameters for the assembler. (The control
file for VMFASM must have a filetype of CNTRL). For example, if you use
the file GENERAL CNTRL to update SAMPLE ASSEMBLE, you enter the
command line:
vmfasm sample general

The VMFASM EXEC uses the MACS card and the update level identifiers
in the control file. It reads the MACS card to determine which macro
libraries (MACLIBs) should be searched by the assembler. Then VMFASM
issues the GLOBAL MACLIB command specifying the MACLIBs you name
on the MACS card.
VMFASM uses the update level identifier to name the output text file
produced by the assembly. If the update level identifier of the most recent
update file (the last one located and applied) is anything other than TEXT,
the update level identifier is prefixed with the characters TXT to form the
filetype. For example, if the file GENERAL CNTRL contains the records:
TEXT MACS CMSLIB MYLIB OSMACRO
UP2 FIX2
UPl FIXl
TEXT AUXLIST

and updates the file SAMPLE ASSEMBLE, then:
o

If the file SAMPLE UPDTFIX2 is found and the updates applied,
VMFASM names the .output text deck SAMPLE TXTUP2.

o

If the file SAMPLE UPDTFIXI is found and the updates applied but no
SAMPLE UPDTFIX2 is found, the text deck is named SAMPLE
TXT UP 1.

•

If the file SAMPLE AUXLIST is found but no SAMPLE UPDTFIXI or
SAMPLE UPDTFIX2 files are found, the text deck is named SAMPLE
TEXT.

4»

If no files are found, the update level identifier on the MACS card is
used and the text deck is named SAMPLE TEXT.

Chapter 6. Updating Source Programs Using CMS

109

________

=oJ

The new fn TEXT or fn TXTxxxxx resides on the A-disk. Because the
UPDATE command works from the bottom of a control file toward the top,
it is logical that the text filename be taken from the identifier of the last
update applied.
The VMFASM EXEC does not produce an updated source file, but leaves
the original source intact.
VMFASM produces two output files:
•

A printed output listing that shows update activity

•

The text file that contains the update log as well as the actual object
code.

If you use the CMS LOAD command to load a text file produced by
VMFASM, records from the update log are flagged as invalid, but the
LOAD operation is not impaired.

Updating EXECs and Macros
If you wish to use the update facility to track changes to EXECs or macros
written for the System Product Interpreter, you need to use the
EXECUPDT command. The EXECUPDT command applies updates to an
EXEC source file (using the UPDATE command) and removes the sequence
numbers from the updated file to produce an executable version of the file.
Using EXECUPDT is very similar to using the VMFASM EXEC to apply
updates to an assembler language source and to assemble it.

Source files for the EXECUPDT command are fixed-length, 80-character
files with sequence numbers just like those for assembler language or
COBOL. The filetype of the EXEC source file has a '$' prefixed to the
normal filetype. For example, SAMPLE $EXEC could be the source for an
EXEC procedure and READY $XEDIT could be a source file for an XEDIT
macro.
Updates to the EXEC source are created using XEDIT in the same manner
as updates to programs in other languages. To apply the updates to the
source, use the EXECUPDT command. For a single level update, issue the
command:
execupdt sample exec

Note that the '$' in the filetype is not included in the fiJetype specified on
the EXECUPDT command. To do a multi-level update, you may use the
CTL option of EXECUPDT. For example:
execupdt sample exec (ctl general

110

VM/Sp· eMS for System Programming

___

r - - - - ---------

~-U----------h-----------U-------------]

The STI( Option
If you are interested in writing your own EXEC procedure to invoke the
UPDATE command, you may wish to use the STK option. The STK (stack)
option is valid only with the CTL option and is meaningful only when the
UPDATE command is invoked within an EXEC procedure.

When the STK option is specified, UPDATE stacks the following data lines
in the console stack:
first line:
second line:

*
*

update level identifier
library list from MACS record

The update level identifier is the identifier of the most recent update that
was found and applied.
For example, an EXEC 2 EXEC that invokes the UPDATE command and
then the ASSEMBLE command may contain the lines:

&TRACE ALL
UPDATE &1 ASSEMBLE * &2 CNTRL * (STK CTL
&READ VARS &STAR &TX
&READ VARS &STAR &LIBl &LIB2 &LIB3 &LIB4 &LIB5 &LIB6 &LIB7 &LIB8
GLOBAL MACLIB &LIBl &LIB2 &LIB3 &LIB4 &LIB5 &LIB6 &LIB7 &LIB8
&IF &TX NE TEXT FILEDEF TEXT DISK &1 TXT&TX Al
ASSEMBLE &1 &3 &4 &5 &6 &7 &8 &9 &10
ERASE $&1 ASSEMBLE

Below is a System Product Interpreter program that invokes the UPDATE
command and then the ASSEMBLE command:

/* Sample System Product Interpreter program to */
/* Update and Assemble a source program
*/
trace a
parse arg filename cntrlfile options
'UPDATE' filename 'ASSEMBLE *' cntrlfile 'cntrl * (STK CTL'
parse pull star tx
parse pull star libl lib2 lib3 lib4 lib5 lib6 lib7 lib8
'GLOBAL MACLIB' libl lib2 lib3 lib4 lib5 lib6 lib7 lib8
if tx ,= TEXT then 'FILEDEF TEXT DISK' filename 'TXT'tx 'Al'
'ASSEMBLE $'filename options
'ERASE $'filename 'ASSEMBLE'

If the EXEC that you use is named UPASM EXEC, it is invoked with the
line:
upasm fica fica (print noxref

and the file FICA CNTRL contains:
MAC MACS CMSLIB OSMACRO MYTEST
FIXl UPDTFIX
LIST AUXLIST
Chapter 6. Updating Source Programs Using CMS

111

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

then the EXEC 2 EXEC executes the following commands:
UPDATE FICA ASSEMBLE * FICA CNTRL * (STK CTL
GLOBAL MACLIB CMSLIB OSMACRO MYTEST
FILEDEF TEXT DISK FICA TXTFIXl Al
ASSEMBLE $FICA (PRINT NOXREF
ERASE $FICA ASSEMBLE

The System Product Interpreter program executes the following:
/* Update FICA ASSEMBLE using FICA CNTRL */

'UPDATE FICA ASSEMBLE * FICA CNTRL * (STK CTL'
'GLOBAL MACLIB CMSLIB OSMACRO MYTEST'
'FILEDEF TEXT DISK FICA TXTFIXl Al'
'ASSEMBLE $FICA (PRINT NOXREF'
'ERASE $FICA ASSEMBLE'

The above examples assume that the update file FICA UPDTFIX was found
and applied.

112

VM/SP eMS for System Programming

,--

----._--------------•. _---._-

•

Using the Parsing Facility
The CMS parsing facility parses and translates command arguments. Your
programs can use the parsing facility to see if the user specifies the proper
arguments on invocation and to see what the arguments are. For a list of
CMS commands that use the parsing facility, see "Supported CMS
Commands" on page 116.

Advantages of the Parsing Facility
When you use the parsing facility, programming commands is simpler
because:
o

The parsing facility detects invalid command arguments.

o

All keyword abbreviations are expanded for you.

o

Command syntax is defined separately from your program and can be
translated into different national languages.

o

When a national language is in use, keywords in that language are
translated into the language recognized by your program.

o

You do not have to write scanning code.

o

The address and length of each token is provided.

o

Validation codes are provided to identify the type of each token.

Advantages of DLCS
To use the parsing facility, you must define command syntax in a special
language, the definition language for command syntax (DLCS).
Keep the DLCS definitions in CMS files. A file can contain more than one
DLCS definition. The parsing facility parses a specified command by
checking whether all operands, options, keywords, and so on, are specified
according to the DLCS definition for that command.

Chapter 7. Developing Commands and Message' Files

113

Defining command syntax in a DLCS file and using the parsing facility has
the following advantages:
•

Syntax checking is unnecessary in your program.

o

If you want to invoke your program in another national language, you
just have to modify your DLCS file.

Refer to "Coding Your Own Command Syntax with DLCS" on page 117 for
details on using DLCS.

Overview
To have the parsing facility do this checking, do the following:
1.

Write DLCS statements.

2.

Check for any DLCS coding errors using the CHECK option of the
CONVERT COMMANDS command.

3.

Issue the CONVERT COMMANDS command to put your syntax file
into a machine readable form the parsing facility can use.

4.

Issue the SET LANGUAGE command to enable the user's DLCS
definitions.

5.

Issue the P ARSECMD command from a REXX program or EXEC 2
EXEC or the P ARSECMD macro from an assembler program to invoke
the parsing facility and to obtain the parsed and translated parameter
lists.

Coding DLCS Statements

To show how DLCS statements work, here is a standard CMS command
string format:
command_name

[operands ... ] [(options ... ]

DLCS has the following statements:

:CMD
:OPR
:OPT

for a command name
for an operand
for an option

A few other statements you can use in DLCS include:

:SYN
:KW.n
:*

to define synonyms
for command name modifiers
to specify comments

For example, the RDRLIST command has the following format:
RDRLIST [(

[PROFile fn]

114 VM/SP eMS for System Programming

[Append]

[)]]

--.----- =:J

Here is how the syntax for RDRLIST is coded in DLCS:
:CMD D9K.RDRLIST RDRLIST RDRLIST 4
:SYN RLIST 2 : i
:OPT KWL(  ) FCN(FN)
:OPT KWL(  ) : i

.f

:i

The section, "Coding Your Own Command Syntax with DLCS" on page 117,
describes DLCS statements in detail.
Converting Your DLCS File

When you are ready to use the DLCS file, you first have to convert the
DLCS file into an machine readable form the parsing facility can use. Use
the CONVERT COMMANDS command to do this.
You can use the CHECK option of CONVERT COMMANDS to make sure
your DLCS syntax descriptions are correct. In addition, you can issue
CONVERT COMMANDS with the CHECK option while you XEDIT the
DLCS file to help remove errors. Next, use the SET LANGUAGE command
to put the new DLCS definitions into effect.
Refer to the VM/SP CMS Command Reference for a complete description of
CONVERT COMMANDS and SET LANGUAGE.
Setting Command Name Synonyms and Translations

Use the SET TRANSLATE command to set user translation synonyms, user
translations, system translation synonyms, and system translations on or
off. Use the QUERY TRANSLATE command to display the contents of the
system synonym tables, system translate tables, user synonym tables, and
user translate tables.
These commands work similarly to the CMS SYNONYM and QUERY
SYNONYM commands.
(Refer to the VM/ SP CMS Command Reference for descriptions of SET
TRANSLATE, QUERY TRANSLATE, SYNONYM, and QUERY
SYNONYM.)
Invoicing the Parsing Facility

You can invoke the parsing facility in two ways:
1.

From EXEC 2 EXECs or REXX programs, use the P ARSECMD
command.
The P ARSECMD command uses the EXECCOMM interface and creates
EXEC variables that describe the translated command string. See
Figure 14 on page 135 for an example using the PARSECMD command.
Refer to the VM/ SP CMS Command Reference for a description of the
PARSECMD command.
Chapter 7. Developing Commands and Message Files

115

2.

From assembler programs, use the P ARSECMD macro.
The P ARSECMD macro call should be in the beginning of the program.
Upon return from the parsing facility, the syntax of the command is
verified and detailed information on the translated command string is
available. See Figure 16 on page 138 for an example using the
P ARSECMD macro.
Refer to the VM/ SP eMS Macros and Functions Reference for a
description 6f the P ARSECMD macro.

Command keywords are uppercased according to the national language
uppercase table for the active application. If one is not found, the CMS
national language table is used.
o

Supported CMS Commands
The following commands use the parsing facility:
ACCESS
ALARM
CLEAR
COMPARE
CONVERT
COPYFILE
CURSOR
DEFAULTS
DEFINE
DELETE
DISK
DROP
ERASE
EXECDROP
EXECLOAD
EXECMAP
EXECSTAT3
FILELIST
FORMAT
GENMSG

I
I
I'
I
I
I
I
I
I

I
I
I
I
I
I

I

I
I
I
I

GET
HELP
HELPCONV3
HIDE
IDENTIFY
LANGGEN
LANGMERG
LIST FILE
MACLIST
MAXIMIZE
MINIMIZE
MODMAP
MOREHELP
NAMES
NOTE
NUCXDROP
NUCXLOAD
NUCXMAP
PARSECMD
PEEK

POP
POSITION
PRINT
PUNCH
PUT
QUERY
RDR
RDRLIST
READ CARD
RECEIVE
REFRESH
RELEASE
RENAME
RESERVE
RESTORE
ROUTE
SCROLL
SENDFILE
SET
SHOW

SIZE
SORT
STATE
SVCTRACE
SYNONYM
TAPE
TELL
TXTLIB
TYPE
UPDATE
WAITREAD
WAITT
WRITE
XEDIT4
XMITMSG

These commands do not have parameters requiring translation, but the
command name itself can be translated.
4

116

XEDIT subcommands are not supported.

VM/SP eMS for System Programming

[0)'3'Ue~8~)aOuO ~~~IDuuuu-Jll8uJt:JG 80~~J ~YJC::GD(](JC0L)

[--------_._- - -

--------------------------------------------=~====--=~..:..-----------=--=~-=--=~~=-=--=-..:==.:=-=-~=-~~=-=~=~~]

Coding Your Own Command SyntaJc with DLCS

Rules to Remember

Some rules to remember while coding in DLCS are:
o

Use special characters:
<
> and' in your data tokens
(keyword names, function names, or function values) only if they are
enclosed in single quotes. The quotes are not counted as part of the
token.

o

Do not use lowercase characters to specify your keyword names,
function names, or function values. Specify these exactly as they
appear after the command line is uppercased by the system at execution
time with the language in effect.

o

Only the first 72 characters of any line of the DLCS file are used. Any
characters beyond 72 are ignored. You can use as many blanks as you
want between tokens, and you can continue DLCS statements on the
following line.

o

Only one system and one user DLCS file for an application can be made
active at any time. When both a user file and a system file are active,
the definitions in the user file override the definitions in the system file.
If no syntax definition is found in the user file, the definition in the
system file is used.

o

Your DLCS file must be merged with your user file for the application
you currently have. You can have only one user table; therefore, if you
have another command or receive a command from someone, you have
to merge it with the other commands in the user table. (For example, if
you want the CMS search order to find your command, define the
command in a DMS file.)

o

You can define the translation of some keywords to be the same as the
keyword the command recognizes. For more information on translation,
see the VM/ SP eMS User's Guide.

Defining Your Command

Define each command as follows:
1.

Start with a CMD statement to specify the name of the command and its
national language equivalent.

2.

Define any synonyms using SYN statements immediately following the
CMD statement.

3.

Define a two word command using the first word as the command name
and using the KW.l statement to define the second word. If the
command is a three word command, use the KW.2 statement to define
the third word. (The second and third words are command name
Chapter 7. Developing Commands and Message Files

117

modifiers.) You can also have a four word command, a five word
command, etc.
4.

Define the syntax for the command with zero or more OPR statements
followed by zero or more OPT statements.

5.

Use ':;' to specify the end of a statement.

SPECIFYING THE APPLICATION AND NATIONAL LANGUAGE

DLCS Statement: Use the DLCS statement to define the application
where commands in the DLCS file are parsed, to specify whether the
commands are system or user commands, and to specify the national
language for the file.
The format of the DLCS statement is:

:DLCS

applid

System IUser

langid

...,

where:
applid
is an application identifier. It must be three alphanumeric characters,
and the first character must be alphabetic (e.g., DMS, DMK, OFS,
AGW, DKK, etc ... ).
SystemlUser
specifies whether the file contains system or user syntax definition
statements. (Only the first letter is significant.)

langid
is the identifier for the language you are working in. It must be one
to five alphanumeric characters (e.g., FRNCH, AMENG, etc ... ).
Notes:
1.

The DLCS statement must be the first non-comment statement in the
DLCS file, and it must be the only DLCS statement in the file.

2.

The CMS command search order uses translations and translation
synonyms defined in DLCS files with an application identifier of DMS.

3.

The DLCS statement determines the filename and filetype of the output
files.

DEFINING THE COMMAND NAME, SYNONYMS, AND MODIFIERS

118

VM/SP eMS for System Programming

CMD Statement: Use the CMD statement to define the name of a
command as the system sees it and as the language sees it.
The format of the CMD statement is:

:CMD unique-id sl-name

[nl-name n ] :;

where:

I
I
I
I

l

unique-id
identifies the syntax definition for the command within the DLCS file.
This is required, and it must be unique for each syntax definition.
When you invoke the parsing facility, unique-id is matched to the one
you specify in the P ARSECMD.
unique-id is any combination of up to 16 characters. For quick access
to the syntax definitions, the first one or two characters are used as
an index. If the first two characters of unique-id are valid
hexadecimal digits, their value is used as the index. Otherwise, the
EBCDIC value of the first character is used. For example, unique-ids
D9xxx and Rxxx both have the same index value of 217. CMS can find
syntax definitions faster if you use as many of the 256 index values as
possible.
sl-name
is the command name as CMS sees it.
nl-name
is the command name as a national language user sees it. Defaults to
s1-name.
n

is the minimum number of characters that must be entered for nl-name
to be accepted. Defaults to the length of sl-name.

Notes:
1.

A new command syntax begins each time a CMD statement is
encountered ..

2.

All uniqueids used for IBM commands have a period as the fourth
character. Do not use a period as the fourth character in the the uniqueid
for your own commands.

3.

A uniqueid of all blanks is reserved to let you define more than one
translation for a command. When this uniqueid is found, no syntax
information is stored. You can only code the :CMD and :SYN statements
in this case.
Chapter 7. Developing Commands and Message Files

119

4.

The minimum length for abbreviations of command name translations
cannot be more than eight or HELP does not recognize them.

5.

nl-name is only used by the CMS search order if the application identifier
of this DLCS file is DMS.

6.

The SET TRANSLATE command enables or disables nl-name.

7.

If SET ABBREV OFF is in effect, you must use the full nl-name.

SYN Statement: Use the SYN statement to define translation synonyms
for the command name defined on the :CMD statement.
The format of the SYN statement is:

:SYN

newnamel nl

[newname2 n2 ]

:;

where:
newname
is the synonym you are assigning to the command name.
n

is the minimum number of characters you must enter for the synonym
to be accepted by CMS.

Notes:

120

1.

The SYN statement is valid only for the first word of a command name
(not the command name modifiers).

2.

All of the SYN statements for a command must immediately follow the
CMD statement.

3.

Only SYN statements defined in a DLCS file with an application
identifier of DMS are used by the CMS command search order.

4.

The SET TRANSLATE command enables and disables translation
synonyms defined by the :SYN statement.

5.

Using multiple names on a single SYN statement has the same effect as
specifying a single name on many SYN statements. Order is not
important.

6.

If SET ABBREV OFF is in effect, you must use the full newnamel.

VMjSP eMS for System Programming

KW.n Statement: Use the KW.n statement to define command name
modifiers keywords that modify the syntax used for parsing the remaining
parameters. For example, a command to manipulate a simple data base can
require different operands-- a filename for an open request, an option for a
close request, and other operands for update requests. The KW.n statement
lets you define a different syntax for each.
The format of the KW.n statement is:

:KW.n sl-name sl-abbrev

[nl-name

nl-abbrevJ

.,

where:

n
is the number of the level. It defines the nth modifier after the
command name.
sl-name
is the name as the command sees it.
sl-abbrev
is the minimum number of characters that must be entered for sl-name
to be accepted by CMS.
nl-name
is the name as the national language user enters it. Defaults to
sl-name.
nl-abbrev
is the minimum number of characters that must be entered for nl-name
to be accepted by CMS. Defaults to sl-abbrev.

Use the following form of the :KW.n statement to indicate that a string of
characters not defined by any :KW.n statement is accepted as an arbitrary
modifier.

:KW.n

.,

Note: This form may not be used as the first :KW.n statement on a level,
and only applies to :KW.n statements on the same level. No further syntax
information may follow this statement, that is, no :OPR, :OPT, or :KW.n
statements with a larger value for n. When the parsing facility finds an
arbitrary modifier it will process that remainder of the argument string as
one text string.

Chapter 7. Developing Commands and Message Files

121

(

------Example:
Suppose the format of a database command is:
DATABASE

OPEN
UPDATE
UPDATE
CLOSE

filename
ROW
row number
COLUMN
column-name
[(REPLACE [)]]

When the DLCS for t,his command is coded, instead of defining OPEN,
UPDATE, and CLOSE as operand keywords, they are coded as modifiers
(because they modify the syntax) using the KW.n statement. Because each
is the first modifier following the command name, the modifier level (the n
part of KW.n) is 1. In this way, you can define a command with many
modifiers at the same level. You can define the remaining operands and
options differently for OPEN, UPDATE, and CLOSE. The DLCS definition
so far is:
:CMD DATABASE DATABASE .,
: KW . 1 OPEN 4 :;
: OPR FCN ( FN) :;
:KW.1 UPDATE :;
:KW.1 CLOSE 5 :;
:OPT KWL«REPLACE 3» :;

The keywords ROWand COLUMN can only follow UPDATE, and they
modify the syntax further. Each is the second modifier after the command
name, so they are coded as a second level modifier following UPDATE.
Each KW.2 statement on this second level may be followed by either a third
level or operand and option definitions, and so on. These KW.2 statements
nest after the previous KW.l statement so that ROW or COLUMN are only
recognized after UPDATE. The complete DLCS definition for the database
command is:
:CMD DATABASE DATABASE.,
:* A sample syntax
:KW.1 OPEN 4 :;
:OPR FCN(FN):;
:* filename
:KW.1 UPDATE :;
: KW . 2 ROW 3 :;
:OPR FCN(PINTEGER).,
:* row-number
:KW.2 COLUMN 3 :;
:OPR FCN(STRING):;
:* column-name
:KW.1 CLOSE 5 :;
:OPT KWL«REPLACE 3» :;

DEFINING OPERANDS
OPR Statement: Use the OPR statement to define the syntax of each
operand of the command.
The format of the OPR statement is:

122 VM/SP eMS for System Programming

:OPR KWL( kwdef1

[kwdef2

... ]

)

[ OPTIONAL I STOP]
:OPR FCN(

fcndef1

[fcndef2

... ]

FCN(

[kwdef2
fcndef1

... ]

...,

[ REPEAT]

.,

)

[ OPTIONAL I STOP]
:OPR KWL( kwdef1

[ REPEAT]

)

[fcndef2

[ OPTIONAL I STOP]

... ]

)

[REPEAT]

.,

where:

KWL
defines the keyword when an operand (or option when defining an
option) is defined to be a keyword.
FCN
defines functions to be used to validate the value of an operand.

KWLFCN
defines a keyword-value pair using the kwdef and fcndef expressions.
The kwdef and fcndef expressions are defined on pages 124 and 125.
OPTIONAL
indicates the operand can optionally be specified.
STOP
specifies that if the operand is not specified then parsing of the
operands stops at that point and no more operands can be specified.
REPEAT
indicates the operand can be specified one or more times.
Notes:
1.

Specify aPR statements in the order the operands are specified on the
command.

2.

Specify the aPR statement after the CMD statement and present SYN
statements or after appropriate KW.n statements.

3.

If both OPTIONAL (or STOP) and REPEAT are specified, the operand
can be specified zero or more times.

Chapter 7. Developing Commands and Message Files

123

D)Gt7G~Q)~J)DuuQJ CC})uu'iluuuE.lliu0]S @Eu(;] Me9D@gC:;9
c::--_~

__

--

4.

---.---.--.-.-----.---------~

If no options are specified, the operand is a required operand that can be
specified only once.

DEFINING OPTIONS
OPT Statement: Use the OPT statement to define the syntax of the
options for the command.
The format of the OPT statement is:

J)

:OPT KWL( kwdefl

[ kwdef2

...

:OPT KWL( kwdefl

[ kwdef2

... ] )

FCN (

fcndefl

:;

[fcndef2

••• ] )

.,

where:

KWL
defines the keyword when an option (or operand when defining an
operand) is defined to be a keyword.
KWLFCN
defines a keyword-value pair using the kwdef and fcndef expressions.
The kwdef and fcndef expressions are defined below.
Note: OPT statements must follow the last aPR statement, if any were
used, for that command. Order of the OPT statements is not important.
,/

kwdef EXPRESSION

The format of kwdef is:

[

< sl-name

sl-abbrev

[nl-name

nl-abbrevJ >

where:
sl-name
is the keyword known by your command.

124 VM/SP eMS for System Programming

]

_..... _._._ .... ----_ .. _-_ ....-_.--_._-------_ .. _--------_._--------_..

["

_ ..-._-_._----_._--_.__.--_._]

sl-abbrev
is the minimum number of characters that must be entered for sl-name
to be accepted.
nl-name
is the keyword known by a national language user. Defaults to
sl-name.
nl-abbrev
is the minimum number of characters that must be entered for nl-name
to be accepted. Defaults to sl-abbrev.
fcndef EXPRESSION
fcndef can be anyone of the system functions listed below. In addition,
fcndef can be a user function. See "User Functions" on page 127 for more
information.

System Functions
Syntax

Description

ALPHANUM

any alphanumeric string

APPLID

any three character alphanumeric string with the first
alphabetic

CHAR

any single nonblank character

CUU

any hex number between 001 and FFF (assumes leading
zeros)

DIGITS

any unsigned number made up of digits 0-9

FN

(filename) any string with the following characters:
A-Z,a-z,0-9,$,#,@, + ,-,:, and _

FT

(filetype) any string with the following characters:
A-Z,a-z,0-9,$,#,@, + ,-,:, and _

FM

(filemode) first character: A-Z, a-z; optional second
character: 0-6

EFN

same as FN with ,*, or '%' also a valid character

EFT

same as FT with ,*, or '%' also a valid character

EXECNAME

any string that d'oes not contain the following characters:
= ,*,(,),' " and X'FF'

Chapter 7. Developing Commands and Message Files

125

EXECTYPE

any string that does not contain the following characters:
= ,* ,(,),' " and X'FF'

HEX

any hexadecimal number

INTEGER

any decimal whole number (can have

NINTEGER

any decimal negative whole number

PINTEGER

any decimal positive whole number (can have + sign)

MODE

any alphabetic character

STRING

any nonblank character string

TEXT

any character string

INVALID

no valid values

+ or - signs)

Notes:

I-

1.

You can specify function definitions with a subset of valid values. Only
items in the subset are valid. For example, if you specify
STRING(MONDAY, TUESDAY, WEDNESDAY), MONDAY,
TUESDA Y, and WEDNESDA Yare the only valid values.

2.

If a list of functions is specified for fendef, the parsing facility validates
an operand or option value with the functions in the order they are
specified. The first function the value is valid for determines the
validation code of the value in PVCENTRY. Refer to the VM/SP CMS
Macros and Functions Reference for more information on the
PVCENTRY macro.

3.

Input to the parsing facility is uppercased according to current language
before it is provided to system or use'7- functions for validation.

4.

If a value is not valid according to any of the functions in the list, the
first one is used to determine which message, if any, is issued. If an error
message based on the first function is not appropriate, place the
INVALID function first in the list. For example:

I
I
I

:OPR FCN(INVALID, INTEGER(2,4,6), MODE)

:i

The invalid function never accepts a value as valid, but a general error
message is issued when a value is not valid according to the rest of the
functions in the list.
5.

Because some functions will validate tokens that are also valid for other
functions, you should be careful to list the most restrictive functions first.
For example, an operand defined as:
:OPR FCN(STRING, DIGITS, FN):i

126

VM/SP eMS for System Programming

c-·-·····--- ----.--... --- ....-.-.-.... -- . ---.. ---. .. -...--_. -.-.......... -.-....-.-.. --.....----.--- -.--_. ---..----.....-..----.----.. ---.-----------.--.. -.-..--.-.. -..--.- . ---.-. -.-.---.. .

-]

will always be validated as a string, while the syntax:
:OPR FCN(FN) REPEAT:;
:OPR FCN(DIGITS):;

can never be satisfied because the required digits operand will be
validated as part of the list of filenames.
6.

The TEXT function cannot be specified in a list with any other function.

User Functions
In addition to the system functions listed above, you can also make your
own functions for the parser to use to check if a token is valid. For
instance, you could make a function VOWEL that considers only alphabetic
characters A,E,I,O and U valid.
After you make your program for your function, assemble it, load it with
the RLDSA VE option, and use the GENMOD command. Then install the
MODULE file of this assembled program as a nucleus extension. Next,
include the name of your function in the DLCS for your command exactly
as you would any other function. The function is invoked by the parsing
facility with an SVC 202. The entry point name of the module must be the
same as the function name (fcndef) in your DLCS file. Your function is
passed the following parameters:
o

An eight byte area containing the function name

o

token-addr: a fullword containing the address of the token to be
validated. The token is already uppercased according to the current
language.

o

token-length: a full word containing the number of characters in the
token.

o

validation code: a byte containing the number interpreted by the parser
as the validation code of the user function. If the token is valid, this
field should be set by the user function. Upon return from the parsing
facility, you can check this validation code to see if your token is valid.

On entry to the program, Rl contains the address of the control block
containing the parameters described above. Use the assembler macro
P ARSERUF to generate a mapping of this control block.
Your program must pass back a return code in R15 that determines the
outcome of the function. A return code of zero specifies the token was
valid; a non-zero return code specifies the token was not valid. You can use
any non-zero return code except -3; this return code would be interpreted to
mean the function did not exist.·

Chapter 7. Developing Commands and Message Files

127

[J)GvGUO[J)Uuu[j COuliuuu'ilC}uu0JS

C}uu0J

~JJG9888GS

c:::: __________________.__ ._____._______________________

~:=~_==_=_==_

_________ __. _.

Notes:
1.

User functions do not override system functions with the same name
(system functions come first in the search order).

2.

When you use CONVERT COMMANDS to process your DLCS file,
specify the ALL or USER options for user functions to be accepted.

3.

When coding user functions in your CDSL file, you can enclose specific
values in parentheses as you can with any system functions and only
those values are accepted.

DEFINING ROUTINES AND KEYWORDS
Note: The :RTN and :KWD statements are reserved for IBM use. You may
not use them in writing your own commands in DLCS. They are only
shown here so that if you need to make your own translation of eMS
commands you can do so without introducing errors into the syntax or its
definition.
RTN Statements: Use the RTN statement to define the routine
responsible for parsing the command.
The format of the RTN statement is:

:RTN

routine-name

...,

where:
routine-name
is a eMS defined name.
Notes:
I

1.

When the :RTN and :KWD statements are used, they replace (and are
nutually exclusive with) the :OPR and :OPT statements. There is one
:RTN statement followed by any number of :KWD statements.

2.

When you are translating a CMS command that uses routine parsing, you
should only changed the nl-name and nl-abbr fields on the :KWD
statement. You must not add or delete :KWD statements or change the
routine and system language names.

I'
I

128

VM/SP eMS for System Programming

~J(:;UG~(G[)Uu'uCJ (GOu·u'uuullc)ullQ.JS c}u-ll(~] ~UJr3GS~]~]::)n
------ ----- -------- -----------_____ __
_. __..

L_::" _._~_~~~~:~~~~_~~~~~_-~-=:_=:.._...::===~-.--

--~:::...~__=:.::.:.:::.:_==_=~_=:=.::.::...~~

~ :._.::._:~

_~--J

KWD Statements: Use the KWD statement to define the keywords that
the command contains for translation purposes.
The format of the KWD statement is:

:KWD

sl-name sl-abbrev

[nl-name

nl-abbrev]

.,

where:
sl-name
is the CMS defined keyword name.
sl-abbrev
is the minimum number of characters that must be entered for sl-name
to be accepted by CMS.
nl-name
is the keyword as a national language user enters it.
nl-abbrev
is the minimuni number of characters that must be entered for nl-name
to be accepted by CMS.
Notes:
1.

When the :RTN and :KWD statements are used, they replace (and are
nutually exclusive with) the :OPR and :OPT statements. There is one
:RTN statement followed by any number of :KWD statements.

2.

When you are translating a eMS command that uses routine parsing, you
should only changed the nl-name and nl-abbr fields on the :KWD
statement. You must not add or delete :KWD statements or change the
routine and system language names.

Writing Comments

Comments: Use the characters :* to specify that a line or the remaining
characters of a line are to be ignored. Use this to put comments and
explanations in your DLCS file.
The format of a comment is:

[DLCS statements or parts of a statement]

...'t

comment

Chapter 7. Developing Commands and Message' Files

129

............... _,...._.___ ._. __.~~_:::.:~_:=:J
where:
comment
is any comment
Creating a DLCS File

For examples of creating a DLCS file, see "Creating a DLCS File" on
page 131 and "Creating a DLCS File with National Language Translations"
on page 132.
What the Parser Does Not Flag

1.

2.

The parser does not flag the following situations:
o

Dependent options and operands. The MAP operand of the
MACLIB command gives an example. Refer to the VM/ SP eMS
Command Reference.

o

Mutually exclusive options or operands. This is where you have a
pair of operands or options. You must specify one or the other -you cannot specify neither or both. The ACK and NOACK
operands of the NOTE command give an example. Refer to the
VM/ SP CMS Command Reference. Most commands that have
mutually exclusive options or operands ignore the condition and use
the last operand or option you specify.

Some IBM supplied commands also use the RTN and KWD statements
for special purposes. Do not use these statements for your own
commands.

oecs and the Parsing Facility
This section lists rules to remember when the current language is a
double-byte character set (DBCS) language.
In DLCS and CONVERT COMMANDS

130

o

You can use DBCS characters only in keyword, modifier, and command
names.

o

You can mix single byte and DBCS characters in a name in the DLCS,
but CONVERT COMMANDS only recognizes single byte characters as
DLCS delimiters.

o

Shift-out and shift-in characters are always recognized as DBCS
delimiters in a DLCS definition regardless of the current language.

o

A double byte character is treated as a single logical character. When
you specify the minimum length for abbreviations of synonyms or
translations, count double byte characters and EBCDIC characters as
single logical characters and ignore shift-out and shift-in characters.

VM/SP eMS for System Programming

[------------------------_.. _------_._-----

For example, if you have the keyword 'abcd rru k1k2k3 mefg', setting
the minimum abbreviation of four allows 'abcd' as the shortest
abbreviation. Setting the minimum abbreviation of five, would allow
'abcd ~ k1m ' as the shortest abbreviation. Setting the minimum
abbreviation of six allows 'abcdrru k1k2
as the shortest abbreviation,
and so on.

ill '

o

If you use DBCS characters when adding translations and translation

synonyms to a DLCS file, you can issue CONVERT COMMANDS and
SET LANGUAGE on these translations. However, you can only use
these commands if the language you are using is set up as a double-byte
language.
From CMS

o

DBCS or mixed DBCS command names and keywords are accepted.
DBCS strings cannot be specified for operand and option values such as
filename, filetype, filemode, cuu, and so on.

o

Each token in the tokenized PLIST is resolved to be a complete DBCS
string. In other words, one of these tokens can contain no more than
three double byte characters.

o

When you invoke CMS commands, you can use DBCS EBCDIC to
specify CMS delimiters such as blanks or parentheses.

Examples: Using the Parsing Facility
Creating a DLCS File

You have two commands, MYCMD1 and YOURCMD.
MYCMD1 has the following syntax:
MYCmdl fn ft [ ( [DlskIPRint]

[NUMrecs nnn]

[)]

]

YOURCMD has the following syntax:
YOURcmd string [ (TYPE [)]

]

Instead of coding syntax checking into your program, you plan to invoke
the parsing facility for these commands. So you have to create a DLCS file
to contain both syntax definitions.
You can create a CMS file called TEST DLCS to contain the statements for
these commands that could look like this:

Chapter 7. Developing Commands and Message 'Files

131

L_.____ .

1
2
3

4
5
6
7
8
9

10
11
12

:DLCS DMS USER AMENG : i
:* The first command
:CMD MMYCMD1 MYCMD1 MYCMD1 3 0'
:SYN MY1 3 : i
:OPR FCN(FN) : i
: OPR FCN ( FT ) : i
:OPT KWL«DISK 2>   0

I/O performed by AUXPROC routine with residual count
in GPR15. DMSSEB returns normally.

GPR15 = 65,536

I/O performed by AUXPROC routine with zero residual
count.

Chapter 8. Developing

as Programs under CMS 167

_________._. _.___.__:::J

L.:~ ....

Passing Information to the DMSTVI Routine: An interface routine,
DMSTVI, can be used to give control to a different multivolume switching
routine than the one supplied with VM (DMSTVS) or a tape management
system.
Use the new SYSPARM option to pass information not included on the
FILEDEF or LABELDEF command to the DMSTVI routine.
When DMSTVI is called, the general-purpose registers contain the
following information:
GPR1
GPR 14
GPR 15

= Address of a parameter list defined by the TVISECT DSECT
= Return address
= Entry point address

The calling routine saves and restores the register contents.
When DMSTVI'gets control, it must check the call function keyword in the
register 1 PLIST. The call function keyword identifies the function being
processed when DMSTVI is called. DMSTVI should use the information in
the PLIST to build a command or to invoke the tape volume switching
routine or tape management system.
When DMSTVI is called during FILEDEF processing, only the call function
(SYSP ARM) and the SYSPARM string address and length field are filled in.
The other fields are set to zeroes.
Because DMSTVI gets control during OPEN macro processing before any
I/O is done, you do not have to mount a tape before OPEN is issued. The
interface routine can mount the tape before returning control to OPEN
macro processing.
If you specify only the first volid of a multivolume tape and the end of the
first volume is reached, DMSTVI gets control with a call function of 'EOV'
and a volid of SCRATC. The tape management system can mount the next
volume if it knows what tape is currently mounted on the drive and the
volid of the next volume in the series.

A 44 character fileid can now be entered with the LABELDEF command.
The 44 character fileid is passed to DMSTVI during OPEN, EOV, and
CLOSE macro processing. DMSTVI should check the TVISCRAT field in
the register 1 PLIST to determine if a tape was requested from the tape
management system. DMSTVI checks the TVISCRAT field by giving a
fileid.
If the TVISCRAT field contains 'SCRATCH', a scratch tape was requested.
If this field contains 'NOSCRATC', a scratch was not requested -- 'SCRATC'
was put in TVIVOLID as a default. If a fileid is also specified (TVIFILID),
a tape containing this fileid was requested. If you want to mount a tape by
specifying just the fileid, you should not specify any volid on FILEDEF or
LABELDEF (including 'SCRATCH').

168

VM/SP eMS for System Programming

ITJGnJ0)~(0[)Uu uU

08 [JutGJOu'c:lu'u'uG

c-------.. . --...--. -.-.---------..----------.---.----..--------.-------..--...---.--.----.----.. ----.----.-----.--.--.-.. -.-.- . -.-----------

---.-_==-:::.::.:~

If no fileid is specified on the LABELDEF command, the TVIFID field in
the register 1 PLIST contains all zeros. The system uses the ddname
(TVIFILE) as the default.

DMSTVI must return to the calling routine when processing is complete.

Creating eMS Files from OS Data Sets
If you have data sets on OS disks, on tapes, or on cards, you can copy them
into CMS files so that you can edit, modify, or manipulate them with CMS
commands. The CMS MOVEFILE command copies OS (or CMS) files from
one device to another. You can move data sets from any valid input device
to any valid output device.

Before using the MOVEFILE command, you must define the input and
output data sets or files and assign them ddnames using the FILEDEF
command. If you use the ddnames INMOVE and OUTMOVE, then you do
not need to specify the ddnames when you issue the MOVEFILE command.
For example, the following sequence of commands copies a CMS disk file
into your virtual card punch:
filedef inmove disk diskin file al
filedef outrnove punch
rnovefile

The result of these commands is effectively the same as if you had issued
the command:
punch diskin file (noheader

The example does, however, illustrate the basic relationship between the
FILEDEF and MOVEFILE commands. In addition to the MOVEFILE
command, if the OS input data set is on tape or cards, you can use the
TAPPDS or READCARD command to create CMS files. These are also
discussed below.
Note: The MOVEFILE command does not support data containing spanned
records. In addition, when copying a variable length data set (RECFM = V
or VB) from an OS disk to a CMS disk, the logical record length (LRECL)
of the file that is created on the CMS disk is equal to the size of the largest
record in the data set being copied. If the file that is being created has a
filemode of 4, the logical record length will be equal to the LRECL of the
largest record plus 8 bytes. The actual LRECL of the new file can be
determined by using the CMS LISTFILE command.
Copying Sequential Data Sets from Disk

The MOVEFILE command copies a sequential OS disk data set from a
read-only OS disk into an integral CMS file on a CMS read/write disk. You
use FILEDEF commands to identify the input file disk mode and data set
name:
filedef inmove cl dsn sales.manual

Chapter 8. Developing

as Programs under CMS 169

l ____.___._

__ . ____._____....._._.__ .__ . ___. ___________ . ._.___.____... _. ______. _. __., _______.__._.~. . __ =:=J

the CMS output file's disk location and fileid:
filedef outmove disk sales manual al

and then you issue the MOVEFILE command:
movefile
Copying Partitioned Data Sets From Disk

The MOVEFILE command can copy partitioned data sets (PDS) into CMS
disk files and create separate CMS files for each member of the data set.
You can have the' entire data set copied, or you can copy only a selected
member. For example, if you have a partitioned data set named
ASSEMBLE.SOURCE whose members are individual assembler language
source files, your input file definition might be:
filedef inmove cl dsn assemble source
or
filedef inmove cl dsn assemble. source

To create individual CMS ASSEMBLE files, you would issue the output file
definition as:
filedef outmove disk qprint assemble al

Then use the PDS option of the MOVEFILE command:
movefile (pds

When the CMS files are created, the filetype on the output file definition is
used for the filetype and the member names are used instead of the eMS
filename you specified.
If you want to copy only a single member, you can use the MEMBER
option of the FILEDEF command:
filedef inmove disk assemble source c (member qprint

and omit the PDS option on the MOVEFILE command:
movefile

The following figure summarizes the' various ways that you can create CMS
files from OS data sets.

170

VM/SP eMS for System Programming

r'" -.... --.- ... _- . .---.. - . --.-.. . .- _. _._. . _n_ -.- --.. -.- --------.------.-----.-----.- .--.--._-- -.--.------....- . --

Input File:

An

as

"_'"

._._._. _. _ _ _ _ _ _

. . . . . . . ._

Sequential Data Set Named:

....._

... __ .. _ .. _

CMS Output File

Disk:
OS RIO
C-disk

filedef indd c1 dsn compute test records
filedef outdd disk compute records a1
movefile indd outdd

COMPUTE RECORDS A1

Tape:
181

filedef inmove tap1 (Irecl 80
filedef outmove disk test records a1
movefile

TEST RECORDS A1

tappds newtest compute (nopds

NEWTEST COMPUTE A1

filedef cardin reader
filedef diskout disk compute cards a1
movefile cardin diskout

COMPUTE CARDS A1

readcard compute test

COMPUTE TEST A1

Input file:

Disk:
OS RIO
C-disk

Tape:
182

Figure 20.

_

. . . . . . _ _ . . . . . . . . . . . . . . . . " ' " ' ' • _ _ ._

... __ • __ .

_ _ ... "

_ .. n _ . . . . . . . . _ _ ... _ _

.. ]

COMPUTE.TEST.RECORDS

CMS Command Examples

Cards:

... _ .

as Partitioned Data Set Named: TEST.CASES
Members named:
SIMPLE, COMPLEX, MIXED

CMS Command Examples

CMS Output File(s)

filedef infile c1 dsn test cases
filedef outfile disk new testcase a1
movefile infile outfile (pds

SIMPLE TESTCASE A1
COMPLEX TESTCASE A1
MIXED TESTCASE

filedef in c1 dsn test cases (member sim'ple
filedef run disk
movefile in run

FILE RUN A1

tappds

* test run

(tap2

SIMPLE TESTRUN A1
COMPLEX TESTRUN A1
MIXED TESTRUN A1

Creating CMS Files from OS Data Sets

Using eMS libraries
CMS provides three types of libraries to aid in OS program development:
o

Macro libraries contain macro definitions and/or copy files.

o

Text, or program libraries contain relocatable object programs
(compiler output).

o

LOADLIB libraries contain link edit files (load modules).

These CMS libraries are like as partitioned data sets; each has a directory
and members. Since they are not like other CMS files, you create, update,
and use them differently than you do other CMS files. Although these
library files are similar in function to as partitioned data sets, as macros

Chapter 8. Developing

as Programs under CMS 171

[Q)Q'\7G~@L3Uuu~
r...::.~~=-_.

08

LJ~1(Q)f~C10Uu\)O

__________. ________ _____.____.___. ______. _____. _____ .______ . _______._. ________.__________. . .
~

should not be used to update them. Macro libraries are discussed below;
text libraries are discussed under "TEXT Libraries (TXTLIBs)" on page 181,
and LOADLIB libraries are discussed under "OS Module Libraries and
CMS LOADLIBS" on page 183.

Macro Libraries (MACLIBs)
A CMS macro library has a filetype of MACLIB. You can create a
MACLIB from files with filetypes of MACRO or COPY. A MACRO file may
contain macro definitions. COpy files contain predefined source
statements.
The MACLIB Command

The MACLIB command performs a variety of functions. You use it to:
o
o
o
o

Create the MACLIB (GEN function).
Add, replace, or delete members (ADD, REP, and DEL functions).
Compress the MACLIB (COMP function).
List the contents of the MACLIB (MAP function).

Descriptions of these MACLIB command functions follow.

Creating a Macro Library: The GEN (generate) function creates a CMS
macro library from input files specified on the command line. The input
files must have filetypes of either MACRO or COPY. For example:
mac lib gen osmac access time put regequ

creates a macro library with the file identifier OSMAC MACLIB Al from
macros existing in the files with the file identifiers:
ACCESS {MACRO} , TIME { MACRO} , PU.T {MACRO}, and REGEQU {MACRO}.
COPY
COpy .
COpy
. COpy

If a file named OSMAC MACLIB Al already exists, it is erased.

Assume that the files ACCESS MACRO, TIME COPY, PUT MACRO, and
REGEQU COpy exist and contain macros in the following form:
ACCESS MACRO
GET
PUT

COpy

PUT MACRO

REGEOU COpy

*COPY TTIMER
TTIMER
*COPY STIMER
STIMER

PUT

XREG
YREG

The resulting file, OSMAC MACLIB AI, contains the members:
GET
PUT
TTIMER

172

STIMER
PUT
REGEQU

VM/SP eMS for System Programming

[D)G\'Je~(Q~)Uuut1
r----.--- ________________

m

_________

([DS ~~u"@[jU"8uJ~S

----------- - - - - - - - - - - - - - - - - - - - - - - . - - - - - - - - . - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - )

The PUT macro, which appears twice in the input to the command, also
appears twice in the output. The MACLIB command does not check for
duplicate macro names. If, at a later time, the PUT macro is requested from
OSMAC MACLIB, the first PUT macro encountered in the directory is
used.
When COpy files are added to MACLIBs, the name of the library member is
taken from the name of the COPY file or from the *COPY statement, as in
the file TIME COPY, above.

Note: Although the file REGEQU COpy contained two macros, they were
both included in the MACLIB with the name REGEQU. When the input
file is a MACRO file, the member name(s) are taken from macro prototype
statements in the MACRO file.

Adding a Member to a Macro Library: The ADD function appends new
members to an existing macro library. For example, assume that OSMAC
MACLIB Al exists as created in the example in the explanation of the GEN
function and the file DCB COpy exists as follows:
*eopy DeB
DeB macro definition
*eOpy DeBD
DeBD macro definition

If you issue the command:
maclib add osmac deb

the resulting OSMAC MACLIB Al contains the members:
GET
PUT
TTIMER
STIMER

PUT
REGEQU
DeB
DeBD

Replacing a Member of a Macro Library: The REP (replace) function
deletes the directory entry for the macro definition in the files specified. It
then appends new macro definitions to the macro library and creates new
directory entries. For example, assume that a macro library MYMAC
MACLIB contains the members ALPHA, BETA, and SIGMA, and that the
following command is entered:
maclib rep mymac alpha sigma

The files represented by file identifiers ALPHA MACRO and SIGMA
MACRO each have one macro definition. After execution of the command,
MYMAC MACLIB contains members with the same names as before, but
the contents of ALPHA and SIGMA are different.

Chapter 8. Developing

as Programs under OMS 173

[liG~rrG~(Q)[:vnuuQJ
c=-.__

=-_____,

08

[Ju'QQJr@u1u6
____ . . __ ~~_._.~.__ ._.___J

Deleting a Member of a Macro Library: The DEL (delete) function
removes members from the macro library directory and compresses the
directory so there are no unused entries. The macro definition still
occupies space in the library, but since no directory entry exists, it cannot
be accessed or retrieved. If you attempt to delete a macro for which two
macro definitions exist in the macro library, only the first one encountered
is deleted. For example:
mac lib del osmac get put ttimer deb

deletes macro names GET, PUT, TTIMER, and DCB from the directory of
the macro library named OSMAC MACLIB. Assume that OSMAC exists as
in the ADD function example. After the above command, OSMAC MACLIB
contains the following members:
STIMER
PUT
REGEQU
DeBD

Compressing a Macro Library: Execution of a MACLIB command with
the DEL or REP functions can leave unused space within a macro library.
The COMP (compress) function removes any macros that do not have
directory entries. This function uses a temporary file named MACLIB
CMSUTl. For example, the command:
maclib comp mymac

compresses the library MYMAC MACLIB.

Listing Information about Members of a Macro Library: The MAP
function creates a list containing the name of each macro in the directory,
the size of the macro, and its position within the macro library. If you want
to display a list of the members of a MACLIB at the terminal, enter the
command:
maclib map mylib (term

The default option, DISK, creates a file on your A-disk, which has a filetype
of MAP and a filename corresponding to the filename of the MACLIB. If
you specify the PRINT option, the list is spooled to your virtual printer as
well as being written onto disk.
Note: The DISK, PRINT, and TERM options erase the old MAP file.

You can also retrieve information for specific members of the library by
indicating the member names following the MAP operand. For example:
mac lib map mylib swerve yield

returns the MAP output for only members SWERVE and YIELD of MYLIB
MACLIB.
If you want to place that information in the program stack, use the STACK
option of the MAP operand. The information can be stacked FIFO (first-in

174 VM/SP eMS for System Programming

c=. . .-.. "....''.--.-.-----.-.''--''''-.. -..-.-''. . -_._''-...__.''-_-..-_"-_. ,,_
..-_-._.. -_ _",,-_...-_--_... -_.-_._. . -._.". _. . ._--_. -_.-._--., _-._-._
..-_-"_-_-"_-". _. .-_-".-_. -_. _-."."........... ,,- .. - . . _._ ...._·... _._· ..

" " h n . _ · ·• • _

•••....•..•••••• - ,

first-out} or LIFO (last-in first-out). The default order when STACK is
specified alone is FIFO. The options STACK, STACK FIFO, and FIFO are
equivalent. The options STACK LIFO and LIFO are equivalent. For
example:
maclib map mylib neutral reverse (stack fifo

stacks in the program stack, the MAP output for the NEUTRAL and
REVERSE members of MYLIB in first-in first-out order.
See "The MAC LIST Command" on page 176 for more information on listing
members of a MAC~IB.
Manipulating MACLIB Members

The following CMS commands recognize MACLIBs and have a MEMBER
option:
o
o
o
o
o

XEDIT (to create and/or edit a specific member).
PUNCH (to punch a member)
FILEDEF (to establish a file definition for a member)
PRINT (to print a member)
TYPE (to display a member at the terminal)

You can use the editor to create MACRO and COpy files and then use the
MACLIB command to place the files in a library. Once they are in a
library, you can erase the original files, or you can edit a member of a CMS
library using the XEDIT command with the MEMBER option. For
example, entering the command:
xedit mylib maclib al {member swerve

If the SWERVE member does not exist in that library, a new file is created
with a fileid of SWERVE MEMBER Al. If SWERVE is an existing member
of MYLIB MACLIB, you can edit the file.

You can also select members of a specific CMS library to edit from your
MACLIST (invoked by the MACLIST command).
Note: You cannot create a new MACLIB using the MEMBER option of the
XEDIT command. You must use the MACLIB command with the GEN
option to create a new MACLIB.
To extract a member from a macro library, you can use either the PUNCH
or the MOVEFILE command. If you use the PUNCH command, you can
spool your virtual card punch to your own virtual reader:
cp spool punch to

*

Then punch the member:
punch testmac maclib {member get noheader

and read it back onto disk:
Chapter 8. Developing OS Programs under CMS

175

r-c-.- . -.. -....-._-....-...-... _-_.-.. _-.__-.._-___-_-.-_.::-_.____ -=-=.:.=_=--=:=-_-.-_=.~=__.._._-_._-.. .::.___--_~_=_.:.-...._-._".-.".-"..- . . -.. . .-"...... _-._.. -._..-: .. .

.. ........... ___ . _"""_,,,.,,,._,.__ '_' ._.• ____._..J

readcard get macro

In the above example, the member was punched with the NOHEADER
option of the PUNCH command, so that a name could be assigned on the
READ CARD command line. If a header card had been created for the file,
it would have indicated the filename and file type as GET MEMBER.
If you use the MOVEFILE command, you must issue a file definition for the
input member name and the output macro or copy name before entering the
MOVEFILE command:
filedef inmove disk testcopy maclib (member enter
filedef outmove disk enter copy a
movefile

This example copies the member ENTER from the ·macro library
TESTCOPY MACLIB into a CMS file named ENTER COPY.
When you use the PUNCH or MOVEFILE commands to extract members
from CMS MACLIBs, each member is. followed by a / / record, which is a
MACLIB delimiter. You can edit the file and use the DELETE
subcommand to delete the / / record.
If you want to move the complete MACLIB to another file, use the
COPYFILE command.

To print asingle member or all members of a macro library, use the CMS
PRINT command with the MEMBER option. To display on the terminal a
single member or all members of a macro library, use the CMS TYPE
command with the MEMBER option.
The MACLIST Command

The MACLIST command displays a list of all members in a specified macro
library. MACLIST provides you with an easy way to select and edit CMS
maclib members. CMS commands can be issued against the members
directly from the displayed list. The commands execute when you press the
ENTER key.
In the MACLIST environment, information that is normally provided by the
MACLIB command (with the MAP option) is displayed under the control of
the System Product editor. You can use XEDIT subcommands to
manipulate the list itself.
The following MACLIST screen was created by issuing the MACLIST
command as follows:
maclist mylib

Note that the members are sorted alphabetically by member name.
Members with the same name are then sorted by index number (least to
greatest).

176

VM/SP eMS for System Programming

r

FARRELL MACLIST AO V 130 Trunc=130 Size=18 Line=l Col=l Alt=O
Cmd
Member name
Index
Records
Library name Library type Mode
CAUTION
190
6
MYLIB
MACLIB
Al
FAST
240
25
MYLIB
MACLIB
Al
FORWARD
613
57
MYLIB
MACI.IB
Al
GO
197
25
MYLIB
MACLIB
Al
GO
615
25
MYLIB
MACLIB
Al
LTURN
546
MYLIB
MACLIB
Al
55
NEUTRAL
266
MYLIB
MACLIB
Al
5
PARK
602
4
MYLIB
MACLIB
Al
REVERSE
272
118
MYLIB
MACLIB
Al
RTURN
524
21
MYLIB
MACLIB
Al
SKID
391
43
MYLIB
MACLIB
Al
SLOW
671
61
MYLIB
MACLIB
Al
SLOWER
435
5
MYLIB
MACLIB
Al
SLOWEST
441
82
MYLIB
MACLIB
Al
SPEED
2
132
MYLIB
MACLIB
Al
STOP
607
MYLIB
MACLIB
Al
5
SWERVE
223
16
MYLIB
MACLIB
Al
YIELD
MYLIB
135
54
MACLIB
Al
2= Refresh 3= Quit
1= Help
4= Sort(name) 5= Sort(index) 6= Sort(size)
7= Backward 8= Forward 9= FL In 10=
11= XEDIT
12= Cursor
====>
XED I T 1 File

\.

Figure 21.

'"

~

Sample MACLIST Screen

Finding Members in Your MACLIST List: If there are many members in
the maclib, the list may take up more than one screen. To find a member in
your MACLIST list, you can do any of the following:
o

o

Scroll through the list using the PF keys.

PF7

Scrolls backward one full screen.

PF8

Scrolls forward one full screen.

Rearrange the list using one of the following PF keys:

PF4

Sorts the list by member name. This is how the list is
initially arranged.

PF5

Sorts the list by index (largest first). The most recently
updated members have a greater number.

PF6

Sorts the list by size (largest to smallest).

o

Use the XEDIT subcommand LOCATE if you know the member name
that you are looking for.

o

Rearrange the list by entering one of the following synonyms on the
command line:

SINDEX

Sorts the list by index (greatest to least) within a library.

Chapter 8. Developing

as Programs under' CMS 177

r

.......... _.._.. ___.____.....__~_ ....__. . __.__._._._ ._.. __.. __ ._________ . _.__ ._._._....... _.._._ ..... _......._. __ ..1

SLIB

Sorts the list alphabetically by library fileid.

SNAME

Sorts the list alphabetically by member name. This is how
the list is initially arranged.

SSIZE

Sorts the list by member size (number of records, greatest
to least).

Entering Commands in the MACLIST Environment: You can type
commands that operate on member names in the list directly on the lines of
the MACLIST display. When you press the ENTER key, all commands
typed on the lines in the file displayed on the current screen are executed.
Symbols can be used to represent operands in the command to be executed.
Symbols are needed if the command to be executed has operands or options
that follow the fileid. For example to issue the PRINT command for this
member of your MACLIST:
NEUTRAL

266

5

MYLIB

MACLIB

Al

type directly on the line that contains this member as follows:
print /EUTRAL

266

5

MYLIB

MACLIB

Al

and then press the ENTER key. Refer to the MACLIST command in the
VM/ SP CMS Command Reference for more information about using
symbols in MACLIST.
Another way to issue commands that make use of member names displayed
is to move the current line to the first (or only) member you want the
command to use. Then issue an EXECUTE command (in the form
"EXECUTE lines command") from the XEDIT command line. This method
may be used on both display and typewriter terminals. You can also enter
commands from the MACLIST command line.

Editing a Maclib Member: The MACLIST command allows you to select
and edit a CMS maclib member from the list. To edit a member, position
the cursor on the line that contains the member to be edited and press the
PFl1 key. Otherwise, you can edit a CMS maclib member by using the
XEDIT command with the MEMBER option. For example, to edit the
SWERVE member of MYLIB maclib, enter:
xedit mylib mac lib al (member swerve

If the SWERVE member did not exist in MYLIB MACLIB, a new file is
created with a fileid of SWERVE MEMBER AI.

178

VM/SP eMS for System Programming

~JG~G~O~JUuuO

oS

lJ[jJOUGJcJOI~G

__

.

=-':=-=:":":'=":"::_-=--=':"::"-=:=-:_==-'-~:~-='-'-~.:~~~'-~_:~:': ==~==~~ =~_~~ ===--::~.-:=-~~~~=--=--=========-~~-==-=:==-~=~.=-~= =-=::.==~~~_~~...:..:..~_-.:~_=J

Adding and Replacing Maclib Members: When the MEMBER option is
specified for the XEDIT command for a member that does not exist in the
library, a new file is created with the fileid of "membername MEMBER fm."
If the MEMBER option is specified on the XEDIT command for an existing
member of a library, the member is read into a file called "membername
MEMBER fm" for you to edit.

When you issue FILE or SAVE for the new or changed member, the library
directory is updated. The new or changed member and the updated library
directory are added to the end of the library. If the directory already
contains a member with the same name as the one being saved, the old
entry is blanked out, so that the updated member replaces the old version.

Deleting Maclib Members: Use the DISCARD command to delete a member
from a library. DISCARD is equivalent to the CMS command MACLIB
DEL. DISCARD can either be typed in the command area of the line that
describes the member you want discarded, or it can be entered from the
command line (at the bottom of the screen). DISCARD can only be used
while in the FILELIST, RDRLIST, MACLIST, and PEEK command
environments.
Setting MACLIST Defaults: When XEDIT is invoked by the MACLIST
command to display the list, the default XEDIT macro, PROFMLST XEDIT,
is executed. If you want to invoke a different XEDIT macro, you can
specify the PROFILE option with the MACLIST command. For example, to
invoke MACLIST with the MYMCLST XEDIT macro, enter
maclist mylib (profile mymclst

You can do the same with the COMPACT and NOCOMP ACT options of the
MACLIST command.
If you are using an alternate profile most of the time, you may change the
default profile with the DEFAULTS command. For example:
defaults set maclist profile mymclst

Entering the DEFAULTS command with no options provides you with the
status of defaults currently in effect. For example, entering
defaults

after changing the XEDIT macro, returns the following information:

Chapter 8. Developing OS Programs under CMS

179

L _______. _. _._. __ ._______._.__________________.__________ ._. ______. __________. ___ .. _. __.______ . . ___._.____.___.J

The following default options have been set:
Filelist options = PROFILE PROFFLST NOFILELIST
Help options = SCREEN BRIEF ALL
Maclist options = PROFILE MYMCLST NOCOMPACT
Note options = PROFILE PROFNOTE SHORT LOG NOACK NOTEBOOK ALL
Peek options = PROFILE PROFPEEK FROM 1 FOR 200
Rdrlist options = PROFILE PROFRLST
Receive options = LOG OLDDATE NOTEBOOK ALL
Sendfile options = NEW TYPE NOFILELIST LOG NOACK
Tell options = MSGCMD MSG
To change any default options enter DEFAULTS Set Cmdname Optl 

The GLOBAL Command

When you want to assemble or compile a source program that uses macro
or copy definitions, you must ensure that the library containing the code is
identified before you invoke the assembler. Otherwise, the library is not
searched. Yo'u identify libraries to be searched using the GLOBAL
command. For example, if you have two MACLIBs that contain your
private macros and copy files whose names are TESTMAC MACLIB and
TESTCOPY MACLIB, you would issue the command:
global maclib testmac testcopy

The libraries you specify on a GLOBAL command line are searched in the
order you specify them. A GLOBAL command remains in effect for the
remainder of your terminal session, until you issue another GLOBAL
MACLIB command or IPL CMS again. To find out what macro libraries
are currently available for searching, issue the command:'
query mac lib

You can reset the libraries or the search order by reissuing the GLOBAL
command.
System MACLIBs

The macro libraries that are on the system disk contain CMS and OS
assembler language macros you may want to use in your programs. The
MACLIBs are:
o

CMSLIB MACLIB contains the CMS macros from VM/370.

o

DMSSP MACLIB contains the macros that are new or changed in
VM/SP.
Note: When assembling programs that use CMS macros, both of these
libraries should be identified via the GLOBAL command. DMSSP
should precede CMSLIB in the search order.

o

180

OSMACRO MACLIB contains the OS macros that CMS supports or
simulates or those that require no CMS support.

VM/SP eMS for System Programming

o

OSMACROI MACLIB contains the macros CMS does not support or
simulate. (You can assemble programs in CMS that contain these
macros, but you must execute them in an OS virtual machine.)

o

OSVSAM MACLIB contains the subset of supported OS/VSAM macros.

o

TSOMAC MACLIB contains TSO macros.

o

DOSMACRO MACLIB contains macros used internally in CMS/DOS.

Note: The DOSMACRO MACLIB contains macros used internally by
CMS/DOS system routines. These macros should not be used in user
written programs.
To obtain a list of macros in any of these libraries, use either the MACLIST
command or the MACLIB command with the MAP function. In the
MACLIST environment, you can issue CMS commands against the members
directly from the displayed list. You can find more information about the
MACLIST command in the VM/ SP CMS Command Reference.

TEXT Libraries (TXTLIBs)
You may want to keep your TEXT files in text libraries. These files have a
filetype of TXTLIB. You can create a TXT LIB from files with a filetype of
TEXT. Like MACLIBs, TXTLIBs have a directory and members.
The TXTLIB Command

TXTLIBs are created and modified by the TXTLIB command, which has
functions similar to the MACLIB command:
o
o
o
o

Create the TXTLIB (GEN function).
Add members to the TXTLIB (ADD function).
Delete members of the TXTLIB and compress the TXTLIB (DEL
function).
List the members of the TXTLIB (MAP function).

There is no REP function. You must use a DEL followed by an ADD to
replace an existing member.

Creating a TXTLIB: The TXTLIB command with the FILENAME option
specified reads the object files as it writes them into the library and creates
a directory entry for each filename. If you have a TEXT file named
MYPROG, which has an entry point named BEGIN, create the TXT LIB
named TESTLIB as follows:
txtlib gen testlib myprog (filename

TESTLIB contains a member name MYPROG with an entry point BEGIN.
Specify the member name MYPROG to reference this TXT LIB member. If
you do not specify the FILENAME option, TESTLIB will contain no entry

Chapter 8. Developing

as Programs under CMS 181

L__ ......... ___.~_, ................ '_H'" O. ___ ..

. _.H_ . _...... _... _· . ~ __.___._____._ _ _ _ _ _ ~ __ .~_ ....~_ . ____ .~:._:.:. __~-=-I·: . . ____ . . . ~~ __ ~_. ____ ~._ ....... _..... ~. _....._. . ~_ .. ___ ._____. .____ . _.H._J

for the name MYPROG. You will have to specify the member name BEGIN
to reference this TXTLIB member.

Loading and Executing TXTLIBs: When you want to load members of
TXTLIBs into storage to execute them Gust as you execute TEXT files), you
must issue the GLOBAL command to identify the TXTLIB:
global txtlib testlib
load begin (start

When you specify more than one TXTLIB on the GLOBAL command line,
the order of search is established for the TXTLIBs. However, if the AUTO
option of the LOAD and INCLUDE commands is in effect (it is the default),
CMS searches for TEXT files before searching active TXTLIBs.
When the TXTLIB command processes a TEXT file, it writes an LDT
(loader terminate) card at the end of the TEXT file so that when a load
request is issued for a TXTLIB member loading terminates at the end of the
member. If" you add OS linkage editor control statements to the TEXT file
(using the CMS editor) before you issue the TXTLIB command to add the
file to a TXTLIB, the control statements are processed as follows:

NAME Statement: A NAME statement causes the TXTLIB command to
create the directory entry for the member using the specified name.
Thereafter, when you want to load that member into storage or delete it
from the TXTLIB you must refer to it by the name specified on the NAME
statement.
Note: The FILename option overrides any name card found in a text file.
The name card functions as before, but the specified file name becomes the
membername in the TXTLIB. The name card is the only entry within that
membername of the TXTLIB.
The loader does not use name cards to resolve entry points. It is important
that the name on the name card be the same as the name on the CSECT or
entry card. This will ensure that the loader will find the correct text deck
and loader tables (any external references) will be resolved with the entry
point. If the names differ, the loader will load the text deck based on the
name card (or file name). However, the loader tables will be set up
according to entry or CSECT cards encountered during the load. Any
external reference using the name from the name card will be resolved as
zeros.

ENTRY Statement: If you use an ENTRY statement, the entry point you
specify is validated and checked for a duplicate. If the entry point name is
valid and there are no duplicates in the TEXT file, the entry name is
written in the LDT card. Otherwise, an error message is issued. When this
member is loaded, execution begins at the entry point specified.

182

VM/SP eMS for System Programming

0 1r"1

[1'11"-")117("') n,'\ [~J nr'l (,', ((~;\ (~ ['J r',l '-.~ ,,'1 r
r "',) '"-'
1:._) ~ U ~
J C. ,j :1 u~..J

b . . _}

L•.J '-'::'" 'J ...:... U1(.':; ~ . ~ Uu

L_. __._"_. __~_~~_. __ .:....__._.. _._ ...._.... ~"':"__ ~ ____ ~'..~ .~.~._._. _____ ...:.._. ___ ~~ __

._~._..

__ .~...:....:.~~~~~ =~.:~:.: .....:~~. ~:..:.:.:~:.:~._. __ ~ ____.. '_ ~:::. ~:.:~~:~:.~-]

ALIAS Name: An entry is created in the directory for the ALIAS name
you specify. A maximum of 16 alias names can be used in a single text
deck. You may load the single member and execute it by referring to the
alias name, but you cannot use the alias name as the object of V-type
address constant (VCON) because the address of the member cannot be
resolved.
SETSSI Card: TXTLIB command information you specify on the SETSSI
card is written in bytes 26 through 33 of the LDT card.
All other OS linkage editor control statements and commands are ignored
by the TXTLIB command and written into the TXT LIB member. When you
attempt to load the member, the CMS loader flags these cards as invalid.
These cards may be added as history information to a module if you specify
the HIST option on the LOAD or INCLUDE commands and then issue a
subsequent GENMOD command.
Manipulating TXTLIB Members

The following CMS commands recognize TXTLIBs and have a MEMBER
option:
o
o
o

PUNCH
PRINT
TYPE

Use the CMS PUNCH command with the MEMBER option to punch a
single member or all members of a TXTLIB. Use the CMS PRINT command
with the MEMBER option to print a single member or all members of a
TXTLIB. Use the CMS TYPE command with the MEMBER option to
display on the terminal a single member or all members of a TXTLIB.

OS Module Libraries and eMS LOADLIBS
The OS relocating loader allows the user to load a member of a CMS
LOAD LIB or an OS module library on an OS formatted disk. The OS
LINK, LOAD, ATTACH, and XCTL macros are supported. In addition, the
OSRUN command (which generates a LINK SVC) loads and executes
members directly from the console.
For the LINK, LOAD, ATTACH, and XCTL macros, the libraries specified
in the LOADLIB global list are searched. If the requested member is not
found, CMS looks for a TEXT file by that name. Then, if still not found,
the TXTLIBs specified in the TXTLIB global list are searched for the
member name.
For the OSRUN command, the libraries specified in the LOADLIB global
list are searched. If the member is not found and the user has a $SYSLIB
LOADLIB file, it is searched for the member name. (TEXT files and
TXTLIBs are not considered by OSRUN.)

Chapter 8. Developing OS Programs under CMS

lS3"

l-'~-------------~-

Executing OS Module Libraries

If the module to be executed resides in an OS module library on an OS
formatted disk, the disk must be accessed and the library must be defined
(via the FILEDEF command) to make it known to CMS.
For example, access the OS disk as a B-disk at the address 250:
ACCESS 250 B

Suppose SYSl.TESTLIB is an OS module library on the OS disk and
contains the member TESTl. Use the FILEDEF command to relate
SYSl. TESTLIB to the CMS LOADLIB called OSLIB LOADIB:
FILEDEF $SYSLIB DISK OSLIB LOADLIB B DSN SYSl TESTLIB
(DSORG PO RECFM U BLOCK 7294

Now you can refer to the OS module library, SYS1.TESTLIB, by using the
CMS file identifier OSLIB LOADLIB.
Before you try to execute TESTl, use the GLOBAL command to identify the
CMS LOADLIBs to be searched. For example,
GLOBAL LOADLIB OSLIB

Then, the OSRUN command searches OSLIB LOADLIB for the member,
TESTl, to load and execute. For example,
OSRUN TESTl

The DDNAME specified on the FILEDEF command must be $SYSLIB. The
filename (OSLIB), specified on the FILEDEF command, can be any name,
but it must correspond to the name stated in the GLOBAL command. The
filetype must be LOADLIB.
Creating and Executing CMS LOADLIBs

If the program to be executed resides on a CMS disk, use the LKED
command. The LKED command creates a CMS LOAD LIB from a CMS
TEXT file. For example:
LKED TESTFILE

takes the CMS TEXT file, TESTFILE TEXT, and creates the CMS
LOADLIB, TESTFILE LOADLIB. For more information on input to the
LKED command refer to "The LKED Command" on page 186. The CMS
LOADLIB created by the LKED command is an OS simulated partitioned
data set (PDS) namedTESTFILE LOADLIB and contains one member
named TESTFILE.
Before executing TESTFILE, use the GLOBAL command to identify the
LOADLIB to be searched:
GLOBAL LOADLIB TESTFILE

184

VMjSP eMS for System Programming

. ______ .___ .:. :____. _. _. :. . . :_ . _ _ ._. _.. : . . _ .. _. _..... ....._. _ .__ . _. ._. _ ... .:. :. _.:. ___ . __. _._____

[~_=-===-~~ _...:_~

_~.

.~_~_

~.:

~_:.::.._

..._. . .. :_._ _.___
~_

.~~...:~_~

__J

Then the OSRUN command loads, relocates, and executes the TESTFILE
member of TESTFILE LOADLIB:
OS RUN TESTFILE
Maintaining CMS LOADLIBs

The LOADLIB command provides the utility necessary to maintain the
CMS LOADLIBs. The following functions are provided:
COpy

Copy members from one LOAD LIB to another
Merge complete.LOADLIBs
Copy with SELECT or EXCLUDE

COMPRESS

Compress a CMS LOADLIB

LIST

LIST members of a CMS LOADLIB

For more detailed information on the LKED, GLOBAL, OSRUN, and
LOADLIB commands, refer to the VM/ SP CMS Command Reference.
Concatenating Files

To define more than one library with the same DDNAME, use the CONCAT
option of the FILEDEF command. You can concatenate the LOADLIB files
on OS disks with each other and/or with CMS LOADLIB files. Any library
to be searched must be specified in the GLOBAL LOADLIB statement. The
data set with the largest block size should be specified first (both in the
FILEDEF and in the GLOBAL list). CMS files do not require a file
definition. But, if used, the file with the largest block size should be
specified first. The GLOBAL list determines the order in which the
libraries are searched.
For example, search two OS files and a CMS LOADLIB for the member,
THETA, using the following commands:
ACCESS 250 B (if 250
FILEDEF $SYSLIB DISK
(DSORG PO RECFM
FILEDEF $SYSLIB DISK
GLOBAL LOADLIB OSLIB
OSRUN THETA

is the address of the OS disk)
OSLIB LOADLIB DSN SYSl LIBl
U BLOCK 7294)
MYLIB LOADLIB B DSN SYSl LIB2 (CONCAT)
MYLIB CMSLIB

Note: The first FILEDEF command for $SYSLIB must describe the first
library filename in the GLOBAL list. Its attribute will be used when the
libraries are searched. It is advisable not to code the CONCAT option on
the first FILEDEF command so that it clears all previous FILEDEFs for
that ddname.

Chapter 8. Developing OS Programs under CMS

185

~)0)t'7G~O[))Uuu[~

08

[?[j~eC:Ju'OuuuD

c=:::=--=..-___

_________.______________ ::::..-==:::J

The LKED Command
The LKED command uses the OS Linkage Editor for the actual link of the
TEXT file to the LOADLIB as an executable module. In order to link edit
CMS files, you can issue the FILEDEF command to identify input to the OS
Linkage Editor. Primary LKED input is a data set known to the linkage
editor as SYSLIN, which can be described in the FNAME operand of the
LKED command. The filetype of the input file named in the command line
must be TEXT. Optionally, you can override the FNAME operand by
issuing a FILEDEF that defines SYSLIN as the ddname of an alternate
primary input source. If your alternate input is a CMS file, the choice of
filetype is unrestricted. The contents of the SYSLIN dataset may be:
1.
2.
3.

Object text such as assembler or compiler output
Linkage editor control statements
A combination of object text and control statements.

Linkage editor control statements can be inserted before, between, and after
object modules and other control statements. Editing procedures can be
used to construct files to meet your requirements. Linkage editor
INCLUDE statements may be used to designate explicitly the following files
or file members as secondary linkage editor input:
1.
2.
3.
4.
5.

CMS TEXT files
Members of CMS TXTLIB files
Members of CMS LOADLIB files
Members of OS object libraries
Members of OS load libraries.

A FILEDEF must be issued before the LKED command to define a unique
ddname for each file to be included as secondary linkage editor input. An
INCLUDE statement in the SYSLIN dataset must specify the ddname
assigned to the file by your FILEDEF. For library files, the statement must
also specify all members of the library that are to be included as input. The
use of all FILEDEF commands and INCLUDE statements to identify input
files is shown in the following examples.
CMS commands:
FILEDEF LIBDEF DISK MYLIB TXTLIB B
FILEDEF TXTDEF DISK MYFILE TEXT C

SYSLIN input:
INCLUDE LIBDEF(CSECT1,CSECT2)
INCLUDE TXTDEF

INCLUDE statements must begin in column 2. The applicable statement
formats are described in the 08/ VB Linkage Editor and Loader.
When SYSLIN input to the LKED command is an assembled object file in
fixed-block format residing on an OS disk, the RECFM FBS option of the
FILEDEF command must be specified. The following example shows

186

VM/SP eMS for System Programming

~j(Y\JG~(O~)UU·l1~j
c= . .-.-.--..-.. -----... -- . . ----.-.--... -... --..---.-.-..------------..-.----.--.-.. -.. -_.. _
..._
..-._.--_. --_-.. .._...

U

- ••• - .

-.--..-.

'.-.:...

nuo

•••• -

.• - - - . - . - . - - . -

«JS

~JuJ()tJu'(Ju {MJ

. - - • • • • • • . - - - . - - . -•• - - • .- - - . - - - - - - .• -

• . . • • - •. -

.~.-

. - •.•• - . - )

FILEDEF commands and SYSLIN input to identify a member of an OS
object library and a CMS TXTLIB.
CMS commands:
FILEDEF OSOBJ DISK OBJECT FILE Q DSN SYS1 FEOBJ (RECFM FBS
LRECL 80 BLOCK 3120
FILEDEF TXTDEF DISK NEWLIB TXTLIB B

SYSLIN input:
INCLUDE OSOBJ(MEMBER1)
INCLUDE TXTDEF(CSECT1)

Automatic library search is available for either CMS or OS type library
members if the FILEDEF for the dataset to be searched specifies SYSLIB as
the ddname. Additional libraries can be selected for automatic search by
placing linkage editor LIBRARY statements in your SYSLIN input file.
Each library statement must contain the associated ddname and a list of
members within the library to be included in the search. A FILEDEF must
be issued before the LKED command to assign a unique ddname to each
dataset to be searched. The library search conducted during a single
linkage editor execution is limited to either object-type or load-type
modules and may not combine both types. The CONCAT option of the
FILEDEF command is not valid for LKED input datasets. To expand the
use of the automatic SYSLIB search, the user may combine the members of
several CMS libraries into a single composite library. The automatic
search facility applies to CMS TXTLIBs and LOADLIBs and to OS object
libraries and LOAD libraries. The following example shows FILEDEF
commands and SYSLIN input for an automatic library search.
CMS commands:
FILEDEF SYSLIB DISK SEARCH1 TXTLIB B
FILEDEF LIBDEFA DISK SEARCH2 TXTLIB C
FILEDEF LIBDEFB DISK OSTEXT LIBRARY D DSN OBJMODS

SYSLIN input:
LIBRARY LIBDEFA(CSECT1,CSECT2)
LIBRARY LIBDEFB(MEMBER1,MEMBER2)

LIBRARY statements must begin in column 2. The GLOBAL command is
not needed to identify linkage editor input libraries. For LOADLIB input
to the linkage editor, the RECFM U option of the FILEDEF command must
be specified.
The default FILEDEF commands issued by the LKED command for the
ddnames presented to the Linkage Editor are as follows:

Chapter 8. Developing

as Programs under CMS 187

[DQvG~CV[vO~u0J O~~ L")U'80u~ClG1uS

...._.__ ......

c::~~:~~==-._==-~:=:=======--:-:-:~

FILEDEF
FILEDEF
-orFILEDEF
FILEDEF
FILEDEF
-orFILEDEF
-orFILEDEF

.. _... _._ . _______.____...._. _____._._. ___.______ .___ .._. __.___._____ ._._. __ ._ ._.________ ._ .. _.::-.:J

SYSLIN DISK FNAME TEXT * (RECFM F BLOCK 80 NOCHANGE
SYSLMOD DISK fname LOADLIB Al (RECFM U BLOCK 260 NOCHANGE
SYSLMOD DISK libname LOADLIB Al (RECFM U BLOCK 260 NOCHANGE
SYSUTI DISK fname SYSUTI *
SYSPRINT DISK fname LKEDIT Al
SYSPRINT PRINTER
SYSPRINT DUMMY

At the completion of the LKED command, all FILEDEFs that do not have
the PERM option are erased.

OS Data Management Simulation
The disk format and data base organization of eMS are different from those
of OS. A eMS file produced by an OS program running under eMS and
written on a eMS disk has a different format from that of an OS data set
produced by the same OS program running under OS and written on an OS
disk. The data is exactly the same, but its format is different. (An OS disk
is one that has been formatted by an OS program, such as the Device
Support Facility.) eMS does not support multi-buffering for unit record
devices. There is one DeB per device, not per file.

Handling Files that Reside on eMS Disks
eMS can read, write, or update any OS data that resides on a eMS disk.
By simulating OS macros, eMS simulates the following access methods so
that OS data organized by these access methods can reside on eMS disks:
o BDAM

(direct) -- identifying a record by a key or by its relative
position within the data set.

o BPAM

(partitioned) -- seeking a named member within data set.

Note:

Two BPAM files with the same filetype cannot be
updated at the same time.

o BSAM/QSAM (sequential) -- accessing a record in a sequence in relation
to preceding or following records.
o VSAM

(direct or sequential) -- accessing a record sequentially or
directly by key or address.

Note: eMS support of OS VSAM files is based on
VSE/VSAM. Therefore, the OS user is restricted to those
functions available under VSE/VSAM. See the section
"eMS Support for OS and VSE/VSAM Functions" for
details.

188 VM/SP eMS for System Programming

[jJGt7G~GJ~)DuutJ

_ __--_------:- ------------ ---:_

l ___ ~,~ _____.__________.___ _

OS lJu'IDU[j'cJu u-~G

~===-=~~~=~~~

___

~=_~~~~~:::":~~~_~_~_:::':::J

Refer to Figure 22 on page 189 and "OS Macros" on page 191, then read
"Access Method Support" on page 199 to see how CMS handles these access
methods.
Since CMS does not simulate the indexed sequential access method (ISAM),
no OS program using ISAM can execute under CMS. Therefore, no
program can write an indexed sequential data set on a CMS disk.

Handling Files that Reside on OS Disks
By simulating OS macros, CMS can read, but not write or update~ OS
sequential and partitioned data sets that reside on OS disks. However, an
OS sequential or partitioned data set that resides on an OS disk can be
written or updated only by an OS program running in an OS system.
CMS can execute programs that read and write VSAM files from OS
programs written in the VS BASIC, COBOL, PL/I, VS/APL, and VS
FORTRAN programming languages. eMS also supports VSAM for use with
DOS/VS SORT/MERGE. This CMS support is based on the VSE/VSAM
Program Product and, therefore, the OS user is limited to those VSAM
functions that are available under VSE/VSAM.

Simulating OS Supervisor Calls
IH~Cl'O

SVC

N'anlC

NUl11.ber

Function

XDAP
EXCP

00
00

WAIT
POST
EXIT/RETURN
GETMAIN
FREEMAIN
GETPOOL
FREEPOOL
LINK
XCTL
LOAD
DELETE
GETMAIN/FREEMAIN
TIME

01
02
03
04
05

Reads or writes direct access volumes
Executes graphic channel programs for graphic access
method (GAM)
Waits for an I/O completion
Posts the I/O completion
Returns from a called phase
Conditionally acquires user storage
Releases user-acquired storage
Simulates as SVC 10
Simulates as SVC 10
Links control to another phase
Deletes, then links control to another load phase
Reads a phase into storage
Deletes a loaded phase
Manipulates user free storage
Gets the time of day

Figure 22 (Part 1 of 3).

06
07
08
09
10
11

Simulated OS Supervisor Calls

Chapter 8. Developing

as Programs under CMS 189

[Q)G~C~~(Q)~])U~ll[j

08

fV~1(Q)fDu1@uuuG

[ •. _._. __....._. __ ...____ ._. __. _____ ._. _____ .______. _ _ _ _ _ _ _ _ _._._1.._ _ __

Macro
Name
ABEND
SPIE

SVC

RESTORE
BLDL
FIND
OPEN
CLOSE
STOW
OPENJ
TCLOSE
DEVTYPE
TRKBAL
FEOV
WTO/WTOR
EXTRACT
IDENTIFY
ATTACH
CHAP
TTIMER
STIMER
DEQ
SNAP
ENQ
FREEDBUF
STAE

17
18
18
19
20
21
22
23
24
25
31
35
40
41
42
44
46
47
48
51
56
57
60

DETACH
CHKPT
RDJFCB
SYNAD
SYNADAF
SYNADRLS
BSP
TGET/TPUT
TCLEARQ

62
63
64

Number
13
14

68
68
69
93
94

Function
Terminates processing
Allows processing program to handle program
interrupts
Effective NOP
Builds a directory for a partitioned data set
Locates a member of a partitioned data set
Activates a data file
Deactivates a data file
Manipulates partitioned directories
Activates a data file
Temporarily deactivates a data file
Gets device-type physical characteristics
Effective NOP
Sets forced EOV error code
Communicates with the terminal
Effective NOP
Adds entry to loader table
Effective LINK
Effective NOP
Accesses or cancels timer
Sets timer interval and timer exit routine
Effective NOP
Dumps specified areas of storage
Effective NOP
Releases a free storage buffer
Allows processing program to decipher abend
conditions
Effective NOP
Effective NOP
Obtains information from FILEDEF command
Handles data set error conditions
Provides SYNAD analysis function
Releases SYNADAF message and save areas
Backs up a record on a tape or disk
Reads or writes a terminal line
Clears terminal input queue

Figure 22 (Part 2 of 3). Simulated OS Supervisor Calls

190

VM/SP eMS for System Programming

-_. . __ ._--_. _---------_ .... _--_.. _._._-_.__._-----J

'_---__ ~~~_-_- ~ ____ . .:. . . . __ --.:.~_=______________________:. . . ___________________ _

C=~:,:,~=_,_'

1I.t1ncro
I'Tame
STAX

SVC

PGRLSE
CALL

112

SAVE
RETURN

-

GET/PUT
READ
WRITE
NOTE/POINT
CHECK
DCB
DCBD
Figure 22 (Part 3 of 3).

NUlllbel'

96

-

-

-

Function
Updates a queue of CMTAXEs that creates an
attention exit block
Releases storage contents
Transfers control to a control section at a specified
entry
Saves program registers
Returns from a subroutine
Reads/Writes system-blocked data (QSAM)
Accesses system-record data
Write system-record data
Manages data set positioning
Verifies READ/WRITE completion
Constructs a data control block
Generates a DSECT for a data control block

Simulated OS Supervisor Calls

as Macros
Because CMS has its own file system and is a single-user system operating
in a virtual machine with virtual storage, there are certain restrictions for
the simulated as function in CMS. For example, HIARCHY options and
options that are used only by as multitasking systems are ignored by CMS.
Due to the design of the CMS loader, an XCTL from the explicitly loaded
phase, followed by a LINK by succeeding phases, may cause unpredictable
results.
Listed below are descriptions of all the as macro functions that are
simulated by CMS as seen by the programmer. Implementation and
program results that differ from those given in as Data Management Macro
Instructions and as Supervisor Services and Macro Instructions are stated.
HIARCHY options and those used only by as multitasking systems are
ignored by CMS. Validity checking is not performed within the simulation
routines. The entry point name in LINK, XCTL, and LOAD (SVC 6,7,8)
must be a member name or alias in a LOADLIB directory or in a TXTLIB
directory unless the COMPSWT is set to on. If the COMPSWT is on, SVC
6,7, and 8 must specify a module name. This switch is turned on and off by
using the COMPSWT macro. See the VM/SP eMS Macros and Functions
Reference for descriptions of all CMS user macros.
XDAP-SVC 0

The TYPE option must be R or W; the V, I, and K options
are not supported. The BLKREF-ADDR must point to an
item number acquired by a NOTE macro. Other options
associated with V, I, or K are not supported.

Chapter 8. Developing

as Programs under CMS 191

L . __ ..-___..._. . .______ ._. __.___. __._______ . _.__. . __...__ .____. ____._ _ _ _ _ _ _ _ .._____ . __._._." .... _......... __. __ ............ _....._.... _._ ........ _ ...___ ..._..... ___.._._.

.0._.••• _ . _ ]

EXCP-SVC 0

The EXCP macro is supported by CMS. The EXCP macro
executes graphic channel programs for graphic access
method (GAM).

WAIT-SVC 1

All options of WAIT are supported. The WAIT routine
waits for the completion bit to be set in the specified ECBs.

POST-SVC 2

All options of POST are supported. POST sets a completion
code and a completion bit in the specified ECB.

EXIT/RETURN-SVC 3
Depending upon whether this is an exit or return from a
linked or an attached routine, SVC 3 processing does the
following: posts ECB, executes end of task routines,
releases phase storage, unchains and frees latest request
block, and restores registers. Do not use EXIT/RETURN to
exit from an explicitly LOADed phase. If EXIT/RETURN is
used for this purpose, CMS issues abend code AOA.
GETMAIN-SVC 4
All options of GETMAIN are supported except SP,
BNDRY=, HIARCHY, LC, and LU. SP, BNDRY=, and
HIARCHY are ignored by CMS. LC and LU result in
abnormal termination if used. GETMAIN gets blocks of
free storage.
FREEMAIN-SVC 5
All options of FREEMAIN are supported except SP and L.
SP is ignored by CMS, and L results in abnormal
termination if used. FREEMAIN frees blocks of storage
acquired by GETMAIN.
GETPOOL/FREEPOOL
All the options of GETPOOL and FREEPOOL are
supported. GETPOOL constructs a buffer pool and stores
the address of a buffer pool control block in the DCB.
FREEPOOL frees a buffer pool constructed by GETPOOL.

192

LINK-SVC 6

The DCB and HIARCHY options are ignored by CMS. All
other options of LINK are supported. LINK loads the
specified program into storage (if necessary) and passes
control to the specified entry point.

XCTL-SVC 7

The DCB and HIARCHY options are ignored by CMS. All
other options of XCTL are supported. XCTL loads the
specified program into storage (if necessary) and passes
control to the specified entry point.

LOAD-SVC 8

The DCB and HIARCHY options are ignored by CMS. All
other options of LOAD are supported. LOAD loads the
specified program into storage (if necessary) and returns
the address of the specified entry point in register O. If

VM/SP eMS for System Programming

loading a subroutine is required when SVC 8 is issued, CMS
searches directories for a TXTLIB member containing the
entry point or for a TEXT file with a matching filename.
An entry name in an unloaded TEXT file will not be found
unless the filename matches the entry name. After the
subroutine is loaded, CMS tries to resolve external
references within the subroutine, and may return another
entry point address. To insure a correct address in register
0, the user should bring such subroutines into storage
either by the CMS LOAD/INCLUDE commands or by a
VCON in the user program.
DELETE-SVC 9
All the options of DELETE are supported. DELETE
decreases the use count by one and, if the result is zero,
frees the corresponding virtual storage. Code 4 is returned
in register 15 if the phase is not found.
GETMAIN/FREEMAIN-SVC 10
All the options of GETMAIN and FREEMAIN are
supported except SP and HIARCHY, which are ignored by
CMS.
TIME-SVC 11

CMS supports only the DEC, BIN, TU, and MIC parameters
of the TIME macro instruction. TIME returns the time of
day to the calling program. However, the time value that
CMS returns is only accurate to the nearest second and is
converted to the proper unit.

ABEND-SVC 13
The completion code parameter is supported. The DUMP
parameter is not. If a STAE request is outstanding, control
is given to the proper STAE routine. If a STAE routine is
not outstanding, a message indicating that an abend has
occurred is printed on the terminal along with the
completion code.
SPIE-SVC 14

All the options of SPIE are supported. The SPIE routine
specifies interruption exit routines and program
interruption types that cause the exit routine to receive
control.

RESTORE-SVC 17
The RESTORE routine in CMS is a NOP. It returns
control to the user.
BLDL-SVC 18 BLDL is an effective NOP for LINKLIBs and JOBLIBs. For
TXTLIBs and MACLIBs, item numbers are filled in the TTR
field of the BLDL list. The K, Z, and user data fields, as
described in DS/VS Data Management Macro Instructions,
are set to zeroes. The "alias" bit of the C field is supported,
and the remaining bits in the C field are set to zero.

Chapter 8. Developing OS Programs under CMS

193

FIND-SVC 18

All the options of FIND are supported. FIND sets the
read/write pointer to the item number of the specified
member.

STOW-SVC 21 All the options of STOW are supported. The "alias" bit is
supported, but the user data field is not stored in the
MACLIB directory since CMS MACLIBs do not contain
user data fields.
When using the STOW macro's ADD directory function
without closing and reopening the data set after each new
member is added, the CLOSE macro must be issued within
each multiple of 256 new members. The existing number of
entries does not need to be known before the ADD function
is started.
OPEN/OPENJ-SVC 19/22
All the options of OPEN and OPENJ are supported except
for the DISP, EXTEND, and RDBACK options, which are
ignored. OPEN creates a CMSCB (if necessary), completes
the DCB, and merges necessary fields of the DCB and
CMSCB.
CLOSE/TCLOSE(CLOSE TYPE = T)-SVC 20/23
All the options of CLOSE and TCLOSE are supported
except for the DISP option, which is ignored. The DCB is
restored to its condition before OPEN. If the device type is
disk, the file is closed. If the device type is tape, the
REREAD option is treated as a REWIND. For TCLOSE,
the REREAD option is REWIND, followed by a forward
space file for tapes with standard labels.
DEVTYPE-SVC 24
With the exception of the RPS option, which CMS ignores,
CMS accepts all options of the DEVTYPE macro
instruction. In supporting this macro instruction, CMS
groups all devices of a particular type into the same class.
For example, all printers are grouped into the printer class,
all tape drives into the tape drive class, and so forth. In
response to the DEVTYPE macro instruction, CMS
provides the same device characteristics for all devices in a
particular class. Thus, all devices in a particular class
appear to be the same device type.
The device type characteristics CMS returns for each class
are:

194

Class

Device Characteristics

Printer
Virtual reader
Console

1403
2540
1052

VM/SP eMS for System Programming

[G GY\J 0 ~ (u ~~) uu-u ~J
. ____ ___: " __

[_~ _~

~:

~~

__ .__ ___
~~

__

.~.~_~::..,~:-:,====~_,::=_~==:,,:~~~~~~,:,, =-_,:,,~_.

Tape drive
DASD
Virtual punch
DUMMY
unassigned

([) ~~

~J U'QJ U[j"tJ ljU"J rJ

_'"_.~~-___
" '_-=~~-~-=~':'~~-==~.~~-':_'

__ J

2400 (9 track)
2314
2540
2314
2314

TRKBAL-SVC 25
The TRKBAL routine in CMS is a NOP. It returns control
to the user.
FEOV-SVC 31 Control is returned to CMS with an error code of 4 in
register 15.
WTO/WTOR-SVC 35
All options of WTO and WTOR are supported except those
options concerned with multiple console support. WTO
displays a message at the operator's console. WTOR
displays a message at the operator's console, waits for a
reply, moves the reply to the specified area, sets a
completion bit in the specified ECB, and returns. There is
no check made to determine if the operator provides a reply
that is too long. The reply length parameter of the WTOR
macro instruction specifies the maximum length of the
reply. The WTOR macro instruction reads only this
amount of data.
EXTRACT-SVC 40
The EXTRACT routine in CMS is essentially a NOP. The
user-provided answer area is set to zeroes and control is
returned to the user with a return code of 4 in register 15.
IDENTIFY-SVC 41
The IDENTIFY routine in CMS adds a REQUEST block to
the load request chain for the requested name and address.
ATTACH-SVC 42
All the options of ATTACH are supported in CMS as in OS
PCP. The following options are ignored by CMS: DCB,
LPMOD, DPMOD, HIARCHY, GSPV, GSPL, SHSPV,
SHSPL, SZERO, PURGE, ASYNCH, and TASKLIB.
ATTACH passes control to the routine specified, fills in an
ECB completion bit if an ECB is specified, passes control to
an exit routine if one is specified, and returns control to the
instruction following the ATTACH.
Since CMS is not a multitasking system, a phase requested
by the ATTACH macro must return to CMS.
CHAP-SVC 44 The CHAP routine in eMS is a NOP. It returns control to
the user.

Chapter 8. Developing OS Programs under CMS

195

EJ)Gt'1G~(})~]DUilQl

08

L]~'(i)G~U1@fJuuS

r------TTIMER-SVC 46
All the options of TTIMER are supported.
STIMER-SVC 47
All options of STIMER are supported except for TASK and
WAIT. The TASK option is treated as if the REAL option
had been specified, and the WAIT option is treated as a
Nap; it returns control to the user. The maximum time
interval allowed is X'7FFFFFOO' timer units (or 15 hours, 32
minutes, and 4 seconds in decimal). If the time interval is
greater than the maximum, it is set to the maximum.
If an STIMER is issued and later the virtual machine is put
into a wait state, the virtual timer is not updated unless
prior to this the CP command SET TIMER REAL was
issued or the REALTIMER option was specified in the
VM/SP directory entry of the virtual machine.

Note: If running in the CMSBATCH environment, issuing
the STIMER or TTIMER macro affects the CMSBATCH
time limit. Depending on the frequency, number, and
duration of STIMERs and/or TTIMERs issued, the
CMSBATCH limit may never expire.
DEQ-SVC 48

The DEQ routine in CMS is a Nap. It returns control to
the user.

SNAP-SVC 51 Except for SDATA, PDATA, and DCB, all options of the
SNAP macro are processed normally. SDATA and PDATA
are ignored. Processing for the DCB option is as follows.
The DBC address specified with SNAP is used to verify that
the file associated with the DCB is open. If it is not open,
control is returned to the caller with a return code of 4. If
the file is open, then storage is dumped (unless the FCB
indicates a DUMMY device type). SNAP always dumps
output to the printer. The dump contains the PSW, the
registers, and the storage specified.
ENQ-SVC 56

The ENQ routine in CMS is a Nap. It returns control to
the user.

FREEDBUF-SVC 57
All the options of FREEDBUF are supported. FREEDBUF
returns a buffer to the buffer pool assigned to the specified
DCB.
STAE-SVC 60

196

VM/SP eMS for System Programming

All the options of ST AE are supported except for the XCTL
option, which is set to XCTL=YES; the PURGE option,
which is set to HALT; and the ASYNCH option, which is
set to NO. STAE creates, overlays, or cancels a STAE
control block as requested. STAE retry is not supported.

"

" .; ~J "

]

DETACH-SVC 62
The DETACH routine in CMS is a Nap. It returns control
to the user.
CHKPT-SVC 63
The CHKPT routine is a Nap. It returns control to the
user.
RDJFCB-SVC 64
All the options of RDJFCB are supported. RDJFCB causes
a job file control block (JFCB) to be read from a CMS
control block (CMSCB) into real storage for each data
control block specified. FILEDEF commands create
CMSCBs.
Additional information regarding CMS 'as Simulation' of
RDJFCB follows:
o

The DCBs specified in the RDJFCB PARAMETER LIST
are processed sequentially as they appear in the
parameter list.

o

On return to the caller, a return code of zero is always
placed in register 15. If an abend occurs, control is not
returned to the caller.

o

Abend 240 occurs if zero is specified as the address of
the area into which the JFCB is to be placed.

o

Abend 240 occurs if a JFCB EXIT LIST ENTRY (Entry
type X'07') is not present in the DCB EXIT LIST for any
one of the DCBs specified in the RDJFCB
PARAMETER LIST.

o

If a DCB is encountered in the parameter list with zero

specified as the DCB EXIT LIST ('EXLST') address, the
RDJFCB immediately returns with return code zero in
register 15. Except for this situation, all of the DCBs
specified in the RDJFCB PARAMETER LIST are
processed, unless an abend occurs.
o

For a DCB that is not open, a search is done for the
corresponding FILEDEF or DLBL. If one is not found,
a test is done to determine if a file exists with a
filename of 'FILE', a filetype of the DDNAME from
DCB, and a filemode of 'AI'. If such a file does exist,
then X'40' is placed in the JFCB at displacement X'57'
(FLAG' JFCOLD IN FIELD' JFCBIND2'). If such a file
does not exist then X'CO' (FLAG 'JFCNEW') will be in
field 'JFCBIND2'.

o

For a file that is not open, but for which a DLBL has
been specified, X'OB' is placed in the JFCB at
Chapter 8. Developing

as Programs under CMS. 197

L _._._....____.____•

- - - - - . - ( J ' . - - - -..---.---.. - - - - - - -..------------------.--___ J

displacement X'63' (field 'JFCDSORG' byte 2) to
indicate that it is a VSAM file.
SYNADAF-SVC 68
All the options of SYNADAF are supported. SYNADAF
analyzes an I/O error and creates an error message in a
work buffer.
SYNADRLS-SVC 68
All the options of SYNADRLS are supported. SYNADRLS
frees the work area acquired by SYNAD and deletes the
work area from the save area chain.
BSP-SVC 69

All the options of BSP are supported. BSP decrements the
item pointer by one block.

TGET/TPUT-SVC 93
TGET and TPUT operate as if EDIT and WAIT were coded.
TGET reads a terminal line. TPUT writes a terminal line.
TCLEARQ-SVC 94
TCLEARQ in CMS clears the input terminal queue and
returns control to the user.
STAX-SVC 96

The only option of STAX that is supported is EXIT
ADDRESS. STAX updates a queue of CMTAXEs each of
which defines an attention exit level.

PGRLSE-SVC 112
Release all complete pages (4K bytes) associated with the
area of storage specified.
CALL

The CALL macro is supported by CMS. The CALL macro
transfers control to a control section at a specified entry.

NOTE

All the options of NOTE are supported. NOTE returns the
item number of the last block read or written.

POINT

All the options of POINT are supported. POINT causes the
control program to start processing the next read or write
operation at the specified item number. The TTR field in
the block address is used as an item number.

CHECK

All the options of CHECK are supported. CHECK tests the
I/O operation for errors and exceptional conditions.

DCB

The following fields of a DCB may be specified relative to
the particular access method indicated:

/

198

VM/SP eMS for System Programming

lDG\JG~Of)~uuU 08 ~Ju·OOU·8Ul{~S
----"-"._-"-----.....:~~=-====.:....-==:-----.-]

r- _.. -. ----.- --.. _._--

Operand

BDAM

BPAM

BSAM

QSAM

BFALN
BLKSIZE
BUFCB
BUFL
BUFNO
DDNAME
DSORG
EODAD
EXLST
KEYLEN5
LIMCT
LRECL
MACRF
OPTCD
RECFM
SYNAD
NCP

F,D
n(number)
a(address)
n
n
s(symbol)
DA

F,D
n
a
n
n
s
PO
a
a

F,D
n
a
n
n
s
PS
a
a
n

F,D
n
a
n
n
s
PS
a
a

n
R,W

n
R,W,P

n
G,P,L,M

J

J

F,V,B,S,A,M,U
a
n

F,V,B,U,A,M,S
a

a
n
n
R,W
A,E,F,R
F,V,U
a

F,V,U,
a
n

Access Method Support
An access method governs the manipulation of data. To facilitate the
execution of as code under CMS, the processing program must see data as
as would present it. For instance, when the processors expect an access
method to acquire input source cards sequentially, CMS invokes specially
written routines that simulate the as sequential access method and pass
data to the processors in the format that the as access methods would have
produced. Therefore, data appears in storage as if it had been manipulated
using an as access method. For example, block descriptor words (BDW),
buffer pool management, and variable records are updated in storage as if
an as access method had processed the data. The actual writing to and
reading from the I/O device is handled by CMS file management. Note that
the character string X'61FFFF61' is interpreted by CMS as an end of file
indicator.
The essential work of the volume table of contents (VTOC) and the data set
control block (DSCB) is done in CMS by a master file directory (MFD) and
a file status table (FST). A MFD updates the disk contents, and a FST
describes each data file. All disks are formatted in physical blocks of 512,
800, 1024, 2048, or 4096 bytes.
CMS continues to update the as format, within its own format, on the
auxiliary device for files whose filemode number is 4. That is, the block
and record descriptor words (BDW and RDW) are written along with the
data. If a data set consists of blocked records, the data is written to and
read from the I/O device in physical blocks rather than logical records.
CMS also simulates the specific methods of manipulating data sets.

5

If an input data set is not a BDAM data set, zero is the only value that should
be specified for KEYLEN. This applies to the user exit lines as well as to the
DCB macro instruction.

Chapter 8. Developing OS Programs under CMS

199

,

Ej\Q t7C' ~ Q'lr
XED I T 1 File

\.

....,. 1

""

.J

Figure 24.

Sample MACLIST Screen

Finding Members in Your MACLIST List

If there are many members in the maclib, the list may take up more than
one screen. To find a member in your MACLIST list, you can do any of the
following:

o

o

232

Scroll through the list using the PF keys.
PF7

Scrolls backward one full screen.

PF8

Scrolls forward one full screen.

Rearrange the list using one of the following PF keys:
PF4

Sorts the list by member name. This is how the list is
initially arranged.

PF5

Sorts the list by index (largest first). The most recently
updated members will have a greater number.

PF6

Sorts the list by size (largest to smallest).

•

Use the XEDIT subcommand LOCATE if you know the member name
that you are looking for.

e

Rearrange the list by entering one of the following synonyms on the
command line.

VM/SP eMS for System Programming

_ _ __'

C=~== :_~=_'

[G~J'U(J~C:.")~-)~u-uCJ \'J8L~ lJ[j'I~CJU1[}O~~O
_'~=~=_,~:,:~=~~_~::,:,~:~~",:~~~~~~::,:,

__~,:"-,,,:. . ___ ~=~~,,~:_~:~===.~.=~~=:'::=~:::==-'-:-~,~=~=~:::"::'~=.::J

SINDEX

Sorts the list by index (greatest to least) within a library.

SLIB

Sorts the list alphabetically by library fileid.

SNAME

Sorts the list alphabetically by member name. This is how
the list is initially arranged.

SSIZE

Sorts the list by member size (number of records, greatest
to least).

Entering Commands In the MACLIST Environment

You can type commands that operate on member names in the list directly
on the lines of the MACLIST display. When you press the ENTER key, all
commands typed on the lines in the file displayed on the current screen are
executed. Symbols can be used to represent operands in the command to be
executed. Symbols are needed if the command to be executed has operands
or options that follow the fileid. For example to issue the PRINT command
for this member of your MACLIST:
NEUTRAL

266

5

MYLIB

MACLIB

Al

type directly on the line that contains this member as follows:
print /EUTRAL

266

5

MYLIB

MACLIB

Al

and then press the ENTER key. Refer to the MACLIST command in the
VM/ SP CMS Command Reference for more information about using
symbols in MACLIST.
Another way to issue commands that make use of member names displayed
is to move the current line to the first (or only) member you want the
command to use. Then issue EXECUTE (in the form "EXECUTE lines
command") from the XEDIT command line. This method may be used on
both display and typewriter terminals. You can also enter commands from
the MACLIST command line.

Editing a Maclib Member: The MACLIST command allows you to select
and edit a CMS maclib member from the list. To edit a member, position
the cursor on the line that contains the member to be edited and press the
PFll key. Otherwise, you can edit a CMS maclib member by using the
XEDIT command with the MEMBER option. For example, to edit the
SWERVE member of MYLIB maclib, enter:
xedit mylib maclib al (member swerve

If the SWERVE member did not exist in MYLIB MACLIB, a new file is
created with a fileid of SWERVE MEMBER AI.

Chapter 9. Developing VSE Programs under eMS

233

l

Adding and Replacing Maclib Members: When the MEMBER option is
specified for the XEDIT command for a member that does not exist in the
library, a new file is created with the fileid of "membername MEMBER fm".
If the MEMBER option is specified on the XEDIT command for an existing
member of a library, the member is read into a file called "membername
MEMBER fm" for you to edit.

When you issue FILE or SAVE for the new or changed member, the library
directory is updated. The new or changed member and the updated library
directory are added to the end of the library. If the directory already
contains a member with the same name as the one being saved, the old
entry is blanked out, so that the updated member replaces the old version.

Deleting Maclib Members: Use the DISCAED command to delete a
member from a library. DISCARD is equivalent to the CMS command
MACLIB DEL. DISCARD can either be typed in the command area of the
line that describes the member you want discarded, or it can be entered
from the command line (at the bottom of the screen). DISCARD can only be
used while in the FILELIST, RDRLIST, MACLIST, and PEEK command
environments.
Setting MACLIST Defaults: When XEDIT is invoked by the MACLIST
command to display the list, the default XEDIT macro, PROFMLST XEDIT,
is executed. If you want to invoke a different XEDIT macro, you can
specify the PROFILE option with the MACLIST command. For example, to
invoke MACLIST with the MYMCLST XEDIT macro, enter
rnaclist rnylib (profile rnyrnclst

You can do the same with the COMPACT and NOCOMPACT options of the
MACLIST command.
If you are using an alternate profile most of the time, you may change the
default profile with the DEFAULTS command. For example:

defaults set rnaclist profile rnymclst

Entering the DEFAULTS command with no options provides you with the
status of defaults currently in effect. For example, entering
defaults

after changing the XEDIT macro, returns the following information:

234

VMjSP OMS for System Programming

[GGU8~O~)DuJ[J

VGl:

c . -.-.---- . -.. -...-.-------:-.-----.-.--------.....-_. __.____.____ u_.._..________ .___.__ ...____ ..__ .__ . _____ ·.·_u· ____ ········ __ ·... -... ----.--.-.- ...-

~-)G~O[Ju'c1ulr~G

... - ......... --.- .... --.-..... -.-....... -.. - .... ]

The following default options have been set:
Filelist options = PROFILE PROFFLST NOFILELIST
Help options = SCREEN BRIEF ALL
Maclist options = PROFILE MYMCLST NOCOMPACT
Note options = PROFILE PROFNOTE SHORT LOG NOACK NOTEBOOK ALL
Peek options = PROFILE PROFPEEK FROM 1 FOR 200
Rdrlist options = PROFILE PROFRLST
Receive options = LOG OLDDATE NOTEBOOK ALL
Sendfile options = NEW TYPE NOFILELIST LOG NOACK
Tell options = MSGCMD MSG
To change any default options enter DEFAULTS Set Cmdname Optl 

The GLOBAL Command
When you want to assemble a source program that uses macro or copy
definitions, you must ensure that the library containing the code is
identified before you invoke the assembler. Otherwise, the library is not
searched. You identify libraries to be searched using the GLOBAL
command. For example, if you have two MACLIBs that contain your
private macros and copy files whose names are TESTMAC MACLIB and
TESTCOPY MACLIB, you would issue the command:
global mac lib testmac testcopy

The libraries you specify on a GLOBAL command line are searched in the
order you specify them. A GLOBAL command remains in effect for the
remainder of your terminal session, until you issue another GLOBAL
MACLIB command or until you IPL CMS. To find out what macro libraries
are currently available for searching, issue the command:
query maclib

You can reset the libraries or the search order by reissuing the GLOBAL
command.

System MACLIBs
The macro libraries that are on the system disk contain CMS and OS
assembler language macros you may want to use in your programs. The
MACLIBs are:
o

CMSLIB MACLIB contains the CMS macros from VM/370.

o

DMSSP MACLIB contains macros that are new or changed in VM/SP.

Note: When assembling programs that use CMS macros, both of these
libraries should be identified via the GLOBAL command. DMSSP
should precede CMSLIB in the search order.
o

DOSMACRO MACLIB contains macros used internally by CMS/DOS.

Chapter 9. Developing VSE Programs under CMS

235

c:-______ .___.._. _ _ . . . _.......". _._ ......_"_____ ~==::-:=:-:-~~:=~.-~'.- - . _-_. .-._---------------_. __ . _----_._. -._---_._-.._-----_._--_._._------_._J
Note: These macros should not be used in user written programs. To
assemble programs that use VSE macros, you should follow the
procedures as previously described in this chapter.
o

OSMACRO MACLIB, OSMACROI MACLIB, and TSOMAC MACLIB
are used by OS programmers.

o

DMKSP MACLIB contains macros that support CPo

o

OSVSAM MACLIB contains the subset of supported OS/VSAM macros.

To obtain a list of macros in any of these libraries, use either the MACLIST
command or the MACLIB command with the MAP function. In the
MACLIST environment, you can issue CMS commands against the members
directly from the displayed list. You can find the MACLIST command
description in the VM/ SP CMS Command Reference.
When you use VSAM on CMS and write programs using VSE/VSAM
macros, you can build a VSE/VSAM maclib by issuing the CMS VSEVSAM
command. The maclib contains the supported VSE/VSAM macros and the
following VSE macros:
CDLOAD
CLOSE
CLOSER
GET
OPEN
OPENR
PUT

Refer to the VM/ SP Installation Guide for the CMS VSEVSAM command
documentation.

VSE Assembler Language Macros Supported
Figure 25 on page 237 lists the VSE assembler language macros supported
by CMS/DOS. You can assemble source programs that contain these
macros under CMS/DOS, provided that you have the macros available in
either your own or a shared CMS macro library. The macros whose
functions are described in the "Function" column with the term "no-op" are
supported for assembly only; when you execute programs that contain these
macros, the VSE functions are not performed. To accomplish the macro
function you must execute the program on a real VSE system.

236

VM/SP eMS for System Programming

[_ . . _..___ . _. _._..... _... _ . .___.........___ .n__ ... ____. _._. . _. .__ ._.

r,:I~cro

NunllJm'

CANCEL
CDLOAD

06
65

CHECK

DEQ
DTFxx
DUMP
ENQ
EOJ
ERET
EXCP
EXIT PC
EXIT AB
EXTRACT
FCEPGOUT
FETCH
FREE
FREEVIS
GENL
GET
GETFLD/
MODFLD
GETVCE
GETVIS
GETIME
JDUMP
LOAD
LOCK/
UNLOCK
MVCOM

..

. -..

.'_'_.'____
. ." __'_' __"_'__.-- ._. ___. .__. ._. _ .._. __ ... _. .

~-_--._
---:.:...~__.-_.n~=::._-

.

__.~.~~_ .:....~

svc

NnnlC
CALL

CLOSEt
CLOSER
CNTRL
COMRG'

..-._. _...

_~~~~:.:_

33
41

42
14
00
17
95
98
86
01
02
36
62

107
99
61
34

Ii'unction
Pass control to another program
Terminate processing
Load a VSAM phase
Verify completion of a read or write operation
Deactivate a data file
Control a physical device
Return address of background partition communication region
no-op
Establish file definitions
Dump storage and registers and terminate processing
no-op
Terminate processing normally
Provide an error routine
Execute a channel program
Return from program check routine
Return from abnormal termination routine
Retrieve PUB, storage boundaries, or CPUID information
no-op
Load and pass control to a phase
Load and pass control to a logical transient
no-op
Release user free storage
Generate a phase directory list
Access a sequential file
Provide macro interface support for system information
retrieval.
Return requested device information to output area.
Obtain user free storage
Get the time of day
Dump storage and registers and terminate processing

04
110

Resource control

05

Modify bytes in the partition communication region

NOTE
OPEN/OPENR
Figure 25 (Part 1 of 2).

Load a phase into storage

Manage data set access
Activate a data file
VSE Macros Supported by eMS

Chapter 9. Developing VSE Programs under CMS

237

Macro
Name
PAGEIN
PDUMP
PFIX
PFREE
POINTR
POINTS
POINTW
POST
PRTOV
PUT
PUTR
READ
RELPAG
RELSE
RETURN
RUNMODE
SECTVAL
SETIME
SETPFA
STXIT AB
STXIT PC
STXIT IT
STXIT OC
SUB SID
TRUNC
TTIMER
WAIT
WRITE
xxMOD

SVC
Number
87
67
68

40

85

66
75
10/24
71
37
16
20
18
105
52
07

Figure 25 (Part 2 of 2).

Function
no-op
Dump storage and registers and continue processing
no-op
no-op
Position a file for reading
Reposition a file to its beginning
Position a file for writing
Post the event control block
Control printer overflow
Write to a sequential file
Communicate with the system operator
Access a sequential file
no-op
Skip to begin reading next block
Return control to calling program
Check if program is running real or virtual
Obtain a sector number
no-op
no-op
Provide or terminate linkage to abnormal ending routine
Provide or terminate linkage to program check routine
no-op
no-op
Retrieve information on supervisor subsystem
Skip to begin writing next block
Return a 0 in Register 0 (effectively a no-op)
Wait for the completion of I/O
Write to a sequential file
Create Logical IOCS routine in line

VSE Macros Supported by eMS

Assembling Source Programs
If you are a DOS assembler language programmer using CMS/DOS, you
should be aware that the assembler used is the VM/SP assembler, not the
DOS assembler. The major difference is that the VM/SP assembler, invoked
by the ASSEMBLE command, is designed for interactive use. Therefore,
when you assemble a program, error messages are displayed at your
terminal when compilation is completed, and you do not have to wait for a

238

VM/SP eMS for System Programming

lDeve~@rjnu1)~ ~§~ ~~)U~(Q)DUAC1u~uS
c

--------------------------------

----------------------]

printed listing to see the results. You can correct your source file and
reassemble it immediately. Then you can print the listing error free.
To specify options to be used during the assembly, you enter them on the
ASSEMBLE command line. So, for example, if you do not want the output
LISTING file placed on disk, you can direct it to the printer:
assemble myfile (print

All of the ASSEMBLE command options are listed in VM/ SP CMS
Command Reference.
When you invoke the ASSEMBLE command specifying a file with a filetype
of ASSEMBLE, CMS searches all of your accessed disks, using the standard
search order, until it locates the file. When the assembler creates the
output LISTING and TEXT files, it writes them onto disk according to the
following priorities:
1.

If the source file is on a read/write disk, the TEXT and LISTING files
are written onto the same disk.

2.

If the source file is on a read-only disk that is an extension of a
read/write disk, the TEXT and LISTING files are written onto the
parent disk.

3.

If the source is on any other read-only disk, the TEXT and LISTING
files are written onto the A-disk.

In all of the above cases, the filenames assigned to the TEXT and LISTING
files are the same as the filename of the input file.
The output files used by the assembler are defined via FILEDEF commands
issued by CMS when it calls the assembler. If you issue a FILEDEF
command using one of the assembler ddnames before you issue the
ASSEMBLE command, you can override the default file definitions.
The ddname for the source input file is ASSEMBLE. If you enter:
filedef assemble reader
assemble sample

then the assembler reads your input file from your card reader, and assigns
the filename SAMPLE to the output TEXT and LISTING files. You can use
this method to assemble programs directly from DOS sequential files on
DOS disks. For example, to assemble a source file named DOSPROG from a
DOS disk accessed as a C-disk, you could enter:
filedef assemble c dsn dosprog (recfm f lrecl 80
assemble dosprog

Again, the name you assign on the ASSEMBLE command may be anything.
The assembler uses this name to assign filenames to the TEXT and
LISTING output files.

Chapter 9. Developing VSE Programs under CMS

239

D)O\7G~0)fVUDufj V8~ [)U @0jltG1mO
1

--_.-._-.-::--:--:-1

r-

LISTING and TEXT are the ddnames assigned to the SYSLST and SYSPCH
output of the assembler. You might issue file definitions to override these
defaults as follows:
filedef listing disk assemble listfile a
filedef text disk assemble textfile a
assemble source

When these commands are executed, the output from the assembly of the
file SOURCE ASSEMBLE is written to the disk files ASSEMBLE
LISTFILE and ASSEMBLE TEXTFILE.

Link-editing Programs in eMS/DOS
When the assembler or one of the language compilers executes, the object
module produced is written to a CMS disk in a file with a filetype of TEXT.
The filename is always the same as that of the input source file. These
TEXT files (sometimes referred to as decks, although they are not real card
decks) can be used as input to the linkage editor or can be used with an
INCLUDE linkage editor control statement.
You can invoke the CMS/DOS linkage editor with the DOSLKED
command, for example:
doslked test testlib

where TEST is the filename of either a DOSLNK or TEXT file (that is, a
file with a filetype of either DOSLNK or TEXT) or the name of a
relocatable module in a system or privaterelocatable library. TESTLIB
indicates the name of the output file which, in CMS/DOS, is a phase library
with a filetype of DOSLIB.
When you issue the DOSLKED command:
1.

CMS first searches for a file with the specified name and a filetype of
DOSLNK.

2. If none is found, CMS searches the private relocatable library, if you
have assigned one. You must issue an ASSGN command for SYSRLB
and use the ddname IJSYSRL in a DLBL statement.
3. If the module is still not found, CMS searches all of your accessed disks
for a file with the specified name and a filetype of TEXT.
4.

240

Last, CMS searches the system relocatable library, if it is available.
You must enter the CMS/DOS environment specifying the mode letter
of the DOS system residence if you want to access the system libraries.

VM/SP eMS for System Programming

L· ..

Linftage Editor Input
You can place the linkage editor control statements ACTION, PHASE,
INCLUDE, and ENTRY in a CMS file with a filetype of DOSLNK. When
you use the INCLUDE statement, you may specify the filename of a CMS
TEXT file or the name of a module in a DOS relocatable library:
INCLUDE XYZ

or you may use the INCLUDE control statement to indicate that the object
code follows:
INCLUDE
(CMS TEXT file)

A typical DOSLNK file, named CONTROL DOSLNK, might contain the
following:
ACTION REL
PHASE PROGMAIN,S
INCLUDE SUBA
PHASE PROGA,*
INCLUDE SUBB

When you issue the command:
doslked control

the linkage editor searches the following for the object files SUBA and
SUBB:
o

A DOS private relocatable library, provided you have issued the ASSGN
and DLBL commands to identify it:
assgn sysrlb d
dlbl ijsysrl d dsn ? (sysrlb

o

Your CMS disks for files with filenames SUB A and SUBB and a filetype
of TEXT

o

The system relocatable library located on the DOS system residence
volume (if it is available).

Unlc-editing TEXT Files

When you want to link-edit individual CMS TEXT files, you can insert
linkage editor control statements in the file using the editor and then issue
the DOSLKED command:
xed it rtnb text
input include rtnc
file
doslked rtnb mydoslib

When the above DOSLKED command is executed, the CMS file RTNB
TEXT is used as linkage editor input, as long as there is no file named

Chapter 9. Developing VSE Programs under' eMS

241

RTNB DOSLNK. The ACTION statement, however, is not recognized in
TEXT files.
You can also link-edit relocatable modules directly from a DOS system or
private relocatable library, provided that you have identified the library. If
you do this, however, you cannot directly provide control statements for the
linkage editor.
To link-edit a relocatable module from a DOS private library and add
linkage editor control statements to it, you could use this procedure:
1.

Identify the library and use the RSERV command to copy the
relocatable module into a CMS TEXT file. In this example, the module
RTNC is to be copied from the library OBJ.MODS:
assgn sysrlb e
dlbl ijsysrl e dsn obj mods (sysrlb
rserv rtnc

2.

Create a DOSLNK file, insert the linkage editor control statements, and
copy the TEXT file created in step 1 into it using the GET subcommand:
xedit rtnc doslnk
input action reI
get rtnc text a
file

3. Invoke the linkage editor with the DOSLKED command:
doslked rtnc mydoslib

Alternatively, you could create a DOSLNK file with the following records:
DOSLNK file
ACTION REL
INCLUDE RTNC

and link-edit the module directly from the relocatable library. If you do not
need a copy of the module on a CMS disk, you might want to use this
method to conserve disk space.
When the linkage editor is reading modules, it may encounter a blank card
at the end of a file or a * (comment) card at the beginning of a file. In
either case, the linkage editor issues a warning message indicating an
invalid card, but it continues to complete the link-edit.

Linkage Editor Output: eMS DOSLIBs
The CMS/DOS linkage editor always places the link-edited executable
phase in a CMS library with a filetype of DOSLIB. You should specify the
filename of the DOSLIB when you enter the DOSLKED command:
doslked progO temp lib

242

VM/SP eMS for System Programming

_ _ _ ""-

.. -:_""._".""_~_""_" ____.::_. ____ ~".___"__ .:....:..:.:.:.._.:. __ ..:....:_. __ ... ____"~~"_""_. ___ ":~_~~~':'::__.~.J

where PROGO is the relocatable module you are link-editing and TEMPLIB
is the filename of the DOSLIB.
If you do not specify the name of a DOSLIB, the output is placed in a
DOSLIB that has the same name as the DOSLNK or TEXT file being
link-edited. In the above example, a CMS DOSLIB is created named
TEMPLIB DOSLIB, or, if the file TEMPLIB DOSLIB already exists, the
phase PROGO is added to it.
DOSLIBs can contain relocatable core image phases suitable for execution
in CMS/DOS. Before you can access phases in them, you must identify
them to CMS with the GLOBAL command:
global doslib temp lib permlib

When CMS is searching for executable phases, it searches all DOSLIBs
specified on the last GLOBAL DOSLIB command. If you have named a
number of DOSLIBs or if any particular DOSLIB is very large, the time
required for CMS to fetch and execute the phase increases. You should use
separate DOSLIBs for executable phases, whenever possible. Then specify
only the DOSLIBs you need on the GLOBAL command.
When you link-edit a module into a DOSLIB that already contains a phase
with the same name, the directory entry is updated to point to the new
phase. However, the space that was occupied by the old phase is not
reclaimed. You should periodically issue the command:
doslib comp temp lib

to compress the DOSLIB and delete unused space. TEMPLIB is the
filename of the DOSLIB.
Linlcage Editor Maps

The DOSLKED command also produces a linkage editor map. It writes into
a CMS file with a filename specified on the DOSLKED command line and a
filetype of MAP. The filemode is always A5. If you do not want a linkage
editor map, use the NOMAP option on the ACTION statement in a
DOSLNK file.

EJtecuiing Programs in eMS/toOS
After you have assembled or compiled a source program and link-edited the
TEXT files, you can execute the phases in your CMS virtual machine. You
may not, however, be able to execute all your DOS programs directly in
CMS. There are a number of execution-time restrictions placed on
CMS/DOS programs. You cannot execute a program that uses:
o
o
o
o

Multi tasking
More than one partition
Teleprocessing
ISAM macros to read or write files
Chapter 9. Developing VSE Programs under CMS

243

[Q)GUG~(i]f.uo~ug V~~ [Du1@~?JU~@uuuG

c_._.__________

._~:.._.....

______.________._.________.____. __ .__ ...
•
•

......-.. -..._. _. . --- . ----_.._. . _. _.... __._---_ . . _--------------J

CMS module files created by DOS programs
EC mode PSW s.

The above is only a partial list representing those restrictions with which
you might be concerned. For a complete list of restrictions, see the VM/SP
Planning Guide and Reference. See also the usage notes of the FETCH
command in the VM/ SP CMS Command Reference.

Executing DOS Phases
You can load executable phases into your CMS virtual machine using the
FETCH command. Phases must be link-edited with ACTION REL before
you load them. When you issue the FETCH command, you specify the
name of the phase to be loaded:
fetch myprog

Then you can begin executing the program by issuing the START command:
start

Or, you can fetch a phase and begin executing it with a single command:
fetch prog2 (start

When you use the FETCH command without the START option, CMS
issues a message telling you at what virtual storage address the phase is
loaded:
PHASE PROG2 ENTRY POINT AT LOCATION 020000

Location X'20000' is the starting address of the user program area for CMS.
Relocatable phases are always loaded starting at this address unless you
specify a different address using the ORIGIN option of the FETCH
command:
fetch prog3 (origin 22000
start

The program PROG3 executes beginning at location 22000 in the CMS user
program area.

Search Order for Executable Phases
When you execute the FETCH command, CMS searches for the phase name
you specify in the following places:
1.

In a DOS private core image library on a DOS disk. If you have a
private library you want searched for phases, you must identify it using
the ASSGN and DLBL commands using the logical unit SYSCLB:
assgn sysclb d
dlbl ijsyscl d dsn ? (sysclb

244

VM/SP eMS for System Programming

[i··~C:YUC;~~)~)UO·JCJ \,!/S~ lJu'(GOu'~1U'"~JG
l~~.~

__ '::':~_·_·-_.':~:":'::'~:':.=_~_~._ ... __ ~:.':'_.:: ___ .__ ":':":':=_-':' __~'::':-=-

__

. _-, .__. ___

:':"_~~':'_._":_~:_~~_._

__ --.------- .----.-----.---.-.

..:.:.:.:..:.=~

------------.=.J

When you enter the DLBL command with the? operand, you are
prompted to enter the DOS file-ide
2.

In CMS DOSLIBs on CMS disks. If you want DOSLIBs searched for
phases, you must use the GLOBAL command to identify the DOSLIBs to
CMS/DOS:
global doslib temp lib mylib

You can specify up to 63 DOSLIBs on the GLOBAL command line.
3.

On the DOS system residence core image library. If you want the
system core image library searched you must have entered the
CMS/DOS environment specifying the mode letter of the system
residence:
set dos on z

When you want to fetch a core image phase that has copies in both the core
image library and a DOSLIB, and you want to fetch the copy from the CMS
DOSLIB, you can bypass the core image library by entering the command:
assgn sysclb ua

When you need to use the core image library, enter:
assgn sysclb c

where C is the mode letter of the system residence volume. You do not
need to reissue the DLBL command to identify the library.

Making 110 Device Assignments
If you are executing a program that performs I/O, you can use the ASSGN
command to relate a system or programmer logical unit to a real I/O device:
assgn syslst printer
assgn sys052 reader

In this example, your program is going to read input data from your virtual
card reader. The output print file is directed to your virtual printer. If you
want to reassign these units to different devices, you must be sure that the
files have been defined as device independent.
If you assign a logical unit to a disk, you should identify the file by using
the DLBL command. On the DLBL command, you must always relate the
DLBL to the system or programmer logical unit previously specified in an
ASSGN command:
assgn sys015 b
dlbl myfile b dsn ? (sysOlS

When you enter the DLBL command with the? operand you are prompted
to enter the DOS file-ide

Chapter 9. Developing VSE Programs under CMS

245

c:::______

---------------------------------------

______________________.__:::J

You must issue all of the ASSGN and DLBL commands necessary for your
program's 1/0 before you issue the FETCH command to load the program
phase and to begin executing.

Specifying a Virtual Partition Size
For most of the programs that you execute in CMS, you do not need to
specify how large a partition you want those programs to execute in. When
you issue the START command or use the START option on the FETCH
command, CMS calculates how much storage is available in your virtual
machine and sets a partition size. CMS calculates how much storage is
available in the following manner:
FREELOWE - (MAINHIGH + (4096

* FRERESPG»

where:

FREELOWE

equals the low extent of allocated storage obtained from the
top of virtual storage downwards via the DMSFREE system
request.

MAINHIGH

equals the high extent of allocated storage obtained from
the low virtual storage upwards via the GETVIS user
request for storage.

FRERESPG

equals the amount of storage to be reserved for subsequent
system requests, in pages.

In some instances, you may want to control the partition size:
o

For performance considerations

o

Because the default may not leave enough free storage to satisfy the
GETVIS requests issued by the DOS program or the access method
services function being executed.

You can set the partition size with the DOSP ART operand of the SET
command. For example, after you enter the command:
set dospart 300k

all programs that you subsequently execute during this session execute in a
300K partition. In this way you can:

246

•

Set a smaller partition size for programs that run better in smaller
parti tions.

o

Set a smaller partition size to leave more free storage. If the reduction
of the DOS partition does not free enough storage for the GETVIS
requests, a larger virtual machine must be defined. If you enter:

VM/SP eMS for System Programming

~ ..

set dospart off

CMS calculates a partition size when you execute a program. This is
the default setting.

Note: The CMS partition, unlike the DOS partition, is used only for the
loading and executing of programs invoked by the FETCH or LOAD
commands. Areas allocated by GETVIS are assigned addresses outside the
partition but within the user's virtual machine.

Setting the UPSI Byte
If your program uses the user program switch indicator (UPSI) byte, you
can set it by using the UPSI operand of the CMS SET command. The UPSI
byte is initially binary zeros. To set it to ones, enter:
set upsi 11111111

To reset it to zeros, enter:
set upsi off

Any value you set remains in effect for the duration of your terminal
session unless you reload CMS (with the IPL command).

Debugging Programs in CMS/DOS
You can debug your DOS programs in CMS/DOS using the facilities of CP
and CMS. By executing your programs interactively, you can determine
the cause of an error or program abend, correct it, and attempt to execute a
program again. The CP and CMS debugging facilities are described in VM
Diagnosis Guide.

Using EXEC Procedures in CMS/DOS
During your program development and testing cycle, you may want to
create EXEC procedures to contain sequences of CMS commands that you
execute frequently. For example, if you need a number of MACLIBs,
DOSLIBs, and DLBL definitions to execute a particular program, you might
have an EXEC procedure as follows:

Chapter 9. Developing VSE Programs under CMS

247

ITJ)QUG~@IT»U~uB ~f§~ [Jr(Q)~1~18mrils
c==:~:-::=~====-_-=-...:::

___.__. __. _._. . _. _._. _. _._._._ ._ . ___._ . . __.__ . _._. ._. _________. ______. __ . _. . . ___ , _____. .__________.____________..____._."__._. . . .__.____J

/* EXEC to set up environment to run program TESTA */
signal on error
global maclib testlib dosmac
assemble testa
print testa listing
doslked testa testlib
global doslib test lib proglib
access 200 e
assgn sys010 e
push dos.test3.stream.beta
dlbl inddl e dsn ? '('sys010
assgn sysOll punch
cp spool punch to '*'
assgn sys012 a
dlbl outfile a cms test data' ('sys012
signal off error
fetch testa' ('start
select
when rc = 100 then do

end
when rc

200 then do

end
otherwise
exit rc
end
Error:
say 'Error occurred on line' sigl':' sourceline(sigl)
exit rc

The 'signal on error' control statement in the EXEC procedure ensures that
if an error occurs during any part of the EXEC, the remainder of the EXEC
does not execute, and the 'Error' displays the line number where the error
occurred as well as the actual command which gave the error.
Note: For the DLBL command entered with the DSN ? operand, you must
stack the response (using 'push') before issuing the DLBL command.

When your program is finished executing, the REXX special variable RC
indicates the contents of general register 15 at the time the program exited
(the 'Return Code'). You can use this value to perform additional steps in
your EXEC procedure. Additional steps are indicated in the preceding
example by ellipses.

248

VM/SP eMS for System Programming

(0)C:YvG~~jIT)null[J
-- ---_._._--_.-

-- - --- -- --

- --

.

- --- - -... ..-

- ..-

l18l2 [J u'\00u [}uJilG

-- -- _. -- - .. - -- --- ...

l

'

-- --- ... -.-.......... -.- .... -._.......... _-

-.--.:::~

Hardware Devices Supported
CMS/DOS routines can read real DOS disks containing VSE data files and
VSE private and system libraries. This read support is limited to the
following disks supported by VSE:
o
o
o

o
o
o

o
o
o
o
o

IBM
IBM
IBM
IBM
IBM
IBM
IBM
IBM
IBM
IBM
IBM

2314
2319
3310
3330
3330
3340
3344
3350
3370
3375
3380

Direct Access Storage Facility
Disk Storage
Direct Access Storage
Disk Storage, Models 1 and 2
Disk Storage, Model 11
Direct Access Storage Facility
Direct Access Storage
Direct Access Storage
Direct Access Storage, Models AI, A2, B1, and B2
Direct Access Storage
Direct Access Storage

The following devices, which are supported by VSE, are not supported by
CMS/DOS:
o

Card Readers: 1442, 2560P, 2560S, 2596, 3504, 5425P, and 5425S

o

Printers: 2560P, 2560S, 3203 Models 1 and 2,3525, 5203, 5425P, and
5425S

o

Disks: 2311.

Also, CMS uses the CP spooling facilities and does not support dedicated
unit record devices. Each CMS virtual machine supports only one virtual
console, one reader, one punch, one printer, four tapes, and 26 disks.
Programs that are executed in CMS/DOS are limited to the number of
devices supported by CMS.

VSE Supervisor and I/O Macros Supported by eMS/DOS
CMS/DOS supports the VSE Supervisor macros and the SAM and VSAM
I/O macros to the extent necessary to execute the DOS/VS COBOL
.
Compiler, the DOS PL/I Optimizing Compiler, and DOS/VS RPG II Compiler
under CMS/DOS. CMS/DOS supports VSE Supervisor macros described in
the publication VSE Macro Reference.
Since eMS is a single-user system executing in a virtual machine with
virtual storage, VSE operations, such as multi-tasking, that cannot be
simulated in CMS' are ignored.
The following information deals with the type of support that CMS/DOS
provides in. the simulation of VSE Supervisor and Sequential Access
Method I/O macros. For a discussion of VSAM macros, see the section
"CMS Support for OS and VSE/VSAM Functions."

Chapter 9. Developing VSE Programs under CMS

249

[IJ)G\7e~Q)~]UUU~l ~8~

ru fJ)fjrDr . ~ [,\ r\n(~[-;;C)\\r; 0'1
\\fC:'
r'Cl
~),~,,")UL ll[J ·,I[l\;l]l:,.. · ._.".,L~l \} LlU U\'.J \, lC.J" .\lJ\./l.
"-.-~

..-.---.-.. ---.-__:_---_::-----.

. . . . -.. . . _. . . ._._._. _--===_.]

recommended}. The actual disk used is not important as long as the
macros are available when VSEVSAM is issued.
3. Issue the CMS VSEVSAM command. Respond to the questions when
you are prompted.
The seven VSE macros can be erased from the disk after the MACLIB is
created because the macros will be in the MACLIB. Once you have created
the MACLIB, you are able to assemble your VSAM assembler applications
using the VSE/VSAM assembler macros in the MACLIB. The VSEVSAM
EXEC is documented in the VM/ SP Installation Guide.

VSE Supervisor Macros and Logical Transients Support for VSAM
VSE supervisor macros required by VSE/VSAM are supported by CMS. See
Figure 25 on page 237 for a complete list of supervisor macros supported.
CMS distributes the VSE transients that are needed in the VSAM support.
Thus, OS users do not need to have the VSE system pack on-line when they
are compiling and executing VSAM programs.
CMS uses all of the VSE B-transients except those that build and release
extent blocks. The extent block is not supported in CMS and, thus, neither
are the B-transients that control extent blocks.
The CMSDOS shared segment contains the B-transients that are simulated
for VSE support in CMS. The B-transients pertaining only to VSAM are
included in the VSAM saved segment. Other VSE routines required by
VSE/VSAM are contained in the CMSBAM shared segment. This includes
the common VTOC handler routines, SAM data management, and the
VSAM look-aside function.

OS/VSAM Macros Supported in eMS
A subset of the OS/VSAM macros are supported for use in CMS. The
macros are at an MVS 3.8 level and they are contained in the OSVSAM
MACLIB that is shipped with VM/SP. The macros are:
ACB
CHECK
ENDREQ
ERASE

EXLST
GENCB
MODCB
POINT

RPL
SHOWCB
TESTCB

Some options of the OS/VSAM macros do not work in CMS because
OS/VSAM macro requests are executed using VSE/VSAM code. Figure 34
lists the OS/VSAM macros and the supported options.
/

312

VMjSP eMS for System Programming

OS/VSAM IVlacro

Supporteu Options

ACB

AM=VSAM
BUFND = number
BUFNI = number
BUFSP = number
DDNAME = ddname
MACRF=ADR, CNV, KEY, NOF,
DIR, SEQ, SKP, IN, OUT,
NRMIAIX, NRSIRST, NSR, NUB1UBF,

CHECK

RPL = address

ENDREQ

RPL = address

ERASE

RPL = address

EXLST

AM=VSAM
EODAD = address
JRNAD = address
LERAD = address
SYNAD = address

GENCB BLK=ACB

EXLST = address
BUFND=number
BUFNI = number
BUFSP = number
COPIES = number
DDNAME = ddname
MACRF=ADR, CNV, KEY, NOF,
DIR, SEQ, SKP, IN, OUT,
NRMIAIX, NRSIRST, NSR, NUBIUBF,

LENGTH = number
MAREA = address
MLEN=number
P ASSWD = address
STRNO=number
WAREA = address

GENCB BLK=EXLST

EODAD = address
JRNAD = address
LERAD = address
SYNAD = address

COPIES = number
LENGTH = number
WAREA = address

GENCB BLK=RPL

ACB = address
AREA = address
AREALEN = number
ARG = address
COPIES = number
OPTCD =ADRICNVIKEY,
DIRlsEQISKP, AROILRD,
FwoIBWD, ASYlsYN,
NSPINUpIUPD, KEQIKGE,
~KsIGEN, LOCIMVE,

ECB = address
KEYLEN = number
LENGTH = number
NXTRPL = address
RECLEN = number

Figure 34 (Part 1 of 3).

EXLST = address
MAREA = address
MLEN = number
P ASSWD = address
STRNO=number

WAREA~number

Options of OS/VSAM Macros Supported in eMS

Chapter 10. Using Access Method Services and VSAM under CMS and CMS/DOS

313

L __._______ _

__ _ _ _ _ _ _ _ _ _ _ _ _==:J

OS/VSAM Macro

Supported Options

GET

RPL = address

MODCBACB

BUFND=number
BUFNI = number
BUFSP = number
DDNAME = ddname
MACRF=ADR, CNV, KEY, NDF,
DIR, SEQ, SKP, IN, OUT,
NRMIAIX, NRSIRST, NSR,
NUBIUBF,

MODCB EXLST

EODAD = address
JRNAD = address
LERAD = address
SYNAD = address

MODCBRPL

ACB = address
AREA = address
AREALEN = number
ARG = address
OPTCD =ADRICNVIKEY,
DIRISEQISKP, ARDILRD,
FWDIBWD, ASYISYN,
NSPINUPIUPD, KEQIKGE,
FKSIGEN, LOCIMVE

POINT

RPL = address

RPL

ARG = address
ECB = address
KEYLEN=number
NXTRPL = address
RECLEN = number

SHOWCBACB

ACB = address
AM=VSAM
AREA = address
AREALEN = number
OPTCD=ADRICNVIKEY,
DIRlsEOISKP, ARDILRD,
FWDIBWD, ASYISYN,
NSPINUpIUPD, KEOIKGE,
FKSIGEN, LOCIMVE,
AREA = address
FIELDS = ACBLEN, AVSPAC,
BUFND, BUFNI, BUFNO,
BUFSP, CINV, DDNAME,
ERROR, EXLST, FS, KEYLEN,
LRECL, MAREA, MLEN, NCIS,
NDELR, NEXCP, NEXT, NINSR,
NIXL, NLOGR, NRETR, NSSS,
NUPDR, PASSWD, RKP, STMST,
STRMAX, STRNO

SHOWCB EXLST

AREA = address

LENGTH = number

EXLST = address
MAREA = address
MLEN = address
P ASSWD = address
STRNO=number

ECB = address
KEYLEN = number
NXTRPL = address
RECLEN = number

OBJECT = DATAIINDEX
LENGTH = number

Figure 34 (Part 2 of 3). Options of OS/VSAM Macros Supported in eMS

314

VM/SP eMS for System Programming

[----_._-----_._. __ ._--------------------_.

- - - - - - - . - - _..

__ . __

...

_--_.- .....

-

----,

Supported Options

OS/VSAM Macro

FIELDS = EODAD, EXLLEN,
JRNAD,LERAD,SYNAD
SHOWCBRPL

AREA = address
FIELDS=ACB, AIXPC, AREA,
AREALEN,ARG,ECB,FDBK,
FTNCD, KEYLEN, NXTRPL,
RBA,RECLEN, RPLLEN

LENGTH = number

TESTCB ACB

ERET = address
OBJECT = DATAl INDEX
ATRB=UNQ
OFLAGS = OPEN
OPENOBJ = PATHIBASEIAIX
ACBLEN = number
AVSPAC=number
BUFND=number
BUFNI = number
BUFNO=number
BUFSP = number
CINV = number
DDNAME = ddname
ERROR = number
EXLST = address
FS=number
KEYLEN = number
ATRB=ESDS, KSDS, REPL,
RRDS, SPAN, SSWD, WCK

LRECL = number
MAREA = address
MLEN = number
NelS = number
NDELR = number
NEXCP = number
NEXT = number
NINSR = number
NIXL = number
NLOGR=number
NRETR=number
NSSS = number
NUPDR=number
P ASSWD = address
RKP=number
STMST = address
STRNO=number
MACRF= ADR, AIX,
CNV, DIR, IN, KEY,
NDF, NRM, NRS, NSR,
NUB, OUT, RST, SEQ,
SKP,UBF

TESTCB EXLST

ERET = address
EODAD = address
JRNAD = address

LERAD = address
SYNAD = address
EXLLEN=number

TESTCB RPL

ERET = address
AIXFLAG = AIXPKP
AIXPC=number
FTNCD = number
I/O = COMPLETE
ACB = address
AREA = address
AREALEN = number
OPTCD=ADR, ARD, ASY, BWD,
CNV, DIR, FKS, FWD, GEN,
KEQ, KEY, KGE, LOC, LRD,
MVE, NSP, NUP, SEQ, SKP, SYN,
UPD

ARG = address
ECB = address
FDBK = number
KEYLEN = number
NXTRPL = address
RBA=number
RECLEN = number
RPLLEN = number

Figure 34 (Part 3 of3).

Options of OS/VSAM Macros Supported in eMS

Chapter 10. Using Access Method Services and VSAM under CMS and CMS/DOS

315

~1J D 0uu Cj

f\ L0J 8 [E L;~ V

[~-==:::-=.::::==:::.==

ElfJ'u c~

\f ~~ f':. ~tfJ

____ ._.__.__.______________.____.___.___._:. _____________________________===::::J

OS/VSAM Error Codes
Error codes returned by VSE/VSAM in response to OPEN, CLOSE, and
Data Management Request macro errors are mapped to the appropriate
OS/VSAM error codes.
•

Figure 35 lists the error codes returned by VSE/VSAM in response to
OPEN errors.

•

Figure 36 on page 318 lists the error codes returned by VSE/VSAM in
response to CLOSE errors.

o

Figure 37 on page 319 lists the error codes returned by VSE/VSAM in
response to Data Management Request macro errors.

If a VSE/VSAM error code cannot be mapped to any OS/VSAM error code,
a CMS error message and an ABEND 35 are issued except for the cases
indicated by an "*".

The following table lists the VSE/VSAM to OS/VSAM error code mapping
for OPEN errors:

VSEjVSAI\(I
Error
Code
2
4
14
15
17
18
19
32
34
40
48
50
64
65
66
67

CIV1S Error
IVlessage or
OSjVSAM
Error
Code
DMSVIP779E
4
DMSVIP782E
DMSVIP782E
DMSVIP782E
DMSVIP782E
DMSVIP782E
DMSVIP782E
DMSVIP782E*
DMSVIP778E
168
DMSVIP782E
188
DMSVIP779E
DMSVIP782E
DMSVIP782E

Figure 35 (Part 1 of 3).

316

VM/SP eMS for System Programming

VSEjVSAlVl
Return
Code
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8

OSjVSAM
Return
Code
8
8
8
8

8
8
8
8
8
8
8
8
8
8
8
8

VSE/VSAM to OS/VSAM Error and Return Code
Mapping for OPEN Errors

r-·-----·---------- ----------.----.---- ----. --- ...-.. -------.-- .-...... -... -..-.. "- --.- -----... -. ---. --.- . .

VSE/VSAIVI
Error
Code
68
69
70
71
72
78
79
80
92
96
100
104
108
110
113
114
115
116
117
118
128
132
136
144
148
152
160
161
165
166
167
168
180
188

.---.. --- --..------.----.- ..--.------.. -..-... - -J

CMS Error
Message or
OS/VSAM
Error
Code
168
DMSVIP782E
DMSVIP782E
DMSVIP782E
148
DMSVIP782E
DMSVIP782E
DMSVIP778E
DMSVIP779E
96
100
104
108
160
144
DMSVIP781E
DMSVIP781E
116
DMSVIP782E
0
128
132
136
144
148
152
160
160
DMSVIP782E
DMSVIP782E
DMSVIP782E
168
180
DMSVIP782E

Figure 35 (Part 2 of 3).

VSE/VSAM
Return
Code

OS/VSAM
Return
Code

8
8
8
8
8
8
8
8
8
4
4
4
4
8
0
0
8
4
8

8
8
8
8
8
8
8
8
8
4
4
4
4
8
4
4

0
8
8
8
8
8
8
8
8
8
'8
8
8
8
8

8
4
8
0
8
8
8
8
8
8
8
8
8
8
8
8
8
8

VSE/VSAM to OS/VSAM Error and Return Code
Mapping for OPEN Errors

Chapter 10. Using Access Method Services and VSAM under CMS and eMS/DOS

317

l'J8Dul1~ AM8[E~V c.Hi)(~

V§AM

c---'---

_____ :::J

VSE/VSAM
Error
Code
192
196
212
216
220
228
232
248
254
255

CMS Error
Message or
OS/VSAIVI
Error
Code

VSE/VSAIVI
Return
Code

OS/VSAIVI
Return
Code

192
196
212
216
220
228
232
DMSVIP782E
DMSVIP782E
144

8
8
8
8
8
8
8
8
8
8

8
8
8
8
8
8
8

Figure 35 (Part 3 of 3).

8
8
8

VSE/VSAM to OS/VSAM Error and Return Code
Mapping for OPEN Errors

The following table lists the VSE/VSAM to OS/VSAM error code mapping
for CLOSE errors:

VSE/VSAM
Error
Code

C:M:S Error
Message or
OS/VSAM
Error
Code

VSE/VSAM
Return
Code

OS/VSAM
Return
Code

2
4
76
136
144
165
166
167
184
188
228
252
254
255

DMSVIP783E
4
DMSVIP784
136
144
DMSVIP784
DMSVIP784
DMSVIP784
184
0
DMSVIP783
DMSVIP784
DMSVIP784
148

non-zero
non-zero
non-zero
non-zero
non-zero
non-zero
non-zero
non-zero
non-zero
non-zero
non-zero
non-zero
non-zero
non-zero

4
4
4
4
4
4
4
4

Figure 36.

318

4
4
4
4
4
4

VSE/VSAM to OS/VSAM Error and Return Code Mapping for
CLOSE Errors

VM/SP eMS for System Programming

For Data Management Request errors, all VSE/VSAM error codes are
returned to the OS/VSAM user since the VSE/VSAM and OS/VSAM error
codes are equivalent, with the following exceptions:

VSE/VSAlVI
Error
Code
32
48
52
56
128
208
212
216
Figure 37.

eMS Error
Message or
OS/VSAM
Error
Code
DMSVIP785E
40
Abend 52*
Abend 56*
DMSVIP786E
DMSVIP786E
DMSVIP786E
DMSVIP785E

VSE/VSAr/l
Return
Code
0
8
8
8
8
8
8
8

OS/VSAIVl
Return
Code
0
8
8
8
8
8
8
8

DATA Management Request Error Return Code Mapping

Hardware De"ices Supported
eMS support of VSAM data sets is based on VSE/VSAM. In its support of
VSAM data sets, eMS uses RPS (rotational position sensing) wherever
possible. eMS does not use RPS for 2314/2319 devices or for 3340 devices
that do not have the feature. Except for the 3380, only disks supported by
VSE can be used for VSAM data sets in eMS. These disks are:
o
o
o
o
o
o
o
Q

o
Q
Q

IBM
IBM
IBM
IBM
IBM
IBM
IBM
IBM
IBM
IBM
IBM

2314 Direct Access Storage Facility
2319 Disk Storage
3310 Direct Access Storage
3330 Disk Storage, Models 1 and 2
3330 Disk Storage, Model 11
3340 Direct Access Storage Facility
3344 Direct Access Storage
3350 Direct Access Storage
3370 Direct Access Storage, Models AI, A2, B1, and B2
3375 Direct Access Storage
3380 Direct Access Storage

eMS disk files used as input to or output from Access Method Services may
reside on any disk supported by eMS.

Chapter 10. Using Access Method Services and VSAM under CMS and CMS/DOS

319

____________________________________________________________________________________________ =:J

/'

320

VM/SP eMS for System Programming

Saving the eMS System
Only named systems can be saved. The NAMESYS macro must be used to
name a system. A discussion on creating a named system is found in the
VM/ SP Planning Guide and Reference.
The DMKSNT file must have been configured (by coding the NAMESYS
macro) when CP was generated. The DMKSNT file contains the system
name, size of the system, and its real disk location. The CMS system may
be saved by:
o

Providing a positive response to the following message (message 729R):
Do you want to save the system? (enter l=YES or O=NO)

o

Modifying the DEFNUC MACRO to include a positive response to the
SAVESYS parameter, or

o

Issuing the IPL command with the "SAVESYS systemname" parameter.

The "systemname" is the name assigned to the saved system. This is the
same system name specified in the DMKSNT file.
The CMS S-disk must be mounted and attached to the virtual machine
creating the saved system before the SAVESYS function is invoked. This
ensures that CMS file directories are saved correctly. However, in addition
to the S-disk, you need the Y-disk to save the shared Y-disk directory.

Note: Any updates to the CMS S-disk or Y-disk require saving the CMS
system again.
In VM/SP, the CMS system is designed to be used as a saved system. Its
location may be modified by an installation for its particular requirements
but should be shared among CMS users.

Chapter 11. Tailoring Your CMS System

321

IT E)U ~Q)~~u~uqJ VQ~~%~

CL{~8 817s~emru
r:====-.~=~:-:-_~-.~.=:::~.~.'~-:::-.~~_:='~.~:_-:: .. ':'~~::'-~==-=~__.: ________ ._ ....___. ___________.
___ ._______. . _. _______. _______. . ___. . _________._. __.____. _._.___.___. ____.__
1

:oJ

Saved System Restrictions for eMS
Several coding restrictions must be imposed on CMS if it is to run as a
saved system.
If the key specified in the CAW for a SIO instruction is zero, the data area
for input may not cross the boundary between two pages with different
storage keys.
If you intend to modify a shared CMS system, be sure that all code that is

shared resides in the shared segments of the CMS nucleus. You can use the
USERSECT area of DMSNUC to contain nonshared instructions.
If you want to have a system profile EXEC, or if you want to use the

NOSPROF, INSTSEG, or SAVESYS parameters of the IPL command, you
must have:
PARMRGS=(O,15)

in the NAMESYS macro for the CMS named system.

I

Using the System Profile, SYSPROF EXEC, for Tailoring

V'Jhat the System Profile Does
The system profile is an EXEC that performs some of the CMS initialization
function previously done in a module. You, the system programmer, can
tailor the CMS environment that users see at initialization time by
modifying this EXEC. You can do such things as access additional system
disks or bring up application programs automatically. Decisions on
tailoring the environment can be made on the basis of userid, responses to
prompting, CMS parameters on the IPL command, or any other conditions
defined by your installation.
You can also bypass the system profile. The system profile is not meant to
force users into an environment. Instead, it enables you to change the
default CMS environment established by DMSINS without modifying a
CMS module and rebuilding CMS. You can modify the EXEC to make it as
secure as your installation requires.
The CMS initialization module, DMSINS, calls SYSPROF EXEC and
executes it from a DCSS (discontiguous shared segment) or the system disk
or the system disk extension. This is done before any user disks are
accessed. When you enter the IPL CMS command, SYSPROF EXEC is
executed unless you:

322

•

Specify the NOSPROF parameter on the command line, or

o

IPL a non-DASD virtual device, such as a reader, or

VM/SP eMS for System Programming

,/

savearea
lr
r13,r15
space
*open files and check that they opened okay
space
la
r3,0
initially set return code
open (indata,outdata,(output))
open files
using ihadcb,rlO
get dsect to check files
la
rlO,indata
prepare to check output file
tm
dcboflgs,x'lO' everything ok?
bnz
checkout
.. . continue
r3,100
set return code
la
b
exit
... exit
checkout la
rlO,outdata
check output file
dcboflgs,x'lO' is it okay?
tm
bnz
process
r3,200
la
set return code
b
exit
space
process equ
*
indata
read a record from input file
get
lr
r2,rl
save address of record
put
outdata, (2)
move it to output
process
continue until end-of-file
b
space
exit
equ
*
close (indata"outdata)
close files
r13,savearea+4 addr of caller's save area
1
lr
r15,r3
load return code
1
r14,12(r13)
get return address
1m
rO,r12,20(r13) restore regs
br
r14
bye ...
space
savearea dc
lBf'O'
ddname=indd,macrf=gl,dsorg=ps,recfm=f,lrecl=BO,
indata
dcb

356

VM/SP eMS for System Programming

*

2

saveninput
Input mode:
outdata

codad=c::i t
deb
ddname=outdd,macrf=pm,dsorg=ps
dcbd
space
end

3

4
S
6

file
Ready;
global maclib osmacro
Ready;
assemble ostest
ASSEMBLER DONE
OST00230
23
LA
R3,0
INITIALLY SET RETURN CODE
IF0188 R3 IS AN UNDEFINED SYMBOL
OST00240
24
OPEN (INDATA/OUTDATA/(~UTPUT))
OPEN FILES
4000000
27+
12,*** IHB002 INVALID OPTION OPERAND SPECIFIED-OUTDATA
IF0197 *** MNOTE ***
OST00290
32
LA
R3,100
SET RETURN CODE
IF0188 R3 IS AN UNDEFINED SYMBOL
OST00340
37
LA
R3,200
SET RETURN CODE
IF0188 R3 IS AN UNDEFINED SYMBOL
OST00460
63
LR
RIS,R3
LOAD RETURN CODE
IF0188 R3 IS AN UNDEFINED SYMBOL
NUMBER OF STATEMENTS FLAGGED IN THIS ASSEMBLY
S
Ready(00012) i

2

Before continuing to enter input lines, the EDIT subcommand SAVE is issued to write what has
already been written onto disk. The CP logical line end symbol (#) separates the SAVE and
INPUT subcommands.

3

A null line returns you to edit mode. You may wish, at this point, to proofread your input file
before issuing the FILE subcommand to write the ASSEMBLE file onto disk.

4

Since this assembler program uses OS macros, you must issue the GLOBAL command to identify
the CMS niacro library, OSMACRO MACLIB, before you can invoke the assembler.

5

The ASSEMBLE command invokes the VMjSP assembler to assemble the source file.

6

The assembler displays errors encountered during assembly. Depending on how accurately you
copied the program in this sample session, you mayor may not receive some of these messages;
you may also have received additional messages.

Appendix B. Sample Terminal Session for OS Programmers

357

7

xedit ostest assemble
locate Ir2
R2
EQU
2
i r3
equ
3

lopen
*OPEN FILES AND CHECK THAT THEY OPENED OKAY

lopen
OPEN

(INDATA,OUTDATA,(OUTPOT))

c 1,1,,1

8
9
10
11
12

OPEN (INDATA"OUTDATA,(OUTPUT))
file
Ready;
assemble ostcst
ASSEMBLER DONE
NO STATEMENTS FLAGGED IN THIS ASSEMBLY
Ready;
filedef indd disk test data a
Ready;
filedef outdd punch
Ready;
cp spool punch to *
Ready;

OPEN FILES
OPEN FILES

7

You must edit the file OSTEST ASSEMBLE and correct any errors in it. The errors placed in
the example included a missing comma on the OPEN macro and the omission of an EQU
statement for a general register. These changes are made as shown. The CMS Editor accepts a
diagonal (/) as a LOCATE subcommand.

S

After all the changes have been made to the ASSEMBLE file, you can issue the FILE
subcommand to replace the existing copy on disk and then reassemble it.

9

This time the assembler completes without encountering any errors. If your ASSEMBLE file
still has errors, you should use the editor to correct them.

10

The FILEDEF command is used to define the input and output files used in this program. The
ddnames INDD and OUTDD, defined in the DCBs in the program, must have a file definition in
CMS. To execute this program, you should have a file on your A-disk named TEST DATA,
which must have fixed-length, SO-character records. If you have no such file, you can make a
copy of your ASSEMBLE file as follows:
copyfile ostest assemble a test data a

11

The output file is defined as a punch file so that it will be written to your virtual card punch.

12

The CP SPOOL command is issued, using the CP function, to spool your virtual punch to your
virtual card reader.

/

358

VM/SP eMS for System Programming

13

14
15

16
17
18
19

load ostest
Ready;
start
DMSLI0740I Execution begins ...
DMSSOP036E Open error code 04 on OUTDD.
Ready(00200);
filedef
INDD
DISK
TEST
DATA
A1
OUTDD
PUNCH
Ready;
filedef outdd punch (lrecl 80 recfm f
Ready;
cp query reader all
NO RDR FILES
Ready;
load ostest (start
DMSLT0740I Execution begins ...
PUN FILE 6198 TO BILBO
COpy 01 NOHOLD
Ready;

13 The LOAD command loads the TEXT file produced by the assembly into virtual storage. The
START command begins program execution.
14 An open error is encountered during program execution. The CMS ready message indicates a
return code of 200, which is the value placed in it by your program.
15 The FILEDEF command, with no operands, results in a display of the current file definitions in
effect.
16 Error code 4 on an open request means that no RECFM or LRECL information is available. An
examination of the program listing would reveal that the DeB for OUTDD does not contain any
information about the file format; you must supply it on the FILEDEF command. Re-enter the
FILEDEF command.
17 You can use the CP QUERY command to determine whether there are any files in your card
reader. It should be empty; if not, determine whether they might be files you need and, if so,
read them into your virtual machine; otherwise, purge them.
18 Use the LOAD command to execute the program again; this time, use the START option of the
LOAD command to begin the program execution.
19 The PUN FILE message indicates that a file has been transferred to your virtual card reader.
The ready message indicates that your program executed successfully.

Appendix B. Sample Terminal Session for

as Programmers

359

20

21
22
23

fi indd reader
Ready;
fi Qutdd disk new osfile a4 (recfm fb block 1600 lrecl 80
Ready;
listfile new osfile a4 (label
DMSLST002E File not found.
Ready(00028);
run: ostest
Execution begins ...
Ready;
listfile new osfile a4 (label
FILENAME FILETYPE FM FORMAT LRECL RECS BLOCKS
DATE
NEW
OSFILE
A4 F
1600
5
10 9/30/75
Ready;

TIME
8:26:14

LABEL
PAT198

20 For the next execution of this program, you are going to read the file back out of your card
reader and create a new CMS disk file in OS simulated data set format. FI is an acceptable
system truncation for the command named FILEDEF.
21 The LISTFILE command is issued to check that the file NEW OSFILE does not exist.
22 The RUN command (which is an EXEC procedure) is used instead of the LOAD and START
commands to load and execute the program. The ready message indicates that the program
completed execution.
23 The LIST FILE command is issued again, and the file NEW OSFILE is listed. (If you issue
another CP QUERY READER command, you will also see that the file is no longer in your card
reader.)

360

VM/SP eMS for System Programming

The following terminal session shows how you might create an assembler
language program in CMS, assemble it, correct assembler errors and
execute it. All the lines in blue are lines that you should enter at the
terminal. The other lines represent the system responses that you should
receive when you enter the command.
The input data lines in the example are aligned in the proper columns for
the assembler; if you are using a typewriter terminal, you should set your
terminal's tab stops at columns 10, 16, 31, 36, 41 and 46, and use the Tab key
when you want to enter text in these columns. If you are using a display
terminal, when you use a PF key or an input character defined as a tab, the
line image is expanded as it is placed in the screen output area.
Note: The assembler, in CMS, cannot read macros from VSE/AF libraries.
This sample terminal session shows how to copy macros from VSE/ AF
libraries and create CMS MACLIB files. Ordinarily, the macros you need
should already be available in a system MACLIB file. You do not have to
create a MACLIB each time you want to assemble a program.

There are some errors in the terminal session so that you can see how to
correct errors in CMS.
1

2

cp link dosres 130 130 rr linkdos
DASD 130 LINKED RIO
Ready;
access 130 z
Z (130) RIO - DOS
Ready;
set dos on z
Ready;

1

Use the CP LINK command to link to the DOS system residence volume and the ACCESS
command to access it. In this example, the system residence is at virtual address 130 and is
accessed as the Z-disk.

2

Enter the CMS/DOS environment specifying the mode letter at which the DOS/VS (VSE/AF)
system residence is accessed.

Appendix C. Sample Terminal Session for DOS Programmers

361

3

4

xedit dostest assemble
Creating new file:
input
Input mode:
begpgm
csect
balr 12,0
using *,12
la
13,savearea
open infile,outfile
loop
get
infile
put
outfile
b
loop
eodad
equ
*
close infile,outfile
eoj
eject
CL80' ,
buffer
dc
infile
dtfdi modname=shrmod,ioarea1=buffer,devaddr=sysipt,
save#input
Input mode:
eofaddr=eodad,recsize=80
outfile dtfdi modname=shrmod,ioareal=buffer,devaddr=syspch,
save#input
Input mode:
recsize=81
shrmod
dimod typefle=output
,'t
endpgm
equ
end

*
*

3

Use the EDIT command to create a file named DOSTEST ASSEMBLE. Since the file does not
exist, the editor indicates that it is a new file and you can use the INPUT subcommand to enter
input mode and begin entering the input lines.

4

Before continuing to enter input lines, the XEDIT subcommand SAVE is issued to write what
has already been written onto disk. The logical line end symbol (#) separates the SAVE and
INPUT subcommands. Another continuation character is needed.

362

VM/SP eMS for System Programming

5

6

7

8

9

10

file
Ready;
xedit getrnacs eserv
Creating new file:
tabs 2 72
input
Input mode:
punch open,close,get,put,dimod,dtfdi
file
Ready;
assgn sysipt a
Ready;
eserv getrnacs
Ready;
listfile getmacs *
GETMACS ESERV
Al
GETMACS MACRO
Al
GETMACS LISTING Al
Ready;
maclib gen dosmac getmacs
Ready;
erase getmacs *
Ready;

5

A null line returns you to edit mode. You may want, at this point, to proofread your input file
before issuing the FILE subcommand to write the ASSEMBLE file on disk.

6

To obtain the macros you need to assemble this file, use the editor to create an ESERV file. By
setting the logical tabs at columns 2 and 72, you can protect yourself from entering data in
column 1.

7

PUNCH is an ESERV program control statement that copies and de-edits macros from source
statement libraries; in this case, the system source statement library. The output is directed to
the SYSPCH device, which the CMS/DOS ESERV EXEC assigns by default to your A-disk.

8

You must assign the logical unit SYSIPT before you invoke the ESERV command. GETMACS is
the filename of the ESERV file containing the ESERV control statements.

9

After the ESERV EXEC completes execution, you have three files. You may want to examine
the LISTING file to check the ESERV program listing. The MACRO file contains the punch
(SYSPCH) output.

10

The MACLIB command creates a macro library named DOSMAC MACLIB. Since the MACLIB
command completed successfully, you can erase the files GETMACS ESERV, GETMACS
LISTING and GETMACS MACRO; an asterisk in the filetype field of the ERASE command
indicates that all files with the filename of GETMACS should be erased.

Appendix C. Sample Terminal Session for DOS Programmers

363

11
12
13

14

15

16

global mac lib dosmac
Ready;
assemble dostest
ASSEMBLER DONE
DOS00040
4
LA
13,SAVEAREA
IF0188 SAVEAREA IS AN UNDEFINED SYMBOL
DOSOOII0
35
EOJ
IF0078 UNDEFINED OP CODE
NUMBER OF STATEMENTS FLAGGED IN THIS ASSEMBLY
Ready(00008);
xedit dotest assemble
locate /buffer/
BUFFER
DC
CL80"
input savearea ds
9d
file
Ready;
xed it eoj eserv
Creating new file:
i
punch eoj
file
.
Ready;
listio sysipt
SYSIPT DISK
A
Ready;
eserv eoj
Ready;

2

11 Before you can invoke the assembler, you have to identify the macro library that contains the
macros; use the GLOBAL command specifying DOSlvIAC MACLIB.
12 The ASSEMBLE command invokes the VM/SP assembler to assemble the source file.
13 The assembler displays errors encountered during assembly. Depending on how accurately you
copied the program in this sample session, you mayor may not receive some of these messages;
you may also have received additional messages.
14 To correct the first error, which was the omission of a DS statement for SAVEAREA, edit the
file DOSTEST ASSEMBLE and insert the missing line.
15 The second error indicates that the macro EOJ is not available since it was not copied from the
source statement library. Create another ESERV file to punch this macro.
16 Use the LISTIO command to check that SYSIPT is still assigned to your A-disk so that you do
not have to issue the ASSGN command again. Then issue the ESERV command again, this time
specifying the filename EOJ.

364

VM/SP eMS for System Programming

17

18
19
20

21

maclib add dosmac eoj
Ready;
maclib map dosmac (term
INDEX SIZE
MACRO
2
OPEN
43
CLOSE
46
43
90
GET
56
147
PUT
93
241
DIMOD
647
889
DTFDI
284
1174
EOJ
6
Ready;
erase eoj ~I:
Ready;
assemble dostest
ASSEMBLER DONE
NO STATEMENTS FLAGGED IN THIS ASSEMBLY
Ready;
listfile dostest *
DOSTEST ASSEMBLE Al
DOSTEST LISTING Al
DOSTEST TEXT
Al
Ready;
print dostest listing
Ready;
doslked dostest
Ready;

17

Use the ADD function of the MACLIB command to add the macro EOJ to DOSMAC MACLIB.
Then issue the MACLIB command again using the MAP function and the TERM option to
display a list of the macros in the library.

18

Erase the EOJ files. You should always remember to erase files that you do not need any longer.
Reassemble the program.

19

This time the assembler completes without encountering any errors. If you ASSEMBLE file still
has errors, you should use the editor to correct them.

20

Use the LIST FILE command to check for DOSTEST files. The assembler created the files
DOSTEST LISTING and DOSTEST TEXT. The TEXT file contains the object module. You can
print the program listing if you want a printer copy. Then you may want to erase it.

21

Use the DOSLKED command to link-edit the TEXT file into an executable phase and write it
into a DOSLIB. Since this program has no external references, you do not need to add any
linkage editor control statements.

Appendix C. Sample Terminal Session for DOS Programmers

365

22

23

24

25

22

listfile dostest *
DOS TEST ASSEMBLE A1
DOSTEST DOSLIB
A1
DOSTEST TEXT
A1
DOSTEST LISTING A1
DOSTEST MAP
A5
Ready;
cp spool punch to *
Ready;
punch test data a
PUN FILE 0100 TO BILBO
COPY 01 NOHOLD
Ready;
cp query reader all
Ready;
ORIGINID FILE CLASS RECDS CPY HOLD DATE TIME
NAME
PATTI
5840 A PUN 000097 01 NONE 09/29 15:00:39 TEST
assgn sysipt reader
Ready;
assgn syspch a
Ready;
dlbl outfile a cms punch output (syspch
Ready;
state punch output a
DMSSTT002E File not found.
Ready(00028);

TYPE
DATA

DIST
BIN211

Now you have a DOSTEST DOSLIB containing the link-edited phase and a MAP file containing
the linkage editor map. You can display the linkage editor map with the TYPE command or use
the PRINT command if you want a printer copy.

23 To execute this program in CMS/DOS, punch a file that _has fixed- length, 80-character records
into your virtual card punch. If you do not have any files that have fixed-length, 80-character
records, you can create a file named TEST DATA with the CMS Editor or by copying your
ASSEMBLE source file with the COPYFILE command as' follows:
copyfile dostest assemble a test data a
Use the CP SPOOL command to spool the punch to your own virtual machine, then use the
PUNCH command to punch the file. The PUN FILE message indicates that the file is in your
card reader. Use the CP QUERY command to check that it is the first or only file in your
reader.
24 Use the ASSGN command to assign SYSIPT to your card reader and SYSPCH to your A-disk.
25

366

When you assign a logical unit to a disk mode, you must issue the DLBL command to identify
the disk file to CMS. For this program execution, you are creating a CMS file named PUNCH
OUTPUT. The STATE command ensures that the file does not already exist. If it does exist,
rename it or else use another filename or filetype on the DLBL command.

VM/SP eMS for System Programming

26

27

28

global doslib dostast
Ready;
fetch dostest
DMSFET710I Phase DOSTEST entry point at location 020000.
Ready;
start
DMSLI0740I Execution begins ...
Ready;
listfile punch output a (label
FILENAME FILETYPE FM FORMAT LRECL RECS BLOCKS
DATE
TIME
PUNCH
OUTPUT
Al F
80
97
10 9/29/79 14:50:55
Ready;
cp query reader all
Ready;
NO RDR FILES
assgn sysipt a
Ready;
dlbl infile a cms punch output (sysipt
Ready;
assgn syspch punch
Ready;

LABEL
BBB191

26 Use the GLOBAL command to identify the DOSLIB, DOSTEST if you want to search for
executable phases; then issue the FETCH command specifying the phase name. The FETCH
command loads the executable phase into storage. When the FETCH command is executed
without the START option, a message is displayed indicating the entry point location of the
program loaded.
27 The START command begins program execution. The CMS ready message indicates that your
program completed successfully. You can check the input and output activity by using the
LISTFILE command to list the file PUNCH OUTPUT. If you use the CP QUERY command, you
can see that the file is no longer in your virtual card reader.
28 If you want to execute this program again, you can assign SYSIPT and SYSPCH to different
devices; in this example, the input disk file PUNCH OUTPUT is written to the virtual punch.
You do not need to reissue the GLOBAL DOSLIB command; it remains in effect until you reissue
it or IPL CMS again.

Appendix C. Sample Terminal Session for DOS Programmers

367

29
30

fetch dostest (start
DMSLI0740I Execution begins ...
PUN FILE 5829 TO BILBO
COpy 01 NOHOLD
Ready;
reud punch2 output
Ready;
listfile punch2 output a (label
FILENAME FILETYPE FM FORMAT LRECL RECS BLOCKS
PUNCH2
OUTPUT
A1 F
80
97
10
Ready;

DATE
TIME
9/29/75 14:50:59

LABEL
BBB191

29 This time the program execution starts immediately because the START option is specified on
the FETCH command.
30 Again, the PUN FILE message indicates that a file has been received in your virtual card reader.
You can use the CMS command READ CARD to read it onto disk and assign it a filename and
filetype; in this example, PUNCH2 OUTPUT.

/

368

VM/SP eMS for System Programming

n
i\ r,-,r~\ lrr-J(]ii
[li""
,I"
U.. :,. "ja

;. ,lL/~'):"'~u

C::',]rr--:lrl"":\n(-\
"U'~"(\r:--'7Infi'7l'Jn (~l\0("">"Uri\lrT':'l nJl~nfi'7l(i'~ /\(22"")'--', r\rJr",;;,~,(i'~"il
r.,)l.., UUU~)U .J-'U UUuUUUl.. U 0.:,) ..H);,.) ."I,.,;;uu ~ .....,Uuu,.J .. :l,_'~;J' ..I\" ' - U'.I ,..,II,;,:.IU'-j ..

~~)O U'\] ~ G_~~)C,)

This sample terminal session shows you how to use access method services
under eMS. You should have an understanding of VSAM and access
method services before you use this terminal session.
The terminal session uses a number of eMS files, which you may create
during the course of the terminal session; or, you may prefer to create all of
the files that you need beforehand. Within the sample terminal session, the
file that you should create is displayed prior to the commands that use it.
This terminal session is for both eMS as VSAM programmers and
eMS/DOS VSAM programmers. All entries in blue are entries you (a eMS
as VSAM programmer or a eMS/DOS VSAM programmer) should enter.
The entries in blue and shaded are only for eMS/DOS programmers.

Notes:
1.

This terminal session assumes that you have, to begin with, a read/write
eMS A-disk. This is the only disk required. Additional disks used in
this exercise are temporary disks, formatted with the Device Support
Facility program. If you have OS or DOS disks available, you should use
them, and remember to supply the proper volume and virtual device
address information, where appropriate. The number of cylinders
available to users for temporary disk space varies among installations; if
you cannot acquire ample disk space, see your system support personnel
for assistance.

2.

Output listings created by A MSER V take up disk space, so if your A-disk
does not have a lot of space on it, you may want to erase the LISTING
files created after each AMSERV step.

3.

If any of the A MSER V commands that you execute during this sample
terminal session issue a nonzero return code,· for example:
Ready(00012);
You should edit the LISTING file to examine the access method services
error messages. The publication VSE/ VSAM Messages and Codes
contains the return codes and reason codes issued by access method
services. You should determine the cause of the error, examine the DLBL
commands and AMSER V files you used, correct any errors, and retry the
command.

Appendix D. Sample Terminal Session Using Access Method Services

369

1

2

cp define t3330 200 10
Ready;
DASD 200 DEFINED
cp query virtual 200
Ready;
DASD 200 3330 (TEMP) R/W

10 CYL

cp define t3330 300 10
Ready;
DASD 300 DEFINED
cp query virtual 300
Ready;
DASD 300 3330 (TEMP) R/W

10 CYL

cp define t3330 400 10
Ready;
DASD 400 DEFINED
cp query virtual 400
Ready;
DASD 400 3330 (TEMP) R/W

10 CYL

File: PUNCH DSF
INIT UNIT(200) DEVTYP(3330) NVFY VOLID(222222) DVTOC(O,l,l)
MIMIC(MINI(10»
INIT UNIT(300) DEVTYP(3330) NVFY VOLID(333333) DVTOC(O,l,l)
MIMIC(MINI(10»
INIT UNIT(400) DEVTYP(3330) NVFY VOLID(444444) DVTOC(O,l,l)
MIMIC(MINI(10»

3

-

File: DSF EXEC

/* EXEC to Invoke Device Support Facility */
arg cntrl .
address command
'CP CLOSE READER'
'CP PURGE READER CLASS I'
'CP SPOOL PUNCH CONT TO * CLASS I'
'PUNCH IPL DSF S ( NOH'
'PUNCH' cntrl 'DSF ( NOH'
'CP SPOOL PUNCH NOCONT CLOSE'
'CP SPOOL READER CLASS I NOHOLD'
'CP IPL OOC CLEAR ATTN'

1

These commands define temporary 3330 mini disks at virtual addresses 200,300 and 400.

2

This file contains control statements for the Device Support Facility program, which initializes
disks for use by VSAM. These disks are labelled 222222, 333333 and 444444.

3

This file contains the commands necessary to use the Device Support Facility program in a
virtual machine.

370

VM/SP eMS for System Programming

4

5

exec dsf punch
NO FILES PURGED
PUN FILE nnnn TO CAMPBEL COpy 001
NOHOLD
ICK005E DEFINE INPUT DEVICE, REPLY 'DDDD,CUU' or 'CONSOLE'
ENTER INPUT/COMMAND:

6

2540,OOc
2540,00C
ICK006E DEFINE OUTPUT DEVICE, REPLY 'DDDD,CUU' or 'CONSOLE'
ENTER INPUT/COMMAND:

7

console
CONSOLE
ICKDSF - SA DEVICE SUPPORT FACILITIES 5.0 TIME20:26:00 03/09/82
INIT UNIT(200) DEVTYP(3330) NVFY VOLID(222222) DVTOC(O,l,l) MIMIC(MINI(10»
ICK00700I 200 BEING PROCESSED AS LOGICAL DEVICE = 3330
PHYSICAL DEVICE = 3330-11
ICK003D REPLY U TO ALTER VOLUME 200 CONTENTS, ELSE T
ENTER INPUT/COMMAND:

8

PAGE

1

u
U

ICK01314I VTOC IS LOCATED AT CCHH=X'OOOO 0001' AND IS
1 TRACKS.
ICK00001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0
INIT UNIT(300) DEVTYP(3330) NVFY VOLID(333333) DVTOC(O,l,l) MIMIC(MINI(10»
ICK00700I 300 BEING PROCESSED AS LOGICAL DEVICE = 3330
PHYSICAL DEVICE = 3330-11
ICK003D REPLY U TO ALTER VOLUME 300 CONTENTS, ELSE T
ENTER INPUT/COMMAND:
u
U

ICK01314I VTOC IS LOCATED AT CCHH=X'OOOO 0001' AND IS
1 TRACKS.
ICK00001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0
INIT UNIT(400) DEVTYP(3330) NVFY VOLID(444444) DVTOC(O,l,l) MIMIC(MINI(10»
ICK00700I 400 BEING PROCESSED AS LOGICAL DEVICE = 3330
PHYSICAL DEVICE = 3330-11

4

Execute the DSF EXEC, specifying that the Device Support Facility control statements
contained in the file 'PUNCH DSF' should be appended to the standalone Device Support
Facility program.

5

These messages are issued by the Device Support Facility standalone program.

6

Since the Device Support Facility control statements reside in the virtual card reader, you must
indicate to Device Support Facility the device type and the address of your virtual reader.

7

This response tells Device Support Facility to output all run time information to your virtual
machine console.

8

This response gives Device Support Facility permission to proceed with the initialization of the
disk.

Appendix D. Sample Terminal Session Using Access Method Services

371

ICK003D REPLY U TO ALTER VOLUME 400 CONTENTS, ELSE T
ENTER INPUT/COMMAND:
u
U

ICK01314I VTOC IS LOCATED AT CCHH=X'OOOO 0001' AND IS
1 TRACKS.
ICK00001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0
ICKDSF MAXIMUM STORAGE USED = 278968 BYTES (FIXED = 258120,
DYNAMIC = 020848)
ICK00002I ICKDSF PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0
cp ipl cms parm autocr
Ready;
CMS VM/SP5.0 SL 000
Ready;

9

10

cp link vseaf 350 350 rr pass=read
DASD 350 LINKED R/O; R/W BY GANDALF
access 350 z
DMSACC723I Z (350) R/O - DOS
Ready;
; set dos on z ( vsam
, Ready;

11

access 200
DMSACC723I
Ready;
access 300
DMSACC723I
Ready;
access 400
DMSACC723I
Ready;

b
B (200) R/W - DOS
c
C (300) R/W - DOS
d
D (400) R/W - DOS

-----------9

You must re-IPL CMS after all Device Support Facility processing has completed.

10 If you are a CMS/DOS user, you must access the VSE/AF SYSRES disk and issue the 'SET DOS
ON fIn (VSAM' command. If you have not previously linked to the VSE/AF SYSRES, you must
use the CP LINK command before you issue the ACCESS command. Another method is to have
the operator ATTACH the SYSRES disk to your virtual machine. Consult with your system
programmer for the procedure to use at your installation.
11 ACCESS the three newly formatted disks as your B-, C- and D-disks.

,/

372

VM/SP eMS for System Programming

12

query search
PLC191 191
222222 200
333333 300
444444 400
MNT190 190
MNT191 190
VSERES 350
Ready;

A
B
C
D
S
Y/S
Z

R/W
R/W
R/W
R/W
R/O
R/O
R/O

- DOS
- DOS
- DOS
- DOS

13

File: MASTCAT AMSERV
DEFINE MASTERCATALOG ( NAME (MASTCAT)
VOLUME (222222) CYL (4) UPDATEPW (GAZELLE) FILE (IJSYSCT) ) DATA (CYL(l))

14

assgn syscat b
Ready;
dlbl ij sysct b dsn mastcat (syscat perm extent
DMSDLB331R Enter extent specifications:
19 171

15
Ready;
16

amserv mastcat
Ready;

12 You can issue the QUERY SEARCH command to verify the status of all disks you currently
have accessed. The 350 disk will be listed only if DOS is set on.
13 The file MASTCAT AMSERV defines the VSAM master catalog that you are going to use and
provides space for suballocated clusters.
14 Identify the master catalog volume, and use the EXTENT option on the DLBL command so that
you can enter the extents. For this extent, specify 171 tracks (9 cylinders) for the master
catalog. Since 4 cylinders are specified in the AMSERV file, the remaining 5 cylinders will be
used for suballocation by VSAM.
15 You must enter a null line to indicate that you have finished entering extent information.
16 Issue the AMSERV command specifying the MASTCAT file. The ready message indicates that
the master catalog is created.

Appendix D. Sample Terminal Session Using Access Method Services

373

17

File: CLUSTER AMSERV
DEFINE CLUSTER ( NAME (BOOK. LIST ) VOLUMES (222222) TRACKS (20) KEYS (14 r 0) RECORDSIZE (120,132) ) DATA (NAME (BOOK. LIST. DATA) ) INDEX (NAME (BOOK.LIST.INDEX ) ) A

18

amserv cluster
4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOB AMSERV
gazelle
Ready;

19

File: REPRO AMSERV
REPRO INFILE (BFILE ENV ( RECORDFORMAT(F) BLOCKSIZE(120) PDEV (3330) ) ) OUTFILE (BOOK)

20

assgn sysOOl a
Ready;
copyfile test data a (recfm f lrecl 120
Ready;
sort test data a book file a
DMSSRT604R Enter sort fields:
1 14
Ready;
dlbl bfile a cms book file (sysOOl
Ready;
assgn sys002 b
Ready;
dlbl book b dsn book. list (vsam sys002
Ready;
amserv repro
Ready;

21

FILE MASTCAT

17 Define a suballocated cluster. This cluster is for a key-sequenced data set named BOOK.LIST.
18 No DLBL command is necessary when you define a suballocated cluster. Not that since the
password was not provided in the AMSERV file, access method services prompts you to enter the
password of the catalog, which is defined as GAZELLE.
19 Use the access method services REPRO command to copy a CMS data file into the cluster that
you just defined.
20 You must identify the ddnames for the input and output files for the REPRO function. BFILE is
a eMS file, which must be a fixed-length, 120-character file, and it must be sorted alphameric ally
in columns 1 through 14. The COPYFILE command can copy any existing file that you have to
the proper record format; the SORT command sorts the records on the proper fields.
21 The output file is the VSAM cluster, so you must use the VSAM option on this DLBL command.

374

VM/SP eMS for System Programming

22

23

24

25

22

File: SPACE AMSERV
DEFINE SPACE ( FILE (SPACE) TRACKS (57) VOLUME (333333)
assgn sys003 c
Ready;
dlbl space c (extent sys003
DMSDLB331R Enter extent specifications:
19 57
Ready;
amserv space
4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOB AMSERV
gazelle
Ready;
File: UNIQUE AMSERV
DEFINE CLUSTER( NAME (UNIQUE.FILE) UNIQUE ) DATA
( CYL (3) FILE (KDATA) RECORDSIZE (100 132) KEYS(12,0) VOLUMES (333333 ) ) INDEX (CYL (1)FILE (KINDEX) VOLUMES (333333)

FILE MASTCAT

Create an AMSERV file to define additional space for the master catalog on the volume labelled
333333.

23

Again, use the EXTENT option on the DLBL command so that you can enter extent information
and a null line to indicate that you have finished entering extents.

24

Issue the AMSERV command. Again, you are prompted to enter the password of the master
catalog.

25

This AMSERV file defines a unique cluster, with data and index components.

Appendix D. Sample Terminal Session Using Ac·cess Method Services

375

26

dlbl kdata c (extent sys003
DMSDLB331R Enter extent specifications:
76 57
Ready;
dlbl kindex c (extent sys003
DMSDLB331R Enter extent specifications:
76 76

27

28

Ready;
amserv unique
4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOB AMSERV
FILE MASTCAT
gazelle
Ready;
File: USERCAT AMSERV
DEFINE USERCATALOG ( CYL (8) FILE (IJSYSUC) NAME (PRIVATE.CATALOG) VOLUME (444444) UPDATEPW (UNICORN) ATTEMPTS (2) ) DATA (CYL (3)
)INDEX ( CYL (1) ) CATALOG (MASTCAT/GAZELLE
assgn sys006 d
Ready;
dlbl ij sysuc d dsn private. catalog (extent sys006 perm
DMSDLB331R Enter extent specifications:
19 152
Ready;
amserv usercat

*

Ready;

26 You must enter DLBL command and extent information for both the data and index components
of the unique cluster.
27 Next, define a private (user) catalog for the volume 444444. This catalog is named
PRIVATE.CATALOG and has a password of UNICORN. Again, as in step 13, space is made
available for suballocation.
28 When you define a user catalog that you are going to use as the job catalog for a terminal
session, you should use the ddname IJSYSUC.

/'

376

VM/SP eMS for System Programming

29

Tape 181 attached

30

File: EXPORT AMSERV
EXPORT BOOK. LIST
INFILE (BOOK) OUTFILE (TEMP ENV (PDEV (2400) REWIND NOLABEL ) )
dlbl book b dsn book list (cat ij sysct sys002
Ready;
amserv export (tapout 181
DMSAMS367R Enter tape output DDNAMEs:
temp
Ready;
File: IMPORT AMSERV

31
32

33

IMPORT

34

CATALOG (PRIVATE.CATALOG/UNICORN) INFILE (TEMP ENV (PDEV (2400) REWIND NOLABEL»
OBJECTS (BOOK.LIST VOL (444444»
amserv import (tapin 181
DMSAMS367R Enter tape input DDNAMEs:
temp
Ready;

-

29 You may want to try an EXPORT!IMPORT function, if you can obtain a scratch tape from the
operator. When the tape is attached to your virtual machine, you receive this message.
30 The file that is being exported is the cluster BOOK.LIST created above. If you do not have
access to a tape, you can export the file to you CMS A-disk. R~member to change the PDEV
parameter to reflect the appropriate device type.
31 You must reissue the DLBL for BOOK.LIST because there is a job catalog in effect, and the file
is cataloged in the master catalog. Use the CAT option to override the job catalog.
32 There is no default tape value when you are using tapes with the AMSERV command. You must
specify the TAPIN or TAP OUT option and indicate the virtual address of the tape. You are
prompted to enter the ddname, which for this file is TEMP.
33 The last AMSERV file imports the cluster BOOK.LIST to the user catalog PRIVATE.CATALOG.
34 Read the tape in as input.

Appendix D. Sample Terminal Session Using Access Method Services

377

/

378

VM/SP eMS for System Programming

Structural Changes
This book contains material formerly found in the VMjSP System
Programmer's Guide, SCI9-6203. Figure 40 on page 380 shows the Release
4 books now obsolete by this reorganization, the new system programming
books, and the topics these new books contain.
To obtain editions of the VMj SP System Programmer's Guide, you must
order using the pseudo-number assigned to the respective edition. For:
VMjSP Release 4, order STOO-1578
VMjSP Release 3, order STOO-1352
VMjSP Release 2, order SQ19-6203
VMjSP Release 1, order STI9-6203.

Summary of Changes

379

Release 4

Introduction to CP
Program States
Processor Resources
Storage Protection
Virtual Storage Preservation
'vN 110 Managemen t
Spooling Functions
CP Corrmands
Interrupt Handling
Accounting Records
Saved System. DCSSs. Shared Segs
CP Conventions
Journa ling
Suppressing Passwords
Performance
3850 MSS
Timers
CP in AP/MP Mode
Print Buffers and Forms Control
3800 Printing Subsystem

Release 5

VM/SP CP For
System
Prograrrming

VM/SP. SC24-5285
VM/SP HPO, SC23-0341

Introduct ion to CMS
Abend Processing
Interrupt Handling in CMS
Functional Information
OS Macro Simulation
VSE Support
CMS'Support for OS and VSE/VSAM
Saving CMS
CMS Batch Fac i,1 i ty
Auxi liary Directories
Assembler Virt Stor Requirements
CMS Macro Library

VM/SP CMS For
System
Prograrrming

System
Programmer's
Guide

SC24-5286

VMCF
lUCY
SNA CCS
*MSG
*BLOCKIO
*SIGNAL
Special Message Faci lity
Single Console Image Faci lity
Logical Device Support Faci lity
DIAGNOSE Instruction and Codes
Using *BLOCKIO from OMS
CMS lUCY
Prograrrmable Operator Faci lity

VM/SP, SC19-6203
VM/SP HPO, SC19-6224

VM System
Facilities
For

progra'i

VM/SP GCS
Guide

•

I

SC24-5249-1

I

SC24-5288

VM Diagnosis
Guide
{

Introduction to Debugging
Debugging the Virtual Machine
Debugging CP
Debugging CMS
Debugging GCS
Debugging Using IPCS
Using DUMPSCAN Subcommands

LY24-5241
SC24-5260-0

Figure 40.

New VM/SP System Programming Manuals for VM/SP Release
5

/

380

VM/SP eMS for System Programming

Technical Changes for VM System Facilitieo for Programming
Summary of Changes
for SC24-5286-0
for VM/SP Release 5

VM/SP Enhanced Usability
VM/SP now has the following usability enhancements:
o
o
o

window functions
full-screen environment for CMS
a CONSOLE macro.

When CMS is in full-screen mode, the user can enter commands from
anywhere on the physical screen, scroll through data, and log data into
files. The CONSOLE macro performs 3270 I/O operations.

New CMS Commands
SET TRANSLATE Command
The SET TRANSLATE command specifies whether to use the User
National Language Translation Tables and/or the System National
Language Translation Tables. This command also suppresses
translations and translation synonyms of command names for a
language.
SET LANGUAGE Command
The SET LANGUAGE command changes the current language of your
CMS session and any application running on CMS that uses national
language support.
P ARSECMD Command
The P ARSECMD command invokes the parsing facility from an
EXEC.

New CMS Macros
All new CMS macros are listed in Appendix A, "CMS Macro Library" on
page 351.

Modified CMS Commands
GLOBAL Command
The enhanced GLOBAL command· allows you to list up to 63 (formerly
8) libraries from one of the supported library types (MACLIB, TXTLIB,
DOSLIB, or LOADLIB) to be searched for macros, copy files,
subroutines,' VSE executable phrases, or OS load modules when
processing subsequent CMS commands.
TXTLIB Command
The FILENAME option of the TXTLIB command creates a directory
entry in the TXTLIB for each filename of the TEXT files specified.

Summary of Changes

381

LOAD Command
The HIST option of the LOAD command lets you add comments from
TEXT files into MODULE files.
INCLUDE Command
The HIST option of the LOAD command lets you add comments from
TEXT files into MODULE files.

Enhancements for EXECs in Storage
VM/SP now has an optional Installation Discontiguous Shared Segement
(DCSS) to contain frequently used EXECs and Editor Macros that your
installation provides. All users can access the DCSS and share the same
executing copy of the EXECs.

Enhanced Interactive Facility/System Profile
The system profile is an EXEC that performs some CMS initialization
function previously done in a module. By modifying this EXEC, the system
programmer will be able to tailor the CMS environment to suit the
installation's needs.

Parsing Facility
The CMS parsing facility parses and translat,es command name arguments.
This lets users enter commands in national languages supported by VM/SP.
These languages are: American English, KANJI, Uppercase English,
French, German.
To use the parsing facility, you must define command syntax in a special
language, the Definition Language for Command Syntax (DLCS). The
parsing facility parses a specified command by checking whether command
arguments are specified according to the DLCS definition for that
command.
Defining command syntax in a DLCS file and using the parsing facility has
the following advantages:
1. Syntax checking is unnecessary in programs.
2.

Users can invoke programs in their own national language by
modifying the DLCS file.

Creating Message Files
VM/SP now lets you store any message text in one central file. This file is
called' a respository file. Some advantages of having a repository file are:

382

•

message text will not clutter your program

•

message text can be translated to another language easily

VM/SP eMS for System Programming

Enhanced Connectivity Facilities on VM/SP
This part of CMS supports IBM Systemj370 to IBM Personal Computer
Enhanced Connectivity Facilities on a VMjSP system. For detailed
information about Enhanced Connectivity Facilities on VMjSP, refer to the
IBM VMjSP Programmer's Guide to the Server-Requester Programming
Interface for VMj SP, SC24-5291.

Miscellaneous
Most CMS messages and responses are now in mixed case.
Minor technical and editorial changes have been made throughout this
publication.

Summary of Changes for the VM/SP System Programmer's Guide
The following "Summary of Changes" reflect the changes made to the
VMj SP System Programmer's Guide, Release 4 and Release 3.
Summary of Changes
for SC19-6203-3
for VM/SP Release 4

Group Control System (VM/SP GCS)
This new component of VMjSP is a virtual machine supervisor that
provides simulated MVS services and supports a multitasking
environment. For more information on the Group Control System
(GCS), refer to the VMj SP Group Control System Guide - (Discontinued),
SC24-5249.

Signal System Service
This new CP system service allows virtual machines in a Virtual
Machine Group to signal each other. The Signal System Service can
only be used by virtual machines in a Virtual Machine Group.

Saved System 8M Byte Limit Removal
With the addition of this support, the SAVESYS, VMSAVE, and IPL
functions have been enhanced to allow a page image copy of up to a
16M byte virtual machine to be saved and restored.

CPFRETTrap
The CP FRET Trap can be used as an aid in solving problems caused by
improper use of CP storage and to solve many storage overlay problems.

Summary of Changes

383

VMDUMP Enhancements
DIAGNOSE code X'94' is available to allow a virtual machine to request
dumping of its virtual storage. Also, the three address range restriction
has been removed from the VMDUMP command.

DIAGNOSE code X'98'
Using DIAGNOSE code X'98' a virtual machine can lock and unlock
virtual pages, and execute its own real channel programs.

The Programmable Operator Facility
The Programmable Operator Facility has been enhanced to support
distributed operations in an SNA network through an interface, the
Programmable Operator/NCCF Message Exchange (PMX), with the
Network Communications Control Facility (N'CCF). The VM/SP
Release 4 programmable operator:
o

Allows an NCCF operator to be identified to the programmable
operator so that any messages intended for the logical operator may
be routed to that NCCF operator.

o

Allows an NCCF operator to issue programmable operator
commands and re,ceive responses.

o

Provides the LGLOPR command for assigning, releasing and
replacing the logical operator during operation.

CPTRAP Enhancements
CPTRAP is a major service aid used in problem determination.
Enhancements to the CPTRAP command provide two additional
functions, GROUPID and WRAP, and one additional entry type, X'3D'.
Enhancements to TRAPRED makes reviewing the trap data easier by
providing more selectivity for X'3D', X'3E', and X'3F' entries and by
providing a way to display formatted output of the trapped data.
Information on CPTRAP has been rewritten and reorganized for
ease-of-use. It has also been moved to the Part 3, the debugging section,
since it is a debugging tool.

Interactive Problem Control System (VM/SP IPCS)
VlVl/SP Release 4 has been enhanced to include IPCS as a component of
VM/SP. VM/SP IPCS is equivalent to the VM/lnteractive Problem
Control System Extension (VM/IPCS/E) Program Product (5748-SAl).

Inter-User Communications Vehicle (IUCV) Enhancements
IUCV now supports the movement of data on the SEND, RECEIVE, and
REPLY functions from discontiguous buffers. The modified IUCV
macro handles the new BUFLIST = parameter on SEND and RECEIVE

384

VM/SP eMS for System Programming

functions and the new ANSLIST = parameter on the SEND and REPLY
functions.

Expansion of User Classes
The DIRECT command has been enhanced and the OVERRIDE
command has been added to provide the user with more than the seven
IBM defined user classes. You can now choose from 32 user classes, A Z, and 1 - 6.

Remote Spooling Communications Subsystem Networking Version 2
With the release of the Remote Spooling Communications Subsystem
Networking Version 2 Program Product (5664-188), any reference to
RSCS in this manual applies to RSCS Version 2. Information
pertaining to RSCS can be found in the VM/ SP Remote Spooling
Communications Subsystem Version 2 General Information, GH24-5055.

Miscellaneous
IOCP Support Enhancements
This support adds new MSSF command words to DIAGNOSE code X'80'.

Integration of Functional Enhancements to VM/SP Release 3
Information has been added to support:
o

The 3290 Information Panel

o

The 3370 Direct Access Storage Model

o

The 4248 Printer

o

The 4361 Model Groups 3, 4, and 5 Processor

o

The 4381 Model Groups 1 and 2 Processor

o

VM/SP 3800 Model 3 Compatibility Support
Compatibility support allows VM/SP users to access the 3800 Model
3 Printing Subsystem. Existing programs designed to produce 3800
Model 1 printer output may produce output for the 3800 Model 3
printer with little or no program change. Use of this support
provides improved print quality (240 x 240 pel resolution) and the
addition of a 10 lines-per-inch (LPI) vertical space option.

DIAGNOSE code X'8C'
DIAGNOSE code X'8C' has been enhanced to allow a user to access all
of the data returned by CP's WRITE STRUCTURED FIELD QUERY.

Summary of Changes

385

DMKFRE/DMKFRT Split
The module DMKFRE has been split into two modules, DMKFRE and
DMKFRT. DMKFRE handles all requests for free storage as well as
calls to DMKFRET to rel~ase free storage. DMKFRT handles all
requests to return free storage thqt cannot be handled by the
microcoded CP assist FRET function.
Minor technical and editorial changes have been made throughout this
publication.
Summary of Changes
for SC19-6203-2
for VM/SP Release 3

Programmable Operator Facility
Several enhancements to the programmable operator facility added are:
•

Message routing with nicknames

•

Remote node availability

e

Enhanced text comparison

•

EXEC action routines

•

LOG recording and error handling

PER
Problem determination capability is greatly extended and enhanced by
the new CP command, PER.

DASD Block I/O System Service
The DASD Block I/O System Service allows a virtual machine fast,
device-independent asynchronous access to fixed size blocks on CMS
formatted virtual DASD I/O devices.

lUCY
Inter-User Communication Vehicle (IUCV) extensions provide:
•

SEND and REPLY extensions

•

An extended mask capability for control interrupts

•

An expanded trace capability to record all IUCV operations

•

A macro option to initialize the parameter list
/

•

386

Support for the DASD block I/O system service.

VM/SP eMS for System Programming

The IBM 3088 Multisystem COInmunications Unit
The IBM 3088 Multisystem Communications Unit interconnects
multiple systems using block multiplexer channels. The 3088 uses an
unshared subchannel for each unique address and is fully compatible
with existing channel-to-channel adapter protocol.

CMS IUCV Support
Support for IUCV communication has been introduced into CMS. This
support allows multiple programs within a virtual machine to use IUCV
functions. Included is the ability to initialize a CMS machine for lUCY
communication and to invoke IUCV functions via new CMS macros.
These macros also allow the user to specify path-specific exits for IUCV
external interrupts.

CMS Abend Exits
A general CMS abnormal exit capability is provided so that user
programs may specify the address of a routine to get control before
CMS abend recovery begins. An exit is established and cleared through
a new CMS macro.

Enhanced Immediate Command Support
The immediate command capability of CMS is extended by allowing
users to define their own immediate commands.

Enhanced VSAM Support
CMS supports VSE/VSAM Release 3 which includes significant
enhancements designed to improve catalog reliability and integrity
while providing additional serviceability and usability. VSE/VSAM
Release 2 is not supported.

Miscellaneous
Changes to the DIAGNOSE code X'OO' interface provide the time zone
differential from Greenwich Mean Time.
DIAGNOSE code X'8C' allows a virtual machine to access device
dependent information without having to issue a WRITE STRUCTURE
FIELD QUERY REPLY.
CMSSEG has been eliminated and the code was merged into the CMS
l':luc1eus.
The Remote Spooling Communications Subsystem (RSCS) section of this
manual has been removed as it pertained to RSCS as a component of
VM/370. Now, any reference to RSCS in this 'manual applies to the
RSCS Networking Programming Product, and information can be found
in the VM/ SP Remote Spooling Communications Subsystem Networking
Program ReferelPce and Operations Manual, SH24-5005.

Summary of Changes

387

A newly added appendix lists and describes the eMS macros applicable
to VM/SP.
Minor technical and editorial changes have been made throughout this
publication.

388

VM/SP eMS for System Programming

can appreciably expand the capabilities of
this component in a VM/SP system by
installing RSCS Networking Version 2
(5664-188).

Abbreviations
Some of the following terms and abbreviations are
used throughout this publication for convenience:

VSE

Unless otherwise noted,
VM/SP refers to the VM/SP program package when
y~¥ use it in conjunction with VM/370
Release 6.
CP

refers to the VM/370 Control Program
component enhanced by the functions
included in the VM/SP package.

CMS refers to the VM/370 Conversational Monitor
System component enhanced by the functions
included in the VM/SP package.
GCS

refers to the Group Control System
component of VM/SP. See the Group Control
System Command and Macro Reference,
SC24-5250, for details of GCS.

IPCS refers to the VM/370 Interactive Problem
Control System component enhanced by the
functions included in the VM/SP package.
The IPCS component of VM/SP replaces the
unmodified VM/370 interactive problem
control system. Details describing this
component are found in the VM Diagnosis
Guide, LY24-5241.
RSCS unless otherwise noted, refers to the RSCS
Networking Version 2 Program Product
(5664-188).
When you install and use VM/SP in
conjunction with the VM/370 Release 6
System Control Program (SCP), it becomes a
functional operating system that provides
extended features to the Control Program
(CP) and Conversational Monitor System
(CMS) components of VM/370 Release 6.
VM/SP adds no additional functions to the
Remote Spooling Communications Subsystem
(RSCS) component of VM/370. However, you

refers to the combination of the DOS/VSE
system control program and the
VSE/Advanced Functions Program Product.
"DOS", in certain cases, is still used as a
generic term. For example, disk packs
initialized for use with VSE or any
predecessor DOS or DOS/V~E system may be
referred to as DOS disks.

CMS/DOS refers to the DOS-like simulation
environment provided under the eMS
component of the VM/SP.
EXEC refers to EXECs using the System Product
Interpreter (REXX), EXEC 2, or CMS EXEC
languages.
System/370 applies to the 4300 and 303X series of
processors.
The following terms in this publication refer to the
indicated support devices:
3066

refers to the IBM 3066 System Console.

3088

refers to the IBM 3088 Multisystem
Communications Unit (MCU) Models 1 and
2.

3262

refers to the IBM 3262 Printer, Models 1, 5,
and 11. 3262 Models 3 and 13 are supported
remotely as 3287 printers.

3270

refers to a series of display devices, namely,
the IBM 3275, 3276 (referred to as a
Controller Display Station), 3277, 3278, and
3279 Display Stations, and the 3290
Information Panel. A specific device type is
used only when a distinction is required
between device types.
Information about display terminal use also
applies to the IBM 3138, 3148, and 3158
Display Consoles when used in display mode,
unless otherwise noted.

Glossary of Terms and Abbreviations

389

3285

or 3286 printer references also pertain to the
IBM 3287, 3288, and 3289 printers, unless
otherwise noted.

3330

refers to the IBM 3330 Disk Storage, Models
1,2, or 11; the IBM 3333 Disk Storage and
Control, Models 1 or 11; and the 3350 Direct
Access Storage operating in 3330
compatibility mode.

3480

refers to the IBM 3480 Magnetic Tape
Subsystem.

3430

refers to the IBM 3430 Magnetic Tape
Subsystem.

3800

refers to the IBM 3800 Printing Subsystems,
Models 1, 3, and 8. A specific device type is
used only when a distinction is required
between device types. References to the 3800
Model 3 apply to both Models 3 and 8 unless
otherwise explicitly stated. The IBM 3800
Model 8 is available only in selected world
trade countries.

3340

refers to the IBM 3340 Direct Access Storage
Facility and the 3344 Direct Access Storage.

3350

refers to the IBM 3350 Direct Access Storage
Device when used in native mode.
4245

refers to the IBM 4245 Line Printer.

3370

refers to the IBM 3370 Direct Access Storage
Model.

4248

refers to the IBM 4248 Printer.

3375

refers to the IBM 3375 Direct Access Device.

4250

refers to the IBM 4250 Printer.

3380

refers to the IBM 3380 Direct Access
Storage. The Speed Matching Buffer Feature
(No. 6550) for the 3380 supports the use of
extended count-key-data channel programs.

4361

refers to the IBM 4361 Model Groups 3, 4,
and 5 Processor.

4381

refers to the IBM 4381 Model Groups 1 and 2
Processor.

3422

refers to IBM 3422 Magnetic Tape
Subsystem.

390

VM/SP eMS for System Programming

Glossary

CMS commands. The CMS system disk can have
extensions, usually the Y-disk.

This glossary defines new terms and all-capital
abbreviations related to the VM/SP. This glossary
is especially oriented for readers of the VM/ SP
eMS for System Programming. Therefore, some
terms already defined in the VM/SP Library Guide,
Glossary, and Master Index, SC19-6207, do not
appear here or may be defined slightly differently.
Another glossary you may refer to is the IBM
Vocabulary for Data Processing,
Telecommunications, and Office Systems.

Count-Key-Data. Those DASD devices whose
architecture defines variable size records consisting
of count, key, and data fields.
CSW. channel status word

DAT. dynamic address translation.
DCSS. discontiguous shared segments.
auxiliary storage. Data storage other than main
storage; in VM/SP, auxiliary storage is usually a
direct access device.

CAW. channel address word
CCW. channel command word
channel address word (CAW). An area in storage
that specifies the location in main storage at which
a channel program begins.
channel command word (CCW). A double word at
the location in main storage specified by the
channel address word. One or more CCWs make up
the channel program that directs data channel
operations.
channel status word (CSW). An area in storage
that proyides information about the termination of
input/output operations.
Channel-to-Channel Adapter. A hardware device
that can be used to connect two channels on the
same computing system or on different systems.

deadline priority. An algorithm for determining
when a virtual machine receives the next time slice.
directory. For VM/SP, a CP disk file that defines
each virtual machine's normal configuration: the
userid, password, normal and maximum allowable
virtual storage, CP command privilege class or
classes allowed, dispatching priority, logical editing
symbols to be used, account number, and CP options
desired.
discontiguous shared segments (DCSS).
Synonymous with discontiguous segment.
discontiguous segment. A 64K segment of
storage that was previously loaded and saved and
assigned a unique name. The segment(s) can be
shared among virtual machines if the segment(s)
contain reentrant code.
DPA. dynamic paging area

dynamic address translation. In System/370
virtual storage systems, the change of a virtual
address to a real storage address during execution
of an instruction.
dynamic paging area (DPA). An area of real
storage that CP uses for virtual machine pages and
pageable CP modules.

CKD. Count-Key-Data
concurrently. Concerning a mode of operation
that includes the performance of two or more
operations within a given interval of time.
CMS system disk. The virtual disk (S-disk) that
contains the CMS nucleus and the disk-resident

FBA. Fixed-block architecture.
file status table (FST). A table that describes the
attributes of a file on a CMS disk, including
filename, filetype, filemode, date last written, and
other status information.

Glossary of Terms and Abbreviations

391

Fixed-Block Architecture (FBA). Those DASD
devices whose architecture uses fixed blocks or
records of 512 bytes.
FST. file status table

GCS. Group Control System facility

minidisk. Synonym for virtual disk.
missing interrupt handler (MIH). A facility of
VM/SP that detects incomplete I/O conditions by
monitoring I/O activity. It also tries to correct
incomplete I/O conditions without operator
intervention.

Group Control System. An operating
envi'ronment that provides a problem state OS
subtasking environment with common storage
access for members of a virtual machine group.
guest virtual machine. A virtual machine in
which an operating system is running.

named system. A collection of saved pages a user
can IPL or load by name.
native mode. A mode in which an operating
system is run stand-alone on the real machine
instead of under VM/SP.

in-queue virtual machines. A virtual machine on
the run list waiting to be dispatched. A virtual
machine is added to the run list if its projected
working set size is less than or equal to the number
of real page frames available for allocation in the
dynamic paging area. An in-queue virtual machine
may be, but is not necessarily, runnable.
interactive. (1) An application in which each user
entry calls forth a response from a system or
program. (2) The classification given to a virtual
machine depending on this virtual machine's
processing characteristics. When a virtual machine
uses less than its allocated time slice because of
terminal I/O, the virtual machine is classified as
being interactive. See also non-interactive.
Interactive Problem Control System (IPCS or
VM/SP IPCS). A component of VM/SP that
permits on-line problem management, interactive
problem diagnosis, on-line debugging for
disk-related CP or virtual machine abend dumps,
problem tracking, and problem reporting.

noninteractive. The classification given to a
virtual machine depending on this virtual machine's
processing characteristics. When a virtual machine
usually uses all its allocated time slice, it is
classified as being noninteractive or compute bound.
See also interactive.
non-resident pages. Pages whose contents are on
DASD but not in real storage. A page is considered
nonresident when an attempt to load its real address
returns a nonzero condition code.

I;l

L:J

page frame. A block of 4096 bytes of real storage.
page table. A table in CP that indicates whether a
page is in real storage and matches virtual
addresses with real storage addresses.
preferred paging area. A special area of auxiliary
storage where frequently used pages are paged out.
It provides high speed paging.
prefix storage area (PSA). a page zero of real
storage that contains machine-used data areas and
CP global data.

logon. The procedure by which a user begins a
terminal session.
logoff. The procedure by which a user ends a
terminal session.

392

VM/SP CMS for System Programming

program status word (PSW). An area in storage
used to indicate the order in which instructions are
executed, and to hold and indicate the status of the

computer system. Synonymous with processor
status word.

segments. Each entry indicates the length, location,
and availability of a corresponding page table.

program temporary fix (PTF). A temporary
solution or by-pass of a problem diagnosed by IBM
field engineering as the result of a defect in a
current unaltered release of the program.

shadow page table. A table that maps real
storage allocations (first level storage) to a virtual
machine's virtual storage (third level storage) for
use by the real machine in its paging operations.

PSA. Prefix storage area.

spool, spooled, spooling. Relates to the reading
of input data streams and the writing of output data
streams on auxiliary storage devices.

PSW. Program status word, or processor status
word.
PTF. Program temporary fix.

queue-add. The action by the system scheduler,
DMKSCH, of placing a runnable virtual machine on
the list of virtual machines that can be given
control of a processor.
queue-drop. The action by the system scheduler,
DMKSCH, of removing a virtual machine from the
list of virtual machines that can be given control of
a processor.

standalone dump. A program used to print the
contents of storage that runs in a virtual machine
not under control of an operating system such as
CMS.
system profile. The system profile is an EXEC,
SYSPROF EXEC, that resides in a DCSS
(discontiguous saved segment) or on a system disk
and is called by CMS initialization. It contains
some initialization function and provides a means
for installations to override the default CMS
environment by tailoring the EXEC to suit the
installation.

time sharing. Sharing of computer time and
resources.
real machine. The actual processor, channels,
storage, and I/O devices required for operation of
VM/SP.
virtual address. An address that refers to virtual
storage or a virtual I/O device address. It must,
therefore, be translated into a real storage or I/O
device address when it is used.
S-disk. See CMS system disk.
S-STAT. A block of storage that contains the file
status tables (FSTs) associated with the S-disk. The
FSTs are sorted so that a binary search can be used
to search for files. The S-STAT usually resides in
the CMS nucleus so it can be shared. Only files
with filemode of 2 will have their associated FSTs
in the S-STAT.
segment. A contiguous 64K area of virtual storage
(not necessarily contiguous in real storage) that is
allocated to virtual m~chine or CPo
segment table. A table used in dynamic address
translation to control user access to virtual storage

virtual disk. A logical subdivision (or all) of a
physical disk storage device that has its own
address, consecutive storage space for data, and an
index or description of the stored data so that the
data can be accessed. A virtual disk is also called a
minidisk.
virtual machine. A functional simulation of a
computer and its associated devices.
Virtual Machine Communication Facility
(VMCF). A CP function that provides a method of
communication and data transfer between virtual
machines operating under the same VM/SP systems:

Glossary of Terms and Abbreviations

393

virtual storage. Storage space that can be
regarded as addressable main storage by the user of
a computer system in which virtual addresses are
mapped into real addresses. The size of virtual
storage is limited by the addressing scheme of the
computing system and by the amount of auxiliary
storage available, and not by the actual number of
main storage locations.

Y -disk. An extension of the eMS system disk.
Y-STAT. A block of storage that contains the file

status tables (FSTs) associated with the V-disk. The
FSTs are sorted so that a binary search can be used
to search for files. The Y-STAT usually resides in
the eMS nucleus so it can be shared. Only files
with filemode of 2 will have their associated FSTs
in the Y-STAT.

/

394

VM/SP eMS for System Programming

Here is a list of IBM books that can help you use your system. If you don't see
the book you want in this list, you might want to check the IBM System/370, 30xx,
and 4300 Processors Bibliography, GC20-0001.

o

Prerequisite Publications

IBM System/360 Principles of Operation, GA22-6821
IBM System/370 Principles of Operation, GA22-7000.
Q

Books About VM/SP

Virtual Machine/System Product:
CP for System Programming, SC24-5285
Transparent Services Access Facility Reference, SC24-5287
General Information, GC20-1838
Introduction, GC19-6200
CMS Command Reference, SC19-6209
CMS User's Guide, SC19-6210
Installation Guide, SC24-5237
System Messages and Codes, SC19-6204
OLTSEP and Error Recording Guide, SC19-6205
Terminal Reference, SC19-6206
Library Guide, Glossary, and Master Index, SC19-6207
Operator's Guide, SC19-6202
EXEC 2 Reference, SC24-5219
System Product Editor User's Guide, SC24-5220
System Product Editor Command and Macro Reference, SC24-5221
System Product Interpreter User's Guide, SC24-5238
System Product Interpreter Reference, SC24-5239
Virtual Machine

System Facilities for Programming, SC24-5288
Bibliography

395

Diagnosis Guide, LY24-5241
Running Guest Operating Systems, 8C19-6212
Note: The V1'.l/SP Library Guide, Glossary, and Master Index, GC19-6207
describes all the VM/8P books and contains an e~panded glossary and
master index to all the books in the VM/8P library.

•

Other Publications

IBM VM/SP Programmer's Guide to the Server-Requester Programming
Interface for VM/ SP, 8C24-5291
IBM 3211 Printer, 3216 Interchangeable Train Cartridge, and 3811 Printer
Control Unit Component Description and Operator's Guide, GA24-3543
IBM 3262 Printers 1 and 11 Component Description, GA24-3733
IBM 3270 Information Display System Library User's Guide, GA23-0058
IBM Virtual Machine Facility/B70: Performance/Monitor Analysis
Program,8B21-2101
ACF/VTAM

VTAM General Information (for VM), GC30-3246
Network Program Products Planning, 8C23-0110
VTAM Installation and Resource Definition, 8C23-0111
VTAM Customization, 8C23-0112
VTAM Operation, 8C23-0113.
VM/8P Remote 8pooling Communications 8ubsystem Networking (R8C8
Networking) Version 2

Planning and Installation, 8H24-5057
Operation and Use, 8H24-5058
Diagnosis Reference, L Y24-5228
VM/SP Data Areas and Control Block Logic,
Volume 2 Conversational Monitor System (CMS), LY24-5221
VM/ SP System Logic and Problem Determination,
Volume 2 Conversational Monitor System (CMS), L Y20-0893
OS/ VS Data Management Macro Instructions, GC26-3793
OS/VS Supervisor Service and Macro Instructions,GC27-6979
If you use the IBM 3767 Communication Terminal as a virtual machine console,

the IBM 3767 Operator's Guide, GA18-2000 may also be helpful.

396

VM/8P eM8 for 8ystem Programming

Note: References in text to titles of corequisite VMjSP Entry and VM/SP
publications are given in abbreviated form.

Bibliography

397

The VM/SP Library (Part 1 of 3)

Evaluation

Index

Z

'/

/'

General
Information

GC20-1838

Introduction

V

GC19-6200

Library
Guide,
Glossary, and
Master Index
GC19-6207

V

Installation

Planning
'/

/'

Planning
Guide and
Reference

SC19-6201

Running
Guest
Operating
Systems

V

/'

/'

GC19-6212

Distributed
Data
Processing
Guide

Release 5
Guide

I

SC24-5290

/'

~

SC24-5241

Installation
Guide

SC24-5237

I

/'

'/

Application
Development
Guide

SC24-5247

/'

Operator's
Guide

Programmer's
Guide to the
SRPI
for VM/SP
I

I

Operation

Applications

SC24-5291

SC19-6202

I

Reference Summaries

398

V

V

To order all of the Reference Summaries. use order number SBOF-3242

Commands
(General User)

Commands
(Other than
General User)

SP Editor
Command
Reference
Summary

EXEC 2
Reference
Summary

Sys.Prod
Interpreter
Reference
Summary

SX20-4401

SX20-4402

SX24-5122

SX24-5124

SX24-5126

CMS Primer
Summary of
Commands

CMS Primer
Line-Oriented
Summary of
Commands

Problem
Reporting
Summary
(Poster)

Summary of
End Use
Tasks and
Commands
(Poster)

SX24-5151

SX24-5159

VM/SP eMS for System Programming

SX24-5171
SX24-5173

,/

Tho "r~~/slP library (IPQr~ 2 of 3)

End Use
'/

/'

Terminal
Reference

GC19-6206

SC24-5236

V

/'

System
Product
Editor
Command and
Macro
Reference
SC24-5221

SC24-5220

V

/'

CMS Primer
for LineOriented
Terminals
SC24-5242

I

/'

System
Product
Editor
User's Guide

'/'

/'

CMS
Primer

CMS
User's
Guide

SC19-6210

V

'/

SC24-5238

I

SC19-6209

I

System
Product
Interpreter
Reference
SC24-5239

V

CMS
Macros and
Functions
Reference
SC24-5284

I

L

'/

System
Product
Interpreter
User's Guide

/'

CMS
Command
Reference

I

'/

CP
Command
Reference

EXEC 2
Reference

SC24-5219

V

SC19-6211

V

V

'/

Quick
Reference

SX20-4400

I

Diagnosis
/'

/'

System
Messages
and Codes

SC19-6204

II

L

SC24-5264

Service
Routines
Program
Logic

V

/'

Problem
Determination
Vol. 1 (CP)

LY20-0892

/

LY24-5220

LY20-0890

Problem
Reporting
Guide

I

'/

Data Areas
and Control
Blocks
Vol. 1 (CP)

LY20-0893

SC24-5282

LY24-5221

LY24-5241

V

GCS
Diagnosis
Reference

V

LY24-5239

V

/'

Data Areas
and Control
Blocks
Vol. 2 (CMS)

V

/'

VM
Diagnosis
Guide

/'

Problem
Determination
Vol. 2 (CMS)

IJ

'/

/'

/'

System
Messages
CrossReference

OLTSEP
and Error
Recording
Guide

IJ

SC19-6205

VM
Problem
Determination
Reference
Information
LX23-0347
I

VM
CP Internal
Trace Table
(Poster)

LX24-5202

Bibliography

399

The Vrtll!SP Llbrsry (Psrt 3 of 3)

Administration
/'

~

VM
System
Facilities
for
Programming

/'

CP for
System
Programming

SC24-5288

SC24-5285

I

SC24-5286

I

'/

/'

CMS for
System
Programming

GCS
Command
and Macro
Reference

TSAF
Reference

SC24-5287

V

V

SC24-5250

I

Auxiliary Communication Support
~

/'

/'

/'

VTAM
Installation
and Resource
Definition

VTAM
Customization

VTAM
Operation

VTAM
Messages
and Codes

SC23-0111

SC23-0112

SC23-0113

SC23-0114

VTAM
Reference
Summary
SC23-0135

I

/'

V

"/

SC23-0115

V

/'

SC23-0116

/'

RSCS
Noh-/orking
Version 2
General
Information

RSCS
Networking
Version 2
Planning and
Installation

GH24-5055 V

SH24-5057

VM/PassThrough
Facility
General
Information

VM/PassThrough
Facility
Guide and
Reference

VTAM
Data
Areas (VM)

VTAM
Diagnosis
Reference

V

LY30-5582

I

"/

"/

VTAM
Diagnosis
Guide

VTAM
Programming

V

V

LY30-5583

V

"/

/'

RSCS
Networking
Version 2
Operation
and Use

RSCS
Networking
Version 2
Ref. Summary

RSCS
Networking
Version 2
Diagnosis
Reference

SX24-5135
I

"/

SH24-5058

V

LY24-5228

I

/'

GC24-5206 V

SC24-5208 ..rl

,L..-_ _ _ _

VM/PassThrough
Facility
Logic
LY24-5208

,1--_ _ _ _

-11
,/

400

VM/SP eMS for System Programming

ISpecial Characters I
+ and - subcommands of DUMPS CAN command
See DIAG
&name subcommand of DUMPS CAN command
See DIAG
$$BCLOSE transient 268
$$BDUMP transient 268
$$BOPEN transient 268
$$BOPENR transient 268
$$BOPNLB transient 268
$$BOPNR2 transient 268
$$BOPNR3 transient 268
$$BOSVLT transient 269
$LISTIO EXEC file 217
*BLOCKIO (DASD Block I/O System Service)
See SFPROG
*CCS (SNA Console Communication Services)
See SFPROG
*LOGREC (Error Logging System Service)
See SFPROG
*MSG (Message System Service)
See SFPROG
*MSGALL (Message All System Service)
See SFPROG
*NCCF
See SFPROG
*SIGNAL (Signal System Service)
See SFPROG
*SPL (Spool System Service
See SFPROG
/ / record 176, 231
/JOB control cards 335
? subcommand of DUMPSCAN command
See DIAG

abend (abnormal termination)
clearing file definitions 166
CMS abend
exit routine processing, CMS
processing 5
recovery 6
DMSABW CSECT 5
information available 5

5

releasing storage 26
ABEND macro
See DIAG
ABEND macro (SVC 13) 193
abend messages
See DIAG
abend recovery process 6
abend, reason for
See DIAG
ABENDs
See also DIAG
CMS abend
exit routine processing, CMS 5
processing 5
recovery 6
ABNEXIT macro 5, 351
abnormal termination (abend)
See abend (abnormal termination)
abnormal termination procedures
See DIAG
ACCEPT, IUCV and logical device support facility
See SFPROG
ACCESS command
accessing OS data sets 161
format of 162
modules included in resident directory 339
response when you access VSAM disks 278
used with OS disks 159
access device dependent information DIAGNOSE
code X'8C'
See SFPROG
access diagnostic information saved for protected
application facility users DIAGNOSE code X'BO'
See SFPROG
access method services (AMS)
control statements, executing 276
DEFINE CLUSTER statement 305
DEFINE control statement 305
DEFINE USERCATALOG 287
defining a master catalog 286
defining OS input/output files 294
DELETE control statement 305
executing in CMS, examples 304
functions
EXPORT 307
IMPORT 307
REPRO 307
in CMS 273
in CMS/DOS 284
restrictions on using for OS and VSE users 274

These symbols are used in the index to refer to other VM and VM/SP books:
...
.
CPPROG-VM/SP CP for System Programming
SFPROG-VM System FaclhtIes for Programmmg
DIAG-VM Diagnosis Guide
Index 401

return codes 277
terminal sessions 369
using tape input/output 292, 303
access method supported by OS 199
accessing
access method services 276
directories of VSE libraries 224
DOS disks 211
OS disks 159
VSE system residence volume 208
accounting
See CPPROG
ACF/VTAM, VM/SP SNA support
See SFPROG·
action routines
See SFPROG
ACTION, VSE linkage editor control
statement 241
activating the TOD-clock accounting interface
DIAGNOSE code X'70'
See SFPROG
active disk table (ADT) 341
signalling preferred filetypes 3
ADDENTRY macro 351
adding
language information for an application
See SFPROG
member to MACLIBs 173,228
ADSTOP command
See DIAG
ADT (active disk table) 341
signalling preferred filetypes 3
ALL subcommand of TRAPRED command
See DIAG
allocating 27
extents on OS disks 295
space for VSAM files (CMS/DOS) 290
space for VSAM files (OS) 300
storage 32
VSAM extents on OS disks and minidisks 295
alter contents of storage
See DIAG
altering storage contents
See DIAG
alternate userid DIAGNOSE code X'D4'
See SFPROG
AMS (access method services)
control statements, executing 276
DEFINE CLUSTER statement 305
DEFINE control statement 305
DEFINE USERCATALOG 287
defining a master catalog 286
defining OS input/output files 294
DELETE control statement 305
executing in CMS, examples 304
functions
EXPORT 307
IMPORT 307
REPRO 307
in CMS 273

402

VM/SP CMS for System Programming

in CMS/DOS 284
restrictions on using for OS and VSE users 274
return codes 277
terminal sessions 369
using tape input/output 292, 303
AMSERV command
creating tape files 303
files, examples 276
filetype 276
format of 276
functions under CMS 304
output listings 277
using to read tapes 303
APAR command
See DIAG
APARs (Authorized Program Analysis Reports)
See DIAG
APPC/VM synchronous event (type X'DC') entry
See DIAG
appending data to existing files 166
APPLMSG macro 351
AREGS subcommand of DUMPSCAN command
See DIAG
ARIOBLOK subcommand of DUMPSCAN command
See DIAG
ASSEMBLE command
example of 66
output files produced 239
assembler language macros
supported by VSE 236
assembler programs
OS programs in CMS 65
overriding default definitions using ddnames 65
programs in CMS/DOS 238
source files, from OS disks 65
VSAM programs in CMS 274
assembler virtual storage
requirements 345
ASSGN command
assigning programmer logical unit 214
description 209
using to assign logical units 214
assigning
disk devices 218
entering before program execution 245
physical devices 218
to a virtual device 218
ATTACH macro (SVC 42) 195
attached processor mode (AP)
See CPPROG
AUTHORIZE VMCF function
See SFPROG
auxiliary directories
adding 339
creating 340
DMSLADAD entry point 341
establishing linkage 341
GENDIRT command 340
generating 339

initializing 340
saving resources 339
usage 339
auxiliary files
description of 104
preferred 108
auxiliary processing routine to receive control
during I/O operation 167
AUXPROC option of FILEDEF command 167

batch facility
/JOB control cards 335
BATEXIT1 routine 335
BATEXIT2 routine 335
BATLIMIT MACRO file 335
data security 336
description 333
EXEC procedures 336
installation input 335
installing 334
IPL performance 336
resetting system limits 334
system limits 334
user-specified control language 335
BATEXIT1 routine 335
BATEXIT2 routine 335
BATLIMIT macro 335,351
BDAM
restrictions on 202
support of 188, 200
BEGIN command
See DIAG
BLDL macro (SVC 18) 193
BLIP character 13
BLKSIZE (blocksize)
512, 1024, 2048, 4096 bytes 2
800 bytes 2
BLOCK option of FILEDEF command 165
*BLOCKIO
See SFPROG
blocksize (BLKSIZE)
See BLKSIZE (blocksize)
books copied from DOS/VSE source statement
libraries 220
BOTTOM subcommand of TRAPRED command
See DIAG
BPAM
support of 188, 200
branch entry Freemain (type X'OB') entry
See DIAG
branch entry Getmain (type X'OA') entry
See DIAG
breakpoint setting
See DIAG

BSAM/QSAM
support of 188, 200
BSP macro (SVC 69) 198
buffers used by FSCB 78
BUFSP option
in CMS/DOS 285
of the DLBL command

295

C subcommand of DUMPS CAN command
See DIAG
calculating storage available in your virtual
machine 246
CALL command 237
CALL macro 198
calling IBM for assistance, data needed
See DIAG
CANCEL command 237
CANCEL VMCF function
See SFPROG
canceling
DLBL definitions 220
user-written immediate commands 155
CAT option 285
of the DLBL command 295
catalogs
clearing 289
defining in CMS/DOS 286
identifying in CMS/DOS 287
IJSUC ddname 288
job 288, 299
master 297
passwords 289, 299
sharing 279
user 298
user in CMS/DOS 287
verifying a structure 289, 300
VSAM 285, 289, 296
catalogued procedures in OS equivalent in
CMS 158
CATCHECK command
verifying a catalog structure 289, 300
*CCS
See SFPROG
CHAIN subcommand of DUMPSCAN command
See DIAG
changes, summary of 379
channel program modification DIAGNOSE code
X'28'
See SFPROG
CHAP macro (SVC 44) 195
CHECK macro 198
CHKPT macro (SVC 63) 197
class override file

These symbols are used in the index to refer to other VM and VM/SP books:
CPPROG-VM/SP CP for System Programming
SFPROG-VM System Facilities for Programming
DIAG-VM Diagnosis Guide
Index 403

See CPPROG
classes of user privilege
See CPPROG
clean-up after virtual IPL by device DIAGNOSE
code X'40'
See SFPROG
clear error recording DIAGNOSE code X'lC'
See SFPROG
clearing
DLBL definitions 220
effect on FILEDEF definitions 166
FILEDEF definitions 166
job catalogs in CMS/DOS 289
job catalogs in OS 299
CLOSE function for SPOOL system service
See SFPROG
.
CLOSE/TCLOSE macro (SVC 20/23) 194
closing
CMS files after reading or writing 81
virtual unit record devices 85
clusters
defining 305, 306
deleting 306
suballocated 305
unique 306
. CMD command used by programmable operator
See SFPROG
CMD option of the PER command
See DIAG
CMS (Conversational Monitor System)
See also Conversational Monitor System (CMS)
abnormal termination
exit routine processing 5
processing 5
recovery 6
batch facility 333
called routine modifications to system area 62
command language 1
command processing 56
command search function 58
commands
ACCESS 161
GENDIRT 340
IPL 323
OS program development 4
used with OS data sets 159
VSE program development 4
description of . 1
devices supported 21
DEVTAB (device table) 21
DISPW macro 93
DMSNUC 21
EXECs
opening and closing files 81
to execute OS programs 73
file system 2
filemode 2
filename 2
filetype 2
free storage management 23

404

VM/SP CMS for System Programming

function of 1
how to save it 3~1
initialization 322
interface with display terminals 88
interrupt handling 9
introduction 1
loader tables 16
macros
ABNEXIT 5
DISPW 93
DMSEXS 41
DMSFREE 15, 27
DMSFRES 35
DMSFRET 33
DMSFST 339
DMSKEY 39
examples 84
FS.CB 75
GETMAIN 16
list of 351
STRINIT 24
usage· 75
managing files 2
modules
DMSABN 5
DMSINA 54
DMSINT 55
DMSIOW 11
DMSITE 13
DMSITI 10
DMSITP 13
DMSITS 9,43
DMSLAD 341
DMSPAGE 34
nucleus 16
OS simulation 157
OS support 273
overlay structures 345
program development 3
PSW keys 39
register restoration 62
register usage 43
returning to called routine 61
saved system restrictions 321
simulation of VSE functions 249
storage
DMSEXS macro 41
DMSFREEmacro 15
DMSFRES macro· 35
DMSFRET macro 33
DMSKEY macro 39
map 17
STRINIT macro 24
structure 15
using 15
SUB COM func'tion 59
support for OS 273
support for VSAM 273
SVC handling 43

/

symbol references 21
system save area modification 62
tape volume switching 204
transient area 15
transient program area 23
user program area 23
USERSECT (user area) 21
using as compilers 4
using as data sets 159
using VSE compilers 4
VSAM support 273
VSE macros 250
VSE simulation 207
what it provides 1
XEDIT 2
CMS abend dump reading
See DIAG
CMS abend recovery function
See DIAG
CMS control block relationship
SeerDIAG
CMS d~bugging
See DIAG
CMS dump file printing
See DIAG
eMS IUCV
See SFPROG
CMS loader, controlling 68
CMS subcommand of DUMPS CAN command
See DIAG
CMS/DOS
commands 209
considerations for execution 272
control blocks simulated by 269
DOSLKED command 240
DTFCD macro 259
DTFCN macro 261
DTFDI macro 261
DTFMT macro 262
DTFPR macro 264
DTFSD macro 265
entering the environment 208
EXCP support 269
extents 291
generating 270
invoking linkage editor 240
libraries 270
library volume directory entries 271
options
BUFSP 285
CAT 285
EXTENT 285
MULT 285
VSAM 285
performance 272
physical IOCS macros 250
program development using 207
relationship to CMS and VSE 207

restrictions 272
SVC support routines 250
terminology 207
user responsibilities 270
using tape input/output 292
VM/SP directory entries 271
VSE I/O macros 249
VSE supervisor macros 249
VSE transients simulation 268
VSE volumes needed 271
VSE/VSAM macros supported 311
CMSDEV macro 351
CMSIUCV macro 351
See also SFPROG
CMSLEVEL macro 351
CMSLIB MACLIB 180
CMSPOINT subcommand of DUMPS CAN command
See DIAG
Goding conventions
See CPPROG
collecting CP data
See DIAG
collecting virtual machine data
See DIAG
command access in CP
See CPPROG
command language, CMS 1
command syntax files, updating
See SFPROG
commands
ACCESS 159
AMSERV 276
ASSEMBLE 65
ASSGN 209
CALL 237
CANCEL 237
CMS/DOS 209
DDR 159
developing 113
DLBL 159
DLBL command 209
DOSLIB 209
DOSLKED 209
DOSPLI 209
DSERV 209
entered from a terminal 55
ESERV 209,223
FCOBOL 209
FETCH 209
FILEDEF 159
GENMOD 209
GLOBAL 209
IPL 323
LISTDS 159
LISTIO 209
LKED 159
LOADMOD 209
MOVEFILE 159

These symbols are used in the index to refer to other VM and VMjSP books:
CPPROG-VMjSP CP for System Programming
SFPROG-VM System Facilities for Programming
DIAG-VM Diagnosis Guide
Index 405

OPTION 209
processing 54, 56
PSERV 209, 222
QUERY 210
RELEASE 159
RSERV 210, 222
SAVEFD 328
search function 58
search hierarchy for 54
SET 210
SSERV 210, 221
STATE 159
COMMENT statement 98
compilers
devices assigned 216
input/output assignments 216
compressing
DOSLIB files 243
members of a MACLIB 174,229
COMPSWT macro 351
configuration file for GCS
See DIAG
CONNECT IUCV function
See SFPROG
connection complete external interrupt in IUCV
See SFPROG
connection pending external interrupt in IUCV
See SFPROG
connection quiesced external interrupt in IUCV
See SFPROG
connection resumed external interrupt in IUCV
See SFPROG
connection severed external interrupt in IUCV
See SFPROG
console facility 88
CONSOLE function
I/O interrupts 10
CONSOLE macro 12, 88, 90, 351
control blocks
simulated by CMS/DOS 269
types
VSE supervisor 269
used by CMS/DOS routines 269
control file
description 103
for a national language
See SFPROG
updating example 106
control register allocation
See DIAG
control registers
See DIAG
control statements
COMMENT statement 99
DELETE statement 98
in AMSERV file 276
INSERT statement 98
REPLACE statement 98
SEQUENCE statement 98
used by UPDATE command 97

406

VM/SP CMS for System Programming

controlling PA2 program function key DIAGNOSE
code X'54'
See SFPROG
Conversational Monitor System (CMS)
See also CMS (Conversational Monitor System)
abnormal termination
exit routine processing 5
processing 5
recovery 6
batch facility 333
called routine modifications to system area 62
command language 1
command processing 56
command search function 58
commands
ACCESS 161
GENDIRT 340
IPL 323,324
OS program development 4
used with OS data sets 159
VSE program development 4
description of 1
devices supported 21
DEVTAB (device table) 21
DISPW macro 93
DMSNUC 21
EXECs
opening and closing files 81
to execute OS programs 73
file system 2
filemode 2
filename 2
filetype 2
free storage management 23
function of 1
how to save it 321
initialization 322
interface with display terminals 88
interrupt handling 9
introduction 1
loader tables 16
macros
ABNEXIT 5
DISPW 93
DMSEXS 41
DMSFREE 15, 27
DMSFRES 35
DMSFRET 33
DMSFST 339
DMSKEY 39
examples 84
FSCB 75
GETMAIN 16
list of 351
STRINIT 24
usage 75
managing files 2
modules
DMSABN 5

DMSINA 54
DMSINT 55
DMSIOW 11
DMSITE 13
DMSITI 10
DMSITP 13
DMSITS 9,43
DMSLAD 341
DMSPAGE 34
nucleus 16
OS simulation 157
OS support 273
overlay structures 345
program development 3
PSW keys 39
register restoration 62
register usage 43
returning to called routine 61
saved system restrictions 321
simulation of VSE functions 249
storage
DMSEXS macro 41
DMSFREE macro 15
DMSFRES macro 35
DMSFRET macro 33
DMSKEY macro 39
map 17
STRINIT macro 24
structure 15
using 15
SUBCOM function 59
support for OS 273
support for VSAM 273
SVC handling 43
symbol references 21
system save area modification 62
tape volume switching 204
transient area 15
transient program area 23
user program area 23
USERSECT (user area) 21
using OS compilers 4
using OS data sets 159
using VSE compilers 4
VSAM support 273
VSE macros 250
VSE simulation 207
what it provides 1
XEDIT 2
CONVERT command
See DIAG
CONVIPCS EXEC
See DIAG
COpy files adding to MACLIBs 173, 228
copying
books from VSE source statement libraries
DOS cataloged procedure 222
DOS files into CMS files 213

220

macros from VSE libraries to add to CMS
MACLIB 228
members of MACLIBs 176
members of OS partitioned data set with
FILEDEF 170
modules from VSE library or SYSIN tapes 213
modules from VSE relocatable libraries 222
OS data sets into CMS files 169
VSAM files into CMS disk files 307
core image
libraries, using in CMS/DOS 225
on a DOS disk 244
VSE libraries 270
CORTABLE subcommand of DUMPSCAN command
See DIAG
COUNT subcommand of the PER command
See DIAG
CP (Control Program)
See CPPROG
CP abend dumps, reading
See DIAG
CP data, recording
See DIAG
CP debugging'
See DIAG
CP FRET Trap
See DIAG
CP internal trace table
See DIAG
CP message repository
See SFPROG
CP SET DUMP command
See DIAG
CP system services
See SFPROG
CP trace table entries, recording
See DIAG
CPEREP program
See DIAG
CPPROG
See VM/SP CP for System Programming
CPRB macro 351
CPTRAP command
See DIAG
CPTRAP facility
See DIAG
CQYSECT macro 351
creating
CMS files from DOS libraries 213
DOSLIB files 242
file from DOS disks and tapes 213
immediate commands 154
macro libraries
example in CMS/DOS 226
from a DOS library 226
modules from VSE library or SYSIN tapes 213
CSIYTD control program
See DIAG

These symbols are used in the index to refer to other VM and VMjSP books:
CPPROG-VMjSP CP for System Programming
SFPROG-VM System Facilities for Programming
DIAG-VM Diagnosis Guide
Index 407

CSMRETCD macro 351
CUSTOMER PROFILE file
See DIAG
CVTSECT (CMS Communications Vector Table)
See DIAG
cylinder
on 2314/2319 disk 296
on 3330 disk 297

DASD Block I/O System Service
See SFPROG
DASD Dump/Restore (DDR) program
See DIAG
data catalog sharing 279
data control block (DCB)
See DCB (data control block)
data extraction routine
See DIAG
data management
See DIAG
data needed before calling IBM for assistance
See DIAG
data security in batch facility 336
Data Set Control Block (DSCB) 199
data sets
creating files 170
format of 160
identify VSAM 294
OS 159
reading, OS 161, 203
specifying a member name 166
VSAM, compatibility considerations 312
data sheet, problem inquiry
See DIAG
DCB (data control block)
exit 165
relationship to FILEDEF command 162
DCB macro 198
DCP command
See DIAG
DCSS (discontiguous shared segment)
. file directory information for shared disk 328
installation 55
placing Editor macros in 331
placing EXECs in 331
ddnames
IJSCT 296
IJSUC 288, 299
IJSYSCT 285
in OS VSAM programs, restricted to seven
characters in CMS 284
specifying with FILEDEF command 162
used when assembling source programs 238
DDR command 159
DDR program

408

VM/SP CMS for System Programming

See DIAG
de-edi ting VSE macros 223
DEBUG command 6
debugging a dump
See DIAG
debugging an AP/MP system
See DIAG
debugging CMS
See DIAG
debugging CP
See DIAG
debugging GCS
See DIAG
debugging the virtual machine
See DIAG
debugging tools summary
See DIAG
debugging TSAF
See DIAG
debugging, introduction
See DIAG
declarative macros
DTFCD 259
DTFCN 261
DTFDI 261
DTFMT 262
DTFPR 264
DTFSD 265
DECLARE BUFFER IUCV function
See SFPROG
default
DLBL definitions 220
FILEDEF definition 164
of MAC LIB MAP command 174
DEFINE control statement 305
defining
cluster for VSAM space 305
clusters 306
DOS input files 284
DOS output files 284
OS data sets 159
OS input/output files 294
space for VSAM files in CMS/DOS 290
space for VSAM files in OS 300
unique clusters 306
user catalogs 298
VSAM master catalog in CMS/DOS 286
VSAM master catalog in OS 297
definition language for command syntax (DLCS»
See DLCS (definition language for command
syntax)
DELENTRY macro 351
DELETE command 98
DELETE control statement 305
DELETE macro (SVC 9) 193
deleting
a national language
See SFPROG
access method services function 306

members of a MACLIB 174,228
VSAM catalogs 306
VSAM clusters 306
VSAM spaces 306
DEQ macro (SVC 48) 196
DESCRIBE IUCV function
See SFPROG
DETACH macro (SVC 62) 197
determine virtual machine storage size DIAGNOSE
code X'60'
See SFPROG
developing
commands 113
message files 145
OS programs 4
programs 4
VSE programs 4
Device Support Facility 371
formatting temporary disks 283
device table (DEVTAB) 21
device type and features DIAGNOSE code X'24'
See SFPROG
device type class and values
See DIAG
devices
assignments in CMS/DOS 214
for CMS system 21
I/O assignments 245
interrupts 12
output, restrictions in CMS/DOS 218
specifying type with FILEDEF command 163
supported by CMS 21
supported, for VSAM under CMS 319
devices, disks, cylinders, and tracks 295
DEVTAB (device table) 21
DEVTYPE macro (SVC 24) 194
DIAG
See VM Diagnosis Guide
DIAGNOSE code interface with a discontiguous
shared segment (DCCS)
See CPPROG
DIAGNOSE code interface with named segments
See CPPROG
DIAGNOSE codes
See SFPROG
DIAGNOSE instruction
See SFPROG
diagnosing problems
See DIAG
directory
entries 271
entries for CMS/DOS library volumes 271
directory update in-place DIAGNOSE code X'84'
See SFPROG
discontiguous shared segment (DCSS)
See CPPROG
See SFPROG
Disk Operating System (DOS)

core image library 244
creating CMS files 213
declarative macros
DTFCD 259
DTFCN 261
DTFDI 261
DTFMT 262
DTFPR 264
DTFSD 265
disks
accessing 211
compatibility with OS disks 280
determining free space 281
formatting using DSF 283
using with AMSERV 278
files used in CMS 211
for transient routines 268
hardware devices supported 249
imperative macros 267
libraries
executing phases from 244
link-editing modules from 241
size considerations 243
macros supported in CMS 236
restrictions on reading in CMS 212
simulation in CMS 208
support of physical IOCS macros 250
terminal sessions 360
VSE macros under CMS 249
disks
extents 295
read-only, exporting VSAM files from 307
sharing 3
temporary 283
DISP MOD option of FILEDEF command 166
dispatcher (type X'Ol') entry
See DIAG
dispatching virtual machines
See CPPROG
DISPLAY command
See DIAG
display data on 3270 console screen DIAGNOSE
code X'58'
See SFPROG
display real CP data
See DIAG
DISPLAY subcommand of DUMPS CAN command
See DIAG
display terminals, CMS interface 88
display virtual data
See DIAG
displaying
a MACLIB member 230
directories of VSE libraries 224
DLBL definitions 220
lines at terminal, WRTERM macro 84
listings from access method services 277
DISPW macro

These symbols are used in the fndex to refer to other VM and VM/SP books:
CPPROG-VM/SP CP for System Programming
SFPROG-VM System Facilities for Programming
DIAG-VM Diagnosis Guide
Index 409

description of 351
format of 93
distributed system use of the programmable
~~~~

.

See SFPROG
DL/I programs in CMS/DOS 210
restrictions 211
DLBL command
CMS operand 220
default file definitions 220
description of 209
DSN ? operand 248
entering before program execution 245
how to use in CMS/DOS 218
identifying VSAM data sets 294
identifying VSAM data sets on CMS/DOS 284
IJSYSCT ddname 285
options
BUFSP 295
CAT 295
EXTENT 291,295
MULT 295
VSAM 295
relationship to ASSGN command 218
specifying extents in CMS/DOS 291
specifying multiple extents 301
SYSxxx option 218
DLBL definitions
entering in a CMS EXEC procedure 247
using the HX command 220
DLCS (definition language for command syntax)
coding command syntax 117, 144
coding statements 114
converting a DLCS file 115
creating a DLCS file 130, 132
description of 113
DLCS statement 118
example 115
types of statements 114
DMKSP MACLIB 236
DMMTAB communication table
See DIAG
DMSABN 6
DMSABN macro 5, 351
See also DIAG
DMSABW CSECT 5
DMSEXS macro
description of 351
formatof 41
DMSFRE service routines 35
DMSFREE macro
allocating nucleus free storage 32
allocating storage 27
allocating user free storage 32
description of 351
error codes 37
format of 27
free storage management 27
nucleus free storage 15, 23
storage pointers 29

410

VM/SP CMS for System Programming

TYPE = NUCLEUS parameter 32
TYPE = USER parameter 32
user free storage 15, 23
DMSFRES macro
error codes 37
format of 35
DMSFRET macro
description of 351
error codes 37
format of 33
releasing storage 33
DMSFRT CSECT 29
DMSFST macro
description of 351
format of 339
DMSINA module 54
DMSINT module 6, 55
DMSIOW module 11
DMSITE module 13
DMSITI module 10
DMSITP module 13
DMSITP routine
See DIAG
DMSITS module 9, 43, 63
DMSKEY macro
description of 351
format of 39
DMSLAD module 341
DMSNUC
DEVTAB (device table) 21
structure of 21
USERSECT (user area) 21
within CMS storage 15
DMSPAG module 34
DMSSP MACLIB 180, 235
DMSTVS module 204
DMSXFLPT XEDIT routine 87
DMSXFLRD XEDIT routine 87
DMSXFLST XEDIT routine 86
DMSXFLWR XEDIT routine 87
DOS (Disk Operating System)
core image library 244
creating CMS files 213
declarative macros
DTFCD 259
DTFCN 261
DTFDI 261
DTFMT 262
DTFPR 264
DTFSD 265
disks
accessing 211
compatibility with OS disks 280
determining free space 281
formatting using DSF 283
using with AMSERV 278
files used in CMS - 211
for transient routines 268
hardware devices supported 249

imperative macros 267
libraries
executing phases from 244
link-editing modules from 241
size considerations 243
macros supported in CMS 236
restrictions on reading in CMS 212
simulation in CMS 208
support of physical IOCS macros 250
terminal sessions 360
VSE macros under CMS 249
DOSLIB command
compressing DOSLIBs 242
description of 209
DOSLKED command
description of 209
using 225, 240
DOSLNK files
used by DOSLKED command 241
used in CMS/DOS 241
DOSMACRO MACLIB 181
DOSPLI command 209
DOSPOINT subcommand of DUMPS CAN command
See DIAG
DOWN subcommand of TRAPRED command
See DIAG
DSCB (Data Set Control Block) 199
DSERV command
creating MAP files 224
description of 209
examples 224
DSN operand of DLBL command 219
DSORG option of FILEDEF command 165
DTFCD macro 259
DTFCN macro 261
DTFDI macro 261
DTFMT macro 262
DTFPR macro 264
DTFSD macro 265
dummy data set name specified on FILEDEF
command 163
DUMP command
See DIAG
dump debugging
See DIAG
dump, used in problem determination
See DIAG
DUMPID subcommand of DUMPS CAN command
See DIAG
dumping to DASD
See DIAG
dumping to printer
See DIAG
dumping to tape
See DIAG
DUMPSCAN command and sub commands
See DIAG
DUMPSCAN scroll interface

See DIAG
dynamic linkage 59
dynamic load over lay 347
dynamic loading
. TXTLIB members 70

editing error messages DIAGNOSE code X'5C'
See SFPROG
END subcommand of DUMPS CAN command
See DIAG
end, abnormal
See abend (abnormal termination)
ENQ macro (SVC 56) 196
entering
DLBL definitions in CMS EXEC procedure 247
file identifications 163
lines at terminal, during program execution 84
entry points
determining for program execution 70
displayed following FETCH command 244
specified using OS entry statement 182
EPLIST (extended PLIST)
first form 46
second form 47
EPLIST macro· 351
error codes
DMSFREE 37
DMSFRES 37
DMSFRET 37
Error Logging System Service
See·SFPROG
error messages editing DIAGNOSE code X'5C'
See SFPROG
ESERV command
adding MACRO files created by ESERV
program 223
description of 209
examples 223
using 223
ETRACE command
See DIAG
ETRACE GROUP
See DIAG
examine real storage· DIAGNOSE code X'04'
See SFPROG
examining output listings from access method
services 277
EXCP macro (SVC 0) 192
EXCP supported by CMS/DOS 269
EXEC action routines
See SFPROG
EXEC procedures
entering FILEDEF defintions 73

These symbols are used in the fndex to refer to other VM and VMjSP books:
CPPROG-V~jSP C.P for. System Programming
SFPROG-VM System Facilities for Programming
DIAG-VM DIagnosIs GUIde
Index 411

for AMSERV 309
for CMS batch 336
for VSAM 309
in CMS/DOS 247
register contents 248
to execute VSE programs 247
using 73
executing
access method services in EXEC procedure 309
DOS phases 244
DSF programs 283
OS program restrictions 66
phases from core image 244
programs 66
programs in CMS/DOS 243
restrictions
DL/I programs in CMS/DOS 211
OS programs in CMS 66
TEXT files 66, 67
VSAM programs 274
VSE procedures 220
exit routine processing 5
EXIT/RETURN macro (SVC 3) 192
EXPORT access method services function 307
exporting VSAM data sets 307
extended control PSW description
See DIAG
extended PLIST (EPLIST)
See EPLIST (extended PLIST)
EXTENT option of DLBL command 285, 295
extents
allocating on OS disks and minidisk 295
availability of 281
determining for VSAM functions 282
entering in CMS/DOS 291
information when defining VSAM master
catalog 286
multiple in CMS/DOS 291
multiple in OS 301
multivolume 291, 301
External Attribute Buffer (XAB)
See SFPROG
external interrupt (type X'02') entry
See DIAG
external interrupts
See also CPPROG
BLIP character 13
HNDEXT macro 13
timer 13
external interrupts in IUCV
See SFPROG
external references, resolving 68
external tracing facilities, GCS
See DIAG
extra references
resolving 68
EXTRACT macro (SVC 40) 195
extracting a member from a MACLIB 175

412

VM/SP CMS for System Programming

FBD (file block descriptor) 30, 31
FCB (file control block) 43
FCOBOL command 209
FDISPLAY subcommand of DUMPS CAN command
See DIAG
FEEDBACK command used by programmable
operator
See SFPROG
feedback file
See SFPROG
FEOV macro (SVC 31) 195
FETCH command
description of 209
loading phases in CMS/DOS 225
START option 244
fetching core image phases for execution in
CMS/DOS 244
file block descriptor (FBD) 30, 31
file control block (FCB) 43
file directory information 328
file status table (FST)
See FST (file status table)
file system 2
file system control block (FSCB)
See FSCB (file system control block)
FILEDEF command
AUXPROC option 167
BLOCK option 165
default definition 164
device type, specifying 163
DISP MOD option 166
DSORG option 165
dummy data set name specified 163
entering file identifications 163
establishing a file definition for a member 230
file format, specifying 165
guidelines for entering 162
how to use 162
issued by assembler, overriding 238
MEMBER option 166
options
AUXPROC 167
BLOCK 165
DISP MOD 166
DSORG 165
MEMBER 166
PERM 166
RECFM 165
SYSPARM 168
override default file definitions 65
PERM option 166
RECFM option 165
SYSPARM option" 168
used with OS data sets 159
FILEDEF defintions
clearing 166

displaying 67
making with FILEDEF command 162
filemode 2
filename 2
files
auxiliary 104
blocksize (BLKSIZE) 2
closing 81
creating from DOS libraries 213
creating from OS data sets 170
defining 284
defining and allocating space 300
defining OS input and output 294
deleting records 98
described by FSCB 75
DOS 211
format information 165
format, specifying on FILEDEF command 165
handling OS data residing on CMS disks 188
handling OS data residing on OS disks 189
identification 2, 219
inserting records 98
management, CMS 2
manipulating 3, 75
multivolume identification 292, 302
opening 81
output produced by ASSEMBLE command 239
reading 79
reading VSAM tape 294
replacing records 98
sequence numbers in source files 97
size, determining 2
support of OS format 199
VSAM, allocating 290
VSAM, defining 290
writing 79
filetype
preferred 3
used in file identification 2
FIND macro (SVC 18) 194
finding discontiguous shared segment DIAGNOSE
code X'64'
See SFPROG
FINDSYS function
See SFPROG
FOB (font offset buffer)
See CPPROG
foreign languages
See SFPROG
FORMAT subcommand of TRAPRED command
See DIAG
formatting
files 165
OS and DOS disks 283
temporary disks 283
free chain element format 31
free storage
DMSFREE macro- 27

GETMAIN macro 24
managing 23
nucleus 23
user 23
FREEDBUF macro (SVC 56) 196
FREELOWE 246
FREEMAIN macro
releasing storage 26
FREEMAIN macro (SVC 5) 192
Freemain via SVC (type X'09') entry
See DIAG
FREETAB storage table 28
FREEWORK (DMKFRE and DMKFRT save area)
See DIAG
FRERESPG 246
FSCB (file system control block)
creating 75
fields defined 75
format of 75
modifying for read/write operations 78, 79
using 78
using with I/O macros 79
FSCB macro
creating 75
description of 352
FSCBD macro
description of 352
generating DSECT for FSCB 80
FSCLOSE macro
description of 352
example 81
FSERASE macro
description of 352
usage 82
FSOPEN macro 352
FSPOINT macro 352
FSREAD macro
description of 352
example 79
reading disk files 79
FSST ATE macro 352
FST (file status table) 158, 339
FSWRITE macro
description of 352
example 80
writing disk files 79
full-screen console service 88

G subcommand of DUMPS CAN command
See DIAG
GCS configuration file
See DIAG
GCS debugging

These symbols are" used in the index to refer to other VM and VM/SP books:
CPPROG-VM/SP CP for System Programming
SFPROG-VM System Facilities for Programming
DIAG-VM Diagnosis Guide
Index 413

See DIAG
GCS dumping facilities
See DIAG
GCS dumps, analyzing
See DIAG
GCS dumps, initiating
See DIAG
GCS external tracing facilities
See DIAG
GCS internal trace table
See DIAG
GCS internal trace table formats
See DIAG
GDUMP command
See DIAG
GENDIRT command
creating auxiliary directories 342
format of 340
general I/O DIAGNOSE code X'20'
See SFPROG
generate accounting records for the virtual user
DIAGNOSE code X'4C'
See SFPROG
generating
CMS/DOS 270
VSE system 270
GENIMAGE command
See CPPROG
GENIMAGE service program
See CPPROG
GENMOD command
See also DIAG
creating .program modules 71
creating user-written CMS command 71
description of 209
GET command used by programmable operator
See SFPROG
GET macro 201
GETMAIN macro
free element chain 25
storage management 16, 24
storage maximum 25
GETMAIN macro (SVC 4) 192
Getmain via SVC (type X'08') entry
See DIAG
GETPOOL/FREEPOOL macro 192
getting national languages on your system
See SFPROG
GLOBAL command
identify TXTLIBs 182
in CMS/DOS 209
used to identify DOSLIBs 243
used to identify macro libraries 180
used to identify macro libraries in
CMS/DOS 226
used to identify TXTLIBs 181
GTF header
See DIAG
GTRACE (type X'OE') entry
See DIAG

414

VM/SP CMS for System Programming

GTRACE macro
See DIAG
GUESTR option of PER command
See DIAG
GUESTV option of PER command
See DIAG

hash table complex (HASHTAB)
See HASHTAB (hash table complex)
HASHTAB (hash table complex) 2
HELP files
HELP subcommand of DUMPS CAN command
See DIAG
HEX subcommand of TRAPRED command
See DIAG
history information, saving 69, 72, 183
HNDEXT macro 13, 352
HNDINT macro 352
HNDIUCV macro 352
See also SFPROG
HNDSVC macro 352
HOSTCHK statement
See SFPROG
HX (Halt Execution) immediate command
effect on DLBL definitions 220
HX subcommand of DUMPS CAN command
See DIAG
hyperblock mapping table (HYPMAP)
See HYPMAP (hyperblock mapping table)
HYPMAP (hyperblock mapping table) 2

I/O (input/output)
assignments 216, 217
defining files 67
defining VSAM files 284
device assignments in CMS/DOS 214, 245
files, defining 67
interrupt handler in DMSITI module 10
interrupts 10
listing assignments 217
macros 249
tape 292
tapes 303
I/O interrupt (type X'03') entry
See DIAG
IDENTIFY macro (SVC 41) 195
IDENTIFY VMCF function
See SFPROG
identifying
macro libraries 180

macro libraries to search in CMS/DOS 226
master catalog for VSAM in CMS/DOS 286
multivolume VSAM files in CMS/DOS 292
multivolume VSAM files in OS 302
VSAM master catalog in OS 297
lIP (ISAM Interface Program) 310
IJSYSCL ddname defined in CMS/DOS 219
IJSYSCT ddname 296
IJSYSRL ddname defined in CMS/DOS 219
IJSYSSL ddname defined in CMS/DOS 219
IMMBLOK macro 352
IMM CMD macro 352
immediate commands created by user 154
imperative macros 267
IMPORT access method services function 307
importing VSAM data sets 307
INCLUDE command
creating program modules 71
issuing 68
options
AUTO 69
CLEAR 69
DUP 69
HIST 69
LIBE 69
ORIGIN 69
RESET 69
RLDSAVE 69
VSE linkage editor control statement, specifying
in 242
INDICATE command
See DIAG
INITIATE logical device support facility function
See SFPROG
input spool file manipulation DIAGNOSE code X'14'.
See SFPROG
input/output (I/O)
See I/O (input/output)
INSERT statement 98
Installation Discontiguous Shared Segment
(DCSS) 55
installing
CMS batch machine 334
installing the programmable operator facility
See SFPROG
Inter-User Communications Vehicle (IUCV)
See SFPROG
Interactive Problem Control System (IPCS)
See DIAG
internal trace table formats, GCS
See DIAG
internal trace table, CP
See DIAG
internal trace table, GCS
See DIAG
internal trace table, TSAF
See DIAG
internal tracing facilities, GCS

See DIAG
interrupt handler, DMSITI module 10
interrupt handling
See CPPROG
interrupts
CMS macros for handling 85
DMSIOW module 11
DMSITE module 13
DMSITI module 10
DMSITP module 13
DMSITS module 9
external interrupts 13
input/output interrupts 10
machine check interrupts 13
printer interrupts 12
program interrupts 13
punch interrupts 12
reader interrupts 12
SVC
SVC interrupts 9, 43
terminal interrupts 11
user-controlled device interrupts 12
INTSVC for SVC handling routine
CMS SVCs 10
internal linkage SVC 9
invoking the programmable operator facility
See SFPROG
IPCS (Interactive Problem Control System)
See DIAG
IPCS interface files
See DIAG
IPCS variables
See DIAG
IPCSDUMP command
See DIAG
IPCSMAP subcommand of DUMPS CAN command
See DIAG
IPL (Initial Program Load)
See CPPROG
IPL command
BATCH parameter 333
description of 323
format of 324
NOSPROF parameter 333
SAVESYS parameter 324
IPL performance using saved system 336
ISAM
CMS restriction 161
CMS/DOS restriction 212
ISAM Interface Program (lIP)) 310
issue SVC 76 from a second level virtual machine
DIAGNOSE code X'48'
See SFPROG
ITRACE command
See DIAG
IUCV (Inter-User Communications Vehicle)
See SFPROG
IUCV functions

These symbols are used in the index to refer to other VM and VM/SP books:
CPPROG-VM/SP CP for System Programming
SFPROG-VM Sy~tem Facilities for Programming
DIAG-VM Diagnosis Guide
Index 415

See SFPROG
IUCV macro instruction
See SFPROG
IUCV subcommand of DUMPSCAN command
See DIAG

job control cards (fJOB) 335
job control language equivalent in CMS
journaling
See CPPROG

158

keys
DMSEXS macro 41
DMSKEY macro 39
PSW 39
keys, storage protection 38

label
DOS disks 286
OS VSAM disks, determining for AMSERV 297
using VSAM tapes in CMS/DOS 294
using VSAM tapes in OS 303
LANGBLK macro 352
LANGGEN command
See SFPROG
LANGMERG command
See SFPROG
language, CMS command 1
languages, national
See SFPROG
LGLOPR statement
See SFPROG
libraries
CMS/DOS 270
copying modules from 222
DOS core image 225
DOS libraries in CMS/DOS 2~0
DOS/VSE source statement used in CMS 221
programs, CMS/DOS 271
types
LOADLIBs 171
MACLIBs 171
TXTLIBs 171
using directories 224
volumes for CMS/DOS directory entries 271
LINEDIT macro 352

416

VM/SP CMS for System Programming

LINERD macro 352
LINEWRT macro 352
LINK command
See CPPROG
link edit
in CMS/DOS 240
modules form DOS relocatable libraries 242
output 242
specifying control statements 241
TEXT files 241
LINK macro (SVC 6) 192
linkage
OS control statements supported by TXT LIB
command 181
linkage editor map
created by DOS/VSE linkage editor 243
option of VSE ACTION control statement, effect
in CMS/DOS 243
LIOCS routines suppo.cted by CMS/DOS 268
LISTCAT access methods services function 277
LISTCRA access methods services function 277
LISTDS command
listing
DOS files 211
extents occupied by VSAM files 281
free space extents 281
OS and DOS disks 281
OS and DOS files 281
used with OS data sets 159
listing
information about MACLIB members 229
input/output assignments 217
listing members of a MACLIB 176
logical unit assignments in CMS/DOS 217
MACLIB members 231
LISTING file
changing filename 278
created by AMSERV command 277
created by assembler, output filemode 65
created by ESERV command 223
LISTIO command 209
listing device assignments 217
LKED command
description 159
specifying input to 186
using 186
LOAD command
See also DIAG
creating program modules 71
issuing 68
loading TEXT files 67
options
AUTO 69
CLEAR 69
DUP 69
HIST 69
LIBE 69
ORIGIN 69
RESET 69

RLDSAVE 69
START 67
LOAD macro (SVC 8) 192
load map generation
See DIAG
load maps
See also DIAG
created by CMS loader 69
produced by LOAD and INCLUDE
commands 69
loader
control statements 69
controlling the CMS loader 68
loader tables in CMS 16
loader terminate (LDT) control statement
usage 182
loading
core image phases into storage for
execution 244
discontiguous shared segment DIAGNOSE code
X'64'
See SFPROG
programs into storage 71
LOADLIBs 171
LOADMOD command 209
LOADSYS function
See SFPROG
LOADTBL command used by programmable
operator
See SFPROG
LOCATE (UP) subcommand of DUMPS CAN
command
See DIAG
LOG command used by programmable operator
See SFPROG
log file
See also SFPROG
updating 99
LOGGING statement
See SFPROG
logical device support facility
See SFPROG
logical device support facility DIAGNOSE code
X'7C'
See SFPROG
logical operator
See SFPROG
logical record length of FILEDEF command 165
logical units
assigning in CMS/DOS 214
LOGON command
See CPPROG
*LOGREC
See SFPROG
loop procedures
See DIAG
looping programs

See DIAG

machine check
See CPPROG
machine check interrupts 13
MACLIB command
ADD function 173, 228
CaMP function 174, 229
DEL function 174, 228
description 172
example 228
GEN function 172, 227
MAP function 174, 229
REP function 173, 228
using 227
MACLIBs
adding a member 173, 228
adding COpy files 173, 228
CMS commands that recognize MACLIBs 175
compressing 174, 229
copying members 176
creating 172, 226, 227
deleting a member 173, 174, 228
example 173
extracting a member 175
finding out about MACLIB members 180,229
lis ting con ten ts 174
listing information about members 180, 229
manipulating members 230
moving members into other files 176
querying in CMS/DOS 235
replacing a member 173, 228
system 180, 235
using 225
VSE assembler language restricted use in
CMS/DOS 238
MACLIST command
listing members of a MACLIB 176
sample screen 231
using 176, 231
macro libraries
adding a member 173, 228
adding COpy files 173, 228
CMS commands that recognize MACLIBs 175
compressing 174, 229
copying members 176
creating 172, 226, 227
deleting a member 173, 174, 228
example 173
extracting a member 175
finding out about MACLIB members 180, 229
listing contents 174
listing information about members 180, 229
manipulating members 230

These symbols are used in the index to refer to other VM and VMjSP books:
CPPROG-V~jSP C.P for. System Programming
SFPROG-VM System Facilities for Programming
DIAG-VM DiagnOSIS GUIde
Index 417

moving members into other files 176
querying in CMS/DOS 235
replacing a member 173, 228
system 235
using 225
VSE assembler language restricted use in
CMS/DOS 238
macro libraries (MACLIBs)
See MACLIBs
macro library in CMS 351
macros
ABNEXIT 5
CMS 351
declarative -258
DMSEXS 41
DMSFREE 15, 27
DMSFRES 35
DMSFRET 33
DMSKEY 39
examples 75
FSCB 75
GETMAIN 16
GETMAIN/FREEMAIN (SVC 10) 193
HNDEXT 13
imperative 267
list of 351
manipulating disk files 75
OPEN 165
OS 188
OS simulation 191
SAM 258,267
STRINIT 24
supervisor 250
using 75
VSAM, supported under CMS 312
VSE assembler language macros supported in
CMS 236
VSE macros supported by CMS/DOS 249
MAINHIGH 246
management of data
See DIAG
management of problems
See DIAG
manipulating members of a MACLIB 175
MAP command
See DIAG
map compressing routine
See DIAG
MAP files
created by DOSLKED command 243
created by DSERV command 224
MAP option ofGENMOD command
See DIAG
MAP option of LOAD command
See DIAG
MAPA subcommand of DUMPS CAN command
See DIAG
MAPN subcommand of DUMPS CAN command
See DIAG
master catalog sharing 279

418

VM/SP CMS for System Programming

MEMBER option of FILEDEF command 166
Message All System Service
See SFPROG
message complete external interrupt in IUCV
See SFPROG
MESSAGE function for SPOOL system service
See SFPROG
message pending external interrupt in lUCY
See SFPROG
message repository
See SFPROG
message repository files
creating 146
creating HELP files 154
creating your own messages 153
rules for creating 148
using 145
using dictionary substitution 151
using substitution 151
Message System Service
See SFPROG
messages
creating 153
minidisks
extents 295
file directory of 328
restriction on using EXPORT/IMPORT with
VSAM 307
shared, EDF R/O 328
temporary 283
transporting to OS system after using with CMS
VSAM 281
using with VSAM data sets 281
mixed environment use of the programmable
operator
See SFPROG
MODMAP command
See DIAG
module load map
See DIAG
modules
DMSABN 5
DMSINA 54
DMSINT 55
DMSIOW 11
DMSITE 13
DMSITI 10
DMSITP 13
DMSITS 9,43
DMSPAG 34
DOS/VSE relocatable, copying into CMS
files 222
relocatable, link-editing in CMS/DOS 241
MONITOR command
See DIAG
MONITOR START command
See DIAG
MOVEFILE command
copying OS data sets 169

extracting a member from a MACLIB 230
options
PDS 170
PDS option 170
used with OS data sets 159
MREGS subcommand of DUMPS CAN command
See DIAG
MRIOBLOK subcommand of DUMPS CAN command
See DIAG
*MSG
See SFPROG
*MSGALL
See SFPROG
MSS (Mass Storage System)
See CPPROG
MSS communication DIAGNOSE code X'78'
See SFPROG
MSSF SCPINFO command
See SFPROG
MSSFCALL DIAGNOSE code X'80'
See SFPROG
MULT option
in CMS/DOS 285
of the DLBL command 295
multiple address stops
See DIAG
multiple extents 291, 301
multiple updates
CTL option of XEDIT command 107
using UPDATE command 102
multiprocessor
See CPPROG
multiprocessor mode (MP)
See CPPROG
multivolume extents 291, 301

named segments, finding, loading, purging
See SFPROG
NAMESYS macro 321
national languages
See SFPROG
native languages
See SFPROG
*NCCF
See SFPROG
NCCF (Network Communications Control Facility)
See SFPROG
NCCF logical operator
See SFPROG
NCPDUMP command
See DIAG
NCPDUMP service program
See DIAG
NETWORK command

See DIAG
Network Communications Control Facility (NCCF)
See SFPROG
network dump operations
See DIAG
non-recoverable machine check
See DIAG
nonrelocatable modules
creating 71
NOTE macro 198
NOTIFY function for SPOOL system service
See SFPROG
NUCALPHA 16
nucleus free storage
allocating 32
description of 15
nucleus load map
See DIAG
nucleus, CMS 16
NUCOMEGA 16
NUCON macro 352
NUCSIGMA 17

OPEN macro 165
OPEN/OPENJ macro (SVC 19/22) 194
opening
CMS files 81
Operating System (OS)
access method support 199
CMS support for 4, 273
compilers, CMS usage 4
data management simulation 188
data sets 159
disks
compatibility with DOS disks 280
determining free space 281
extents 295
formatting using DSF 283
using with AMSERV 278
files
handling files on CMS disks 188
handling files on OS disks 189
formatted files 199
FREEMAIN macro 26
GETMAIN macro 24
linkage editor control statements read by
TXTLIB command 181
macro simulation 159
macros 188, 191
ABEND 193
ATTACH 195
BLDL 193
BSP 198

These symbols are used in the index to refer to other VM and VM/SP books:
CPPROG-VM/SP CP for System Programming
SFPROG-VM System Facilities for Programming
DIAG-VM Diagnosis Guide
Index 419

CALL 198
CHAP 195
CHECK 198
CHKPT 197
CLOSE/TCLOSE 194
DCB 198
DELETE 193
DEQ 196
DETACH 197
DEVTYPE 194
ENQ 196
EXCP 192
EXIT/RETURN 192
EXTRACT 195
FEOV 195
FIND 194
FREEDBUF 196
FREEMAIN 192
GET 201
GETMAIN (SVC 4) 192
GETMAIN/FREEMAIN 193
GETPOOL/FREEPOOL 192
IDENTIFY 195
LINK 192
LOAD 192
NOTE 198
OPEN/OPENJ 194
PGRLSE 198
POINT 198
POST 192
PUT 201
PUTX 201
RDJFCB 197
READ 202
RESTORE 193
SNAP 196
SPIE 193
STAE 196
STAX 198
STIMER 196
STOW 194
SYNADAF 198
SYNADRLS 198
TCLEARQ 198
TGET/TPUT 198
TIME 193
TRKBAL 195
TTIMER 196
WAIT 192
WRITE 202
WTO/WTOR 195
XCTL 192
XDAP 191
reading data sets 161
simulated data sets 160
Isimulated OS supervisor calls 189
/simulation in CMS 157
supervisor calls 189
tape volume switching 204
terminal sessions 353

420

VM/SP CMS for System Programming

TXTLIBs 181
OPTION command 209
OS (Operating System)
access method support 199
CMS support for 4, 273
compilers, CMS usage 4
data management simulation 188
data sets 159, 203
disks
compatibility with DOS disks 280
determining free space 281
extents 295
formatting using DSF 283
using with AMSERV 278
files
handling files on CMS disks 188
handling files on OS disks 189
formatted files 199
FREEMAIN macro 26
GETMAIN macro 24
linkage editor control statements read by
TXTLIB command 181
macro simulation 159
macros 188, 191
ABEND 193
ATTACH 195
BLDL 193
BSP 198
CALL 198
CHAP 195
CHECK 198
CHKPT 197
CLOSE/TCLOSE 194
DCB 198
DELETE 193
DEQ 196
DETACH 197
DEVTYPE 194
ENQ 196
EXCP 192
EXIT/RETURN 192
EXTRACT 195
FEOV 195
FIND 194
FREEDBUF 196
FREEMAIN 192
GET 201
GETMAIN (SVC 4) 192
GETMAIN/FREEMAIN 193
GETPOOL/FREEPOOL 192
IDENTIFY 195
LINK 192
LOAD 192
NOTE 198
OPEN/OPENJ 194
PGRLSE 198
POINT 198
POST 192
PUT 201

PUTX 201
RDJFCB 197
READ 202
RESTORE 193
SNAP 196
SPIE 193
STAE 196
STAX 198
STIMER 196
STOW 194
SYNADAF 198
SYNADRLS 198
TCLEARQ 198
TGET/TPUT 198
TIME 193
TRKBAL 195
TTIMER 196
WAIT 192
WRITE 202
WTO/WTOR 195
XCTL 192
XDAP 191
reading data sets 161
simulated data sets 160
simulated OS supervisor calls 189
simulation in CMS 157
supervisor calls 189
tape volume switching 204
terminal sessions 353
TXTLIBs 181
OS linkage editor control statement
ALIAS statement 183
assigning entry point names 182
ENTRY statement 182
NAME statement 182
SETSSI card 183
OS/VSAM
macros
ACB 312
CHECK 312
ENDREQ 312
ERASE 312
OSMACRO MACLIB 180, 236
OSMACR01 MACLIB 180, 236
OSPOINT subcommand of DUMPS CAN command
See DIAG
OSRUN command 184
OSVSAM MACLIB 181, ~36
output
controlling the filename 278
devices restricted in CMS/DOS 218
file produced by ASSEMBLE command 239
linkage edit CMS DOSLIBs 242
listings from AMSERV command 277
printed access method service listing 277
records, sequencing 98
overlay structures
description 345

dynamic load 347
example 346
prestructured 346

page management 34
page release function DIAGNOSE code X'10'
See SFPROG
pageable module, identify and locate
See DIAG
paging
hash table complex (HASHTAB) 2
hyperblock mapping table (HYPMAP) 2
ways to control 2
parameter list (PLIST)
See PLIST (parameter list)
parameter lists of IUCV functions
See SFPROG
P ARSECMD macro 352
P ARSERCB macro 352
P ARSERUF macro 352
parsing facility 113
partition size specified for execution in
CMS/DOS 246
partitioned data s~t (PDS)
copying into CMS files 170
specifying members with FILEDEF
command 170
password
defining for VSAM catalogs 289
for VSAM catalogs in CMS/DOS 289
for VSAM catalogs in OS 299
passwords
See CPPROG
paths, IUCV
See SFPROG
PA2 program function key controlling DIAGNOSE
code X'54'
See SFPROG
PER command
See DIAG
performance of virtual machines
See CPPROG
'
.
PERM option of FILEDEF command 165, 166
PGRLSE macro (SVC 112) 198
PLIST (parameter 1i~t) 43, 46
extended '46
tokenized . 46
using FSCB 83
PLU (programmer logical units) assigned in
CMS/DOS 214
PMX (Programmable Operator/NCCF Message
Exchange)
See SFPROG

These symbols are used in the index to refer to other VM and VMjSP books: ,
CPPROG-V~jSP C.p for. System Programming
. SPPRQO:-VM System Facilities for Programming
DIAG-VM DiagnOSIS GUIde
Index 421

POINT macro 198
POST macro (SVC 2) 192
poster, CP internal trace table
See DIAG
PRB command
See DIAG
PRBnnnnn aaaaaaaa file
See DIAG
PRBnnnnn dump file
See DIAG
PRBnnnnn report
See DIAG
PRBnnnnn report file
See DIAG
PRB00003 report file with status updates added
See DIAG
preferred auxiliary files 108
preferred filetypes 3
preferred level updating 108
PRESENT logical device support facility function
See SFPROG
prestructured overlays 346
PRINT access methods services function 277
PRINT subcommand of DUMPS CAN command
See DIAG
printer
See CPPROG
printer interrupts 12
PRINTER subcommand of TRAPRED command
See DIAG
printing
a MACLIB member 230
access method services listings 277
printing tape dump
See DIAG
PRINTL macro description 352
PRINTL macro usage 85
privilege classes for a user
See CPPROG
PROB command
See DIAG
problem analysis
See DIAG
problem diagnosis
See DIAG
problem exist?
See DIAG
problem identification
See DIAG
problem inquiry data sheet
See DIAG
problem management
See DIAG
problem number assignment
See DIAG
problem report file (PRBnnnnn REPORT)
See DIAG
problem reporting
See DIAG
problem types

422

VM/SP CMS for System Programming

See DIAG
procedures, DOS/VSE, copying into CMS files 222
processor
See CPPROG
PROFILE EXEC file
CMS/DOS VSAM user 286
OS VSAM user 296
program check debugging
See DIAG
program exceptions
See DIAG
program interrupt (type X'04') entry
See DIAG
program interrupts 13
program modules, creating 71
Program Support Representative (PSR)
See DIAG
program temporary fix (PTF)
See DIAG
programmable operator facility
See SFPROG
Programmable Operator/NCCF Message Exchange
(PMX)
See SFPROG
programs
developing 4
executing 66
input and output files, identifying 162
interrupts 13
libraries 171
specifying virtual partition size 246
updating, with XEDIT UPDATE option 95
PROPCHK statement
See SFPROG
PROPRTCV for converting routing tables
See SFPROG
protected application facility DIAGNOSE code
X'BO'
See SFPROG
PRTDUMP command
See DIAG
PSA (Prefix Storage Area)
See CPPROG
PSERV command
description of 209
using 222
pseudo timer DIAGNOSE code X'OC'
See SFPROG
PSR (Program Support Representative)
See DIAG
PSW (program status word)
DMSEXS macro 41
DMSKEY macro 39
keys 39
storage protection keys 38
PTF (program temporary fix)
See DIAG
punch interrupts 12
PUNCHC macro

description of 352
usage 85
punching a MACLIB member 230
PURGE IUCV and VMCF functions
See SFPROG
PURGESYS function
See SFPROG
purging discontiguous shared segment DIAGNOSE
code X'64'
See SFPROG
PUT macro 201
PUTX macro 201
PVCENTRY macro 353

QUERY command
description of 210
MACLIBs available 235
QUERY IUCV function
See SFPROG
QUERY SRM command
See DIAG
QUIESCE IUCV and VMCF functions
See SFPROG
QUIT subcommand of DUMPSCAN command
See DIAG
QUIT subcommand of TRAPRED command
See DIAG

RDCARD macro 353
RDJFCB macro (SVC 64) 197
RDTAPE macro 353
RDTERM macro 353
READ functions for SPOOL system service
See SFPROG
read LOGREC data DIAGNOSE code X'30'
See SFPROG
READ macro 202
read system dump spool file DIAGNOSE code X'34'
See SFPROG
read system symbol table DIAGNOSE code X'38'
See SFPROG
read/write operation 82
reader interrupts 12
reading
CMS disk files 79
DOS files 212
OS data sets 203
restrictions
OS data sets 161

SAM files 212
SAM files 212
tapes 303
variable length records 80
VSAM tape files 294
Ready; message
CPU times displayed 46
real channel program support DIAGNOSE code
X'98'
See SFPROG
real storage
See CPPROG
RECEIVE IUCV and VMCF function
See SFPROG
RECFM option of FILEDEF command 165
record format
DOS files 213
program input and output files 165
records, accounting
See CPPROG
records, sequencing 98
recovery, CMS abend 6
references, resolving unresolved 68
REGEQU macro 353
register
contents after CMS command execution 44
restoration 62
usage 43
REGS subcommand of DUMPSC}\.N command
See DIAG
REJECT IUCV and VMCF functions
See SFPROG
relative record number 77
RELEASE command
used with OS disks 159
releasing storage
allocated by DMSFREE 33
allocated by GETMAIN 26
by ab'~nds 33
by an abend 26
by DMSFRET 34
by DMSPAG 34
by FREEMAIN macro 26
by the STRINIT macro 26
relocatable files
modules, link-editing in CMS/DOS 241
object files, loading into storage for
execution 67
using the LOAD and START commands 67
repetitive output
See DIAG
REPLACE statement 98
replacing
member of a MACLIB in CMS/DOS 228
member of a MACLIB in OS 173
REPLY IUCV and VMCF function
See SFPROG
reporting problems

These symbols are used in the index to refer to other VM and VM/SP books:
CPPROG-VM/SP CP for System Programming
SFPROG-VM System Facilities for Programming
DIAG-VM Diagnosis Guide
Index 423

See DIAG
repository files
creating message 146
message 145
REPRO access method services function 307
Resource Access Control Facility (RACF)
See CPPROG
responding to prompting messages from AMSERV in
an EXEC 309
responsibilities of user for CMS/DOS 270
RESTORE macro (SVC 17) 193
restrictions
BDAM 202
eMS/DOS 272
CMS, saved system 321
ddnames in OS VSAM programs 294
executing
OS programs in CMS 66
programs executing in transient area 73
reading
OS data sets 161
SAM files 212
using
DOS macro libraries in CMS/DOS 225
minidisks with VSAM data sets 281
OS programs in CMS/DOS 208
RESUME IUCV and VMCF function
See SFPROG
retrieve a group name DIAGNOSE code X'AO'
See SFPROG
RETRIEVE BUFFER IUCV function
See SFPROG
return codes
displayed in ready message 46
DMSXFLPT 87
DMSXFLRD 87
DMSXFLST 86
DMSXFLWR 87
from access method services 277
from SUBCOM function 61
passed by register 15 46
REUSE subcommand of DUMPS CAN command
See DIAG
RIOBLOK subcommand of DUMPS CAN command
See DIAG
ROUTE statement
See SFPROG
routing table (RTABLE)
See SFPROG
RSERV command
description of 210
examples 222
RTABLE (routing table)
See SFPROG

424

VM/SP CMS for System Programming

S-STAT 16
SAD MACRO
See DIAG
SADGEN ASSEMBLE file
See DIAG
SADGEN TEXT file
See DIAG
SADUMP EXEC
See DIAG
SAM (sequential access method)
declarative macros 258, 267
I/O macros 258, 267
reading 212
sample terminal sessions
for DOS programmers 360
for OS programmers 353
using access method services 369
save the 370X control program image DIAGNOSE
code X'50'
See SFPROG
saved system
See also CPPROG
restrictions for CMS 321
SAVEFD command 328
saving
CMS 321
history information 69, 72, 183
saving or loading a 3800 named system DIAGNOSE
code X'74'
See SFPROG
saving the CP message repository DIAGNOSE code
X'CC'
See SFPROG
SCBLOCK control block
created by SUBCOM 59
SCBLOCK macro 353
scheduling virtual machines
See CPPROG
SCIF (Single Console Image Facility)
See SFPROG
SCPINFO command
See SFPROG
screen management VM/SP SNA support
See SFPROG
SCRIPT command execution restrictions in
CMS/DOS 208
scroll interface, DUMPS CAN
See DIAG
SCROLL subcommand of DUMPSCAN command
See DIAG
SDUMP command
See DIAG
search order
for executable phases in CMS/DOS 244
for routines or commands in CSMMS 54
for TEXT files and TXTLIB members 182

/'

used by ASSEMBLE command 239
searching libraries 180
SELECT function for SPOOL system service
See SFPROG
SEND IUCV and VMCF functions
See SFPROG
SEND/RECV VMCF function
See SFPROG
SENDREQ macro 353
SENDX VMCF function
See SFPROG
SEQUENCE statement 97
sequencing
,
output records 99
using XEDIT SERIAL subcommand 97
sequential access method (SAM)
See SAM (sequential access method)
service routines 34
SET command
description 210
DOSPART operand 246
SET command used by programmable operator
See SFPROG
SET CONTROL MASK IUCV function
See SFPROG
SET DOS command used to enter or exit DOS
environment 208
set languages DIAGNOSE code X'C8'
See SFPROG
SET MASK IUCV function
See SFPROG
setting UPS I byte 247
SEVER IUCV function
See SFPROG
SFPROG
See VM System Facilities for Programming
shadow table maintenance DIAGNOSE code X'6C'
See SFPROG
shared segments
See CPPROG
shared storage 328
sharing virtual disks 3
SHVBLOCK macro 353
*SIGNAL
See SFPROG
Signal System Service
See SFPROG
simulated OS supervisor calls 189
simulation
of VSE functions by CMS 249
OS macro 159
Single Console Image Facility (SCIF)
See SFPROG
single processor mode
See CPPROG
single system use of the programmable operator
See SFPROG
SIO (type X'06') entry

See DIAG
SNA (System Network Architecture)
See SFPROG
SNAP macro (SVC 51) 196
sorting directories of DOS/VSE private
libraries 224
source files
adding comments 99
deleting records 98
inserting records 98
multiple updates to using CTL option of
XEDIT 107
replacing records 98
sample using UPDATE command 100
spanned records, usage 201
Special Message Facility
See SFPROG
SPIE macro (SVC 14) 193
*SPL
See SFPROG
spool file
See CPPROG
spool file external attribute buffer manipulation
DIAGNOSE code X'B8'
See SFPROG
SPOOL System Service
See SFPROG
spooling
See CPPROG
SSERV command
description of 210
examples 221
using 221
STAE macro (SVC 60) 196
stand-alone dump facility
See DIAG
stanqard DASD I/O DIAGNOSE code X'18'
See SFPROG
START command
executing a file 67
executing TEXT files 67
used with FETCH command 244
start of LOGREC area DIAGNOSE code X'2C'
See SFPROG
starting, program execution in CMS 67
STAT command
See DIAG
statall local file
See DIAG
STATE command used with OS data sets 159
status file
See DIAG
STAX macro (SVC 96) 198
STCP command
See DIAG
STIMER macro (SVC 47) 196
STOP command used by programmable operator
See SFPROG

These symbols are used in the index to refer to other VM and VM/SP books:
CPPROG-VM/SP CP for System Programming
SFPROG-VM System Facilities for Programming
DIAG-VM Diagnosis Guide
Index 425

stop execution
See DIAG
storage
allocation of 27, 32
assembler requirements 345
CMS nucleus 16
DMSFREE macro 15
DMSFREE management 27
DMSNUC 15, 21
free storage 23
loader tables 16
managing 23
map, CMS 17
nucleus free 15, 23
protection keys 38
releasing 26, 34
shared 328
structure of 15
transient program area 15, 23
user free 15, 23
user program area 16, 23
storage available in your virtual machine calculated
by CMS 246
storage contents, altering
See DIAG
storage protection
See CPPROG
STORE command
See DIAG
store extended-identification code DIAGNOSE code
X'OO'

See SFPROG
store real CP data
See DIAG
store virtual data
See DIAG
STOW macro (SVC 21) 194
STRINIT macro
description of 24, "353
format of 24
initializing pointers for storage management
releasing storage 26
structure of CMS storage 15
structured data base (SDB)
See DIAG
suballocated VSAM cluster, defining 305
SUBCOM function
calling routines dynamically 59
command search function 58
register 1 contents 49
return codes 61
summary of changes 379
summary record file
See DIAG
supervisor calls 189
SVC
CMS/DOS support routines 250
DMSITS module 9
handling routine
DMSITS 43

426

VM/SP CMS for System Programming

24

INTSVC 43
interrupts 9
linkage 48
types 48
invalid SVCs 53
as and VSE SVC simulation 53
SVC 202 48
SVC 203 52
user-handled 53
SVC interrupt (type X'05') entry
See DIAG
SVC interrupts
CMS SVCs 10
description of 9
internal linkage SVC 9
SVC save area (SVCSAVE)
See DIAG
SVC 199 services
See DIAG
SVC 202 9
description of 48
entered from a program 54
extended PLIST 46
processing 57
return codes 51
search hierarchy 54
tokenized PLIST 46
SVC 203 9,52
SVCTRACE command
See DIAG
switching, CMS tape volume 204
SYMP subcommand of DUMPSCAN command
See DIAG
symptom records
See DIAG
symptom summary file
See DIAG
symptom summary file conversion
See DIAG
SYNADAF macro (SVC 68) 198
SYNADRLS macro (SVC 68) 198
SYSCAT system logical unit
assigning in CMS/DOS 285
SYSCLB system logical unit
assigning in CMS/DOS 216
unassigning 245
SYSCOR macro
See DIAG
SYSIN system logical unit
assigning in CMS.DOS 215
input for ESERV command 223
SYSIPT system logical unit 215
SYSLOG system logical unit 215
SYSLST system logical unit
assigning in CMS/DOS 215
output from ESERV program 223
SYSOPR macro
See DIAG
SYSPCH system logical unit

"

----~

assigning in CMS/DOS 215
output from ESERV program 223
SYSPROF EXEC
description of 322
functions of 323
SYSRDR system logical unit 215
SYSRLB system logical units assigned in
CMS/DOS 216
SYSSLB system logical units assigned in
CMS/DOS 216
system abend
See DIAG
system information, collect and analyze
See DIAG
system logical units
SYSCLB 216
SYSIN 215
SYSIPT 215
SYSLOG 215
SYSLST 215
SYSPCH 216
SYSRDR 215
SYSRLB 216
SYSSLB 216
system MACLIBs 180
CMS macros 235
CMSLIB 180
DMSSP 180
DOSMACRO 181
OS macros 235
OSMACRO 180
OSMACR01 180
OSVSAM 181
TSOMAC 181
System Network Architecture (SNA)
See SFPROG
System Product Editor (XED IT)
See XEDIT (System Product Editor)
system profile 321
bypassing 327
creating 325
description of 322
functions of 328
system save area
format of 63
modifications of 62
system security
See CPPROG
system service, CP
See SFPROG
SYSxxx (programmer logical units)
programmer logical units, assigning 214

TACTIVE subcommand of DUMPSCAN command
See DIAG
tailoring your system 321
tape volume switching in CMS 204
TAPECTL macro 353
tapes
considerations for CMS/DOS 214
input 303
output 303
reading 303
used for AMSERV input and output 292
T APESL macro 353
TCLEARQ macro (SVC 94) 198
temporary disks
formatting using DSF 283
using for VSAM data sets 283
TEOVEXIT macro 353
terminal interrupts 11
terminals
CMS interface 88
macros for communication 84
sample sessions for DOS programmers 360
sample sessions for OS programmers 353
sample sessions using access method
services 369
TERMINATE ALL logical device support facility
function
See SFPROG
TERMINATE logical device support facility
function
See SFPROG
termination, abnormal
See abend (abnormal termination)
terminology
CMS/DOS 207
OS 158
TEST COMPLETION IUCV function
See SFPROG
TEST MESSAGE IUCV function
See SFPROG
TEVC (trace entry verification code)
See DIAG
TEXT files
adding as linkage editor control
statements 182
created by assembler, output filemode 65
executing 66
link-editing in CMS/DOS 241
loading 67
TEXTSYM statement
See SFPROG
TGET/TPUT macro (SVC 93) 198
TIME macro (SVC 11) 193
timers

These symbols are used in the index to refer to other VM and VM/SP books:
CPPROG-VM/SP CP for System Programming
SFPROG-VM System Facilities for Programming
DIAG-VM Diagnosis Guide
Index 427

See CPPROG
TLOADL subcommand of DUMPSCAN command
See DIAG
TOD-clock accounting interface
See SFPROG
tokenized PLIST 46
TOP subcommand of TRAPRED command
See DIAG
TRACCURR (current CP internal trace table entry)
See DIAG
TRACE command
See CPPROG
See DIAG
trace entry verification code (TEVC)
See DIAG
trace execution
See DIAG
trace real machine events
See DIAG
TRACE subcommand of DUMPSCAN command
See DIAG
trace table, CP
See CPPROG
TRACEND (end of CP internal trace table)
See DIAG·
tracing
See DIAG
tracing capabilities in EXECs
See DIAG
tracing storage alteration using PER
See DIAG
tracking number per cylinder on disk devices 296
TRACSTRT (start of CP internal trace table)
See DIAG
transient program area
creating modules to execute in 72
description of 23
location in virtual storage 72
restrictions on modules executing in 72
transient program area 15
transient routines
$$BCLOSE 268
$$BDUMP 268
$$BOPEN 268
$$BOPENR 268
$$BOPNLB 268
$$BOPNR2 268
$$BOPNR3 268
$$BOSVLT 269
supported by CMS/DOS 268
transporting VSAM data sets 281
TRANTBL macro 353
TRAPRED command format
See DIAG
TRAPRED facility
See DIAG
TRAPRED subcommands
See DIAG
TRKBAL macro (SVC 25) 195
TSAB subcommand of DUMPS CAN command

428

VM/SP CMS for System Programming

See DIAG
TSAF console log sample
See DIAG
TSAF debugging
See DIAG
TSAF dumps
See DIAG
TSAF internal trace table
See DIAG
TSAF QUERY command
See DIAG
TSAF SET ETRACE command
See DIAG
TSAFIPCS MAP
See DIAG
TSOMAC MACLIB 181, 236
TTIMER macro (SVC 46) 196
TVSPARMS macro 353
TXTLIB command
creating 181
description 181
ENTRY statement 182
executing 182
FILENAME option 181
GEN function 181
loading 182
members, creating a directory entry for 182
OS linkage editor control statements
supported 181
SETSSI card 183
specify an alias name 183
usage 181
TXTLIBs
TYPE subcommand of TRAPRED command
See DIAG
TYPEBACK subcommand of TRAPRED command
See DIAG
typenum subcommand of TRAPRED command
See DIAG

UCS (Universal Character Set)
See CPPROG
UCSB (Universal Character Set Buffer)
See CPPROG
unassigning logical unit assignments in
CMS/DOS 217
UNAUTHORIZE VMCF function
See SFPROG
unexpected results procedures
See DIAG
unique clusters, defining 306
UP subcommand of TRAPRED command
See DIAG
UPDATE command control statement usage
updating

97

multiple 102
preferred level 108
programs 95
source file, using CTL option of XEDIT 107
UPDATE command 95
VMFASM EXEC 109
VSE 270
updating problem report
See DIAG
updating VM/SP directory DIAGNOSE code X'3C'
See SFPROG
UPSI (user program switch indicator)
byte, setting in CMS/DOS 247
operand, of CMS SET command, example 247
setting 247
user area (USERSECT) 21
user free storage
allocating 32
DMSFREE requests 15, 23
user privilege classes
See CPPROG
user program area
description of 16, 23
GETMAIN macro 24
over laying programs in 72
user program switch indicator (UPS I)
See UPSI (user program switch indicator)
user responsibilities for CMS/DOS 270
user save area 63
user-controlled device interrupts 12
user-written commands
creating 71, 73
USERMAP subcommand of DUMPS CAN command
See DIAG
USERSECT (user area) 21
USERSECT macro 353

variable length record
reading using FSREAD macro 80
writing using FSWRITE macro 80
VIOBLOK subcommand of DUMPSCAN command
See DIAG
virtual console function DIAGNOSE" code X'08'
See SFPROG
virtual machine
See CPPROG
virtual machine assignments 218
virtual machine assist feature
See CPPROG
Virtual Machine Communication Facility (VMCF)
See SFPROG
virtual machine data, recording
See DrAG
virtual machine debugging

See DIAG
virtual machine storage size DIAGNOSE code X'60'
See SFPROG
Virtual Machine/System Product (VM/SP)
See also VM/SP (Virtual Machine/System
Product)
CMS subsystem 1
virtual printer external attribute buffer
manipulation DIAGNOSE code X'B4'
See SFPROG
virtual storage
assembler requirements 345
overlaying during program execution 72
specifying locations for program execution 72
Virtual Storage Access Method (VSAM)
catalog
defining in CMS/DOS 285, 296
sharing 279
structure 289
CMS support for 273
compiling and executing in CMS 274
data sets
compatibility considerations 312
exporting 307
identifying 294
importing 307
manipulating with AMSERV command 273
defining
catalogs in CMS/DOS 286
clusters 305
master catalog in OS 297
unique clusters 306
user catalogs in CMS/DOS 287
devices supported under CMS 319
disks 281
extent, multiple, information in CMS/DOS 291
extent, multivolume, information in
CMS/DOS 291
files
in CMS/DOS 290
in OS 300
identifying multivolume files
in CMS/DOS 292
in OS 302
macros supported under CMS 312
master catalogs 286
multivolume extents 301
programs
identifying before executing programs 275
reading tape files 294
support of 188, 200
using in CMS 273
writing EXECs 309
virtual storage preservation
See CPPROG
virtual storage, altering
See DIAG
VM/SP (Virtual Machine/System Product)

These symbols are" used in the index to refer to other VM and VM/SP books:
CPPROG-VM/SP CP for System Programming
SFPROG-VM System Facilities for Programming
DIAG-VM Diagnosis Guide
Index 429

CMS 1
CMS subsystem 1
directory entries, for VSE 271
VM/SP directory updating DIAGNOSE code X'3C'
See SFPROG
VM/VCNA, VM/SP SNA support
See SFPROG
VM/VTAM, VM/SP SNA support
See SFPROG
VMBLOK subcommand of DUMPS CAN command
See DIAG
VMCF (Virtual Machine Communication Facility)
See SFPROG
VMDUMP command
See DIAG
VMDUMP function
See SFPROG
VMDUMP Function DIAGNOSE code X'94'
See SFPROG
VMFASM EXEC
description 109
VMFDOS command 213
VMLOADL subcommand of DUMPS CAN command
See DIAG
Volume Table of Contents (VTOC) 199
VSAM (Virtual Storage Access Method)
catalog
defining in CMS/DOS 285, 296
sharing 279
structure 289
CMS support for 273
compiling and executing in CMS 274
data sets
compatibility considerations 312
exporting 307
identifying 294
importing 307
manipulating with AMSERV command 273
defining
catalogs in CMS/DOS 286
clusters 305
master catalog in OS 297
unique clusters 306
user catalogs in CMS/DOS 287
devices supported under eMS 319
disks 281
extent, multiple, information in CMS/DOS 291
extent, multivolume, information in
CMS/DOS 291
files
in CMS/DOS 290
in OS 300
identifying multivolume files
in CMS/DOS 292
in OS 302
macros supported under CMS 312
master catalogs 286
multivolume extents 301
programs
identifying before executing programs 275

430

VM/SP CMS for System Programming

reading tape files 294
support of 188, 200
using in CMS 273
writing EXECs 309
VSAM dumping information
See DIAG
VSAM option
of DLBL command 295
of DLBL command in CMS/DOS 285
VSCS printing formatted control blocks
See DIAG
VSCS, VM/SP SNA support
See SFPROG
VSE
assembler language macros supported in
CMS 236
CMS support for 4
compilers, CMS usage 4
hardware devices supported 249
I/O macros 249
libraries 270
macros supported under CMS 249
macros, supervisor 250
supervisor control blocks simulated 269
supervisor macros 249, 250
system residence volume, using in
CMS/DOS 208
transient routines 268
transients simulated by CMS/DOS 268
VM/SP directory entries 271
VSE/VSAM
macros
ACB 311
BLDVRP 311
DLVRP 311
ENDREQ 311
ERASE 311
VSE macros supported by CMS 312
VSEVSAM command prompting 312
VTAM printing formatted control blocks
See DIAG
VTAM service machine VM/SP SNA support
See SFPROG
VTOC (Volume Table of Contents) 199

wait bit, modifying
See DIAG
WAIT macro (SVC 1) 192
wait state procedures
See DIAG
WAITD macro 353
W AITECB macro 353
WAITT macro
description of 353
usage 84

WRITE macro 202
writing
CMS disk files 79
lines to terminal 84
specific records in CMS file 80
variable length records 80
WRTAPE macro 353
WRTERM macro
description of 353
examples 84
WTO/WTOR macro (SVC 35) 195

X'64' -- finding, loading, purging named segments
See CPPROG
XAB (External Attribute Buffer)
See SFPROG
XCTL macro (SVC 7) 192
XDAP macro (SVC 0) 191
XEDIT (System Product Editor)
changing files 2
creating files 2
CTL option, creating multiple updates to source
file 107
DMSXFLPT 87
DMSXFLRD 87
DMSXFLST 86
DMSXFLWR 87
interface to access files in storage 86
XEDIT command
changing files 2
creating files 2
editing a MACLIB member 230

Y-STAT

16

ZAP command
See DIAG
ZAPTEXT command
See DIAG

I Numerics I
3081 processor MSSFCALL - DIAGNOSE code X'80'
See SFPROG
3203
See CPPROG
3270 virtual console interface DIAGNOSE code
X'58'
See SFPROG
3480 tape volume serial support DIAGNOSE code
X'DO'
See SFPROG
37XX Control Program
See CPPROG
See SFPROG
370X dump processing
See DIAG
3800 printer
See CPPROG

These symbols are used in the index to refer to other VM and VM/SP books:
CPPROG-VM/SP CP for System Programming
SFPROG-VM System Facilities for Programming
DIAG-VM Diagnosis Guide
Index 431

International Business
Machines Corporation
P.O. Box 6
Endicott, New York 13760

File No. S370/4300-36
Printed in U.S.A.

SC24-5286-0

--==--_--::::::::iI
- . . ----= ---_ _ _ .a::=-

==='"

1::1

1::1

1::1

==="""

1::1 t:::= c::::II

&::::::I

Y

®

READER'S
COMMENT
FORM

VM/SP
CMS for System Programming
Order No. SC24-5286-0
Is there anything you especially like or dislike about this book? Feel free to
comment on specific errors or omissions, accuracy, organization, or
completeness of this book.
If you use this form to comment on the online HELP facility, please copy the
top line of the HELP screen.
____ Help Information

line

of

IBM may use or distribute whatever information you supply in any way it believes appropriate without
incurring any obligation to you, and all such information will be considered non confidential.
Note: Do not use this form to report system problems or to request copies of publications. Instead,
contact your IBM representative or the IBM branch office serving you.

Would you like a reply? _YES _NO
Please print your name, company name, and address:

IBM Branch Office serving you:
Thank you for your cooperation. You can either mail this form directly to us or give this
form to an IBM representative who will forward it to us.

SC24-5286-0

Reader's Comment Form
CUT
OR
FOLD
ALONG

LINE

Please Do Not Staple

Fold and tape

Fold and tape

NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED STATES

BUSINESS REPLY MAIL
FIRST-CLASS MAIL

PERMIT NO. 40

ARMONK, NY

POSTAGE WILL BE PAID BY ADDRESSEE:
_ _ _ _ ......

_ _ _ ~_J "'tr~-~...:..........

.f''''..... ,•• '.""'"

----- --- -- -------------_.-

.... ~

-

'"

INTERNATIONAL BUSINESS MACHINES CORPORATION
DEPARTMENT G60
PO BOX 6
ENDICOTT NY 13760-9987

1"111 .. 11111111111,,111111.111111'11 .. 1111111111111
Fold and tape

---------- --- -- , -®

- --

Please Do Not Staple

-

,~-

1

~-~~-'~

Fold and tape

READER'S
COMMENT
FORM

VMjSP
CMS for System Programming
Order No. SC24-5286-0
Is there anything you especially like or dislike about this book? Feel free to
comment on specific errors or omissions, accuracy, organization, or
completeness of this book.
If you use this form to comment on the online HELP facility, please copy the
top line of the HELP screen.

____ Help Information line __ of __
IBM may use or distribute whatever information you supply in any way it believes appropriate without
incurring any obligation to you, and all such information will be considered non confidential.
Note: Do not use this form to report system problems or to request copies of publications. Instead,
contact your IBM representative or the IBM branch office serving you.

Would you like a reply? _YES _NO
Please print your name, company name, and address:

IBM Branch Office serving you:
Thank you for your cooperation. You can either mail this form directly to us or give this
form to an IBM representative who will forward it to us.

SC24-5286-0

Reader's Comment Form

CUT
OR
FOLD
ALONG

LINE

Please Do Not Staple

Fold and tape

BUSINESS REPLY MAIL
FIRST-CLASS MAIL

PERMIT NO. 40

Fold and tape

NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED STATES

ARMONK, NY

POSTAGE WILL BE PAID BY ADDRESSEE:

-------- --- -- ----------_.INTERNATIONAL BUSINESS MACHINES CORPORATION
DEPARTMENT G60
PO BOX 6
ENDICOTT NY 13760-9987

1••• 11 •• 1i .1 ••• 1.11 •• 11 ••• 1.1 •• 1.1 •• 1•• 1.1 ••• 11111.1
Please Do Not Staple

Fold and tape

--..--- ----- ----,®

Fold and tape

/

I'

If

..

SC24-5286-00



Source Exif Data:
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.3
Linearized                      : No
XMP Toolkit                     : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37
Producer                        : Adobe Acrobat 9.31 Paper Capture Plug-in
Modify Date                     : 2010:03:20 15:49:52-08:00
Create Date                     : 2010:03:20 15:49:52-08:00
Metadata Date                   : 2010:03:20 15:49:52-08:00
Format                          : application/pdf
Document ID                     : uuid:f5c35172-77c0-4421-bbfd-36a044fd80ac
Instance ID                     : uuid:56a57aea-c2b9-4255-8cf5-28882b84d04c
Page Layout                     : SinglePage
Page Mode                       : UseNone
Page Count                      : 450
EXIF Metadata provided by EXIF.tools

Navigation menu