Digital PDFs

AA-C747C-TC

May 1980

266 pages

Original

9.6MB

Document:	CTS-300 System Users Guide May80
Order Number:	AA-C747C-TC
Revision:	0
Pages:	266
Original Filename:	AA-C747C-TC_CTS-300_System_Users_Guide_May80.pdf

OCR Text

•

o system

CTS-300
System User's Guide
Order No. AA-C747C-TC

May 1980

This manual is a guide for users applying the DIBOL language and the CTS-300
utility programs in the CTS-300 environment.

SUPERSESSION/UPDATE INFORMATION:

This document supercedes
CTS-300 User's Guide
(AA-C747B-TC) •

OPERATING SYSTEM AND VERSION:

RT-ll V4

SOFTWARE VERSION:

CTS-300 V6

To order additional copies of this document, contact the Software Distribution
Center, Digital Equipment Corporation, Maynard, Massachusetts 01754

digital equipment corporation · maynard, massachusetts

First Printing, September 1977
First Revision:
October 1978
Second Revision:
May 1980
The information in this document is subject to change without notice
and should not be construed as a commitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this document.
The software described in this document is furnished under a license
and may only be used or copied in accordance with the terms of such
license.
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by DIGITAL or its affiliated companies.

The postage-prepaid READER'S COMMENTS form on the last page of this
document requests the user's critical evaluation to assist us in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:

DIGITAL
DEC
PDP
DECUS
UNIBUS
COMPUTER LABS
COMTEX
DDT
DECCOMM
ASSIST-ll

DECsystem-lO
DECtape
DIBOL
EDUSYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-8
DECSYSTEM-20
RTS-8

8/80-14

MASSBUS
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESET-8
TYPESET-ll
TMS-ll
ITPS-lO

CTS-300 REVISION HISTORY

With the release of the CTS-300 Version 6 software, this user's guide
has been revised to reflect changes resulting from the software
changes and to provide a more useful manual.
The primary software changes are the addition of CTSGEN which replaces
TSDGEN;
the ability of XMTSD to be run in the foreground (and the resulting
communications
now
possible
between
foreground
and
background);
the DIBOL keyboard editor, DKED; and the PRINTU report
generator utility.
The entire manual has been restructured for ease of use.
explains the new organization and goals for the manual.

The

preface

The highlights of the documentation changes are:
• The above software changes have been documented.
• The error messages are now listed in one place -- at the
of the manual in Appendices A and B.
• Chapters on
reworked.

ISAM,

DDT,

and

SORT

have

been

• Material has been added on CTS-300 file types.

end

extensively

CONTENTS
Page
PREFACE

SECTION I

INTRODUCTION TO CTS-300

.. CHAPTER 1

INTRODUCTION TO CTS-300

1-1

INTRODUCTION
MONITORS
SJ Monitor
FB Monitor
XM Monitor
RUN-TIME SYSTEMS
The Single-User System
The Time-Shared System
The Extended Memory Time-Shared System
DEVELOPMENT
Program Development
System Development
DIBOL UTILITIES AND PROGRAMS
Supplied Utilities
Other DIBOL Programs

1-1
1-1
1-2
1-2
1-2
1-2
1-3
1-3
1-3
1-3
1-4
1-4
1-4
1-4
1-5

BASIC COMMANDS AND FILE CONVENTIONS

2-1

INTRODUCTION
2.1
COMMANDS
2.2
Special Character Functions
2.2.1
Basic Command Rules
2.2.2
Commands to Allocate System Resources
2.2.2.1
2.2.2.2
Commands to Start a Program
Monitor Error Messages
2.2.3
2.3
FILE CONVENTIONS
File Naming
2.3.1
File Types
2.3.2
2.3.3
CTS-300 Data Files
Sequential and Random Access Sequential
2.3.3.1
Files
2.3.3.2
Multivolume Sequential Files
ISAM Files
2.3.3.3

2-1
2-1
2-1
2-2
2-3
2-3
2-4
2-4
2-4
2-4
2-5

1.1
1.2
1.2.1
1.2.2
1.2.3
1.3
1.3.1
1.3.2
1.3.3
1.4
1.4.1
1.4.2
1.5
1.5.1
1.5.2
CHAPTER 2

SECTION II

DEVELOPMENT

CHAPTER 3

DIBOL KEYBOARD EDITOR (DKED)
3.1
INTRODUCTION
USING DKED
3.2
page Format
3.2.1
Commands
3.2.2
New Commands
3.2.2.1
Command Response Messages
3.2.2.2
File Extensions
3.2.3
Search
3.2.4
HELP
3.2.5
3.2.6
CTRL/Z
ERROR MESSAGES
3.3
iii

2-5
2-5
2-7

3-1
3-1
3-1
3-2
3-3
3-3
3-3
3-4
3-5
3-7
3-9
3-9

CONTENTS (Cont.)
Page
CHAPTER 4

DIBOL COMPILER (DICOMP)
4.1
INTRODUCTION
4.1.1
Characteristics
4.1.2
Chapter Organization
4.2
USING DICOMP
4.2.1
Running DICOMP
4.2.2
Options
4.2.2.1
/A
4.2.2.2
/B
4.2.2.3
/C
4.2.2.4
/D
4.2.2.5
/G
4.2.2.6
/L
4.2.2.7
/0
4.2.2.8
/P:N
4.2.2.9
/S
4.2.2.10
/W
4.2.3
Standard Listings
4.2.3.1
Program Listing
4.2.3.2
Symbol Table
4.2.3.3
Label Table
4.2.4
CREF Listing
4.2.4.1
Symbol Cross Reference Table
4.2.4.2
Label Cross Reference Table
4.2.4.3
External Subroutine Cross Reference Table
4.2.4.4
COMMON Cross Reference Table
4.3
ERROR MESSAGES

CHAPTER 5

CTS-300 OPERATING SYSTEMS
5.1
INTRODUCTION
5.1.1
Operating Systems Characteristics
General System Requirements
5.1.2
Chapter Organization
5.1.3
THE SINGLE-USER ENVIRONMENT
5.2
System Requirements for SUD
5.2.1
Preparing Programs
5.2.2
Linking Programs
5.2.3
5.2.4
Running Programs
5.2.5
SUD Memory Allocation
THE TIME-SHARED ENVIRONMENT
5.3
System Requirements for Time-Sharing
5.3.1
Dynamic Memory Allocation
5.3.2
Scheduling
5.3.3
5.3.4
Detached Program Operation
Data File Management
5.3.5
F i 1 e Sh a ring
5.3.5.1
5.3.5.2
Device Sharing
5.3.6
Preparing Programs
5.3.7
Linking
Linking to the Time-Shared DIBOL Library
5.3.7.1
5.3.7.2
Linking for DDT Use

4-1
4-1
4-1
4-1
4-2
4-2
4-2
4-3
4-3
4-3
4-3
4-3
4-4
4-4
4-4
4-4
4-4
4-5
4-5
4-5
4-6
4-6
4-7
4-7
4-7
4-7
4-7
5-1
5-1
5-1
5-1
5-3
5-2
5-2
5-2
5-3
5-3
5-3
5-4
5-5
5-5
5-5
5-6
5-6
5-6
5-7
5-8
5-8
5-8
5-9

CONTENTS (Cont.)
Page
Creating Overlays
5.3.8
Commands
5.3.9
The RUN Command
5.3.9.1
The ATTACH Command
5.3.9.2
5.3.10
Programmed Startup
Forced Job Startup
5.3.10.1
Chain Mode Startup
5.3.10.2
5.3.10.3
Implicit Job Startup
5.3.11
Stopping Programs
TSD CHARACTERISTICS
5.4
System Requirements for TSD
5.4.1
Running the TSD System Program
5.4.2
TSD Memory Allocation
5.4.3
XMTSD CHARACTERISTICS
5.5
System Requirements for XMTSD
5.5.1
XMTSD in the Foreground
5.5.2
Foreground Queue Program
5.5.2.1
Background Listener Program
5.5.2.2
5.5.2.3
Communications Commands
BGMAN.TSD Operation
5.5.2.4
User-Created Commands
5.5.2.5
Running XMTSD in the Foreground
5.5.2.6
Memory Allocation
5.5.2.7
Applications
5.5.2.8
XMTSD in the Background
5.5.3
Running XMTSD in the Background
5.5.3.1
5.5.3.2
Memory Allocation
Applications
5.5.3.3
TERMINATING TIME-SHARED OPERATION (RTEXIT)
5.6
Running RTEXIT
5.6.1
5.6.2
Chaining to RTEXIT
RTEXIT for XMTSD in the Foreground
5.0.3
UTILIZING RESOURCES ON A SMALL SYSTEM
5.7
ERROR MESSAGES
5.8
CHAPTER 6

SYSTEM DEVELOPMENT
INTRODUCTION
6.1
System Generation Programs
6.1.1
Chapter Organization
6.1.2
CTS-300/RT-ll SYSGEN
6.2
CTSGEN
6.3
6.3.1
Characteristics
Choices
6.3.1.1
6.3.1.2
Preliminary Requirements
Question Types
6.3.1.3
CTSGEN Dialog
6.3.2
6.3.2.1
Single-User or Time-Shared System
6.3.2.2
Single-User System
6.3.2.3
Time-Shared System
6.3.2.4
Terminal Specification
6.3.2.5
Local DLll Terminals
6.3.2.6
Remote DLll Terminals

5-9
5-9
5-10
5-11
5-11
5-12
5-12
5-13
5-14
5-14
5-14
5-15
5-15
5-16
5-16
5-16
5-17
5-17
5-18
5-21
5-24
5-26
5-27
5-28
5-29
5-29
5-30
5-30
5-31
5-31
5-31
5-32
5-32
5-33
6-1
6-1
6-1
6-1
6-2
6-4
6-4
6-4
6-5
6-6
6-6
6-8
6-8
6-9
6-10
6-10
6-12

CONTENTS (Cont.)
Page
6.3.2.7
Local DZll Terminals
6.3.2.8
Remote DZll Terminals
6.3.2.9
System Hardware/Software Configuration
6.3.2.10
Naming the Time-Shared Program
6.4
ERROR MESSAGES
SECTION III

UTILITY PROGRAMS

CHAPTER 7

DIBOL DEBUGGING UTILITY (DDT)
7.1
INTRODUCTION
Features
7.1.1
Chapter Organization
7.1.2
7.2
PREPARING FOR DDT
CTSGEN
7.2.1
7.2.2
Compiling
7.2.3
Linking
DDT Operation
7.2.4
7.2.4.1
Running DDT
7.2.4.2
Failure to Properly Prepare for DDT
Error Messages
7.2.4.3
7.3
DDT COMMANDS
7.3.1
Program Execution Control
7.3.1.1
Program Execution
7.3.1.2
Single Step
Breakpoint Control
7.3.2
7.3.2.1
Setting Breakpoints
7.3.2.2
Clearing Breakpoints
7.3.2.3
Iteration of Breakpoints
Variable Manipulation
7.3.3
7.3.3.1
Examining Variables
7.3.3.2
Setting Variables
7.3.3.3
Extended Variable Manipulation
7.3.4
Subroutine Traceback

CHAPTER 8

LINE PRINTER SPOOLERS
8.1
INTRODUCTION
8.1.1
Common Characteristics
8.1.2
Chapter Organization
8.2
LPTSPl.REL (SUD OPERATION)
8.2.1
Characteristics
8.2.1.1
Features
8.2.1.2
Requirements
8.2.2
Using LPTSP 1. RE L
8.2.2.1
Shared Line Printer Operation
8.2.2.2
Shared Terminal Operation
8.2.3
Starting
8.2.4
Run-Time Dialog
8.2.5
Error Messages
LPTSPL.TSD (TSD OPERATION)
8.3
8.3.1
Characteristics
8.3.1.1
Features

6-13
6-15
6-16
6-19
6-20

7-1
7-1
7-1
7-1
7-1
7-2
7-2
7-2
7-3
7-3
7-3
7-3
7-4
7-4
7-4
7-5
7-5
7-6
7-7
7-7
7-8
7-8
7-9
7-9
7-10
8-1
8-1
8-1
8-1
8-2
8-2
8-2
8-2
8-2
8-2
8-3
8-3
8-4
8-5
8-5
8-5
8-5

CONTENTS (Cont.)
Page
8.3.1.2
8.3.2
8.3.2.1
8~3.2.2

8.3.2.3
8.3.2.4
8.3.2.5
8.3.3
8.3.3.1
8.3.3.2
8.3.4
8.3.5
8.3.6
8.4
8.4.1
8.4.1.1
8.4.1.2
8.4.2
8.4.3
8.4.4
8.4.5
8.4.6
CHAPTER 9
9.1
9.1.1
9.1.2
9.1.3
9.1.4
9.2
9.2.1
9.2.2
9.2.3
9.2.4
9.2.5
9.2.6
9.2.7
9.2.8
9.2.9
9.3
9.4
CHAPTER 10
10.1
10.1.1
10.1.2
10.2
10.2.1
10.2.2
10.2.3
10.2.4

Requirements
Using LPTSPL.TSD (TSD Operation)
Default Line Printers
File Recovery
Suspension of Spooling
Detached Mode Operation
The Queue File
Starting
Response with an Attached Terminal
Response with a Detached Program
Stopping
Run-Time Dialog
Error Messages
LPTSPL.TSD (XMTSD OPERATION)
Characteristics
Features
Requirements
Using LPTSPL.TSD (XMTSD Operation)
Starting
Stopping
Run-Time Dialog
Error Messages

8-6
8-6
8-6
8-6
8-6
8-7
8-7
8-7
8-8
8-8
8-9
8-9
8-10
8-10
8-10
8-10
8-11
8-11
8-11
8-12
'8-12
8-12

PRINTU

9-1

INTRODUCTION
Features
Limitations
File Control Records
Chapter Organization
THE CONTROL FILE
IDENT
HEAD1 and HEAD2
EXECUTE
OUTPUT
INPUT
INDEX/LIST
COMPUTE
PRINT
END
USING PRINTU
ERROR MESSAGES

9-1
9-1
9-1
9-2
9-2
9-2
9-4
9-5
9-6
9-6
9-7
9-10
9-12
9-13
9-15
9-15
9-17

ISAM (ISMUTL)

10-1

INTRODUCTION
Features
Chapter Organization
ISAM BASICS
Data Section
Index Section
Handling Added Records
Summary of ISAM Basics

10-1
10-1
10-1
10-2
10-2
10-2
10-2
10-3

vii

CONTENTS (Cont.)
Page
10.3
ISAM INTERNALS
10.3.1
Detailed Structure
10.3.1.1
Data Files
10.3.1.2
Index File
10.3.2
Interrelationships and Tradeoffs
10.3.2.1
Key
10.3.2.2
Record
10.3.2.3
Changing Record and Key Sizes
10.3.2.4
Group
10.3.2.5
Overflow Area
10.3.2.6
Append Area
10.3.3
DISOL Statements
10.3.4
Data Storage
10.4
USING ISMUTL
10.4.1
ISMUTL Requirements
10.4.1.1
SUD Operation
10.4.1.2
TSD Operation
10.4.2
Running ISMUTL
10.4.3
Creating a File (CREATE)
10.4.3.1
Special CREATE Characteristics
10.4.3.2
Design/CREATE Process
10.4.3.3
CREATE Dialog
10.4.3.4
CREATE Example
10.4.3.5
Handling CREATE Problems
10.4.4
Determining the Status of an ISAM File
(STATUS)
10.4.4.1
STATUS Selection and Characteristics
10.4.4.2
STATUS Example
10.4.5
Reorganizing a File (REORG)
10.4.5.1
Special REORG Characteristics
10.4.5.2
REORG Process and Dialog
10.4.5.3
REORG Example
10.4.5.4
Handling REORG Problems
10.4.6
Exiting ISMUTL (EXIT)
10.4.7
Miscellaneous ISMUTL Capabilities
10.4.7.1
STATUS and REORG in Chain Mode
10.4.7.2
Auto-CREATE
10.5
ERROR MESSAGES
CHAPTER 11
11.1
11.1.1
11.1.2
11.2
11.2.1
11.2.2
11.2.3
11.2.4
11.2.5
11.2.6
11.2.7
11.2.8

10-4
10-4
10-4
10-6
10-9
10-9
10-9
10-10
10-11
10-12
10-12
10-13
10-16
10-21
10-21
10-21
10-21
10-22
10-22
10-23
10-25
10-26
10-30
10-32
10-32
10-32
10-33
10-33
10-34
10-35
10-36
10-37
10-38
10-38
10-38
10-40
10-42

SORT/MERGE

11-1

INTRODUCTION
Characteristics
Chapter Organization
THE CONTROL FILE
INPUT
OUTPUT
RECORD
KEYS
DETACH
EXECUTE
SPACE
SU

11-1
11-1
11-2
11-2
11-3
11-5
11-5
11-6
11-7
11-8
11-8
11-9

viii

CONTENTS (Cont.)
Page
11.2.9
TAGS
11.2.10
WORK
END
11.2.11
Summary of Control File Statements
11.2.12
11.3
SORT/MERGE PROGRAM DEVELOPMENT AND USE
SORTG
11.3.1
Compiling with SORTM
11.3.2
Linking
11.3.3
11.3.4
Running the SORT or MERGE Program
Example
11.3.5
SORT/MERGE in Chain Mode
11.3.6
ERROR MESSAGES
11.4
CHAPTER 12

12-1

STATUS

INTRODUCTION
12.1
Features
12.1.1
12.1.2
Chapter Organization
12.2
OPTIONS
STATUS Conventions
12.2.1
Option F
12.2.2
12.2.3
Option H
12.2.4
Option J
12.2.5
Option Jx
12.2.6
Option Kx
Option L
12.2.7
12.2.8
Option Lx
Option M
12.2.9
Option T
12.2.10
Option X
12.2.11
12.3
USING STATUS
12.4
ERROR MESSAGES
CHAPTER 13

12-1
12-1
12-2
12-2
12-2
12-2
12-3
12-3
12-4
12-4
12-5
12-5
12-5
12-6
12-6
12-6
12-7
13-1

REDUCE

13.1
INTRODUCTION
13.1.1
Characteristics
13.1.2
Chapter Organization
13.2
REDUCE OPTIONS
13.2.1
Query Mode
13.2.2
/N Option (No Query)
13.2.3
/V Option (Version Number)
13.3
USING REDUCE
13.3.1
Conventions
13.3.2
Running REDUCE
13.3.3
REDUCE Examples
13.3.3.1
Query Mode
13.3.3.2
No Query Mode
13.3.3.3
Version Number Mode
13.4
ERROR MESSAGES
APPENDIX A

11-10
11-11
11-13
11-13
11-14
11-14
11-14
11-15
11-15
11-15
11-16
11-18

CTS-300 RUN-TIME ERROR MESSAGES

13-1
13-1
13-1
13-1
13-2
13-2
13-2
13-2
13-2
13-3
13-3
13-3
13-4
13-4
13-4
A-I

CONTENTS (Cont.)
Page
APPENDIX 8

ERROR MESSAGES

8-1

Table

DKED Error Messages
DICOMP Error Messages
Time-Shared DI80L Error Messages
Foreground/8ackground Communication
Command Error Messages
DDT Error Messages
Spooler Error Messages (LPTSPl.REL)
Spooler Error Messages (LPTSPL.TSD)
PRINTU Error Messages
ISMUTL Error Messages
SORTG Error Messages
SORTM Error Messages
STATUS Error Messages
REDUCE Error Messages

8-3
8-6
8-11

8-1
8-2
B-3
8-4
8-5
8-6
B-7
8-S
8-9
8-10
8-11
8-12
B-13·

8-12
8-13
8-14
B-15
8-17
8-19
8-20
8-22
8-23
8-24

FIGURES
3-1
5-1
5-2
5-3
5-4
5-5
6-1
10-1
10-2
lb-3
10-4
10-5
10-6

DKED HELP Frame
SUD Memory Allocation
TSD Memory Allocation
8GMAN
Memory Allocation for XMTSD as a Foreground
Program
Memory Allocation for XMTSD as a Background
Program
CTS-300 Operating System Generator (CTSGEN)
ISAM File Overview
Data Group
Index Area
Data Storage (File Initially Empty)
Data Storage (Sequential File as Input)
ISAM CREATE Flowchart

3-7
5-3
5-15
5-lS
5-27
5-30
6-7
10-3
10-5
10-S
10-lS
10-20
10-27

TA8LES
10-1
10-2

File Control Group
ISMUTL CREATE Modes

10-7
10-43

PREFACE

GOALS
This manual supplies information specific to users of a CTS-300 system.
It is not a tutorial manual nor is it purely a reference manual.
However, one goal is to supply information so a new user can use the
system and another goal is to provide enough easy-to-find detail so
the experienced user can build and use a system for greater functionality and efficiency.

ASSUMPTIONS
The ability to write simple DIBOL programs is assumed as is the ability to perform basic RT-II operating system procedures.
If you are a
new user of CTS-300 without this background, you should refer to the
related documentation listed at the end of this preface. Specifically
recommended is the Introduction to CTS-300 and DIBOL (AA-5519A-TC).

STRUCTURE
The body of the manual is divided into three sections:
SECTION I

Introduction to CTS-300

This section will be of primary interest to the new user.
It
discusses the general capabilities of the system and explains the
general system components. The kinds of files the system uses
are also covered.
SECTION II

Development

Information you need to build both a working system and programs
to run under that system is in this section. This section covers
the relationship of the CTS-300 System to the RT-II SYSGEN and
details the CTSGEN procedure. The DKED editor is presented and
program compilation discussed in detail.
xi

SECTION III

Utilities

All the CTS-300 utilities (except CTSGEN and DKED which
vered in Section II) are described in this section.

are

co-

The remainder of the manual consists of two appendixes. Appendix
A contains the CTS-300 System error messages. Messages in this
appendix are listed in sequence by error number. Appendix B contains error messages for all the supplied utility programs.

DOCUMENTATION CONVENTIONS
The DIGITAL Command Language (DCL) format is used for the majority
commands used in examples.

User input is shown printed in red.
The carriage return terminator is not shown at the end of command
lines;
its use is assumed.
It is shown, however, where confusion
might result if it were missing.

RELATED DOCUMENTATION
Document Title

Order Number

Introduction to CTS-300 and DIBOL
CTS-300 Release Notes and Installation Guide
CTS-300 Concepts and Facilities
DIBOL-II Language Reference Manual
PDP-II MACRO-Il Languag,e Reference Manual
RT-II Documentation Directory
Introduction to RT-II
RT-Il System User's Guide
RT-II System Installation and System
Generation Guide
RT-II Software Support Manual
RT-Il Master Index
RT-II Keypad Editor User's Guide
RT-Il Programmer's Reference Manual
RT-II System Message Manual
RT-II Pocket Guide
RT-II System Release Notes
DECFORM User's Guide

AA-55l9A-TC
AA-5697E-TC
AA-5495A-TC
AA-1760F-TC
AA-5075B-TC
AA-5285E-TC
AA-528lB-TC
AA-5279B-TC

xii

AA-H376A-TC
AA-H379A-TC
AA-H380A-TC
AA-H366B-TC
AA-H378A-TC
AA-5284C-TC
AA-5287C-TC
AA-5286C-TC
AA-5792D-TC

INTRODUCTION TO SECTION I

Section I contains material to aquaint the new user with CTS-300.
Chapter 1 explains the relationship of CTS-300 to RT-ll and briefly
highlights some of the major components of CTS-300 and how they relate
to one another.
Chapter 2 lists some of the RT-ll monitor commands
more commonly required by the CTS-300 user.
Also covered are file
conventions and CTS-300 data files.

INTRODUCTION TO SECTION I

CHAPTER 1
INTRODUCTION TO CTS-300

1.1

INTRODUCTION

The Commercial Transaction System 300 (CTS-300) is an operating system
for the DIGITAL Datasystem 300 series of equipment.
CTS-300 consists of a group of programs, including an RT-ll monitor,
RT-ll utility programs, and CTS~300 programs. This group of programs
organize$ the processor and peripheral devices into a working unit for
the development and execution of DIBOL programs. DIBOL is DIGITAL's
business-oriented language and is designed for ease of use in the
business community.
The result is an operating environment expressly
suited to business data processing needs.
The most visible parts of a CTS-300 Operating System are the RT-ll
monitor,
if it is a single-user system, the CTS-300 Run-Time System
(RTS), if it is a time-shared system, and the CTS-300 utility
programs.
All these are outlined in this chapter and explained later
in this manual.
This manual
is
components are
documentation.

1.2

directed toward CTS-300 related subjects.
RT-Il
discussed in complete detail in the appropriate RT-II

MONITORS

A monitor is a master control program that observes, supervises, controls, or verifies the operation of a computer system.
It coordinates
all activities in a system, including I/O supervision, resource allocation, program execution, and operator communication.
There are
three monitors associated with CTS-300.
These three monitors are supplied by RT-Il and they are:
• Single-Job Monitor (SJ)
• Foreground/Background Monitor (FB)
• Extended Memory Monitor (XM)
1-1

1.2.1

SJ Monitor

The Single-Job (SJ) monitor runs in systems with up to 64 K bytes of
memory.
This monitor has limited capability when compared with the
other two, but it has the advantage of being small.

1.2.2

FB Monitor

The Foreground/Background (FB) monitor runs in systems with 64 K bytes
of memory and allows access to both the foreground and the background
divisions of memory. Foreground/background operation provides a way
to share the processor between two programs; one in the foreground
and one in the bacKground. For example, during program execution, the
FB monitor could run the single-user line printer spooler program in
the foreground part of memory for output while it accepts keyboard
input in the background part of memory.

1.2.3

XM Monitor

The Extended Memory (XM) monitor supports the same capabilities as the
FB monitor and, in addition, this monitor will run in systems with up
to 256 K bytes of memory. With the XM monitor, it is also possible to
run the DrBOL extended memory time-shared RTS program in the foreground.

1.3

RUN-TIME SYSTEMS

Run-time systems are a function of CTS-300.
The purpose of the
CTS-300 RTS is to provide facilities for interpreting DrBOL code.
Additionally, in a multiple-user system, a
run-time system provides
executive control over the various programs that may be running.
There are three run-time systems:
• Single-User
• Time-Shared
• Extended Memory Time-Shared

1-2

INTRODUCTION TO CTS-300

1.3.1

The Single-User System

As its name implies, a Single-User DIBOL (SUD) RTS is for single-user,
single-program execution.
Programs developed for single-user operation automatically call the interpretive program from memory whenever
such a single-user program is run. Single-user programs operate under
the direct control of an RT-ll monitor.

1.3.2

The Time-Shared System

A Time-Shared DIBOL RTS (called TSD in the non-extended memory version)
is for multiple-user, multiple-program execution. Application
programs developed for multiple-user operation run under the control
of a time-shared run-time program. This time-shared run-time program,
developed by the user with supplied CTS-300 resources, contains the
interpretive code that operates like the single-user system explained
above and, in addition, exercises control over the DIBOL programs
being run by the users. The time-shared run-time program, itself,
runs under the control of an RT-ll monitor.
Although it is recommended that the TSD program be run under the SJ
monitor, it can run under the FB or the XM monitor. In the latter
case, it must always run in the background; and, of course, the extended memory capability is not available, even with the XM monitor.

1.3.3

The Extended Memory Time-Shared System

The Extended Memory Time-Shared System (XMTSD) is a special version of
the time-sharing program to allow programs to load and execute above
64 K bytes. To operate above 64 K bytes, XMTSD must be used with the
XM monitor.
When XMTSD is run under the XM monitor (as it should always be), it
can be run in the foreground and this gives it additional important
capabilities that are discussed in Chapter 5.

1.4

DEVELOPMENT

CTS-300 is supplied to users who are interested in developing
application programs to solve specific business problems. Development
is divided into two broad categories: program development and system
development. Both categories are explained primarily in Section II of
this manual.

INTRODUCTION TO CTS-300

1-3

1.4.1

Program Development

The resources provided for DIBOL program development are the DIBOL
editor, DKED, the debugging utility, DDT, the DIBOL compiler, DICOMP,
and" the object module linker, LINK.
DKED, which will operate under control of a time-sharing program,
allows. you to create and/or modify source files or data files.
DICOMP compiles source files and produces object files
linking.
DICOMP also provides listings and symbol tables.
DDT, the debugging utility, is
manual.

documented

Section

III

ready

for

this

Linking is the final step in program development, and this is done
under the control of the RT-II linker utility. Specific examples of
linking are provided, where appropriate, throughout the manual.

1.4.2

System Development

Before program development can be accomplished, both the hardware and
software must be matched to the specific needs of the user.
In this
manual, this is called system development.
The RT-II and the CTS-300
systems must each undergo this process. For RT-ll, there is a special
RT-ll/CTS-300 SYSGEN, and for CTS-300, there is CTSGEN.
Chapter 6,
System Development, describes the process.

1.5

DIBOL UTILITIES AND PROGRAMS

In addition to the resources already mentioned, there are several programs that are useful, either by themselves or in conjunction with the
run-time system. Utilities are described in Section III of this manual.

1.5.1

Supplied Utilities

Line Printer Spoolers
LPTSPl and LPTSPL are the line printer spooler utility programs for
CTS-300.
They are used to output a data file to one or more line
printers. These programs function similarly but are different in
loading and starting procedures, as well as in error messages.
They
are documented in Chapter 8.

1-4

INTRODUCTION TO CTS-300

PRINTU
PRINTU is a utility that provides a means to generate a simple report
program to present information in a data file.
PRINTU is documented
in Chapter 9.
ISAM (ISMUTL)
ISMUTL
of, or
cessed
ISMUTL

is a CTS-300 utility program that creates, reports the status
reorganizes ISAM files.
ISAM files are data files that are acthrough the indexed sequential access method.
ISAM files and
are documented in Chapter 10.

SORT/MERGE
The SORT/MERGE utility is supplied in the form of two files.
SORTG,
along with a user-generated control file as input, generates the data
division of a DIBOL program which is then compiled with SORTM to produce an object file.
The object file is linked to produce the
SORT/MERGE program.
SORT/MERGE is documented in Chapter 11.
STATUS
STATUS is a utility program that provides information on active
time-shared jobs and on the parameters of the time-shared RTS.
In addition, while running STATUS, there is an option which allows an active job to be terminated. STATUS is documented in Chapter 12.
REDUCE
REDUCE is a utility that is used to remove the unnecessary blocks from
DIBOL run-time programs that result from the way time-shared programs
are linked.
REDUCE is documented in Chapter 13.

1.5.2

Other DIBOL Programs

There are other programs related to CTS-300 systems that could be useful
in your application. Among these are DECFORM and RDCP.
DECFORM
is an application package that is part of the CTS-300 distribution.
RDCP is a communications package.

INTRODUCTION TO CTS-300· 1-5

CHAPTER 2
BASIC COMMANDS AND FILE CONVENTIONS

2.1

INTRODUCTION

There are basic operating commands and file conventions that must be
understood and observed if efficient, trouble-free use of the CTS-300
system is to be obtained.
It is not the intent of this chapter to explain all the RT-II commands or to discuss files in detail, but rather
to make you aware of everyday requirements.
2.2

COMMANDS

Special function keys and keyboard commands provide communication with
the keyboard monitor (KMON).
These keys and commands allocate system
resources, manipulate memory images, start programs and enable file
maintenance.
After the RT-II Operating System has been brought up,
any RT-II keyboard command is legal provided the appropriate software
module{s)
exists on your system. The readiness of KMON to receive a
command is indicated by its period (.) prompt character. For the sake
of convenience, this chapter contains some of the more commonly used
special keys and commands.
All the commands presented here are explained in detail in
System User's Guide.
2.2.1

the

RT-II

Special Character Functions

The special functions of some characters on the keyboard are noted
below.
These special functions are obtained by simultaneously pressing the key marked CTRL and the character noted (C, 0, S, Q, U, or Z).
CTRL/C

If CTRL/C trap is not set (see the FLAGS external subroutine in the DIBOL-l1 Language Reference Manual),
the following action occurs:
A single CTRL/C aborts the program or transaction,
clears task-oriented
information, and returns control
to KMON.
A double CTRL/C operates the same as a single CTRL/C.
2-1

~--a

program is accepting input and CTRL/C trap is set,

then:
A single CTRL/C has no immediate effect but is stored
in the input buffer.
If the program accepts input
later, the single CTRL/C aborts the program or transaction, clears task-oriented information, and returns
control to KMON.
A double CTRL/C aborts the program and returns
to KMON.

control

CTRL/O

A single CTRL/O suppresses terminal output while permitting program execution. A second CTRL/O reenables
terminal output. Terminal output is lost between the
first CTRL/O and the second.

CTRL/S

A single CTRL/S suspends terminal output.

CTRL/Q

A single CTRL/Q continues terminal output after suspension by CTRL/S.
Terminal output resumes from the point
at which it was suspended. No output is lost.

CTRL/U

A single CTRL/U erases the entire current line of terminal
input. The current line is defined as being the
characters between the last line feed
(or CTRL/C or
CTRL/Z) and the present cursor position.

CTRL/Z

Indicates end-of-file (EOF) when the terminal
as an input file device.

RUBOUT

This key erases the character preceding the cursor.
This operation continues, right-to-Ieft, up to the beginning of the current line.

2.2.2

used

Basic Command Rules

The following are general rules that apply to all keyboard commands.
• Keyboard commands can be abbreviated as long as the command
remains unique.
Throughout the manual optional characters in
each keyboard command are noted by brackets [ ].
• Keyboard command syntax requires a minimum
between the command and the first argument.

one

space

• Each command line must be terminated by pressing the RETURN
key. The system accepts only one such command per line.

2-2

BASIC COMMANDS AND FILE CONVENTIONS

2.2.2.1

Commands to Allocate System Resources

The following are some of the more common commands used to allocate
See the
system resources.
A brief explanation is given for each.
RT-11 System User's Guide for details.
DATE

The DATE command enters the indicated date into the
system and allows you to determine what date (if any)
is presently in the system.
The system date is
assigned to newly created files, new device directory
entries, and listing output.

TIME

The TIME command allows you to determine the current
time of day as kept by the system, or to enter a new
time of day.
If the KWII-L clock option is not present
on the system or if the time is entered incorrectly, an
error message is generated.

ASSIGN

The ASSIGN command assigns a user-defined logical name
as an alternate name for a physical device.
Only one
logical name can be assigned per ASSIGN command, but
several ASSIGN commands can be used to assign different
names to the same physical device.

DEASSIGN

The DEASSIGN command removes the logical name(s) previously assigned to a device.

LOAD

The LOAD command makes a device handler resident.
Program execution is faster when a handler is resident,
even though memory area for the handler must be allocated.

UNLOAD

The UNLOAD command makes previously loaded handlers
nonresident, thus freeing the memory they occupied.

SET

The SET command changes device handler
and system configuration parameters.

2.2.2.2

characteristics

Commands to Start a Program

The following two commands are used to start programs from
board.
See the RT-II System User's Guide for details.

the

key-

image

file

RUN

The RUN command loads the specified memory
into memory and starts execution.

This command is similar to the RUN command except that
the file specified must be on the system device (SY:).

BASIC COMMANDS AND FILE CONVENTIONS

2-3

2.2.3

Monitor Error Messages

Monitor error messages are produced by the RT-ll Operating
See the RT-ll System Message Manual for these messages.
2.3

FILE CONVENTIONS

2.3.1

File Naming

System.

CTS-300 system conventions call for a standard two-character device
name.
Devices may be assigned logical names which take precedence
over physical names. File names consist of one to six characters followed by an optional combination of a period with from one to three
characters. Those optional characters and period specify the file
name extension and usually indicate the format of the file.
If an extension is not specified, most system programs assign default extensions to identify that file.
See the following section for common
file name extensions for the various types of files.
2.3.2

File Types

There are several kinds of files used in an RT-ll/CTS-300 system.
These fall
into the general categories of: system files (monitors,
device handlers, command files, and other internal files), program
files
(source, object, and executable files), and data files.
Data
files are covered in Section 2.3.3.
As explained in the preceding section, files are assigned an extension
that usually indicates the file format and function. Below are listed
some of the more common RT-ll file extensions and some extensions
unique to CTS-300.
Extension
.BAD
.BAK
.BAT
.COM
.DDF
• DBL
.DIR
.ISM
• LOG
• LST
.MAC
.MAP
.OBJ
.REL
.SAV
.SYS
.TMP
.TSD

2-4

Meaning
file with unreadable blocks
edit (K52 and DKED) backup file
batch command file
indirect command file
DIBOL data file
DIBOL source file
directory listing file
ISAM file
log file
listing file
MACRO source files
output (linker) file
object code file
relocatable image file
memory image file
monitor or device handler file
temporary file
program file linked to run in a DIBOL
time-shared system

BASIC COMMANDS AND FILE CONVENTIONS

2.3.3

CTS-300 Data Files

There are three kinds of data files used in CTS-300:
files, random access sequential files, and ISAM files.
2.3.3.1

sequential

Sequential and Random Access Sequential Files

DIBOL sequential files are composed of fixed-length records containing
ASCII characters. As each record is stored, a carriage return / line
feed character is automatically appended. When the file is closed
(after being opened in output (0) mode) a CTRL/Z character (decimal
026) is written by CTS-300 following the last record. With the exception of multivol~me files, discussed below, the CTRL/Z character is
required in any sequential file accessed by CTS-300.

2.3.3.2

Multivolume Sequential Files

The CTS-300 system can create a logical file that consists of one or
more volumes.
Each volume is a single, separately named RT-ll file
that can reside on either the same or a different device unit or
device type.
For example, a CTS-300 data file might consist of six
volumes:
the first three residing on RKO as DATAl.DDF, DATA2.DDF, and
DATA3.DDF;
the fourth residing on RKI as DATA4.DDF;
the fifth,
DATA5.DDF, residing on a disk pack that is not presently mounted;
and
the last on MTO as DATA6.DDF.
This arrangement allows files to be
virtually unlimited in length.
As with single-volume sequential files, the last record in the last
volume of a file is always followed by a CTRL/Z character. And, as
with single-volume sequential files, the file must have been opened in
output mode for the CTRL/Z character to have been inserted upon execution of the CLOSE statement.
This CTRL/Z character is interpreted by
the CTS-300 RTS as a logical end-of-file (EOF).
However, by using one of the FLAGS options (see the DIBOL-ll Language
Reference Manual), multivolume files can be disabled.
In this case,
for an input file, an EOF will be returned when the last block is read
or a CTRL/Z is detected; whichever is first.
For an output file, an
error message indicating that the output file is full will appear if
the space allocated for the file is exceeded. When the output file is
closed, the unused portion of the final block is cleared to nulls, but
no CTRL/Z is appended.
It is the responsibility of any DIBOL-ll program and the user to distinguish between the volumes of a multivolume sequential file, since
neither the CTS-300 RTS nor the RT-ll Operating System can do so.
Each volume is simply another file to RT-ll.
Further, as far as the
run-time system is concerned, each volume is identical except for the
one that contains the CTRL/Z character which is detected as an EOF
condition.
The RT-ll files which comprise the volumes of the logical
file may be located anywhere there is room on a disk.
BASIC COMMANDS AND FILE CONVENTIONS

2-5

During sequential output
(FORMS, WRITES, or DISPLAY statements),
whenever RT-ll detects the physical EOF (that is, the last available
block is reached) before a CLOSE statement is issued, the run-time
system assumes that another volume of the logical file is to be
created.
The run-time system displays the following message at the
console terminal and waits for a response:
MOUNT SUCCESSOR TO dev:filnam.ext FOR OUTPUT
where dev:filnam.ext is the file whose physical EOF was just found.
If another volume is being created, type in the new file specification. For example, if DATAl had been the file on the first volume,
you would type the following:
MOUNT SUCCESSOR TO DKI:DATAI.DDF FOR OUTPUT
DKI:DATA2.DDF
This new file becomes the next volume in the logical file;
the old
output file is closed; and the processing continues until either the
last available block is used or a CLOSE is issued.
If there is to be no successor to this volume, or if a premature termination is desired, you may respond to the message by typing a
CTRL/Z, which causes the OUTPUT FILE FULL error condition.
The data
that caused the overflow will not be written.
During input (ACCEPT statement with alphanumeric argument ,or READS
statement),
if a physical EOF is detected before a logical EOF
(CTRL/Z), it is assumed that the logical file continues elsewhere in
another volume (RT-II file).
The run-time system displays the following message at the console terminal and waits for your response:
MOUNT SUCCESSOR TO dev:filnam.ext FOR INPUT
where the meaning and response are similar to the message for the output file above.
That is, if another volume is available for input,
type in the new file specification, and program processing will continue until a physical EOF is again detected or until programming
ends.
If there is no successor to this volume, or if premature termination is desired, you can respond to the message by typing CTRL/Z,
which causes an EOF error condition, or a branch to the EOF label
specified in the ACCEPT or READS statement.
When the next volume of the logical input or output file is to be continued on the same device drive with a different disk or tape, the
CTS-300 system must wait while the old disk or tape is exchanged for
the new one.
This is done by including a /W at the end of the file
specification which was given in response to the mount successor message.
For example, using the above example for an output successor
(only this time with a new device) type:
MOUNT SUCCESSOR TO DKI:DATAI.DDF FOR OUTPUT
DK2:DATA2.DDF/W
CTS-300 closes the file on the old unit and displays the message:
WAITING FOR DK2:DATA2.DDF •••

2-6

BASIC COMMANDS AND FILE CONVENTIONS

You may now exchange the new disk for the old one.
or tape is ready, type

When the new

disk

<CR) or <LF)
to open the next volume of the logical file on the new
and continue processing.

disk

tape

When performing input using the ACCEPT statement with a decimal argument, the program operates as described above except that CTRL/Z is
treated as any other character, and termination of the file can be accomplished only by a CTRL/Z response to the mount successor message.
When performing random access operations using READ and WRITE statements, the program must choose the correct volume to access. This is
because a record in a random access file is located in relation to the
beginning of the file on the current volume being accessed, not to the
entire logical file that comprises all volumes.
In this mode of operation, it is often useful for a number of volumes to be kept open simultaneously, each on a separate channel, so the program can more easily find the volume containing the desired record.

2.3.3.3

ISAM Files

An ISAM (Indexed Sequential Access Method) file is a multivolume file
in which the records are stored and accessed according to an index
file and a linking scheme that are a part of the ISAM file structure.
All volumes of an ISAM file are open simultaneously, so access to the
proper device is automatically maintained.
There are some differences between an ISAM file and a sequential file.
One difference is that in an ISAM file the EOF marker is not a CTRL/Z
but rather an entire record in which each bit is set to a one.
Another difference is that in a sequential file a carriage return/line
feed is appended to each record.
CTS-300 ISAM files are discussed in detail in Chapter 10.

BASIC COMMANDS AND FILE CONVENTIONS

2-7

INTRODUCTION TO SECTION II

Section II covers the CTS-300. facilities that are provided for
and program development.

system

Program development begins with a source file consisting of DIBOL program statements.
This file can be created with the DIBOL keyboard editor, OKEO, described in Chapter 3.
The source file is compiled with
the OIBOL compiler, OICOMP, described in Chapter 4.
The final step in
producing an executable program is linking.
Linking
is illustrated
throughout the manual to show specific requirements and is documented
in the RT-II System User's Guide.
Before any program (RT-Il or CTS-300) can be run, however,
the total
hardware/software system must be configured for its intended use.
This is accomplished via an RT-II SYSGEN and a CTS-300 CTSGEN,
both
described
in Chapter 6.
In order to know what the CTS-300 system capabilities are, both for the CTSGEN and for later day-to-day use,
the
CTS-300 Run-Time Systems are discussed in Chapter 5.

CHAPTER 3
DIBOL KEYBOARD EDITOR (DKED)

3.1

INTRODUCTION

The DIBOL keyboard editor (DKED) is designed to emulate the RT-ll Keyboard editor,
K52.
DKED is available for both Single-User Systems
(DKED.SAV) and Extended Memory Time-Shared Systems
(DKED.TSD).
This
makes it possible to create and edit source files under either SUD
(with EIS) or XMTSD.
The assumption is made that you know how to use K52 (if you do not,
see the RT-11 Keypad Editor User's Guide).
This chapter simply
explains the areas where the operating characteristics of DKED are
different from those of K52.
3.2

USING DKED

Differences between DKED and K52 are discussed in this section.
The more minor differences are:
• DKED is designed for use with the VTS2.
When a VT100
is
used, it is automatically set to the VT52 mode and remains in
this mode when you exit from DKED.
The keypad functions of
the VT100 are similar to those of the VT52.
•

If you are operating a single-user system, you must:
SET TT SCOPE
SET TT NOCRLF

• Messages appear at the top of the display.
• DEL WORD and UNDEL WORD are not implemented.
• CTRL/U operates the same as DELLIN.
• There is no displayed end-of-file (EOF)

character.

• You can not open a file of zero length.
• The operator is queried for confirmation of a QUIT command or
a YANK command (YANK is a new command;
see Section 3.2.2).
•

Every command issued must be followed by the <RETURN> key.
3-1

Differences that are explained in more detail in
tions are:

the

following

sec-

• DKED is organized on a page basis.
• DKED has a new command:

YANK.

• There are some new command response messages.
• Default file extensions are different.
• The search mode supports wildcards.
• The HELP command has been expanded.
• CTRL/Z is a valid character in DKED.

3.2.1

Page Format

The major difference between DKED and K52 is that DKED is organized on
a page basis.
A page in DKED is defined as either the area between
two form-feed characters or as all the characters preceding a
form-feed character that can be contained in the text buffer.
The following messages do not indicate an error condition.
They
displayed simply to provide you with additional information.
valid function or command can be entered.

are
Any

When a form feed is encountered in a file, the editor sounds the audible alarm and informs you with the message:
Page (Ctrl/l) detected
If the text buffer should become filled before a CTRL/L is encountered, the editor sounds the audible alarm and informs you with the
message:
EXCESSIVE PAGE LENGTH.
If the EOF is encountered, the editor sounds the audible alarm and informs you with the message:
EOF ends current page
The page organization has the following
insertion and manipulation:

additional

effects

data

• DKED allows you to finish the last line you are working on,
even if the text buffer is full.
You must use the PAGE or
REOPN command to complete the editing.
Maximum line size,
including continuation, is 130 characters~

3-2

DIBOL KEYBOARD EDITOR (DKED)

• You can not return to the previous page (or pages) within the
file.
You must use the REOPN command to return to the beginning of the file.
• Because of the page format, you can
spans a page break.

3.2.2

not

CUT

area

that

Commands

3.2.2.1

New Commands

YANK

The YANK command results in deletion of the present page.
When YANK is selected, the editor queries you for confirmation before doing the deletion with the message:
?DKED-W-Kill present page [Y,N]

(Y)

REOPN

The REOPN command closes a file, reopens it, and places
cursor at the beginning of the file.

3.2.2.2

Command Response Messages

the

The following are the characteristics of the command response messages
for DKED.
• The QUIT command is unchanged from K52;
mation message is now:
?DKED-W-Purge output file?

[Y,N]

however, the confir(Y)

• If you have entered an improperly structured command, a
sage will appear:

mes-

?CSI-F-Illegal command
•

If you have specified an input file that does
message appears:

not

exist,

the

one

you

DIeOL KEYBOARD EDITOR (DKED)

3-3

?DKED-F-Unable to open input file
• If there is an output file of the same name as
specify, you will receive a message:
?DKED-W-Output file exists- continue?

[y,N]

(N)

• In a time-shared system, if either the input or output file
is currently being used by another user, you will receive one
of the.following messages:
?DKED-W-Input file being edited by another user
or
?DKED-W-Output file being edited by another user
• When you attempt to open a file that already exists and then
respond in a manner that would cause destruction of that
file, a message appears:
?DKED-F-Illegal command sequence.

Please start over.

The specific circumstances that will cause this message are:
a) You open (or REOPN) a file
OUTFIL=INFIL or OUTFIL=
and the output file already exists. Your response is
then Y (continue even though the file exists) followed
by a QUIT command.
b) You open (or REOPN) a file
INFIL or INFIL=INFIL
and INFIL.BAK exists and the QUIT command is used.

3.2.3

File Extensions

When you open a file under DKED, the default extension is .DDF.
is, if you opened a file as
A=
the file, after editing and exiting, would be
A.DDF
If, however, you opened the file as
A.DBL=
the resulting file would have a .DBL extension.
If the file were opened as:
A.=
the resulting file would have a null extension.

3-4

DIBOL KEYBOARD EDITOR (DKED)

That

3.2.4

The search function under DRED operates somewhat differently from K52;
to some extent, this is due to the page construction.
The following
explanations apply to searches using the FIND, FIND NEXT, REPLACE, and
SUBSTITUTE commands.
Model
The model is the search string specifier.
It is supplied for the FIND
command and serves for the subsequent FIND NEXT, REPLACE, and SUBSTITUTE commands. The model must be changed by another FIND command.
If the first three characters of the model specification are \P\,
the
search will page until the target is found, or an EOF is encountered.
This applies in the forward mode only; see Mode, below.
As an example of a search, consider the following models:
Model

Meaning

\P\ABC

Searches for ABC in the present page and continues to successive pages until the search is successful or the EOF is
encountered.

ABC

Searches for ABC in the present page and stops when
search is successful or the end of the page is reached.

the

Mode
If you are in advance mode,
the search starts from the present
position and
is done by line,
from left to right, in a forward
direction. Whether you search beyond the present page depends on how
you specify the model
(see above).
If you are in backup mode, the
search is done by line, from right to left, from the present position,
in a backward direction.
The backward search remains in the present
page;
it is not possible to search past the beginning of the present
page in the backup mode.
SET WILDCARDS ON/OFF
If you select SET WILDCARDS ON, you indicate the presence of certain
characters in the target that need not be compared for a successful
match.
There are two valid wildcard characters:
a dot (.) and an aster i sk (*).
If you select SET WILDCARDS OFF (the default), wildcard characters are
treated like any other character, and there is no wildcard capability.

DIBOL KEYBOARD EDITOR (DKED)

3-5

The dot wildcard
The dot (.) indicates that any character in the dot's position will be
accepted for a match. That is:
A.B, matches

AXB
AYB
AZB

The asterisk wildcard
The asterisk (*) is equivalent to an indeterminate number of dot wildcards and indicates that a match will be made with any character
string (including a string of zero length) in the asterisk's position.
That is:
A*B, matches

AB
AXB
AXXXXXXXXB

An asterisk wildcard is useful for finding
first and last characters are known.

target

when

only

the

Additional wildcard rules:
• A model can not begin or end with a wildcard.
• Asterisks and dots can be combined to select a target in
which the number of characters in some positions is important
and in which the number of characters in other positions is
not important.
That is:
A.B*C, matches

AXBC
AYBC
AXBXC
AYBXXXXC

• Adjacent asterisks are allowed;
equivalent to one asterisk.

however,

the

meaning

• Adjacent asterisks and dots force the indeterminate asterisk
string to have a minimum length determined by the number of
dots.
• If wildcards are in use, a search can not be made for
the asterisk (*) or dot (.) character.

3-6

DIBOL KEYBOARD EDITOR (DKED)

either

3.2.5

HELP

The HELP frame received in response to the HELP command has changed
slightly from the one provided by K52.
See Figure 3-1 for the DKED
HELP frame.
The YANK command is added, and there are two notes whose
meaning will be discussed.

DKED V06
Ke~pad La~out for VT52
Lower Function is GOLD

!------------------------------------------------!
!
!
! IIELIN -> !
,..
GOLD

HELP!

UNDELIN

!!
REPLACE

!----------------------------------------------PAGE
! FIND NEXT !
! COMMAND

! (Note 11)!
7!
FIND
8!

BLANK!
9!

V
SECTION

!----------------------------------------------ADVANCE
BACKUP
DELCHR - ) !
----)
!

BOTTOM

TOP

UNDLCH

YANK

!----------------------------------------------WORD
!
EOL
CUT
(---!

DELETE
RUB CHAR(CTRL/U
RUB LINE-)
CTRL/W
SCREEN
(GOLD)NNNN REPEAT

11) \P\model

= paSed
search

= Survives commands
set command list b~:
(GOLD>(COMAND> and
respond: ·HELPC·

CHNGCASE 1! DELEOL-) 2!
PASTE 3! APPEND
!-----------------------------------------------!
BEGIN OF LINE
SELECT
ENTER

OPEN LINE

RESET

SUBS

!-----------------------------------------------!
Figure 3-1

DKED HELP Frame

Note 1.
This note in the FIND block reminds you that "\P\" must
for a multiple page search (see Section 3.2.4).

specified

DIBOL KEYBOARD EDITOR (DKED)

3-7

Asterisk (*)
The asterisk in the FIND and the PASTE blocks indicates that more
information pertaining to these two commands is made available by
selecting <GOLD><COMMAND> and responding HELPC.
The
statement
"survives command" means the PASTE buffer and search model will
survive even if you exit from the file and open another file.
HELPC
lists a summary of the options and operations related to searching and
pasting.
The response is a display:
1. )
2.)
3. )
4.}
5.}
6.)
7.)
8e)

9.}
10.)
II.}
12.}
13.}
14.}

EXIT
REOPN
·QUIT
SET SEARCH BEGIN (default)
or:SSB
SET SEARCH END
or:SSE
CLEAR PASTE
or:CP
SET EXACT CASEFLAG
or:SEC
SET EXACT NONE (default)
or:SEN
SET WILDCARDS OFF (default)
or:SWOFF
SET WILDCARDS ON
or:SWON
HELP WILDCARDS
or:HELPW
HELP COMMANDS
or:HELPC
SEARCH RULES
or:RULES
MODEL (displays the current search model)

Type <return> to continue:
This display shows:
•

Items 4 through 13 show the
with DKED.

•

Items 1 and 3 through 8 above are
commands.

•

Item 2, the REOPN command (see Section 3.2.2), is
place yourself at the beginning of the file.

• Item 12, HELP COMMANDS
this list.
•

abbreviated

available

duplicates

K52

useful

(or HELPC), is the command to

display

Item 13, the SEARCH RULES (or RULES) command, causes the following display:
SET SEARCH BEGIN (or END)
SET EXACT NONE (or CASEFLAG)
SET WILDCARDS OFF (or ON)
ADVANCE (or BACKWARD)
Model: xxx
Paging: No(Yes}
Length: ( n)
Type <return> to continue:

3-8

exact

commands

DIBOL KEYBOARD EDITOR (DKED)

This display summarizes for you the current search
model options (search begin/end, case exact/none, wildcards on/off, advance/backward search, and
paging
yes/no). The model you have selected for the search is
shown (xxx) and its length indicated by the value of n •
•

Item 14, MODEL command, causes the following display:
xxx
Paging:

No(Yes) Length:

(n) Type <return> to continue:

This display is a summary of the current model parameters
showing: model (xxx), paging (yes/no), and model length (n) •
• Item 11, HELP WILDCARDS (or HELPW) command, causes a description of the wildcard rules to be displayed.
The display is
self-explanatory.

3.2.6

CTRL/Z

CTRL/Z is interpreted in either of two ways by DKED, depending on when
it is entered.
CTRL/Z in a Command String
If you enter a CTRL/Z when DKED is in the command string
interpreter
mode
(a command is being entered in response to DKED's asteri~k
prompt), CTRL/Z operates like a CTRL/C; that is,
DKED operation is
terminated and control returns to the monitor.
CTRL/Z as a Character in a File
CTRL/Z can be entered like any other valid character in a file being
created with DKED.
The response is a AZ.
This allows you to insert
the required CTS-300 terminating character in files you create or to
add it to existing files.
Once you have entered a CTRL/Z, the next
time it is encountered DKED will interpret it as the EOF of the file
being edited.

3.3

ERROR MESSAGES

DKED uses essentially the same error messages as K52.
See Appendix B,
Table B-1, in this manual and the RT-ll Keypad Editor User's Guide for
an explanation of these messages.

DIBOL KEYBOARD EDITOR (DKED)

3-9

CHAPTER 4
DIeOL COMPILER (DICOMP)

4.1

INTRODUCTION

The DIBOL compiler (DICOMP.SAV) is a CTS-300 program that is run under
control of the RT-ll Operating System.
It accepts source files that
may have been created by the user and creates object files
(.OBJ
files) that are ready to be linked to produce an executable DIBOL program. This compiler may be invoked via DCL command (DIGITAL's Command
Language;
see the RT-ll System User's Guide); however, that mode
does not support the /G, /P:N, and /S options (see Sections 4.2.2.5,
4.2.2.8, and 4.2.2.9).

4.1.1

Characteristics

Some DICOMP features:
• Can produce two output files:
file.

an object file and

listing

• Outputs object code to the single object file.
• Accepts up to six DIBOL source code files.
• Accepts several options which govern the nature of the
produced, the listings, and warning messages.

4.1.2

files

Chapter Organization

The remainder of this chapter is comprised of two sections:
4.2, Using DICOMP, and Section 4.3, Error Messages.

Section

4-1

4.2

USING DICOMP

Running DICOMP

4.2.1

DICOMP is executed with the RUN command, like any other program, in
response to the RT-ll monitor's prompt. DICOMP responds with an asterisk prompt •
• R [U] DICOMP
*[outfil] [,listfil]=infill [,infi12, ••• infi16] [In] [In]
where:
outfil

is the output of
dev:filnam.ext.

the

compiler

the

general

form

• If not specified, the default device is OK:.
• The default extension is .OBJ.
• If the output file is not specified, no
is generated.
,listfil

object

file

is the listing file in the general form dev:filnam.ext.
• The default device is OK:. Most often
file is directed to either the terminal
line printer (LP:) by specifying just
This could also be used with just a
store the listing on a disk.

the listing
(TT:) or the
the device.
file name to

• The default extension is .LST.
• If no list file is specified, none is produced;
if
an object file is specified, only that file is generated.
• If only a listing file is desired with no object
file, specify only a listing file device and file
specification preceded by the comma. The comma indicates there is no object file.
infi11[infi12 ••• infi16]
are the DIBOL source files supplied as input to the
compiler.
These files are specified in the general
form dev:fi1nam.ext.
• The default device is the system device DK:.
• The default extension is .DBL.
/n

4-2

is the compiler switch option. The options are discussed in detail in the following section. More than
one option can be specified.
They are separated by
slashes.

DIeOL COMPILER (DICOMP)

4.2.2

Options

The valid options for DICOMP are listed below in alphabetical order.
4.2.2.1

The /A switch alphabetizes the symbol and label
tables.
Therefore,
symbols and labels do not appear in the order they are encountered by
the compiler.
4.2.2.2

The /B switch selects single buffering for I/O.
The compiler normally
uses two buffers to increase I/O speed. Single buffering slows down
I/O time but provides more space for compilation.
This additional
space may be necessary during program development in an extended memory time-shared environment (see Chapter 5).
4.2.2.3

The /C switch causes a Cross Reference (CREF) listing to be generated.
This listing indicates, by line number, where symbols are used and defined.
(See Section 4.2.4.)
NOTE
The file CREF.SAV must be on the system
device in order to obtain a CREF listing.
4.2.2.4

The /0 switch causes a symbol table to be generated for use by the
DIBOL Debugging Program (DDT). This switch must be specified if you
intend to use DDT later.
4.2.2.5

The /G switch creates a log file of the errors generated during
compilation.
If there were no listing file selected, the log file
also contains the statements that are in error.
The log file
IS
placed on the system device and takes the name of the first module in
the compiler command line. This file always has an extension of .LOG.
The user is responsible for removing this file when it is no longer
needed.
DIBOL COMPILER (DICOMP)

4-3

The main purpose of the log file is to provide a place for error information when a compilation is requested by an operator using XMTSD
in the foreground.
(See Chapter 5)

4.2.2.6

The /L switch suppresses a program listing if one has been specified
in the command string, but it does not suppress the symbol table.

4.2.2.7

The /0 switch suppresses the generation of line numbers in the program
listing. This has the advantage of using less memory, increasing program speed, and reducing the program size. This switch should be used
only with debugged programs; otherwise, the line numbers in the error
messages will be meaningless.

4.2.2.8

/P:N

The /P switch allows you to override the default listing page length
of 66 lines.
The number of lines is selected with the value of N
which may be either octal or decimal.
The value of N is interpreted as decimal if it is followed by a decimal point.
Every page of a listing has two header lines followed by a
blank line. Therefore, a value of N of 16 (/P:16.) would result in a
listing page having two header lines, one blank line, and 13 lines of
source code.

4.2.2.9

The /S switch suppresses the symbol table and label table listings
a listing file were requested.

4.2.2.10

The /W switch suppresses the warning messages.
Since many of the
warning messages do not interfere with running the program, they are
not always needed.

4-4

DIBOL COMPILER (DICOMP)

4.2.3

Standard Listings

If a listing file is indicated in the command string, and
if neither
the program nor the symbol table has been suppressed, the normal output consists of three segments. These are the program listing,
itself, the symbol table segment, and the label table segment with an
error report appended to the latter.

4.2.3.1

Program Listing

The compiler produces a complete listing of the source program.
Sequential line numbers are assigned to most lines in the program.
The exceptions are:
• START statements
• Compiler directive statements (for example, IFDEF)
• Continued lines
• Blank lines
• Comment lines
The line numbers are also referenced by the symbol table,
the label
table segment, and the CREF listing (if selected).
Line numbers are
especially useful in debugging DIBOL programs.
Errors in the source program also appear in the program
Section 4.3).

4.2.3.2

listing

(see

Symbol Table

The symbol table segment consists of a listing of all the data and
literals referenced in the program. The table contains four columns
which are entitled NAME, TYPE, DIMENSION, and SIZE.
These titles are
explained below:
NAME

Contains a list of all data field
referenced by the program.

TYPE

Contains the field type of the data field and literals
found
in the column entitled NAME.
Field types are:
ALPHA, DECIMAL, RECORD, or IMDEF (Improper Definition).
Symbol table entries for COMMON variables have a C
preceding the type of symbol it is:

names

and

literals

C- ALPHA
C- DECIMAL
C- RECORD
DIBOL COMPILER (DICOMP)

4-5

DIMENSION

Contains the dimension of the data fields and literals
listed under the NAME column. This is the array element count defined for the field given under NAME.
A
dimension of zero is always assigned to any data field
or literal which is improperly defined
(that is,
IMDEF) •

SIZE

Contains the size, in terms of 8-bit bytes, of the data
fields and literals given under NAME. For a field this
corresponds to the size of the field or array element.

4.2.3.3

Label Table

The label table segment contains a listing of all the labels and
external subroutines used within the program. The table contains five
columns which are entitled NAME, i, TYPE, LINE i, and ORIGIN.
The
columns headed i and ORIGIN are of little importance to the DIBOL-ll
programmer and are not discussed.
The headings used in the label
table listing are explained below:
NAME

Contains the name of each label and external subroutine
referenced by the program.

TYPE

Contains the type of name
types are identified:

listed

under

Three

NAME.

LABEL for labels
EXSUB for subroutines
IMDEF for both improperly defined labels
properly defined subroutines.
LINE i

4.2.4

and

im-

Contains the line number on which a label
is defined.
This line number is zero for each external subroutine
called, and it is also zero for each improperly defined
or improperly referenced label or external subroutine.
CREF Listing

When a listing file is specified with the /C switch in the compiler
string, a Cross Reference (CREF) listing is generated and appended to
the end of the compiler listing.
DICOMP normally places a CTRL/Z (A Z) at the end of a DIBOL listing;
however, it is not done when a CREF listing is appended. When CREF is
specified, a temporary file is opened on the system device.
The CREF listing adds as many as four separate sections to the listing
file.
A discussion of sections and their functions follows.

4-6

DIBOL COMPILER (DICOMP)

4.2.4.1

Symbol Cross Reference Table

Lists, in alphabetical order, each of the user-defined symbols, followed by a series of numbers. The first number, followed by the #
symbol, indicates the line number in which the symbol is defined. All
other numbers indicate line numbers which reference the symbol. Each
page of this section is numbered S-n, where n is the page number in
the section.

4.2.4.2

Label Cross Reference Table

Lists, in alphabetical order, each of the program labels, followed by
a series of numbers. The first number, followed by the # symbol, indicates the line number in which the label is defined.
All other
numbers indicate line numbers which reference the label. Each page of
this section is numbered L-n, where n is ·the page number in the section.

4.2.4.3

External Subroutine Cross Reference Table

Lists, in alphabetical order, each of the external subroutines that is
called, followed by a series of numbers. Each line number indicates a
line number in which that subroutine is called.
Each page of this
section is numbered X-n, where n is the page number in the section.

4.2.4.4

COMMON Cross Reference Table

Lists, in alphabetical order, each of the user-defined COMMON symbols,
followed by a series of numbers. The first number, followed by the #
symbol, indicates the line number in which the symbol is defined. All
other numbers indicate line numbers which reference the symbol. Each
page of this section is numbered C-n, where n is the page number in
the section.

4.3

ERROR MESSAGES

DICOMP detects three classes of mistakes in the source language files.
A mistake is presented to the user as either a warning, an error, or a
fatal error.
A warning is issued by the compiler when a statement is potentially a
problem in the program. Otherwise, the statement is properly defined
and executable. Warning messages do not affect compilation. An error
usually indicates a mistake in definition or syntax. Fatal errors indicate that it is impossible to continue processing.
DIBOL COMPILER (DICOMP)

4-7

All fatal error messages are printed on the terminal.
Two kinds of
fatal errors are possible: those which return to the DICOMP prompt
and those which return to the RT-ll monitor. A special case is that
in which th~ compiler detects no PROC statement.
In this case, entry
for the binary output file is removed from the directory, and a message indicating that there is no PROC statement is displayed on the
terminal.
Error messages usually contain helpful information to find and correct
the problem. A pointer (circumflex or up arrow, depending on the terminal) is displayed which points to the approximate position of the
first error detected in the line.
If the statement contains an error,
two asterisks are placed to the left of the assigned statement number.
If the statement contains only a warning, no asterisks appear.
The
error message appears below the line containing the error.
Below is an example of error reporting for an error in the
tion of a source file:

data

por-

1 RECORD A
2 Dl,D2,00
3 D2,D2,00
4 RECORD,X
5 ,A2,'AB'
INITIAL VALUE NOT ALLOWED
The circumflex under line five indicates the point at which the error
occurred;
the text below the line in error specifies the nature of
the error.
Whenever a statement line contains an improperly defined symbol, the
error is flagged only on the line where it first occurs.
Two asterisks appear to the left of the assigned statement number, with the
error message below the line. All subsequent occurrences of the symbol are flagged by the two asterisks only, without the message.
As many as three error and/or warning messages are printed per line.
A total error and warning message count, which includes the printed
messages and any undefined labels, is printed on the terminal.
Appendix B, Table B-2, contains a complete list of the error
for DICOMP.

4-8

OIeOL COMPILER (DICOMP)

messages

CHAPTER 5
CTS-300 OPERATING SYSTEMS

5.1

INTRODUCTION

This chapter describes both the single-user and the multi-user
(time-shared)
environments and presents some of their system requirements.
It also contains information on preparing programs and explains how to run programs in either of the two environments.

5.1.1

Operating Systems Characteristics

The function of any CTS-300 operating system is to allow you to run
DIBOL programs.
It provides the interface between a DIBOL program and
the RT-ll Operating System.
Although there are
some
special
time-shared related instructions, the run-time environment is not a
major consideration when writing a DIBOL program. A program becomes a
single-user or a mUlti-user program as a result of how it is linked.

5.1.2

General System Requirements

Whether yours is a single-user or a multi-user
(time-shared)
system,
there are preliminary requirements that must be met before programs
can be run.
These requirements are satisfied by properly running
the
RT-ll Operating System Generation program (SYSGEN) and the CTS-300 Operating System Generation program
(CTSGEN).
SYSGEN allows you to
build an RT-ll Operating System software environment that is compatible with your hardware configuration. CTSGEN allows you to build a
CTS-300 Operating System that is compatible with both the RT-ll system
as structured by SYSGEN and the intended DIBOL-II program requirements.
SYSGEN and CTSGEN are discussed briefly in this chapter and in
detail in Chapter 6.

5-1

5.1.3

Chapter Organization

The remainder of this chapter is comprised of six sections:
Sections
5.2 through 5.7.
Section 5.2, The Single-User Environment, describes
the operation of a single-user system. The remaining sections are devoted to time-shared operation. Section 5.3, The Time-Shared Environment, is general in its discussion of time-sharing requirements and
characteristics.
The
time-shared user without extended memory
hardware will be interested in Section 5.4, TSD Characteristics, which
covers the TSD system.
The extended memory time-shared user will
find, in Section 5.5, XMTSD Characteristics, a discussion of the XMTSD
system and its variations.
Section 5.6, Terminating Time-Shared Operation (RTEXIT), will be of interest to all time-shared users.
S~ction
5.7,
Utilizing Resources on a Small System, is intended to provide
some useful guidelines for users with a floppy-based system.
Section
5.8, Error Messages, is a reference to time-shared error messages.

5.2

THE SINGLE-USER ENVIRONMENT

5.2.1

System Requirements for SUD

For SUD programs you can SYSGEN for either the SJ, FB, or the XM monitor.
The SJ monitor is recommended unless you intend to use the SUD
print spooler (LPTSPl.REL);
then the FB or XM monitor must be used.
The DIBOL compiler produces interpretive code.
Therefore,
the requirement for DIBOL programs to run under the RT-ll Operating System
is that there be a run-time code interpreter available.
This interpreter which can be thought of as an executive or a run-time system is
produced as a result of the CTSGEN process.
It is assigned the name
SUD.RTS by CTSGEN and must always reside on the system disk.
If you plan to use either ISAM or the DIBOL debugging
you must make an appropriate selection in CTSGEN.

program,

DDT,

The single-user run-time code interpreter requires approximately
KB of memory without ISAM or DDT.

12.4

5.2.2

Preparing Programs

Program editing and compilation of DIBOL-ll programs for SUD systems
are performed using any valid editor (EDIT, TECO, K52, DKED, etc.) and
theDIBOL compiler.
DKED and the DIBOL compiler (DICOMP) programs are
described in Chapters 3 and 4 of this manual.
If you plan to use DDT, you must compile with the debugging option.

5-2

CTS-300 OPERATING SYSTEMS

5.2.3

Linking Programs

The object (OBJ) file resulting from compilation must be linked to the
DIBOL library (DIBOL.OBJ).
The following command string could be used
to link the program TEST.OBJ and subroutines SUB.OBJ and SUB1.0BJ for
SUD 0 pe rat ion:
For programs without DDT:
.LINK TEST,SUB,SUB1,DIBOL
Results in a SUD program named TEST.SAV.
For programs with DDT:
The following command string illustrates linking for DDT:
.LINK TEST,SUB,SUB1,TSDDT,DIBOL
5.2.4

Running Programs

DIBOL programs in a SUD system are run like any other Save file:
.R PROG or .RU dev:PROG
The run-time interpreter SUD.RTS is automatically brought into
whenever a single-user DIBOL program is run.
5.2.5

memory

SUD Memory Allocation

The allocation of memory for a SUD System is shown in Figure 5-1.
56 KB
RMONSJ
and
System Handler

52 KB

Device Handlers

buffers
free memory

SUD.RTS
(12.4 KB)
without ISAM or DDT

SUD
Application Program
(DIBOL code)

Figure 5-1

SUD Memory Allocation

CTS-300 OPERATING SYSTEMS

5-3

5.3

THE TIME-SHARED ENVIRONMENT

A DIBOL-ll Time-Shared RTS or executive, is a program that runs under
the control of the RT-ll monitor.
Its purpose is to control
time-shared DIBOL user programs. There are two versions available:
• The normal version, identified as TSD, runs under the RT-ll
Single-Job
(SJ)
monitor, the Foreground/Background
(FB)
monitor, or the Extended Memory (XM) monitor.
Of course, TSD
can not access extended memory even with the Extended Memory
monitor. The SJ monitor is recommended because its small
size leaves more memory for user programs.
• The extended memory version, identified as XMTSD, runs
the RT-ll Extended Memory monitor only.

under

A time-shared RTS permits properly compiled and linked DIBOL-Il
programs to be independently loaded and executed in a time-shared
environment. The time-shared system communicates with all active
terminals to provide interactive program control. Simple keyboard
commands, explained below, permit you to initiate and terminate
program operation. During execution, each program appears to have at
its disposal the full
resources of the CTS-300 system.
Further,
programs can share data files and I/O devices.
The time-shared system
provides complete facilities for:
• Program loading and execution
• Allocation of memory resources
• Program scheduling
• Detached program operation
•

Error detection and reporting

• Sending/Receiving messages between programs (see the DIBOL-Il
Language Reference Manual)
• Timed wait of program execution (SLEEP
DIBOL-ll Language Reference Manual)

statement;

see

the

• Line printer spooling (see Chapter 8)
The information in this section applies to both TSD and XMTSD systems.

5-4

CTS-300 OPERATING SYSTEMS

5.3.1

System Requirements for Time-Sharing

As with the single-user system, the DIBOL programs in a time-shared
environment require a run-time code interpreter, and, as with the single-user environment, CTSGEN produces this code.
However, the CTSGEN
for a time-shared system also includes the specification (and resulting construction) of the code to process the time-shared related
statements.
If you plan to use either ISAM or the DIBOL debugging
program, DDT, you must make an appropriate selection in CTSGEN.
In
addition, active terminals to be recognized by the run-time system are
selected in CTSGEN.
Special SYSGEN requirements are presented under
the TSD and XMTSD sections.
The following table indicates the approximate memory requirements of
the two commonly used RT-II monitors and the two CTS-300 time-shared
run-time systems. The time-shared systems both have multiterminal
support.
The sizes of ISAM and DDT are also shown.
Component

Approximate Size

SJ Monitor
XM Monitor
SUD Interpreter (SUD.RTS)
TSD Run-Time System
XMTSD Run-Time System

3.5 - 4.5 KW
7.0 - 9.0 KW
6.2 KW
9.0 KW
12.0 - 16.0 KW

ISAM
DDT

2.1 KW
0.6 KW

5.3.2

Dynamic Memory Allocation

The time-shared RTS dynamically manages the allocation of the free
memory used by DIBOL programs.
This means that memory space is
allocated automatically on a demand basis. When you request that a
program be executed, the run-time system loads the program into the
first free area of memory that it finds large enough to contain the
program.
When a program terminates execution, the memory space that
it occupied becomes available for
reallocation to another program.
When free memory becomes fragmented to the extent that no contiguous
area of memory is large enough to contain the program to be loaded,
the run-time system attempts to relocate currently existing programs
to make the necessary room.
The free memory spaces are concatenated
and, if there is then enough space, the program is loaded.
5.3.3

Scheduling

To effect time-sharing operation, the run-time system performs program
scheduling
(time sharing) on both a DIBOL-1l interpretive instruction
basis and an I/O request basis.
This means that a
program will run
until a predetermined number (usually 64) of DIBOL-Il interpreter instructions are executed or until an I/O statement (READ, WRITE,
etc.)
is executed.
When either of these conditions occurs, the run-time
system suspends execution of the current program and schedules another
program to run.
CTS-300 OPERATING SYSTEMS

5-5

Program scheduling on an instruction count basis can be controlled
within a DISOL program by means of the SLICE external subroutine. See
the DISOL-11 Language Reference Manual.

5.3.4

Detached Program Operation

A program that is running under the control of a time-sharing system
program, and that does not require the constant use of a terminal, can
disconnect itself from the terminal by using the DETACH statement.
Detached operation disconnects a program either from the terminal that
initiated the program's operation or from the terminal to which it was
last attached.
When a DETACH statement is executed by a program,
below is displayed:

the

message

shown

DETACHING
TSD VERSION VBnn-nn

(or XM-TSD VERSION VC nn-nn)

*
At this point you may issue either a RUN command or an ATTACH command.
See Section 5.3.9.
The detached program runs to completion as long as either no further
terminal
I/O is required or no error condition occurs that requires a
displayed message.
If terminal I/O is required, the program's operation is suspended until an ATTACH command is issued from an active
terminal.

5.3.5

Data File Management

Files created in the time-shared environment are compatible with those
created in the single-user environment and conform to the file conventions discussed in Chapter 2 of this manual.
Under the time-shared
RTS, these data files can also be shared by two or more programs, thus
providing the capability of creating a common data base.
In addition,
programs can also share certain I/O devices with one another.

5.3.5.1

File Sharing

All programs that are to share a file must open the file with the OPEN
statement in either update (U) or in input (I) mode. When a program
opens a file for either update or input, the file can subsequently be
opened by other programs (in I or U modes). For example, one or more
programs can be reading a file sequentially (READS statement)
while
other programs can be directly accessing the file (READ or WRITE
statement).
5-6

CTS-300 OPERATING SYSTEMS

When a record is read using the direct access READ statement in update
mode,
the blocks within which the record wholly or partially resides
are automatically locked.
This means that the record cannot be read
by another program until it is released. Also, other adjacent records
may be locked if they happen to reside wholly or partially within the
block(s)
that contains the record being read. An attempt to access
(READ or WRITE statement) a locked record will cause an error message
to be displayed.
The block(s) that contains the record is unlocked
when the program that originally read the record does one of the following:
• Rewrites the record
• Reads another record from the same file
• Issues an UNLOCK statement (When a program that accesses a
file using
two or more channels issues an UNLOCK, the lock
condition is cleared for all channels.)
• Issues a CLOSE to the channel
• Terminates operation

5.3.5.2

Device Sharing

Mass storage direct access devices, such as disks and DECtape, are
sharable.
Sequential
access devices
(magtape)
are nonsharable
devices.
However, in the case of magtapes, different device unit
numbers are considered to be different devices.
Line printers and
other non-mass storage devices are also nonsharable.
There is a restriction on the use of the ASSIGN command when devices
are being shared.
If the ASSIGN command is used to assign a logical
name to a disk, then this assigned name must be unique throughout all
programs that refer to that device.
That is, the device must be referred to by its assigned name and that name only.
To do otherwise
creates an ambiguous condition for the run-time system with the following results:
• The run-time system will not perform I/O mode checking
correctly.
If two programs attempt to open (OPEN statement)
the same file using different logical device designations,
the run-time system will not be able to detect the error
condition that should be detected
if a file is opened
simultaneously for I mode and for 0 mode.
• The automatic lock feature will not be invoked to
simultaneous reading or writing of the same record.

prevent

CTS-300 OPERATING SYSTEMS

5-7

5.3.6

Preparing Programs

A program that runs under a time-shared RTS is identical to a program
that runs in the single-user environment except that the time-sharing
capabilities of certain·
language
statements
become
operable.
Specifically these are:
READ, WRITE, READS, WRITES, SEND, RECEIVE,
DETACH, and SLEEP.
The SLEEP command, while it operates in a
single-user system, is primarily a time-sharing statement. Details on
the use of these statements are provided in the DIeOL-II Language
Reference Manual.
All program preparation operations, including compilation and linking,
are identical for the TSD or the XMTSD Run-Time Systems.
Program editing and compilation are performed using any valid editor
(EDIT, TECO,
K52, DKED, etc.) and the DIeOL compiler (DICOMP).
DKED
is the only editor you can use under a DIBOL time-sharing RTS.
DKED
and DICOMP are described in Chapters 3 and 4 of this manual.
If you plan to use DDT, you must include the /D switch in your
command string.

5.3.7

DICOMP

Linking

5.3.7.1

Linking to the Time-Shared DIeOL Library

The object (OBJ) file resulting from compilation must be linked with
the time-shared RTS library (TDIBOL.OBJ).
The following command
string could be used to link, for time-shared operation, the program
TEST.OBJ and subroutines SUB.OBJ and SUB1.OBJ:
.LINK/EXE:TEST.TSD TEST,SUB,SUB1,TDIBOL/BOT:IOOOOO
It is recommended that the file name extension .TSD be used for the
program file output by the linker. This has two important benefits:
• A file linked for time-sharing operation can be easily distinguished from a file linked for single-user operation.
This naming convention also prevents a .SAV file from being
overwritten if the time-sharing file has the same file name •
• No extension need be specified in the RUN
time-shared program with the .TSD extension.

command

for

To save disk storage space, the utility program, REDUCE, should be
used to remove the unused blocks resulting from the linking process.
See Chapter 13.

5-8

CTS-300 OPERATING SYSTEMS

5.3.7.2

Linking for DDT Use

If the DDT utility program is to be used with a program running in the
time-shared environment, the file TSDDT.OBJ must be included in the
link command string. The following command string, assuming the program was compiled for DDT, could be used to link (for DDT operation)
the program and subroutines shown in the previous example:
.LINK/EXE:TEST.TSD TEST,SUB,SUB1,TSDDT,TDIBOL/BOT:100000
• The file TSDDT must precede the file TDIBOL in the linker's
command string; otherwise, a linker error will result •
• DDT operation requires the time-shared system to be a version
in which DDT was selected during CTSGEN.
See Chapter 6 in
this manual.
In order to save disk storage space, the utility program, REDUCE,
should be used to remove the unused blocks resulting from the linking
process. See Chapter 13.

5.3.8

Creating Overlays

Programs and their subroutines that are to be run in a time-shared environment can be formed into a series of overlays using the same procedures used with any other program.
See the RT-II System User's
Guide.
The main object module, TDIBOL, and TSDDT (if used) must all
reside in the root segment of the overlay.
The example below illustrates linking for overlays using the same
modules as with linking for DDT, above.
In this example, subroutines
SUB and SUBI are linked for non-simultaneous operation in overlay
region one.
The remaining modules are in the root segment •
• LINK/PROMPT/EXE:
*SUB/0:1
*SUB1/0:1
*//

5.3.9

TEST.TSD TEST,TSDDT,TDIBOL/BOT:100000

Commands

All time-shared run-time systems accept at least two commands:
the
RUN command and the ATTACH command.
Either of these commands can be
terminated by a carriage return. When XMTSD is run as a foreground
program,
it supports additional commands.
See Section 5.5.2.
The
time-sharing program indicates its readiness to receive a command with
an asterisk prompt.

CTS-300 OPERATING SYSTEMS

5-9

5.3.9.1

The RUN Command

A RUN command issued from any active terminal loads and starts
tion of a OIBOL-ll progr~m.

execu-

The command has the form:
*R filnam[.ext]

or *RU dev:filnam[.ext]

where:
dev:

is the name of the device where the program
If not specified, the device OK:
is assumed.

resides.

filnam[.ext]
is the name of the program that is to be run •
•

If no extension is specified, the extension
assumed •

• Programs with overlays
device.

must

reside

.TSO

the

system

Examples:
*R ACCTOl
Loads and executes program ACCTOl.TSO from the device OK:.
*RU RLl:LIST
Loads and executes program LIST.TSD from device RLl:.
Program execution continues until one of the following conditions
curs:

oc-

• The program issues a STOP or END statement.
• A trappable run-time error occurs that was not trapped by
ONERROR statement.
• A fatal

(nontrappable)

run-time error occurs.

• A.detached program requires the use of a terminal.
ATTACH command, described in the following section.

See

• The user types a CTRL/C command while the program is attached
to the terminal.
• The program is terminated via the kill command in the
program.

5-10

CTS-300 OPERATING SYSTEMS

STATUS

5.3.9.2

The ATTACH Command

The ATTACH command connects a program running in the detached state to
the terminal from which the command was issued.
The command has the form:
*ATTACH [dev:] [filnam.ext]
or
*A [dev:] [filnam.ext]

for XMTSD operation (See Section 5.5)

where:
dev:

is the name of the device where the program
If not specified, the device DK:
is assumed.

resides.

filnam.ext
is the name and extension of the program that is to be
attached to the terminal from which the command is entered •
•

If no extension is specified, the extension
assumed .

.TSD

•

If no file name is specified,
the ATTACH command
lists all the current detached jobs in the system.

Example:
.R TSD
TSD VERSION VBnn-nn
*ATTACH
NO DETACHED JOBS
*R LPTSPL
TIME SHARED DIBOL LINE PRINTER SPOOLER VBOX-OX
DO YOU WANT TO RUN DETACHED?

Y
DETACHING
TSD VERSION VBnn-nn
*ATTACH
JOBS RUNNING DETACHED
DK:LPTSPL.TSD

5.3.10

Programmed Startup

Time-shared programs can be executed with the RUN command discussed
above,
or their execution can be initiated by a program which is running under a time-shared system.
There are three methods by which
this can be accomplished:
forced job startup, chain mode startup, and
implicit job startup.
CTS-300 OPERATING SYSTEMS 5-11

5.3.10.1

Forced Job Startbp

A forced job startup occurs when the XCALL statement is used with the
RUNJB subroutine in the manner presented here. Forced job startup is
used to start up a program that is not already running.
The format is:
XCALL RUNJB ('fi1spec' ,n)
where:
fi1spec

is the CTS-300 file specification for the program to be
started up.

is a number with the following meaning:
•

If n is positive (including 0), it is the number of
the terminal to which the program is to be attached •

•

If n is ~1, it indicates that the program
started up in a detached state.

If the program is started up detached and it requires a response,
it
is necessary to supply this response with a SEND statement prior to
the XCALL for the forced startup.
The general form is:
SEND ('msg' ,'fi1spec')

XCALL RUNJB ('fi1spec' ,-1)
where:
m~

is a message sent to the program before it is
This message is required for some DIBOL programs.

fi1spec

is, in both lines, the CTS-300 file
the program to be started up.

-1

5.3.10.2

for
/~

indicates the program is started in a detached state.

Chain Mode Startup

Chain mode is used when it is desired to execute a
the normal termination of a first program.

5-12

specification

run.

CTS-300 OPERATING SYSTEMS

program

following

The format is:
STOP 'filspec'
where:
filspec

is the CTS-300 file specification for the desired
program to run.

If the calling program were detached, the program started in chain
mode will also be detached. If this second program requires an operator response, it is necessary to supply this response with a SEND
statement prior to chaining. The general form is:
SEND ('msg' ,'filspec')

STOP 'filspec'
where:
m~

is a message sent to the program before it is run.
This message is required for some DIBOL programs that
would normally query the operator.

filspec

is, in both cases, the CTS-300 file
the program to be started up.

5.3.10.3

specification

for

Implicit Job Startup

Implicit job startup is used to send a message to a program and to ensure that the program will be automatically started up detached if not
already running.
The form is:
SEND ('msg' ,'filspec' ,n)
where:
msg

is the message to be sent.

filspec

is the CTS-300 file specification for the program to be
st9rted up.

has a value of -2 or -3:
•

~. -2

indicates that if the program is not currently
rUhning, the time-shared RTS will start up the job in
a detached state •

• A -3 indicates that a copy of the program will be
started up in a detached state. The copy started is
in addition to any others that may be currently running.
CTS-300 OPERATING SYSTEMS

5-13

5.3.11

Stopping Programs

A program normally continues until it runs to completion and a STOP or
END statement is executed.
You can prematurely terminate program operation by typing a CTRL/C at the keyboard of the terminal to which
the program is currently attached. The CTRL/C function can be disabled by the CTRL/C trap.
It is wise to be certain that the trap is
not set if you are planning to use the CTRL/C to terminate program execution.
If the program is running in a detached state, the ATTACH
command must first be used to connect the terminal to the program before CTRL/C can be used to stop it. When the program stops, control
returns to the run-time system.
CTRL/C normally causes immediate program termination.
If the program
is not waiting for keyboard input (that is, executing a READS statement to the terminal), two CTRL/Cs typed in succession are needed to
terminate program operation.
Files opened for output (0) mode are
lost since they cannot be closed.
Following are some of the implications of the CTRL/C command:
•

If keyboard input is pending, or if no I/O operation
process, CTRL/C stops the program immediately.

•

If an I/O operation is in process, CTRL/C stops
only after the I/O operation is completed.

program

the

will
cause
an
immediate,
• Two CTRL/Cs in succession
unconditional stop, regardless of any I/O operation that may
be pending.
• CTRL/C has the following effect on files:
Files opened in
the output
(0) mode are lost, since they cannot be closed.
Files opened in the update (U) mode may not have all changes
incorporated in them.
• The CTRL/C command can be disabled from within a
DIBOL program by means of the external subroutine FLAGS.
See the
DIBOL-ll Language Reference Manual.

5.4

TSD CHARACTERISTICS

This section applies only to the nonextended memory time-sharing
gram identified as TSD.

5.4.1

pro-

System Requirements for TSD

For TSD, you must SYSGEN for either the SJ, FB, or the XM monitor.
However, even if you use TSD with the XM monitor, you will not be able
to access extended memory.

5-14

CTS-300 OPERATING SYSTEMS

5.4.2

Running the TSD System Program

Once the TSD program has been properly built via CTSGEN, time sharing
can begin.
Load and execute the time-sharing program (TSD RTS) by
using the monitor's RUN command in the form:
.R fi1nam.ext or .RU dev:fi1nam.ext
where:
dev:

is the name of the device where the TSD RTS program
resides.
If not specified, the system device is assumed.

fi1nam.ext

is the name and extension of the TSD RTS.
The name is
the one specified in answer to the last question in
CTSGEN.
See Chapter 6.
Regardless of the file name
you choose, TSD will always identify itself as TSD.

Once started, the TSD RTS identifies itself by displaying the
ing message at each of the terminals that it recognizes:

follow-

TSD VERSION VBnn-nn

*
where:
nn-nn

is the version number.

(*)

the prompting character, indicates readiness to accept
a command from the keyboard.
At this point, any program linked for time-shared operation can be run.

5.4.3

TSD Memory Allocation

The allocation of memory for a TSD System is shown in Figure 5-2.
56 KB
RMONSJ
and
System Handler
48 KB . . . - - - - - - - - - - - Device Handlers

free memory
(30 KB)
Used by TSD run-time
system for TSD user
programs or application

18KB . . . - - - - - - - - - - - -

TSD
without ISAM or DDT

Figure 5-2

TSD Memory Allocation
CTS-300 OPERATING SYSTEMS

5-15

5.5

XMTSD CHARACTERISTICS

This section applies only to the extended memory time-sharing
identified as XMTSD.

program

The use of virtual overlays supported in RT-II V4 makes it possible to
run a Save image program using virtual overlays as either a background
or as a foreground job. Because only XMTSD of the two time-shared
system programs uses virtual overlays, only XMTSD can be run as either
a foreground or as a background program.
As will be seen,
this results in some unique capabilities.
As explained in Section 5.3.9, the RUN command can be used
in any
time-shared RTS to execute a program.
It is also possible under XMTSD
to execute a program simply by specifying the name of the program.
For example:
*PROG <CR)
will cause program PROG.TSD to be executed. Because of this, the command to attach a program or to display detached programs must be issued as A and not as ATTACH under XMTSD because ATTACH would be interpreted as a program.

5.5.1

System Requirements for XMTSD

XMTSD requires that the XM monitor be selected during SYSGEN.
If you
intend to run XMTSD as a foreground program and plan to communicate
with the background (see Section 5.5.2), implicit job startup must be
selected during CTSGEN.
There is no other special requirement, nor
are special questions asked, either for building the XMTSD system or
for the foreground / background run capability.

5.5.2

XMTSD in the Foreground

If you choose to run XMTSD as a foreground job, the time-shared programs are restricted to running in the extended memory region.
This
frees a part of lower memory for use by other programs.
These other
programs could be Save image programs such as PIP, DUP, DIR, DICOMP,
LINK, or SUD programs.
When XMTSD is running as a foreground program,
it is possible for
XMTSD to communicate with a special program (supplied with CTS-300)
running in the background.
XMTSD has, as part of its system, a queuing routine for directing requests to this special background program.
The next several subsections explain the communication process.

5-16

CTS-300 OPERATING SYSTEMS

5.5.2.1

Foreground Queue Program

Foreground communication with the background is initiated via a special series of commands which are similar to DCL commands.
It is important to note that these commands are, in reality, TSD programs constructed to implement the communications capability. The function of
each is covered in detail in Section 5.5.2.3.
A time-shared queue
manager program, BGMAN.TSD, a part of XMTSD, is automatically invoked
whenever one of these commands is issued.
If BGMAN.TSD is not already
running,
it is started up in a detached state to respond to the command request (hence the need for implicit job startup).
The request
is queued
(16' requests maximum) by BGMAN.TSD and if the request requires it, the information is sent to the special background program.
BGMAN.TSD will also accept input from a user-written program.
The
same rules and limitations, covered in detail in Section 5.5.2.3 for
the SUBMIT,
CANCEL, and SHOW commands apply to input from
a
user-written program.
See Section 5.5.2.5 for more information on
user-written programs.
BGMAN.TSD has, as part of its code, a timing facility to allocate processor time between the foreground and the background. When BGMAN.TSD
is started up, it automatically assigns a value of one to this timer.
A value of one allocates 1/60th (or 1/50th - depending on the system
clock) of a second to background operation for each XMTSD scheduler
cycle.
This allocation can be changed when the job is submitted to
BGMAN (see SUBMIT, Section 5.5.2.3). The value is returned to one
once the submitted request has been carried out. The advantage of increasing this value is to allocate a greater proportion of time to the
submitted background job.
This allows the job to execute faster;
however, foreground programs will slow down proportionately.
If BGMAN.TSD has no pending requests in its queue, it will terminate
itself.
It is started (implicitly) later if there is a need for it to
be involved.

5.5.2.2

Background Listener Program

The background program supplied by CTS-300 to receive the requests
(indirect files) from the foreground is called LISTNR.SAV.
This program is run at the console terminal by the user once XMTSD is running
in the foreground.
The command and response are:
.R LISTNR
CTS300 V6 LISTENER
When the indirect file from the foreground is received by the listener
program in the background, the listener program displays the following
message:
BYE

CTS-300 OPERATING SYSTEMS

5-17

and then builds a one-block system indirect
which contains:
@FILE.COM

file

called

SYSTEM.BRG.

iUSER PASSED INDIRECT FILE
iRECONSTRUCTED FOR THE RT-ll SYSTEM
iRESTART LISTENER

.R LISTNR

The listener submits the user request to RT-ll by chaining to
SYSTEM.BRG.
After the commands within the indirect file are processed, the listener is again started up.
The listener displays the
version message and informs XMTSD (BGMAN.TSD) that the job is done and
that it is ready to receive the next command with its associated instructions in the form of another indirect file.
At this time
BGMAN.TSD also resets the background time allocation value to one.

5.5.2.3

Communications Commands

The special DCL-like communication commands provide the interface
between the keyboard and the foreground queue manager (BGMAN). These
commands are described in this section.
The function of both the
foreground queue manager and the background listener programs in
response to each command is illustrated in Figure 5-3.
Reference to
this figure may help clarify the commands which follow.
~ YURPRG.TSD

SUBMIT.TSD

BGMAN.TSD
• communicates with
foreground request
programs
• manages request
'queue
• communicates with
background

h~~
SHOW. TSD ...

~_~

__________

/..~0
q,Ci)
0
<i 0~·0~

~~...

CD
C)

:!:

foreground

.:J!.

-------------------------------~
background

(.)

I
CTS-300 OPERATING SYSTEMS

'--------- CANC EL. TSD

...
(.)

:sc:
.- .-----------------------------_.-

LlSTNR.SAV

Figure 5-3
5-18

;;::::

BGMAN

Error messages associated with the foreground / background
tions commands are listed in Appendix B, Table B-4.

communica-

SUBMIT
This command is used to present a previously constructed indirect file
to the background listener program.
The response to the command is a
request to the user for an indirect file name.
The indirect file previously constructed by the user is typically a list of instructions to
be perf~rmid in the background. After receiving the indirect file
name, the command-processing program
(SUBMIT.TSD) issues a SEND to
BGMAN.TSD.
The SUBMIT program recelves a response indicating the
status of the request and passes it to the user.
The command processing program then terminates. To run SUBMIT, the DCL-like command
is
entered in response to XMTSD's asterisk prompt:
*SUBMIT <RET>
SUBMIT prompts for identification of the indirect file:
_FILE/[n] :filspec/n
where:
filspec

is the file specification of the desired indirect file.
The default file extension is .COM. More than one file
may be specified, if so, they are separated by commas.

is an optional number specified by the user to allocate
the time available for background processing.
It
allocates 1/60th (or 1/50th) of a second to background
operation for each XMTSD scheduler cycle (see Section
5.5.2.1). The usable range is from 1 to an upper limit
determined by the particular application parameters.
Two digits are allowed but anything greater than a
single number usually has an unacceptable effect on the
foreground.
The default value of n is 3.

SUBMIT.TSD returns a message indicating the status of your request:
Assume that jobs A.COM and C.COM, requested from terminal 1, are already in queue with the default time allocation of three and that a submission request is made for a job B.COM from terminal 2 as follows:
_FILE/[n] :B/5

CTS-300 OPERATING SYSTEMS

5-19

The response is:
BACKGROUND QUEUE STATUS
ENTRIES:
3
CURRENT JOB:

DK:X.COM

TERMINAL

FILENAME

TIME ALLOC

I
I
2

DK:A.COM
DK:C.COM
DK:B.COM

3
3

*** END ***
The current job listed above is the file being processed at
the command was issued.

the

time

SHOW
The SHOW command allows you to determine the status of your request at
some time after a request was submitted.
SHOW does not communicate
with the background.
It simply receives a response from BGMAN.TSD regarding the contents of the queue file.
The command is entered in
response to XMTSD's asterisk prompt:
*SHOW <RET)
The response format is identical to that
command above.

illustrated

the

SUBMIT

The SHOW command can be used to determine if the background listener
program is running.
If the listener is not running, an error message
appears informing you of this fact.
CANCEL
The CANCEL command is issued whenever you want to retract a
request
while it is still in the BGMAN processing queue.
The command is entered in response to XMTSD's asterisk prompt:
*CANCEL <RET)
CANCEL prompts for identification of the indirect file(s):
_FILES:filspec
where:
filespec

5-20

CTS~300

is the file specification of a previously submitted indirect file.
All files with the same file specification are canceled.
The default extension is
.COM.
More than one file may be specified, if so, they are
separated by commas.

OPERATING SYSTEMS

CANCEL returns the status of the queue thereby showing the file del~t~\
ed.
For example, a CANCEL request sequence for job A.COM (assuming \
A.COM, B.COM, and C.COM are in queue), would be:
FILES:A
The response is:
BACKGROUND QUEUE STATUS
ENTRIES:
2
CURRENT JOB:

DK:X.COM

TERMINAL

FILENAME

TIME ALLOC

DK:C.COM
DK:B.COM

*** END ***
The current job listed above is the file being processed at
the command was issued.

5.5.2.4

the

time

BGMAN.TSD Operation

An understanding of the operation of BGMAN.TSD in relation to both the
requests submitted to it and the responses it returns is essential to
anyone writing a program to be used as a special DCL-like command in
the same way that SUBMIT and CANCEL are used. BGMAN.TSD interfaces
with such a program via a message record.
The details of this record
and its use in communicating with BGMAN are the subject of this section.
The message record is structured identically for both requests and
responsesi
however, some fields are used differently.
For this
reason the record is shown and discussed from both viewpoints.
The format of the message record for requests is:
RECORD CDMESS
Fl,

F2,
F3,
F4,
F 5,

A2
D2
AlO
A14

iREQUEST CODE DEPENDENT (SEE
iREQUEST CODE 01 BELOW)
iREQUEST CODE (SEE BELOW)
iTERMINAL NUMBER
iORIGINATING PROGRAM NAME
iINDIRECT FILE SPECIFICATION

CTS-300 OPERATING SYSTEMS

5-21

Request Codes
There are five request codes
(field F2)
recognized
BGMAN.TSD. They are listed with their function below:

Request Code

Function

Enters the information specified in fields F3, F4, and
F5 into the BGMAN queue.
If a background time allocation other than three is desired, it is specified in
Fl.

Requests a response from BGMAN showing
status. The other fields are unused.

Requests that the file (if still in the queue)
specified
in F3, F4, and F5 not be processed when it is encountered in the queue.

Same as 01 except for the expected
responses for request code 04).

response

(see

Same as 01 except for the expected
responses for request code 05).

response

(see

The format of the message record for receiving responses is:
RECORD CDMESS
Fl,

F2,
F3,
F4,
F5,

5-22

input

AI0
A14

;RESPONSE CODE DEPENDENT (SEE
iRESPONSE CODE 12, BELOW)
iRESPONSE CODE (SEE BELOW)
iUNUSED
iUNUSED
iRESPONSE CODE DEPENDENT (SEE
;RESPONSE CODES 13 AND 14, BELOW)

CTS-300 OPERATING SYSTEMS

the

queue

Response Codes
The possible response code(s) (field F2) received by
BGMAN.TSD depends on the original request.

Request
Code

Response
Code

program

from

Meaning

The entry has been accepted,

or one of the following:

The queue is full and
been rejected.

the

request

has

The indirect file was not found.

A device handler required by an element
of the indirect file is not available.

The special background listener
is not running.

The queue is empty,

program

or the following series:
The following responses to 02 occur as a series of messages with the
codes appearing sequentially in the order shown.
Therefore, you will
have to do successive receives and process each message as it is received.
The codes received will be 12, 13, 14 (possibly multiple) ,
and finally 19.

The number of jobs in queue is contained
in Fl.

The current job name is contained in F5.

A queue entry is contained
in
F5.
Repeated messages with this code will
probably be sent by BGMAN until all
queue entries are sent.

Signals
BGMAN.
passed.

The queue is empty,

the
All

end of the report
queue entries have

from
been

or the following series:
12, 13, 14, 19 A cancel request (03) automatically includes a request for a queue status report (see responses to request code 02).

CTS-300 OPERATING SYSTEMS

5-23

Entry accepted,

followed by:
40

Job completed,

or the response if there is an error is one of the
following codes:
20, 22, 23, 30 Same as for request 01.
05

Entry Accepted,

followed by the series:
12, 13, 14, 19 An 05 submission request automatically
includes a request for a queue status
report (see responses to request code
02).
The SUBMIT.TSD program supplied
with CTS-300 uses this code.
or the response if there is an error is one of the
following codes:
20, 22, 23, 30 Same as for request 01.

5.5.2.5

User-Created Commands

The ability to execute a program under XMTSD by simply entering its
name, the capabilities of XMTSD running in the foreground, and the
special background program (LISTNR), enable you, the user, to create
your own programs to be executed as commands.
Several unsupported utilities have been included in the V6 distribution of CTS-300.
These are designed as examples to illustrate how
utilities can be created to perform various functions.
They are furnished in both DIBOL source code and as XMTSD executable programs.
These utilities present messages based on the following codes:
Code
10
20
22
23
24
25
26
30
40
90

5-24

Message
ENTRY ACCEPTED
QUEUE FULL-ENTRY REJECTED
FILE NOT FOUND
HANDLER NOT FOUND
I/O ERROR
DEVICE IN USE
DIRECTORY I/O ERROR
BACKGROUND LISTENER NOT RUNNING
REQUEST DISCARDED
JOB COMPLETED
ILLEGAL BACKGROUND OPERATION

CTS-300 OPERATING SYSTEMS

A short description of each utility follows:
CREATE.TSD

This program asks for an output file name and transfers
keyboard
input into that field.
It is suitable for
creating short indirect command files for submission to
the background.
It produces the following prompt line:
-FILE:
The default extension is
.COM.
Errors are reported
for:
22 and 23. CREATE.TSD is terminated with a CTRL/Z.

COPY. TSD

This program ask for the standard command string
input
without wild card
features.
It copies an ASCII text
file from the input to output.
The prompt character is
an asterisk.
It is of the form:
DEV:FILEOUT.EXT=DEV:FILEIN.EXT
Err 0 r s are r e po r ted for:

DELETE.TSD

22, 23, 24, 25, and 26.

This program is used to delete a file from a TSD keyboard.
It accepts multiple file specifications separated by commas.
There may be up to eight files.
The
prompt is:
-FILES:
Errors are reported for:

RENAME.TSD

22,23, and 26.

This program is used to rename a file from a TSD keyboard.
The prompt character is an asterisk and it expects a standard command string input without wild card
features.
The output is the new filename and the input
is the old filename.
DEV:NEWNAME.EXT=DEV:OLDNAME.EXT
Errors are reported for:

TYPE.TSD

22,

23, and 26.

This program asks for a file name without wildcard features,
reads the file, and writes it to the terminal.
It reads ASCII text files only.
The default extension
is
.DBL.
It is suitable for examining DIBOL program
source code without having to
use an editor.
The
prompt is:
-FILE:
Errors are reported for:

PRINT.TSD

22,

23, 24, and 26.

This program accepts multiple file specifications without the wild card feature and submits them to the line
printer spooler.
The prompt is:
-FILES:
Errors are reported for:

22,23,24, and 26.

eTS-300 OPERATING SYSTEMS

5-25

VIEW.TSD

This program is a modified version of RTEXIT and
is
used for system monitoring, or for getting job reports
without having to run STATUS. There is no input.

SUBMIW.TSD

This program is an example of how to communicate with
the
background
manager.
It
is
a
submit-and-wait-for-completion command.
It takes multiple file specifications for each request submitted.
The prompt is:
-FILES:
Codes received are:
and 90.

5.5.2.6

10, 20, 22, 23, 24,

26,

30,

40,

Running XMTSD in the Foreground

Once the XMTSD program has been properly built via CTSGEN, time sharing can begin. Assume you have four terminals, including the console
terminal, and that four terminals were selected in both the RT-ll SySGEN and the CTS-300 CTSGEN.
It is recommended that you use the following procedure to execute the time-sharing program and the background listener program.
Load and execute the time-sharing program (XMTSD
foreground RUN command in the form:

RTS)

using

the

.FRUN filnam.SAV
where:
filnam

is the name and extension of the XMTSD RTS as specified
in answer to the last question in CTSGEN (see Chapter
6). Regardless of the file name you choose for your
XMTSD RTS, XMTSD will always identify itself as XM-TSD •
• The extension .SAV must be specified •
• The program must be run from the system device.

Once started, the XMTSD RTS identifies itself by displaying the following message at each of the terminals that it recognizes (in this
case, terminals 1, 2, and 3):
XM-TSD VERSION VCnn-nn

*
where:
nn-nn

5-26

is the version number.

CTS-300 OPERATING SYSTEMS

(*)

the prompting character, indicates readiness to accept
a command from the keyboard. At this point, you may
set terminal characteristics but do not run any program
unless you do not intend to run the listener.

If you want XMTSD to have access to the background, run the listener
program at terminal 0,
the background console.
The command and
response are:
• R LISTNR
CTS300 V6 LISTENER
Enter the following to return to the foreground
programs:

run

time-sharing

CTRL/F
5.5.2.7

Memory Allocation

The allocation of memory for an XMTSD RTS in which XMTSD is run
foreground program is shown in Figure 5-4.

248 KB
~

80 KB

Free memory
Used by XMTSD for
TSD programs

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

XMTSD (Part 2)

56KB ~----------------------------------XM Monitor
and
Device Handlers

40KB

~------------------------XMTSD (Part 1)

32KB ~------------------------USR
28KB ~-------------------------------free memory
• Useable for a background Job
• Not useable for DIBOL
Programs under XMTSD's
control

o
Figure 5-4

Memory Allocation for XMTSD as a Foreground Program
CTS-300 OPERATING SYSTEMS

5-27

5.5.2.8

Applications

When XMTSD is run in the foreground, the system can be thought of as
running
in what is primarily a development mode, because in this mode
many activities normally associated with development are efficiently
handled.
Among these are concurrent development and remote patching.
Possible operation as a production system is also discussed.
Concurrent Development
The entire process of application program development
can
be
undertaken by several users of a time-shared DIBOL system. Any user
at a foreground terminal can edit and debug under XMTSD.
The DIBOL
editor DKED.TSD (see Chapter 3 in this manual) can be used to create
and edit source files.
These files can be DIBOL programs or indirect
files
consisting
of
commands to be sent to the background.
Furthermore, by communicating with the background program,
LISTNR,
programs can be compiled and linked.
Note that when compiling programs in this mode you must use the /G option to create an error log file which will contain possible errors.
See Chapter 4, DICOMP, for more information.
Remote Patching
Since it is possible for a remote terminal to communicate with the
foreground program XMTSD and, through it, with the background, any remote terminal can be used to perform system maintenance,
including
patching.
Production Mode
While running XMTSD in the background l is considered the conventional
production mode (see Section 5.5.3), it is possible that running XMTSD
in the foreground could be useful
in some production environments.
This would be an application that could make use of the background
processing capability.
In such a situation, you would probably want all terminals,
the console terminal, to be available for production use.
plish this you must:

including
To accom-

• Suppress the CTS300 V6 LISTENER and BYE commands generated by
the listener.
This is done by running RT-ll PATCH and setting location 1000 in LISTNR.SAV to a one.
• Set TT:QUIET for the console terminal.
I

• Ensure that the background o~eration you are performing
not output to the terminal.
"

does

• Be sure not to enter a CTRL/B which would attach the terminal
to the background.

5-28

CTS-300 OPERATING SYSTEMS

5.5.3

XMTSD in the Background

This is the conventional mode of operation in which XMTSD has the same
capabilities and limitations (except, of course, for the greater memory capacity) as TSD running with the non-extended memory monitor.

5.5.3.1

Running XMTSD in the Background

Once the XMTSD program has been properly built via CTSGEN, time sharing can begin. Load and execute the time-sharing program (XMTSD RTS)
which must be on the system device by using the monitor's RUN command
in the form:
.R filnam.ext
where:
filnam.ext
is the name and extension of the XMTSD RTS as specified
in answer to the last question in CTSGEN. See Chapter
6.
Once started, the XMTSD RTS identifies itself by displaying
lowing message at each of the terminals that it recognizes:

the

fol-

XM-TSD VERSION VCnn-nn

*
where:
nn-nn

is the version number.

(* )

the prompting character, indicates readiness to accept
a command from the keyboard. At this point, any program linked for time-shared operation can be run.

CTS-300 OPERATING SYSTEMS

5-29

5.5.3.2

Memory Allocation

The allocation of memory for an XMTSD System in which XMTSD is running
as a background program is shown in Figure 5-5.
248 KB

free memory
Used by XMTSD for
TSD programs

80KB ~---------------------------------

XMTSD (Part2)

56KB~------------------

_____

XM Monitor
and
Device Handlers
40 KB ~----------------------USR
36 KB

t---------------------free memory
Used by XMTSD for
TSD programs

8 KB

t------------XMTSD (Part 1)

o
Figure 5-5

5.5.3.3

Memory Allocation for XMTSD as a Background Program

Applications

When XMTSD is run in the background (as contrasted with running in the
foreground),
the system can be thought of as running in a production
mode. All the system resources, including lower memory and console
terminal, are available for the day-to-day needs of application programs under the control of the run-time system.
5-30

CTS-300 OPERATING SYSTEMS

5.6
5.6.1

TERMINATING TIME-SHARED OPERATION (RTEXIT)
Running RTEXIT

The RTEXIT program is used to terminate the operation of the
time-shared system and the programs operating under its control.
The
procedure is the same for both TSD and for XMTSD when run in the background.
For XMTSD in the foreground, see Section 5.6.3.
For TSD and
XMTSD
(background)
the following command is entered while
the
time-shared system is operating:

* R RTEXIT
If no jobs are running, control returns immediately to the RT-ll monitor.
If other jobs are running, the response is:
DO YOU WISH AN ABSOLUTE SHUTDOWN?

(Y-N)

(N)

An answer of Y causes any job currently running to be unconditionally
terminated with unpredictable results for that job.
If you answer N
(or CR), RTEXIT will display the current status of jobs every 20 seconds until such time as~all jobs are done. At this time, control returns to the RT-ll monitor. You may cancel the current status display
by entering a CTRL/C at any time.
This will allow you to run RTEXIT
again and to select the absolute shutdown.
5.6.2

Chaining to RTEXIT

RTEXIT may be automated by having the preceding program chain to it
with the SEND statement. This operation is essentially the same as
the situation where RTEXIT is run manually;
it has the same restrictions as XMTSD when it is run in the foreground.
The sequence for a
program running under a time-shared operating system program
(except
XMTSD in the foreground) could be:

SEND ('MSG','RTEXIT.TSD ' )

STOP 'RTEXIT.TSD '
The message 'MSG ' is optional. When used with RTEXIT, it contains a
file name and, separated by a space, an optional alpha character.
The
file name is that of a file to be executed once the time-shared program is terminated and could be a Save image program (.SAV) or an indirect file.
The alpha character is the response to the absolute
sh~tdown
question.
An absolute shutdown occurs if the character is
absent.
If the program preceding the running of RTEXIT is detached,
the shutdown is always absolute regardless of the presence of the N
alpha character in the message.
CTS-300 OPERATING SYSTEMS

5-31

5.6.3

RTEXIT for XMTSD in the Foreground

When XMTSD is operating in the foreground, the selection of RTEXIT is
somewhat more involved, because of possible interaction between foreground and background at the time RTEXIT is run.
See below for an example of the steps that may be required.
To start time-sharing XMTSD in the foreground:
.FRUN XMTSD.SAV
at the background terminal:
.R LISTNR
To terminate the listener which is running in the background, enter:
CTRL/C
to terminate XMTSD which is running in the foreground, enter:
*R RTEXIT
DO YOU WISH AN ABSOLUTE SHUTDOWN?

(Y-N)

(N)

<CR>

When all the jobs are complete and XMTSD terminates,
terminal, enter:

the

consol~

UN F
This unloads the foreground job which is XMTSD.

5.7

UTILIZING RESOURCES ON A SMALL SYSTEM

The relatively limited capacity and access speed of a diskette,
especially when used as the system device, make careful planning
necessary if you want to make the best use of your system.
The
following guidelines are presented to make you aware of what may be
done:
•

Include only the essential programs, data
and options •

files,

utilities,

• Use the SEGMENT:l option when initializing diskettes prior to
building your system. The result is a two-block directory on
each diskette.
This gives you a directory with a 72-file
capacity and saves six blocks (two blocks per segment) of
diskette space.

5-32

eTS-300 OPERATING SYSTEMS

•

If you have an application'program that uses overlays, consider reI inking your overlayed routines, where possible, to
make them a part of the root section of your program.
This
reduces disk access time.
Programs that use overlays heavily
are slower on a diskette system than when run in a system
with faster disks.
The elimination of overlays will, therefore, increase performance.

•

If you set USR to NOSWAP, you reduce the time to open and
close files by 90 percent.
This is recommended as a standard
procedure if you plan to be manipulating files extensively
and if you have the space in memory (the USR requires 4 KB).

• Depending on the size of your application and the functions
you wish to support, you might segregate programs to be used
together and place them on a single diskette. That is, not
all
the capabilities need be placed on the system disk but
could be grouped by logical use onto individual diskettes.
If you swap disks in this way to perform various functions,
you also have to set USR to SWAP so the directory lookups for
program name will work correctly.

5.8

ERROR MESSAGES

The operating system error messages are listed in Appendix A.
Special
error messages generated by the time-shared system program (TSD or
XMTSD) are listed in Appendix B, Table B-3.
The error messages for
the foreground / background communication commands are listed in Appendix B, Table B-4.

CTS-300 OPERATING SYSTEMS

5-33

CHAPTER 6
SYSTEM DEVELOPMENT

6.1

INTRODUCTION

A CTS-300 System is comprised of two major software packages:
RT-ll
and CTS-300.
Both of these are furnished in a form that has the potential for many capabilities but which is probably not immediately or
directly usable by any CTS-300 user.
Each software package should be
tailored to match the hardware and to provide the specific software
capabilities needed for a given user.
In this manual, this process is
called system development.
Both RT-ll and CTS-300 have their own programs and procedures to facilitate developing an optimal system with
minimal memory requirement.

6.1.1

System Generation Programs

RT-ll software is adapted to the hardware and user requirements using
the RT-ll SYSGEN program documented in the RT-ll System Generation
User's Guide.
The RT-ll SYSGEN program is modified slightly for
CTS-300 users, and these modifications are explained in this chapter.
CTS-300 software (both single-user and multi-user) is adapted to the
user's requirements with a program called CTSGEN.
CTSGEN is described, in detail, in this chapter.

6.1.2

Chapter Organization

The remainder of this chapter is comprised of three major sections.
The first,
Section 6.2, CTS-300/RT-ll SYSGEN, describes RT-ll SYSGEN
as it applies to CTS-300.
The second, Section 6.3,
CTSGEN,
provides
detailed information on theCTSGEN program. This includes the actual
CTSGEN dialog and information to help you make choices.
The third,
and last, section, Section 6.4, Error Messages, is a discussion of
errors that may be encountered during a CTSGEN.

6-1

6.2

CTS-300/RT-ll SYSGEN

The first step in developing a working system is to build an
appropriate RT-ll Operating System. You must run SYSGEN to select the
RT-ll monitor services and device handlers you require.
Since the
RT-ll dialog is long and repetitive, an optional, shorter list is
provided for CTS-300 users.
This shorter version is known as
CTS-300/RT-ll SYSGEN.
The first question asked in the CTS-300/RT-ll SYSGEN allows you to
choose either the CTS-300/RT-ll version or the full RT-ll SYSGEN as
described in the RT-ll documentation. The CTS-300/RT-ll version is
different in that it rephrases some questions and provides a programmed selecti~n of certain routinely chosen answers to selected
questions.
Users for whom the programmed answers are valid (most
CTS-300 users)
can save time and prevent errors by
selecting
CTS-300/RT-ll SYSGEN.
The questions that have been rephrased are:
Question

Change

Asks:

Do you want the extended memory (XM) monitor?
Default answer has been changed to a Y.

Q12

Was:
Now:

Do you want multiterminal support?
Are you going to use TSD with this monitor?

RT-ll's Q89 to Q93:
Line printer support questions have been
removed
and replaced in CTS-300/RT-ll by Q152
through Q164.
The TSD multiterminal support handles
a maximum of four line printers in any combination
of parallel and/or serial.
Q152 Asks:

How many line printers in all?

Q153 Asks:

Is the first line printer (LP) parallel?
fa u 1 t i s a Y; jan s we r wit han N i f s e ria 1 )

Q154 and Q155:

de-

ask for CSR and vector addresses.

Q156 through Q158 Ask: as in Q153, 154, and 155, the same
tions for the second line printer (LQ) .- "

ques-

Q159 through Q16l Ask: as in Q153, 154, and 155, the same
tions for the third line printer (LR).

ques-

Q162 through Q164 Ask: as in Q153, 154, an~, 155, the same
tions for the fourth line printer (LS) •

ques-

RT-ll's Q152 through Q155 have been renumbered
to Q165, Q166, Q167, and Q168.

6-2

(the

SYSTEM DEVELOPMENT

CTS-300/RT-ll

The answers automatically provided with CTS-300/RT-11 SYSGEN are:
Question

Answer

Baseline single-job monitor

SJ timer support

Yes

Error message to replace system halt
upon receipt of a system I/O error
for the single-job monitor

Yes

QlO

.SPCPS request

Q11

Idle loop light pattern

Q13

Asynchronous terminal status

Yes

Q23

KWll-P clock as the system clock

Q25

Floating point support

Q5l

TCl1 DECtape support

Q52

RF-l1 fixed head disk support

Q54

RJS03 or RJS04 disk support

Q88

TA-ll cassette support

Q96

PC-II high speed paper tape reader/punch

Q97

PR-ll high speed paper tape reader

Q100 VTll or VS60 graphics support

Q168 Retention of system OBJ's

Answered as a YES only if you have answered YES to
TSD; otherwise, it is not preanswered.

Q12

for

If you wish to change any of the automatic selections, answer NO to
the first question in CTS-300/RT-ll SYSGEN. By responding NO, you
will have entered the full RT-1l SYSGEN, and you will then be asked
the first question in the RT-l1 SYSGEN.
If you choose RT-1l SYSGEN,
and you plan to run a time-shared DIBOL program, you must choose
mu1titermina1 support
(Q12)
and answer YES to asynchronous terminal
status (Q13).
Whether you choose CTS-300/RT-ll SYSGEN or RT-ll
SYSGEN, you should refer to the RT-ll System Generation Manual before
you start.
When you have completed your CTS-300/RT-l1 SYSGEN (or
you will have to run CTSGEN.

RT-ll

SYSGEN),

SYSTEM DEVELOPMENT

6-3

6.3

CTSGEN

The CTSGEN program is the CTS-300 Operating System Program generator.
It is an interactive program that is used to select the parameters associated with a CTS-300 system.
It can create a run-time code interpreter for a Single-User DIBOL (SUD) program, or it can create both a
code interpretor and run-time system executive for a time-shared
(TSD
or XMTSD). As with the RT-ll SYSGEN, it is wise to plan ahead exactly
what your requirements are before building the CTS-300 system.
It may
help if you read Chapter 5, CTS-300 Operating Systems, before initiating any CTSGEN activity.

6.3.1

Characteristics

6.3.1.1

Choices

CTSGEN allows you to build either a Single-User DIBOL RTS program or a
Time-Shared DIBOL RTS program.
Single-User System
If you are building a SUD system, the choices are limited to
lection of two system services. You may select:

the

se-

types

support for ISAM files
support for DDT
Time-Shared System
If you are building a time~shared RTS, there are two
support services you may select:

basic

Run-time system services you may select are:
number of programs
number of messages stored
number of channels opened per program
support for ISAM files
support for the XM monitor (and residency of USR)
support for DDT
support for implicit or forced-job startup
auto job startup upon completion of the time-shared RTS load
Peripheral device support you may select:
standard (or non-standard) terminals
local or remote terminal use
DLll or DZll terminal interface
mechanical operating characteristics of each terminal
total number of different peripheral devices
6-4

SYSTEM DEVELOPMENT

6.3.1.2

Preliminary Requirements

As you did with SYSGEN, you must plan ahead for your CTSGEN session.
Acquaint yourself with the flow of CTSGEN by using the chart, Figure
6-1, in Section 6.3.2 and by reading the dialog and responses in the
following sections for the system you intend to build.
It is important to remember your SYSGEN responses dealing with terminals, because
they affect your answers in CTSGEN.

Single-User System
The following modules are necessary for building
They must be on the system disk.
CTSGEN.SAV
LINK.SAV
MACRO.SAV
SUD.RTS

ELONG.OBJ
DDT.OBJ
DDTX.OBJ
SDIRT.OBJ

single-user

RTS.

ISAM.OBJ
ISAMX.OBJ
MATH.OBJ
IO.OBJ
JOB.OBJ

Time-Shared System
Use the lists in Section 6.3.1.1 and note the peripheral devices on
your system and the run-time system services you require for your application.
The following modules are necessary for building a
(TSD and XMTSD). They must be on the system disk.
CTSGEN.SAV
LINK.SAV
MACRO.SAV
SUD.RTS
SYSMAC.SML
QC.MAC
ST.MAC
TO. MAC
TSDTBL.MAC
DEFS.MAC
TSDDFN.MAC

DMESS.OBJ
DJOB.OBJ
DISAM.OBJ
DISAMX.OBJ
DESHRT.OBJ
DELONG.OBJ
FRUNIT.OBJ
FRUNXX.OBJ
DDDT.OBJ
DDDTX.OBJ
DMATH.OBJ
DDIRT.OBJ
DTO.OBJ
DIO.OBJ
DTOINI.OBJ

time-shared

RTS

KDMESS.OBJ
KDJOB.OBJ
KISAM.OBJ
KISAMX.OBJ
KESHRT.OBJ
KELONG.OBJ
KFRUN.OBJ
KFRUNX.OBJ
KDDT.OBJ
KDDTX.OBJ
KMATH.OBJ
KDIRT.OBJ
KDTO.OBJ
KDIO.OBJ
KTOINI.OBJ
KCORE.OBJ

SYSTEM DEVELOPMENT

6-5

6.3.1.3

Question Types

Each CTSGEN question has a default answer. That default is noted
immediately after the question and is placed within parentheses. After
each question is displayed, you respond by typing the desired entry or
by typing a carriage return (CR) to select the default.
There are two kinds of questions in CTSGEN:
• Questions that require a Y or an N response •
• Questions that require a numeric response.
Unlike SYSGEN, there is no need to specify numbers in octal.
Questions that require a numeric response accept only decimal numbers.
The default value is contained in parentheses immediately following
the question.
If you need to change your response to a previous question, you may
return to that question by entering Q followed by the question number.
Take special care when responding to questions that require other than
Y, N, or a default value.

6.3.2

CTSGEN Dialog

This section describes the dialog in detail. All text~ questions, and
responses displayed during the dialog are described.
However, during
any run of CTSGEN some of these questions and comments will not appear, since their occurrence may depend on the answers to previous
questions.
Like SYSGEN, CTSGEN dialog has two forms.
There is a short form with
the question and the default answer only and a longer form which presents the question and explanatory comment. The short form is the default;
however, when you enter a question mark (or an invalid response) in response to a CTSGEN question, the program repeats the question
(and default)
along with explanatory comments on the question
displayed.
Those comments can guide you through a CTSGEN session, and
if you are not experienced with CTSGEN, this longer session will help
you to be sure of the implications of your answers and to avoid inaccurate responses.
If you are familiar with CTSGEN, use the short
form.
Figure 6-1 illustrates the flow of questions in CTSGEN.

6-6

SYSTEM DEVELOPMENT

SYSTEM SELECTION

.R CTSGEN
1. CHOOSE SUDGEN [SI OR TSDGEN
I

TERMINAL SELECTION

m: (T)

4. ARE ALL TERMINALS STANDARD? (Y)

____________~

I~Y

6. HOW MANY LOCAL (DLlIl TERMINALS TO BE USED
other related questions
7. HOW MANY REMOTE (DLIIl TERMINALS TO BE USED
other related questions
8. HOW MANY LOCAL (DZIIl TERMINALS TO BE USED
other related questions

5. HOW MANY TERMINALS TO BE USED

9. HOW MANY RE~OTE (DZI!) TERMINALS TO BE USED

HARDWARE
SOFTWARE
CHARACTERISTICS
10. HOW MANY PROGRAMS TO RUN (4)
11. HOW MANY TOTAL MESSAGES TO BE STORED IN
MEMORY (8)
12. HOW MANY KINDS OF DEVICES TO BE USED (4)
13. HOW MANY TOTAL CHANNELS TO BE USED (12)

USR TO BE L~]~:::::R:E,:SEI ~NI

HOW MANY TOTAL]ILES OPEN FOR UPDATE (6)

ISAM FILES
15. ARE ISAM FiES TO BE USED (N)

if XMTSD

if not 'XMTSD

t
HOW MANY TOTAL ISAM

2. ARE ISAM FILES TO BE USED: (N)

FILES TO BE USED (3)

MAN~

HOW
ISAM
VOLUMES/FILE: (2)
DDT
16. IS DDT TO BE USED: (N)

BRIEF ERROR M~:S

3. IS DDT TO BE USED (N)

L..----r-----'

PROGRAMMED
START UP

17. IS IMPLICIT JOB START UP TO BE USED (N)

IS FORCED JOB ~TART UP TO BE USED (N)

I
18. IS AUTO JOB START TO BE USED (N)

PROGRAM NAME
J
RUN TIME SYSTEM
NAME
19. DO YOU NEED TO CHANGE AN ANSWER (N)

REENTER AT QUESTION:

if TSD: ENTER THE NAME OF THE SAVE FILE
if SUD: file is assigned name SUD:RTS

Figure 6-1 CTS-300 Operating System Generator (CTSGEN)
SYSTEM DEVELOPMENT

6-7

The following is the actual CTSGEN dialog and explanatory text.
It is
broken into sections in this manual to identify more clearly the activity taking place. The dialog is shown in upper case only. The explanatory material is shown in both uppercase and lowercase.
CTSGEN is executed with the following command;

it responds as

shown:

.R CTSGEN
CTSGEN Vnn-nn
EACH OF THE FOLLOWING QUESTIONS IS FOLLOWED BY A DEFAULT
RESPONSE IN PARENTHESES. THIS RESPONSE WILL BE USED
IF A <CR) IS TYPED IN ANSWER TO THE QUESTION.
IF A
QUESTION MARK OR ANY ILLEGAL RESPONSE IS TYPED, FURTHER
INFORMATION CONCERNING THE CURRENT QUESTION WILL BE PRINTED
AT THE TERMINAL. IN GENERAL YOU MAY RETURN TO ANY OF THE
QUESTIONS THAT ARE MARKED WITH A LINE NUMBER. SIMPLY TYPE
THE LETTER Q FOLLOWED BY THE LINE NUMBER. (I.E. Ql, Q3, QlO)

6.3.2.1

Single-User or Time-Shared System

The first question in CTSGEN:
1.

CHOOSE - SUDGEN [S] OR TSDGEN [T]:

(T)

Respond with S if you are going to build a single-user system or with
T (or CR)
if you are going to build a time-shared system.
If you
answer T, Q4 will appear. See Section 6.3.2.3.

6.3.2.2

Single-User System

There are only two questions asked for a single-user system:
2.

ARE ISAM FILES TO BE USED:

(N)

Choosing ISAM costs approximately 4.2 K bytes.
Respond with N (or CR) if you do not plan to use ISAMfiles.
with Y if you do plan to use ISAM files.
The next question:
3.

IS DDT TO BE USED:

Respond

(N)

Choosing DDT costs approximately 1100 bytes.
Respond with N (or CR) if you do not plan to use the DIBOL
program, DDT.
Respond with Y if you do plan to debug.

6-8

SYSTEM DEVELOPMENT

debugging

With your answer to this last question, CTSGEN proceeds to automatically build a run-time code interpreter for Single-User DIBOL (SUD)
programs. The name of the interpreter is assigned by CTSGEN to be
SUD.RTS.
This file must always be on the system disk for your SUD
system.
In addition, a link map (SUD.MAP) is generated which may help
identify problems with the interpreter.
It is advised that you rename CTSGEN.COM to SUDGEN.COM using the
mand string:

com-

• RENAME CTSGEN.COM SUDGEN.COM
You can not run any Single-User DIBOL program, not even CTSGEN, without SUD.RTS.
The SUDGEN.COM that you just made is a backup you can
use to recreate the same SUD.RTS selected by questions 2 and 3 above.
All you have to do is type @SUDGEN.
This can be very helpful if you
should accidently destroy your SUD.RTS.
Every time you run a CTSGEN,
a new CTSGEN.COM is generated. For this reason, you must rename the
CTSGEN.COM to SUDGEN.COM after this CTSGEN and before another.
It is permissible, and often useful, to create several versions of
SUD.RTS and store them for later use.
There-are four possibilities by
choosing to support (or not support) ISAM and/or DDT.
The distribution version is without ISAM or DDT support.
However, other versions
must be stored with names other than SUD.RTS, since SUD programs automatically look for SUD.RTS when the RUN command is issued. Whenever a
particular version is needed, you simply rename it to SUD.RTS
(after
storing its predecessor under its storage name) and run your SUD programs.

6.3.2.3

Time-Shared System

The first question related to a time-shared system:
4.

ARE ALL THE TERMINALS STANDARD:

(Y)

"Standard" is a term used here solely in regard to the CTSGEN dialog.
A standard terminal
is defined as being either a VT100, VT52, or a
VT50H, each of which has the following attributes:
•

Local DLll interface only

• Master terminal
You cannot initiate a time-shared program at a
nal.

slave

termi-

• Line width of 80 characters
• No CTRL/C trap support
CTRL/C trap prevents a CTRL/C from terminating a time-shared
program.
Such abnormal termination could result in loss or
corruption of data files.
SYSTEM DEVELOPMENT

6-9

If your answer is N, Q6 will be displayed.
6.3.2.5;
but, first, see Section 6.3.2.4.

Q6 is discussed in Section

If your answer is Y or <CR):
5.

HOW MANY TERMINALS TO BE USED:

(2)

You may select up to the number chosen in the RT-ll SYSGEN.
A limit
of 8 is recommended for systems in which terminal input will be heavy;
CTSGEN will permit up to 12. A valid response prompts QIO to be displayed.
See Section 6.3.2.9 to continue selection of other system
parameters.

6.3.2.4

Terminal Specification

Since your response to question 4 was N (your terminals are not all
standard), more information is needed.
Terminal information to be
specified in the following sections of this chapter (CTSGEN questions
6 through 9) depends on the following factors.
Your answers in SYSGEN set the limits for your answers in CTSGEN.
SYSGEN used your answers to assign hardware interfaces to support the
terminals. CTSGEN asks you which of these terminals you want your
time-shared program to recogn-ize.
CTSGEN terminal questions are presented in the same four categories as
in SYSGEN:
DZll local, DLll remote, DZll local, and DZll remote.
In
each category you are asked how many terminals are to be used and how
many are to be unused. The total (used and unused) must equal the
SYSGEN assignment for that category.
Additional information pertaining to these terminals is also asked
each of the four categories.

6.3.2.5

Local DLll Terminals

This series of questions pertains to local terminals on the
terface.
6.

HOW MANY LOCAL (DLll) TERMINALS TO BE USED:

DLll

in-

(4)

Respond with the number of terminals that are connected to DLll
hardware and that are to be used locally. This question was asked in
SYSGEN; your response may be the same or less than your response in
SYSGEN.
You must specify at least one for your console terminal.
HOW MANY LOCAL (DLll) TERMINALS LEFT UNUSED:

(0)

Respond with the number of terminals that are not to be used.
Your
response to the preceding question and the number that you specified
in SYSGEN for local use are important here.
Your answer must be the
difference between those two responses.

6-10

SYSTEM DEVELOPMENT

You have specified how many local DLll terminals are to be recognized
by the time-shared RTS.
Now you must enter the operating characteristics of each one. A series of five questions follows for each terminal noted in the first part of Q6.
TERMINAL n
S TERMINAL n A SCOPE:

(Y)

Respond Y or <CR) if this terminal has a display
(video)
screen.
Respond N if this terminal is a teleprinter (prints out hard copy).
From within a DIBOL program, terminal 1 would be referred to as
terminal o.
IS TERMINAL n A SLAVE:

(N)

Respond N or <CR) if this terminal
is to be a master terminal.
Respond Y if you do not want this terminal to be able to start jobs
with keyboard commands. A Y response means that jobs at this terminal
must be started by forced-job startup.
Remember, if this is terminal
1 (the console terminal), it must be a master terminal.
IS CTRL/C TRAP TO BE USED:

(N)

Respond N or <CR) if you want a CTRL/C to be recognized by the
time-shared RTS.
Respond Y if you want a CTRL/C to be ignored by the
time-shared RTS.
This CTRL/C is not passed to the DIBOL program.
HOW MANY FILL CHARACTERS TO BE USED:

(0)

Respond with a decimal number according to your terminal model as
noted in the following chart.
The chart notes the number of fill
characters required for each terminal model set for the baud rate
shown.
This number provides a delay time to allow completion of the
carriage return/line feed.
VT100
VT50H
VT52
LA36
LA30
LA30
LA30
VT05
VT05
VT05

(set
(set
(set
(set
(set
(set
(set
(set
(set
(set

for
for
for
for
for
for
for
for
for
for

9600 baud)
9600 baud)
9600 baud)
300 baud)
300 baud)
150 baud)
110 baud)
2400 baud)
1200 baud)
600 baud)

0
0
0
0
10
4
2
2
2
1

The next question:
WHAT IS THE LINE WIDTH TO BE USED:

(80)

Respond with a decimal number in the range of 1 through 132
to your terminal model.
This number is usually 80.

according

These preceding five questions appear for each local DLll terminal you
specified in question Q6 until operating characteristics are detailed
for all local DLll terminals to be supported at run time.
Now you
must consider DLll terminals for remote use.
SYSTEM DEVELOPMENT

6-11

6.3.2.6

Remote DLll Terminals

This series of questions pertains to remote terminals on the DLII
terface.
7.

HOW MANY REMOTE (DLII) TERMINALS TO BE USED:

in-

(0)

Respond with the number of terminals to be used that are connected to
DLII hardware and that will Qe used in a remote mode. This question
was asked in SYSGEN; your response may be the same or less than your
response in SYSGEN.
HOW MANY REMOTE (DLII) TERMINALS LEFT UNUSED:

(0)

Respond with the number of terminals that will not be used.
Your response to the preceding question and the number that you specified in
SYSGEN for remote use are important here.
Your answer must be the
difference between those two responses.
You have specified how many remote DLII terminals are to be recognized
by the time-shared RTS.
Now you must enter the operating characteristics of each one. A series of five questions follows for each terminal noted in the first part of Q7.
TERMINAL n
IS TERMINAL n A SCOPE:

(Y)

Respond Y or <CR) if this terminal has a display screen
(a video
screen). Respond N if this terminal is a teleprinter (prints out hard
copy) •
IS TERMINAL n A SLAVE:

(N)

6-12

SYSTEM DEVELOPMENT

(0)

Respond with a decimal number according to your terminal model.
The
chart notes the number of fill characters required for each terminal
model at the baud rate shown. This number provides a delay time to
allow completion of the carriage return/line feed.
VT100
VT50H
VT52
LA36
LA30
LA30
LA30
VT05
VT05
VT05

(set
(set
(set
(set
(set
(set
(set
(set
(set
(set

for
for
for
for
for
for
for
for
for
for

9600 baud)
9600 baud)
9600 baud)
300 baud)
300 baud)
150 baud)
110 baud)
2400 baud)
1200 baud)
600 baud)

0
0
0
0
10
4
2
2
2
1

The next question:
WHAT IS THE LINE WIDTH TO BE USED:

(80)

Respond with a decimal number in the range of 1 through 132, according
to your terminal model. This number is usually 80 and may be thought
of as setting the margins.
The preceding five questions appear for each remote DL11 terminal you
specified in Q7 until operating characteristics are detailed for all
remote DL11 terminals to be supported at run time.
Now you must consider terminals that interface with DZ1l hardware.
6.3.2.7

Local DZ11 Terminals

This series of questions pertains to local terminals on the
terface.
8.

HOW MANY LOCAL (DZ1l) TERMINALS TO BE USED:

DZll

in-

(0)

Respond with the number of terminals to be used that are connected to
DZ11 hardware and used locally. This question was asked in SYSGEN;
your response may be the same or less than your response in SYSGEN.
HOW MANY LOCAL (DZll) TERMINALS LEFT UNUSED:

(0)

Respond with the number of terminals that are not to be used.
Your
response to the preceding question and the number that you specified
in SYSGEN for remote use are important here. Your answer must be the
difference between those two responses.
You have specified
by the time-shared
tics of each one.
noted in the first

how many local DZ11 terminals are to be recognized
RTS.
Now you must enter the operating characterisA series of six questions follows for each terminal
part of Q8.

TERMINAL n
IS TERMINAL n A SCOPE:

(Y)
SYSTEM DEVELOPMENT

6-13

Respond Y or <CR> if this terminal has a display (video)
screen.
Respond N if this terminal is a teleprinter (prints out hard copy).
IS TERMINAL n A SLAVE:

(N)

Respond N or <CR> if this terminal
is to be a master terminal.
Respond Y if you do not want this terminal to be able to start jobs
with keyboard commands. A Y response means that jobs at this terminal
must be started by forced-job startup.
IS CTRL/C TRAP TO BE USED:

(N)

Respond N or <CR> if you want a CTRL/C to be recognized by the
time-shared RTS. Respond Y if you want a CTRL/C to be ignored by the
time-shared RTS. This CTRL/C is not passed to the DIBOL program.
HOW MANY FILL CHARACTERS TO BE USED:

CO)

Respond with a decimal number according to your terminal model.
The
chart notes the number of fill characters required for each terminal
model at the baud rate shown.
This number provides a delay time to
allow completion of the carriage return/line feed.
VT100
VTSOH
VTS2
LA36
LA30
LA30
LA30
VTOS
VTOS
VTOS

(set
(set
(set
(set
(set
(set
(set
(set
(set
(set

for
for
for
for
for
for
for
for
for
for

9600 baud)
9600 baud)
9600 baud)
300 baud)
300 baud)
ISO baud)
110 baud)
2400 baud)
1200 baud)
600 baud)

0
0
0
0
10
4
2
2
2
1

The next question:
WHAT IS THE LINE WIDTH TO BE USED:

(80 )

Respond with a decimal number in the range of 1 through 132 according
to your terminal. model. This number is usually 80 and may be thought
of as setting the margins.
WHAT IS THE LOCAL TERMINAL BAUD RATE:

(9600)

Respond with a decimal number according to your terminal model
and the speed that is appropriate for it. Baud rates are:
110,
1800,
7200,

ISO,
2000,
9600.

300,
2400,

600,
3600,

type

1200,
4800,

These preceding six questions appear for each local DZll terminal you
specified in Q8 until operating characteristics are detailed for all
local DZll terminals to be supported at run time.
Now it is time to consider your DZll terminals for remote use.

6-14

SYSTEM DEVELOPMENT

6.3.2.8

Remote DZll Terminals

These questions pertain to remote terminals on the DZll interface.
9.

HOW MANY REMOTE (DZll) TERMINALS TO BE USED:

(0)

Respond with the number of terminals to be used that are connected to
DZll hardware and that will be used in a remote mode.
This question
was asked in SYSGEN; your response may be the same or less than your
response in SYSGEN.
You have specified how many remote DZll terminals are to be recognized
by the time-shared RTS. There is no need to specify remote DZll terminals left unused. Now you must enter the operating characteristics
of each terminal noted in Q9. A series of six questions follows for
each terminal noted in the first part of Q9.
TERMINAL n
IS TERMINAL n A SCOPE:

(Y)

Respond Y or <CR) if this terminal has a display screen
screen). Respond N if this terminal is a teleprinter.
IS TERMINAL n A SLAVE:

video

(N)

Respond Y or <CR) if this terminal
is to be a master terminal.
Respond Y if you do not want this terminal to be able to start jobs
with keyboard commands. A Y response means that jobs at this terminal
must be started by forced-job startup.
IS CTRL/C TRAP TO BE USED:

(N)

(0)

(set
(set
(set
(set
(set
(set
(set
(set
(set
(set

for
for
for
for
for
for
for
for
for
for

9600 baud)
9600 baud)
9600 baud)
300 baud)
300 baud)
150 baud)
110 baud)
2400 baud)
1200 baud)
600 baud)

o
o

4
2
2
2
1

The next question:
WHAT IS THE LINE WIDTH TO BE USED:

(80)
SYSTEM DEVELOPMENT

6-15

Respond with a decimal number in the range of 1 through 132, according
to your terminal model. This number is usually 80 and may be thought
of as setting the margins.
WHAT IS THE REMOTE TERMINAL BAUD RATE:

(300)

Respond with a decimal number according to your terminal model type
and the speed that is appropriate for it.
The baud rate must be the
same as that chosen in the RT-ll SYSGEN question for 0211 support.
Baud rates are:
110,
1800,
7200,

150,
2000,
9600.

300,
2400,

600,
3600,

1200,
4800,

These preceding six questions appear for each remote 0211 terminal you
specified in Q9 until operating characteristics are detailed for all
remote 0211 terminals to be supported at run time.
You have completed the entry of details for all your
now appears (see the next section).

6.3.2.9

terminals;

QlO

System Hardware/Software Configuration

The first of the system-related questions:
10.

HOW MANY PROGRAMS TO BE RUN:

(4)

The cost is approximately 60 bytes per program selected.
Respond with the decimal number of programs or jobs that you
run at anyone time.
The range is from 1 through 16.
11.

HOW MANY TOTAL MESSAGES TO BE STORED IN MEMORY:

plan

(8)

The cost is approximately 14 bytes per message.
Respond with the decimal number of messages that can be stored
in
memory at anyone time.
This number depends on your programming
needs. Consider which of your programs use SEND or RECEIVE statements
and how many messages are generated (LPTSPL.TSD and BGMAN.TSD use this
facility).
The range is from 1 through 50.
12.

HOW MANY KINDS OF DEVICES TO BE USED:

(4)

The cost is approximately 10 bytes per device selected.
Respond with the decimal number
categories of devices with the
printer requires a separate device
through 10.
13.

of devices.
This number notes
exception of printers.
Each line
handler.
The range is from 1

HOW MANY TOTAL CHANNELS TO BE USED:

(12)

The cost is approximately 55 bytes per channel selected.

6-16

SYSTEM DEVELOPMENT

Respond with a decimal number in the range of 1 through 50.
This
refers to I/O channels (referenced by the DIBOL OPEN statement) that
are needed for devices or files at anyone time across all programs.
In addition, your number sets the limit for questions prompted in Q14
(files opened for update) and in Q15 (total ISAM files).
14.

IS EXTENDED MEMORY TSD TO BE USED:

(N)

Respond Y if you intend to run XMTSD. An answer of Y automatically
implies that the User Service Routine (USR) will be locked in memory
so the USR question, below, does not appear. Respond N or <CR) if you
do not need DIBOL support for extended memory.
If you answer N or
<CR) the following question is asked:
IS USR TO BE LOCKED IN MEMORY:

(N)

Choosing USR to be locked in memory costs approximately 4.2 K bytes.
Respond N or <CR) if you want the USR to be swapped out during program
execution. You will want the USR to be swapped out if memory space is
too small to permit program execution.
Respond with Y if you want the
USR to remain in memory permanently. With the USR locked in memory,
files OPEN and CLOSE much faster.
Any response to the previous question, or an answer of Y to Q14,
prompt:
HOW MANY TOTAL FILES OPENED FOR UPDATE:
The cost (in bytes)

will

(6)

is approximately:

4 X [number of jobs] X [number of files opened for update].
Respond with a decimal number in the range of 0 through 25.
This
number, which is the total number open at anyone time, cannot exceed
your response to Q13 (total channels to be used).
Your response
prompts:
15.

ARE ISAM FILES TO BE USED:

(N)

Choosing ISAM costs approximately 4.2 K bytes.
Respond N or <CR) if ISAM files are not to be accessed in this version
of the time-shared RTS.
Respond Y if ISAM files are to be created or
accessed in this version of the time-shared RTS.
If you answer Y now,
and you have answered Y to Q14 concerning extended-memory time sharing, two additional questions appear:
HOW MANY TOTAL ISAM FILES TO BE USED:

(3)

The cost is a function of both this question and the next; therefore,
see the discussion of the next question before answering this.

SYSTEM DEVELOPMENT

6-17

This is the maximum number of ISAM files to be open at anyone time
across all jobs. Respond with a decimal number in the range of 1 up
to the number you specified in answer to Q13 (but not to exceed 25).
A second question appears:
HOW MANY ISAM VOLUMES/FILE:
The cost (in bytes)

(2)

is approximately:

the number of files X [20 + [10 X the number of volumes per file]].
Respond with a decimal number in the range of 2 through 8.
The ISAM
file that occupies the largest number of volumes will determine your
response.
If you have prompted CTSGEN for explanatory remarks with
either of the two preceding questions, or if you have exceeded limits
set for these questions, the questions will be
asked
again;
otherwise, your response prompts:
16.

IS DDT TO BE USED:

(N)

The cost is approximately 600 bytes.
Respond N or <CR) if you will not require the use of DDT in this
time-shared RTS.
Respond Y if you require the use of DDT in this
time-shared RTS.
The Y response indicates that you also will get
brief error messages that are listed by number only.
If you answer N:
DO YOU WANT BRIEF ERROR MESSAGES:

(Y)

The cost of selecting expanded error messages
bytes.

approximately

1300

Respond N if you want the run-time error message text to be displayed
when an error is detected.
Respond Y or <CR) if you want only the
number of a run-time error message to be printed when an error is detected.
17.

IS IMPLICIT JOB STARTUP TO BE USED:

(N)

Implicit job startup costs approximately 100 bytes.
Respond Y if you want the capability of implicit job startup.
This
will allow a job to start in response to a SEND statement. Selecting
implicit job startup automatically selects forced job startup, below;
and that question is therefore not asked.
Implicit job startup must
be selected if you intend to run XMTSD as a foreground program.
If
you do not want the capability of implicit job startup, respond N or
<CR).
If you answer N to the preceding question:
IS FORCED JOB STARTUP TO BE USED:

(N)

Forced job startup costs approximately 280 bytes.

6-18

SYSTEM DEVELOPMENT

Respond Y if you want the capability for forced job startup.
This enables you to start a job on another terminal with an XCALL to RUNJB.
Respond with N or <CR> if you do not want to use this capability. You
must respond with Y if the line printer spooler LPTSPL.TSD is to be
used.
18.

IS AUTO JOB STARTUP TO BE USED:

(N)

Auto job startup costs approximately 30 bytes.
Respond N or <CR> if you do not want to specify a DIBOL program to be
started after the time-shared RTS is loaded. Respond with Y if you
want to automatically start a DIBOL program upon completion of the
time-shared RTS load.
If you answer Y, you are prompted for the name
of the program to be automatically started:
ENTER PROGRAM NAME [DEV:FILNAM.EXT]:
At this point you have selected all the system parameters, and you are
asked whether you wish to change any of your answers.
19.

DO YOU NEED TO CHANGE AN ANSWER:

If you are satisfied that
software needs, respond
next section.

your
with

(N)

answers reflect your hardware and
N or (CR);
Q19 will appear. See the

If you wish to change an answer, respond with a Y:
REENTER AT QUESTION:
Respond with Q followed by the question
begin again at the question you select.

6.3.2.10

number.

Questioning

will

Naming the Time-Shared Program

The final question:
ENTER THE NAME OF THE SAVE FILE:
The file name entered represents your customized
time-shared RTS.
The default extension is .SAV.

version

Your final carriage return begins a process of assembling and linking
files that will produce your customized time-shared RTS.
Your answers
create the file TSDPAR.MAC and the indirect file CTSGEN.COM which contains the commands for assembling and linking the time-shared RTS.
After the final carriage return is entered, CTSGEN chains
to
CTSGEN.COM to complete the creation of your customized run-time system. The system is identified by the file name you specified in the
last question of the CTSGEN dialogue.
In addition, the linker creates
a link map with this same file name and a default extension of
.MAP.
This link map may help identify problems with a time-shared RTS.

SYSTEM DEVELOPMENT

6-19

6.4

ERROR MESSAGES

CTSGEN checks your responses to verify that they are within the range
of permissible answers.
If an error is detected, you are advised that
your answer exceeds the possibilities and you are prompted with the
question again. CTSGEN does not detect logical errors (such as specifying more terminals than exist).
However, in the assembling process
after CTSGEN execution, MACRO assembly errors can occur.
If a message
indicating that a file was not found appears during the assembling or
linking process, one of the files specified in Section 6.3.1.2 is not
present on the system device.
If you continue to receive errors, consult your DIGITAL software
cialist.

6-20

SYSTEM DEVELOPMENT

spe-

INTRODUCTION TO SECTION III

Section III contains the system utilities provided with CTS-300.
These utilities assist you in maintaining your system, in monitoring
its operation, and in providing a convenient way to present data.
Each utility is discussed in its own chapter.
There is no particular
order of presentation. Some of the utilities are usable in all systems and some are applicable to TSD systems only.
The utilities and their major functions are:
DDT (Chapter 7)
A run-time debugging program for DIBOL programs.
Spoolers (Chapter 8)
There are two line printer spoolers. One for SUD systems and one
for TSD systems. These programs implement the DIBOL LPQUE statement to print data.
PRINTU (Chapter 9)
A program that allows you to quickly develop and organize
reports from a known data base structure.

simple

ISMUTL (Chapter 10)
A program that permits you to develop an ISAM file that is tailored to your specific needs and to monitor this file and reorganize it as it grows.
SORT/MERGE (Chapter 11)
A program that allows you to sort or
~ight keys.

merge

files

using

STATUS (Chapter 12)
A TSD utility that shows the current system operation
such as numbers and names of jobs and terminals.

parameters

REDUCE (Chapter 13)
A TSD utility used to eliminate unused blocks of a DIBOL
file resulting from the TSD linking process.

program

CHAPTER 7
DIBOL DEBUGGING UTILITY (DDT)

7.1

INTRODUCTION

DDT (DIBOL Debugging Technique) is a system utility that allows you to
interact with your DIBOL program while it is executing.

7.1.1

Features

The features of DDT are intended to aid the DIBOL programmer in locating problems; correcting data values; and testing programming errors
directly without having to
edit,
compile,
and
link
again.
Specifically, you may:
• Set predetermined stopping points.
•

Examine and/or alter the contents of variables.

• Single step through lines of a DIBOL program.
• Trace through sequences of XCALL nestings.

7.1.2

Chapter Organization

The remainder of this chapter is arranged in two major sections.
Section 7.2,
Preparing for DDT, discusses the procedures required to
prepare your system and program for DDT operation.
Section 7.3,
DDT
Commands, describes the various DDT commands and their use.

7.2

PREPARING FOR DDT

This section details the procedures required to compile, link, and run
with DDT.
7-1

7.2.1

CTSGEN

You must first request DDT during the CTSGEN in addition to
and linking individual routines for use with DDT.

7.2.2

compiling

Compiling

The main program, as well as all subroutines which are to be debugged,
must first be compiled for use with DDT by specifying the DDT option
in the DIBOL compiler command. This option generates a symbol table
used by DDT. A typical command line might be:
• DIBOL/ONDEBUG PROG,SUBl, SUB2, SUB3
which generates PROG.OBJ, SUBI.OBJ, SUB2.0BJ,
necessary symbol tables for DDT.

and

SUB3.0BJ

and

the

If certain subroutines are known to be already debugged, you may
compile your program specifying only those modules you intend to
further debug.
The following command line illustrates this:
.DIBOL PROG/ONDEBUG,SUBI/ONDEBUG,SUB2,SUB3
With the above compiler command structure, only the main
SUBI are compiled for DDT.

7.2.3

program

and

Linking

The compiled main program and all subroutines must be linked with a
special DDT module in order for it to be available at run time.
Notice that both the SUD and TSD are linked to the same DDT module
(TSDDT).
The basic command for the main program and subroutines used
in compiling would be:
For SUD operation:
.LINK PROG,SUBI,SUB2,SUB3,TSDDT,DIBOL
which would create PROG.SAV.
For TSD operation:
• LINK/EXE:PROG.TSD PROG,SUBI,SUB2,SUB3,TSDDT,TDIBOL/BOT:IOOOOO
which would create PROG.TSD.

7-2

DIBOL DEBUGGING UTILITY (DDT)

7.2.4

DDT Operation

7.2.4.1

Running DDT

DDT is initialized whenever a program compiled and linked for DDT
operation is run under a
run-time system which includes DDT.
DDT
outputs its version number and, on the next line, the hyphen prompt.
In the following program,PROG which has been compiled and linked for
DDT, is executed for manipulation with DDT commands:
.R PROG or .RU dev:PROG
DIBOL DDT VAnn-nn
where the A in the version identifier indicates a SUD
would be B for a TSD system and C for an XMTSD system.

system.

At this point any valid
entered.

7.3

7.2.4.2

command

discussed

Section

can

Failure to Properly Prepare for DDT

If you forget to perform one of the required steps in sections 7.2.1
through 7.2.3, the program will exhibit the following characteristics:
•

If no DDT were requested at CTSGEN time:
The program will run as though no DDT were requested.

• If no DDT were requested during compilation:
The program will respond to DDT except for those commands
that examine and/or alter the contents of variables.
•

If no DDT were requested during linking:
The program will run as though no DDT were requested.

7.2.4.3

Error Messages

See Appendix B, Table B-5, for a list of DDT error messages.

DIBOL DEBUGGING UTILITY (DDT)

7-3

7.3

DDT COMMANDS

This section discusses the commands that are valid for DDT.
In the
following text, when the term routine is used it refers to a specific
program module; either the main program or an external DIBOL subroutine.
For future reference, the DDT commands and command formats are
below in the order they appear in this section.

listed

Format

Command
Start or resume execution

CTRL/Z

Single step

CTRL/G

Setting breakpoints

$[name:]nnn

Clearing breakpoints

$ [name]

Iteration of breakpoints

Examining variables

vvv=

Setting variables

vvv=nnn

Extended variable manipulation

++vvv= or ++vvv=nnn

Subroutine traceback
DDT commands, like other commands, require a carriage return
tion to enter the command.
7.3.1

termina-

Program Execution Control

Program execution control has two functions:
It allows you to resume
execution after a breakpoint has been encountered;
and it allows you
to single step through individual DIBOL statements to see if they are
being properly executed.
7.3.1.1

Program Execution

To start or resume execution of the DIBOL routine from a DDT
breakpoint, enter the following command in response to the DDT prompt:
CTRL/Z
There are no arguments.
execution.

The current routine simply starts or

Example:
-CTRL/Z
resumes execution of the current routine.
7-4

DIBOL DEBUGGING UTILITY (DDT)

resumes

7.3.1.2

Single Step

It is frequently desirable to know which branch of a computed GOTO, or
The single step
of a complicated IF statement the program will take.
command executes the next instruction in the routine and halts.
To
single step, enter the following command in response to the DDT
prompt:
-CTRL/G
There are no arguments.
The routine executes the present
and returns the following message:

instruction

AT LINE xxxx IN ROUTINE yyyy
where:
xxxx

is the line number of the instruction
of the single step.

after

yyyy

is the name of the routine in which line xxxx resides.

You may now enter any DDT command you wish, as indicated
prompt.

execution

the

DDT

Example:
Assume there is a conditional jump statement in routine SUB3 at line
47, and you wish to find the next instruction to be executed. First,
while in subroutine SUB3, set a breakpoint (see Section 7.3.2.1)
at
line 47:
$47
Start execution of the routine by issuing a CTRL/Z, and when (and
line 47 is reached the display will be:

if)

DDT BREAK AT LINE 47 IN ROUTINE SUB3
Respond to the prompt with CTRL/G which will, in turn, display:
AT LINE

NN IN ROUTINE ABC

which is the next instruction location.
subroutine including SUB3.

7.3.2

Routine

ABC

could

any

Breakpoint Control

A breakpoint is a user-determined stopping point within a
routine.
Breakpoints are used to position yourself in a routine so you can exercise other DDT capabilities.
DIBOL DEBUGGING UTILITY (DDT)

7-5

7.3.2.1

Setting Breakpoints

You set a breakpoint in a routine by typing the following
response to the DDT prompt:

command

$[name:]nnn
where:
name

is the name of the routine in which the breakpoint is
to be set.
If a breakpoint is to be set in the main
program, the name of the first routine specified in the
link command
(by convention, the root segment) should
be used.
Otherwise, the name of the routine should
match the name given in the subroutine statement.
If
the name argument is omitted, the current routine is
assumed.

nnn

is the line number at which the routine is to halt.
• The line at which the routine is halted has
been executed.

not

yet

• A maximum of eight breakpoints may be set at anyone
time.
• Only one breakpoint is allowed in any main program or
subroutine.
• A breakpoint in the data section has no meaning.
Example:
;

-$8U81:50
sets a breakpoint at line 50 in subroutine SUBI.
-$21
sets a breakpoint at line 21 in the current routine.

7-6

DIeOL DEBUGGING UTILITY (DDT)

7.3.2.2

Clearing Breakpoints

Pr~viously set breakpoints may be cleared by typing the following command in response to the DDT prompt:

$ [name]

where:
name

is the name of the routine in which the breakpoint is
to be deleted. If name is omitted, the breakpoint in
the current routine is cleared.
• The breakpoint in a routine need not be deleted
before a breakpoint is set at a new line in that
routine.
• Setting a new breakpoint automatically
other breakpoint in that routine.

deletes

any

routine

and

Example:
-$8U82
clears the breakpoint in subroutine SUB2.
-$56
sets a breakpoint at line 56 in the current
clears any prior breakpoint in that routine.
7.3.2.3

Iteration of Breakpoints

To test the effects resulting from iterative procedures, it is sometimes useful to set a breakpoint in a loop and pass through it several
times before allowing execution to halt. This is accomplished with
the following command in response to the DDT prompt:

>n
where:
n

is the iteration count. This is the number of times
the breakpoint is to be encountered before execution is
halted.
• The iteration count can be set only
routine.
• You must be at the
iteration command.

breakpoint

• Execution is halted the nth time
encountered.

the

current

before

issuing

the

breakpoint

DIBOL DEBUGGING UTILITY (DDT)

7-7

Example:
Assuming that a breakpoint is set in a loop at line 25 of the current
routine, and the program executes until reaching this point, the response will be:
DDT BREAK AT LINE 25 IN ROUTINE XXX
where:
XXX

is the name of the current routine.

You might respond with an iteration count and execution command:

>8
-CTRL/Z
The routine then loops through this location;
stopping the eighth
time it reaches line 25 without executing the instruction there.
The
response is:
DDT BREAK AT LINE 25 IN ROUTINE XXX

7.3.3

Variable Manipulation

Variable manipulation allows you to examine or change variables in a
routine to determine whether or not they are being correctly handled.
7.3.3.1

Examining Variables

Variables may be examined to verify their contents with the
command in response to the DDT prompt:

following

vvv=
where:
vvv

is the variable name.
Subscripts, either single or
double, may be used with the variable name to access a
part of a field or data in an unlabeled field.

Example:
Assume you have stopped at a breakpoint;

then:

-VARl=
results in a display of the present contents of this variable.

7-8

DlBOL DEBUGGING UTILITY (DDT)

7.3.3.2

Setting Variables

Variables may be set (loaded) with any desired value by using the following command in response to the DDT prompt:
vvv=nnn
where:
vvv

is the variable name.

nnn

is the value you wish to assign to the variable.
•

If the length of nnn is too long to store in vvv, the
data is left justified in the field and the excess
right-hand characters are truncated.
This is true
for both alpha and decimal fields.

• Do not use single quotes when specifying alpha data.
• A field, alpha or decimal, can be cleared by entering
a space for an assigned value.
• Subscripts, single or double, can also be used to set
variables.
Examples:
-VARl=ABCD
Assigns the value of ABCD to VAR1.
-VARl='ABCD'
Assigns the value of 'ABC to VAR1.
7.3.3.3

Extended Variable Manipulation

It is possible under the specific circumstances explained here to exThis
amine, or to set, a variable used outside the current routine.
may be done only when the variable is defined
in the routine which
called the current routine or is defined in one of the routines in the
chain of calls which led to the current routine. For example:
-++VAR2=
will return the current value of VAR2 located
which called the current routine.
The two
the variable was defined in a routine located
els of nesting) in the chain which led to the

in the chain of routines
plus signs indicate that
two calls back (two levcurrent routine. Also:

-++VAR2=EFGH
will set VAR2 to the value EFGH.
DIBOL DEBUGGING UTILITY (DDT)

7-9

7.3.4

Subroutine Traceback

The subroutine traceback feature allows you to determine whether or
not the calling sequences (XCALL statements) are executing in the expected manner. The outp~t is a list of the routines and the line
numbers in those routines of all the related preceding XCALL statements back to the main program. To obtain this list, enter the following command
(a caret, up arrow, or circumflex) in response to the
DDT prompt:

There are no arguments.
erated.

The circumflex (A) causes the list to be gen-

Example:
Assume you have halted in a subroutine at a DDT breakpoint, or you
have single stepped to the current position, and you need to know how
you arrived at this point from the main program.
The command and
traceback list might look like the following:
AT LINE 37 IN ROUTINE SUB3
AT LINE 192 IN ROUTINE SUB2
AT LINE 21 IN ROUTINE MAIN

(current location)
(SUB3 called from SUB2, line 192)
(SUB2 called from MAIN, line 21)

You are still in routine SUB3 and may enter any DDT command.

7-10

OIBOL DEBUGGING UTILITY (DDT)

CHAPTER 8
LINE PRINTER SPOOLERS

8.1

INTRODUCTION

The two line printer spoolers, LPTSPl.REL and LPTSPL.TSD, are utility
programs used to print data and program source files.
LPTSPl.REL is
used with SUD systems, and LPTSPL.TSD is used with TSD and XMTSD systems.

8.1.1

Common Characteristics

Both spoolers operate in response to the DrBOL LPQUE statement.
The
function of the spooler, regardless of run-time system, is to queue
files to be printed, and to issue print commands to the printer.
The
DrBOL OPEN statement is not used by a DrBOL program that uses a line
printer spooler.

8.1.2

Chapter Organization

The remainder of this chapter is comprised of three sections: Section
8.2, SUD;
Section 8.3, TSD; Section 8.4, XMTSD.
Each section is
organized the same way: first, the characteristics of the particular
spooler are covered;
then the details associated with using the
spooler are presented.

8-1

8.2

LPTSP1.REL (SUD OPERATION)

8.2.1

Characteristics

8.2.1.1

Features

The SUD spooler has the following features:
• The SUO spooler is a queue manager program written in
bly language.

assem-

• Sharea operation of the line printer (between the spooler and
a OIBOL program) is not supported. See Section 8.2.2.1 for
further information.
• The SUD spooler operates as a foreground job. Other programs
run concurrently in the background.
See Section 8.2.2.2 for
further information.
• Output is to one line printer only.
• LPTSPl.REL can queue up to ten print jobs.

8.2.1.2

Requirements

The SUD spooler requires the following system supports:
• LPTSPl.REL requires 4 K bytes of memory.
• A handler, LP.SYS, must be resident (via the RT-ll LOAD
mand) in memory.

com-

• LPTSPl.REL must be on the system device.
• LPTSPl.REL requires either the FB or the XM monitor.

8.2.2

Using LPTSP1.REL

8.2.2.1

Shared Line Printer Operation

The line printer can not be shared between the line printer spooler
and a OIBOL program or a CTS-300 system program. An attempt to use
the line printer while LPTSPI is running will
result
in
a
device-in-use error message.
8-2

LINE PRINTER SPOOLERS

Shared Terminal Operation

8.2.2~2

Both the line printer spooler and a DIBOL program running concurrently
under the FB monitor can make use of the same terminal. As stated
above, the spooler runs in the foreground, and the DIBOL program runs
in the background.
I/O operations at the terminal are independent functions for the two
programs.
The line printer can display a message at any time by assuming control of the terminal. Data that is input at the terminal
while the spooler is using the terminal is stored in a 40-character
terminal buffer. When the spooler releases control, the stored input
data is displayed.
A symbol is displayed with each message to the
terminal to identify the message source; likewise, an indicator must
be provided by the operator to identify the program being addressed.
These symbols are shown below:
Input
Indicator

Output
Indicator

Spooler program
(foreground job)

CTRL/F

DIBOL program
(background job)

CTRL/B

Program

If both the spooler and the DIBOL program require the terminal simultaneously, the spooler has priority because it is a foreground job and
the foreground always has priority. Under these conditions, data output from the spooler continues to the end of the display line, and
then control passes to the DIBOL program which, in turn, outputs a
line.

8.2.3

Starting

Before running the spooler, the printer handler must be loaded.
The
handler is loaded for the exclusive use of the foreground program (the
spooler). This avoids mixing output from the spooler with output from
a DIBOL program. The command is:
• LOAD LP=F
If you want to print a file that is not on the system device, you must
also load the handler for that device, to make it available for the
spooler. Use the following command:
• LOAD dev=F
where:
dev

is the name of the device where the file to be
resides.

printed

LINE PRINTER SPOOLERS

8-3

The spooler is started by entering the following command:
.FRUN LPTSPI
The response is:
F)

SINGLE-USER DIBOL LINE PRINTER SPOOLER VAnn-nn

B)
where:
nn-nn

is the version number for the spooler program.

When the monitor's prompt (.) appears, any runnable DIBOL program or
CTS-300 program can be executed. An LPQUE statement within that program will then cause the spooler to queue and print the specified
file.

8.2.4

Run-Time Dialog

If either the FORM or ALIGN argument were included in the LPQUE statement,
the spooler will output an appropriate message to the terminal.
The message is preceded by F) to indicate that it has been issued by
the foreground job (LPTSPl). The messages and appropriate responses
are listed below:
Message

Response

LOAD xxxxxx IN LP

The operator must load the specified form
(xxxxxx), that is, invoices, payroll checks,
etc., into the line printer.
Operation is
continued by typing CTRL/F <CR).

IS ALIGNMENT OK ?

8-4

The operator must ensure that the two rows of
alignment characters are properly positioned
on the form in the line printer.
If the form
is correctly positioned, the response is
CTRL/F Y <CR).
If the alignment is not correct, the operator must realign the form and
request another group of alignment characters
by typing CTRL/F <CR).

LINE PRINTER SPOOLERS

8.2.5

Error Messages

When an error condition occurs, LPTSPl.REL displays one of the error
messages listed in Appendix B, Table 8-6. All errors for the spooler
are fatal errors. Any queued file(s) is lost, and the operator must
take the following steps:
1.

Enter at the terminal:
• UNLOAD F

8.3

Correct the condition that caused the error.

Restart the spooler, as described in Section 8.2.3.

Request a print again.

LPTSPL.TSD (TSD OPERATION)

8.3.1
8.3.1.1

Characteristics
Features

The TSD spooler has the following features:
• LPTSPL.TSD is a DIBOL program that operates under the control
of the TSD RTS.
• LPTSPL.TSD consists of a queue manager and four
satellite
programs:
LPSAT.TSD,
LQSAT.TSD,
LRSAT.TSD, and LSSAT.TSD.
Each satellite program is active only as long as there are
files to be printed on its associated printer.
• Each satellite automatically opens its line printer and loads
its handler if not already loaded.
• A maximum of four line printers is supported.
• LPTSPL.TSD supports assignment of default line printers.
Section 8 .• 3. 2~_J for more information.

See

• If spooler execution is terminated before completion of all
print requests, the remaining requests are stored for later
recovery.
The current print job is not lost.
See Section
8.3.2.2 for more information.
• Spooler operation is suspended for printers being used by
another program.
See Section 8.3.2.3 for more information.
• LPTSPL.TSD can be run detached.
information.

See Section 8.3.2.4 for more

• LPTSPL.TSD can queue up to fifty files per printer.
tion 8.3.2.5 for more information.

See Sec-

LINE PRINTER SPOOLERS

8-5

8.3.1.2

Requirements

The TSD spooler requires the following system supports:
• The LPTSPL.TSD queue manager requires 4 K bytes
each satellite requires an additional 2 K bytes.
• The number of line printers must be
SYSGEN.

specified

memory;

during

RT-ll

• Forced job star~up must be requested during CTSGEN
to utilize LPTSPL.TSD.

8.3.2

order

Using LPTSPL.TSD (TSD Operation)

8.3.2.1

Default Line Printers

Ordinarily, a specific line printer is assigned by line printer number
to a print job from within a DISOL ~rogram. For example, the following LPQUE statement assigns the second line printer as the printer to
print the file named XXX.YYY:
LPQUE{'RKl:XXX.YYY',LPNUM:2)
This however, is not a requirement, since the spooler accepts the assignment of a default line printer.
(See Section 8.3.3.1 for assignment.) If more than one default printer is assigned, the default line
printer for a given job is defined by LPTSPL.TSD as being the printer
having the least number of print requests queued.

8.3.2.2

File Recovery

If spooler execution is terminated before the completion of all print
requests, the remaining requests are stored in file LPTSPL.LPQ. After
reinitialization, the spooler checks this file and prints the remaining requests.
Partially completed print jobs can be reprinted in
full.
See Section 8.3.4.

8.3.2.3

Suspension of Spooling

When the spooler is started, it opens an I/O channel to the line
printer(s).
If the printer(s) is being used by another program, an
error message indicating the printer is not free is displayed and
spooler operation is suspended until that program releases the busy
printer.

8-6

LINE PRINTER SPOOLERS

8.3.2.4

Detached Mode Operation

You may select detached program operation for LPTSPL.
(See Section
8.3.3).
LPTSPL runs independently of the terminal, as long as it is
not required by the spooler. During this time the terminal is available for other DIBOL-II programs. When'LPTSPL requires the terminal
for information or error messages, the execution of LPTSPL is suspended until an ATTACH command is issued. Then, LPTSPL displays the message; waits for user response, if any; and resumes operation in detached mode.
Once detached operation is selected, it remains in effect until LPTSPL.TSD is attached by the user and terminated with a
CTRL/C, an S, or killed via STATUS.

8.3.2.5

The Queue File

LPTSPL maintains a list of files to be printed in file LPQFIL.LPQ on
the system device.
LPQFIL has four sections, one for each possible
line printer.
Each section has fifty slots.
If the queue section is
full when a print request is received from LPQUE, the spooler attempts
to display a message to a terminal indicating that the queue is full,
and that the file was not accepted for printing.
If the spooler is
running detached, see Section 8.3.2.4.

8.3.3

Starting

Line printer spooler, LPTSPL.TSD, may be started by anyone of four
methods.
In methods 2, 3, and 4, '?YNNY' refers to answers to the default printer selection.
The questions are discussed
in Section
8.3.3.1 and the SEND statement is discussed in Section 8e3.3.2 and in
the DIBOL-II Language Reference Manual.
Method 1, Direct startup:
*R LPTSPL
Method 2, Forced job startup:
XCALL RUNJB ('LPTSPL.TSD',term#)
or, if a -1 is specified as the terminal number (indicating a detached
job), the spooler must be supplied with the default printer selection
information as follows:
SEND ('?YNNY','LPTSPL.TSD')
XCALL RUNJB ('LPTSPL.TSD' ,-1)

LINE PRINTER SPOOLERS

8-7

Method 3, Chain mode startup:
STOP 'LPTSPL.TSD'
or, if the chaining job is detached, the spooler must be supplied with
the default printer selection information as follows:
('?YNNY','LPTSPL.T~D')

SEND

STOP 'LPTSPL.TSD'
Method 4, Implicit job startup:
SEND ('?YNNY','LPTSPL',-2)

8.3.3.1

Response with an Attached Terminal

When LPTSPL.TSD is started, the following message is displayed:
TIME-SHARED DIBOL LINE PRINTER SPOOLER - VBnn-nn
where:
nn-nn

is the version number.

The spooler then asks for default printer identification:
DEFAULT PRINTERS?
LINEPRINTER 1
If line printer 1 is to be a default printer, enter Y.
If this
printer is not to be a default printer, enter N. The remaining
printers are then similarly presented for default selection.
One last question is asked:
DO YOU WANT TO RUN DETACHED?
If detached operation is desired, enter Y. The spooler then proceeds
to print or wait for a file to be queued. Terminal control returns to
the run-time system which displays the asterisk prompt.
If detached operation is not desired, enter an N.
can then be executed from that terminal.

8.3.3.2

other

program

Response with a Detached Program

If LPTSPL.TSD were started as a detached program, the version number
message would not be displayed, so default printer selection could not
be asked.
The default printer selection information must be supplied
via a DIBOL SEND statement from the DIBOL-ll program which is
initiating startup of LPTSPL.TSD.
This is illustrated above,
in
Section 8.3.3,
in examples 2 through 4.
In these examples, the
question mark in the SEND statement
message
SEND('?YNNY', ••• )
indicates to the spooler that the information defines default line

8-8

LINE PRINTER SPOOLERS

printers.
Each character after the question mark is a response to a
default printer selection question
(yes, no, no, yes;
in the
examples) •
8.3.4

Stopping

LPTSPL.TSD can be stopped, and the memory it used made available to
the system, only if it is attached to a terminal.
The spooler is
stopped with either a CTRL/C or an S entered at the keyboard, or it
can be stopped with the kill option in STATUS;
see Chapter 12.
8.3.5

Run-Time Dialog

During runtime, LPTSPL.TSD may display messages as a result of interrupted or terminated printing, or as a result of the FORM or ALIGN arguments in the DI80L LPQUE statement.
Interrupted or Terminated Print
If printing is interrupted or terminated, the print job can be resumed.
When LPTSPL.TSD is started again,
the LPQFIL.LPQ file is
checked for incomplete jobs.
If such a job is found,
the following
message is displayed:
CONTINUE PRINTING
fi1enam?

If you wish to continue printing from the beginning of the file, respond with Y.
If you wish to
ignore the file, respond with a <CR).

FORM or ALIGN Arguments
If the FORM or ALIGN argument(s) were included in the LPQUE statement,
the spooler will output the message(s) these arguments imply.
If
FORMS or ALIGN are used, you should run LPTSPL as an attached job
since, without a terminal, LPTSPL will be suspended until it is attached whenever the terminal message is output. The messages with appropriate responses are listed below:
Message

Response

LOAD xxx xxx IN LINE PRINTER n
The operator must load the specified
where:
n is 1,2,3, or 4
form
(xxxxxx), that is, invoices, payroll checks, etc.,
into the printer.
Operation is continued by typing <CR).
ALIGNMENT OKAY FOR
PRINTER n?
where: n is 1,2,3, or 4

The operator must ensure that the two
rows of alignment characters are properly positioned on the form
in
the
printer.
If the form is correctly positioned, the response is Y.
If the alignment is not correct, the operator
must realign the form and must request
another group of alignment characters by
typing <CR).
LINE PRINTER SPOOLERS

8-9

8.3.6

Error Messages

Error messages for LPTSPL.TSD are listed in Appendix B, Table B-7.
If an error occurs while the spooler is running detached from the
terminal, spooler operation is suspended until the operator issues an
ATTACH LPTSPL command, at which time the error message will be
displayed.

8.4

LPTSPL.TSD (XMTSD OPERATION)

8.4.1

Characteristics

The operation of LPTSPL.TSD in an XMTSD system is the same as in a TSD
system, except that the handlers for the printers must be loaded before the spooler can be run.
See Sections 8.4.1.1 and 8.4.3.

8.4.1.1

Features

The XMTSD spooler has the following features:
• LPTSPL.TSD is a DIBOL program that operates under the control
of the XMTSD RTS.
• LPTSPL.TSD consists of a queue manager and four satellite
programs:
LPSAT.TSD,
LQSAT.TSD,
LRSAT.TSD, and LSSAT.TSD.
The satellite programs are running only as long as there is a
file to be printed.
• A maximum of four line printers is supported.
• LPTSPL.TSD supports assignment of default line printers.
Section 8.3.2.1 for mpre information.
•

See

If spooler execution is terminated before completion of all
print requests, the remaining requests are stored for later
recovery. See Section 8.3~2.2 for more information.

• Spooler operation is suspended for printers being used by
another program. See Section 8.3.2.3 for more information.
See

Section

• LPTSPL.TSD can queue up to fifty files per printer.
tion 8.3.2.5 for more information.

See Sec-

• Detached terminal operation
8.3.2.4 for more information.

8-10

LINE PRINTER SPOOLERS

supported.

8.4.1.2

Requirements

The XMTSD spooler requires the following system support:
•

LPTSPL.TSD requires 4 K bytes of memory;
quires an additional 2 K bytes.

each satellite

• Appropriate printer handlers must be resident in
They are:
LPX.SYS, LQX.SYS, LRX.SYS, or LSX.SYS.
• The number of line printers must be
SYSGEN.

specified

8.4.2

memory.

during

• Forced job startup must be requested during CTSGEN
to utilize LPTSPL.TSD.

re-

RT-II

order

Using LPTSPL.TSD (XMTSD Operation)

See Section 8.3.2.
The information for TSD operation is valid for
XMTSD operation except for the ATTACH commond which becomes A under
XMTSD (see Chapter 5, Section 5.5).
8.4.3

Starting

Before execution of LPTSPL.TSD in the XMTSD environment, the appropriate handler(s) must be loaded.
If all four handlers are required, the
procedure is:
.LOAD LP
.LOAD LQ
.LOAD LR
.LOAD LS

or you may issue a single line command:
.LOAD LP,LQ,LR,LS

Handlers LP, LQ, LR, and LS correspond to line printers 1, 2,
4, respectively.

and

Under the XMTSD monitor, the correct handler is loaded with the above
commands.
This is done despite the fact that the XM handler name has
a third character (X).
After the handlers are loaded, proceed as
in
Section 8.3.3 to run the spooler.

LINE PRINTER SPOOLERS

8-11

8.4.4

Stopping

See Section 8.3.4

8.4.5

Run-Time Dialog

See Section 8.3.5.

8.4.6

Error Messages

8-12

LINE PRINTER SPOOLERS

CHAPTER 9
PRINTU

9.1

INTRODUCTION

PRINTU is a utility program for the creation of simple report programs
using data from either a sorted sequential file or from an ISAM file.
PRINTU utilizes a user-written control file that describes the
parameters of the desired report.
Given the control file, PRINTU
generates a nISOL program that is compiled and linked like any other
nISOL program. The resulting program, when run, produces the report.

9.1.1

Features

PRINTU has a number of features that makes it particularly useful:
• PRINTU has the ability to process data files without physically reordering them by using a sorted tag file generated by
the SORT utility.
• Once a report program is created, it can be stored for
use.

later

• Since PRINTU generates a nISOL program, extra features or
capabilities can be added by simply modifying the program to
achieve your needs.
These needs could be special output
print lines, more header lines, output based on logical test
results, operation with packed records as input, or any other
feature you wish to develop.

9.1.2

Limitations

There are limitations that require foresight when you are using PRINTU.
These concern the way you handle file control records (explained
in the next subsection) and the nISOL requirement for an end-of-file
(EOF) marker (a CTRL/Z) in all data files.
Potential problems in both
of these areas are easily avoided, however, as you will see in the
next two subsections.
9-1

9.1.3

File Control Records

Some application system files are designed to contain a control record
as the first record. More than likely this will produce meaningless
output on the first report page printed.
There are two ways to
prevent this from happening: the first way is to do a tag sort on the
file and ensure that the control record sorts out as the first record
in the tag sort file.
You can then use an editor to delete this
record. PRINTU will then begin with the second record in the file.
The second way to prevent a control record from interfering with a
print report is to place the control record at the end of the file.
To prevent PRINTU from accessing this record you can precede this
record with another record containing an EOF marker as the first
character.
These two records can be inserted using direct access.
The EOF character is obtained by using the decimal equivalent of
CTRL/Z (026) and an XCALL to ASCII. The control record is then not
accessible by PRINTU.

9.1.4

Chapter Organization

The remainder of this chapter is comprised of two sections.
Section
9.2, The Control File, is a detailed discussion of the PRINTU control
file and how the individual control statements relate to each other
and to the desired printed report. Section 9.3, Using PRINTU, illustrates the manner in which the control file is used with the PRINTU
program to produce a DIBOL file, and how this DIBOL file is compiled
and linked.

9.2

THE CONTROL FILE

PRINTU depends on information supplied by the user to describe the
input file{s), output file, and other parameters of the report. This
information is given to PRINTU via a control file containing control
statements. The control file is created using an editor. The control
file is the heart of PRINTU.
It is here that you provide the
parameters that determine the appearance of the report.
The control file has its own terminology and, at times, this can be
confusing.
For this reason, the following essential terms are introduced. Many of them are further defined in context.
accumulation field

A user-identified field whose value from record to
record is accumulated to produce a total.

break field

When the data in a break field changes, a print
occurs.
The break field is covered in detail in
Section 9.2.5.

9-2

PRINTU

detail print

The normal print mode (as opposed to a summary
print - see below). Individual values are printed, as well as the totals.

input data file

The file containing the data which is to
as the source for your report.

report file

The output of the report program when that program
is run.

report program

The program generated by running PRINTU and then
compiling and linking the resulting DIBOL source
file.

summary print

A printout that includes only the totals from each
accumulation field whenever a new value occurs in
a break field.

tag file

The file produced by the SORT utility when its TAG
option is selected. Used by PRINTU to access the
input data file.

used

There are nine possible control statements in the control file, of
which only four are required. The other five control statements supply optional capabilities that you mayor may not need.
The control
file structure, format, content, individual control statement descriptions, and other characteristics are explained below and in subsequent
sections.
Before we discuss the control file, briefly consider what your goals
for the report are. You begin with a file whose record structure is
known to you, and your major goal is to produce a printed report that
shows the data in this file in some desired order in relationship to
the data in each record field or fields. Additionally, there may be
some data in each record that you wish to ignore, and there are probably one or more fields in related records which contain numeric data
that you would like to have totaled.
How these and other requirements are achieved is covered in detail in
the individual control statement descriptions. However, the following
gives you an idea where, in the context of a simple control file,
these requirements are specified.
You will find PRINTU easy to understand and use if for the first few
times you use it you confine yourself to the four required control
statements. A useful report can be generated with these four alone.
The four control statements and their characteristics are:
IDENT

This statement provides a means of assigning a name to
the control file.
It has no effect on input data selecti on, fo rmat, or content, of the pr i nted repo rt.

OUTPUT

This statement serves only to assign a unique name to
the resulting print report. This statement is optional
in the sense that, if not included, a prompt will request the name at program run time.

PRINTU

9-3

INPUT

INPUT is one of the two most important field definition
statements. It is here that you:
• Select the input data file.
If this statement is omitted, this information
be requested via a prompt at run time.
• Describe the fields that you
input data record.

need

from

will

within

the

• Select break fields.
• Request a new printed page concurrent
field change.
• Select whether you print only totals or
values, as well.

with

break

intermediate

• Request to read an ISAM input file sequentially.
PRINT

PRINT is the other field definition statement
of prime importance. It is here that you:

that

• Make the logical connection between fields identified
in the input statement and fields to be printed.
• Assign column headings for each field printed.
• Select numeric fields that are to be accumulated.
• Format the numeric data to be printed.
• Assign column spacing.
All nine control file statements are discussed in the following subsections.
Optional input for each statement is shown in brackets.
Comment lines are allowed only as shown for each entry. An example is
given for each statement as it is presented. Each example is part of
an overall exercise to build a usable control file, so, therefore,
some examples build on previous concepts. The completed control file
is shown as part of the example in Section 9.3.1.

9.2.1

IDENT

IDENT is the first entry in the control file.
It provides the control
file title and appears on the first line of the DIBOL listing of the
report program and at the top of each printed report page.
Its most
important use is to identify your control file when you run PRINTU.

9-4

PRINTU

It is of the form:
IDENT program, author

[;comment]

where:
program

is the identifier you wish to assign to the report.
It
can be up to 22 characters long with a slash (/) used
as a word separator.

author

is any text up to 24 characters long.

Example:
IDENT PAY/ANALYSIS, Your name
The START line of the DIBOL listing would look like the following:
START

9.2.2

;PAY ANALYSIS

-YOUR NAME

HEADl and HEAD2 (Optional)

HEAD1 defines the first heading line appearing on each page of the report and HEAD2 defines the second. Both are optional, and headings
are centered on the page. The form is:
HEAD1 'text'

[;comment]

HEAD2 'text'

[;comment]

where:
text

is a string of characters from the DIBOL set, exclusive
of quotes, up to 132 characters long.

There may be more than one HEAD1 or HEAD2 line.
If so, the individual
text lines for given HEADn statements are concatenated. This is
necessary for long titles.
If HEAD1 is less than 67 characters, the
line will be expanded by inserting a space between each character.
The total number of characters for either line is limited to 132.
Example:
HEAD1 'PAY ,
HEAD1 'ACCOUNTABILITY'
HEAD2 'BY EMPLOYEE AND TASK CODE'
The heading on each page would then appear as follows:
PAY

A C C 0 U N TAB I LIT Y

BY EMPLOYEE AND TASK CODE

PRINTU

9-5

9.2.3

EXECUTE (Optional)

EXECUTE creates the OIeOL stop and chain exit in the
The format is:

report

EXECUTE filespec

program.
[;comment]

where:
filespec

is a CTS-300 OIeOL file specification.

Example:
EXECUTE OLl:STATUS.TSO
Upon completion of the report, the report program
program called STATUS.TSO on device OLI.

would

chain

HaTE
The EXECUTE statement must appear after
IOENT and before the INPUT statements.

9.2.4

OUTPUT

OUTPUT identifies, by nature of your response, either a printer or a
report file that is the destination of the output that results from
running the report program.
Its form is:
OUTPUT filespec
where:
filespec

is a CTS-300 OIeOL file specification.

No comment line is allowed with this statement.
Example:
OUTPUT RKl:PAYACC.DDF
When the report program is run, the resulting report is placed on
and is named PAYACC.OOF.
HaTE
The OUTPUT statement must appear after
IOENT and before the INPUT statement.

9-6

PRINTU

RKl

If the OUTPUT statement is omitted from the control file,
program will request the file specification at run time.
will be:

the report
The message

OUTFILE NAME:
The ability to supply the output file specification at run time permits you to use the same report program on the same data file to produce a file with a different name and/or device destination.

9.2.5

INPUT

INPUT is a multiline control statement. It specifies the data source
for the report program (Input Statement Line) and describes the input
data file's record structure (Field Description Lines).
HOTE
The input file must be sorted in relation to the break field(s) before it is
supplied to the report program.
This
requirement becomes obvious when you become familiar with the function of a
break field.
The multiline format is:
INPUT [filespec] [/SU] [/IS]
[; comment]
A

[name],

n [. m]

[, Lr [ P] ]

[; comment]
The Input Statement Line and Field
sepa ratel y.

Description

Lines

are

discussed

PRINTU

9-7

Input Statement Line
Taking the INPUT statement by itself, the form is:
INPUT [filespec] [/SU] [/IS]
[; comment]
where:
filespec

is the CTS-300 DIBOL file specification for the
data file from which the report is generated.

input

/SU

is the summary switch. When included, it causes suppression
(during print) of individual values being accumulated. See PRINT, Section 9.2.8.

/IS

indicates that the input data file is an ISAM file to
be read sequentially.
IS must be used when you wish to
generate a report directly from an ISAM file without
using the INDEX statement. See Section 9.2.6.
NOTE
The default condition assumes that the input
data file is a sequential file.
If the input
data file is an ISAM file, either the IS option
or the INDEX statement must be used.

Comments are on a separate line as shown.
If the file specification alone is omitted, the
request it at run time.
The message will be:

report

program

will

INFILE:
The options SU and IS may not be supplied at run time, but can be selected in the control file, with a file specification to be supplied
at run time, by using the form:
INPUT /SU
The ability to supply the input data file specification at run time,
combined with the same ability for the output file, makes it possible
to use a given report program with any number of input data files and
to produce a separate output for each.
Of course, the record structure must be the same in all such input files.
Field Description Lines
Before analyzing a field description line, it is necessary
stand exactly what a field description line does.

under-

One function of a field descripti9n line is to describe the input data
file's record structure.
The data record is partitioned into fields,
and the nature of each field is d~scribed in detail.
These' details
include name, data type, size, and, for decimal fields, number of
decimal places.

9-8

PRINTU

The field description line is also used to identify break fields. The
break field contains data that is constant over a series of records.
However, for each break field there are corresponding fields which may
contain data which can vary from record to record. It is this relationship that is the basis for reports. And, in PRINTU, it also controls when data is printed.
An example may help to clarify this concept:
A record might contain an employee's name, the date, a task code, and
the hours worked for this task code. For a given employee, there will
exist at least one record for every task code for which time was
charged.
In the simplest case, you may want a report showing the
hours worked by each employee.
Here the field containing the
employee's name would be identified as the break field. The report
would then print all the hours worked by each employee. Note that it
may also be desirable to show, for a given employee, the total hours
worked in a given day or on a given task.
More than one break field can be identified. For example, it may also
be desirable to report hours worked for each task code, as well as for
each employee. In this case, task code would also have to be identified as a break field. With more than one break field, a way to show
this relative importance is necessary. PRINTU allows you to identify
both break fields within the control file INPUT statement and to show
their relative importance. In this second case, task code hours would
appear as subtotals every time the task code changed, and a total of
hours by each employee's name would appear as each name changed.
From the preceding paragraphs, it can be seen that a break field controls the printing of data. Whether it is a summary print or a detail
print is also determined by the INPUT statement. Since the file is
read sequentially, the input file must, in the first case above, be
sorted by employee name. If other break fields of lesser importance
were identified, they also would have had to have been identified as
minor keys (in the correct order) in the sort. Task code as a break
field would be identified as a minor key in the sort.
Again, the format for a field description line is:
[ n am e], AJ n [. m] [, Lr [ P] ]
[; commen~
where:
name

is the symbolic name of the field to be used for reference by the COMPUTE and PRINT statements. See Sections
9.2.7 and 9.2.8. It can contain up to six alphanumeric
characters.

indicates alpha or decimal field type.
D

PRINTU

9-9

is the size of the field
acters.

expressed

decimal

char-

is the number of decimal places in
valid only for decimal fields.

the

field

indicates a break field in which the r is a single
decimal digit, which expresses the relative importance
of the break field compared to other break fields (1 is
the least important and 9 is the most important). When
a "break" occurs, the total is printed for fields being
accumulated. This total also includes all other fields
of lower break level. See PRINT, Section 9.2.8.
All
accumulated values are then cleared to zero.

indicates that the report will start a new
the totals for this break are printed.

and

page

after

within

the

Comments are on a separate line as shown.
Twenty is the maximum number of labeled fields
INPUT control statement.

allowable

Example (INPUT statement and field definition lines):
INPUT EXAMPI
;comment line
NAME,
A15,L2P

DATE,
TCODE,
CRATE,
HOURS,

A4,Ll
D3.2
D2.l

Five fields have been identified for the data contained in each record
of file EXAMPI. Data areas within the record that are not of interest
can be ignored by using an unnamed alpha field of appropriate size.
In this example, there is one such area seven characters long. The
two fields, NAME and TCODE, are identified as break fields and NAME is
of greater importance. Whenever the data in TCODE changes, the output
lists specified totals (and individual values, unless a summary is requested) •
The exact format of the data to be printed will be defined
in the PRINT statement (see Section 9.2.8). When NAME changes, the
totals printed include the totals from intermediate TCODE lines. A
new page is started after each NAME change. HOURS is a two-character
field with one decimal place. CRATE is a three-character field with
two decimal places.

9.2.6

INDEX/LIST (Optional)

INDEX and LIST are statements that enable PRINTU to utilize a tag file
generated by the SORT utility. See Chapter 11, SORT/MERGE, and the
TAGS:LIST and TAGS: INDEX options. The usefulness of such a tag file
becomes apparent when you consider that it is unlikely that the input
data file will be arranged in the order that you wish for your report.
9-10

PRINTU

There are two solutions to this problem.
You can either reorder the
input data file, which is especially time-consuming if you wish
several kinds of reports from the same data, or you can use the
SORT-generated tag file.
The tag file allows access to the input data
file in its original form.
Consequently,
it is not necessary to
reorder the entire input file when a different sort sequence is
desired. All you have to do is generate a new tag file.
A tag sort is first carried out on the input data file.
The output is
a file of records containing only the relative record number, or if it
is an ISAM input file, the file contains the SORT keys also.
The tag file is specified for use in PRINTU by either the INDEX or
LIST statement.
When INDEX is used, it implies that the input data
file (as defined by the INPUT statement) is an ISAM file.
When LIST
is used, it implies that the input data file (as defined by the INPUT
statement) is a sequential file.
The format, if the input file is a sequential file, is:
LIST filespec

[;comment]

where:
filespec

is a CTS-300 DISOL file specification of the
generated by the SORT utility.

tag

file

There are no qualifiers with LIST.
The tag file is assumed to consist
of records which are seven-digit decimal numbers.
Example:
LIST DKl:SORTO.DDF
This statement line specifies tag file SORTO.DDF on DKI.
SORTO.DDF is
a result of previously having run SORT with the TAGS:LIST option on
the sequential file defined in the PRINTU control file INPUT statement.
This tag file is a file of seven-digit numbers.
The format, if the input file is an ISAM file, is:
INDEX filespec/recl,key,length

[;comment]

where:
filespec

is a CTS-300 DISOL file specification of the
generated by the SORT utility.

tag

file

recl

is an integer defining the record length
file as generated by the SORT utility.

the

tag

key

is an integer defining the starting
ISAM key within a tag file record.

position

the

length

is an integer defining the length of the ISAM key within a tag file record.

PRINTU

9-11

Example:
INDEX RK1:SRTOUT.DDF/12,8,5
This statement line specifies a secondary input file SRTOUT.DDF on
RKI.
SRTOUT.DDF is the result of previously having run SORT with the
TAGS: INDEX option on the ISAM file defined in the PRINTU control file
INPUT statement. This example indicates that the secondary input file
record length is twelve characters long, and that the ISAM key is five
characters
long,
beginning
at character position eight.
The
seven-character relative record number is not used.
If neither the INDEX nor LIST statement is included in
file, the input file is processed as a sequential file.

9.2.7

the

control

COMPUTE (Optional)

COMPUTE is a multiline control statement that allows you to include
data in your report that does not exist in the input data file.
This
new data is a result of a mathematical process performed on the input
data.
The COMPUTE line is followed by one or more additional lines
describing the mathematical process. There can be up to eight of
these additional lines. The multiline format is:
COMPUTE
[icomment]
name=expression[in]
where:
name

is the symbolic name given to the computation result and is used for reference by the PRINT statement (see Section 9.2.8).
It must neither duplicate any input field name nor any previous computation result name.

expression

is any valid DIBOL expression.
It may be an alpha
or decimal field or a literal. See SPECIAL RULES
below.

is an integer specifying the number of decimal
places the resulting computation will have. See
SPECIAL RULES below.

The comment line is a separate line as shown.

SPECIAL RULES FOR COMPUTE:
These special rules concern the number of decimal places for operands
within a mathmatical operation. The PRINT control statement, unlike
the DIBOL-il language, maintains the number of decimal places.
In all
arithmetic operations, the operands must have an equal number of

9-12

PRINTU

decimal places. Operands can be either constants or variables.
following rules determine the resulting decimal places:
addition (+)

no change in decimal places

subtraction (-)

no change in decimal places

multiplication (*)

the sum of decimal places

division (/)

the difference in decimal places

The

To adjust the number of decimal places of any operand, multiply by a
suitable decimal representation for the constant 1. For example, if
operand 1 has two places, and operand 2 has no places; then operand 1
* operand 2 * 1.00 will be acceptable and will result in a product
which will have four decimal places. For example:
COMPUTE
;compute total pay
TPAY=CRATE*HOURS*1.OO#2
Total pay (TPAY) is equal to compensation rate (CRATE) multiplied
hours worked (HOURS). TPAY is to have two decimal places.

9.2.8

PRINT is a multiline control statement that defines the format of the
final print report and identifies the variable fields that are to be
accumulated (added) and printed as totals for a given break field.
The PRINT control statement is followed by one or more additional
statements describing the overall print format and accumulation
fie~ds.
The multiline format is:
PRINT
[; comment]
name,'text'
or
,An

[,A] [,picture]

where:
name

is the name of a field from an INPUT field description
line (see Section 9.2.5) or the name assigned to a
mathmatical result within a COMPUTE statement (see Section 9.2.7).

text

is a string of characters from the DISOL character set
(excluding single quotes).
This text is used as the
heading for the individual columns for the data fields
identified by name as well as in the line printed for
totals for each break field. An asterisk in the text
string will cause the remaining text to be printed on
the next line. Text is automatically centered. An asterisk is treated as a space when the text is printed.

PRINTU

9-13

indicates that the field is to be accumulated and the
sum is to be printed as a total for a break field.
This field must be decimal.
If the ISU option Were selected in the INPUT statement, only the total would be
printed (summary print), not the intermediate values.

picture

is a string of text in the form of a DIBOL data format
field.
Here it is valid only for decimal fields.
If a
picture is not included, PRINT will create one using
the description of the field.
If it is an accumulated
field, two extra places will be assumed.
The form is:

xx,xxx.xx,An

is an alternate format line that will produce blank
column separators of n characters in width between
printed output columns· (where n is an integer from 1 to
9).
If not included, two blank columns will be
assumed.

The comment line is a separate line as shown.
Example:
PRINT
icomment
NAME,
,A4
TCODE,
,A4
HOURS,
,A3
TPAY,

'EMPLOYEE'
'TASK*CODE'
'HOURS*WORKED' ,A,ZZ.Z
'TOTAL*PAY',A,ZZZZ.XX

Assuming that INPUT and COMPUTE statements remain as previously illustrated, in this example the print output would be:
EMPLOYEE

TASK
CODE

HOURS
WORKED

TOTAL
PAY

namel

codel

Zz.z
ZZ.Z

ZZZZ.XX
ZZZZ.XX

ZZZZ.Z

ZZZZZZ.XX

ZZ.Z
ZZ.Z
ZZ.Z

ZZZZ.XX
ZZZZ.XX
ZZZZ.XX

ZZZZ.Z
ZZZZ.Z

ZZZZZZ.XX
ZZZZZZ.XX

ZZ.Z

ZZZZ.XX

TASK CODE TOTAL
namel

code2

TASK CODE TOTAL
EMPLOYEE TOTAL
name2

9-14

PRINTU

codel
(and so forth)

(New Page)

9.2.9

END (Optional)

The END statement is optional and consists of a line
the word:

containing

only

END

9.3

USING PRINTU

9.3.1

producing the Report Program

Once the control file is written, using PRINTU is a straightforward
process.
The control file is created manually by the user with the
aid of an edit program. The file simply consists of the required
PRINTU statements from Section 9.2 plus any optional statements desired. Regardless of which editor you use to create your PRINTU control file, you will be required to specify a name for the file resulting from your edit session.
Specify this name as input to the PRINTU
program.
The resulting DIBOL program source file is compiled and
linked just like any other such program. The following dialog
illustrates in detail the steps required.
The same control file statements
developed for the examples in Section 9.2 are used.
There are five steps:

Create the control file:
• R DKED
*PTSAMP.TXT=
IDENT PAY/ANALYSIS, YOUR NAME
HEADl'PAY ACCOUNTABILITY'
HEAD2'BY EMPLOYEE AND TASK CODE'
EXECUTE URPROG.TSD
;return to your
;program when
;finished
OUTPUT RKl:PAYACC.DDF
INPUT EXAMPI. DDF
;input file is a sequential file on the default device, no
;summary wanted
NAME, AlS,L2P
A7

DATE, D6
TCODE, A4,Ll
CRATE, 03.2
HOURS, D2~1
COMPUTE·
;compute total pay
TPAY=CRATE*HOURS*l.OO 2
PRINT
;comment
PRINTU

9-15

NAME, 'EMPLOYEE'
,A4
TCODE, 'TASK*CODE'
,A4
HOURS, 'HOURS*WORKED' ,A,ZZ.Z
,A3
TPAY, 'TOTAL*PAY',A,$$$$.XX
END
<GOLD/COMMAND)
EXIT
2.

Run PRINTU:

Enter the following command:
• R (RU) PRINTU
The general form for entry of arguments in PRINTU in response
asterisk prompt is:

the

*outfil,lstfil=txtfil
where:
fl,

outfil

is the CTS-300 DIBOL file specification for the name
assigned to the output of PRINTU.
It consists of the
appropriate device, the name of
the
text
file
containing the PRINTU control file.
Since the output
of PRINTU is supplied to the compiler, an extension of
.DBL should be chosen.

lstfil

is the CTS-300 DIBOL file specification for the
list file.

PRINTU

txtf il

is the name given to the PRINTU
edit session.

control

file

the

For the example being developed here the entry is:
*PTSAMP.DBL,LP:=PTSAMP.TXT
which produces the DIBOL source file PTSAMP.DBL on the default
and a listing of this program on the line printer.

device

It might be useful to first find the syntax errors, using the
ing command:

follow-

*PTSAMP.DBL,TT:=PTSAMP.TXT
edit out the errors, and (assuming you do not need a listing) enter:
*PTSAMP=PTSAMP.TXT
3.

Compile:
.DIBOL PTSAMP

9-16

PRINTU

Link:
.LINK PTSAMP,DIBOL

Run the report program:
.R PTSAMP

NOTE
Ensure that the input file is sorted in relation to
chosen break fields before the report program is run.
Section 9.2.5, INPUT.

the
See

PTSAMP is the report program, and the result of running
it will be
file PAYACC.DDF which is written to RK1 in the format specified in the
PRINT statement.

9.4

ERROR MESSAGES

See Appendix B, Table B-8, for a list of error messages for PRINTU.

PRINTU

9-17

CHAPTER 10
ISAM (ISMUTL)

10.1

INTRODUCTION

ISMUTL is the DIBOL utility program used to build and reorganize
CTS-300 ISAM
(Indexed Sequential Access Method) files.
This chapter
introduces CTS-300 ISAM and its terminology and then explains the
internal structure in the detail necessary for you to be able to build
and use an ISAM file.
Each of the various functions of ISMUTL are
discussed separately,
using flowcharts
(where appropriate), actual
program dialog, and examples.

10.1.1

Features

ISAM files offer several advantages over random or sequential files:
• Simplified record storage and retrieval
• Greater file access speed
• Ability to delete records
• More easily designed and modified to fit the growth
ments of the application.

10.1.2

require-

Chapter Organization

The remainder of this chapter is comprised of three major sections.
First is Section 10.2,
ISAM Basics, for users who are not familiar
with ISAM concepts and terminology.
Section 10.3,
ISAM Internals,
discusses the internal structure of an ISAM file and explains the relationships that exist within the file as well as the factors that
must be considered when designing an ISAM file.
ISAM-related DIBOL
statements are also covered, along with data storage and access.
Section 10.4,
Using ISMUTL, describes the use of the ISAM utility to
create or reorganize your particular ISAM file.
10-1

10.2

ISAM BASICS

The basic concepts and terminology of ISAM are presented in this section.
It is a brief, overall description of an ISAM file.
The purpose is to provide backgr6und for detailed discussions in the following sections. The indexed sequential access method (ISAM) is a means
of organizing data for storage and subsequent access. An ISAM file is
composed of two major sections: the data section and the index section.

10.2.1

Data Section

Records are assigned, in ascending order, to a specific location in an
ISAM file, called the data section, which is comprised of data files.
A user-identified field within the record determines where that record
is stored in a data file within the data section. This field is
called the record key.
In CTS-300 ISAM, there is only one such key
field per record. Records are sequentially stored by this key in data
groups of constant size. These data groups are organized to form as
many as seven data files.
These data files constitute the data section.

10.2.2

Index Section

The greatest record key within each data group is entered, along with
the address of its associated data group, into an index. The index is
contained in the index section, often called the index file.
This
index section
(index file)
is the second major division of an ISAM
file.
By searching this index for a key match, the group which contains the desired record may be quickly accessed.
Each record in the
group is then searched sequentially for a key match, and the desired
record is obtained.

10.2.3

Handling Added Records

Suppose you wish to store a record that, because of its key value,
belongs in a given group but which cannot be placed there because the
group is full.
One solution would be to leave a few empty record
spaces in each group when the file is first constructed and the
initial data is loaded. When this is done, the number of spaces left
empty is called the load exclusion factor.
But what happens when even
these spaces in a given group are filled? A way to handle this is to
set aside an area somewhere within the total ISAM file to place the
new records. This is called the overflow area, and it physically
precedes the index in the index section.
This overflow area is
organized in groups identical to data file groups but, as will be
explained later, access is different.
10-2

ISAM (ISMUTL)

There is one remaining question: How do you add records which have
greater key values than those of any existing group? These new
greater key records cannot go into overflow, because they do not
logically belong in any existing group.
There is no such group,
because when an ISAM file is created from a given input file, the ISAM
file size is determined by the initial space requirements of the input
file.
The solution is to provide space at the end of the data area,
in addition to the known initial space requirement. This area is
known as the append area.
10.2.4

Summary of ISAM Basics

In summary, there are two basic parts to an ISAM file:
the index section and the data section. The index section is by far the smaller of
the two and contains the overflow record groups and the index to the
data portion of the file.
A search for data is made via the index
which points to a data group which is, upon access, searched sequentially for the desired record.
Added records of intermediate key
value go into open record spaces, load exclusion record spaces or, if
the group is full, into the overflow area. Records with keys greater
than the current key range are placed in the append area.
The structure of an ISAM file is illustrated in Figure 10-1.

r-~-~r-----I~~ ~~~~~~..Lln_de_XA+rea_ --<-~-_-~-_~---I

I I I~ I

IFCG ~Gr~upi

I~ ~ I

I I

IFCG ~Gr~upi

I~ ~ I

I I

Index File
File 0

~~11

Data File 1

Data File2

Index
Section

I I

•
•
•

•
•

'l.....r-

Data
Section

~I I I I I I I I

Data File7

Append Area

Data Record

I I

____---J!

Possible wasted space
Exclusion
Records

Figure 10-1 ISAM File Overview

ISAM (ISMUTL)

10-3

10.3

ISAM INTERNALS

The previous section presented a simplified picture of an ISAM file.
However, a more detailed understanding is necessary for the ISAM user
in order to respond to questions asked by a utility (ISMUTL) that will
direct that utility to' construct the index, overflow, and append
areas.
To build a file that provides maximum efficiency in terms of
access speed and storage requirements, requires a thorough and complete understanding of both the ISAM file, itself, and the particular
requirements dictated by the data.
This section, then, discusses the
file structure in detail;
the interrelationships between the various
parts of the file;
and, as an aid to more efficient use, the DISOL
statements used to access ISAM files.
Section 10.3.4 illustrates how
data is handled in an ISAM file.

10.3.1

Detailed Structure

10.3.1.1

Data Files

Data flIes are discussed first, because the overflow area is constructed like a data file, and also because the index and overflow
area are more meaningful after the data file is understood.
As stated before, there may be up to seven data files
(or logical
volumes)
in an ISAM file.
These are labeled 1 through 7.
Logical
volumes are RT-I1 files whi.ch may be located on the same physical
volume
(a disk, for example) or on different physical volumes. All
access to the file is done using the name assigned to the index file.
The main reason for multiple data files is to allow division of the
total ISAM data file over the system resources.
Each of the data files in an ISAM file may be a different size but all
are constructed the same.
Each file is segmented into sequentially
numbered groups of equal size.
The first group (group 0) of each data
file is reserved for system use and contains only 132 bytes of data
that are meaningful, regardless of group size.
This first group is
called the File Control Group (FeG). FCGs are created at the beginning of each data file and at the beginning of the index file when the
ISAM file is created. As the ISAM file changes, only the FCG in the
index file is updated. More information about the FCG is contained in
the index file discussion. All remaining groups in the data file are
data groups.
Each data group consists of a record area and, at. the end of the
group, an area containing linking information to the next logical data
group. Within the record area are the data records which are of equal
length.
Data groups eventually become filled as records are stored.
When each group is filled, the records are ordered so that the last
record in the group has the greatest key. This key is then inserted
in a preassigned position in the index file.
Thus each data group has
a corresponding index entry.
Index space is set aside when the ISAM
file is originally built, with one index entry being allocated per
data group.

10-4

ISAM (ISMUTL)

The last four bytes of each group are reserved for linking and are not
accessible to the user.
The link information consists of one byte indicating the number of presently valid records in the group; one byte
for the file number of the next logical data file;
and two bytes for
the number of the next logical data group within that next logical
data file.
Until overflow occurs, a link will always point to the
next data group in the present file or to the first data group in the
next data file. When overflow~occurs, the link points to a group in
the overflow area. The groups in overflow are identical in structure,
including link structure, to those in the data file.
The link in the
overflow group points back to the original data file if the number of
records requires only one overflow group; or if more than one overflow group were required to contain the overflowed records, the link
in the last overflow group would point back to the original data file.
The append area is simply an extension of the data section, resulting
from the need for more storage area than is indicated by the input
file size. Since the append area is a part of the data section, added
records in the append area may also cause overflow.
The choice of group size depends on many factors and
cussed in Section 10.3.2.

these

are

dis-

Figure 10-2 illustrates the concepts o~ data group organization discussed above using a group that IS 512 bytes in size with five
100-byte records, two of which are identified as load exclusion.
Data File N (Logical Volume N)
Group 3

Group 2

Group 1

GroupO
FCG
132
bytes

~ ..........--------- Group Size 512 bytes - - - - - - - -.....
,.-

I
Record

Record

141-----------

Two records allocated
for load exclusion

------------1*=
I

Record Area, 500 bytes

Fill Area (Unused), 8 bytes

Link, 4 bytes

r---

Figure 10-2 Data Group

ISAM (ISMUTL)

10-5

10.3.1.2

Index File

An ISAM file contains one, and only one, index section
(file).
This
is defined as file O.
File 0 is always examined first to determine
the status of the entire ISAM file and also to determine the group location of a desired'record, or the location of the group in which to
store a record.
The
entire index file is divided into groups which are the same size
I
as the data file groups.
The first group, group 0, as in the data
file, is an FCG.
The first 132 bytes of this group contain a description of the ISAM file structure, file status, and data file allocations in terms of number of groups.
Unlike the data file FCGs, the
FCG for the Index File is updated as the ISAM file grows and changes.
Because CTS-300 ISAM files are designed to be compatible with CTS-500
ISAM files,
the FCG contains some information not used by CTS-300.
Table 10-1 shows the contents of the index file FCG.
Following the FCG group in the index file is the overflow area (if selected)
of a size determined by the user. No index entries were set
aside for the overflow groups, as there were for the data section groups. All records in overflow are accessed via the linking information
in each data file group.
Once a group is accessed, whether a data
file group or an overflow group, the records in that group are accessed sequentially.
The last part of the index section is the index. Since the group size
is the same as in the data file;
and since the key is smaller than
its corresponding record, there are many more index key entries per
group than records per group.
Each index entry consists of the record
key and associated link to its data group or, as you will see, to
another index entry.
If the keys and their links do not fit exactly
into the space available in the group, the unused space is ignored.
To speed access, the index, itself, can be indexed.
The resulting
levels of indexing are determined by an algorithm based on the total
number of data file groups.
In fact, all index entry spaces are preassigned,
and links are preconstructed, based on this total number of
data file groups. The highest (coarsest) level of indexing appears
first in the file and the lowest (finest) level of the index (the
largest part) is at the end of the file.
The higher index entries
point, via index entry links, to lower levels until, at the lowest
level, the index entry points to a specific group in a data file.
The organization of the index area of the index section is shown in
Figure 10-3. This is a hypothetical index for an ISAM file of approximately 8000 records with five data records per group and 20 index entries per group.
There are seven data files with approximately 1200
records (240 groups) per data file.
Keys are numeric, starting with
one.
The illustration is of a search for a record whose key is 5877.
The search is started in the highest (coarsest) level of the index.
In this example this level consists of four entries in group 101. The
search is for a key of equal or greater value than 5877.
The index
entry link for index key 5998 points to group 104. The search of this
group stops at key 5887, whose associated link points to group 157 in
the lowest
(finest)
section of the index area. The search of the
group ends at key 5879 which points, via the link, to data file five,
group 257.
Group 257 is searched sequentially for the desired record.
10-6

ISAM (ISMUTL)

Table 10-1
File Control Group
No.
Bytes

Description

2
2
2
2
2
2

--No~of data groups in this file

2
2
2

No. retries for locked block
No. levels of indexing
Group No. of first group in
primary index
No. index entries per group
No. data records per group
Current No. groups in overflow
Maximum No. groups in overflow
Load exclusion factor (O-n)
File protection code
Group length
Last file in use (0-7)
File 0 clustersize (2-256)
File 1 clustersize (2-256)
File 2 clustersize (2-256)
File 3 clustersize (2-256)
File 4 clustersize (2-256)
File 5 clustersize (2-256)
File 6 clustersize (2-256)
File 7 clustersize (2-256)
Data file 0 allocation
Data file 1 allocation
Data file 2 allocation
Data file 3 allocation
Data file 4 allocation
Data file 5 allocation
Data file 6 allocation
Data file 7 allocation
[proj,prog]filnam.ex
Data file 1 device
Data file 2 device
Data file 3 device
Data file 4 device
Data file 5 device
Data file 6 device
Data file 7 device
Total No. records (low order)
Total No. records (high order)
Multikey ISAM

2
2
2
2
2
2
2
2
2
2
2
2
2
2
2
2
2
2
2
2
2
2
2
2
18
6
6
6
6
6
6
6
2
2
2

No. of records per group
Record length in bytes
Key length (l-n)
Key location in record (l-n)
Allow duplicate keys

Comment

O=no,-l=add at
beginning,+l=add at end

Not used in CTS-300 ISAM (O)
1
1
1

1 Not used in CTS-300
1 ISAM
1
1
1

(No. groups per
file, -65535)
Not used in CTS-300 ISAM
No colon, right space fill

Valid only in index file
Valid only in index file
Always 0 (no mu1tikey for
CTS-300)

132 Total bytes

ISAM (ISMUTL)

10-7

.....

~
Overflow
......1 - - - - Area

~------------------------- IndexArea--------------------_______________~

,......------ Mid Level------""'\

J---- Low Level----S ---------~
\-oS

Index
Section

Data File

Group
1

I }
Data
Section

Records
(Key Shown)

.....
o
I
w

desired
record

10.3.2

Interrelationships and Tradeoffs

There is no file organization that is best for all applications, but
there is one that is better suited to your application. This section
discusses choices and decisions for each file component on an individual basis, starting with the key.
Physical limits imposed by CTS-300
ISAM are also given. Some of these limits may seem impractically
large and should certainly present no problem, but all limits must be
observed.

10.3.2.1
Size:

Key

1 to 100 characters (to change limits, see Section 10.3.2.3).

The key is an ordinary data field, defined within a DISOL
statement, which contains alphabetic or numeric information.

record

CTS-300 ISAM can, optionally, accept duplicate keys.
That is, more
than one record with the same key may be stored. Within the CREATE
dialog, you are asked whether the more recent record is to be stored
before or a~ter other such records with this key.
It is the storage
placement that determines the access order.
If placed before, it will
be accessed first with a READS (sequential read) statement;
if after,
it will be accessed last after all other records with that key.
If you elect to allow duplicate keys, it is wise to provide sufficient
overflow area, because duplicate keys have the potential for unlimited
overflow.

10.3.2.2
Size:

Record

2 to 16,383 bytes (to change limit, see Section 10.3.2.3).

The most important consideration concerning record size is its relation to group size; therefore, record size cannot be selected without
also considering group size. A major design goal for an ISAM file is
to fit as many records as possible in a group with little or no wasted
space.
If the record can be designed so that a multiple will fit the
chosen group size, the file will operate at maximum efficiency.
Too many records in a group could cause a performance degradation, because records are always searched sequentially after the group is accessed.
Too few records per group could limit load exclusion availability, and
the addition of many records in any such group can result in heavy
overflow usage.

ISAM (ISMUTL)

10-9

10.3.2.3

Changing Record and Key Sizes

The standard record length buffer is 1500 characters, and the standard
key length buffer is 100 characters. However, it is possible to create a file with a record or key length that exceeds these limits by
changing the limits in the UTL2.DBL, RORG3.DBL, and CRETl.DBL subroutines used by the ISMUTL program.
Insert the following decimal values
as shown below:
@@@@ = NEW RECORD LENGTH
%%%% = NEW RECORD LENGTH MINUS 132
+++ = NEW KEY LENGTH
Using EDIT:
• R EDIT
*EBUTL 2. DBL$$
*FBUFLN,$5J$4C@@@@$$
*FKEYLN,$5J$3C+++$$
*EX$$
• R EDIT
*EBRORG3.DBL$$
*FRECBUF$lA$FA$4C@@@@$$
*6A$FA$4C%%%%$$
*5A$FA$4C%%%%$$
* 3A$FA$3C+++$$
*EX$$
• R EDIT
*EBCRETl.DBL$$
*FRECBUF$lA$FA$4C@@@@$$
*6A$FA$4C %%%%$$
*4A$FA$4C %%%%$$
*EX$$
After you have modified these routines, you must recompile and
them as shown below for ISMUTL.SAV (SUD system):
.DIBOL/NOLINE UTL2,FCGFX,RORGl,RORG2
no-error response
.DIBOL/NOLINE RORG3,RORG4,STAT,CRETI
no-error response
.DIBOL/NOLINE CRET2,CRET3,NUMQ
no-error response
.LINK/PROMPT/EXE:ISMUTL.SAV UTL2,FCGFX,DATE,DIBOL
RORGl/O:l
RORG2/0:l
RORG3/0:l
RORG4/0:l
STAT/O:l
CRETl/O:l
CRET 2, NUMQ/O: 1
CRET3/0:1//
10-10

ISAM (ISMUTL)

reI ink

10.3.2.4
Size:

Group

132 to 16,383 bytes (additionally the size can not exceed
records) •

127

The first consideration in determining group size is related to machine I/O.
For efficiency, it is best if the ISAM group size is equal
to the machine I/O block size. Data is normally read by the hardware
in blocks of 512 bytes.
Therefore, a group size smaller than the
hardware block size would not use part of the data obtained with each
read.
If the group size is made larger, that is, if a group crosses a
block boundary, the cost may be extra I/O for a given record access.
Another consideration with groups that cross block boundaries is that
it requires additional processing by the run-time system.
In TSD operation, when a record is opened in update mode,
the record
is locked.
Its entire group, and all blocks associated with that
group, are also locked and can not be accessed by another user.
However, I/O byte block size can be changed in whole multiples of 512
bytes with the DIBOL PROC(n) statement. When using the PROC statement
you must remember that it affects all files opened on the system.
Regardless of group size, however, the link area still requires only 4
bytes. Therefore, the record space available would be 508,
1020,
1532, etc. bytes for values of n (in PROC(n»
of 1, 2, 3, etc.
The second consideration is to design records to be placed in this
group, or to make the group fit a multiple of existing records.
If
you are free to design the record, this fit can usually be achieved
with little waste.
On the other hand, if for example you are creating
an ISAM file from an existing sequential file, this can not be done.
In either case, you will likely have to make a decision whether or not
to artificially fill any remaining space in the group.
This is done
at the expense of losing some storage space.
However, it avoids the
performance degradation caused by mismatching the group and block
size.
The amount of space wasted by filling has to be balanced on an
individual basis by evaluating the increased access efficiency.
·Ideally, the amount of fill is small, and the decision to fill is then
the logical one.
The number of load exclusion records chosen for the group has no effect on the total number of records. The purpose of load exclusion
records is to reserve one or more open record spaces within each
group.
It is selected when you expect to add a random distribution of
relatively few records, thus lowering the likelihood of group overflow.

ISAM (ISMUTL)

10-11·

10.3.2.5
Size:

Overflow Area

0 to 16,383 groups

Allocation of overflow area depends on the nature of expected file
growth.
Overflow is required when new records are likely to be distributed unevenly throughout the file.
That is, where the likelihood
is great that there will be many records that logically fall under
one, or a few, keys. The problem with overflow, as mentioned~ before,
is that access within the overflow area must be accomplished via links
and sequential search which involves multiple reads. Within overflow,
the advantages of ISAM are lost, except that storage is still sequential.
Overflow should be used only as a temporary solution to accommodate a particular class of added records. As the overflow area becomes filled, the need to reorganize the file to increase access efficiency becomes greater.
See Section 10.4.5. The manipulation of records by ISAM when overflow occurs is illustrated in Section 10.3.4.

10.3.2.6

Size:

Append Area

0 to number of records determined by system storage limitations

The append area, since it is indexed, does not have the drawbacks associated with the overflow area.
Index entries are created for each
append area group as it is filled.
Efficient use of an append area is
achieved whenever records are added in ascending order by key value.
If a record with a high key value is prematurely stored, this could
eventually cause records with lower key values to be placed in overflow.
If it is the nature of the application that new data records being
added to an existing ISAM file will always or usually have a key with
a greater value than those records already in the ISAM file,
then a
large append area would be required.
In this case, little or no load
exclusion area or overflow area would be necessary since we are not
expecting new data records to have to be inserted between existing
records.
Append area is assigned in whole groups, even though it is specified
in records. ·Thus, if you had previously chosen four records per group
for group size, and specified six records for append, the append area
would be eight records (two groups) in size. Also, ISMUTL always appends a minimum of one group.
So, even if you requested no append
area, in this example there would be space for four records in the append area.
If no input file is specified when creating the ISAM file, the amount
of space allocated in the append area becomes the entire data area of
the file.

10-12

ISAM (ISMUTL)

10.3.3

DIeOL Statements

ISAM file access and data manipulation is accomplished with both standard DIeOL statements and special ISAM DIBOL statements. All bookkeeping and updating involved are handled by the run-time system.
A
complete description of these statements is found in the DIBOL-ll
Language Reference Manual. This section discusses their specific relationship to ISAM files.

NOTE:

All media containing any part of the ISAM file must be
for any 1SAM DIBOL statement operation.

on-line

The following are D1BOL statements used with 1SAM files:

OPEN
This statement for an 1SAM file is in the form:
S1

OPEN (ch,

,filespec)
SU

where:
ch

is the channel to be opened.

indicates input from an 1SAM file;
no change to the
file is allowed, and no records are locked. The following statements may be used with a file opened in SI
mode: READ, READS, and CLOSE.

indicates update of an ISAM file. When specified in a
TSD environment, the record accessed is locked (no
other user may access the record). The ISAM groUp, of
which the 1SAM record is a part, is also locked, as is
any block which is a part of the group.
Any ISAM
statement may be used with a file opened in SU mode.

filespec

is an alphanumeric literal, field, or record that contains the file specification of the file to be opened
in the form dev:filnam.ext.
• The 1SAM file must be opened before any operation
performed.

• The two modes SI and SU are exclusively for ISAM use.
• The OPEN statement opens all volumes of an ISAM
on a single RT-ll channel.

file

• The following statements will unlock a record locked
in update mode: UNLOCK, DELETE, WRITE, STORE, CLOSE,
or a READ of a record in another group.

ISAM (ISMUTL)

10-13

READ
This statement for an ISAM file is in the form:
READ (ch,record,keyf1d)
where:
ch

is the channel opened for the file.

record

is the destination of the retrieved data.

keyf1d

is the ISAM key for the desired record.
• The first record with a key match is the
turned.

record

re-

• If there are duplicate keys, successive records
be accessed with the READS statement.

must

•

If the key is not found, the record with the next
greater key is returned, along with an error message
indicating that the requested key was not found.
If
the key size is less than the size of the data file
key, it is interpreted as a partial key.
In this
case the first record retrieved is the one whose
initial characters match the characters of
the
specified key field.
If the characters do not match,
the record with the next greater partial key is
returned along with the error message.

•

If a READ of a locked record is
remains intact.

attempted,

the

key

READS
This statement for an ISAM file is in the form:
READS (ch,record(,label])
where:
ch

is the channel opened for the file.

record

is the destination of the retrieved data.

label

is the label of the statement where control is
ferred when the ISAM end-of-file is detected.

trans-

• The READS statement is normally issued after a READ;
in which case the next logical block is returned.
•

10-14

If the statement first issued after an OPEN
READS, the first logical record is returned.

ISAM (ISMUTL)

• If a READS of a locked block is attempted, you will
receive an error message indicating the locked block
condition •
• A READS is accomplished using a key value of zero and
there is no erro~ message because of the failure to
find a key match.
WRITE
This statement for an ISAM file is in the form:
WRITE (ch,record,keyfld)
where:
ch

is the channel opened for the file.

record

is the source of the output data.

keyfld

is the ISAM key for the desired record.

A WRITE may be performed only if the record is the one most recently
retrieved by a READ or READS.
It is a read-modify-write operation.
STORE
This is an ISAM statement of the form;
STORE (ch,record,keyfld)
where:
ch

is the channel opened for the file.

record

is the record to be written.

keyfld

is the field containing the key of
stored •

the

record

• This statement places the record in the ISAM file according to its key value •
•

If a record with the same key already exists, and duplicate keys are not allowed, an error is generated.
NOTE:
Do not use the STATUS program
(see STATUS
utility)
kill option or a CTRL/C to terminate a program doing STORES to an ISAM file opened in SU mode.
Such a termination of the program (or the last program, if more than one) will prevent updating of the
index file FCG.
An attempt to REORG this file will
then result in an error message indicating that more
input records were found than were specified. See
the error message table for further information.
ISAM (ISMUTL)

10-15

DELETE
This is an ISAM statement of the form:
DELETE (ch,keyfld)
where:
ch

is the channel opened for the file.

keyfld

is the field containing a value equal to the key of the
record to be deleted.
The keyfield must contain a value equal to the
the last record read.

key

UNLOCK
This is an ISAM statement of the form:
UNLOCK (ch)
where:
ch

is the channel opened for the file.

The UNLOCK statement clears any existing lock condition on the
fied channel.

speci-

CLOSE
The form is:
CLOSE (ch)
where:
ch

is the channel opened for the file.

The CLOSE statement terminates the use of a channel by closing the,
file and releasing the channel. Any record in the device data buffer
is written to the file.
The index file FCG is updated with the number
of records current upon the last close (in a multiuser system) by any
update user (SU).
10.3.4

Data Storage

As will be seen in Section 10.4 ISAM files may be created without any
data as input; with a sequential file as input; or with another ISAM
file as input.
In this section, files will be shown as data is added
to illustrate the characteristics of an ISAM file.
Figure 10-4 shows
an empty file to which records are added. Figure 10-5 shows an ISAM
file created with a sequential file as input, followed by later
addition of records.
10-16

ISAM (ISMUTL)

Records Added to an Empty ISAM File
Consider a data file with group number "Nil as shown in Figure 10-4.
This file was created without any specified input. This is ~ata file
two in an ISAM file whose group size is 512 bytes, each of which contains five records of 100 bytes each.
Each data group in this file
contains, in addition to the 5 records, 8 bytes of unused space, because the fill option was chosen. Figure 10-4 consists of six parts
used to illustrate changes in a data group as records are added and
deleted. The parts, as identified in the figure, are:
a) Initially the group has no data. The only entry is an EOF in
the first record position. The index entry corresponding to
the data group also has an EOF as the key entry.
The link
shows one valid record (the EOF) and points to the next group
in the same data file.
No search of the data file
(or the
ISAM file)
will proceed beyond this EOF record, since it is
the greatest possible key value.
b) A record is added (with the STORE statement) which has a key
value of 13. The EOF is now the second record in the group.
The link shows two valid records, and the index entry remains
unchanged.
c) Records with key values of 15, 17, 18, and 19 are added.
The
records are stored in ascending order. The EOF record is
replaced by the record with the key of 19. The key of 19 is
now placed in the index for this group. No record with a key
greater than 19 can hereafter be placed in this group number
N.
The link for the group indicates 5 valid records.
d) The addition of one more record (key of 16)
now exceeds the
capacity of the group and results in the split to the overflow
area as shown. The index entry for all records in this group
is still 19 but now access to records 17, 18, and 19 is
achieved via the link to overflow.
Data group N contains
copies of records 18 and 19, but the link identifies only
three valid records in this group. The overflow group link
points back to the next logical group (N+l) in the data file.
e) If record 15 were now deleted, the group would be as shown.
The group N link is unchanged except there are now only the
two valid records indicated. Note there are now two copies of
record 18 and three of record 19 shown.
Only the single entries in the overflow group are accessible.
Note that the figure is not to any scale and the information
shown consists only of key values, EOF entries, and link in.formation. The link information is: number of valid records
in the group, number of the next data file, and number of the
next logical record.

ISAM (ISMUTL)

10-17

a) no data
DATA GROUP N

INDEX ENTRY

OVERFLOW GROUP X

' - - - - RECORD AREA --~UNUSED

b) one record (key 13)
DATA

GROUP

II 0

OVERFLOW

2,2,N+1

INDEX

ENTRY

EOF

2,N

GROUP X

I I II
c) four records (keys 15, 17, 18, and 19 added)
,)

DATA

GROUP

I
d)

1 '5 117 1 '8 1 '9
OVERFLOW

index entry of 19

GROUP

INDEX

ENTRY

INDEX

ENTRY

5,2,N+1

I I I 0

record with key of 16 added
DATA

GROUP

3,O,X

OVERFLOW

GROUP

Figure 10-4 Data Storage (File Initially Empty)
10-18

ISAM (ISMUTL)

2,N

record with key of 15 deleted
DATA

GROUP

INDEX

2,O,X

OVERFLOW

GROUP

.7 \.8 \.9 \

\.9

ENTRY

2, N

I 0 3,2,N+'

Figure 10-4 Data Storage (File Initially Empty) (Cont.)
Records Input from a Sequential File during CREATE
When an ISAM file is created with a sequential file specified as the
initial input, the user has the option of selecting the load exclusion
option. This option is illustrated here in Figure 10~5.
This is data
file number 3 in an ISAM file whose group size, as in Figure 10-4, is
512 bytes, each of which contains 5 records of 100 bytes each.
Each
data group in this file contains, in addition to the 5 records, 8
lbytes of unused space, because the fili option was chosen. A load exclusion factor of 2 record spaces has been chosen. The parts of this
figure, as identified, are:
a) When this ISAM file is created, the data from the sequential
input file is immediately entered.
In this example this group
happens to receive records with key values of 13, 17, and 20.
Records with greater key values go into the next group because
the load exclusion of two records prevents further entries
during the creation phase.
The key of 20 is placed in the
index entry for the group. No record with a key greater than
20 can hereafter be placed in this group N. The link for the
group indicates three valid records.
b) At some time after the file is created and all the sequential
file input data is stored, records are added (one at a time,
with the STORE statement) which have key values of 15 and 18.
The link now shows 5 valid records, and the index entry
remains unchanged.
c) A record with a key value of 14 is now added.
The number of
records now exceeds the capacity of the group and a split to
overflow occurs, as with the example in Figure 10-4.
d) The record with key value 13 is now deleted. The only change
is a reduction in the number of valid records in group N and a
shift of the other records to the left. This creates a total
of 3 copies of the record with key value 20. Only the one in
overflow is accessible.
Note that this figure, like Figure 10-4, is not to any scale
and the information shown consists only of key values, EOF entries, and link information.

ISAM (ISMUTL)

10-19

a) data from sequential file as input

DATA

GROUP

INDEX

ENTRY

KEY

LINK

3,3,N+1

LINK
RECORD AREA - - - - - - '
UNUSED

OVERFLOW

GROUP

LINK

records 15 and 18 added
DATA

GROUP

INDEX ENTRY

1. I 1. I rIA
5

OVERFLOW

GROUP

5,3, N+'

I I II 0
c)

record with key of 14 added causing overflow
DATA

GROUP

OVERFLOW

INDEX

GROUP

ENTRY

record with key of 13 deleted
DATA

GROUP

INDEX

2,O,X

OVERFLOW

GROUP

3,3,N+1

Figure 10-5 Data Storage (Sequential File as Input)

10-20

ISAM (ISMUTL)

ENTRY

3,N

10.4

USING ISMUTL

ISMUTL is the OIBOL utility that allows you to select
to define, build, and support the desired ISAM file.
four selectable operations:

the parameters
ISMUTL performs

• An ISAM file is constructed by using the create (CREATE) feature of ISMUTL.
• The status (STATUS) feature of ISMUTL allows the operator to
check file structure, fil~ status, utilization of overflow,
and (in chain mode) append areas. When one or both of the
latter become full, or nearly so, it is usually necessary to
rebuild your ISAM file.
This may be done with either the
create or the reorganization feature of ISMUTL.
• Assuming the basic parameters are still valid, the reorganization
(REORG)
feature of ISMUTL can automatically create a
new ISAM file which restores file expansion areas to their
original values and consolidates all the data. The result is
then a larger
(or perhaps smaller)
addressable
(indexed)
area.
• The exit (EXIT) feature terminates ISMUTL and returns control
to the run-time system (TSO or XMTSO) or the operating system.

10.4.1

ISMUTL Requirements

Before you actually use any of the features of ISMUTL, there are several requirements and characteristics of the utility that must be understood.

10.4.1.1

SUO Operation

In order to execute a OIBOL program that contains ISAM
ments, ISAM must first be selected during CTSGEN.

10.4.1.2

access

state-

TSO Operation

TSD operation with ISAM and ISMUTL requires special attention during
CTSGEN.
The CTSGEN must include ISAM, and a specific number of channels must be specified in CTSGEN, depending on the number of logical
volumes to be assigned in ISMUTL CREATE.
It is also possible to add a
data file durin~ REORG, and this would affect channel requirements.

ISAM (ISMUTL)

10-21

Twelve is the maximum number of channels required if you are creating
or reorganIzIng an ISAM file of seven data volumes. TSD channel requirements, as a function of data volumes, are listed below:
NUMBER OF
LOGICAL DATA
VOLUMES

NUMBER OF
CHANNELS
REQUIRED
6
7
8
9

1
2
3

4
5

10
11
12

NOTE
Under TSD, no other user should access
the ISAM file while it is being created
or reorganized.

10.4.2

Running ISMUTL

Assuming proper linking and a CTSGEN for ISAM, the
ISMUTL.SAV (SUD) is then:

command

for

file

sufficient

chan-

• R ISMUTL
or, assuming proper linking, a CTSGEN for ISAM, and
nels, the command for file ISMUTL.TSD (TSD) is:
*R ISMUTL

The response is:
CTS300 ISAM UTILITY PROGRAM, Vnn-OOn
SELECT FUNCTION (CREATE,STATUS,REORGANIZE, OR EXIT):
Your response to this selection message is the first letter of the
chosen function. But first see the appropriate section below for the
operating details of that function.

10.4.3

Creating a File (CREATE)

The previous sections of this chapter have covered the ISAM file and
its structure.
This section contains a discussion of the special
chara~teristics of CREATE and details of the CREATE process.

10-22

ISAM (ISMUTL)

10.4.3.1

Special CREATE Characteristics

Input File
Input for ISAM file creation may be a sequential file;
another ISAM
file;
or an ISAM file may be created without an input file.
If the
input is a sequential file, there is a special requirement:
the file
must first be sorted in ascending order by the same key that will become the ISAM key.
After naming the
the input file
CREATE opens two
keep track of
same-name file.

input file, you will be asked if you want to delete
after CREATE.
If you chose to delete the input file,
checkpoint files which,
in an alternating manner,
the cleanup process associated with the deletion of a

If a machine malfunction occurs during CREATE with the input file deleted,
the checkpoint files allow resumption at the correct point.
See Section 10.4.3.5 for details on restarting the process.
NOTE:
If you do decide to delete your input file,
you may want to
make a back-up copy to eliminate loss of data due to a hardware malfunction.
NOTE
Certain ASCII characters must be avoided
in ISAM files.
These characters (listed
below) interact with intermediate work
files during ISMUTL CREATE or later
REORG.
Any of these characters will
cause truncation of the record in which
it is found.
Character

Decimal Code

Null

9
10
11
12
13
26
27

LF
VT

FF
CR
~Z

Esc
Output File

You must name the resulting ISAM file at the beginning of the CREATE
dialog.
Allocation of the index and data files to the system resources (devices) takes place at the end of the dialog.

ISAM (ISMUTL)

10-23

The output file name can be any six-character file name.
The default
extension is
.ISM, which is assigned to the index file.
The data
files are assigned default extensions of .ISI through .IS7.
If an extension is specified, it must be at least two characters long;
if it
is three characters, the last character can not include the numbers 1
through 7.
These numbers are assigned by ISMUTL and' will override any
third character position. The extension .ROG can not be used either,
since that is a temporary extension used by the system when the file
is reorganized.
If the output file name is the same as the input file
name, temporary files, .TMP and .TMI through .TM7, are built by CREATE
and there should be no other files of that name on the system.
Device identification takes place at the end of the CREATE dialog when
files are allocated.
There must be enough contiguous space on each
device to open its data file and, for one device, to open the index
file as well.
If any difficulty arises, see Section 10.4.3.5.
Ordinarily volumes containing data files must always be mounted for
use on the same devices and units as those on which they were created.
However, by using the RT-ll ASSIGN command for device names, you are
not restricted to the same physical devices.
Total File Requirements
In addition to files already mentioned, in all CREATE operations there
are also two work files that are opened to build the output index
file.
CREATE will try to find space for the work files on the device
you specify for your output files.
If enough space is not found, CREATE will ask for additional devices.
These are temporary files that
will be deleted automatically after CREATE has built the index file.
Below is a summary of the files that will be
depending on deletion and same-name choices:

automatically

If you wish to delete the input file and both input and
have the same name:

created,

output

files

filnam.CKI
(checkpoint file on system device)
filnam.CK2
(checkpoint file on system device)
filnam.TMP
(temporary file)
filnam.TMI to .TM7 (depending on the number of input data files)
filnam.ROG
(temporary REORG file)
filnam.ROI to .R07 (depending on the number of input data files)
filnam.WKO
(work file)
filnam.WKl
(work file)
If you wish only to delete the input file:
filnam.CKl
filnam.CK2
filnam.WKO
filnam.WKI

(checkpoint file on system device)
(checkpoint file on system device)
(work file)
(work file)

If you do not wish to delete the input file:
filnam.WKO (work file)
filnam.WKl (work file)

10-24

ISAM (ISMUTL)

Auto-Create
The CREATE function includes the optional capability of operating from
an external data file of input responses. This is a special function
for experienced users and should not, in any case, be invoked to create a file with unproven parameters. For this reason, a complete discussion of this capability is provided under Section 10.4.7.2,
rather
than here.

10.4.3.2

Design/CREATE Process

Creating an ISAM file is a five-step process.
steps are preliminary to running CREATE:

The first four of these

Determine the key/record/group/block size relationship.

Determine record addition characteristics for load exclusion,
overflow, and append area requirements.

Determine the output names.

To satisfy requirements which apply to your proposed ISAM
file, determine the following in advance of running CREATE:
• Whether to do an auto-create
• Input file (name, ext .DDF assumed)
• Whether to delete your input file (ISAM or sequential only)
• Output file name
• Approximate number of input records (sequential only)
• Record length (only if no input file)
• Number of records per group
• Load exclusion value
• Whether to fill out the group to end of block boundary
• Append area size
• Overflow area size
The following two factors are automatically supplied
input file is an ISAM file:

the

• Key length
• Key location

ISAM (ISMUTL)

10-25

• Whether to allow duplicate keys, and,
if so, whether to
place at beginning or end ( j f ISAM input file, question appears only if not already allowed)
• Output allocation:
Index File
Data Files
The device is specified without the colon.
5.

Select CREATE by typing C in response to the ISMUTL selection
message and enter the values you have just determined. The
following section will help you during the CREATE process.

10.4.3.3

CREATE Dialog

This section contains the actual text for the create process.
All
create questions are included here, even though no given create could
include every question. Allowable ranges are shown as a final check
on your answer. Figure 10-6 illustrates the dialog flow for the possible input file types and subsequent choices.
The following is the CREATE dialog:
DO YOU WANT TO DO AN AUTO-CREATE?

(YES/NO)

Answer NO, or carriage return, unless you are familiar with the
auto-create process. The special procedures for this function are detailed in Section 10.4.7.2.
INPUT FILE (DEV:NAME.EXT):
If not specified, assumed device is the default device and assumed extension is
.DDF.
A carriage return implies no input file, in which
case the next question does not appear.
DELETE INPUT FILE AFTER CREATE (YES/NO):
If yes, your input file will be automatically deleted after the output
file is created.
OUTPUT FILE (NAME. EXT, DEFAULT EXT=ISM):
Just enter the file name;

device names are supplied later.

APPROXIMATE NUMBER OF INPUT RECORDS (0-16,777,215):
Appears only if sequential input is specified.
the system limit. Unneeded space is not used.
the size of the work files.

10-26

ISAM (ISMUTL)

You can specify up to
Your answer determines

.R ISMUTL

FUNCTION AND FILE SPECIFICATION

PROGRAM,~V04-00E

CTS300 ISAM UTILITY
SELECT FUNCTION (CREATE, STATUS, REORGANIZE, OR EXIT): C
DO YOU WA'NT TO 00 AN AUTO-CREATE? (YES/NO)

INPUT FILE (DEV:NAME.EXT):

DF or IF

S•• S.ctlon
10.4.7.2

NFS

DELETE INPUT FILE AFTER CREATE (YES/NO)

OUTPUT FILE (NAME.EXT. DEFAULT EXT=ISM):

Nfs_______________________

,IF._______

APPROXIMATE NUMBER OF INPUT RECORDS (0-16,777,215):
GROUP SPECIFICATION INFORMATION

RECORD LENGTH, IN BYTES 2-16.383):

L-______________~------~~----~

NUMBER OF RECORDS PER
, PHYSICAL GROUP (x-x):

I
DF or IF

NFS

M••••g. to u••r:
LOAD EXCLUSION INFORMATION FOR FUTURE REORGANIZATIONS
LOAD EXCLUSION FACTOR. IN RECORDS (O-x):

I. group I.ngth (In byt•• ) • multiple of 512?

FILL OUT GROUP TO END OF PHYSICAL BLOCK? (YES/NO)

FILE EXPANSION AREA INFORMATION

NUMBER OF RECORDS IN APPEND AREA (k):

KEY INFORMATION

SIZE OF OVERFLOW AREA IN GROUPS (0-16,383):
I

DF or NFS

KEY LtNGTH:

Dupllc.te key. In Input file?

KEY LOCATION:

ALLOW DUPLICA E KEYS (YES/NO):

Y
ADD DUPLICATES TO

INDEX FILE ALLOCATION

BEGINNING~OR

END OF SUBSET (BEGIN/END):

INDEX FILE REQUIRES x BLOCKS
INDEX FILE DEVICE (RETURN IMPLIES SYSTEM DEFAULT DEV.):

-------------------------------------------------------------~------------------------------~-DATA FILE ALLOCATION
A TOTAL OF x RECORD SPACES ARE ALLOCATED.
KEY
UPPER CASE = Sy.tem output
Upper .nd lowerc••• = Comment.
INPUT FILE TYPE:
DF = An exl.tlng .equentlal data file
IF = An exl.tlng ISAM file
NFS = No file .peclfled

APPROXIMATELY Y BLOCKS OF DISK SPACE ARE
DATA FILE 1 DEVICE (RETURN IMPLIES SYSTEM
DATA FI.LE 1 ALLOCATION (1-x):
DATA FILE N DEVICE (RETURN IMPLIES SYSTEM
DATA FILE N ALLOCATION (1-%):
Rep ••ted to N=7 If necess.ry to
r.qulred block. to de.'red device•.

assign

all

Figure 10-6 ISAM CREATE Flowchart
ISAM (ISMUTL)

10-27

RECORD LENGTH, IN BYTES (2-16,383):
Appears only if no input is specified.
NUMBER OF RECORDS PER PHYSICAL GROUP (x-x):
The range is determined by a mInImum group size of 132 bytes and by a
maximum group size of 127 records or 16,383 bytes, whichever is
larger.
LOAD EXCLUSION INFORMATION FOR FUTURE REORGANIZATION
Appears only if there is no specified input file.
Since there is no
initial data, there can be no exclusion. However, when the file is
reorganized, the amount of exclusion selected here will be provided.
LOAD EXCLUSION FACTOR, IN RECORDS (O-x):
The maximum number of records that can be allocated for exclusion is
always one less than the total number of records in a group.
If there
were no input file specified, this message would be preceded by the
following:
FILL OUT GROUP TO END OF PHYSICAL BLOCK?

(YES/NO)

This answer depends on the record/group/block size relationships
is a matter of jUdgement. You trade efficiency for access speed.

and

NUMBER OF RECORDS IN APPEND AREA (O-x):
The append area is for the addition of records with key values greater
than the initial input.
Although the low range of your choice is
labeled 0, you actually get at least one group. The maximum number is
limited by system storage capacity.
SIZE OF OVERFLOW AREA IN GROUPS

(0-16,383):

The overflow area is for addition of records of intermediate key value
to groups that may eventually be filled.
KEY LENGTH
Key length is the length of the key in bytes.
input is not an ISAM file.

I~ appears only if your

KEY LOCATION
Key location is the beginning byte position of the key within the record.
The first byte position of a record is number one.
It appears
only if your input is not an ISAM file.
ALLOW DUPLICATE KEYS

(YES/NO):

Do you wish to allow more than one record with the same key value? It
appears only if your input is not an ISAM file, or if your input ISAM
file did not allow duplicate keys.

10-28

ISAM (ISMUTL)

ADD DUPLICATE KEYS TO BEGINNING OR END OF SUBSET (BEGIN/END):
To place added records before or after existing records with the same
key, respond with B or E.
Storage at the beginning means that the
last record will be stored at the beginning of the duplicate set and
will be the first record accessed with a READ.
Storage at the end
means tbat the last record will be stored at the end of the duplicate
set and will be the last record accessed with a READS. This question
is not asked if duplicates are not allowed.
INDEX FILE ALLOCATION.
INDEX FILE REQUIRES x BLOCKS.
INDEX FILE DEVICE (RETURN IMPLIES SYSTEM DEFAULT DEV.):
The program has calculated the space requirement for the index file.
The x indicates the blocks necessary to create the index file.
Respond with the device you want without the colon. A carriage return
indicates the default device. The entire index file must be on a single device.
DATA FILE ALLOCATION.
A TOTAL OF x RECORD SPACES ARE ALLOCATED.
APPROXIMATELY Y BLOCKS OF DISK SPACE ARE REQUIRED.
DATA FILE 1 DEVICE (RETURN IMPLIES SYSTEM DEFAULT DEVICE):
At this point you must finalize your decision on how many files (logical volumes) the ISAM file will have and upon what device(s) they will
be placed. The values of x and yare approximations, but they are
close enough to indicate space requirements. With a small file, it
may be possible to place the entire data file on the same device as
the index file.
Select the device, without the colon, for the first
data file.
DATA FILE 1 ALLOCATION (I-x):
Assign the blocks to the first device. The range is from one to the
maximum required.
Select a value in keeping with the disk capacity.
If a choice is lower than the upper limit, unassigned blocks will have
to be assigned to other data volumes. The above sequence of assignment of device and blocks will continue as follows:
NOTE
A choice higher than, or equal to, the
upper limit will default to the upper
limit, thereby terminating the dialog.
DATA FILE 2 (through 7) DEVICE (RETURN IMPLIES SYSTEM DEFAULT DEVICE):
Assign device two (through seven).
DATA FILE 2 ALLOCATION (l-n):
Assign the blocks to the second (through seventh) device. There will
be a diminishing number of blocks to be assigned, as indicated by the
value of n.
ISAM (ISMUTL)

10-29

If the end of the sequence is reached but not all the blocks have been
assigned, the process is repeated, starting at the beginning of the
data file assignment sequence.
It is recommended that you keep an ISAM file on as few physical and
logical volumes as possible because nothing is gained unless you have
a fragmented disk due to bad blocks.
If any difficulty is encountered, see Section 10.4.3.5.

10.4.3.4

CREATE Example

The following is an example of the dialog for the creation of an ISAM
file from a sequential input file.
The input file is known to consist
of 72-byte records with the key of eight bytes located at the beginning of the file.
Seven records per group will be chosen to allow a
group to exist within a 512 byte block.
Since this leaves little
wasted space, fill-out to the end of the block is chosen. There are
somewhat less than 250 records in the input file.
New records to be stored are expected to be scattered throughout the
file and, in addition, there will be new records whose key values are
greater than any presently existing in the input file. A load exclusion factor of two is chosen to handle the initial scattered records
of intermediate key value. There are most likely less than 700 new
intermediate records to be added that cannot be accommodated by load
exclusion; however, an overflow area of 100 groups is chosen.
There
are estimated to be somewhat less than 200 records that will be added
to this file that have greater than present key values.
A value of
200 records is therefore chosen for the append area size. Duplicate
keys will not be allowed.
After file allocation is complete, ISMUTL automatically gives you the
status of the new file.
Notice the values.
Later, in Section
10.4.4.1, STATUS Example, this same file with added records will be
shown.
The CREATE example is on the next page.

10-30

ISAlVI (ISMUTL)

The CREATE Example:

.R ISMUTL
CTS300 ISAM UTILITY PROGRAM, V06-00
SELECT FUNCTION (CREATE, STATUS, REORGANIZE, OR EXIT):
DO YOU WISH TO DO AN AUTO - CREATE? N
INPUT FILE (DEV:NAME.EXT): XDATA1.DDF

DELETE INPUT FILE AFTER CREATE (YES/NO): N
OUTPUT FILE (NAME.EXT, DEFAULT EXT=ISM): XDATA1.ISM
APPROXIMATE NUMBER OF INPUT RECORDS (0-16,777,215): 250
GROUP SPECIFICATION INFORMATION.
NUMBER OF RECORDS PER PHYSICAL GROUP (2-127):
7
LOAD EXCLUSION FACTOR, IN RECORDS (0-6):
2
FILL OUT GROUP TO END OF PHYSICAL BLOCK? (YES/NO)
FILE EXPANSION AREA INFORMATION.
NUMBER OF RECORDS IN APPEND AREA (0-16,776,863):
SIZE OF OVERFLOW AREA IN GROUPS (0-16383): 100
KEY INFORMATION.
KEY LENGTH: 8
KEY LOCATION: 1
ALLOW DUPLICATE KEYS (YES/NO):

200

INDEX FILE ALLOCATION.
INDEX FILE REQUIRES 107 BLOCKS.
INDEX FILE DEVICE (RETURN IMPLIES SYSTEM DEFAULT DEV.)
DATA FILE ALLOCATION.
A TOTAL OF 553 RECORD SPACES ARE ALLOCATED.
APPROXIMATELY 80 BLOCKS OF DISK SPACE ARE REQUIRED.
DATA FILE 1 DEVICE (RETURN IMPLIES SYSTEM DEFAULT DEVICE)
DATA FILE 1 ALLOCATION (2-80): 80
GROUPS ALLOCATED
14-APR-80
FILE LOCATION
104
KEY LENGTH IS- 8
INDEX FILE
DK
78
RECORD LENGTH IS- 72
DATA FILE tl DK
LEVELS OF INDEXING IS- 1
LOAD EXCLUSION FACTOR- 2
KEY STARTS AT LOCATION- 1
DUPLICATE KEYS ALLOWED- NONE
CURRENT NUMBER OF RECORDS- 238
GROUPS ALLOCATED TO OVERFLOW- 100
GROUPS REMAINING IN OVERFLOW- 100
NUMBER OF RECORDS PER GROUP- 7
GROUP LENGTH IS- 512
SELECT FUNCTION (CREATE, STATUS, REORGANIZE, OR EXIT): E
END ISAM UTILITY.
Note that the ISAM file created in the example could become an inefficient file because such a large overflow area was chosen. Because of
this large overflow area, the index file is larger than the one data
file.

ISAM (ISMUTL)

10-31

10.4.3.5

Handling CREATE Problems

Failure During Clean-up
If a machine malfunction occurs during the cleanup routine of a CREATE
with input file deleted, it is possible to complete the operation. To
do so, you must have at least one of the checkpoint files on the system device.
Start the CREATE again and specify the same file previously named in response to the input file question.
The program
searches for a file with the CKI or CK2 extension and, when found,
restarts and completes the function automatically.
NOTE: Remember that if CREATE does not terminate normally, do not delete temporary files, work files, or checkpoint files.
Doing so may
result in the loss of your input ISAM file.
More Space Required for Output Files
If, at the end of the CREATE dialog, you have failed to allocate
the space required by the ISAM file, you will receive a message:

all

ALL FILES ALLOCATED AND MORE
SPACE IS REQUIRED.
PLEASE TRY AGAIN.
The allocation sequence starts again, and you must allocate all of the
required file space before you reach the end.
Insufficient Work File Space
It is possible that there is not enough space for the CREATE function
to open all the files necessary to operate.
If this is the case, the
following message will appear:
WORK FILES REQUIRE x BLOCKS OF DISK SPACE
WORK FILE DEVICE:
Respond with a device name.

10.4.4

Determining the Status of an ISAM File (STATUS)

10.4.4.1

STATUS Selection and Characteristics

To determine the status of an ISAM file, type S in response to the
ISMUTL selection message.
The program responds with a description of
group structure, of current number of records, and of how much
overflow area has been used. Status selected in this manner does not
provide any information on the append area space which remains.
To
obtain information on the free append space, see Section 10.4.7.1.

10-32

ISAM (ISMUTL)

10.4.4.2

STATUS Example

The ISAM file created in the example in Section 10.4.3.4 is used to
illustrate the changed STATUS information after the addition of some
records.
The number of records has increased by 110 records to a total of 348
records.
There are now 12 overflow groups in use for a maximum of 84
records in overflow (12 x 7 records/group);
therefore, the remaining
added records are probably accounted for by load exclusion record
spaces becoming filled and by records going into the append area.
This same file is reorganized in Section 10.4.5.3.
The STATUS Example:

.R ISMUTl
CTS300 ISAM UTILITY PROGRAM, V06-00
SELECT FUNCTIO~ (CREATE, STATUS, REORGANIZE, OR EXIT): S
INPUT FILE (DEV:NAME.EXT): XDATA1.ISM
GROUPS ALLOCATED
14-APR-80
fILE LOCATION
KEY LENGTH IS- 8
INDEX FILE
DK
104
RECORD LENGTH IS- 72
DATA FILE tl DK
78
lEVELS OF INDEXING IS- 1
LOAD EXCLUSION FACTOR- 2
KEY STARTS AT LOCATION- 1
DUPLICATE KEYS ALLOWED- NONE
CURRENT NUMBER OF RECORDS- 348
GROUPS ALLOCATED TO OVERFlOW- 100
GROUPS REMAINING IN OVERFlOW- 88
NUMBER OF RECORDS PER GROUP- 7
GROUP LENGTH IS- 512
SELECT FUNCTION (CREATE~ STATUS, REORGANIZE~ OR EXIT): E
END ISAM UTILITY.

10.4.5

Reorganizing a File (REORG)

As you add and delete records in an ISAM file,
the sequential order
and
index are maintained, except, of course, there are no index entries for overflow records. When load exclusion, append, or overflow
areas become filled, or performance deteriorates, you will want to restore these areas and place all records into indexed data groups.
There are two ways to reorganize an ISAM file.
You can rerun CREATE
or run REORG.
If you do not WIsh to change the original specifications,
REORG is the logical choice.
REORG allows continued growth in
the manner originally specified, and it does not permit you to change
any of these specifications;
however,
if the resulting file is
larger, you must specify how to allocate more space.
Except for dialog, the process is the same as a CREATE.

ISAM (ISMUTL)

10-33

10.4.5.1

Special REORG Characteristics

Input File
The input for a REORG is your present ISAM file.
deleted, and the new file will be created.

This

file

will

Output File
The output file has the same name as the input file.
There are
temporary extensions assigned to the output files of .ROG and .ROI
through • R07.
Note that the volumes containing data files must always be mounted for
use on the same devices and units as those on which they were created
(by CREATE or REORG). By using the RT-ll ASSIGN command for device
names, you are not restricted to the same physical devices.
File Growth
The amount of growth is determined by a comparison of the number of
records in the present file with the number of records in the file
just after the last REORG or CREATE.
Since the overflow area size
does not change, the index expands or decreases by the space required
for key entries. Since append and load exclusion are restored to
their original values, the data area increases by a combination of
records added from overflow, append, and load exclusion; or decreases
as a result of records deleted.
Total File Requirements
Because the input file is deleted and because the output file has the
same name as the input, the REORG function is similar to the CREATE
function with deleted input and same input/output name.
The files
created are the same as the CREATE function under these conditions,
namely:
filnam.CKl
(checkpoint file on system device)
filnam .CK2
(checkpoint file on system device)
filnam.TMP
(temporary file)
filnam. TMI through .TM7
(depending on the number of input data f i 1 es)
filnam.ROG
(temporary REORG file)
filnam.ROl through .R07
(depending on the number of input data f i 1 es)
filnam.WKO
(work f il e)
filnam.WKl
(work f il e)

10-34

ISAM (ISMUTL)

Until enough space is found to open all the required output files, the
actual reorganization cannot start. After the output files are built,
REORG enters the cleanup routine. The cleanup routine:
1.

Writes a dummy checkpoint file.

Renames input files to .TMP and .TMI through .TM7.

Renames output files to correct extensions.

Rewrites the output FCGs.

Deletes input files.

Checks to see if all output files are on the correct
(If yes, go to step 8.)

Moves files, if possible, to the correct device. After every
successful move, it rewrites the FCG.
If there is not enough
room on a device, it terminates the REORG and te~ls you which
device did not have enough room.

Rewrites a correct and complete FCG and gives you a status.

drives.

If REORG fails during this process, see Section 10.4.5.4.

10.4.5.2

REORG Process and Dialog

To run REORG, type R in response to the ISMUTL selection message. The
program asks you for the name of the ISAM input file, and then
proceeds with the reorganization. During the process, you may be
asked to provide more work file space, or be notified of a problem
during the cleanup procedure associated with the deletion of the input
file.
If any of these occur, see Section 10.4.5.4. The last response
you will have to make is in regard to allocation of space for the
added records in the indexed data files.
The following is the text
that will appear for a reorganization:
INPUT FILE (DEV:NAME.EXT):
This is your ISAM file to be reorganized.
APPROXIMATELY XX ADDITIONAL BLOCKS OF DISK SPACE REQUIRED
A=ADD EQUALLY TO EACH DATA FILE - B=ADD TO LAST DATA FILE
C=ADD EXTRA DATA FILE
PLEASE RESPOND WITH A,B OR C:
If you respond with C, the following additional question is asked:
ASSIGN DATA FILE DEVICE:
Respond with a device to accommodate the added file requirements.

ISAM (ISMUTL)

10-35

10.4.5.3

REORG Example

The ISAM file illustrated in Sections 10.4.3.4 and 10.4.4.1
(CREATE
and STATUS examples), is used to show the effect doing a reorganization has on a file with records in overflow, load exclusion, and the
append area.
The reorganization dialog consists essentially of specifying the input
file and of allocating additional storage space. The automatic status
response shows the file after the reorganization.
The new file has the same 348 records as indicated in Section
10.4.4.1; but now the overflow area has been restored to a full 100
groups. Although not shown, the load exclusion record spaces and append area have also been restored. All the records are now in indexed
data groups. Consequently the data file has increased by 22 groups
and the index file by one group.
The REORG Example:

.R ISMUTL
CTS300 ISAM UTILITY PROGRAM, V06-00
SELECT FUNCTION (CREATE, STATUS, REORGANIZE, OR EXIT):
INPUT FILE (DEV:NAME.EXT): XDATA1.ISM

APPROXIMATELY 23 ADDITIONAL BLOCKS OF DISK SPACE ARE REQUIRED
A=ADD EQUALLY TO EACH DATA FILE
B=ADD TO LAST DATA FILE
C=ADD EXTRA DATA FILE
PLEASE RESPOND WITH A,B OR C:
A
GROUPS ALLOCATED
FILE LOCATION
14····APR··80
105
DK
INDEX FILE
KEY LENGTH IS- 8
100
DATA FILE :JI:l DK
RECORD LENGTH IS- 72
LEVELS OF INDEXING IS- 1
LOAD EXCLUSION FACTOR- 2
KEY STARTS AT LOCATION- 1
DUPLICATE KEYS ALLOWED- NONE
CURRENT NUMBER OF RECORDS- 348
GROUPS ALLOCATED TO OVERFLOW- 100
GROUPS REMAINING IN OVERFLOW- 100
NUMBER OF RECORDS PER GROUP- 7
GROUP LENGTH IS- 512
SELECT FUNCTION (CREATE, STATUS, REORGANIZE, OR EXIT): E
END ISAM UTILITY.

10-36

ISM (ISMUTL)

10.4.5.4

Handling REORG Problems

Failure During Cleanup
If a machine malfunction or.a forced termination occurs during REORG,
it is still possible to complete the operation. Do not delete any
temporary files, work files, or checkpoint files and
just start the
REORG again and specify the input file name.
The program searches for
a file with the CKI or CK2 extension and, when found,
restarts and
completes the function.
Insufficient Space to Open Output Files
There are three ways you can deal with this situation. The method you
use depends on your file and your system. The possible solutions are:
~he

disk(s), and
of the checkpoint

Eliminate all unnecessary files,
squeeze
retry ISMUTL.
This process makes use
files.

Eliminate all the unnecessary files, including the input and
checkpoint files, squeeze the disk(s), and start the entire
process over. To do this, you must have a backup copy of the
input.

Write a small program to convert your ISAM input file into a
sequential file and, using this file, use CREATE to produce
the desired ISAM file.

Insufficient Work File Space
REORG attempts to open output files on the same devices as the input
file counterparts.
If this is not possible, due to space limitations,
a work device is requested via the message:
WORK FILES REQUIRE x BLOCKS OF DISK SPACE
WORK FILE DEVICE:
Respond to this with a device name.
If the specified device does not
have enough space, the question will be repeated. Be sure that none
of the devices made available to REORG have files with the same name
as the input file;
files with .ROG extension (or .ROI through .R07);
or files with .CKn extensions. Any existing file of this same name
will be deleted.
Until enough space is found to open all the required files
the index build work files), reorganization cannot start.

(including

ISAM (ISMUTL)

10-37

10.4.6

Exiting from ISMUTL (EXIT)

When you no longer need ISMUTL, you may return to the monitor or the
operating system by responding to the ISMUTL selection message with an
E.
The response is:
END ISAM UTILITY
In chain mode, the utility automatically chains to the specified
program.
10.4.7

Miscellaneous ISMUTL Capabilities

10.4.7.1

STATUS and REORG in Chain Mode

user

STATUS and REORG can be automated.
If you end your program with
ISMUTL as the optional argument with the STOP statement, control is
automatically passed to the ISAM utility program.
Within your user
program, you must previously send, with the SEND statement, a record
of directions to ISMUTL.
Depending on the function to be performed,
the record must contain specific field sizes in a certain order. An
example for REORG and for STATUS is shown below.
It illustrates the
required format for the record.
Example of a record sent to do a REORG:
USER PROGRAM (USPROG)
RECORD REORG
FNCT,
AI, 'R'
CHNFLG,
Dl
FILIN,
USRPG,
ADBLR,
EXPDV,
WORKNM,
\'lORKDV,

Al?,'DK:ISAM.ISM'
AI?
Al
A6

Dl
8A6

iDO A REORG
iO=DO NOT CHAIN TO USER
iSET USRPG TO SPACES

PROGRAM

i1=CHAIN TO USRPG
iYOUR ISAM FILE
iPROGRAM TO CHAIN TO
iADDITIONAL SPACE (A, B, OR C)
iDEV IF C (SPACES IF A OR B)
iNUMBER OF WORK FILES
i (1-8 DEVICES) (3 CHAR DEVICE NAME,
iNa COLON !)
iIF THE NUMBER IS LESS THAN 8,
iREMAINDER IS FILLED IN WITH SPACES

PROC

SEND (REORG,'ISMUTL',TERM)

.iTERM=NUMBER OF TERMINAL
iYOU ARE CURRENTLY
iRUNNING ON

STOP 'I SMUTL'

iSTOP THIS PROGRAM START
iUP ISMUTL

10-38

ISAM (ISMUTL)

Example of a record sent to do a STATUS:
In the following example, the first time the user program (USPROG.SAV)
is run, there is no message to receive, so the record STATUS is therefore sent to ISMUTL with instructions to chain
(fields CHNFLG and
USRPG) to USPROG.SAV.
At the end of the ISMUTL STATUS function, a record is sent to the user
program (specified by USRPG), and ISMUTL chains to USPROG. The record
STAT must contain the fields shown in order to receive the STATUS information sent by ISMUTL.
USER PROGRAM (USPROG)
RECORD STATUS
FNCT,
AI, 's'
CHNFLG,
D1, '1 '
FILIN,
USRPG,

A17,'DK:ISAM.ISM'
A17,'USPROG.SAV'
A56

APDFLG,

RECORD STAT
CUROFL,
D6
TOTOFL,
D6
TOTREC,
D12
ORGREC,
D12
APDREC,
D8

iDO A STATUS
iO=DO NOT CHAIN TO USRPG (SET
iUSRPG TO SPACES)
i1=CHAIN TO USRPG
iYOUR ISAM FtLE
iFILE TO CHAIN TO
iFILLER
iO=DO NOT RETURN APPEND RECORDS,
iNON ZERO VALUE
i= RETURN # APPEND RECORDS
iNO. OF UNUSED OVRFLOW GROUPS
iNO. OF GROUPS ALLOCATED TO OVRFLOW
iC~RRENT NO. OF RECORDS IN FILE
iORIG NO OF RECORDS IN FILE
iREMAINING NO. OF RECORD SPACES IN
iTHE APPEND AREA

PROC

RECV (STAT, LABEL)

;CHECK FOR STATUS INFO. IF NONE,
iSEND MESSAGE
iOTHERWISE PROCESS AND OUTPUT
iSTATUS

STOP

iSTOP WITHOUT CHAIN

LABEL,

SEND(STATUS,'ISMUTL.SAV' ,TERM) iTERM=TERMINAL YOU ARE ON

STOP 'I SMUTL'

;STOP THIS PROGRAM START
;UP ISMUTL

ISAM (ISMUTL)

10-39

The STATUS function will perform considerably faster if the remaInIng
number of record spaces in the append area is not requested. When
APDFLG in record STATUS contains zero, the remaining number of record
spaces will not be returned.

10.4.7.2

Auto-CREATE

The CREATE function requires considerable operator interaction to produce a file.
The auto-create capability eliminates most, or all, of
this interaction. There are many applications for this capability.
One use would be the situation where the parameters of a file are
known, and similar files are to be built.
It could also be used when
some predictable small changes are to be made to an ISAM file, and it
would be convenient to avoid numerous sessions with the dialog.
Another si tuation would be a .. turnkey" system, in which the operator
is not permitted to do a manual create. A final example of an application would be an auto-create to do a reorganization with different
parameters than originally specified;
because as a file matures the
distribution of records to be added often changes.
The auto-create is selected with an answer of YES to the first question in the CREATE dialog.
This is followed by a request for an
auto-filename.
The auto-filename is a data file constructed by the
user which contains a list of answ~rs for the expected ISAM CREATE
questions.
Upon specifying the auto-filename, the CREATE process continues to completion, or until an invalid answer is encountered.
In either SUD or TSD operation, access to the auto-filename or
response file can be done manually with the YES answer to the first
CREATE question. Access may also be made automatic
(programmed).
Programmed access to the auto-filename is a function of whether you
are operating under SUD or TSD.
Under SUD the program selection (R ISMUTL) and initial responses
(C,
YES~ auto-filename) are supplied from an indirect file.
The responses
to the CREATE dialog are then supplied by the auto-filename. Below is
an illustration of this indirect file:
!INDIRECT FILE ISMCRT
! RUN ISMUTL
R ISMUTL
!CREATE FUNCTION
C
!AUTO OPTION
Y
!AUTO FILENAME (CREATE QUESTION RESPONSES)
filnam

10-40

ISAM (ISMUTL)

TSD operation does not support indirect file operation, but a message
can be sent to ISMUTL to supply the initial responses in the same
manner as with REORG and STATUS when they are run in chain mode.
The
YES answer to the auto-create question is assumed by ISMUTL when this
mode is chosen.
The record sent must contain the specific field sizes
in the order shown below:
USER PROGRAM (USPROG)
RECORD CREATE
FNCT,
AI, 'C '
CHNFLG,
Dl
FILIN,
USRPG,

iDO A CREATE
iO=DO NOT CHAIN

TO USRPG (SET
iUSRPG TO SPACES)
il=CHAIN TO USRPG
iAUTO-FILENAME (RESPONSE FILE)
iCHAIN FILE

A17
A17

PROC

SEND (CREATE,'ISMUTL',TERM)
STOP 'ISMUTL'

iTERM=NUMBER OF TERMINAL
iYOU ARE CURRENTLY
iRUNNING ON /
iSTOP THIS PROGRAM START
iUP ISMUTL

Following is an example of an auto-file.
In the previous examples,
this
is filnam for SUD, or field FILIN in the message sent from the
TSD program. This auto-file creates the same ISAM file as shown in
the example in Section 10.4.3.4 •
• R DKED
*AFILE=
XDATAl.DDF
N

XDATAl.ISM
250
7

2
y

200
100
8
1
N

DK
DK
E

iAFILE is filnam or FILIN
iinput file
ido not delete input file
ioutput file
inumber of input records
inumber of records per group
;load exclusion
;fill out group
irecords in append area
;overflow groups
;key length
;key location
;no duplicate keys
;allocate index file to default dev
;allocate data file to default dev
;exit ISMUTL

(GOLD/COMMAND)
EXIT

ISAM (ISMUTL)

10-41

If ISMUTL is called from a detached job via chaining, the normal dialog which appears on the screen will be written to a file called
xxx. LOG where XXX is the name of the auto-file. This file will show
all display input and output, and will help reveal problems with execution of ISMUTL in detached mode.
If any answer to the response file is invalid, the CREATE will fail.
In the manual mode, an invalid answer will result in the question
being repeated;
in auto mode, the program terminates.
If the file is
being created in the detached mode (TSD) when an error occurs, the
progra~ chain will be broken.
A detailed study of the program queries
and appropriate responses must be made. There are many conditions
which will appear only at run time. Among the things that must be
considered are disk space and disk fragmentation.
Table 10-2 summarizes the methods you can use to create an ISAM file.
Table 10-2
ISMUTL CREATE Modes
System
Mode

SUD

TSD

Manual

R ISMUTL
C
N
Respond to the
CREATE dialog

SemiAutomated

R ISMUTL
C
y

auto-filname
Automated

@ISMCRT.COM
where ISMCRT.COM contains:
R ISMUTL
C
y

In the calling program:
RECORD CREATE
FNCT, AI, 'C'
CHNFLG, Dl
FILIN, A17,'auto-filname'
USRPG, A17

auto-filname
PROC
SEND (CREATE,'ISMUTL.TSD')
STOP 'ISMUTL'
10.5

ERROR MESSAGES

See Appendix B, Table B-9, for a list of error messages for ISMUTL.

10-42

ISAM (ISMUTL)

CHAPTER 11
SORT/MERGE

11.1

INTRODUCTION

At one time or another, you will probably be faced with a file whose
records are not in the order you need for a particular use.
Or you
may find that you have two or more files containing information in
identically structured records that you want to combine into one file
to form a common data base. A sort program facilitates the reordering
of a file,
and a merge program is used to combine files having the
same record structure.
CTS~300

includes tools that enable the user to develop a sort or merge
program. The techniques for doing this are described in this chapter.
The development of a sort or merge program starts with a ~ser-written
control file that describes the parameters of the operation. The
SORTG program, with the control file as input, generates the variable
data division of the desired sort or merge program. This file and
SORTM.DBL, which is the procedure division of the sort or merge program, are then compiled to produce an object file.
This object file
is linked like any other such file to produce the usable sort or merge
program.
When the program is run, the specified files are sorted or
merged, as requested.

11.1.1

Characteristics

Several features of CTS-300 Sort/Merge should be pointed out:
• Files may be sorted by multiple keys, and the sort
key may be in ascending or descending order.

for

each

• An optional key sort (TAGS sort) is available which allows a
sort of key fields only, without transporting entire records
across work files.
• Optional statements are provided to allow the user to define
such operating parameters as memory allocation, work files,
and so forth.
• The sort or merge program developed by the CTS-300 user has
the optional ability to receive a control record sent from
another program. This control record facilitates changes in
selected sort or merge parameters at r~n-time.
11-1

When you use a CTS-300 Sort/Merge program, you must be aware
limitations:

some

• The caret symbol (~), which is 136 octal,
is the internal
control character used in Sort for the end-of-string marker.
If used as the first character of a record, sort results will
be unpredictable.
• The Sort program is not able to sort a multivolume sequential
file, because Sort requires a CTRL/Z at the end of all input
files.
• The Sort/Merge program is not able to sort or merge records
with packed keys. Compressed records can be handled as long
as the record lengths and displaced keyes) are correctly described, and the sort keys remain unpacked.
• The output of a sort or merge is a sequential file.
Sorting
an ISAM file will not produce another ISAM file as output.
11.1.2

Chapter Organization

The remainder of this chapter is structured in the general sequence
required to develop a sort or merge program.
It is comprised of three
sections.
Section 11.2, the Control File, covers control file
characteristics and requirements.
The individual statements within
the control file are explained, and examples are given
where
necessary.
The statements are then summarized. This is followed by
Section 11.3, Sort/Merge Program Development and Use, which covers the
development procedure.
Development consists of using the routines
supplied by CTS-300, SORTG and SORTM, to integrate the control file
into the desired program.
The last steps of the procedure are
basically routine compilation and linking.
Examples are used to
illustrate both features and correct usage.
Last of all, the use of a
control record for chain mode operation is presented.
Section 11.4,
Error Messages, is a reference to the Sort/Merge error messages.
11.2

THE CONTROL FILE

The sort or merge that you want operates on information supplied by
you,
the user.
The control file describes the input file{s), output
file, sort key{s), record format and other necessary parameters and
options.
This control file is created by you with the aid of an editor.
The control file is composed of five required control statements and
six optional control statements.
A different control file must be
built for each sort or merge.
There are situations where another control
file may involve just a simple change of input file name, or it
may require a change of most or of all the parameters.
Whenever any
statement is changed, the control file must go through the procedure
of being processed by SORTG, compiled along with SORTM, and linked to
produce the usable program.
11-2

SORT/MERGE

The characteristics and use of all eleven statements are discussed on
an individual basis in the following subsections. Control statement
options are shown in brackets.
Comment lines are allowed on any
statement line if preceded by a semicolon. Examples are given for
each statement requiring clarification.
Your first Sort/Merge exercise will be easier if you avoid the optional statements. The five required statements are summarized below:
INPUT

This statement is used to specify the input file(s) for
the sort or merge.

OUTPUT

This statement is used to specify the name of the sorted or merged file that results from running the sort or
merge program.

RECORD

The program must know the record structure of the input
file(s)
it IS dealing with and the location of the
keyes) within the record.
This statement specifies
these parameters.

KEYS

This statement defines the order in which the file
to be sorted, in relation to the chosen key(s).

END

This statement identifies the end of the control file.

The required statements are presented in the above order in the following sections.
Optional statements are grouped together and are
listed in alphabetical order between the KEYS and the END statements.
There is no required order for the statements; the order shown here
is just a logical arrangement.

11.2.1

INPUT

The INPUT statement is normally the first statement in a control file.
The file to be sorted or the files to be merged are specified here.
The specification of a single file indicates that a sort is desired.
The specification of two or more files indicates that a merge is to be
performed.
The format is:
IN [P UT] : f i I s p e c I [ , f i I sp e c 2 ••• , f i 1 s pe c'7] [ (co un t) ]
where:
filspecl

is the first input file specification. If this is the
only file specified, the operation is a sort of this
file.

SORT/MERGE

11-3

filspec2 through filspec7
is one or more additional file specification(s) up to a
If included in the statement,
maximum of seven files.
the operation is a merge of the files specified here.
Files specified in addition to the first file are separated by commas.

NOTE
Files to be merged
merging.
(count)

must

sorted

prior

is optional when used with sequential files.
It
specifies the number of records, starting with the
first record, to be sorted or merged.
If multiple
files are specified, the count argument must either be
specified for all of the files or for none of the
files.
The number must be enclosed by parenthesis.

NOTE
The count argument must be used for an ISAM
input file(s)
and must, in this case, contain
only the letters ISM •
• Mixed file types can not be used as input to a merge
operation.
That is,
ISAM and sequential files can
not both be specified in the same merge operation •
• The count argument can be overridden at run time by a
program that chains to your Sort/Merge program. See
Section 11.3.6.
Example:
INPUT:RKO:PAY.DDF(2400)
Sorts the first 2400 records of file RKO:PAY.DDF.
INPUT:LABR.DDF
Sorts file LABR.DDF on the default device.

The entire file is sorted.

INPUT:RK1:LABM.DDF(3000),RKI:LABT.DDF(4000)
Merges the first 3000 records of file RKI:LABM.DDF and the first
records of file RK1:LABT.DDF.
INPUT:RKO:PAY.ISM(ISM)
Sorts the ISAM file on RKO called PAY. ISM.

11-4

SORT/MERGE

4000

11.2.2

OUTPUT

The output statement specifies the name you wish to give the file that
is the output of the sort or merge operation.
The form is:
OU[TPUT]:filspec
where:
fi1spec

is the desired name of the output file •
• The output filename can not be the same as the input
filename for
ISAM files if a merge is performed, or
if a TAGS:SORT,
TAGS:LIST, or TAGS:INDEX sort is
being done
(see Section 11.2.9). An error message
will result if any of these is attempted.
In the
case of the TAGS:SORT, the error message will appear
only if there is not sufficient free space for a temporary copy of the input file •
•

If a sequential file is being sorted, and if the output file name is the same as the input file, the
input file is overwritten.

Example:
OUTPUT:RK1:WEEKLY.DDF
The sorted or merged output is written as a file named
device RKl.

11.2.3

WEEKL¥.DDF

RECORD

The record statement defines the format of the records in the input
fi1e(s) •
The format for each file is identical to the DIBOL record
format, except that no initial value may be specified.
The format is:
RE[CORD]:
field def 1

field def n

SORT/MERGE

11-5

where:
field def 1 to field def n
are field definitions for each key field to be used
in
the subsequent sort or mergei
for fields to be used as
filler to position the key fields within the recordi
and for fields to fill out the record to the total
length of the input record •
• Each field def is on a separate line •
•

Each field def is formed in accordance with the rules
for a DIBOL data division statement.

Example:
RECORD:
FILLA,
NAME,
FILLB,
BADGE,

AS
A20
A3S
AS

ifill characters
ifill characters

This record statement defines a record of 65 characters.
Positions
6-25 contain a key field named NAME, and positions 61-65 contain a key
field named BADGE. The other positions in the record may contain any
number of other fields, but they are of no interest to the Sort/Merge
program.

11.2.4

KEYS

The keys statement specifies which fields within the input file
These
records are to be used to control the order of the output file.
fields are known as control keys.
The format is:
KE[YS]:fldnaml[-] [,fldnam2[-] ••• ,fldnam8[-]]
where:
fldnaml through fldnam8
indicates the field(s)
to be
field(s) (or control key(s» •
•

used

the

control

Each fldnam must be a name of a field defined in
RECORD statement •

the

• The first fldnam specified becomes the major control
keYi
the last fldnam specified becomes the minor
control keYi
and the fldnams between become intermediate control keys in the order specified.

11-6

SORT/MERGE

is an optional argument associated with a given fldnam
that, if included, causes records to be ordered in descending sequence by that fldnam. If not included, the
records are ordered in ascending sequence.
No more than eight control keys may be specified.
Example:
KEYS: NAME, DATESpecifies a sort or merge using the field called NAME as the major
control field, ordered in ascending order, and the field called DATE
as the minor control field, ordered in descending order.
Names appearing first in the alphabet would appear first in the file, and for
each name category, the records would be arranged with the most recent
date appearing first.
Note that a blank is treated differently depending on whether it appears in an alpha or a decimal field.
An
alpha space is on octal 40 and a numeric zero is an octal 60.

11.2.5

DETACH (Optional)

The DETACH statement is an optional statement that causes the sort or
merge program to detach from its associated terminal. This allows you
to execute another job while a sort or merge is running.
The format is:
DE[TACH]:
There are no arguments.
The characteristics of this statement are:
• DETACH is ignored under SUD operation.
• Any detached program that produces terminal output will
until it is attached.
• If error messages are generated, they will not
until the program is attached.

hang

displayed

• DETACH occurs only once. If you reattach, your terminal is
dedicated to the attached program until it terminates. See
Chapter 5 of this manual for information on the ATTACH and
DETACH commands.

SORT/MERGE

11-7

11.2.6

EXECUTE (Optional)

EXECUTE is an optional statement that specifies the name of a program
to be executed (chained to) after the Sort/Merge program terminates.
The format is:
EX[ECUTE]:fi1spec
where:
fi1spec

specifies the name of the program to be executed.
•

If EXECUTE is omitted, control returns to the
monitor.

• EXECUTE may be overridden.

system

See Section 11.3.6.

Example:
EXECUTE:MYFIL.SAV
Indicates that program MYFIL.SAV on the default device is to
cuted upon completion of the Sort/Merge operation.
11.2.7

exe-

SPACE (Optional)

The SPACE statement is an optional statement that controls the
of additional memory available for a Sort/Merge operation.

amount

The format is:
SP[ACE]:kbytes
where:
kbytes

is a decimal number used to specify, in thousand byte
segments, the total amount of main memory to be available to a Sort/Merge program. This includes the DIBOL
program and all buffers, but does not include the DIBOL
interpreter, monitor, or any other requirement.
• The default memory size if the SPACE statement is not
used is 16 K bytes.
•

11-8

SORT/MERGE

If the default of 16 K bytes is used, and the record
is too large to allow a minimum of three records to
be held in the work buffers, SORTG suggests, via a
message, the amount of space required to support the
number of work files requested. You then have the
option of reducing the number of work files or of increasing the space.

• The Sort/Merge program is-designed to work within artificial limits imposed by TSD.
If the sort requirements exceed the memory space available, a message
(as above)
will appear, suggesting new values for
space and work file allocation.
• For faster operation, add 1 K byte of memory for
every work file assigned in addition to the default
of three work files.
• Files with very large records may require more than
the
default
of three work files
(see Section
11.2.10). Specify 1 K byte of additional memory for
each added file.
• Within TSD operation, the SPACE option should be used
with consideration for the memory requirements of
other users.
Example:
SPACE:18
Indicates that a Sort/Merge program may use up to 18 K bytes of
ry.

11.2.8

memo-

SU (Optional)

SU is an optional statement that specifies that the Sort/Merge program
is going to be run as a Single User DISOL program. SUD operation is
faster than TSD operation, for several reasons, and should be used for
large files.
The format is:
SU:
There are no arguments.
The characteristics of SU are:
• Compared to TSD, SU operation is faster, because more memory
can be used. There is no contention for memory or disk resources.
•

I/O buffer allocation is automatically doubled
option.

with

the

• The SU option forces six work files.
More may be specified
with the WORK statement, but it is not advised for sorts that
utilize random access I/O (TAGS:SORT).

SORT/MERGE

11-9

• The SU option overrides the SPACE statement and automatically
optimizes the internal working areas •
If you use the SU option with the XM monitor, you may receive
a message indicating there is not enough memory.
If this
happens, use the'SJ monitor.

•

11.2.9

TAGS (Optional)

The TAGS statement is an optional statement that allows a sort to be
performed using only the keys instead of the entire record. A key
sort offers substantial advantages in execution speed and minimized
disk requirements, since the entire file need not be manipulated.
The
TAGS option should be used for most sorts.
The format is:
TA[GS]:type
where:
type

is either SORT, LIST, or INDEX.

TAGS:SORT specifies a sort that produces a sorted version of the
input file.
The key or keys are first sorted, and then
a pass is made to write each complete record in the new
output file.
• TAGS:SORT must not be used on an ISAM file.
• A TAGS:SORT requires much smaller work files
normal sort.

than

• A TAGS:SORT can provide a significant performance advantage over a normal sort when working with a record
of approximately 80 characters and a short key. With
larger records, the advantage is greater.
• The final pass to write the output file consumes much
of the time required for a TAGS:SORT.
This pass is
eliminated with either
the
TAGS: LIST
or
the
TAGS: INDEX sort below.
TAGS:LIST specifies a sort that produces an output file which
consists of a seven-byte record number.
This file
can then be used to access the original file.
The
TAGS:LIST is basically like the TAGS:SORT but without
the pass required for the post-sort write.

11-10

SORT/MERGE

• Each of the records in the output file contains a
record number identifying the record in the original
file that corresponds to the relative position of
this number in the output file.
That is, the third
record in the output file contains the record number
for the record in the original file that has become
third in the desired sort sequence.
• Leading zeros in
spaces.

the

output

• The output f il e name -should
input file name.

file

:be

are

encoded

different

from

the

TAGS:INDEX specifies an output file consisting of the key
field(s)
specified in the KEYS statement and a corresponding seven-byte relative record number,
as in
the TAGS:LIST statement. The record format consists
of the major key, the intermediate key(s), the minor
key, and the relative record number.
•

If your original file is an ISAM file,
use the
TAGS:INDEX option and add the ISAM key as a minor
sort key.
It has little effect on sort speed, and
you can then access the original ISAM data file by
means of the sorted TAGS:INDEX output file.
That is,
you can select a record on the basis of any chosen
key in the TAGS:INDEX output file,
and then access
the record in the ISAM file using the corresponding
ISAM key.

• The output file name should
input file name.
11.2.10

different

from

the

WORK (Optional)

The WORK statement is an optional statement that specifies both the
number of work files to be used for a sort and the devices on which
the work files are to reside.
The format is:
WO [RK]: [number] [,devl: ••• ,devn:]
where:
number

is a decimal number between three and nine,
inclusively, that specifies the number of work files to be allocated.
If the number (or the WORK statement itself) is
omitted, the default is three work files on the default
device.

SORT/MERGE

11-11

devl:

through devn:
specifies a list of one or more devices to which the
work files are allocated.
Dev: must be a valid device
name and must include the colon.
If dev:
is omitted,
all work files are allocated to device OK:.
• The first work file is assigned to the first device
in the list.
The second work file is assigned to the
second device, and so forth.
The same device may be
specified more than once.
•

If the number of devices specified is less than the
number of work files, devices are allocated to files
by starting over with the first device specified.
File assignments cycle through the device list, until
all the files have been assigned to devices.

•

If the number of devices assigned exceeds the number
of work files, the excess devices are ignored.

•

If a merge is specified, the WORK
nored.

statement

ig-

• With a file of approximately 5000 to 10,000 records,
four to six work files, rather than the default of
three, will result in a measurable performance improvement.
Example:
WORK:4
Allocates four work files, all on device OK:.
WORK:3,RK2:
Allocates three work files, all on device RK2.
WORK:3,RKl:,RK2:,RK3:,RK4:
Allocates three work files, one each on devices RKl,
RK2,
RK4 is ignored, since only three work files are specified.

and

RK3.

WORK:3,RKI:,RK2:
Allocates three work files, the first on device
device RK2, and the third on device RKI.

11-12

SORT/MERGE

RKl,

the

second

11.2.11

END

The END statement indicates the end of the control file.
is:

The

format

EN [D] :
there are no arguments. The only restriction on the statement is that
it must be the last one in the control file.

11.2.12

Summary of Control File Statements

Below are the control file statements in the order presented previously, with optional statements indicated.
Statement

Optional

Comments

IN[PUT]:filspecl[ ••• ,filspec7]
[ (co unt) ]

First statement

OU[TPUT]:filspec

Name of the file resulting
from the sort or merge
operation

RE[CORD]:
field def

Fields must be in specified
order

KE[YS]:fldnaml[-]
[ ••• ,fldnam8 [-]]

Maximum of 8

WO[RK]: [number]
[,devl: ••• ,devn:]

Yes

Ignored for merge

TA[GS]:SORT
:LIST
: INDEX

Yes

Fast sort

S P [ACE] : kbytes

Yes

SU:

Yes

su overrides SPACE
allocation

DE [TACH] :

Yes

Ignored with SU option

EX[ECUTE]:filspec

Yes

EN [D] :

Last statement in control
file

SORT/MERGE

11-13

11.3

SORT/MERGE PROGRAM DEVELOPMENT AND USE

Now that you have developed a control file, it must be processed by
SORTG.
The output of SORTG is compiled together with SORTM, and the
result linked to produce your Sort/Merge program. The program is then
run to perform the sort or merge.
The details of these steps are contained in the following sections.

11.3.1

SORTG

SORTG is
division
It is an
file and

a CTS-300 supplied file (SORTG.SAV) that generates the data
of your Sort/Merge program, using your control file as input.
executable program that asks you for the name of its input
of its output file.
The dialog sequence follows:

.R SORTG
SORT GENERATOR VAnn-nn
INFILE=
Respond with the name given to your control file when you
with the editor. The response will be:

created

OUTFILE=
Respond with the desired file specification of your Sort/Merge program
(SMPROG.DBL for the sake of the following discussion).
After 'you provide the output file name, SORTG generates the output
file unless an error is detected.
Errors for SORTG are listed in Appendix B, Table B-lO.
If an error is detected, a message will be displayed
indicating that output has been suspended.
This message will
be followed by the error message.
The error message is usually preceded by the line number of the control statement in error.

11.3.2

Compiling with SORTM

SORTM.DBL is another CTS-300 supplied file and is the procedure
division of your Sort/Merge program. SORTM and the output resulting
from running SORTG (SMPROG.DBL) must both be compiled to produce an
OBJ file.
That is:
.DIBOL SMPROG+SORTM
whose output is SMPROG.OBJ.

11-14

SORT/MERGE

11.3.3

Linking

The .OBJ file produced by the compiler must be linked to run in either
SUD or TSD mode.
for SUD:
.LINK SMPROG.OBJ,DIBOL
whose output is:

SMPROG.SAV ,or

for TSD
.LINK/EXE:SMPROG.TSD SMPROG.OBJ,TDIBOL/BOT:lOOOOO
whose output is:

SMPROG.TSD

You will probably want to run REDUCE on this TSD file.

11.3.4

Running the Sort or Merge Program

The Sort/Merge program is run like any other program:
.R SMPROG or .RU dev:SMPROG
The input file{s) specified in the control file is sorted (or merged)
to produce a file with the specified output name.
Errors generated
during execution are those listed for SORTM in Appendix B, Table B-ll.
11.3.5

Example

The following is an example illustrating all
generate and run a sort program.

the

steps

required

There are five steps:
1.

Create the control file:
• R DKED
*FILE.CTL=
IN: DATAl. DDF
OU: SDATAl. DDF
RE:
,
A5
NAME,A20
,
A35
BADGE, A5
SU:
EN:
<GOLD/COMMAND>
EXIT

ithe unsorted input data file
ithe desired sorted file
irecord definition follows
ispace filler
ia field to be used as a sort key
ispace filler
ia field to be used as a sort key
ithe sort program will be
irun in a single-user environment
iend of control file

SORT/MERGE

11-15

Run SORTG
.R SORTG
SORT GENERATOR VAn-nn
INFILE=FILE.CTL
OUTFILE=SORT.DBL

Compile:
.DIBOL SORT.DBL+SORTM

whose output is: SORT.OBJ
4.

Link:
.LINK SORT.OBJ,DIBOL

whose output is: SORT.SAV
5.

Run the sort program:
.R SORT.SAV

when you run SORT.SAV file DATAl.DDF will be
sorted as specified into a new file SDATAl.DDF.

11.3.6

SORT/MERGE in Chain Mode

Certain parameters in the Sort/Merge Control File can
run time. The parameters that can be changed are:

changed

• The record count in the control file INPUT statement.
• The name of the program to be executed after the sort or
merge is completed (originally specified in the control file
EXECUTE statement).
• The EXECUTE statement, as originally specified, may be selected as the only statement to be executed. That is, no
sort or merge is to be performed.
• A message can be sent by a preceding program to the program
specified in the EXECUTE statement of the Sort/Merge Control
File.
The size of the message is 100 characters but it can
be changed by editing SORTM.DBL.

11-16

SORT/MERGE

The operations listed previously are accomplished via a Sort/Merge
Control Record that is sent to the sort or merge program prior to execution. The required format of this control record is:
RECORD SCR
OPCODE, A1,'x'
;value determines the interpretation of
;the control record (see below)
COUNT,
D6
;record count (overrides count in INPUT
;statement)
NEXT,
A14
;filspec of program to follow sort
MSG,
A1DD
;message to be passed to the program to
;which sort or merge is chained
The value of the opcode character determines how the control record is
interpreted.
This character may have one of three values.
They are:
%, @, or a character other than % or @ (including a space).
If the opcode value is a %:
•

If COUNT (in the control record) is nonzero, its value is inserted as the control file INPUT statement record count. Any
previous value is overwritten.

•

If NEXT is nonblank, its contents replace the program specified in the control file EXECUTE statement. NEXT, therefore,
forces sort or merge to chain to a program specified at run
time.
If the opcode value is a @:

• No sort or merge takes place.
Instead the program specified
by the control file EXECUTE statement is executed.
This feature allows SUD-chained programs to dynamically bypass a sort
without breaking the run chain.
If the opcode value is anything other than a % or a @:
• The message in field MSG of the control record is sent to the
program specified by the EXECUTE statement in the control
file.
Thus a control record may consist of
fields and functions:

the

following

combinations

OPCODE{%)

sets COUNT and/or NEXT

OPCODE{@}

indicates no sort or merge; simply chain directly
program specified by the EXECUTE statement

OPCODE (other than % or @)
indicates a message is to be sent to the program specified by the EXECUTE statement.

SORT/MERGE

11-17

As an example of how this feature is used, consider a program {PROGl}
running prior to a sort or merge. Within P~OGI a Sort/Merge Control
Record is sent (wi th the OrBOL SEND statement) to--,the Sort/Merge program {SMPROG}. PROGI then chains to SMPROG by hav{ng SMPR6G specified
as the chain program name in the DrSOL STOP statement at the end of
PROGI.
SMPROG then runs with modifications determined by the control
record contents.
Upon completion of the sort or merge, the chain program {if so specified by the EXECUTE statement in the sort control
file} is executed or control returns to the monitor.

11.4

ERROR MESSAGES

See Appendix B, Tables B-I0 and B-ll, for a list of error messages for
SORTG and SORTM.

11-18

SORT/MERGE

CHAPTER 12
STATUS

12.1 INTRODUCTION
STATUS is a TSD utility
Run-Time System.

used

obtain

information

your

TSD

The information obtained using STATUS is determined by the option
choose.
The specific kinds of information available are:

you

12.1.1 Features

•

List of STATUS options

• Available free memory and its relative location
• Total active jobs
•

Information on a specified active job

• Total line printer active jobs
• Active job information for a specific line printer
• Pending messages
• Characteristics of the current version of a time-shared RTS.
Additionally, two options that are useful after information
retrieved are:

has

been

• Termination of an active job
• Exit from STATUS
Some of the other characteristics of STATUS are:
• STATUS runs only on a time-shared
terminal.

system

with

attached

• STATUS requires 6 K bytes of memory.
• STATUS outputs to either a terminal or a line printer.
12-1

12.1.2 Chapter Organization
Section
The remainder of this chapter is comprised of two sections.
12.2, Options, details the individual options available. Section
12.3, Using STATUS, explains how to use the STATUS utility to gather
information on your time-shared system.

12.2 OPTIONS
STATUS functions as a result of the options you select. These options
are explained after a short discussion of the conventions used in
STATUS.

12.2.1 STATUS Conventions
A list of options is initially displayed every time STATUS is run, and
a brief option list is displayed each t~me STATUS prompts for input.
Only one option can be selected at a time. STATUS recognizes a maximum of three characters to designate an option; however, most options
require only one character.
The individual options are all shown with the STATUS prompt line
lowed by a typical output.

fol-

12.2.2 Option F
Option F retrieves the amount of free memory and identifies its
tion.

loca-

Typical Option F response:
ENTER OPTION (F,H,J,K,L,M,T OR X): F
FREE MEMORY
HIGH MEMORY:
o BYTES
LOW MEMORY:
16824 BYTES
STATUS. TSD:
6304 BYTES IN LOW MEMORY

DD-MMM-YY HH:MM:SS

The numbers shown indicate the amount of memory available in extended
memory
(HIGH)
and in lower memory (LOW). The dividing line between
LOW and HIGH memory is at 56 KB.
The high memory value will always be
zero unless you have an XMTSD system. The size and location of STATUS
indicate additional memory that will be available when STATUS is terminated.

12-2

STATUS

12.2.3 Option H
Option H presents a list of the STATUS options.
The response is:
ENTER OPTION (F,H,J,K,L,M,T OR X): H
OPTIONS
(F)
FREE MEMORY
(H)
HELP
(J)
ACTIVE JOB LIST
(JX)
ACTIVE JOB NO. DESCRIPTION
(KX)
KILL AN ACTIVE JOB
(L)
LPQFIL JOBS PENDING - ALL LP'S
(LX)
LPQFIL JOBS PENDING - BY PRINTER (L1,L2,L3,L4)
(M)
MESSAGES PENDING
(T)
TSD PARAMETERS
(X)
EXIT

12.2.4 Option J
Option J retrieves the complete list of active jobs on the system.
Typical Option J response:
ENTER OPTION (F,H,J,K,L,M,T OR X): J
JOB NO. JOBNAME
TERM. NO.
SIZE
o
DK :STATUS.TSD
0
6232
1
KBDLDR
1
688
3
DK :COUNT2.TSD
DET
920
(MESSAGE AREA>
2048

MEM.LOC. DD-MMM-YY HH:MM:SS
LOW
LOW
LOW
LOW

JOB NO.
is a numeral assigned by STATUS to identify a job.
JOBNAME
is displayed in usual fi1spec format (dev:fi1nam.ext). The remaining
entries are self-explanatory, with the following exceptions:
If there
is no job running at a terminal, and if the terminal is able to receive a job request, that terminal will show a pseudo job indicated by
the name KBDLDR.
The last line in the example shows the message
buffer allocation for XMTSD systems only.
If there are no messages
pending, the message area report does not appear.
In this case, it
shows there is 2 K bytes of buffer space used for this purpose.

STATUS

12-3.

12.2.5 Option Jx
Option Jx retrieves information on a specific job.
The STATUS job
number is specified by a numeric value for x where x may be up to two
characters.
Use the J option to determine the STATUS job number.
Typical Option Jx response:
ENTER OPTION (F,H,J,K,L,M,T OR X): J3
JOB NO.
3
DD-MMM-YY HH:MM:SS
JOBNAME DK :COUNT2.TSD TERM. NO.
DET SIZE
920 LOW MEMORY
CHANNEL DEV:FILNAM.EXT FLSIZE
MODE
TOT. USERS
UPD.USERS
I
DK :NUMBER.DDF
3049
o
1
255
This message repeats the job number (3, selected with J3) on the first
line.
The second line specifies the job filspec, the terminal number
(indicated by DET because job 3 is detached), and the size of the job
in bytes.
The fourth line shows the channels open for the job; the
device and files being accessed;
the file size; the mode of access;
the total users of that file;
and the number of update users of that
file.
If the job number specified is valid, but no files are open, a
message appears indicating that no files are open.
If an invalid job
number is specified, a message will appear indicating that no job by
that number exists.

12.2.6 Option Kx
The option Kx kills the job indicated by the specified numeric value
of x where x may be up to two characters. This option permits you to
terminate any job, regardless of whether or not the job is attached or
detatched, or on a master or a slave terminal.
Use the J option to
determine the number of the job you wish to terminate and again to
verify that the termination took place.
When the job specified is running attached, the TSD version number
displayed on the attached terminal once the job is terminated.
When the job specified is running detached, there is no message.
NOTE
The Kx option operates like a double
CTRL/C. Files opened in output mode are
lost when Kx is entered;
and files that
were opened in update mode may not reflect the latest record updates,
if Kx
is entered.

12-4

STATUS

12.2.7 Option L
Option L retrieves the contents of the print queue
with the print spooler utility, LPTSPL.TSD.

that

was

created

Typical Option L response:
ENTER OPTION (F,H,J,K,L,M,T OR X): L
NAME NO. DEV:FILENAM.EXT COPIES ALIGN
LP
1 RK1:MIPROG
1
Y
LP
1 RK1:URPROG
2
Y
LR
3 RKl:BIGPRG
4
LS
4 RK1:SMLPRG
1

DELETE DD-MMM-YY HH:MM:SS
N
N

Each print request is identified by a two-character line printer name,
followed by the line printer number; the file to be printed; and the
number of copies. The response to the ALIGN and DELETE arguments is
as specified in the original DIBOL LPQUE statement. If the queue is
empty, a message is displayed indicating this condition.

12.2.8 Option Lx
Option Lx retrieves the contents of the print queue for a specific
printer.
When entered, x is a decimal number in the range 1 to 4
which indicates the desired printer~
Typical Option Lx response:
ENTER OPTION (F,H,J,K,L,M,T OR X): Ll
NAME NO.
DEV:FILNAM.EXT COPIES ALIGN
LP
1
DK1:MIPROG
1
Y
LP
1
DK1:URPROG
2
Y

DELETE DD-MMM-YY HH:MM:SS
N
N

Each file in the queue for the selected printer is on a separate line.
The information is arranged in this order: printer name and number;
file specification; and, as with Option L, the number of copies. The
response to the ALIGN and DELETE arguments is, again, as specified in
the original DIBOL LPQUE statement.
If there are no print jobs pending for this printer, a message is displayed indicating that there are none.
12.2.9 Option M
Option M retrieves the contents of the message queue.
Typical Option M response:
ENTER OPTION (F,H,J,K,L,M,T OR X): M
MESSAGE FOR PROGRAM
TERM. NO. SIZE
DK1:MIPROG
1
704

DD-MMM-YY HH:MM:SS

STATUS

12-5

Each pending message is on a separate line.
Information is provided
on the device; program name; size (in bytes); and the number of the
terminal for which the message is queued.
If there are no messages pending, a message
there are none.

displayed

indicating

12.2.10 Option T
Option T retrieves the operating parameters of the current version
the TSD or XMTSD RTS.

Typical Option T response:
ENTER OPTION (F,H,J,K,L,M,T OR X): T
TSD PARAMETERS
DD-MMM-YY HH:MM:SS
MAX. NO. OF JOBS:
NO. OF TERMINALS:
4
2
MAX. NO. OF CHANNELS:
12
MAX. NO. OF MESSAGES
8
MAX. NO. OF DEVICES:
SLICE:
64
6
SWAP USR:
YES
ISAM:
YES
DDT:
YES
MONITOR (SJ/FB/XM)
FB
FORCED JOB STARTUP:
YES
The
or
and
and

values displayed are the limits for the current version of the TSD
XMTSD system. Most of these reflect decisions made during CTSGEN
can be changed only with another CTSGEN, the exceptions are SLICE
swap/noswap USR.

12.2.11 Option X
This is the exit option.
It allows control to return to the run-time
system.
When option X is selected, the TSD or XMTSD RTS regains control of the terminal and displays the current TSD version number and
the asterisk prompt. Any program linked for TSD operation can then be
run.

12.3 USING STATUS
The STATUS program is run by entering the following
TSD asterisk prompt:
*R STATUS or *RU dev:STATUS
the response is:
OUTPUT TO LINE PRINTER?

12-6

STATUS

ENTER YIN:

response

the

Respond with Y or N. An N response indicates that you want the output
device to be the terminal. A Y response indicates that you want the
output device to be a line printer.
Line printer selection produces a
further question:
ENTER PRINTER NUMBER.

(1-4):

Enter the number for the desired printer on your system. The printer
must have been specified during the RT-ll SYSGEN.
If the printer were
not specified in SYSGEN, or if the printer is busy, an appropriate
message is displayed.
If an invalid printer number (not 1-4) is entered, the system prompts for the number again.
After selection of output device, a list of options
printed, as with Option H.

displayed

12.4 ERROR MESSAGES
Error messages for STATUS are contained in Appendix B, Table B-12.

STATUS

12-7

CHAPTER 13
REDUCE

13.1

INTRODUCTION

REDUCE is a time-shared utility program that decreases the size of a
file linked at a base address of 100000 (octal) (16 K bytes). A file
so linked includes 63 unused blocks.
In a small system, especially
those using floppies, this wasted space can become excessive.
Eighty
TSD files, linked as described, contain more than enough wasted space
to fill an entire RK05.
REDUCE accepts an input file, reads it; then
copies the file, minus the 63 unused blocks.
It then deletes the
input file.
For overlaid files,
the relative block number in the
overlay handler tables is also modified.
13.1.1

Characteristics
• Requires 4 K bytes of memory.
• Recognizes file-structured devices only.
• Supported by RT-ll V3 (or later) only.

13.1.2

Chapter Organization

The remainder of this chapter is comprised of two sections.
The
first,
Section 13.2, REDUCE Options, is a discussion of the options
available with REDUCE.
The second, Section 13.3, Using REDUCE, describes the use of REDUCE.

13.2

REDUCE OPTIONS

There are three modes in which REDUCE can operate: query,
no query,
and version number.
These modes are a result of options selected when
you specify the file(s) to be reduced.
There are two options.
Modes
and options are discussed next. Because REDUCE is such a straightforward program, selection and format for mode and option are shown in
Sections 13.3.2 and 13.3.3 rather than in this section.
13-1

13.2.1

Query Mode

This is the default mode; no option is specified.
Each file that satisfies the stated file specification{s) is listed for you to decide
whether to reduce it. You respond with Y if you wish the file reduced, or with N (or carriage return), if you do not wish the file reduced.
If you attempt to reduce a file that was previously reduced,
or a file that was not linked for a base of 100000, a message will be
displayed indicating that REDUCE has ignored that file.

13.2.2

IN Option (No Query)

The IN option suppresses the individual file queries present in the
query mode.
Processing proceeds on all the files that meet the file
specification{s). This option provides fast processing of your files.
Messages are displayed, as in the query mode, indicating a previously
reduced file or a file not linked for a base of 100000.

13.2.3

IV Option (Version Number)

The IV option causes the REDUCE utility to display its current version
number.

13.3

13.3.1

USING REDUCE

Conventions

Input files
• REDUCE operates only on files that have been linked for a
base address of 100000
(octal). Upon receipt of an input
file specification, REDUCE searches the header block for the
correct link address, and makes sure the file has not already
been reduced.
• REDUCE will select only files with an extension of .TSD.
• More than one input file can be specified.
Output files
The output file resulting from reduction has
input file{s).

13-2

REDUCE

the

same

name

the

13.3.2

Running REDUCE

To start REDUCE, enter the following command:
.R REDUCE or .RU dev:REDUCE
or, for TSD
*R REDUCE or

*RU dev:REDUCE

REDUCE responds with an asterisk prompt for the input file(s).
The general form of file specification and option selection is:
filespecln
where:
filespec is the file specification of the file(s)
•

to' be reduced •

If more than one file is to be reduced,
specifications are separated by commas •

the

file

• REDUCE assumes a default extension of .TSD.
In

13.3.3

is the option specifier with n being either an N for no
query or a V for version number.

REDUCE Examples

The modes and options available with REDUCE
following subsections.

the

To reduce the two files MYFIL and YURFIL, enter the following in
ponse to the asterisk prompt:

res-

13.3.3.1

are

illustrated

Query Mode

*MYFIL,YURFIL

REDUCE

13-3

The result will be
DK:MYFIL.TSD?
The file is on the default device and exists with
Respond with Y or N.
The next line will be:

.TSD

extension.

DK:YURFIL.TSD?
The same conditions and possible response exist as did for
file.

the

first

To reduce the two files used in the query mode example without
the response to the asterisk prompt is:

query,

13.3.3.2

No Query Mode

*MYFIL,YURFIL/N
to which the only response would be the
files have been reduced.

13.3.3.3

prompt

indicating

the

*/V
The display would then be
REDUCE UTILITY VAnn-nn
where:
nn-nn

is the current version number.

ERROR MESSAGES

See Appendix B, Table B-13, for REDUCE error messages.

13-4

the

response

Version Number Mode

To obtain the version number of the REDUCE utility,
the asterisk prompt is:

13.4

that

REDUCE

APPENDIX A
CTS-300 RUN-TIME ERROR MESSAGES

The following is a list of the CTS-300 Run-Time Error Messages and
their meanings. They are listed in order by error number. Table B-3
in Appendix B of this manual contains a few special errors generated
by the DIBOL Time-Shared RTS only. Additional errors are also listed
in Appendix B of this manual for the CTS-300 Utility Programs and in
the RT-ll System Message Manual for the RT-Il Operating System.
There are certain errors listed which suggest you notify your Digital
representative.
These errors indicate there is a serious logic error
in the system software rather than the application software.
You
should inform DIGITAL in writing notifying us of the problem and include information on how to reproduce the problem.
Messages are identified by type:
nontrappable errors.

T for trappable errors

and

for

A-I

CTS-300 Run-Time Error Messages
Number/Message

Type

1 END OF FILE

Meaning
Logical end-of-file (CTRL/Z) detected:
•

When reading an input file (except
via ACCEPT field).

•

When operator typed CTRL/Z in response to the message requesting
you to mount a successor device
for input.

•

When requesting an ISAM record
whose key value exceeds the greatest key already in the file.

2 RETURN WITHOUT CALL

Program executed a RETURN statement but
no CALL or XCALL statement was in effect.

3 COMPILATION ERROR

Attempt to execute a statement line that
contains an error previously detected by
the compiler.

4 DIBOL STACK OVERFLOW

Too many nested subroutine calls and/or
subroutine calls with many arguments.
Subexpression nesting too deep.

5 RECURSIVE EXTERNAL CALL NT

An external subroutine attempted to call
itself (XCALL statement) either directly
or indirectly through another external
subroutine.

6 INCORRECT NUMBER OF
ARGS

The number of arguments passed to an
external subroutine by an XCALL statement is not equal to the number of arguments specified under the subroutine's
SUBROUTINE statement.

7 SUBSCRIPT ERROR

The subscript value of a singly subscripted variable specified a data element outside the program's data area, or
was zero or negative.
of
a
doubly
The first
subscript
subscripted variable specified a value
greater than
that
of
the
second
subscript;
one of the subscripts was a
negative value;
or
the
subscript
specified a data element outside the
program's data area.

A-2

eTS-300 RUN-TIME ERROR MESSAGES

CTS-300 Run-Time Error Messages

Number/Message

Type

Meaning

8 WRITING INTO A LITERAL

Attempt by an external subroutine to
store data in a literal passed as an argument to the subroutine call.

9 NOT ENOUGH MEMORY

Insufficient memory for
the
device
buffer and/or the device handler being
loaded:
•

In response to an OPEN statement.

•

In response to a call to the DELET
external subroutine.

Insufficient memory for the
being sent (SEND statement).

message

10 ILLEGAL CHANNEL NUMBER NT

The channel number specified in an OPEN,
ACCEPT, DISPLAY, FORMS, WRITE, WRITES,
READ, or READS statement is out of the
range for legal channel numbers (I-IS).

11 CHANNEL NOT OPEN

Attempt to perform I/O to a channel
prior to issuing an OPEN statement.

12 INPUT FROM WRITE-ONLY

Attempt to issue an OPEN statement in
input (I) mode to an output-only device
(for example, a line printer).

The operating system detected a logic
error in the run-time system software.
Notify your DIGITAL representative.

14 UNDEFINED OPCODE

The
run-time
system
detected
a
compiler-generated error in your program. Notify your DIGITAL representative.

15 NUMBER TOO LONG

The program performed a calculation producing a result greater than 18 digits.

DEVICE
13 CHANNEL DEFINITION

ERROR

An INCR statement caused a number to
exceed the specified size of its data
field.
16 DIBOL CHANNEL IN USE

17 BAD FILE SPECIFICATION T

Attempt to issue an OPEN statement to
channel that is already open.

Incorrect syntax in the file specification for LPQUE, OPEN, or SEND statement,
or in an external call to RENAME.

CTS-300 RUN-TIME ERROR MESSAGES

A-3

CTS-300 Run-Time Error
Number/Message

Type

M~ssages

Meaning

18 FILE NOT FOUND

The file specified in an OPEN
does -not exist.

19 HANDLER NOT AVAILABLE

The handler for the device specified
in
the file specification of an OPEN statement is not installed and/9r loaded.

20 BAD DIGIT

The alphanumer'ic value being converted
to a decimal value consisted of characters other than:
space, +, 0,
1,
2, 3, 4, 5, 6, 7, 8, or 9.

21 BAD OPEN

Attempt to issue an ACCEPT,
READ,
or
READS statement to an output-only device
(for example, line printer, paper tape
punch) •

statement

Attempt to
issue a DISPLAY,
WRITE,
FORMS, or WRITES to an input-only device
(for example, paper tape reader).
Attempt to open a file of length zero in
I or U mode.
Attempt to perform other than a READ
a WRITE in U mode.

22 1-0 ERROR

The system detected bad data during
an
input or output operation.
This may be
either a software or a hardware error.
If the operation being performed is sequential (READS or WRITES), attempts to
retry may cause loss or duplication of
data.

23 LINE TOO LONG

The data record being
input is larger
than,the space reserved for it in memory
by the associated RECORD statement
in
the Data Division.

The number of blocks of storage requested
in the file specification of an OPEN
statement is not available on this device.

SPACE

FOR

FILE

The device cannot contain more
files,
because its directory is full.
On TSD
systems, squeezing the disk may relieve
the problem.

A-4

CTS-300 RUN-TIME ERROR MESSAGES

CTS-300 Run-Time Error Messages
Number/Message
25 OUTPUT FILE FULL

Type
T

Meaning
This message is output when the operator
types a CTRL/Z at the terminal in response to the message MOUNT SUCCESSOR TO
dev:filnam.ext FOR OUTPUT. It indicates
that:
The blocks of storage requested in the
file specification of the OPEN statement
are used.
No further storage space is available on
this device.

26 FIELD OR RECORD TOO

The size of a recerd or field is greater
than 16, 383 characters.

Attempt to issue an OPEN statement in
update mode to a nonrandom access device
(that is: papertape, line printer, magnetic tape, or terminal) •

28 ILLEGAL RECORD NUMBER

A READ or WRITE statement specified a
record number argument that is negative,
zero, or greater than the number of
records in the file.

29 INCOMPATIBLE COMPILER

The program was compiled using a version
of the compiler that is incompatible
with the run-time system.

30 DIVIDE BY 0

The program performed an arithmetic operation that resulted in division by
zero.

31 ARGUMENT WRONG SIZE

Attempt to call one of the external
utility subroutines supplied by DIGITAL
using one or more arguments of the wrong
1 eng th.

32 SUPERSEDING EXISTING
FILE

Indicates that the program attempted to
create an output file having the same
name as an existing file. This error
will always occur with magnetic tape.
With disks this condition is detected
only if set up by the FLAGS external
utility subroutine (see the OIBOL-ll
Language Reference Manual).

LONG
27 UPDATE OF NON-FILE

DEVICE

CTS-300 RUN-TIME ERROR MESSAGES

A-S

eTS-300 Run-Time Error Messages
Number/Message

Type

Meaning

33 TOO MANY CHANNELS OPEN NT

A program attempted to open more I/O
channels
than the Time-Shared OISOL
supervisor allows. This limit is set
during system generation.
This error
occurs
while
executing
an
OPEN
statement.

34 TOO MANY HANDLERS
CALLED

A program attempted to use more devices
than the Time-Shared OISOL supervisor
allows.
This
limit is set during
CTS-300 system generation.
This error
occurs while executing an OPEN statement.

35 TOO MANY FILES
OPENED

The maximum number of files that TimeShared DISOL allows to be open simultaneouslywas exceeded.

36 TOO MANY BUFFERS
ALLOCATED

The maximum number of buffers
that
Time-Shared DISOL allows was exceeded.

37 DEVICE IN USE

A program operating under Time-Shared
DISOL attempted to open a channel to a
nonsharable I/O device that was being
used by another program. This error is
detected during execution of an OPEN
statement.

38 FILE IN USE

A program operating under Time-Shared
DISOL attempted to open an output file
(0 mode)
that was already opened by
another program.

39 OUTPUT TO READ-ONLY
DEVICE

Attempt to issue an OPEN statement in
output (0 mode) to an input-only device
(that is: paper tape reader).

40 RECORD LOCKED

A READ or WRITE statement specified a
record that is currently being accessed
by
another
program
running
under
Time-Shared DIBOL.

41 ?M-ILL USR

Indicates an internal problem with the
system software that is beyond your control. Notify your DIGITAL representative.

A-6

eTs-300 RUN-TIME ERROR MESSAGES

CTS-300 Run-Time Error Messages
Number/Message

Type

42 ?M-NO DEV

Meaning
Attempt to use the line printer while
the single-user line printer spooler is
running.
Indicates an internal problem with the
system software that is beyond your control. Notify your DIGITAL representative.

43 ?M-DIR IO ERR

Hardware error:

•

Device write-locked.

•

Device either cannot
read
or
cannot write in its directory.
If
condition persists, notify your
DIGITAL representative.

44 ?M-BAD FETCH

Error while loading a device handler.
The file cannot be read.
If condition
persists, notify your DIGITAL representative.

45 ?M-OVLY ERR

Error while reading DIBOL-II program
overlay into memory. This is a hardware
error.
If condition persists, notify
your DIGITAL representative.

46 ?M-DIR OVFLO

During execution of an OPEN statement (0
mode)
no entry space for the new file
was available in the device directory.

47 ?M-ILL ADDR

Indicates an internal problem with the
CTS-300 software.
Notify your DIGITAL
representative.

48 ?M-ILL CHAN

Indicates an internal problem with the
CTS-300 software.
Notify your DIGITAL
representative.

49 ?M-ILL EMT

Indicates an internal problem with the
CTS-300 software.
Notify your DIGITAL
representative.

50 UNRECOVERABLE SYSTEM
ERROR

Indicates an internal problem with the
system software that is beyond your control.
Notify your DIGITAL representative.

CTS-300 RUN-TIME ERROR MESSAGES

A-7

CTS-300 Run-Time Error Messages
Number/Message

Type

Meaning

51 TOO MANY MESSAGES

The total size of all messages is more
than 16 K bytes, there are too many messages, or the size of this message is
too large.
In all cases, the message is
not stored.

52 ILLEGAL KEY

An ISAM key was specified that was not
defined in the data section of the program. That is, the key position was
wrong.
This message occurs with the
~READ, NEXT, STORE, and WRITE
statements
in conjuction with ISAM.

53 KEY NOT SAME

This message can occur while doing a DELETE or a WRITE:
message occurs with a READ if
• This
the size of the key is equal to
the size of the data file key but
the system can not find the key
specified. The next higher approximate key is returned along
with this message.
message occurs while doing a
• This
DELETE or a WRITE if the key value
identified within the record to be
deleted or updated is not the same
as the key of the last record
read.
This last record is still
locked and the DELETE or WRITE is
not performed.

54 NO DUPLICATES

In an ISAM file, a recQrd with a duplicate key was added to a file where duplicate keys are not allowed.

55 NO ISAM CTSGENED

During CTSGEN, a negative answer was
specified
to
DO
YOU
WANT
ISAM?
Therefore, if SI or SU is used with the
OPEN statement, this message will occur.

56 NOT ISAM FILE

The specified file was not an ISAM file
and was OPENed in SI or SU mode. The
message occurs with DELETE and STORE
statements.

57 OVERFLOW FULL

In an ISAM file,
there is not enough
room for another record to be added
(that is, there are no empty overflow
groups or load exclusion spaces).

A-a

CTS-300 RUN-TIME ERROR MESSAGES

CTS-300 Run-Time Error Messages
Number/Message

Type

Meaning

58 JOB STARTUP ERROR

There is not enough memory, the terminal
is busy, or an I/O error occured while
loading the job.

59 ILLEGAL TERMINAL
NUMBER

You are either sending a message specifying a terminal number that does not
exist or you are trying to start up a
job on a terminal that does not exist.

66 R6 STACK OVERFLOW

An attempt was made to use imbedded
CALLs, or a routine calls itself.

68 NOT ENOUGH MEMORY TO
RUN PROGRAM

Program cannot be run, due to insufficient addressable memory space.
In
Time-Shared DIBOL, the size of the program is greater than available free memory.

69 PROGRAM NOT LINKED
WITH /B:100000 ?

A program is linked at an octal address
other than 100000.

70 BAD BINARY FILE

The data is corrupted, or this is not
DIBOL file.

71 ILLEGAL DEVICE

In XMTSD, the device handler is either
not installed or is installed and not
loaded.
In nonextended memory TSD,
a
legal device name has been specified but
the handler is not installed in the system.

72 JOB TABLES FULL

You have exceeded the maximum number of
jobs specified when you did your CTSGEN
for your configuration.

73 JOB EXCEEDS
MAXIMUM SIZE

The job has exceeded the maximum permissible size.
In TSD or XMTSD the maximum
addressable amount of memory is 16 K
words (32 K bytes).
In SUD maximum size
is limited by available free memory.

74 TOO MANY ISAM VOLUMES
PER FILE

The maximum number of volumes per file
that you specified in CTSGEN has been
exceeded.

75 TOO MANY ISAM FILES

The number you specified in
just been exceeded.

76 TOO MANY FILES OPENED
IN U-MODE

The number you specified in CTSGEN has
just been exceeded.

CTSGEN

CTS-300 RUN-TIME ERROR MESSAGES

has

A-9

CTS-300 Run-Time Error Messages
Number/Message

Type

Meaning

77 ARGUMENTS OUT OF ORDER T

The order of the arguments in the call
to the PAK/UNPAK subroutine does not
match the record definition.

78 ARGUMENT OUT OF RECORD T
LIMIT

An argument passed in the call is not
part of the record being packed or unpacked.

79 ARGUMENT COUNT

A minimum of three arguments is required
by the PAK subroutine.

80 FIELD NOT PACKED

The UNPAK subroutine is asked to unpack
a record that was not previously packed.

81 FB INIT ERROR

A program has attempted to use a system
communication feature that is reserved
for exclusive use by XMTSD.

82 ILLEGAL XCALL

A call to the GLINE subroutine is invalid from a time-shared program.

A-10

CTS-300 RUN-TIME ERROR MESSAGES

APPENDIX B
ERROR MESSAGES

The following tables B-1, B-2, and 8-4 through 8-11 present the error
information for the CTS-300 Utility Programs. Table 8-3 contains errors generated by a OI80L Time-Shared RTS program.
All error messages are in blue print.

8-1

Table 8-1
DKED Error Messages
Advance line finds end of page
The advance line function moved the cursor to the top of the
Use any valid function or command.

page.

Arrow command finds extremity of page
The meaning depends on the particular arrow function:
• The uparrow function has moved the cursor to the bottom of
the page.
• The leftarrow function has moved the cursor to the
ning (first character position) of the page.

begin-

• The downarrow function has moved the cursor to the
of the page.

bottom

• The rightarrow has moved the cursor to the end (last character position) of the page.
Use any valid function or command.
Backup line finds beginning of page
The backup function moved the cursor to the
Use any valid function or command.

beginnin~

Bad digit in repeat count
A character other than a digit was entered as part
count.

of the

page.

the

repeat

Buffer is full
The text buffer is full.
Keyboard data is no longer accepted.
EXIT, REOPN, or PAGE to continue entering data.

Use

Change case finds beginning of page
In the backup direction mode, the change case function changed the
case of the first character in the page.
Use any valid function or
command.
Change case finds end of page
In the advance direction mode, the change case function changed the
case of the last character in the page.
Use any valid function or
command.
CTRL/C ignored use quit
DKED ignores a single CTRL/C.

Use any valid function or command.

Cursor not at target
DKED could not complete a REPLACE or SUBSTITUTE function because
either the cursor is not at the search model or you have not specified a search model.

B-2

'ERROR MESSAGES

Table B-1 (Cont.)
DKED Error Messages
DELETE finds end of page
The DELETE function deleted the last character in
any valid function or command.

the

page.

Use

DELETE finds beginning of page
The DELETE function erased the first character in
any valid function or command.

the

page.

Use

model,

the

first

Dot (.) cannot be 1st chr of target
When you are specifying wildcards in
character can not be a dot.

Dot (.) cannot be last chr of target
When you are specifying wildcards in a search model, the last character can not be a dot.
EDL finds end of page
The end-of-line function moved the cursor to the end of
Use any valid function or command.

the

EDL finds beginning of page
The end-of-line function moved the cursor to the beginning
page. Use any valid function or command.

page.

the

exists;

you

Illegal command
DKED could not recognize the command you specified.
Illegal command sequence. Please start over.
This error occurs when you open a file that already
elect to continue and then issue a QUIT command.

Illegal function for mode of use
This error occurs in inspection use mode. When you are inspecting
a file, you can not enter commands or perform functions that modify
the file.
Invalid terminatinq key
DKED could not complete a FIND function for one
reasons:

the

following

• You included an illegal character in the model •
• You did not terminate the model with the ADVANCE or BACKUP
function.
More than 130 chars./record
You entered more than 130 characters since
. return / line feed.

the

carriage

ERROR MESSAGES

B-3

Table 8-1 (Cont.)
DKED Error Messages
Move to bottom when at bottom
You have attempted to move to the bottom of the page when
already there.

you

are

Move to top when at top
You have attempted to move to the top of the page when you are
ready there.

al-

No search model defined
DKED could not process the FIND-NEXT, REPLACE, or SUBSTITUTE
tion because you have not yet specified a search model.

func-

NOT ENOUGH ROOM IN OUTPUT FILE - PLEASE START OVER
You have opened a file and have specified a value for number of
blocks that results in a file smaller than the input, and then you
exited or paged.
There are not enough blocks in the
output file, you have specified.

output

file,

intermediate

There is no room on the physical device for the output file or
termediate output file.
Nothing to undelete
DKED could not complete the undelete function because
ponding line or character buffer is empty.

the

in-

corres-

No valid select range
There are three circumstances under which this message can occur:
• You tried to CUT or APPEND before using the
tion.

SELECT

func-

• You have modified the file after using
tion.

the

SELECT

func-

• You used either a PAGE or a YANK after
function.

the

SELECT

RANGE

Repeat = 0 ??
Repeat count can not be a "0".
Section finds beginning of page
The section function moved the cursor to the beginning of the page.
Use any valid function or command.
Section finds end of page
The section function moved the cursor to the end of the page.
any valid function or comman~
Asterisk (*) cannot be 1st chr of target
When you are specifying wildcards in a
character can not be an asterisk.
8-4

ERROR MESSAGES

model,

the

Use

first

Table 8-1 (Cont.)
DKED Error Messages
Asterisk (*) cannot be last chr of tarqet
When you are specifying wildcards in a search model, the last character can not be an asterisk.
Target not found
A FIND or FINDNEXT function moved the cursor to the bottom or top
of the page
(or file if p option used in forward mode) without
finding a string that matches the model specified.
Text buffer is filling up
DKED has detected that the text buffer is close to
Use EXIT, REOPN, or PAGE to continue entering data.

being

filled.

Unable to open input file
The file specified was not found.

ERROR MESSAGES

8-5

Table B.... 2
DICOMP Error Messages
In the following table the errors are identified as to type:
E

= error, compilation not stopped

= fatal error, compilation stops
W = warning, program will run, but unpredictably
F

Message

Type

BAD DUMMY VARIABLE SIZE

Meaning
The size of a dummy variable should be
To prevent the warning message, the
dimension should be specified as 0 or
omitted altogether.

BAD IF STMNT

A START, END, or illegal statement was
detected within an IF statement, or no
statement was found on the right side of
the IF statement.

No variable was found on the left side
of "=", or it was not a legal variable.

BAD LPQUE STMNT

A colon was missing, or the order of argum'ents was incorrect in an LPQUE statement.

BAD OVERLAY

There was no previously
to be overlaid.

BAD PROC #

The left parenthesis was missing, or n
was greater than 16. The statement must
be of the form PROC (n).

BAD SWITCH

The compiler detected an unrecognized
switch. The compiler is restarted.
The
switches are:

BAD LEFT SIDE OF

'='

defined

record

W,B,S,D,O,A,C,P:N,G, and L
CCP ERROR

Every .IFDEF and
.IFNDEF
corresponding
.ENDC for
nesting.

COMMA MISSING

No comma was found where it was
ed.

CREF I/O ERROR

A hardware error occurred while writing
the CREF output file.
The system returns to monitor command level.

8-6

ERROR MESSAGES

must have a
each level of
expect-

Table B-2 (Cont.)
DICOMP Error Messages
Message

Type

Meaning

CREF OUT OF ROOM

The space allocated for the temporary
CREF output file was completely filled.

DECIMAL FIELD )18 CHARS

The legal limit of a decimal field
for
run time is eighteen (18) characters.

EXPECTED LABEL MISSING

A label was not found where it
pected or required.

was

ex-

EXPRESSION NOT DECIMAL

The expression is not defined, or it
in alphabetic format.

EXTRA CHARS AT STMNT END

This is an error in the PROC section.

This becomes a warning in the DATA
tion.

FIELD
TOO LARGE OR ZERO
.,.

A field exceeded
acters) •

FILE NOT FOUND

The compiler could not find the file(s)
specified in the command line. The compiler is restarted.

ILLEGAL COMMAND

Only two output files may be specified
in a compiler command string.
The compiler is restarted.

ILLEGAL DEVICE

A device specified in the compiler
mand string was not recognized
legal device.

ILLEGAL FIRST STMNT

The only allowable initial statements in
a
program
segment are the RECORD,
SUBROUTINE, START, and CCP statements.

ILLEGAL NAME

The first character in a name was not an
alphabetic character.

ILLEGAL OR MISSING
OPERATOR

No comma appeared in the data formatting statements, or an invalid operator
was found within an expression.

ILLEGAL STMNT

The statement was not recognized as a
legal
DIBOL statement, or the PROC
statement was used more than once, or an
END or START was found within an IF
statement.

16,383

bytes

sec(char-

ERROR MESSAGES

comas a

B-7

Table B-2 (Cont.)
DICOMP Error Messages
Message

Type

Meaning

INITIAL VALUE NOT ALLOWED W

No fields within overlay records can
given initial values.

INITIAL VALUE NOT EQUAL
TO SIZE

The field size specifier and the size
of its initial value do not agree.

INPUT FILES?

The compiler command string contained no
input files.

INPUT I/O ERROR

A hardware error occurred while an input
file was being read. The system returns
to monitor command level.

LINE TOO LONG

The line exceeded 511 characters including carriage return / line feed pairs.

LISTING I/O ERROR

A hardware error occurred while writing
the listing file. The system returns to
monitor command level.

LISTING OUT OF ROOM

The space allocated for the listing file
was completely filled.

MISSING CLOSE PAREN

Not every left parenthesis used within
an expression has a corresponding right
parenthesis.

MISSING OPERAND

An expected
missing.

MISSING QUOTE

A quote (I) was not found where
expected.

NAME PREVIOUSLY DEFINED

Multiple definition of a field or record
name is not allowed.

NAME TOO LONG

A name with more than six characters, or
a subroutine name with more than five
characters, was detected.
The excess
characters are ignored.

NO FIELD STMNTS IN
PREVIOUS RECORD

A record size of zero was detected.
The problem occurs because of the lack
of, or the improper definition of, field
statements.

8-8

ERROR MESSAGES

variable

literal
it

was
was

Table 8-2 (Cont.)
DICOMP Error Messages
Message

Type

Meaning

NO LISTING FILE FOR CREF

A CREF listing was specified in the compiler command string via the /C switch,
but no listing file specification was
included in the same command string.
The compiler is restarted.

NOT A OR D

A field specification can be only A (alphabetic) or D (decimal).

NOT DECIMAL

The initial value of a decimal field was
not specified in decimal format.

NOT ENOUGH MEMORY

There was not enough memory to compile
the program.
Reduce either the number
of output files and different device
handlers, or the number of symbols in
the program. The system returns to monitor command level.

NOT I, 0, OR U

The second argument of an OPEN statement
does not begin with an I, 0, U, or S.

OBJ I/O ERROR

A hardware error occurred while writing
the object file. The system returns to
monitor command level.

OBJ OUT OF ROOM

The space allocated for the object
was completely filled.

RECORD TOO BIG

The named record exceeded 16,383 bytes
(characters), or an overlay exceeded the
size of the record it was overlaying.

RELATIONAL NOT IN IF
STMNT

A relational operator appears outside an
IF statement.

STMNT TOO COMPLEX

Internal compiler storage was exceeded
in an attempt to compile too complex an
expression. Break the expression into
two or more statements.

SUBSCRIPT ERROR

The specified subscripts are alphabetic,
or are not separated by a comma, or are
not.c1osed by a right parenthesis, or
total more than two subscripts.

SUBSCRIPT STACK OVERFLOW

Internal compiler storage was exceeded
in an attempt to compile too many nested
subscripts.

ERROR MESSAGES

file

B-9

Table B-2 (Cont.)
DICOMP Error Messages
Message

Type

Meaning

SUBROUTINE NAME MISSING

The name of the subroutine in a SUBROUTINE or XCALL statement is missing.

TOO MANY SYMBOLS OR
LABELS

More than 1023 symbols,
1023 labels occurred in a
ment.

TOO MUCH DATA

More than 32,767 bytes of data
literals were found in the program.

and

UNDEFINED LABEL

An unidentified label was referenced
the PROC section.

UNDEFINED NAME

A variable not defined in the DATA section was encountered in the PROC section.

WRONG DATA TYPE

An expression contains incompatible data
types: alphabetic and decimal.

8-10

ERROR MESSAGES

or more than
program seg-

Table 8-3
Time-Shared OI80L Error Messages
PROGRAM NOT DETACHED
An attempt was made to issue an ATTACH command to
was currently attached to another terminal.

program

that

not

reside

PROGRAM NOT FOUND
The program specified in an ATTACH or RUN command does
on the specified device.

TRAP TO 4 PC=
A time-out or bus error has occurred, there has been an attempt to
access nonexistent memory, or a word instruction was attempted on
an odd address. Consult your DIGITAL hardware/software specialist.
TRAP TO 10 PC=
An attempt to execute an undefined instruction
Consult your DIGITAL hardware/software specialist.

has

occurred.

TSD INITIALIZATION ERROR CANNOT RUN IN FOREGROUND PARTITION
An attempt to run nonextended memory TSD in the foreground
tion was made. Control returns to the RT-ll monitor.

parti-

XM-TSD INITIALIZATION ERROR CANNOT CREATE EXTENDED MEMORY REGION
An attempt was made to run XMTSD with the SJ or F8 monitor.

ERROR MESSAGES

8-11

Table B-4
Foreground/Background Communication Command
Error Messages
Message

Meaning

BACKGROUND LISTENER NOT
RUNNING REQUEST DISCARDED
filespec

The special background listener program
is not running, so the request from the
foreground has to be rejected. The file
discarded is identified by filespec.

FILE NOT FOUND

The indirect file specified in the request from the foreground was not found.

HANDLER NOT FOUND

In processing the indirect file from the
foreground, the background has found a
necessary device handler missing.

ILLEGAL BACKGROUND OPERATION

A communication command was issued when
XMTSD is running in the background.

QUEUE FULL-ENTRY REJECTED
filespec

The job queue is full,
so the request
has to be rejected. The file rejected
is identified by filespec.

QUEUE IS EMPTY

There are no jobs in the queue for
background
processing.
This is not
considered an error message when in
response to a SHOW command.

B-12

ERROR MESSAGES

Table 8-5
DDT Error Messages
Message

Meaning

LITERAL?

The variable name entered appears to
a literal.

NO SUCH VARIABLE

There is no variable
tered.

en-

SUBSCRIPT ERROR

You have attempted to manipulate a variable using subscripts to access part of
a field and you have not conformed to
the
rules for subscripts.
See the
DI80L-II Language Reference Manual.

TOO MANY BREAKPOINTS

There may be only one breakpoint in the
main program and in each of the subscripts. A maximum of eight breakpoints
total is allowed at anyone time.

WHAT?

The number was not specified in an iteration command.

the

name

You specified a routine name in which to
set q breakpoint but did not follow it
with a colon.
A decimal value was expected but was not
entered.

ERROR MESSAGES

8-13

Table 8-6
Spooler Error Messages (LPTSP1.REL)
Message

Meaning

FATAL LPQUE ERROR

The spooler detected
file being read.

?M-NO DEV

The device handler for the device containing the file to be printed was not
loaded when the spooler was initialized.

?PLEASE LOAD LINE PRINTER
HANDLER

The spooler was run before the
printer handler was loaded.

8-14

ERROR MESSAGES

error

the

line

Table 8-7
Spooler Error Messages (LPTSPL.TSD)
Message

Meaning

BAD LPQFIL.LPQ

This message occurs under the
conditions:'

following

•

The spooler attempts to create this
file and the OPEN fails.

•

The file already exists and the
spooler attempts to open it in update mode and the OPEN fails.

•

The file exists and a failure occurs while doing I/O to the file.

ERROR OPENING
dev:filnam.ext

The queue file entry specified a nonexistent file (dev:filenam.ext), or
a
nonexistent
or
illegal I/O device.
Processing continues with the next queue
file entry.

I/O ERROR dev:filnam.ext

An error occurred while the spooler was
reading the file (dev:filnam.ext) currently being printed. A YES response to
the resulting message CONTINUE PRINTING
filename?
will
reprint
the
file.
Otherwise, processing continues with the
next queue entry.

LP HUNG-FIX & TYPE CR

The line printer is in an off-line
state. This could be because it ran out
of paper, was placed off line, or possibly because of a malfunction. The record that was being printed is lost.
Correcting the problem and typing carriage return will resume printing with
the next record.

ERROR MESSAGES

8-15

Table 8-7 (Cont.)
Spooler Error Messages (LPTSPL.TSD)
Message

Meaning

PRINTER n NOT FREE

The printer handler is not loaded or
a job has just been submitted to a
satellite
which attempts to open a
printer. The printer is found to be
already in use. The satellite program
terminates and the spooler searches for
another job to print. When the spooler
returns to this point in the queue,
another attempt will be made to print
the file.

SATELLITE L P SAT CAN NOT RUN Failure to CTSGEN for forced job startup
Q
can cause this error message~
It may
also indicate that a satellite progr~m
R
S
is
already running although, it IS
unrecognized by the spooler, or that the
spooler is
attempting a forced job
startup on an already active satellite.
Kill that job via the STATUS option Kx
and
bring the TSD system down and
restart it.

8-16

ERROR MESSAGES

Table 8-8
PRINTU Error Messages
The number near the error message (indicated by a pound sign)
cates the character position nearest where the error occurred.

indi-

Message

Meaning

ALPHA LITERAL REQUIRED #

Expected alpha literal is missing.

ALREADY DEFINED

An attempt was made to name a field
in
the INPUT or COMPUTE section with a name
that was previously used.

HEADER IS TOO LONG

The header line exceeds 132 characters.

IMPROPER DEFINITION #

Filler item in the PRINT section is used
incorrectly.

IMPROPER LITERAL #

Literal too large

IMPROPER USE OF DECIMAL
PLACES #

The number of decimal places exceeds the
size of the field being defined.

INTEGER FROM 1-15 REQUIRED #

The expected decimal
range.

field

out

INTEGER FROM 1-132 REQUIRED # The expected decimal
range.

field

out

INTEGER REQUIRED #

Integer missing where expected.

LITERAL TOO LONG #

Field description exceeds 30 characters.

MUST BE IDENT #

The first section in
must be IDENT.

MUST BE NUMERIC ITEM #

An item expected to be
fined incorrectly.

MUST BE SU OR IS

SU and IS are the only legal options in
the INPUT statement that follow the
comma.

NEED FILE NAME

File name missing from the IDENT
ment.

NO ENDING QUOTE #

No closing quote for a HEADl, HEAD2, or
for the text portion in a PRINT statement.

NO INPUT DIRECTIVE

The INPUT statement is missing.

the

control

numeric

file

ERROR MESSAGES

de-

state-

8-17

Table 8-8 (Cont.)
PRINTU Error Messages
Message

Meaning

NO PRINT ITEMS

No fields are specified
PRINT statement.

NOT DEFINED

An attempt was made to print
that has not been defined.

NOT ENOUGH RIGHT
PARENTHESES #

A statement in the COMPUTE
too few right parentheses.

PICTURE TOO LONG

The picture, or edit mask, for
exceeds 22 characters.

SYNTAX ERROR #

Statement contains illegal characters or
options.

TOO MANY COLUMNS IN REPORT

More than 132 columns under
HEAD2, or PRINT sections.

TOO MANY COMPUTE STATEMENTS

More than eight COMPUTE statements
specified.

were

TOO MANY DATA ITEMS

More than 20 data
section.

INPUT

TOO MANY LEFT PARENTHESES

A statement in the COMPUTE section is
too complicated to be handled by PRINTU.

TOO MANY LIST ITEMS

More than 20 data
section.

TOO MANY RIGHT PARENTHESES

A statement in the COMPUTE section
too many right parentheses.

UNKNOWN DIRECTIVE

An invalid section statement.
Only
IDENT,
HEADI,
HEAD2,
INPUT, COMPUTE,
PRINT, and END are legal.

8-18

ERROR MESSAGES

items

following

the

field

section

has

printing

HEAD1,

the

INPUT
has

Table 8-9
ISMUTL Error Messages
Message

Meaning

ALL FILES ALLOCATED AND MORE
SPACE IS REQUIRED PLEASE TRY
AGAIN

The required disk space was not. allocated within the limit of seven data files.

BAD FILE SPECIFICATION

Something other than a specification of
the form DEV:FILENA.EXT was given, or
the specification contains an invalid
element.
(The extension is not necessary when specifying an output file.)

DUPLICATE KEYS FOUND

During CREATE, the input file was found
to contain records with duplicate keys
when the answer had been NO to ALLOW DUPLICATE KEYS.

FILE ALREADY EXISTS
REPLACE?
(YES/NO)

An existing file name was specified
an output file.

FUNCTION REQUIRES ISAM INPUT
FILE

During a REORG or STATUS function,
a
file other than an ISAM file was specified as the input file.

MORE INPUT RECORDS THAN
SPECIFIED - RESTART FUNCTION

The number of records in the input file
is greater than the number specified
during the ISAM file CREATE.
Restart
the CREATE and specify a number for
input records equal to, or greater than,
the number in ·the input file.
This message may also occur during a REORG if
the number of records specified by the
Index File Control Group is less than
the number of records in the ISAM input
file.
In this situation a restart will
not help.
You must build a sequential
file from the corrupted ISAM file and
use this as input for a new ISAM CREATE.

NO SPACE FOR FILE

While running REORG,
the number
of
blocks
of storage requested is not
available on the device, or the device
directory is full.

NOT ENOUGH WORKFILE SPACE
ALLOCATED

While running REORG in CHAIN mode, there
was not enough work space available to
perform the function.
Control is returned to the monitor.

OUT OF RANGE

A number larger than the limit was
during the CREATE or REORG dialog.

used

PLEASE TRY AGAIN

Neither a Y nor an N was given
ponse to a YES/NO question.

res-

ERROR MESSAGES

8-19

for

Table 8-10
SORTG Error Messages
Message

Meaning

EXECUTE STATEMENT ERROR

The EXECUTE statement does not contain a
valid file specification.

FILENAME MISSING

An INPUT or OUTPUT statement has no file
name.

INPUT:

No INPUT statement exists.

STATEMENT MISSING

INSUFFICIENT SPACE

The main memory allocation is too small
to support the record size. You must
either increase main memory allocation,
decrease the number of work files, or
change to aTAGSORT.
The SORT/MERGE
internal
buffer
is
slightly smaller than the maximum nIBOL
record size permitted. This error message could be caused by record sizes
which are larger than the limits of the
work area.
In this case, a TAGSORT
could be used.

INVALID INPUT RECORD COUNT

The record count for an input file
the INPUT statement is not valid.

KEYS:

No KEYS statement exists.

STATEMENT MISSING

MULTIPLE CONTROL STATEMENT

More than one control statement has
same identifier.

OUTPUT:

No OUTPUT statement exists.

STATEMENT MISSING

RECORD HAS NO DATA ITEMS

The RECORD statement does
any field definitions.

RECORD:

No RECORD statement exists.

STATEMENT MISSING

not

the

contain

SIZE DEFINITION ERROR

A field definition in the RECORD statement describes the field as having an
invalid length.

SORT KEY MISSING

The KEYS statement has no control
names, or ends with a comma.

8-20

ERROR MESSAGES

key

Table 8-10 (Cont.)
SORTG Error Messages
Message

Meaning

SORT MODE FILENAME CONFLICT

An attempt was made to
into itself when:

write

the

file

• The input file is an ISAM file.
• A file merge is being done.
• TAGSORTS that do not produce a reordered file (i.e., INDEX or LIST)
are being done.
TAG SORT TYPE INVALID

A tag other than SORT,
LIST, or INDEX
has been used and is not recognized.

TOO MANY MERGE FILES

The INPUT statement has more than
files specified.

seven

TOO MANY SORT KEYS

The KEYS statement contains
eight control key names.

than

TYPE DEFINITION ERROR

A field definition in the RECORD statement describes the field to be other
than alphabetic or decimal.

UNRECOGNIZED STATEMENT

SORTG was unable to identify the meaning
of the line.

ERROR MESSAGES

8-21

Table 8-11
SORTM Error Messages
Message

Meaning

END OF SORT RECIN-xxxxx
RECOUT=yyyyy

Possibly due to a bad I/O transfer, the
number of input records does not agree
with the number of output records.
In
this case, xxxxx will be the count of
input records, and yyyyy will be the
count of output records.

HANDLER NOT

AVAILABLE

An
unassigned device name has been
specified.
You must assign the logical
device name to a physical device.

OPEN ERROR FREE SPACE
MARGINAL

SORT/MERGE cannot find enough disk space
to allocate the files.

WRONG RECORD SIZE

An attempt was made to specify a file
name with an improper record description.

8-22

ERROR MESSAGES

Table 8-12
STATUS Error Messages (STATUS.TSD)
Message

Meaning

BAD SPECIFICATION

A printer number for a
printer has been specified.

LP IN USE

A number between 1 and 4 has been entered;
however, that line printer is
busy.

NO JOB BY THAT NUMBER

A job number for a nonexistant
been entered.

NO SUCH OPTION

A letter other than a
letter has been entered.

nonexistant

job

valid

ERROR MESSAGES

has

option

8-23

Table 8-13
REDUCE Error Messages
Message

Meaning

?REDUCE-F-ERROR READING
DIRECTORY

The directory is nonexistent or damaged.
This is often a hardware error.

?REDUCE-F-ERROR READING FILE

The input file cannot be read.
usually a hardware error.

This

?REDUCE-F-ERROR WRITING FILE

The file cannot be written.
This
usually
a
hardware
error
or
WRITE-LOCKED device.

is
a

?REDUCE-I-FILE INCORRECTLY
LINKED DEV:FILENA.EXT

An input file linked for a base address
of other than 100000 has been specified.

?REDUCE-I-IMPROPER BASE
ADDRESS IN OVERLAID FILE
DEV:FILENA.EXT

An input file linked for a base address
other than 100000 has been specified.

?REDUCE-I-INCORRECT RELATIVE
BLOCK NUMBERS IN OVERLAID
FILE DEV:FILENA.EXT

A library .OBJ file has been linked into
an overlay region.

?REDUCE-I-FILE-PREVIOUSLY
REDUCED DEV:FILENA.EXT

An input file that has already
REDUCED has been specified.

been

?REDUCE-W-FOREIGN HANDLER

A device handler unknown to
been specified'.

has

REDUCE

A nonfile-structured device has been assigned a file-structured name.
?REDUCE-W-ILLEGAL COMMAND

This is a syntax error;
graphical error.

?REDUCE-F-ILLEGAL DIRECTORY

A device with a non-RT-ll directory
been specified for input.

?REDUCE-W-ILLEGAL OPTION
"/OPT"

An option other
entered.

usually a typohas

than /N or /V has been

?REDUCE-F-INSUFFICIENT MEMORY There is not enough memory on the system
to support REDUCE and
its associated
data.
?REDUCE-F-INSUFFICIENT ROOM
IN DIRECTORY OR ON DEVICE

8-24

ERROR MESSAGES

The output
device
contain the file.

specified

cannot

Table B-13 (Cont.)
REDUCE Error Messages
Message

Meaning

?REDUCE-I-VERNUM

This message is displayed with the current verSion number
(VERNUM) whenever
the IV option is specified in the command line.

?REDUCE-W-SPECIFIED INPUT
FILE(S) NOT FOUND

The input
specified.
null line.

file is not on the device
This can also be caused by a

?REDUCE-W-UNSUPPORTED DEVICE: A nonfile-structured
"DEV"
specified.
?REDUCE-W-[+2K MEMORY]

device

has

been

This notes that, due to
processing
needs, the USR is forced to swap to obtain the necessary processing space for
REDUCE.

ERROR MESSAGES

8-25

INDEX

A
/A (DICOMP option), 4-3
Abbreviated keyboard commands,
2-2
Absolute shutdown, 5-31
Access,
ISAM, 10-14 to 10-16
random, 2-5
sequential, 2-5
Accumulation field, 9-2, 9-13,
9-14
Append area, 10-3, 10-5, 10-12
ASSIGN command, 5-11
use with I$AM file devices,
10-24
Assignments,
device, 2-2
removal of, 2-3
ATTACH command, 5-6, 5-11
restrictions, 5-7
Auto-Create (ISAM), 10-25,
10-40, 10-42
Auto job startup,
specification in CTSGEN, 6-19
B
/B (DICOMP option), 4-3
Backup file (ISAM input), 10-23
BGMAN.TSD, 5-17
Brackets in keyboard commands,
2-2
Breakfield (PRINTU), 9-2, 9-9
Breakpoints, see DDT
Brief error messages,
specification in CTSGEN, 6-18
.BAD, 2-4
• BAK, 2-4
C
/C (DICOMP option), 4-3
CANCEL command (XMTSD), 5-20
Carriage return, command
terminator, 2-2
Chain mode startup (TSD
program), 5-12
RTEXIT, 5-31
STATUS and REORG, 10-38, 10-39
TSD printer spooler, 8-8
Changing record or key length,
10-10
Channels,
specification in CTSGEN, 6-16
requirement for ISAM files,
10-21, 10-22
Checkpoint files (ISAM), 10-23,
10-34

Cleanup routine (in ISAM
CREATE), 10-32
Clearing breakpoints, see DDT
Clock, KWII-P, 6-2
CLOSE statement (ISAM use),
10-16
Command(s) ,
abbreviations, 2-2
compiler, see DICOMP
debugging, see DDT
errors from terminal, 2-4
keyboard, 2-3
linker, see program (utility)
to be linked
syntax, 2-2
termination, 2-2
to allocate system resources,
2-3
to start a program, 2-3, 5-10,
5-16
Common cross-reference table
(D I COM P), 4 - 7
Compiler, see DICOMP
Compiling for DDT, 7-2
COMPUTE statement (PRINTU), 9-12
Concurrent development (XMTSD),
5-28
Control,
file (PRINTU), 9-2, 9-3
file (SORT/MERGE), 11-2, 11-3
key (SORT/MERGE), 11-6
Control statements, see PRINTU
and SORT/MERGE
COpy command (XMTSD), 5-25
CREATE command (XMTSD), 5-25
Creating overlays, 5-9
CREATE, ISAM function, 10-22 to
10-32
characteristics, 10-23
dialog, 10-26 to 10-30
example, 10-30, 10-31
flowchart, 10-27
possible CREATE problems,
10-32
CREF listing (DICOMP),
common cross-reference table,
4-7
external subroutine
cross-reference table, 4-7
label cross-reference table,
4-7
symbol cross-reference table,
4-7
CTRL/B, LPTSPl.REL, 8-3
CTRL/C, 2-1. 5-14
CTRL/F, LPTSPl.REL spooler
response, 8-3, 8-4
Index-l

INDEX (Cont.)

CTRL/G, in DDT, 7-5
CTRL/L, 3-2
CTRL/O, 2-2
CTRL/Q, 2-2
CTRL/S, 2-2
CTRL/U, 2-2
CTRL/Z,
as EOF, 2-5
DKED interpretation, 3-9
in DDT, 7-4
keyboard command, 2-2
CTRL key, 2-1
CTSGEN, 1-4, 5-1, 6-1, 6-4
brief error messages, 6-18
choices, 6-4
dialog, 6-6 to 6-19
error messages, 6-20
flowchart, 6-7
hardware/software
configuration, 6-16 to 6-19
preliminary requirements, 6-5
question types, 6-6
SUD system, 6-8, 6-9
terminal specification, 6-10
to 6-16
TSD system, 6-9
CTS-300,
common file name extensions,
2-4
data files, 2-5
device name format, 2-4
pur po s e, 1-2
run-time system errors, A-2
utility programs, 1-4
CTS-300/RT-11 SYSGEN, 6-2, 6-3
.COM, 2-4
D

/D (DICOMP option), 4-3
Data,
field (DICOMP), 4-5
field dimension (DICOMP), 4-6
field names (DICOMP), 4-5
field size DICOMP), 4-6
f i 1 e ( I SAM), 10- 2 , 10:'" 4, 10- 5
file management (TSD), 5-6
DATE command, 2-3
DCL commands, 4-1, 5-17
DCL-like commands, 5-18, 5-21
DDT (DIBOL debugging technique),
1-4, 7-1
breakpoint control, 7-5
commands, see DDT commands
command termination, 7-4
compiling for, 7-2
consequences of improper
preparation, 7-3
2-Index

error messages, 7-3, B-13
1 ink i ng, 7 - 2
preparing for, 7-1 to 7-3
program execution control, 7-4
running, 7-3
specification in CTSGEN, 6-18
subroutine traceback, 7-10
variable manipulation, 7-8
DDT commands,
clearing breakpoints, 7-7
examining variables, 7-8
extended variable
manipulation, 7-9
iteration of breakpoints, 7-7
setting breakpoints, 7-6
setting variables, 7-9
single step, 7-5
start or resume operation, 7-4
subroutine traceback, 7-10
DEASSIGN command, 2-3
Debugging, see DDT
Default extensions, 2-4, 10-24
Default printers, see LPTSPL.TSD
DELETE command (XMTSD), 5-25
DELETE statement (ISAM use),
10-16
DETACH statement,
SORT/MERGE, 5-6
TSD, 5-6
Detached program operation, 5-6
Device,
assignments, 2-3, 10-24, 10-34
handler changes by SET
command, 2-3
name, 2-4
sharing, 5-7
specification in CTSGEN, 6-16
DIBOL,
code interpreting, 1-2, 5-2
compiler, see DICOMP
data file, 1-4, 2-4
debugging technique, see DDT
DIGITAL's Business Oriented
Language, 1-1
library, 5-3, 5-8
object file, 1-4, 4-1
source file, 1-4, 4-1
utilities, 1-4, 1-5
DIBOL ISAM access
statements, 10-13, 10-16
CLOSE statement, 10-16
DELETE statement, 10-16
OPEN statement, 10-13
READ statement, 10-14
READS statement, 10-14
STORE statement, 10-15
UNLOCK statement, 10-16

INDEX (Cont.)

WRITE statement, 10-15
DICOMP (DI80L compiler), 1-4
/A option, 4-3
/8 option, 4-3
/C option, 4-3
/D option, 4-3
/G option, 4-3
/L option, 4-4
/0 option, 4-4
/P:Noption, 4-4
/S option, 4-4
/W option, 4-4
cross reference listing, see
CREF
error messages, 4-7, 8-6
error reporting, 4-7
label table, 4-6
options, 4-3, 4-4
program listing, 4-5
running, 4-2
DKED, 1-4, 3-1, 5-8
command response, 3-3
error messages, 3-9, 8-2
file extensions, 3-4
QUIT command, 3-1, 3-3, 3-4
REOPN command, 3-3
search mode, 3-5
wildcards, 3-5, 3-6
YANK command, 3-3
Duplicate key, 10-9
.D8L, 2-4
• DDF, 2-4
.DIR, 2-4
E

EDIT program, 10-10
END statement,
PRINTU, 9-15
SORT/MERGE, 11-13
EOF (end of file), 2-2
Error log file, 5-28
Error messages,
CTS-300 run-time system, A-2
DICOMP, 8-6
DDT, 8-13
DKED, 8-2
foreground/background
communications, 8-12
ISMUTL, 8-19
LPTSP1.REL, 8-14
LPTSPL.TSD, 8-15
monitor, 2-4
REDUCE, 8-24
SORTG, 8-20
SORTM, 8-22
STATUS program, 8-23

TSD, 8-11
Examining variables, see DDT
EXECUTE statement,
PRINTU, 9-6
SORT/MERGE, 11-13
Extended memory monitor (XM),
1-1, 1-2, 5-4
Extensions, default, 2-4, 10-24
External subroutine
cross-reference table
(DICOMP), 4-7
F

F8 monitor, 1-2
wi th SUD, 5-2
wi th TSD, 5-4
FCG, file control group, 10-4,
10-6
File,
conventions, 2-4
device name, 2-4
name, 2-4
extension, 2-4
sharing, 5-6
types, 2-4
Files,
checkpoint, 10-23, 10-34
control (PRINTU), 9-2, 9-3
control (SORT/MERGE), 11-2,
11-3
data, 2-5, 10-2, 10-4, 10-5
EOF (end of file), 2-5
index, 10-6 to 10-8
ISAM, see ISAM and ISMUTL
multivolume ISAM, 10-4
multivolume sequential, 2-5
object (DICOMP), 1-4, 4-1
random access, 2-5
sequential access, 2-5
source (DICOMP), 1-4, 4-1
FLAGS option, 2-5
Forced job startup, 5-12
specification in CTSGEN, 6-18
TSD printer spooler, 8-7
Foreground/background
communications (XMTSD), 5-16
to 5-26
commands, 5-18 to 5-21, 5-24
to 5-26
message record format, 5-21,
5-22
request codes, 5-22
response codes, 5-23, 5-24
user-created commands, 5-24 to
5-26

Index-3

INDEX (Cont.)
G

/G (DICOMP option), 4-3
Group (ISAM), 10-2, 10-4, 10-5,
10-11
Group, fill to end of block,
10-11
H
Handler,
LPTSPl.REL, 8-3
LPTSPL.TSD (XMTSD), 8-11
HEADl/HEAD2 statements (PRINTU),
9-5
HELP command,
DKED, 3-7
STATUS, 12-3

IDENT statement (PRINTU), 9-3,
9-4
Implicit job startup, 5-13
specification in CTSGEN, 6-18
TSD printer spooler, 8-8
Improperly defined symbols, 4-8
Index file, 10-2, 10-6 to 10-8
Index level, 10-6
. Indexed Sequential Access
Method, see ISAM
INDEX/LIST statement (PRINTU),
9-10, 9-11
Indirect fi1e(s),
foreground/background
communications, 5-17, 5-18
with ISAM auto-create, 10-40
INPUT statement,
PRINTU, 9-4, 9-7
SORT/MERGE, 11-3, 11-4
Interpretive program, 1-3
ISAM files, 1-5, 2-7, 10-1
access statements, see DI80L
ISAM access statements
advantages, 10-1
append area, 10-3, 10-5, 10-12
ba sic s , 10- 2 , 10- 3
data files, 10-2, 10-4, 10-5
data groups, 10-2, 10-4, 10-5,
10-11
data section, 10-2
data storage, 10-16 to 10-20
default file extensions, 10-24
duplicate keys, 10-9
example showing added records,
10-16 to 10-20
file control group, 10-4, 10-6
file efficiency, 10-11
handling added records, 10-2
4-Index

index file organization, 10-6
to 10-8
index section (file), 10-2,
10-6 to 10-8
input files, 10-23
key, 10-2, 10-9
links, 10-5
load exclusion factor, 10-2
locked block/record, 10-11
output files, 10-23, 10-24
overflow area, 10-2, 10-6,
10-12
record, 10-2, 10-9
record area, 10-4
sequential search, 10-2
specification in CTSGEN, 6-17
utility program, see ISMUTL
ISMUTL (ISAM utility program) ,
1-5, 10-1, 10-22
assignment of append area,
10-2
Auto-Create, 10-25, 10-40 to
10-42
changing record and key buffer
sizes, 10,10
CREATE function, see CREATE,
ISAM function
duplicate keys, 10-9
error messages, 10-42, 8-19
exiting ISMUTL, 10-38
fill to end of group, 10-11
REORG function, see REORG,
ISAM function
running, 10-22
STATUS and REORG in chain
mode, 10-38, 10-39
STATUS function, see STATUS,
ISAM function
using, 10-21
Iteration count, see DDT
• ISM, 2-4
K

Key, ISAM,
definition (ISAM), 10-2, 10-9
duplicate, 10-9
Keyboard commands, 2-1 to 2-3
Keyboard monitor (KMON), 2-1
Key sort (SORT/MERGE), 11-10,
11-11
KEYS statement, 11-4, 11-5
Kill option (STATUS utility),
12-4
K52 (editor), 3-1

INDEX (Cont.)
L
/L (DICOMP option), 4-4
Label cross-reference table
(DICOMP), 4-7
Label table listing (DICOMP),
4-6
Line number (DICOMP), 4-4
Line printer spooler program,
see LPTSPl.REL and
LPTSPL.TSD
Line printer spoolers, 1-4
Link map, 6-19
Linking, 1-4,
for DDT, 7-2
for the SUD run-time system,
5-3
for the TSD run-time system,
5-8
Links (ISAM), 10-5
Listing file, 4-2
LISTNR.SAV (XMTSD), 5-17, 5-18
termination, 5-32
LOAD command, 2-3
Load exclusion factor, 10-2
Locked blocks/records, 5-7
Log file (DICOMP), 4-3
Logical,
assignments, 2-3
names, 2-3
LPQFIL, 8-7
STATUS display, 12-5
LPQUE statement,
FORMS/ALIGN argument
(LPTSPl.REL), 8-4
FORMS/ALIGN argument
(LPTSPL.TSD), 8-9, 8-12
LPTSPl.REL,
error messages, 8-5, 8-14
error recovery, 8-5
handler, 8-3
requirements, 8-2
shared line printer, 8-2
shared terminal operation, 8-3
starting, 8.3
LPTSPL.!I'SD,
assignment of default
printers, 8-6
detached mode operation, 8-7,
8-8
error messages, 8-10, 8-12,
8-15
extended memory operation,
8-10
file recovery, 8-6
handl~rs (XMTSD operation) ,
8-11
interrupted or terminated
pr i nt, 8-9

requirements (TSD) , 8-6
requirements (XMTSD), 8-11
queue file (LPQFIL), 8-7
starting (TSD) , 8-7
starting (XMTSD), 8-11
startup dialog, 8-8
stopping (TSD), 8-9
stopping (XMTSD), 8-12
suspensiom ~f spooling, 8-6
• LST, 2-4
• LOG, 2-4
M

Manipulating variables, see DDT
Memory allocation,
SUD, 5-3
TSD, 5-15
XMTSD background, 5-30
XMTSD foreground, 5-27
Memory requirements,
SUD, 5-2
TSD/XMTSD, 5-5
MERGE, see SORT/MERGE
Mode,
DKED search, 3-5
input, 5-6, 5-7
no query (REDUCE), 13-2, 13-4
query (REDUCE), 13-2, 13-4
update, 5-6, 5-7, 5-14
version number (REDUCE), 13-2,
13-4
Model (DKED search), 3-5
Monitor error messages, 2-4
Monitors (RT-l1), 1-1, 1-2
see also SJ, F8, XM
Multivolume ISAM file, 10-4
.MAP, 2-4
N

/N (REDUCE option), 13-2
Name,
dev ice, 2-4
file, 2-4
log ical, 2-3
No query mode (REDUCE), 13-2,
13-4

o
/0 (DICOMP option), 4-4
Object file, 1-4, 4-1
ONERROR, 5-10
OPEN statement,
ISAM use, J.0-13
TSD use, 5':"6

Index-5

INDEX (Cont.)

Operating commands (RT-ll), 2-1
Operating system (CTS-300), 5-1
Output,
file (ISAM), 10-23, 10-24
file restrictions (ISAM),
10-23, 10-24
OUTPUT statement,
PRINTU, 9-3, 9-6
SORT/MERGE, 11-3, 11-5
Overflow area, 10-2, 10-6,. 10-12
Over 1 ays, 5-9
• 08J, 2-4
p

/P:N (DICOMP option), 4-4
(DKED), 3-5
PRINT command (XMTSD), 5-25
PRINT statement (PRINTU), 9-4,
9-13
Printer, see LPTSPl.REL and
LPTSPL. TSD
PRINTU utility, 1-5, 9-1
/IS option, 9-7, 9-8
/SU option, 9-7, 9-8
accumulation field, 9-2, 9-13,
9-14
break field, 9-2, 9-9
column separators, 9-14
COMPUTE statement, 9-12
control file, 9-2, 9-3, 9-15
END statement, 9-15
error messages, 9-17, 8-17
EXECUTE statement, 9-6
field description lines, 9-8,
9-9
file control records (as a
limitation), 9-1, 9-2
HEADI/HEAD2 statements, 9-5
IDENT statement, 9-3, 9-4
INDEX/LIST statement, 9-10,
9-11
INPUT statement, 9-4, 9-7
ISAM input file, 9-11
OUTPUT statement, 9-3, 9-6
PRINT statement, 9-4, 9-13
producing the report program,
9-15, 9-16
report program, 9-3, 9-17
required control statements,
9-2, 9-3
running, 9-16, 9-17
sorting input prior to using,
9-7
specification of input file at
run time, 9-8

6-Index

specification of output file
at run time, 9-7
summary print, 9-3, 9-8, 9-14
tag file, 9-3
tag file as input, 9-10 to
9-12
Production mode,
XMTSD as a background program,
5-30
XMTSD as a foreground program,
5-28
Program,
development, 1-4
development utilities, 1-4
execution, 2-3, 5-10, 5-16
listing (DICOMP), 4-5
schedul ing, 5-5
Prompt character,
RT-ll, 2-1
TSD, 5-15
XMTSD., 5-27
Q

Query mode (REDUCE), 13-2, 13-4
Queue file (LPQFIL), 8-7
Queue manager (8GMAN.TSD), 5-17
QUIT command (in DKED), 3-1,
3-3, 3-4
R

Random access, 2-5
R command, 2-3
READ statement (ISAM use), 10-14
READS statement (ISAM use),
10-14
RECORD statement (SORT/MERGE),
11-5
REDUCE utility, 1-5, 13-1
/N option, 13-2
/V option, 13-2
characteristics, 13-1
conventions, 13-2
error messages, 13-4, 8-24
examples, 13-3, 13-4
no query, 13-2, 13-4
query mode, 13-2, 13-3, 13-4
runni ng, 13-3
using, 13-2
version number, 13-2, 13-4
Relocatable image file, 2-4
Remote patching (XMTSD), 5-28
Removal of assignments, 2-3
RENAME command (XMTSD), 5-25
REOPN command, 3-3

INDEX (Cont.)

REORG, ISAM function, 10-33 to
10-37
characteristics, 10-34
dialog, 10-35
example, 10-36
in chain mode, 10-38, 10-39
possible REORG problems, 10-37
requirements, 10-34
RT-11 SYSGEN, see SYSGEN
RTEXIT,
absolute shutdown, 5-31
for XMTSD in the foreground,
5-32
run n i ng, 5- 31
RUBOUT, 2-2
RUN command, 2-3, 5-10
Run-time system, 1-1
• REL, 2-4

S
/S (DICOMP option), 4-4
Sequential access, 2-5
SET command, 2-3
SHOW co~mand (XMTSD), 5-20
Single buffering (DICOMP), 4-3
Single step, see DDT
Single-User DIBOL (SUD), 1-3
DIBOL code interpreter, 5-2
linking for DDT, 5-3
memory allocation, 5-3
preparing programs, 5-2
running, 5-3
system requirements, 5-2
wi th DDT, 5-2
wi th ISAM, 5-2
Single user print spooler, see
LPTSP1.REL
Shared line printer operation
(LPTSP1.REL), 8-2
Shared terminal operation
(LPTSP1.REL), 8-3
SHOW command (XMTSD), 5-20
SJ monitor, 1-2
wi th SUD, 5-2
wi th TSD, 5-4
Sort control record
(SORT/MERGE), 11-17, 11-18
opcode, 11-1 7
SORTG, 1-5, 11-1, 11-14
error messages, 8-20
SORTM, 1-5, 11-1, 11-14
error messages, 8-22
SORT/MERGE, 1-5, 11-1
chaining to another program,
11-8, 11-16 to 11-18
chain mode, 11-16 to 11-18

characteristics, 11-1, 11-2
compiling, 11-14
control file, 11-2 r 11-3
control key(s), 11-6
control statements, 11-2 to
11-13
count argument, 11-3. 11-4
detached SORT/MERGE operation,
11-7
DETACH statement, 11-7
error messages, 11-18, B-20,
B-22
END statement, 11-13
example, 11-15, 11-16
EXECUTE statement, 11-8
field definition, 11-5, 11-6
INPUT statement, 11-3, 11-4
KEYS statement, 11-4, 11-5
limitations r 11-2
1 inK r ng, 11-1 6
~~rge specification, 11-3,
11-4
OUTPUT statement, 11-3, 11-5
overriding the EXECUTE
statement, 11-16, 11-17
RECORD statement, 11-5
required control statements,
11-2, 11-3
r un n i ng, 11-15
single-user operation, 11-9,
11-10
SORT/MERGE program
development, 11-14 to 11-16
SORTG, 11-14
sorting with keys only, 11-10,
11-11
SORTM, 11-14
SPACE statement (SORT/MERGE),
11-8, 11-9
specifying a descending order
sort, 11-7
specifying memory available
for SORT/MERGE, 11-8, 11-9
specifying work files, 11-11,
11-12
summary of control file
statements, 11-13
SU statement, 11-9, 11-10
TAGS: INDEX, 11-11
TAGS: LIST, 11-10, 11-11
TAGS:SORT, 11-10
tags sort, 11-5
tags sort with ISAM file as
input, 11-11
TAGS statement, 11-11, 11-12
WORK statement, 11-11, 11-12
Source code file, 4-1
Index-7

INDEX (Cont.)

SPACE statement (SORT/MERGE),
11-8, 11-9
Special character functions, 2-1
Spooler, see LPTSPl.REL and
SPTSPL.TSD
Standard listing (DICOMP), 4-5
Stan9ard terminal, specification
1 n CTSGEN, 6-9
STATUS, ISAM function, 10-32,
10-33
exampl e, 10- 33
in chain mode, 10-38, 10-39
STATUS utility, 1-5, 12-1
available memory, 12-2
conventions, 12-2
error messages, 12-7, B-23
ex i ti ng, 12-6
features, 12-1
job list, 12-3
kill job, 12-4
line printer output selection,
12-6, 12-7
list of options, 12-3
message queue, 12-5, 12-6
option F, 12-2
option H, 12-3
option J, 12-3
option Jx, 12-4
option Kx, 12-4
option L, 12-5
option Lx, 12-5
option M, 12-5
option T, 12-6
option X, 12-6
print queue by printer, 12-5
print queue list, 12-5
specific job information, 12-4
TSD or XMTSD RTS operating
parameters, 12-6
usi ng, 12-6, 12-7
STORE statement, 10-15
Stored messages, 6-16
SUBMIT command (XMTSD), 5-19
SUBMIW command (XMTSD), 5-26
Subroutine traceback,· see DDT
SUD, see single user DIBOL
SUDGEN, see CTSGEN
SUD.RTS, 5-2, 6-9
Suspension of spooling, 8-6
Symbol cross-reference table
listing (DICOMP). 4-7
Symbol table listing (DICOMP)
4-5
'
Symbols, improperly defined, 4-8
SYSGEN, 1-4, 5-1, 5-14, 6-2 (
System conventions, 2-4
System development, 1-4
8-Index

SYSTEM.BKG (XMTSD), 5-18
SUBMIT command (XMTSD), 5-19
.SAV, 2-4
• SYS, 2-4
T

TAGS statement (SORT/MERGE),
11-11, 11-12
Temporary files, 2-4, 10-24,
10-34
Terminals,
specification in CTSGEN, 6-10
to 6-16
shared (LPTSPl.REL), 8-3
Terminating spooling
(suspension), 8-6
TIME command, 2-3
Time-shared DIBOL, 1-3, 5-4
capabilities, 5-4
commands, 5-9 to 5-11
common data base, 5-6
creating overlays, 5-9
data file management, 5-6
detached program operation,
5-6
device sharing, 5-7
dynamic memory allocation, 5-5
error detection, 5-4, 5-33
error messages, 5-33, B-11
file management, 5-6
file sharing, 5-6
linking for DDT, 5-9
linking programs, 5-8
locked blocks/records, 5-7
program preparation, 5-8
program scheduling, 5-5
programmed startup, 5-11 to
5-13
running programs, 5-10, 5-16
scheduling, 5-5
stopping programs, 5-14
system requirements, 5-5
utilizing resources, 5-32,
5-33
Time sharing, 1-3
Traceback, see DDT
TSD, see time-shared DIBOL
TSD run-time system,
memory allocation, 5-15
system requirements, 5-14,
5-15
r unn i ng, 5-15
termination, 5-31
TSDGEN, see CTSGEN
TYPE command (XMTSD), 5-25
• TMP, 2-4
• TSD, 2-4

INDEX (Cont.)
U

as a foreground program, 5-16
to 5-28
background listener program
(LISTNR.SAV), 5-17, 5-18
BGMAN.TSD operation, 5-18
communication commands, 5-18
to 5-21, 5-24 to 5-26
foreground queue program
(BGMAN.TSD), 5-17
indirect files, 5-17, 5-18
memory allocation as a
background program, 5-30
memory allocation as a
foreground program, 5-27
program execution, 5-16
running in the background,
5-29
running ih the foreground,
5-26, 5-27
running LISTNR.SAV, 5-27
system requirements, 5-16
termination of LISTNR.SAV,
5-32
termination (RTEXIT), 5-31,
5-32
timing facility, 5-17
user-created commands, 5-24
virtual overlays, 5-16

UNLOAD command, 2-3
UNLOCK statement,
ISAM use, 10-16
TSD use, 5-7
User-created commands, 5-24
User service routine (USR), 5-33
specification in CTSGEN, 6-17
Utility programs, 1-4, 1-5

v
/V (REDUCE option), 13-2
Variable manipulation, see DDT
VIEW command (XMTSD), 5-26
Virtual overlays, 5-16

w
/W (DICOMP option), 4-4
Wildcards (DKED), 3-5, 3-6
WORK statement (SORT/MERGE),
11-11, 11-12
WRITE statement (ISAM use),
10-15
X

XM monitor, 1-2
wi th SUD, 5-2
wi th TSD, 5-4
XMTSD run-time system,
applications as a background
prog ram, 5-30
applications as a foreground
prog ram, 5-28
as a background program, 5-29

y
YANK command, 3-3

Index-9

CTS-300 System User's Guide
AA-C747C-TC
READER'S COMMENTS

NOTE:

This form is for document comments only. DIGITAL will
use comments submitted on this form at the company's
discretion. Problems with software should be reported
on a Software Performance Report (SPR) form. If you
require a written reply and are eligible to receive
one under SPR service, submit your comments on an SPR
form.

Did you find errors in this manual?

·
.5
Q)

If so, specify by page.

Did you find this manual understandable, usable, and well-organized?
Please make suggestions for improvement.

Is there sufficient documentation on associated system programs
required for use of the software described in this manual? If not,
what material is missing and where should it be placed?

Please indicate the type of user/reader that you most nearly represent.

o Assembly language programmer
o Higher-level language programmer
o Occasional programmer (experienced)
o User with little programming experience
o Student programmer

o Non-programmer interested in computer concepts and capabilities
Name

Date __________________________

Organization _______________________________________________________________
Street ___________________________________________________________________
City __________________________

Code ______________
or
Country

St~te-------------Zip

I
- -

-Do Not Tear - Fold Here and Tape -

- - - - -

----1

~DmDDmallllll

No Postage
Necessary
if Mailed in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

DIGITAL EQUIPMENT CORPORATION
Applied Commercial Engineering MK1-2/H32
Continental Boulevard
Merrimack N.H. 03054

ATTN: Documentation Supervisor

I
Do Not Tear - Fold Here and Tape -

--,I