Google
 

Trailing-Edge - PDP-10 Archives - BB-L665A-BM - documentation/rmsref.mem
There are 10 other files named rmsref.mem in the archive. Click here to see a list.












                           TOPS-10/TOPS-20


                         RMS Reference Manual


                              Version 1






The information in this document is subject to change  without  notice
and  should  not  be  construed  as  a commitment by Digital Equipment
Corporation.

Actual distribution of the software  described  in  this  document  is
subject to terms and conditions to be announced in some future date by
Digital Equipment Corporation.

DIGITAL assumes no responsibility for the use or  reliability  of  its
software  on  equipment  which  is  not  supplied  by  DIGITAL  or its
affiliated companies.

This software is furnished to purchaser under a license to  use  on  a
single  computer system and can be copied (with inclusion of DIGITAL's
copyright notice) only for use in such system, except as may otherwise
be provided in writing by DIGITAL.


 ***COPYRIGHT 1980, 1981, DIGITAL EQUIPMENT CORP., MAYNARD, MASS.***
                                                                Page 2









                               CONTENTS



                                                                 Page


CHAPTER  1       OVERVIEW OF RMS                                 1-1  

         1.1     OVERVIEW OF RECORD MANAGEMENT                   1-1  
         1.2     INTRODUCTION TO RMS                             1-1  
         1.3     RMS FACILITIES                                  1-2  
         1.4     RMS CONCEPTS                                    1-3  

CHAPTER  2       PROPERTIES OF RMS RECORD FILES                  2-1  

         2.1     SEQUENTIAL FILES                                2-1  
         2.2     RELATIVE FILES                                  2-2  
         2.2.1     Sequential Access To Relative Files           2-3  
         2.2.2     Random Access To Relative Files               2-3  
         2.3     INDEXED FILES                                   2-3  
         2.3.1     Sequential Access To Indexed Files            2-4  
         2.3.2     Key Access To Indexed Files                   2-4  
         2.3.2.1   Key Matches                                   2-4  
         2.3.2.2   Key Content                                   2-5  
         2.3.3     Indexes                                       2-5  
         2.3.4     Format Of A Record File Address (RFA) In           
                   An Indexed File                               2-8  
         2.4     INDEXED FILE EFFICIENCY                         2-8  
         2.4.1     Key Access Efficiency                         2-8  
         2.4.1.1   Determining Number Of Levels                  2-8
         2.4.1.2   Shaping Your Index                            2-10 
         2.4.2     Write Access Efficiency                       2-10 

CHAPTER  3       RMS FILE MANAGEMENT UTILITY                     3-1  

         3.1     RULES OF OPERATION                              3-1  
         3.1.1     Command Format                                3-1  
         3.1.2     Command Status                                3-2  
         3.2     CREATING A FILE                                 3-3  
         3.3     FILE MANIPULATION                               3-3  
         3.4     MANIPULATING DATA IN A FILE                     3-3  
         3.5     FILE SCANNING                                   3-4  
         3.6     COMMAND DESCRIPTIONS                            3-5  
         3.6.1     CHANGE Command                                3-7  
                                                                Page 3


                           CONTENTS (CONT.)



                                                                 Page

         3.6.2     CLOSE Command                                 3-10 
         3.6.3     DEFINE DATAFIELD Command                      3-11 
         3.6.4     Defining File Attributes And The DEFINE            
                   FILE Command                                  3-13 
         3.6.5     DELETE Command                                3-16 
         3.6.6     DISPLAY Command                               3-17 
         3.6.7     FIX Command                                   3-19 
         3.6.8     INFORMATION Command                           3-20 
         3.6.9     OPEN Command                                  3-21 
         3.6.10    REDEFINE Command                              3-23 
         3.6.11    SET Command                                   3-24 
         3.6.12    SPACE Command                                 3-27 
         3.6.13    UNCLUTTER Command                             3-28 
         3.6.14    VERIFY Command                                3-29 
         3.6.15    Secondary Commands                            3-31 
         3.7     RECORDS-TO-USE CLAUSE                           3-32 
         3.8     THE REPORT FILE                                 3-33 
         3.8.1     DISPLAY OUTPUT                                3-33 
         3.8.2     File-Scanning Output                          3-34 

CHAPTER  4       FORMAT OF AN RMS RECORD FILE                    4-1  

         4.1     PROLOGUE SECTION                                4-1  
         4.1.1     File Descriptor For File Argument Block            
                   (FAB)                                         4-1  
         4.1.2     Key Descriptor For Extended Argument Block         
                   (XAB)                                         4-2  
         4.2     DATA SECTION OF SEQUENTIAL AND RELATIVE              
                 FILES                                           4-4  
         4.3     DATA SECTION OF AN INDEXED FILE                 4-5  
         4.3.1     Bucket Headers                                4-6  
         4.3.2     Entries in a Primary-Data Bucket              4-6  
         4.3.3     Entries in an Index Bucket                    4-7  
         4.3.4     Entries in a Secondary-Data Bucket            4-8  

CHAPTER  5       RMS STATUS CODES                                5-1  

APPENDIX A       USAGE OF AN RMS FILE FROM BOTH BASIC+2 AND           
                 COBOL-74                                        A-1  

INDEX                                                        Index-1  
                                                                Page 4


                               FIGURES


FIGURE   2-1        Sequential File Organization                2-1
         2-2        Relative File Organization                  2-2
         2-3        Storage of Keys in an Indexed File          2-6
         2-4        Buckets in Indexed Files                    2-7
         4-1        RMS Record File Format                      4-5


                                TABLES


TABLE    5-1        RMS Status Codes                            5-2
         5-2        STV Values for ER$UDF                       5-9
                                                                Page 5














                               PREFACE



The TOPS-10/TOPS-20 RMS Reference Manual is:

         o  An introductory manual to illustrate basic  file  concepts
            and their application to Record Management Services (RMS).

         o  A reference manual to define the components  of  RMS,  its
            relationship   with   user   written  programs  (COBOL-74,
            BASIC+2), and descriptions of RMSUTL commands.

The information in this document is organized as follows:

         o  Chapter 1 provides an overview of RMS, its facilities, and
            its concepts.

         o  Chapter 2 provides a description of the properties of  RMS
            files.

         o  Chapter  3  provides  a  description  of  the   RMS   file
            management utility, RMSUTL, and the use of this utility to
            create and access RMS files.

         o  Chapter 4 provides descriptions of the sections within RMS
            files, based on their organization.

         o  Chapter 5 provides descriptions of all RMS status codes.

         o  Appendix A provides the rules for using an RMS  file  from
            both BASIC-PLUS-2 and COBOL-74.


RMS  provides  record  management  for  COBOL-74  (Version  12B)   and
BASIC-PLUS-2  (Version  2.1)  (TOPS-20  only).   COBOL-74  programmers
should reference the COBOL-74 Language Reference Manual (AA-5059B-TK).
BASIC-PLUS-2  programmers  should  reference  the TOPS-20 BASIC-PLUS-2
Language  Manual  (AA-H654A-TM).   Both  of  these   manuals   provide
additional information on creating and maintaining RMS files.
                                                                Page 6


If you find any errors in this manual, please write them on a separate
sheet of paper and address it to:

               DIGITAL EQUIPMENT CORPORATION
               Software Documentation
               200 Forest Street
               MR1-2/L12
               Marlborough, Massachusetts 01752

All reported errors will be corrected as soon as possible.



                   Conventions Used In This Manual



     Symbol                   Meaning



     <RET>        Press the key labeled RETURN or CR.

     <ESC>        Press the key labeled ESC, ESCAPE, ALT, or PRE.

     <CTRL/C>     Press the keys labeled CTRL and C simultaneously.











                              CHAPTER 1

                           OVERVIEW OF RMS



1.1  OVERVIEW OF RECORD MANAGEMENT

As a user writing application programs, you need  to  create  programs
that will do some or all of the following:

     1.  Accept new input

     2.  Read or modify data

     3.  Produce output in some meaningful form

RMS provides generalized routines that are useful to  you  in  writing
such programs.



1.2  INTRODUCTION TO RMS

RMS is a file/record management system for TOPS-10/TOPS-20 (KL and KS)
systems.   It  provides  an interface between the operating system and
user-developed application programs.  User programs can be written  in
COBOL-74 or BASIC-PLUS-2 (TOPS-20 only).

The RMS functions available from COBOL-74 are only those  that  result
from  support of multikey indexed files in Level-2 ANSI COBOL-74.  The
COBOL compiler and OTS automatically do the RMS setup  operations  and
calls  needed  to  support the RMS-based language features.  Thus, the
primary reference  document  for  COBOL  programmers  wishing  to  use
multikey  indexed files is the COBOL-74 Language Reference Manual.  In
particular, these users should see Appendix I, Using Multikey  Indexed
Files.

As with COBOL,  BASIC  and  BASOTS  automatically  do  the  RMS  setup
operations   and  calls  needed  to  support  the  RMS-based  language
features.  Additionally  all  RMS  file  organizations  are  available
through BASIC-PLUS-2.
OVERVIEW OF RMS                                               Page 1-2


RMSUTL is an interactive file management utility.  With  it,  you  can
examine  and  patch  your  RMS  files.   You  can also define a file's
properties and create it using RMSUTL.  (Refer  to  Chapter  3  for  a
detailed description of RMSUTL.)



1.3  RMS FACILITIES

RMS provides a wide range  of  facilities.   The  file  operations  it
provides are:

     1.  Create file

     2.  Open existing file

     3.  Close file

     4.  Delete file

     5.  Truncate file (TOPS-20 only)

Stream files and record files are supported.  Stream files  are  ASCII
text  files,  with or without line-sequence numbers.  Record files may
be sequential, relative, or multikey indexed,  and  are  described  in
more detail in Chapter 2.

The record operations RMS supports are:

     1.  Put (create) record

     2.  Find and get record

     3.  Find record

     4.  Update existing record

     5.  Delete record

The access methods by which you can find a record are:

     1.  Sequential

     2.  Relative record number

     3.  Random by key (a value in a record)

However, some operations and access methods cannot be applied  to  all
file organizations (see Chapter 2).
OVERVIEW OF RMS                                               Page 1-3


1.4  RMS CONCEPTS

Access Mode -- The  method  in  which  data  records  in  a  file  are
retrieved.   The  access  modes  supported  by  RMS are sequential and
random.

Area -- An area is a region of a file with a particular  bucket  size.
Thus,  all  RMS  files  consist  of  (at least) one area.  For indexed
files, you may declare additional areas.

Bucket -- Data in an RMS file is organized into buckets.  A bucket  is
the unit of physical I/O RMS uses.  When RMS reads or writes a record,
it actually reads or writes the bucket(s) containing  the  record.   A
bucket  consists  of one or more file pages (= 512 words).  At present
however, multipage buckets can only be declared for indexed files.

Entry -- The data objects in  a  bucket  are  called  entries.   Thus,
records  are  one  type of entry.  Entries are numbered, and the entry
with the lowest offset in a bucket is entry 1.  Entry numbers are  not
names;   if  entry 3 is expunged from a bucket, then entry 4 "becomes"
entry 3.

File Organization -- The physical arrangement of  records  in  a  file
when  it  is created.  File organizations can be sequential, relative,
or multikey indexed.

ID -- A per-bucket unique ID is associated  with  each  record  in  an
indexed file.  RMS assigns IDs in ascending sequence, starting with 1,
as records are put in a bucket.

Prologue -- The beginning of an RMS record file is called its prologue
section.  It is the repository of the file's attributes.

Random Access -- An access mode in which the  program-specified  value
of  a  key  data  item  identifies  the  logical  record that is to be
accessed in a relative or indexed file.

RFA -- When RMS puts a record in a file, it assigns it a "Record  File
Address" (RFA).  You may think of an RFA as the physical location of a
record.  RMS guarantees that no other record  will  be  assigned  this
location while the file remains open.

Sequential Access -- With  sequential  access,  you  do  not  directly
identify  the  record  you  wish  to  access.  Instead RMS chooses the
logical next record.  Initially, when the file is opened, the  current
record  is  the first record in the file.  Also, except for sequential
files, it can be reset by a random access.











                              CHAPTER 2

                    PROPERTIES OF RMS RECORD FILES



TOPS-10/TOPS-20 RMS supports a variety of file  organizations,  record
access  modes,  and  record  formats.   The  specific  use of the file
determines which file organization is best.  The sections that  follow
describe the meanings of each of the above items.

Each file organization has unique properties.  However, there are some
properties common to all record files.

     o    Sequential access is supported.

     o    Records can be deleted and/or updated.

     o    RMS assigns each record a record file address (RFA).

     o    A header is stored with each record.

     o    File has prologue.



2.1  SEQUENTIAL FILES

In sequential file organization, records appear in the order in  which
they were written to the file.


     -------------------------------------------------------------
     |         |         |         |         |         |         |
     | First   | Second  | Third   | Fourth  | Fifth   | Sixth   |
     | Record  | Record  | Record  | Record  | Record  | Record  |
     |         |         |         |         |         |         |
     -------------------------------------------------------------


               Figure 2-1 Sequential File Organization


Thus, you can only add records to a sequential file at the current end
of the file.
PROPERTIES OF RMS RECORD FILES                                Page 2-2


Only sequential access can be used in a sequential file, and  physical
adjacency  establishes  the order in which RMS reads data records.  In
particular, if you sequentially access a record in the file, the  next
record is the physically following record.

When you update an existing record in a sequential  file,  you  cannot
change the length of the record.



2.2  RELATIVE FILES

Relative file  organization  consists  of  a  series  of  fixed-length
positions  (or  cells)  that  are  consecutively numbered from 1 to n.
Position 1 is at the beginning of the file.  Position 2 is  next,  and
so on.  The number of a record is called its relative record number.

                      Relative Record Numbers
                                 |
                                 |
          ---------------------------------------------------
          |         |         |         |         |         |
          |         |         |         |         |         |
          1         2         3         4         5         6
          |         |         |         |         |         |
          |         |         |         |         |         |
          V         V         V         V         V         V
     -------------------------------------------------------------
     |         |         |         |         |         |         |
     | Third   | Empty   | Second  | First   | Fourth  | Fifth   |
     | Record  | Cell    | Record  | Record  | Record  | Record  |
     | Written |         | Written | Written | Written | Written |
     |         |         |         |         |         |         |
     -------------------------------------------------------------


                Figure 2-2 Relative File Organization


This method of file organization is available on disk drives only.

Although each record in a relative file is assigned to a  fixed-length
cell,  the actual size of an individual record can be smaller than the
cell size.  Different size records can be in the same file.

Relative file organization allows  sequential  and  random  access  of
records.  The relative record number of a record in a relative file is
the key value in random-access mode.
PROPERTIES OF RMS RECORD FILES                                Page 2-3


2.2.1  Sequential Access To Relative Files

When you use sequential-access mode in a relative file, physical order
establishes the order in which RMS reads and writes data records.

RMS recognizes whether record cells  are  empty  or  contain  records.
When  a  program  issues read requests in sequential-access mode for a
relative file, RMS  searches  successive  cells  until  it  finds  one
containing a record.

When a program  adds  new  records  in  sequential-access  mode  to  a
relative  file,  the  records  are  written to ascending relative cell
numbers.  Each write operation causes RMS to place  a  record  in  the
cell  whose  record number is one higher than the record number of the
previous write operation.  If the cell already contains a record,  RMS
rejects the write operation and returns an error.



2.2.2  Random Access To Relative Files

In random-access  mode,  your  program,  not  the  file  organization,
determines  the order in which record processing occurs.  Each program
request for a record must include the  key  value  of  the  particular
record to be accessed.

When you use random-access mode in a relative file,  you  specify  the
relative  record  number of the object record.  If no record exists in
the specified cell on  a  retrieval  request,  RMS  returns  an  error
indicator  to  the  requesting  program.   Similarly,  a  program  can
randomly store records in a relative file by identifying the  cell  in
the  file  that  a  record  is to occupy (see Figure 2-2).  If a write
operation specifies the relative record number of a cell that contains
a record, RMS returns an error indicator to the program.

One method of keeping track of each record's cell is to store  records
based  on  a numeric value within the record.  For example, an account
number could be equivalent to the relative record number.



2.3  INDEXED FILES

An indexed file is a file in which a record can  be  randomly  located
using arbitrary value(s) in the record.  A portion of a record defined
for this purpose is called a key.  An indexed  file  is  distinguished
from  a  hashed-key  file  by  the fact that the records are logically
sorted by each key as well.

An RMS indexed file has at least one  key,  called  the  primary  key.
Optionally  up  to  255 "secondary" keys can also be defined.  This is
referred to as a multikey indexed file.  You describe keys to RMS just
once,  when  the  file is created.  RMS places the key descriptions in
the file's prologue, and thereafter uses the stored  key  descriptions
to support usage of the keys.
PROPERTIES OF RMS RECORD FILES                                Page 2-4


2.3.1  Sequential Access To Indexed Files

When you use sequential-access mode in an indexed file,  the  key  you
choose  establishes  the  order  in which RMS presents data records to
your  program.   If  a  series  of  sequential  reads  is  done,  each
successive  record contains a value in the specified key field that is
equal to or greater than that of the previous record.  The chosen  key
is called the "key-of-reference".

When you write records in  an  indexed  file  using  sequential-access
mode,  the  primary  keys  in  the  records must be presented in ASCII
ascending order.  If the keys are not in ascending order, an error  is
returned to your program.



2.3.2  Key Access To Indexed Files

To do a key access, you specify a key of reference and  a  key  value.
When RMS finds a matching key value in the specified index, it locates
the associated user data record and passes  the  record  to  the  user
program.  If there are multiple records containing the same key value,
the key access always finds the one that was written first.  To access
the other records with the duplicate key value, you must do sequential
accesses.

In contrast to read requests, program requests to write records in  an
indexed  file do not require the separate specification of a key value
or index.  This is because all the record's keys must be  inserted  in
their  respective  indexes.   In this way, RMS insures that the record
can later be retrieved by any of its key values.



2.3.2.1  Key Matches - The key value specified on a key access can  be
tailored  to different circumstances.  RMS supports the following four
types of key matches:

     1.  Exact key match

     2.  Approximate key match

     3.  Generic key match

     4.  Approximate generic key match

Exact key match means that RMS returns an  error  unless  there  is  a
record  in the file whose key precisely matches the value specified in
your program.

The approximate match facility allows your program to select either of
the  following  two  relationships  between  the  key  of  the  record
retrieved and the key value specified by your program:
PROPERTIES OF RMS RECORD FILES                                Page 2-5


     1.  Equal to or greater than

     2.  Greater than

The advantage of the first kind of match is that if the specified  key
value does not exist in any record of the file, RMS returns the record
that contains the next higher key value.  The  second  kind  of  match
specifies  that  the record with the next higher key value is returned
even if a record with the specified key value exists.  You  would  use
this  type  of  match if you were sequentially processing the file and
wanted to bypass the records whose key values  equalled  the  one  you
have in hand.

Generic key match means that the program  needs  only  to  specify  an
initial  portion  of  the  key value.  RMS returns to your program the
first occurrence of a record whose key  value  begins  with  what  you
specified.

Approximate  generic  key  match  combines  the   second   and   third
techniques.   For  example,  if  "AAAAA" and "ZZZZZ" are the keys in a
file, specifying "BB" will locate the record that  has  "ZZZZZ"  as  a
key.



2.3.2.2  Key Content - A key value in a record is a specific series of
bytes  within  the  record.  A key must have the same byte size as the
file, and an indexed file may have byte sizes of  6,  7,  or  9.   Key
location  and  byte  size are both established when an indexed file is
created.

The series of bytes comprising a key value may be composed of up to  8
key-segments and may be as long as 255 characters.  Multi-segment keys
are useful when you wish to sort the records of a file upon more  than
one  logical  field.   For  example,  suppose you wish to periodically
print a file of car records sorted by make, model, and year  of  make.
This  can be done by a sequential scan if you have defined a 3-segment
key whose key-segments are respectively make, model, and year of make.



2.3.3  Indexes

Buckets in an indexed file are linked together  into  trees.   Such  a
tree  is  called  an  index.   RMS maintains an index for each key you
define for an indexed file (see Figure 2-4).

Each level of an index contains entries sorted on the index's key, and
buckets  further  from  the  root  contain  key values that are closer
together.  This increase in detail continues to the leaf  level  where
every key value in the file appears (see Figure 2-3).
PROPERTIES OF RMS RECORD FILES                                Page 2-6






                         Root Bucket
                       (Primary Index)
                
               -------------------------------
               |         |         |         |
               |  ADAM   |  * * *  |  JASON  |
               |         |         |         |
               -------------------------------
               |                   |
               |                   |
----------------                  --
|                                 |
|   Data Bucket 1                 |   Data Bucket n
V                                 V
-------------------------------   -------------------------------
|         |         |         |   |         |         |         |
|  ARRON  | * * * * |  ADAM   |   |  JOHNS  | * * * * |  JASON  |
| WEST ST |         | ELM ST  |   | EAST ST |         | MAIN ST |
|  01347  |         |  21000  |   |  30306  |         |  45591  |
|         |         |         |   |         |         |         |
-------------------------------   -------------------------------

<-------------------------DATA RECORDS-------------------------->


            Figure 2-3 Storage of Keys in an Indexed File



When you do a key access, RMS moves from the  root  towards  the  leaf
level.   RMS  starts  by  scanning the root bucket for the first entry
whose key value is greater than or equal to the key value you want  to
access.  When RMS finds this entry, RMS continues the scan at the next
level.  This process continues until the scan reaches the data  level.
Thus, the cost of a key access is proportional to the number of levels
in an index rather than the number of records in the file.
PROPERTIES OF RMS RECORD FILES                                Page 2-7


                         ------------                       <-----
                         |          |                            |
                         |   ROOT   |                            |
                         |          |                            |
                         ------------                            |
                               |                                 |
                               |                                 |
                               |                                 |
               --------------------------------                  |-Index
               |                              |                  | Buckets
               |                              |                  |
               |                              |                  |
       -----------------              -----------------          |
       |               |              |               |          |
       | Intermediate  |              | Intermediate  |          |
       |     Index     |              |     Index     |          |
       |    Bucket     |              |    Bucket     |          |
       |               |              |               |          |
       -----------------              -----------------     <-----
               |                              |
               |                              |
               |                              |
       -----------------               -----------------
       |               |               |               |
       |               |               |               |
       |               |               |               |
 -------------   -------------   -------------   -------------  <--
 |           |   |           |   |           |   |           |    |
 |   LEAF    |   |   LEAF    |   |   LEAF    |   |   LEAF    |    |-Data
 |           |   |           |   |           |   |           |    | Buckets
 -------------   -------------   -------------   -------------  <--


                Figure 2-4   Buckets in Indexed Files



                                 NOTE

               The root of the tree is  "up,"  and  the
               leaves of the tree are "down."


There are three types of buckets in indexed files:

     1.  Index buckets are the buckets that  constitute  all  but  the
         leaves of an index.

     2.  Secondary-data buckets are the buckets that  are  leaves  for
         secondary  key  indexes.  Entries in these buckets are called
         SIDRs.
PROPERTIES OF RMS RECORD FILES                                Page 2-8


     3.  Primary-data  buckets  are  the  buckets  that  contain  your
         records.   Thus,  they  are  the  leaves of the primary key's
         index.




2.3.4  Format Of A Record File Address (RFA) In An Indexed File

The physical location of a record in  an  indexed  file  is  specified
relative to the bucket that contains it.  Specifically, a record's RFA
is the starting page of the  record's  bucket  combined  with  its  ID
within the bucket.

An indexed file RFA is graphically represented as p1/i1, where  p1  is
the  starting  page  of the record's bucket and i1 is the record's ID.
For example, the first record put in a file is often assigned the  RFA
2/1  (because  page 0 is the prologue and page 1 is the root bucket of
the primary index).



2.4  INDEXED FILE EFFICIENCY

2.4.1  Key Access Efficiency

The efficiency of a key access in an indexed file is a function of how
many  levels there are in the index.  Thus, there is a large change in
random access time when the number of levels  changes.   For  a  given
number  of records, the number of levels is a function of how full the
buckets  are  and  the  number  of  entries  that  fit   per   bucket.
Specifically,  the  number of records that fit in an index of n levels
is described in the following section.



2.4.1.1  Determining Number Of Levels - You can determine  the  number
of  records  that  fit  in an index of L levels by using the following
formula:


                         DF/R * ((IF/K) **L)


where:

     D   =     Words per data bucket - 3 words of overhead

     F   =     Average fullness of bucket (for example, 1/2)
PROPERTIES OF RMS RECORD FILES                                Page 2-9


               If you do a lot of random writes,  you  can  expect  an
               average  on  the  order  of  half-full.   If you mostly
               retrieve from a file loaded from  a  sorted  sequential
               file,  you can expect an average that is close to full.
               Characteristics between these extremes lead to fullness
               factors between half-full and full.

     I   =     Words per index bucket - 3 words of overhead

     K   =     Words per key + 1 word of overhead

     L   =     Number of levels

     R   =     Average number of words per record + O (overhead)

     O   =     2 (If the record format is fixed-length records)

     O   =     3 (If the record format is variable-length records)


                                        NOTE

                   For a secondary key, R is approximately 2 + K +
                   average number of write operations per record.


For example:

     D   =     509 (512 words/data bucket -3)

     F   =     0.8 (Average fullness of bucket)

     I   =     509 (512 words/index bucket -3)

     K   =     3 (for example, 10 character ASCII key plus overhead)

     L   =     2 (number of levels)

     R   =     50 (Average number of words/record plus overhead)

     DF/R=     8 (Records/data bucket)

     IF/K=     135 (Keys/index bucket)

     MAX =     153000 (Maximum records that fit on 2 levels)

Thus, with 2 index levels, you can  store  153000  records.   If  each
bucket  were  half  full (F = 0.5), the maximum number of records that
will fit on 2 levels is 26244.  If each bucket were full (F = 1),  the
maximum  number  of  records  that fit on 2 levels is 285610, over ten
times greater than half full.
PROPERTIES OF RMS RECORD FILES                               Page 2-10


2.4.1.2  Shaping Your Index - Shaping your index effectively  involves
having  certain  data  and  making  certain  trade-offs.  You need the
following pieces of data:

     1.  The number of records that will eventually be in the file.

     2.  The number of records you plan to initially load.

     3.  The values of D, F, I, K, and R.

     4.  The frequency with which you do writes and deletes.

Aside from shrinking your records and  keys,  your  primary  tool  for
minimizing levels in an index is increasing F.  You can improve F over
time in two ways:

     1.  Sort the records in the initial load of the file, and

     2.  Periodically reload or UNCLUTTER a heavily updated file.

Bucket splitting occurs when you add more records than the bucket  can
hold.  You can control bucket splitting in two ways:

     1.  During  initial  load  of  the  file.   Set   data-fill   and
         index-fill  divided  by  bucket  size equal to initial record
         count  divided  by  eventual  record  count.   Data-fill  and
         index-fill  are  defined  with  the  /DAFILL:   and  /IAFILL:
         switches in the RMSUTL DEFINE  command.   (Refer  to  Section
         3.6.4 for a description of these two switches.)

     2.  Periodically  UNCLUTTER  or  reload  the  file.   The  RMSUTL
         UNCLUTTER command is described in Section 3.6.13.

If your file is on a TOPS-10 and you pre-allocate the  file,  you  can
also make D or I greater than one page.



2.4.2  Write Access Efficiency

Write efficiency depends on three factors of decreasing importance.

     1.  The number of secondary keys.  An  additional  secondary  key
         linearly increases the cost of each write operation.

     2.  The number levels in an index.  This has the same  effect  as
         for key accesses.

     3.  Likelihood of bucket splitting.  A bucket split adds 2 bucket
         writes to a write operation.











                              CHAPTER 3

                     RMS FILE MANAGEMENT UTILITY



The RMS file management utility, RMSUTL, is an interactive utility for
creating and manipulating RMS index files.




3.1  RULES OF OPERATION

To use RMSUTL, type RMSUTL (for TOPS-20) or R  RMSUTL  (for  TOPS-10).
RMSUTL  responds  with  RMSUTL>,  and  you  may  now  enter any of the
commands described in section 3.6.



3.1.1  Command Format

Command formats consist of keywords, switches, names you have DEFINEd,
file   specifications,  numbers,  quoted  strings,  and  guide  words.
Keywords and switches are  names  predefined  by  RMSUTL.   Names  you
define  may  consist  of letters, digits, hyphen, dollar-sign, period,
and percent-sign, and may be as long as  desired.   However  to  avoid
keyword  conflicts,  you  should not create a name that is a prefix of
BUCKET, DATAFIELD, FOUND-KEY-VALUE, HIGHEST, or PROLOGUE-DATA.

Command  names  and  all  other  keywords  need  not  be  spelled  out
completely;   any  unique  beginning  is acceptable.  For example, the
DEFINE command can be DEF or  DEFI.   Commands  are  terminated  by  a
carriage return - linefeed sequence.

See the TOPS-10 and TOPS-20 User Manuals for  a  description  of  file
specification  format.   A  quoted  string  is  an arbitrary string of
characters enclosed in double quotes.  A guide word is  a  descriptive
phrase  enclosed  in parentheses.  You need never type in guide words.
They are in RMSUTL to be typed out when you use recognition.  You  can
type  commands  in  either  uppercase  or  lowercase.  However, quoted
strings are processed exactly as typed.  Thus "ABC" is a different key
value from "abc" (unless the current file is a SIXBIT file).

Type a ?  to cause RMSUTL to display the list of available commands.
RMS FILE MANAGEMENT UTILITY                                   Page 3-2


Question mark can also be used  at  any  later  point  during  command
typein in order to see the alternatives available.

RMSUTL supports the usual input editing characters.  Use ^U to  delete
the  current  command  line.   Use  DELETE to backspace the cursor one
position.  Use ^R to redisplay the current command line.   Use  ^H  to
reestablish  an  aborted  command  line up to where the illegal typein
occurred.

RMSUTL supports command recognition (use of ESCAPE), although not  for
file specifications.  When you type ESCAPE, RMSUTL displays as much of
the remainder of the command as it can.  In particular,  if  you  type
the  beginning  characters  of  a  keyword  followed by ESCAPE, RMSUTL
responds by typing the remainder of the keyword and  any  guide  words
following  it.  However, if you have not uniquely identified a keyword
(for example, DE could be DELETE or DEFINE), RMSUTL sounds the bell.



3.1.2  Command Status

When necessary, RMSUTL displays errors,  warnings,  and  informational
messages.

An error message starts with ?, and there are the following cases.

     1.  ?  message -- the command processor detected an input  error,
         and command execution was not started.

     2.  ?UTLxxx -- RMSUTL detected an error during command execution.
         Usually  this means that the whole command is cancelled.  The
         exception occurs when the  command  performs  more  than  one
         independent operation (for example, FIX RFA1, RFA2).  In this
         case, only the operation affected by the error is  cancelled;
         any preceding and succeeding operations are performed.

     3.  ?  message / exit to EXEC -- an internal RMS error  occurred.
         You  should  always  report such errors to DIGITAL.  You must
         rerun RMSUTL to perform more commands.

A warning message starts with % and indicates that something minor  is
in  error,  but  RMSUTL is continuing execution of the operation.  For
example, you tried to name  more  than  16  datafields  in  a  DISPLAY
data-list command.

An informational message is enclosed  in  square  brackets  and  is  a
comment about the command.
RMS FILE MANAGEMENT UTILITY                                   Page 3-3


3.2  CREATING A FILE

The DEFINE FILE command enables you to create a  file  at  a  terminal
rather  than in a program.  Unless you wish to create an indexed file,
you simply give a single DEFINE FILE command, specifying  the  desired
file  attributes.   If  you  wish to create an indexed file, you first
DEFINE the areas and keys you wish to associate with the  file.   Then
you give the DEFINE FILE command as before.

The following example creates an indexed file with a primary key and a
secondary  key,  declares  a  large bucket size for the records of the
file, and uses defaults for all other file attributes.

     RMSUTL>DEFINE (OBJECT) AREA (NAMING IT) BIG (WITH BUCKET SIZE) 2 <RET>
     RMSUTL>DEFINE (OBJECT) DATA (NAMING IT) EMPLOYEE-NAME (WITH TYPE) SIXBIT
            (WITH LENGTH) 30 (STARTING AT BYTE) 0 /DANAME:BIG <RET>
     RMSUTL>DEFINE (OBJECT) DATA (NAMING IT) JOB-CLASS (WITH TYPE)
            SIXBIT (WITH LENGTH) 12 <RET>
     RMSUTL>DEFINE (OBJECT) DATA (NAMING IT) SALARY (WITH TYPE) INTEGER <RET>
     RMSUTL>DEFINE (OBJECT) KEY (NAMING IT) JCS (WITH SEGMENTS) 
            JOB-CLASS,SALARY /CHANGES-ALLOWED /DUPLICATES-ALLOWED <RET>
     RMSUTL>DEFINE (OBJECT) FILE (NAMING IT) EMPLOYEES.RMS 
            (WITH ORGANIZATION) INDEXED (WITH KEYS) EMPLOYEE-NAME,JCS <RET>



3.3  FILE MANIPULATION

RMSUTL operates on one RMS file at a time.  You  establish  this  file
with the OPEN RMS-FILE command.  Similarly all output from the DISPLAY
and scanning commands is written to a report file.  The report file is
an  ASCII  text  file,  and  it  is identified by the OPEN REPORT-FILE
command.  However, its use is optional.  If no report  file  is  open,
data is output to your terminal.

When you are finished using a file, a CLOSE RMS-FILE command or  CLOSE
REPORT command must be done.



3.4  MANIPULATING DATA IN A FILE

RMSUTL enables you to symbolically manipulate control  data  and  user
data.   It  provides keywords for control field names and includes the
DEFINE DATAFIELD command so you can name  and  describe  your  fields.
The  things  you  can do are DISPLAY fields, CHANGE fields, and DELETE
entries.

You can access and change arbitrary fields in a prologue with  DISPLAY
PROLOG  and CHANGE PROLOG.  You can access, change, and expunge bucket
entries with DISPLAY BUCKET, CHANGE BUCKET, and DELETE BUCKET.  To use
CHANGE  BUCKET,  CHANGE PROLOG, or DELETE BUCKET, you must open a file
for  PATCHING.   The  BUCKET  and  PROLOGUE  options   of   the   data
manipulation  commands  constitute  a physical view of the file.  This
view is normally needed  only  by  system  personnel.   Its  principle
purpose is to facilitate diagnosing and patching corrupted files.
RMS FILE MANAGEMENT UTILITY                                   Page 3-4


You can access, update, and delete  records  with  DISPLAY  data-list,
CHANGE data-list, and DELETE RECORD.  A data-list is one or more names
created with the DEFINE DATAFIELD command.  The  record-level  options
of  the data manipulation commands constitute a conceptual view of the
file.  They provide  you  at  command-level  with  the  same  sort  of
capabilities  you  have in a program.  Additionally, they allow you to
scan a group of records and select all or some of them for processing.
This  control  is  provided  by  the  records-to-use  clause, which is
described in section 3.7.

Another aspect of  data  manipulation  is  selecting  what  is  to  be
processed.  RMSUTL allows you to set:

     o    Current  key  tells  RMSUTL  which   index   to   use   when
          sequentially traversing the file.

     o    Current bucket tells RMSUTL which bucket to process  when  a
          CHANGE BUCKET, DISPLAY BUCKET, or DELETE BUCKET is done.

     o    Current record tells RMSUTL the  base  record  that  applies
          when relative record processing is done.

Currency indicators can be directly modified only by the SET  command,
which is described in section 3.6.11.



3.5  FILE SCANNING

Every  file-scanning  command  directly  accesses   consecutive   data
buckets.  These commands are designed so that it is easy to process an
entire index or entire file in one command.

The file-scanning commands are  SPACE,  UNCLUTTER,  and  VERIFY.   The
VERIFY  command is used to detect file corruption and out-of-sync-file
control data.  In update mode, it can be used to fix  out-of-sync-file
control  data.   The  UNCLUTTER  command is an updating VERIFY command
that also removes deleted POINTER entries and deleted records  from  a
file.  The SPACE command simply reports on space usage in a file:  how
full buckets are and how much clutter there is in them.   Output  from
each of these commands goes to the report file.

The OPEN RMS-FILE command for OUTPUT or PATCHING causes the file to be
opened  for  exclusive update.  Thus, an UNCLUTTER command or updating
VERIFY command cannot  be  done  while  you  are  up  for  production.
However,  the  impact of these restrictions has been minimized.  First
of all, you can do a read-only VERIFY.  If  any  out-of-sync  data  is
detected,  you  can then reopen the RMS file at a more convenient time
and quickly correct the affected entries with the FIX command.
RMS FILE MANAGEMENT UTILITY                                   Page 3-5


Additionally, a read-only VERIFY can be done from multiple jobs at the
same  time.   This  can be done because it is easy to specify mutually
exclusive portions of the file within each job.   Similarly,  one  can
UNCLUTTER a file over a period of several runs.



3.6  COMMAND DESCRIPTIONS

The following conventions are used in the  command  descriptions  that
follow.   Switches  are  shown alphabetically, but zero or more may be
specified in any  order.   The  symbol  (|)  represents  a  choice  in
arguments, parameters, or switches that can be used in a command.  For
example,

          /DISPLAY:| OCTAL   |
                   | DECIMAL |

means you can specify /DISPLAY:OCTAL or  /DISPLAY:DECIMAL.   If  there
are multiple options in a command that start with the same phrase, the
guide words for the phrase are  shown  only  with  the  first  command
option.   Also  guide  words  are shown for clarity only;  it is never
necessary to type in guide words.

The RMSUTL commands are:

     o   CHANGE         changes the specified fields to the  specified
                        values

     o   CLOSE          closes the currently opened RMS or REPORT file

     o   DEFINE
            AREA        creates and names an area description
            DATA        defines data fields in a record
            FILE        creates an RMS file with specified attributes
            KEY         creates and names a key description

     o   DELETE         deletes the specified entry or record

     o   DISPLAY        outputs the specified  fields  to  the  report
                        file

     o   EXIT           returns to operating system command level (you
                        can CONTINUE)

     o   HELP           outputs a brief description of RMSUTL

     o   INFORMATION    displays the specified portion of the  current
                        environment

     o   OPEN           opens the specified RMS or REPORT file

     o   REDEFINE       gives new attributes to a DEFINEd name
RMS FILE MANAGEMENT UTILITY                                   Page 3-6


     o   SET            changes the currency indicators

     o   SPACE          outputs  space  usage   statistics   for   the
                        specified part of a file

     o   TAKE           executes the RMSUTL commands in the  specified
                        file

     o   UNCLUTTER      eliminates deleted POINTER entries and deleted
                        records from a file

     o   VERIFY         determines if a file is internally consistent
RMS FILE MANAGEMENT UTILITY                                   Page 3-7






3.6.1  CHANGE Command



Function

     This command enables you to alter entries in your file.  The file
     is checkpointed after an entry is changed.

     Caution should be applied when using the CHANGE BUCKET and CHANGE
     PROLOGUE  commands.   Their  purpose  is  to  provide  you with a
     symbolic, and therefore safer, way of correcting damaged  control
     data.   Conversely, they give you the power to damage a perfectly
     valid file.


Formats

     The "to-list" argument in the formats below is of the form:

          field-name (TO) value, field-name (TO) value, ... , etc.

                                           | FILE    |
     CHANGE (VALUE OF) PROLOGUE-DATA (FOR) | AREA n1 | (SETTING) to-list
                                           | KEY  n2 |

          Fields in the specified descriptor  are  altered.   The  RMS
          file must be open for patching.

          N1 is an area number.  N2 is a key of reference.  If FILE is
          specified, the allowed fields are:

               1.  AREA-COUNT

               2.  AREA-OFFSET

               3.  BUCKET-SIZE

               4.  BYTE-SIZE

               5.  FORMAT

               6.  KEY-COUNT

               7.  KEY-OFFSET

               8.  MAXIMUM-RECORD-SIZE
RMS FILE MANAGEMENT UTILITY                                   Page 3-8


               9.  ORGANIZATION

              10.  PAGES-IN-FILE

          If KEY n2 is  specified,  the  allowed  fields  are  LEVELS,
          NEXT-KEY, ROOT-PAGE, and all the field-names of a KEY XAB.

          The internal tables of RMS do not reflect the effects  of  a
          CHANGE  PROLOG  command  until  after the file is closed and
          reopened.  Therefore RMSUTL does not allow  you  to  perform
          any bucket or record operations until you reopen the file.

                                   | ENTRY  n1 |
     CHANGE (VALUE OF) BUCKET (AT) | HEADER    | (SETTING) to-list
                                   | ID     n2 |

          RMSUTL  changes  the  specified  entry  within  the  current
          bucket.   The  RMS file must be open for patching.  An entry
          can be  identified  by  entry  number  or  ID  number.   The
          field-names  allowed  in  to-list  are bucket and entry type
          dependent, see section 4.3.

          If a RECORD entry of a primary-data bucket is specified, the
          to-list  can  also  contain  datafield  names.   This  usage
          differs from CHANGE datafield-list in that there are no side
          effects or checks when a key value is changed.

          RMSUTL changes the indicated fields in  the  header  of  the
          current bucket.  The field-names allowed in to-list are:

               1.  AREA-NUMBER

               2.  ATTRIBUTES

               3.  LAST-ID

               4.  LEVEL

               5.  NEXT-BUCKET

               6.  NEXT-ID

               7.  TYPE

               8.  WORDS-IN-USE


     CHANGE (VALUE OF) to-list records-to-use

          The indicated  datafields  in  the  identified  records  are
          changed.   At  most  16 datafields can be specified.  If the
          records-to-use clause is  omitted,  the  current  record  is
          used.  The file must be open for output or patching.
RMS FILE MANAGEMENT UTILITY                                   Page 3-9


          RMSUTL performs an RMS update operation (COBOL REWRITE verb,
          BASIC+2  UPDATE  statement).   Therefore,  you  have no more
          power than if you did  the  operation  in  a  program.   For
          example,  if  you  tried  to change the value of the primary
          key, RMS would not perform the update.  See Section 3.7  for
          a description of the "records-to-use" clauses.
RMS FILE MANAGEMENT UTILITY                                  Page 3-10






3.6.2  CLOSE Command



Function

     This  command  closes  the  specified  type  of   file,   thereby
     permitting you to open another file of that type.


Format

     CLOSE (FILE TYPE) | REPORT   |
                       | RMS-FILE |

          This command closes either the currently opened report  file
          or the currently opened RMS file.
RMS FILE MANAGEMENT UTILITY                                  Page 3-11






3.6.3  DEFINE DATAFIELD Command



Function

     The DEFINE DATAFIELD command is used to associate a name and data
     type  with a consecutive group of bytes in a record.  RMSUTL then
     can display or modify such a data segment when  given  its  name.
     Additionally,  you can place all your field definitions in a file
     and thereafter TAKE them whenever you run RMSUTL.

     The DEFINE DATAFIELD command can  be  used  to  define  a  single
     segment key.  You accomplish this by suffixing /KEY or any of the
     switches described for DEFINE KEY (see Section 3.6.4).


Formats

     DEFINE (OBJECT) DATAFIELD (NAMING IT) user-name (WITH TYPE) 

          | ASCII      |
          | FILE-BYTES | (WITH LENGTH) n1 (STARTING AT BYTE) n2
          | SIXBIT     |

          This usage defines a string  datafield  with  the  specified
          internal  representation.   FILE-BYTES  indicates  that  the
          representation  is  taken  from  the  file  byte  size.   N1
          indicates   the  number  of  bytes  in  the  datafield.   N2
          indicates the number of bytes preceding the starting byte of
          the   datafield.   If  n2  is  omitted,  RMSUTL  places  the
          datafield  immediately  past  the  last  defined  datafield.
          However  default  positioning  is allowed only when the last
          defined string has the same  internal  representation.   The
          initial positioning defaults are ASCII at byte 0.

     DEFINE (OBJECT) DATAFIELD (NAMING IT) user-name | FLOATING |
                                                     | INTEGER  |

          (STARTING AT WORD) n3

          FLOATING defines a numeric  datafield  that  is  represented
          internally  as a single-precision floating-point number.  N3
          indicates the number of words preceding the  datafield.   If
          n3 is omitted, RMSUTL places the datafield at the first word
          boundary past the last defined datafield.
RMS FILE MANAGEMENT UTILITY                                  Page 3-12


          INTEGER defines a  numeric  datafield  that  is  represented
          internally   as   a  single-precision  binary  integer.   N3
          indicates the number of words preceding the  datafield.   If
          n3 is omitted, RMSUTL places the datafield at the first word
          boundary past the last defined datafield.


Switch

     /DISPLAY: | OCTAL   |
               | DECIMAL |

          The /DISPLAY:  switch is applicable only when you  DEFINE  a
          DATAFIELD  to  be INTEGER.  If OCTAL is specified, the field
          is DISPLAYed as an unsigned  octal  value.   If  DECIMAL  is
          specified, the field is DISPLAYed as a signed decimal value.
          If /DISPLAY is not specified, DECIMAL is assumed.
RMS FILE MANAGEMENT UTILITY                                  Page 3-13






3.6.4  Defining File Attributes And The DEFINE FILE Command



Function

     The DEFINE FILE command is used to create an RMS file and  assign
     it  attributes.   The DEFINE FILE command is the only way to make
     an indexed file contain multiple areas, allow duplicates for  the
     primary  key,  or  be  loaded  with  partially  full buckets (see
     Appendix A).

     For indexed files, you must define at least one key  field.   You
     may  also  define  one  or  more  areas.  An area must be DEFINEd
     before it is used in a DEFINE KEY or  DEFINE  DATAFIELD  command.
     Similarly,  keys must be DEFINEd before they are used in a DEFINE
     FILE command.


Format I

     DEFINE (OBJECT) FILE (NAMING IT) filename (WITH ORGANIZATION)

          INDEXED (WITH KEYS) key-name-list

          Key-name-list is one or more key-names you have DEFINEd.  It
          identifies  the  file's  primary  key,  first secondary key,
          second secondary key, and so on.  No segment of  a  key  can
          have  a string data type that disagrees with the file's byte
          size.


     Switches

     /BUCKET-SIZE:n     

          RMSUTL sets bucket size for the default area to n pages.  If
          this switch is omitted, a bucket size of 1 page is assumed.

     /BYTE-SIZE:n       

          RMSUTL sets the file's byte size to n bits.  N can be 6,  7,
          or  9.  If this switch is not specified, a byte size of 7 is
          assumed.
RMS FILE MANAGEMENT UTILITY                                  Page 3-14


     /RECORD-SIZE:n     

          N is a byte count.  If record format is fixed, RMS uses n as
          the  record  size  for  all records in the file.  Thus, this
          switch is required if record format  is  fixed.   If  record
          format  is  variable, RMS interprets n as the maximum record
          size.  If this switch is not specified for a variable-record
          file, no maximum is established.

     /FORMAT: | FIXED    |
              | VARIABLE |

          RMSUTL gives the file the indicated record format.  VARIABLE
          means  that  the  file  can  contain  records  of  different
          lengths.  FIXED indicates that each  record  must  have  the
          size  specified  in the /RECORD-SIZE switch.  If this switch
          is not specified, VARIABLE is assumed.

Format II

     DEFINE (OBJECT) KEY (NAMING IT) key-name (WITH SEGMENTS) segment-name

          This command creates a key description  with  the  specified
          name and attributes.  Segment-name identifies the datafields
          that comprise the key, up to eight can  be  specified.   The
          datafields  specified  must  already have been DEFINEd.  The
          combined size of a key's segments may not exceed 255  bytes.
          The data type of a string segment must conform to the file's
          byte size.  For example, a segment's data type can be SIXBIT
          only if the file's byte size is 6.


     Switches

     /CHANGES-ALLOWED

          If specified, a program will be able to alter this key on an
          update.  This switch can not be applied to a primary key.

     /DANAME:area-name

          Data buckets  for  this  key  will  be  allocated  from  the
          specified  area,  which  must already have been DEFINEd.  If
          this switch is not specified, area 0 is used.

     /DAFILL:n

          RMS will put at most n words in a data bucket for this  key.
          This  enables  you  to  spread  out  records  when initially
          loading a file.  If this switch is not specified, n  is  set
          to 0 which means the entire bucket is used.
RMS FILE MANAGEMENT UTILITY                                  Page 3-15


     /DUPLICATES-ALLOWED

          If specified, a program will be able to write a record  that
          contains a key value that already exists in the file.

     /IANAME:area-name

          Index buckets for  this  key  will  be  allocated  from  the
          specified  area,  which  must already have been DEFINEd.  If
          this switch is not specified, area 0 is used.

     /IAFILL:n

          RMS will put at most n words in an  index  bucket  for  this
          key.   This  enables  you  to spread out bucket entries when
          initially loading a file.  If this switch is not  specified,
          n is set to 0 which means the entire bucket is used.


Format III

     DEFINE (OBJECT) AREA (NAMING IT) area-name (WITH BUCKET SIZE) n

          This command creates an area description with the  specified
          name  and  bucket size.  N is the number of pages to be used
          for buckets of this area.  An area-name can be referenced in
          0 or more key descriptions.
RMS FILE MANAGEMENT UTILITY                                  Page 3-16






3.6.5  DELETE Command



Function

     This command is used to reclaim space in a file or  to  logically
     delete records.

     Caution should be applied when using DELETE BUCKET.  Its  purpose
     is  to  provide  you with a symbolic, and therefore safer, way of
     correcting damaged control data.  Therefore,  it  gives  you  the
     power to damage a perfectly valid file.


Formats

     DELETE (OBJECT) BUCKET-ENTRY (IDENTIFIED BY) | ENTRY n1 |
                                                  | ID    n2 |

          The space occupied by the specified  entry  in  the  current
          bucket is reclaimed.  ID n2 may be specified only for a data
          bucket.  The RMS file must be open for patching.

          RMSUTL tries to prevent accidental deletions.  A SIDR  entry
          space  may not be reclaimed if any non-NIL values are in its
          RFA list.  An index entry's space may not  be  reclaimed  if
          its  DOWN-POINTER  identifies  a  valid  nonempty bucket.  A
          RECORD entrys space may not be reclaimed unless its  DELETED
          attribute is on.

          RECORD entries are special in that they are  pointed  at  by
          other  entries.   If a RECORD entry points back to a POINTER
          entry, the POINTER entry is  reclaimed  as  well.   However,
          deletion  of  a  RECORD  entry does not affect any secondary
          data entries associated with the record.

                                            | KEY             |
     DELETE (OBJECT) RECORD (IDENTIFIED BY) | LAST-ENTRY      |
                                            | RELATIVE-REC-NO |

          The   records   identified   by    KEY,    LAST-ENTRY,    or
          RELATIVE-REC-NO  clause  are  deleted.   These  clauses  are
          referred to as "records-to-use"  clauses.   If  you  do  not
          specify  one  of  these  records-to-use  clauses,  only  the
          current record is deleted.  A delete operation in a  program
          would  have  the  exact  same effect.  See Section 3.7 for a
          description of the "records-to-use" clauses.
RMS FILE MANAGEMENT UTILITY                                  Page 3-17






3.6.6  DISPLAY Command



Function

     This command  outputs  values  to  the  report  file,  which  you
     identify  with an OPEN REPORT command.  However, if a report file
     is not open, the report is output to the user terminal.  The data
     in the report is discussed in Section 3.8.1.


Formats

                                            | AREA n1           |
     DISPLAY (VALUE OF) PROLOGUE-DATA (FOR) | FILE field-list   |
                                            | KEY n2 field-list |

          If the (FOR) clause  is  omitted,  the  entire  prologue  is
          displayed.   If  a  field-list  is omitted, the entire file,
          area, or key descriptor is displayed.  N1 is an area number.
          N2 is a key of reference.

          If FILE is specified, the allowed fields are:

               1.  AREA-COUNT

               2.  AREA-OFFSET

               3.  BUCKET-SIZE

               4.  BYTE-SIZE

               5.  KEY-COUNT

               6.  KEY-OFFSET

               7.  MAXIMUM-RECORD-SIZE

               8.  ORGANIZATION

               9.  PAGES-IN-FILE

              10.  RECORD-FORMAT

          If KEY n2 is  specified,  the  allowed  fields  are  LEVELS,
          NEXT-KEY,  ROOT-PAGE,  and  all the field-names of a KEY XAB
          (extended argument blocks).
RMS FILE MANAGEMENT UTILITY                                  Page 3-18


                                    | ENTRY n-list       |
                                    | HEADER             |
     DISPLAY (VALUE OF) BUCKET (AT) | ID n-list          |
                                    | KEY-VALUE "string" |
                                    | LARGEST-ENTRY      |

          The specified clause of the current bucket is displayed.   A
          bucket  consists of a header and 0 or more entries.  If none
          of the above clauses are specified in the  DISPLAY  command,
          the  entire  bucket  is  displayed.   The  above clauses are
          defined as follows:

          ENTRY n-list  the specified entries are displayed.

          HEADER        the bucket's header is displayed.

          ID n-list     the  entries  with  the  specified   IDs   are
                        displayed.   The current bucket must be a data
                        bucket.

          KEY-VALUE "string" 

                        the first entry with a  key  greater  than  or
                        equal to "string" is displayed.

          LARGEST-ENTRY the largest entry in the bucket is displayed.

          N-list is a list of ranges separated by commas.  A range  is
          n1  (TO)  n2.  If n2 is omitted, n1 (TO) n1 is assumed.  For
          example, DISPLAY BUCKET ENTRY 1 (TO) 3, 7 displays entry  1,
          entry  2, entry 3, and entry 7.  A range may be sparse.  For
          example, if no record  in  the  current  bucket  has  ID  4,
          DISPLAY  BUCKET  ID  3 (TO) 5 displays the other two entries
          regardless.

                                                         | KEY             |
     DISPLAY (VALUE OF) DATA (FOR RECORDS IDENTIFIED BY) | LAST-ENTRY      |
                                                         | RELATIVE-REC-NO |

          The portion of the identified records indicated by the  KEY,
          LAST-ENTRY,  or  RELATIVE-REC-NO clause is displayed.  These
          clauses are referred to as  "records-to-use"  clauses.   The
          entire   record   is  treated  as  a  field  whose  type  is
          FILE-BYTES.  A datafield-list is one or more datafield names
          separated by commas.  If a datafield-list is specified, each
          field is displayed in accordance with its DEFINE command.  A
          maximum  of  16  datafields  can be specified.  If the above
          clauses are  omitted,  the  current  record  is  used.   See
          section  3.7  for  a  description  of  the  "records-to-use"
          clause.
RMS FILE MANAGEMENT UTILITY                                  Page 3-19






3.6.7  FIX Command



Function

     This command completes an aborted delete, put, or update for  the
     specified  entries.   If the entry needs fixing, the same message
     as would occur during a VERIFY is output to the report file.   No
     message  is  generated when you give a FIX command for an already
     valid entry.

     FIX is used in conjunction with VERIFY.  When VERIFY  is  run  in
     NOFIX mode, it denotes inconsistencies that can be fixed later by
     suffixing [Fixable] to the message describing the  inconsistency.
     See  section  3.8.2  for  a description of these messages and the
     exact FIX statement that applies to each of them.


Format

     FIX (RECORD WITH RFA) fix-list

          An entry in a fix-list is of the form "rfa1 (OF  INDEX)  n".
          If n is omitted, 0 is assumed.  If an entry in a fix-list is
          invalid in some way, processing of subsequent entries in the
          list is not affected.
RMS FILE MANAGEMENT UTILITY                                  Page 3-20






3.6.8  INFORMATION Command



Function

     The INFORMATION command displays on your terminal  the  specified
     information, dependinng on the clause you use, the current status
     of RMSUTL, and the file you are maintaining.


Format

                         | ALL        |
                         | AREAS      |
     INFORMATION (ABOUT) | CONTEXT    |
                         | DATAFIELDS |
                         | KEYS       |

          Specifying  AREA,  DATAFIELDS,  or  KEYS  causes  RMSUTL  to
          display the attributes of the indicated DEFINEd names.

          CONTEXT displays information about the currency  indicators.
          It  displays  the  current  key  of  reference,  the current
          record's RFA, and the current bucket's page number.  It also
          tells you about the report file and RMS file.

          ALL combines the output of the other options.
RMS FILE MANAGEMENT UTILITY                                  Page 3-21






3.6.9  OPEN Command



Function

     The OPEN command identifies and makes a file available to RMSUTL.
     There  are  two  types of files, RMS files and report files.  All
     data manipulation is with respect to the currently open RMS file.
     The  output of DISPLAY and the file-scanning commands is directed
     to the currently open report file, if there is one.  If no report
     file  is  open,  reports  are  directed to TTY:.  Until a file is
     CLOSEd, a new file of the same type cannot be identified.


Format I

                                                          | INPUT    |
     OPEN (FILE TYPE) RMS-FILE (WITH NAME) filespec (FOR) | OUTPUT   |
                                                          | PATCHING |

          Opens the specified RMS  file  for  the  indicated  type  of
          access.   The default access mode is INPUT.  CHANGE, DELETE,
          and UNCLUTTER may not be done if the file is open for input.
          CHANGE PROLOGUE, CHANGE BUCKET, and DELETE BUCKET may not be
          done unless the file is open for PATCHING.

          If OUTPUT or PATCHING is specified, no one else can have the
          file  open  to  write.   If there is an access conflict with
          another user, the OPEN fails.  If  INPUT  is  specified,  an
          access  failure  cannot  occur.   However  there  is a small
          chance that a later command may be affected by the output of
          another job.

          OPEN RMS-FILE is a two operation command:  OPEN followed  by
          SET  INDEX  0.   If  the  second  operation  fails, the file
          "remains" open, with current bucket set to 1 and no  current
          record set.


     Switch

     /MAXIMUM-RECORD-SIZE:n

          If a file was created without a maximum record size,  RMSUTL
          has  no  direction  as  to  an appropriate size for its data
          record buffer.  This  switch  tells  RMSUTL  to  allocate  a
          buffer  of  n  file-bytes.   If  the switch is also omitted,
          RMSUTL allocates a buffer of 512 words.
RMS FILE MANAGEMENT UTILITY                                  Page 3-22


Format II

     OPEN (FILE TYPE) REPORT /APPEND

          The OPEN REPORT command opens the specified file for output,
          creating it if necessary.  If the file already exists, it is
          superseded unless the  /APPEND  switch  is  specified.   The
          report  file  is  a stream ASCII file and is checkpointed at
          the end of each RMSUTL command.


     Switch

     /APPEND

          If a report file already exists, the /APPEND switch  permits
          you  to  add  stream  ASCII  data to the existing file.  The
          existing report file will not be superseded.
RMS FILE MANAGEMENT UTILITY                                  Page 3-23






3.6.10  REDEFINE Command



Function

     This command gives new attributes to an already DEFINEd name.


Formats

                     | datafield |
     REDEFINE (NAME) | area      | remainder of DEFINE
                     | key       |

          See section 3.6.3 for a  description  of  DEFINE  DATAFIELD.
          See section 3.6.4 for descriptions of DEFINE AREA and DEFINE
          KEY.
RMS FILE MANAGEMENT UTILITY                                  Page 3-24






3.6.11  SET Command



Function

     This command enables you to modify the currency indicators.   The
     general rules governing currency indicators are as follows:

     1.  When you open an RMS file, RMSUTL simulates a SET INDEX 0.

     2.  If a SET command  results  in  a  ?   message,  the  currency
         indicators are left unchanged.

     3.  The SET INDEX command sets all three currency indicators.

     4.  The SET BUCKET command sets only the current bucket.

     5.  The SET RECORD command sets just the  current  record  unless
         you  specify  SET  RECORD  KEY new-key-of reference.  In this
         case, it sets all three currency indicators.



Formats

     SET (CURRENT) BUCKET (TO ONE IDENTIFIED BY) bucket-to-use

          This command sets the current bucket to the one specified in
          the  bucket-to-use  clause.  The bucket-to-use clause may be
          one of the following:

          o  DATA-LEVEL locate the  leftmost  data  bucket  under  the
                        current   bucket.   Leftmost  means  the  data
                        bucket with the lowest keys.

          o  DOWN n     move to the bucket pointed to by the nth entry
                        from  the  top of the current bucket.  If n is
                        omitted, move to the bucket pointed to by  the
                        first  entry.   The  current bucket must be an
                        index bucket.

          o  LAST-RECORD 

                        move to the bucket associated  with  the  last
                        record   selected   in   a   record-processing
                        command.  The record-processing  commands  are
                        CHANGE   data-list,   DELETE  RECORD,  DISPLAY
                        data-list, and SET RECORD.  If the primary key
                        is current, the primary data bucket containing
RMS FILE MANAGEMENT UTILITY                                  Page 3-25


                        the record is selected.  If a secondary key is
                        current,  the secondary data bucket containing
                        the  SIDR  that  points  at  the   record   is
                        selected.

          o  NEXT       move to the bucket at the same  level  of  the
                        tree with the next higher group of key values.
                        However, if the current bucket  is  rightmost,
                        move to the leftmost bucket.

          o  ROOT       position to the root  bucket  of  the  current
                        index structure.

          o  UP         move to the bucket whose entry points  at  the
                        current bucket.

     SET (CURRENT) INDEX (USING KEY OF REFERENCE) n1 (AND) where-in-index

          This command sets the current key of reference  to  n1.   It
          sets   current   bucket   and   current   record  using  the
          where-in-index clause.  The possibilities are:

               BUCKET (AT PAGE) n2

               RFA (BKT/ID) n3/n4

               ROOT

          If the where-in-index clause is omitted, ROOT is assumed.

          ROOT causes the current bucket to be set to the root  bucket
          of  index n1.  It causes the current record to be set to the
          record containing the lowest key value for key n1.

          BUCKET n2 sets the current bucket to n2.  If this bucket  is
          not  part  of  index  n1, RMSUTL may not be able to tell for
          sure.  If [Page not start of ...  ] is displayed, the bucket
          is  still  made  current because the problem may be that the
          bucket's header is clobbered rather than that you  specified
          a  bad  page number.  RMSUTL tries to set the current record
          to the record identified by the first entry in the  selected
          bucket.   However,  RMSUTL  cannot always do this.  The full
          set of rules are:

          1.  If the bucket's  header  is  clobbered,  do  not  set  a
              current record.

          2.  If  the  bucket  at  page  n2  is  not  a  data  bucket,
              internally perform a SET BUCKET DATA-LEVEL.

          3.  If the bucket at the data-level is empty, do not  set  a
              current record.
RMS FILE MANAGEMENT UTILITY                                  Page 3-26


          4.  For key 0, try to set current record to the first  entry
              in this bucket.

          5.  For a secondary key, try to set current  record  to  the
              first RFA in the first entry's RFA list.  If the list is
              empty, do not set a current record.

          6.  Do a key access using the key  value  in  the  tentative
              current  record.   If the key access fails, do not set a
              current record.

          7.  Scan up to 100 duplicates until  the  tentative  current
              record  is  found.   If  it  is  found, it has been made
              current.  If it cannot be found (probably because it  is
              a deleted entry or it is more than the 100th duplicate),
              "approximate" and  set  current  record  to  the  record
              located by the key access.

          RFA n3/n4 tries to set the  current  record  to  the  record
          located by ID n4 in the primary data bucket at page n3.  The
          record or its POINTER entry may be at n3/n4.  The  operation
          may  fail  or  become approximate in the same ways as BUCKET
          n2.   For  key  0  current  bucket  is  set  to  the  bucket
          containing  the  current record.  For a secondary key, it is
          set to the bucket containing the current record's SIDR.

     SET (CURRENT) RECORD (TO FIRST ONE IDENTIFIED BY) records-to-use

          This command sets  the  current  record  to  the  first  one
          selected by the records-to-use clause, which is described in
          section 3.7.  If a new key of reference is specified in  the
          records-to-use  clause,  it becomes current, and the current
          bucket is set to the data bucket containing the data  record
          (or SIDR) selected.
RMS FILE MANAGEMENT UTILITY                                  Page 3-27






3.6.12  SPACE Command



Function

     This command accumulates space  usage  statistics  for  the  data
     buckets  in  the  specified  key  range.   SPACE  outputs  status
     information and the results of its scan to the report file.  This
     output  is  described in section 3.8.2.  The fullness and clutter
     statistics  it  generates  are  a  good  indication  of  when  to
     UNCLUTTER or reload a file.


Format

                                | ALL-KEYS          |
     SPACE (USAGE OF FILE FROM) | KEY (#) n1 range  |
                                | SECONDARY-KEYS    |

          If ALL-KEYS is  specified,  all  indexes  of  the  file  are
          scanned.   If SECONDARY-KEYS is specified, the index of each
          secondary key is scanned.   If  KEY  n1  is  specified,  the
          specified  part of that key's data buckets is scanned.  If a
          range is not specified, the entire  index  is  scanned.   If
          none  of  the  above  options  are  specified,  ALL-KEYS  is
          assumed.

          Range is of  the  form  (FROM)  low-bound  (TO)  high-bound.
          Low-bound  may be LOWEST or a quoted string.  High-bound may
          be HIGHEST or a quoted  string.   The  interpretation  of  a
          scanning range is consistent with the records-to-use clause,
          described in section 3.7.
RMS FILE MANAGEMENT UTILITY                                  Page 3-28






3.6.13  UNCLUTTER Command



Function

     This command eliminates  POINTER  entries  and  expunges  DELETEd
     records  within  the  specified range of keys.  In the process of
     doing this, it does an updating VERIFY KEY 0  for  the  specified
     range.   UNCLUTTER  outputs status information and the results of
     its scan to the report file.  This output is described in section
     3.8.2.

     Periodic  use  of  this  command  reduces  degradation  of  keyed
     accesses  over time.  There are two reasons for this.  UNCLUTTER,
     by reclaiming space, reduces the likelihood of bucket  splitting.
     Secondly,  removing  POINTER entries saves the file access needed
     to process the level of indirection POINTER entries imply.


Format

     UNCLUTTER (INDEX FILE FROM) range

          Range is of the form low-bound (TO)  high-bound.   Low-bound
          may be LOWEST or a quoted string.  High-bound may be HIGHEST
          or a quoted string.  If the range is  omitted,  LOWEST  (TO)
          HIGHEST  is assumed.  The interpretation of a scanning range
          is consistent with the records-to-use clause,  described  in
          section 3.7.


Switch

     /PROGRESS:n2

          If the /PROGRESS switch is  specified,  RMSUTL  outputs  the
          UNCLUTTER's  progress  every  n2 keys it scans.  Progress is
          shown by displaying the highest key value  scanned  so  far.
          If  /PROGRESS  is  omitted,  10000  is assumed.  RMSUTL also
          checkpoints the RMS file and the report file when it makes a
          progress report.
RMS FILE MANAGEMENT UTILITY                                  Page 3-29






3.6.14  VERIFY Command



Function

     This command verifies that records in the specified key range can
     be  accessed  sequentially  and  by  key.   VERIFY outputs status
     information and the results of its scan to the report file.  This
     output  is  described  in section 3.8.2.  If the RMS file is open
     for output or patching, VERIFY  will  complete  aborted  deletes,
     puts, and updates, unless you specify otherwise.

     As VERIFY scans an index structure, it does the following:

               1.  It verifies that the keys of each bucket are sorted
                   in  ascending sequence.  And for secondary keys, it
                   checks that each RFA in a SIDR  points  to  a  data
                   record with the same key value as the SIDR.

               2.  It verifies that duplicates occur only when proper.

               3.  It verifies that each entry scanned can be accessed
                   by  key  (by doing a key access for the highest key
                   in each data bucket).

               4.  It checks the  bucket  header  of  each  bucket  it
                   accesses.



Format

                              | ALL-KEYS          |
     VERIFY (INDEX FILE UPON) | KEY (#) n1 range  |
                              | SECONDARY-KEYS    |

          If ALL-KEYS is  specified,  all  indexes  of  the  file  are
          scanned.   If SECONDARY-KEYS is specified, the index of each
          secondary key is scanned.   If  KEY  n1  is  specified,  the
          specified  part  of that key's index is scanned.  If a range
          is not specified, the entire index is scanned.  If  none  of
          the above options are specified, ALL-KEYS is assumed.

          Range is of  the  form  (FROM)  low-bound  (TO)  high-bound.
          Low-bound  may be LOWEST or a quoted string.  High-bound may
          be HIGHEST or a quoted  string.   The  interpretation  of  a
          scanning range is consistent with the records-to-use clause,
          described in Section 3.7.
RMS FILE MANAGEMENT UTILITY                                  Page 3-30


Switches

     /NOACCESS

          When a  primary  index  is  scanned,  VERIFY  accesses  data
          records  by  each of their secondary keys unless this switch
          is specified.  If the primary index is  not  being  scanned,
          this  switch  is  ignored.   Accessing  by  secondary key is
          important but expensive.  It is the only  way  to  guarantee
          that  a data record can be accessed by each of its secondary
          keys.   However,  a  scan  of  the  secondary  indexes  will
          discover  most key inconsistencies caused by aborted updates
          (as opposed to aborted puts).

     /NOFIX

          When the RMS file is open for  output  or  patching,  VERIFY
          completes  aborted  deletes,  puts,  and updates unless this
          switch is specified.

     /PROGRESS:n2

          If the /PROGRESS switch is  specified,  RMSUTL  outputs  the
          VERIFY's progress every n2 keys it scans.  Progress is shown
          by displaying the highest key  value  scanned  so  far.   If
          /PROGRESS   is  omitted,  10000  is  assumed.   RMSUTL  also
          checkpoints the RMS file and the report file when it makes a
          progress report.
RMS FILE MANAGEMENT UTILITY                                  Page 3-31






3.6.15  Secondary Commands



Function

     These commands (as shown in  the  formats  below)  allow  you  to
     perform other functions in the RMSUTL program.


Formats

     EXIT (TO MONITOR)

          Return to the operating  system  command  level.   Any  open
          files  are  closed.   You can type CONTINUE, but you have to
          (re)open the files you wish to process.

     HELP (PLEASE)

          Displays description of each RMSUTL command.

     TAKE (COMMANDS FROM) file-spec /[NO]DISPLAY

          Reads RMSUTL commands  from  the  specified  file.   If  the
          /DISPLAY  switch  is specified, TAKE outputs the commands to
          the  terminal  as  they  are  processed.   The  default   is
          /NODISPLAY.
RMS FILE MANAGEMENT UTILITY                                  Page 3-32


3.7  RECORDS-TO-USE CLAUSE

The record-processing commands allow you to select all or  part  of  a
group of records for processing in a single command.  You can select a
range of records by key value  or  relative  to  the  current  record.
Additionally  you  can  select  the  current  record  by  omitting the
records-to-use clause, or you can select the  last  entry  used  in  a
bucket-processing command.

The facility for selecting part of a range is the  value-test  phrase.
The  value-test  phrase is of the form datafield-name operator value3.
When this optional phrase is specified, it causes RMSUTL to apply  the
indicated  test  to each record it locates.  If the test is false, the
located record is bypassed.  Datafield-name must have been declared in
the DEFINE DATAFIELD command.  Value3 must conform to the data type of
the specified datafield.  Operator can be =, #,  >,  >=,  <,  or  <= .
These are respectively equal, not equal, greater than, greater than or
equal, less than, and less than or equal.


Formats


     KEY (#) n (FROM) low-bound (TO) high-bound (AND) value-test

          RMSUTL locates each record that has a key value that  is  >=
          the  value  derived  from low-bound and <= the value derived
          from high-bound.  If high-bound is omitted, RMSUTL  supplies
          a  default.   N  identifies  which key to use.  Specifying 0
          identifies the primary key.  Omitting n causes RMSUTL to use
          the current key of reference.

          Low-bound may be LOWEST  or  a  quoted  string.   The  value
          RMSUTL  derives  from  LOWEST  is  a  string  of  NULs.   If
          low-bound is LOWEST and high-bound is omitted, high-bound is
          set to FOUND-KEY-VALUE.  If low-bound is a quoted string and
          high-bound is omitted, high-bound is set to the  same  value
          specified  in  low-bound.   Thus,  if  no records have a key
          value equal to the quoted string, no  records  are  located.
          Conversely,  if there are multiple records whose key is this
          value, each is located.

          High-bound may be  HIGHEST,  FOUND-KEY-VALUE,  or  a  quoted
          string.   The  value RMSUTL derives from HIGHEST is a string
          whose bits are  all  1s.   The  value  RMSUTL  derives  from
          FOUND-KEY-VALUE  is  the  first  key  value  in  the file >=
          low-bound.  If low-bound  and  high-bound  are  both  quoted
          strings, high-bound must not be less than low-bound.

          When the length of a quoted string is less than the  defined
          length  of  the specified KEY, RMSUTL pads it to the defined
          length.   For  low-bounds,   it   pads   with   NULs.    For
          high-bounds,  it  pads  with  1  bits.  Thus, if you specify
          DISPLAY DATA KEY 1 "A", RMSUTL  locates  each  record  whose
RMS FILE MANAGEMENT UTILITY                                  Page 3-33


          first secondary key starts with "A".  This is because RMSUTL
          interprets the KEY range as "A000..." (TO) "A111...",  where
          000...   and 111...  indicate padding to defined length with
          bytes that are all 0s and 1s respectively.

          A  range  containing  padded  lengths  is   sometimes   "too
          powerful."  Consider  a  key that is a blank-padded person's
          name.  It is not enough to specify DISPLAY DATA KEY  "BROWN"
          to  exclusively  locate  records  whose key is "BROWN     ".
          You must specify "BROWN " to prevent "BROWNxxxxx" from  also
          being located.


     LAST-ENTRY

          If the primary key is current and a data bucket  is  current
          and  the last accessed entry is an existing record, the last
          accessed entry is selected.


     RELATIVE-REC-NO (FROM) n1 (TO) n2 (AND) value-test

          RMSUTL locates  the  specified  range  of  records  from  n1
          through  n2.   Record  0 is the current record;  record 1 is
          the next record;  and so on.  "Next" is with respect to  the
          sequential ordering implied by the current key of reference.

          If n2 is not specified, only the record identified by n1  is
          located  and  a  value-test  may not be specified.  If n2 is
          specified, it must be greater than n1.  If n2  is  past  the
          last record in the current index, no error results.



3.8  THE REPORT FILE

Output from DISPLAY, FIX, and the file-scanning commands  is  directed
to  the  report  file.   If  no  report  file  is open, this output is
directed to TTY:  and is  intermixed  with  command  status  messages.
Also the command as typed does not appear in the report, as is usually
the case.



3.8.1  DISPLAY OUTPUT

The format in which an entry is  displayed  depends  on  the  type  of
bucket.   The  display  of an index entry contains a key value and the
page number of a  bucket.   The  display  of  a  secondary-data  entry
contains  a  key  value  and  one  or  more  RFAs.   The  display of a
primary-data entry contains the entry's control data and primary  key,
unless  the  entry  is  a  POINTER  entry.  DISPLAY BUCKET and DISPLAY
PROLOG usually suppress output of 0-valued fields.
RMS FILE MANAGEMENT UTILITY                                  Page 3-34


Record displays are analogous to entry displays.  In  effect,  control
field-names  are  replaced  by  user  field-names.   Additionally, the
record's RFA is included in the display.  If the record has a  POINTER
entry,  the  POINTER  entry's  RFA  is  displayed  as  well.   The RFA
information is important when you are examining SIDRs.



3.8.2  File-Scanning Output

File-scanning output falls into two categories:  scan status messages,
which are enclosed in square brackets;  and scan results.

There are the following types of scan status messages:

     1.  Completion messages occur when the scan of an index has  been
         completed.   For  example,  if  you  specify VERIFY ALL for a
         three key file, three  completion  messages  are  output.   A
         normal  completion message for VERIFY (or UNCLUTTER) contains
         a count of the records scanned.  For the primary key, this is
         the  number of existing user records.  For secondary keys, it
         is the number  of  SIDRs.   An  abnormal  completion  message
         occurs if a loop is detected in the data buckets of an index.

     2.  Progress reports occur as a result of the /PROGRESS:n switch,
         where  n  refers  to  existing  user  records  or  SIDRs,  as
         appropriate.  When RMSUTL outputs a progress report, it  also
         checkpoints  the  report  file  and  RMS file.  Thus, you are
         guaranteed that you can safely resume a  scan  with  the  key
         value output in the last progress report.

     3.  [Fixing] and  [Fixable]  are  appended  to  scan  results  to
         indicate  what  RMSUTL  took  care of or can take care of for
         you.  The two messages are mutually exclusive;   an  updating
         scan  outputs  the [Fixing], and a read-only scan outputs the
         [Fixable].

     4.  [Aborting scan of current  bucket]  occurs  after  the  third
         uncorrectable  inconsistency  has  been detected in a bucket.
         It is simply a means of bounding  output  when  "garbage"  is
         being scanned.

     5.  [Changing to /NOFIX ...   ]  occurs  after  an  UNCLUTTER  or
         updating  VERIFY  has detected an inconsistency RMSUTL cannot
         correct.  It is a precautionary  measure  to  prevent  RMSUTL
         from further clobbering your file.

     6.  [Empty RFA list ...  ] occurs when  RMSUTL  detects  an  SIDR
         whose  RFA  list  contains  all NILs.  You need do nothing in
         response to this message, but you may reclaim some  space  by
         DELETing the specified entry if desired.

The scan-result messages are as  follows.   Except  where  noted,  the
messages relate to the VERIFY and UNCLUTTER commands.
RMS FILE MANAGEMENT UTILITY                                  Page 3-35


For fixable conditions, the message description shows the FIX  command
you  would  later  type  in  if the message occurred doing a read-only
VERIFY.  Most of the other conditions should never occur.  For  these,
you  will  usually  have  to  do most of the diagnosis yourself.  Your
primary tools are SET INDEX, SET BUCKET, and DISPLAY BUCKET.

     Access by key n1 failed for rfa1

          The record with RFA  rfa1  could  not  be  accessed  by  the
          indicated  secondary  key.  This is normally caused by a put
          or update that aborted after the user record was updated but
          before  all  of  its  secondary  keys  were processed.  This
          inconsistency is fixable;  specify FIX  rfa1.   If  the  fix
          fails,  "Could  not  insert  key  into  secondary  index" is
          output.

          If the ID of  one  or  more  entries  is  clobbered,  it  is
          possible to get a cyclic fix.  You fix key 0 and get "Access
          ...  failed";  you fix a secondary key and get "No  matching
          data  record  ...";   you  fix  key  0  and  get "Access ...
          failed";  and so on.

     Data bucket at page n1 points at page n2 but succeeding index entry does not

          Normally  consecutive  data  buckets  are  pointed   at   by
          successive  index  entries  (or  the  same  index entry in a
          horizontal search situation).  This message can mean that  a
          whole  page of records has been accidentally bypassed in the
          data bucket chain.  You will be able to access the  affected
          records  by  key,  but  not  sequentially.   To  locate  the
          relevant index entries:

               SET INDEX index-being-scanned BUCKET n1
               DISPLAY BUCKET LAST
               SET BUCKET UP
               DISPLAY BUCKET KEY-VALUE "key of entry just DISPLAYed"

     Data bucket clutter n%

          This  is  output  from  a  SPACE  scan.   It  indicates  the
          percentage  of  total  data  bucket  space that is currently
          devoted to POINTER entries  and  records  with  the  DELETEd
          attribute  on.   This  message is output for the primary key
          only.

     Data bucket fullness n%

          This  is  output  from  a  SPACE  scan.   It  indicates  the
          percentage  of  total data bucket space that is currently in
          use (including clutter).
RMS FILE MANAGEMENT UTILITY                                  Page 3-36


     Data record identified by back pointer for rfa1

          The RFA field of the data record at rfa1 points  at  another
          data record rather than at a POINTER record.

     Duplicate key encountered for rfa1

          Duplicates are not allowed for the key  being  scanned,  but
          the  entry  at rfa1 has the same key value as the entry that
          precedes it.

     Key access aborted for rfa1

          An unexpected error occurred in RMS when the record at  rfa1
          was  accessed  by  key.   This  may indicate clobbered index
          buckets or a bug in RMS.

     Key access failed for rfa1

          The record at rfa1 could not be found by a key access.  This
          may indicate clobbered index buckets.  Other records earlier
          in the same bucket may also be inaccessible.

     Key value out of order for rfa1

          The entry at rfa1 has a lower key value than the entry  that
          precedes it.  If this message occurs, it is likely that "Key
          access failed ..." will occur for  the  last  entry  in  the
          bucket.   In  the special case that the message occurs for a
          record with the DELETEd attribute on, simply  DELETE  BUCKET
          ID ID-of-rfa1 after making the bucket of rfa1 current.

     No matching data record for RFA n1 (rfa1) of rfa2

          The n1th RFA of the SIDR at rfa2 contains the pointer  rfa1,
          and  rfa1 does not identify an existing record with the same
          key value as appears in the SIDR.  Normally this means  that
          a  delete  or  update  aborted  after the record's entry was
          updated but before all of the old secondary references  were
          deleted.   This  inconsistency is fixable;  specify FIX rfa2
          index-of-scan.

          If the match did not occur because the data record contained
          a  different key value, RMSUTL also outputs "Access ...  may
          fail ...".  This is because VERIFY KEY 0 may lead to "Access
          ...  failed for rfa1".  Specifying FIX rfa1 will correct the
          problem if it does exist.
RMS FILE MANAGEMENT UTILITY                                            Page 3-37


     Page n1 not start of bucket OR ... clobbered OR not part of index n2

          During the scan, RMSUTL tried to read a bucket at  page  n1,
          and  it was bad in some way.  You will have to diagnose why;
          start  by  specifying  SET  INDEX  n2  BUCKET  n1  and  then
          displaying the bucket's header.

     POINTER entry does not point at data record for rfa1

          The data record at rfa1 pointed back at a POINTER entry that
          does  not  point  at it.  Normally this is caused when a put
          aborted after a bucket split but before the record's POINTER
          entry  could  be  updated.   This  inconsistency is fixable;
          specify FIX rfa1.

     POINTER entry not found for rfa1

          The data record at rfa1 pointed back at an empty slot.  This
          should  not happen, but is fixable;  specify FIX rfa1.  This
          message may occur in conjunction with  "Access  ...   failed
          ..." messages.











                              CHAPTER 4

                     FORMAT OF AN RMS RECORD FILE



An RMS record file consists of a prologue section and a data  section.
The  prologue section is the repository of the file's attributes.  The
data section contains your records (and indexes if applicable).



4.1  PROLOGUE SECTION

The prologue section of an RMS file contains  a  file  descriptor.   A
file descriptor contains all the permanent attributes you specified in
the DEFINE FILE command or in your program (the DEFINE FILE command is
described  in  Chapter  3).  An indexed file also contains one or more
key descriptors and  one  or  more  area  descriptors,  including  the
descriptor of area 0, which RMS creates.  There is a second difference
as well.  In nonindexed files, the data  section  immediately  follows
the  prologue.   In indexed files, the data section starts at the next
page boundary.

The two types of fields in descriptors are argument block  fields  and
RMS-created  fields.  File attributes are specified to RMS when a file
is created.  They are specified in argument  blocks  called  FABs  and
XABs (file and extended argument blocks).



4.1.1  File Descriptor For File Argument Block (FAB)

A  file  descriptor  contains  the  following  FAB  information.   The
field-names recognized by RMSUTL are given.

     o   BUCKET-SIZE    represents the unit of I/O for the  file,  and
                        it  is  specified  in terms of pages (1 page =
                        512 words).

     o   BYTE-SIZE      is the number of bits per byte in  records  in
                        this  file.  It must be 6, 7, or 9 for indexed
                        files, 7 for stream  files,  and  not  greater
                        than 36 for relative and sequential files.
FORMAT OF AN RMS RECORD FILE                                  Page 4-2


     o   RECORD-SIZE    If the record format is variable,  this  field
                        is  the maximum number of bytes that can be in
                        a record in the file.  If you try to  write  a
                        record  whose size is larger than RECORD-SIZE,
                        an error status is returned and the record  is
                        not  written.   However this check is bypassed
                        if RECORD-SIZE is 0.

                        If record format is fixed length,  RECORD-SIZE
                        is  the  number of bytes in each record in the
                        file.  If you perform an output operation  and
                        do  not  set  record  size  to  the  value  of
                        RECORD-SIZE, RMS does not write the record and
                        returns an error.

     o   ORGANIZATION   is SEQUENTIAL, RELATIVE, or INDEXED.

     o   FORMAT         is either FIXED or VARIABLE.


A file descriptor also contains:

     o   AREA-COUNT     is the number of areas defined for the file.

     o   AREA-OFFSET    is  the  number  of  words  in  the   prologue
                        preceding the first area descriptor.

     o   KEY-COUNT      is the number of keys defined for the file.

     o   KEY-OFFSET     is  the  number  of  words  in  the   prologue
                        preceding the first key descriptor.

     o   PAGES-IN-FILE  is the number of pages currently in the file.



4.1.2  Key Descriptor For Extended Argument Block (XAB)

A key descriptor contains all the field-names of a KEY XAB:

     o   DATA-AREA      This field must equal the  ID  field  of  some
                        AREA descriptor.  RMS assigns the data buckets
                        for this key to that  area  and  thereby  sets
                        their bucket size.  Note that, for the primary
                        key, the data buckets contain user data;  and,
                        for  secondary  keys, they contain the keys by
                        themselves.  If DATA-AREA is  0,  the  default
                        area  is  used,  and  its bucket size is taken
                        from  the  BUCKET-SIZE  field  of   the   file
                        descriptor.
FORMAT OF AN RMS RECORD FILE                                  Page 4-3


     o   DATA-FILL      provides a means of spreading out the data  in
                        a  file  when  you  first load the file.  This
                        field is used to indicate the number of  words
                        that can be used in a data bucket when loading
                        this key's data buckets.  For example,  if  it
                        is desirable that buckets be no more than half
                        full and the bucket size is  1  (=512  words),
                        this  field would be set to 256.  If DATA-FILL
                        is 0, the entire bucket can be filled.

     o   DATA-TYPE      determines the byte size RMS uses  to  compare
                        keys.   Therefore,  it must be set so that key
                        byte size matches the BYTE-SIZE field  of  the
                        file  descriptor.   It  should  be  SIXBIT for
                        6-bit bytes.  It should  be  ASCII  for  7-bit
                        bytes.  It should be EBCDIC for 9-bit bytes.

     o   ATTRIBUTES     The ATTRIBUTES field controls the handling  of
                        keys  during  put  and update operations.  The
                        "changeable" attribute means  you  can  change
                        the  value  of  this  key  when  you  update a
                        record.  "Changeable" can not be specified for
                        the  primary  key.  The "duplicates" attribute
                        means that multiple records in  the  file  can
                        contain  the  same value of this key.  Records
                        having duplicate keys are stored in  the  file
                        so that sequential retrieval of them is in the
                        order in which they were stored.

     o   INDEX-AREA     must  equal  the  ID  field   of   some   AREA
                        descriptor.   It assigns the index buckets for
                        this key to that area and thereby  sets  their
                        bucket  size.  If INDEX-AREA is 0, the default
                        area is used, and its  bucket  size  is  taken
                        from   the   BUCKET-SIZE  field  of  the  file
                        descriptor.

     o   INDEX-FILL     provides a means of spreading  out  the  index
                        data  in  a file when you first load the file.
                        This field is used to indicate the  number  of
                        words that can be used in an index bucket when
                        loading  this  key's   index   buckets.    For
                        example, if it is desirable that index buckets
                        be no more than half full and the bucket  size
                        is  1 (=512 words), this field would be set to
                        256.  If INDEX-FILL is 0,  the  entire  bucket
                        can be filled.
FORMAT OF AN RMS RECORD FILE                                  Page 4-4


     o   KEY-OF-REFERENCE 

                        contains a number  that  indicates  which  key
                        this  is:   0  for  the primary key, 1 for the
                        first secondary key, and so on.

     o   POSITIONs      define  the  starting  byte  number  of   each
                        segment  of  this key.  Each starting position
                        is paired with the corresponding  size  value.
                        A  key  has between one and eight segments.  A
                        size  field  containing  0  implies  that  the
                        preceding  segment was the last.  Key segments
                        are   logically   concatenated   to   form   a
                        particular key value.

     o   SIZEs          define the number of bytes in each segment  of
                        this  key.  Each size value is paired with the
                        corresponding starting position.   A  key  has
                        between  one and eight segments.  A size field
                        containing  0  implies  that   the   preceding
                        segment   was  the  last.   Key  segments  are
                        logically concatenated to  form  a  particular
                        key  value.   The sum of the specified segment
                        sizes must be less than 256 characters.

A key descriptor also contains the following:

     o   LEVELS         is the number of levels in this key's index.

     o   NEXT-KEY       is the offset of the next  key  descriptor  in
                        the prologue.

     o   ROOT-PAGE      is the page number where the root  bucket  for
                        this key's index is located.


An indexed file can have from 1 to 17 areas.   Area  0  is  implicitly
defined  by  RMS.   The  bucket  size  of  area  0  is  taken from the
BUCKET-SIZE field of the file descriptor.   BUCKET-SIZE  is  the  only
field in an area descriptor.



4.2  DATA SECTION OF SEQUENTIAL AND RELATIVE FILES

Records may cross bucket boundaries in a sequential or relative  file.
The  only  control  information  in  the  data  section  of these file
organizations is the record header.  A sequential or  relative  record
header consists of one word, and its format is:
FORMAT OF AN RMS RECORD FILE                                  Page 4-5


     o   ATTRIBUTES     DELETED and  USED.   DELETED  is  set  if  the
                        record  is  deleted.   USED  is  set  when the
                        record  is  created.   RMS  checks   USED   to
                        determine  if it is past the EOF (end-of-file)
                        or scanning an empty cell in a relative file.

     o   SIZE           is the number of bytes in the record.



4.3  DATA SECTION OF AN INDEXED FILE

Figure 4-1 displays the relationship between a  primary  index  and  a
secondary  index.   Each  SIDR  points  at  the  user data record that
contains the same key value as in the SIDR.


                                PROLOGUE
                             ---------------
                             |             |
                             |     KEY     |
                             | DEFINITIONS |
                             |             |
                             ---------------
                                    |
                                    |
                                    |
                ---------------------------------------
                |                                     |
                |                                     |
                |                                     |
         ---------------                       ---------------
         |             |                       |             |
         |   PRIMARY   |                       |  SECONDARY  |
         |    INDEX    |                       |    INDEX    |
         |   BUCKETS   |                       |   BUCKETS   |
         |             |                       |             |
         ---------------                       ---------------
                |                                     |
                |                                     |
                |                                     |
         ---------------                       ---------------
         |             |                       |             |
         |     USER    |                       |    SIDR     |
         |     DATA    |<----------------------|             |
         |   BUCKETS   |                       |   BUCKETS   |
         |             |                       |             |
         ---------------                       ---------------

         <-------------------DATA BUCKETS-------------------->


                 Figure 4-1   RMS Record File Format
FORMAT OF AN RMS RECORD FILE                                  Page 4-6


4.3.1  Bucket Headers

Each bucket in an indexed file contains a header describing  its  type
and other properties.  A header contains the following fields:

     o   AREA-NUMBER    is the number of the area to which the  bucket
                        belongs.

     o   ATTRIBUTES     can be RIGHTMOST and  ROOT.   ROOT  identifies
                        the  bucket as the root of an index structure.
                        RIGHTMOST indicates that the  bucket  contains
                        the  highest  group of key values at its level
                        in the index structure.

     o   LAST-ID        is the largest entry ID that this  bucket  can
                        contain.  It is normally 2**17 - 1.

     o   LEVEL          is the number of levels between  the  bucket's
                        level  and  the data level.  Thus data buckets
                        are level 0.

     o   NEXT-BUCKET    is the page number of the next bucket at  this
                        level of the index structure, unless this is a
                        rightmost bucket.  In this  case,  it  is  the
                        page  number  of  the  leftmost bucket at this
                        level.

     o   NEXT-ID        is the ID that is to be assigned to  the  next
                        entry  stored  in this bucket.  An entry in an
                        index bucket does not have an ID.

     o   TYPE           can be INDEX or DATA.

     o   WORDS-IN-USE   is the number of  words  preceding  the  first
                        unused word in the bucket.



4.3.2  Entries in a Primary-Data Bucket

Most entries in a primary-data bucket are your records.  An entry  can
also be an internal pointer to a moved record.

The common fields in an entry are:

     o   ID             is  the  "address"  of  an  entry  within  its
                        bucket.
FORMAT OF AN RMS RECORD FILE                                  Page 4-7


     o   ATTRIBUTES     can be any  of  the  following  normal  cases.
                        DELETED means that the record has been deleted
                        and that RMS will expunge it  when  reclaiming
                        space  in the bucket.  DELETED+KEEP means that
                        the record has been deleted and that the  only
                        way   to  expunge  it  is  with  RMSUTL.   NIL
                        indicates   an   existing   record.    POINTER
                        indicates  an  entry  that  points at a record
                        that has been moved because of a bucket split.

The additional fields in a RECORD entry are:

     o   DATA           is the contents of the record.

     o   RFA            is the address in the file  where  the  record
                        was  originally  stored.  The record can still
                        be there, but if it is not,  there  is  now  a
                        POINTER entry there.

     o   SIZE           is the number of bytes of data in the  record.
                        This  field  is  present only if record-format
                        for the file is variable.

The additional fields in a POINTER entry are:

     o   RFA            is the address in the file  where  the  record
                        was last moved to.



4.3.3  Entries in an Index Bucket

An entry in an index bucket contains the following fields:


     o   ATTRIBUTES     are HIKEY or NIL.  HIKEY is on if  this  entry
                        points  to  the  bucket containing the highest
                        key value at its level in the index.

     o   DOWN-POINTER   is the page number of the  bucket  whose  keys
                        are  all  less  than  or equal to the value in
                        KEY-VALUE.  Also, the lowest key value in  the
                        pointed-to  bucket  is always greater than the
                        KEY-VALUE in the preceding entry.

     o   KEY-VALUE      RMS uses the KEY-VALUE field to determine  the
                        DOWN-POINTER  to follow down an index during a
                        key  access.   Index  entries  are  sorted  in
                        ascending  order by KEY-VALUE, so RMS uses the
                        DOWN-POINTER for  the  first  KEY-VALUE  field
                        that is greater than or equal to the key value
                        presented by the user.
FORMAT OF AN RMS RECORD FILE                                  Page 4-8


4.3.4  Entries in a Secondary-Data Bucket

Secondary-data buckets maintain the  sorted  ordering  of  keys  in  a
secondary  index and are the link between secondary key values and the
various records that contain them.  An  SIDR  contains  the  following
fields:

     o   ID             is the address of the entry within its bucket.

     o   KEY-VALUE      contains the key value upon which the entry is
                        sorted.

     o   RFA 1 - RFA n  identify the records whose  key  values  match
                        the  value  in  KEY-VALUE.  These pointers are
                        not modified when a record is moved  during  a
                        bucket split.  Thus, they may point at POINTER
                        entries, which  in  turn  point  at  the  data
                        records.

                        When a record is  deleted,  RMS  locates  each
                        SIDR  that  points  at the record and sets the
                        relevant RFA in each to NIL.  When a secondary
                        key value of a record is modified, RMS locates
                        the SIDR containing the old key value and sets
                        the relevant RFA to NIL.

     o   SIZE           is the number of words used to  hold  the  KEY
                        field and all the RFA fields.











                              CHAPTER 5

                           RMS STATUS CODES



Normally RMSUTL, the COBOL OTS,  and  BASOTS  transform  status  codes
returned  by  RMS  into  responses that do not involve telling you the
actual  code.   However,  it  is  possible  for  an   unprogrammed-for
condition  to  occur,  in  which case COBOL OTS and BASOTS display the
underlying RMS status code.

There are two types of status codes which are returned by RMS:

     1.  ER$ - error codes 

     2.  SU$ - success codes

Error codes are larger than success codes, and the minimum error  code
is  ER$MIN.   Thus,  if  RMS  returns  a code greater than or equal to
ER$MIN, it must be an error code.  All status codes are represented by
a  mnemonic  symbol  preceded  by  a  two-character  string indicating
whether the code is a success or error code.

ER$MIN may change in the future, but it  is  currently  300000  octal.
SU$MIN (success minimum code) may also change in the future, but it is
currently 1000 octal.  However, the relative  value  of  status  codes
with respect to SU$MIN and ER$MIN will not change.

The following table names and describes each of the RMS status  codes.
If  an  STV (subsidary status value) value is associated with an error
status, its meaning is also described.  The VALUE field is the  status
code's offset in decimal (and octal) from xx$MIN.
RMS STATUS CODES                                              Page 5-2


                              Table 5-1

                           RMS Status Codes


NAME     VALUE                          MEANING


SU$SUC     0            Operation was successful.

SU$IDX     1            Index  could  not  be   updated   because   an
                        unexpected  error  (for example, I/O) occurred
                        while updating the index.  This  is  precisely
                        the   state  an  indexed  file  is  in  if  an
                        ill-timed crash occurs.  The record  is  still
                        accessible  but efficiency can be affected, so
                        you should consider  reorganization  (use  the
                        UNCLUTTER command or reload the file).

SU$REO     2            File should be reorganized because RMS  needed
                        to  insert  a record into a bucket that has no
                        more record IDs  available.   This  can  occur
                        only  if  a  large number of deletes, updates,
                        and puts are done to a  bucket  because  there
                        are  2**17-1  IDs  available per bucket.  This
                        status is  returned  both  on  the  $PUT  that
                        caused the status and when the file is closed.

SU$RRV     3            An  internal  record  pointer  could  not   be
                        updated.   This  state  can  be  reached  as a
                        result of a crash  during  $PUT  and  $UPDATE.
                        This status code merely shows a case where the
                        state has been reached.  It shows that one  or
                        more  records  can  not  be  accessible by its
                        secondary   key,   or   by   RFA   addressing.
                        Reorganization    is   suggested,   (use   the
                        UNCLUTTER command or reload the file).

SU$DUP     4            A record was $PUT or $UPDATE, and one or  more
                        of  its  key values was in a record already in
                        the file.  SU$DUP applies rather  than  ER$DUP
                        because XB$DUP was set for each such key.
RMS STATUS CODES                                              Page 5-3


ER$AID     0            AID field in AREA XAB is not greater than  AID
                        field  in  preceding  AREA  XAB, or it is 0 or
                        greater than 16.  STV contains the address  of
                        the bad XAB.

ER$BKZ     4            BKZ in AREA XAB is 0 or greater than  7.   STV
                        contains the address of the bad XAB.

ER$BLN     5            BLN value in argblk is  not  correct  for  the
                        specified BID value.

ER$BSZ     6            BSZ is not 7 for stream file or BSZ  is  0  or
                        greater than 36 for some other file type.

ER$BUG     7            Internal  error  detected  in  RMS.   If   the
                        internal   error   was  caused  by  a  monitor
                        detected condition, the STV field contains the
                        monitor error code.

ER$CCF     8 (10)       Can't $CLOSE file.  An unusual condition arose
                        that  prevented  RMS  from  closing  the file.
                        Check the STV  field  for  the  monitor  error
                        code.

ER$CCR     9 (11)       Can't $CONNECT  RAB  because  another  RAB  is
                        already connected to the indicated file.

ER$CEF     11 (13)      Can't $ERASE file.  RMS could not erase a file
                        for  an  unknown  reason.  Check the STV field
                        for the monitor error code.

ER$CGJ     12 (14)      Can't get a JFN for this file for  an  unknown
                        reason.   Check  the STV field for the monitor
                        error code.

ER$CHG     13 (15)      Illegal key value change.  An $UPDATE was done
                        in  which the value of a particular key in the
                        record was changed, and the  key  was  defined
                        without  the  XB$CHG  attribute.  STV contains
                        the key  of  reference  of  the  improper  key
                        value.  If there is more than one improper key
                        value, the lowest key of reference  is  placed
                        in STV.

ER$COD     14 (16)      COD field in XAB not XA$ALL,  XA$DAT,  XA$KEY,
                        or  XA$SUM.   STV  contains the address of the
                        bad XAB.

ER$COF     15 (17)      Can't open  file.   Caused  by  an  unexpected
                        error  when RMS tried to open the file.  Check
                        the STV field for the monitor error code.
RMS STATUS CODES                                              Page 5-4


ER$CUR     16 (20)      No  current  record.   Caused  by  a  $UPDATE,
                        $TRUNCATE, or $DELETE that was not preceded by
                        a successful $FIND or $GET operation.

ER$DAN     17 (21)      DAN field of KEY XAB contained  value  greater
                        than  your  highest area ID.  STV contains the
                        address of the bad XAB.

ER$DEL     18 (22)      A record accessed with RFA addressing has been
                        deleted since you saved the RFA.

ER$DEV     19 (23)      Device not disk (RMS-10), device not  disk  or
                        terminal  (RMS-20),  or  device  not  disk  on
                        $CREATE.

ER$DME     22 (26)      Dynamic  memory  exhausted.   RMS  could   not
                        allocate temporary storage for buffers, and so
                        on.  If you set MBF to a large value  on  your
                        $CONNECTs,  you  might  try  using  a  smaller
                        value.

ER$DTP     23 (27)      DTP field in KEY XAB is not XB$SIX, XB$STG, or
                        XB$EBC,  or  BSZ in FAB is not respectively 6,
                        7, or 9.  STV contains the address of the  bad
                        XAB.

ER$DUP     24 (30)      A record was $PUT or $UPDATE, and one or  more
                        of  its  key values was in a record already in
                        the file.  ER$DUP applies rather  than  SU$DUP
                        because XB$DUP was not set for some of them.

ER$EDQ     25 (31)      ENQ/DEQ monitor error.  An attempt to (un)lock
                        a  record  (or file) resulted in an unexpected
                        error from the monitor.  Check the  STV  field
                        for the monitor error code.

ER$EOF     26 (32)      You sequentially read ($FIND or $GET) past the
                        last record in the file or index.

ER$FAB     27 (33)      BID field of FAB did not contain FA$TYP.

ER$FAC     28 (34)      The file  access  field  in  the  FAB  is  not
                        compatible with what you did.

                        1.  Occurs if FB$PUT not set on a $CREATE.

                        2.  Occurs if a record operation ($GET,  $PUT,
                            ...)  is  attempted with the corresponding
                            FAC bit not set.
RMS STATUS CODES                                              Page 5-5


ER$FEX     29 (35)      You tried to $CREATE  an  existing  file,  and
                        FB$CIF and FB$SUP were both off.

ER$FLG     30 (36)      XB$CHG was set for primary key.  STV  contains
                        the address of the bad XAB.

ER$FLK     31 (37)      File already locked.  Someone else has already
                        opened  and  locked  the  file  with an access
                        incompatible with the access you requested.

ER$FNC     33 (41)      You cannot $ERASE a file when anyone else  has
                        it open.  Just wait and try again.

ER$FNF     34 (42)      File not found.  The file name  you  specified
                        by FNA did not identify any file.

ER$FSI     96 (140)     File  spec  on  $CREATE,  $ERASE,   or   $OPEN
                        contained  illegal  syntax  of  some sort (for
                        example, two directory specs).

ER$FUL     37 (45)      An RMS file can be no larger than 256K pages.

ER$IAL     38 (46)      Illegal argument on call.

ER$IAN     39 (47)      IAN field of KEY XAB contained  value  greater
                        than  your  highest area ID.  STV contains the
                        address of the bad XAB.

ER$IFI     43 (53)      The IFI field did  not  identify  an  internal
                        file  block.   This  is  normally  caused by a
                        $CLOSE or $DISPLAY on a FAB that has not  been
                        correctly opened.

ER$IMX     45 (55)      Multiple SUMMARY or DATE XABS appeared  in  an
                        XAB  chain on $OPEN or $DISPLAY.  STV contains
                        the address of the bad XAB.

ER$ISI     48 (60)      The ISI field did  not  identify  an  internal
                        record  block.   This  is normally caused by a
                        record operation on a RAB that  has  not  been
                        correctly connected.

ER$JFN     49 (61)      On $OPEN or $CREATE or $ERASE, you specified a
                        nonzero  JFN to RMS-10, or you specified a JFN
                        that  TOPS-20  did  not  recognize,   or   you
                        specified the JFN of an open file.

ER$KBF     50 (62)      You did a $FIND or  $GET  with  RAC  equal  to
                        RB$KEY, but did not set KBF.
RMS STATUS CODES                                              Page 5-6


ER$KEY     51 (63)      KBF on a key access to a relative file pointed
                        to  a  zero  or  a number greater than the MRN
                        value for the file.

ER$KRF     52 (64)      You specified an incorrect  key  of  reference
                        for an indexed file.  This can happen on a key
                        $GET, key $FIND, or $CONNECT that specified  a
                        KRF  greater  than the highest key defined for
                        the file.

ER$KSZ     53 (65)      You specified a KSZ value on a random $GET  or
                        random  $FIND that is greater than the defined
                        length of the key.

ER$MRS     56 (70)      Invalid MRS value on a $CREATE,  caused  by  a
                        value  of  zero  when  RFM is FB$FIX or ORG is
                        FB$REL.

ER$NEF     57 (71)      Not at end of file.  Caused by an  attempt  to
                        $PUT into the middle of a sequential file.

ER$NPK     59 (73)      No primary  key.   Caused  by  an  attempt  to
                        $CREATE  an indexed file without specification
                        of a primary key.  In other words,  first  KEY
                        XAB in chain had a nonzero REF field.

ER$NXT     60 (74)      Incorrect value of NXT field and  XAB,  caused
                        by an address in the range 1-17.  STV contains
                        the address of the bad XAB.

ER$ORD     61 (75)      Either KEY or AREA XABS are not  in  ascending
                        order   with   respect   to   their  ID  field
                        (respectively REF and AID).  STV contains  the
                        address of the bad XAB.

ER$ORG     62 (76)      ORG was not FB$SEQ, FB$REL,  or  FB$IDX  on  a
                        $CREATE.

ER$PEF     63 (77)      Can't position to EOF.  Caused by RB$EOF being
                        set on $CONNECT of nonsequential file.

ER$PRV     66 (102)     Privilege Violation.  Caused by an attempt  to
                        open  file for access for which you don't have
                        the rights.

ER$RAB     68 (104)     BID field of RAB did not contain RA$TYP.

ER$RAC     69 (105)     RAC was not RB$SEQ, RB$KEY,  or  RB$RFA  on  a
                        $FIND or $GET, or RAC was not RB$SEQ or RB$KEY
                        on a $PUT.
RMS STATUS CODES                                              Page 5-7


ER$RAT     70 (106)     You  specified  an  invalid  RAT  value  on  a
                        $CREATE.   RAT  was nonzero and not FB$BLK, or
                        it was FB$BLK for a stream file.

ER$RBF     71 (107)     RBF was not set up on a $PUT or an $UPDATE.

ER$REF     72 (110)     REF field in KEY XAB is not greater  than  REF
                        field  in  preceding KEY XAB, or it is greater
                        than 255.  STV contains the address of the bad
                        XAB.

ER$RFA     75 (113)     The RFA field on an RFA access contained  zero
                        or identified a never used cell.

ER$RFM     76 (114)     On a $CREATE, RFM was FB$LSA or FB$STM and ORG
                        was not FB$SEQ, or RFM was not FB$LSA, FB$STM,
                        FB$FIX, or FB$VAR.

ER$RLK     77 (115)     Record locked.  Caused by an attempt to access
                        a  record  that is currently locked by another
                        process.

ER$RNF     78 (116)     Record  not  found  occurs  in  the  following
                        situations:

                        1.  Key $FIND or key $GET to cell in  relative
                            file  that  is empty or contains a deleted
                            record.

                        2.  Exact key access.  There is no record with
                            the specified key value.

                        3.  Generic key  access  There  is  no  record
                            whose  key  starts  with the specified key
                            value.

                        4.  (Generic)  approximate   key   access   is
                            attempted.   The  specified  key  value is
                            greater than (RB$KGE) or greater  than  or
                            equal  to  (RB$KGT)  for  any  key  in the
                            specified index.
RMS STATUS CODES                                              Page 5-8


ER$RSZ     84 (124)     RSZ not equal to size of record on $UPDATE, or
                        RSZ was not valid on $PUT:

                        1.  RFM is FB$FIX and RSZ is not equal to MRS.

                        2.  RSZ is greater than MRS.

                        3.  ORG is FB$IDX and RSZ is greater than  the
                            number of bytes in a data-record bucket.


ER$RTB     85 (125)     Move mode applied on a $GET, when  the  record
                        was  larger than the number of words specified
                        in USZ.  Note that RMS does fill your  buffer.
                        Check  the  STV  field for the number of bytes
                        actually in the record.

ER$SEQ     86 (126)     Keys out of sequence.  Caused by a  sequential
                        $PUT  to  an indexed file in which the primary
                        key value is not greater than the key value on
                        the   previous   $PUT.   This  restriction  is
                        enforced only if the last operation was also a
                        sequential $PUT.

ER$SIZ     87 (127)     The number of bytes in a key is 0  or  greater
                        than 255.  STV contains the address of the bad
                        XAB.

ER$UBF     90 (132)     UBF was not set up on a $CONNECT or a $GET.

ER$UDF     91 (133)     The file is in an undefined state  and  should
                        be  reorganized.   STV  contains  a  code that
                        further explains the state of  the  file  (see
                        Table 5-2).

ER$XAB     94 (136)     BID field of XAB did not contain XA$TYP.   STV
                        contains the address of the bad XAB.
RMS STATUS CODES                                              Page 5-9


The following table describes the STV values for  ER$UDF.   The  VALUE
field is an offset from ER$MIN.



                              Table 5-2

                        STV Values for ER$UDF


NAME         VALUE                      MEANING


ER$RRV     81  (121)    Bad internal  record  pointer  encountered  in
                        file.

FE$BEM     320 (500)    Empty index bucket detected.

FE$BFC     321 (501)    Bad file class found in file FDB.

FE$BHE     322 (502)    Bucket header has bad format.

FE$HNF     327 (507)    File prologue header was not found.

FE$NOA     328 (510)    No area descriptors were found in the file.

FE$NOI     329 (511)    No index descriptors were found in the file.

FE$NOU     332 (512)    No data record  found  for  RFA  in  secondary
                        index.











                             APPENDIX A

         USAGE OF AN RMS FILE FROM BOTH BASIC+2 AND COBOL-74





                            (TOPS-20 ONLY)


When you create an RMS file to be used by both BASIC+2  and  COBOL-74,
you should observe the following rules:

     1.  The file must be indexed and its keys must be ASCII.

     2.  A record may contain only:

                COBOL                   BASIC

               DISPLAY-7                NAME$
               COMPUTATIONAL            NAME%
               INDEX                    NAME%
               COMPUTATIONAL-1          NAME


     3.  A COBOL record may not contain a group-level field  that  has
         an OCCURS clause.  

     4.  There must be no usage of the JUSTIFY or SYNC keywords.

     5.  You must declare fields in the same order, set string lengths
         the same, and set array bounds the same.


All the file parameters established  by  COBOL  can  be  processed  in
BASIC+2 Version 2.1 or later.

All  the  indexed  file  parameters  established  by  BASIC+2  can  be
processed  by  COBOL.   However,  full  compatibility is achieved only
when:

     o    The file is defined with  duplicates  not  allowed  for  the
          primary key.

     o    Changes are allowed for all secondary keys.
USAGE OF AN RMS FILE FROM BOTH BASIC+2 AND COBOL-74            Page A-2


If the primary key is defined such that duplicates  are  allowed,  you
must  have  a  DECLARATIVE  procedure  to  intercept  the  error COBOL
generates for this condition.  For example,




        ENVIRONMENT DIVISION.
        FILE-CONTROL.
                SELECT RMS-FILE ASSIGN TO DSK;
                        .
                        .
                        .
                FILE STATUS IS FS-1, FS-2, ACTION-CODE.
                        .
                        .
                        .
        DATA DIVISION.
                .
                .
                .
        01      FS-1    PIC 99.
        01      FS-2    PIC 9(10).
        01      FS-2-IMAGE      REDEFINES FS-2.
                02      FILLER  PIC X(7).
                02      ERR-CODE        PIC X(3).
        01      ACTION-CODE     INDEX.
                .
                .
                .
        PROCEDURE DIVISION.
        DECLARATIVES.
        OPEN-ERROR SECTION.
                USE AFTER STANDARD ERROR PROCEDURE ON RMS-FILE.
        OPEN-ERROR-1.
                IF ERR-CODE = "523"
                        MOVE 1 TO ACTION-CODE.
        OPEN-ERROR-EXIT.
                EXIT.
        END DECLARATIVES.
                .
                .
                .
        Paragraph-name.  or  Section-name SECTION.
                remainder of PROCEDURE DIVISION
USAGE OF AN RMS FILE FROM BOTH BASIC+2 AND COBOL-74            Page A-3


If a file defined in BASIC+2  has  a  secondary  key  defined  without
changes  allowed,  you  can  use  the  file  freely  in COBOL with one
exception.  To detect an attempt (by a terminal operator for  example)
to  update  the key, you must have a DECLARATIVE procedure that checks
for an error code (ERR-CODE) of 506.  Alternatively you can  eliminate
the problem by using RMSUTL to make all such keys changeable.  See the
description of the CHANGE PROLOG command in section 3.6.1.









                             INDEX


Access,                            Bucket (Cont.)
  key, 2-6                           entries in secondary-data,
  random, 1-3                          4-8
Access efficiency,                 Bucket headers, 4-6
  key, 2-8                         BUCKET-SIZE, 4-1
  write, 2-10                      /BUCKET-SIZE: switch, 3-13
Access methods, 1-2                Buckets,
Access, 1-3                          data, 2-7
  random, 2-3                        index, 2-7
  sequential, 1-3                    primary-data, 2-8
Access to indexed files,             secondary-data, 2-7
  key, 2-4                         BYTE-SIZE, 4-1
  sequential, 2-4                  /BYTE-SIZE: switch, 3-13
Access to relative files,
  random, 2-3
  sequential, 2-3
Address,                           Cell,
  format of record file,             record, 2-3
    2-8                            CHANGE BUCKET command, 3-8
/APPEND switch, 3-22               CHANGE command, 3-8
Area, 1-3                          CHANGE PROLOGUE-DATA
AREA-COUNT, 4-2                        command, 3-7
AREA-NUMBER, 4-6                   /CHANGES-ALLOWED switch,
AREA-OFFSET, 4-2                       3-14
Argument block,                    Clause,
  extended, 4-2                      records-to-use, 3-32
  file, 4-1                        CLOSE REPORT command, 3-10
ATTRIBUTES, 4-3, 4-5, 4-6,         CLOSE RMS-FILE command,
    4-7                                3-10
Attributes,                        COBOL-74 file,
  defining file, 3-13                usage of RMS, A-1
                                   Codes,
                                     ER$ error, 5-1
                                     RMS status, 5-1, 5-2
BASIC+2 file,                        SU$ success, 5-1
  usage of RMS, A-1                Command,
Block,                               CHANGE, 3-8
  extended argument, 4-2             CHANGE BUCKET, 3-8
  file argument, 4-1                 CHANGE PROLOGUE-DATA, 3-7
Bucket, 1-3                          CLOSE REPORT, 3-10
  current, 3-4                       CLOSE RMS-FILE, 3-10
  entries in index, 4-7              DEFINE AREA, 3-15
  entries in primary-data,           DEFINE DATAFIELD, 3-11
    4-6                              DEFINE FILE, 3-13


                            Index-1


                             INDEX (CONT.)


Command (Cont.)                    Data section of indexed
  DEFINE KEY, 3-14                     files, 4-5
  DELETE BUCKET-ENTRY, 3-16        Data section of relative
  DELETE RECORD, 3-16                  files, 4-4
  DISPLAY BUCKET, 3-18             Data section of sequential
  DISPLAY DATA, 3-18                   files, 4-4
  DISPLAY PROLOGUE-DATA,           DATA-AREA, 4-2
    3-17                           DATA-FILL, 4-3
  EXIT, 3-31                       DATA-TYPE, 4-3
  FIX, 3-19                        DEFINE AREA command, 3-15
  HELP, 3-31                       DEFINE DATAFIELD command,
  INFORMATION, 3-20                    3-11
  OPEN RMS-FILE, 3-21              DEFINE FILE command, 3-13
  REDEFINE, 3-23                   DEFINE KEY command, 3-14
  SET BUCKET, 3-24                 Defining file attributes,
  SET RECORD, 3-26                     3-13
  SPACE, 3-27                      DELETE BUCKET-ENTRY command,
  TAKE, 3-31                           3-16
  UNCLUTTER, 3-28                  DELETE RECORD command, 3-16
  VERIFY, 3-29                     Descriptions,
Command descriptions, 3-5            command, 3-5
Command format, 3-1                Determining number of
Command status, 3-2                    levels, 2-8
Commands,                          DISPLAY BUCKET command,
  file-scanning, 3-4                   3-18
  secondary, 3-31                  DISPLAY DATA command, 3-18
Commannd,                          Display output, 3-33
  SET INDEX, 3-25                  DISPLAY PROLOGUE-DATA
Comnmand,                              command, 3-17
  OPEN REPORT, 3-22                /DISPLAY: switch, 3-12
Completion messages, 3-34          DOWN-POINTER, 4-7
Concepts,                          /DUPLICATES-ALLOWED switch,
  RMS, 1-3                             3-15
Conditions,
  fixable, 3-35
Content,
  key, 2-5                         Efficiency,
Creating a file, 3-3                 indexed file, 2-8
Currency indicators, 3-4             key access, 2-8
Current bucket, 3-4                  write access, 2-10
Current key, 3-4                   Entries in index bucket,
Current record, 3-4                    4-7
                                   Entries in primary-data
                                       bucket, 4-6
                                   Entries in secondary-data
/DAFILL: switch, 3-14                  bucket, 4-8
/DANAME: switch, 3-14              Entry, 1-3
DATA, 4-7                            fields in POINTER, 4-7
Data buckets, 2-7                    fields in RECORD, 4-7
Data in a file,                    ER$ error codes, 5-1
  manipulating, 3-3



                            Index-2


                             INDEX (CONT.)


ER$UDF,                            File-scanning output, 3-34
  STV values for, 5-9              Files,
Error codes,                         data section of indexed,
  ER$, 5-1                             4-5
EXIT command, 3-31                   data section of relative,
Extended argument block,               4-4
    4-2                              data section of
                                       sequential, 4-4
                                     indexed, 2-3
                                     key access to indexed,
FAB,                                   2-4
  file descriptor for, 4-1           properties of record, 2-1
Facilities,                          random access to relative,
  RMS, 1-2                             2-3
Field,                               relative, 2-2
  SIDR ID, 4-8                       sequential, 2-1
  SIDR KEY-VALUE, 4-8                sequential access to
  SIDR RFA, 4-8                        indexed, 2-4
  SIDR SIZE, 4-8                     sequential access to
Fields in POINTER entry,               relative, 2-3
    4-7                              stream, 1-2
Fields in RECORD entry, 4-7        FIX command, 3-19
File,                              Fixable conditions, 3-35
  creating a, 3-3                  FORMAT, 4-2
  keys in indexed, 2-6             Format,
  manipulating data in a,            command, 3-1
    3-3                              RMS record file, 4-5
  report, 3-33                     Format of record file
  RMS record, 4-1                      address, 2-8
  usage of RMS BASIC+2, A-1        Format of RMS record file,
  usage of RMS COBOL-74,               4-1
    A-1                            /FORMAT: switch, 3-14
File address,                      Formats,
  format of record, 2-8              records-to-use, 3-32
File argument block, 4-1
File attributes,
  defining, 3-13
File descriptor for FAB,           Headers,
    4-1                              bucket, 4-6
File efficiency,                   HELP command, 3-31
  indexed, 2-8                     High-bound,
File format,                         records-to-use, 3-32
  RMS record, 4-5
File management utility,
  RMS, 3-1
File manipulation, 3-3             /IAFILL: switch, 3-15
File operations, 1-2               /IANAME: switch, 3-15
File organization, 1-3             ID, 1-3, 4-6
  relative, 2-2                    Index,
  sequential, 2-1                    shaping your, 2-10
File scanning, 3-4                 Index bucket,
File-scanning commands, 3-4          entries in, 4-7


                            Index-3


                             INDEX (CONT.)


Index buckets, 2-7                 Manipulating data in a file,
INDEX-AREA, 4-3                        3-3
INDEX-FILL, 4-3                    Manipulation,
Indexed file,                        file, 3-3
  keys in, 2-6                     Matches,
Indexed file efficiency,             key, 2-4
    2-8                            /MAXIMUM-RECORD-SIZE:
Indexed files, 2-3                     switch, 3-21
  data section of, 4-5             Messages,
  key access to, 2-4                 completion, 3-34
  sequential access to, 2-4          scan-result, 3-34, 3-35
Indexes, 2-5                       Methods,
Indicators,                          access, 1-2
  currency, 3-4                    Mode,
INFORMATION command, 3-20            access, 1-3
Introduction RMS, 1-1                random access, 2-3
                                     sequential access, 1-3


Key,
  current, 3-4                     NEXT-BUCKET, 4-6
KEY,                               NEXT-ID, 4-6
  records-to-use, 3-32             NEXT-KEY, 4-4
Key access, 2-6                    /NOACCESS switch, 3-30
Key access efficiency, 2-8         /NODISPLAY switch, 3-31
Key access to indexed files,       /NOFIX switch, 3-30
    2-4                            Number,
Key content, 2-5                     relative record, 2-2
Key descriptor for XAB, 4-2        Number of levels,
Key matches, 2-4                     determining, 2-8
KEY-COUNT, 4-2
KEY-OF-REFERENCE, 4-4
KEY-OFFSET, 4-2
KEY-VALUE, 4-7                     OPEN REPORT comnmand, 3-22
Keys,                              OPEN RMS-FILE command, 3-21
  storage of, 2-6                  Operations,
Keys in indexed file, 2-6            file, 1-2
                                     record, 1-2
                                   ORGANIZATION, 4-2
                                   Organization,
LAST-ENTRY,                          file, 1-3
  records-to-use, 3-33               relative file, 2-2
LAST-ID, 4-6                         sequential file, 2-1
LEVEL, 4-6                         Output,
LEVELS, 4-4                          display, 3-33
Levels,                              file-scanning, 3-34
  determining number of,           Overview record management,
    2-8                                1-1
Low-bound,                         Overview RMS, 1-1
  records-to-use, 3-32




                            Index-4


                             INDEX (CONT.)


PAGES-IN-FILE, 4-2                 Records-to-use low-bound,
POINTER entry,                         3-32
  fields in, 4-7                   Records-to-use
POSITION, 4-4                          RELATIVE-REC-NO, 3-33
Primary-data bucket,               Records-to-use value-test,
  entries in, 4-6                      3-32
Primary-data buckets, 2-8          REDEFINE command, 3-23
Progress reports, 3-34             Relative file organization,
/PROGRESS: switch, 3-28,               2-2
    3-30                           Relative files, 2-2
Prologue, 1-3                        data section of, 4-4
Prologue section, 4-1                random access to, 2-3
Properties of record files,          sequential access to, 2-3
    2-1                            Relative record number, 2-2
Properties of RMS, 2-1             RELATIVE-REC-NO,
                                     records-to-use, 3-33
                                   Report file, 3-33
                                   Reports,
Random access, 1-3                   progress, 3-34
Random access mode, 2-3            Results,
Random access to relative            scan, 3-34
    files, 2-3                     RFA, 1-3, 2-8, 4-7
Record,                            RMS,
  current, 3-4                       introduction, 1-1
Record cell, 2-3                     overview, 1-1
RECORD entry,                        properties of, 2-1
  fields in, 4-7                   RMS BASIC+2 file,
Record file,                         usage of, A-1
  format of RMS, 4-1               RMS COBOL-74 file,
  RMS, 4-1                           usage of, A-1
Record file address,               RMS concepts, 1-3
  format of, 2-8                   RMS facilities, 1-2
Record file format,                RMS file management utility,
  RMS, 4-5                             3-1
Record files,                      RMS record file, 4-1
  properties of, 2-1                 format of, 4-1
Record management,                 RMS record file format, 4-5
  overview, 1-1                    RMS status codes, 5-1, 5-2
Record number,                     RMS usage rules, A-1
  relative, 2-2                    RMSUTL, 3-1
Record operations, 1-2             RMSUTL rules, 3-1
RECORD-SIZE, 4-2                   ROOT-PAGE, 4-4
/RECORD-SIZE: switch, 3-14         Rules,
Records-to-use clause, 3-32          RMS usage, A-1
Records-to-use formats,              RMSUTL, 3-1
    3-32
Records-to-use high-bound,
    3-32
Records-to-use KEY, 3-32           Scan results, 3-34
Records-to-use LAST-ENTRY,         Scan-result messages, 3-34,
    3-33                               3-35



                            Index-5


                             INDEX (CONT.)


Scanning,                            /FORMAT:, 3-14
  file, 3-4                          /IAFILL:, 3-15
Secondary commands, 3-31             /IANAME:, 3-15
Secondary-data bucket,               /MAXIMUM-RECORD-SIZE:,
  entries in, 4-8                      3-21
Secondary-data buckets, 2-7          /NOACCESS, 3-30
Section,                             /NODISPLAY, 3-31
  prologue, 4-1                      /NOFIX, 3-30
Sequential access, 1-3               /PROGRESS:, 3-28, 3-30
Sequential access to                 /RECORD-SIZE:, 3-14
    indexed files, 2-4             
Sequential access to               
    relative files, 2-3            
Sequential file                    TAKE command, 3-31
    organization, 2-1              TYPE, 4-6
Sequential files, 2-1              
  data section of, 4-4             
SET BUCKET command, 3-24           
SET INDEX commannd, 3-25           UNCLUTTER command, 3-28
SET RECORD command, 3-26           Usage of RMS BASIC+2 file,
Shaping your index, 2-10               A-1
SIDR, 2-7                          Usage of RMS COBOL-74 file,
SIDR ID field, 4-8                     A-1
SIDR KEY-VALUE field, 4-8          Usage rules,
SIDR RFA field, 4-8                  RMS, A-1
SIDR SIZE field, 4-8               Utility,
SIZE, 4-4, 4-5, 4-7                  RMS file management, 3-1
SPACE command, 3-27                
Status,                            
  command, 3-2                     
Status codes,                      Value-test,
  RMS, 5-1, 5-2                      records-to-use, 3-32
Storage of keys, 2-6               Values for ER$UDF,
Stream files, 1-2                    STV, 5-9
STV values for ER$UDF, 5-9         VERIFY command, 3-29
SU$ success codes, 5-1             
Success codes,                     
  SU$, 5-1                         
Switch,                            WORDS-IN-USE, 4-6
  /APPEND, 3-22                    Write access efficiency,
  /BUCKET-SIZE:, 3-13                  2-10
  /BYTE-SIZE:, 3-13                
  /CHANGES-ALLOWED, 3-14           
  /DAFILL:, 3-14                   
  /DANAME:, 3-14                   XAB,
  /DISPLAY:, 3-12                    key descriptor for, 4-2
  /DUPLICATES-ALLOWED, 3-15







                            Index-6