Trailing-Edge - PDP-10 Archives - dbmsv5a - dbms5.doc
There are 2 other files named dbms5.doc in the archive. Click here to see a list.

DBMS.DOC -- Changes from V3 to V5
June 1977

Copyright (C) 1976,1977
Digital Equipment Corporation, Maynard, Mass.

This software is furnished under a license for use only  on  a  single
computer system and may be copied only with the inclusion of the above
copyright notice.  This software, or any other copies thereof, may not
be provided or otherwise made available to any other person except for
use on such system and to one  who  agrees  to  these  license  terms.
Title  to  and  ownership of the software shall at all times remain in

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

DEC assumes no responsibility  for  the  use  or  reliability  of  its
software on equipment which is not supplied by DEC.
DBMS5.DOC                                                       Page 2

DBMS.DOC -- Changes from V3 to V5
June 1977


DBMS-V5(240) replaces DBMS-V3 and DBMS-V4.

DBMS-V5 can co-exist with, and has been tested with, version 6.02 (and
6.03)  of  TOPS-10,  version  1B  (and  2)  of  TOPS-20, version 11 of
COBOL/LIBOL, and version 5 of FOROTS.  

Because both V3 and V4  users  will  be  reading  this  document,  the
changes  from V3 towards V5 have been partitioned into section 2.1 and
section 2.2 (V4 changes) and into section 2.3 (V5 changes) as much  as
is  feasible.   V5  is  a  compatible upgrade of V4;  however existing
DBMS-V3 applications must reload their data  bases  in  order  to  use
DBMS-V5.   This  conversion  procedure,  and  the  other  installation
instructions, are discussed in section 4.0.

The primary enhancements to DBMS-V5 are the following:

     1.  Support of sorted sets via indexed sequential access

     2.  Greatly improved performance in SCHEMA and DBCS

     3.  The OWNER IS SYSTEM clause

     4.  DBINFO as a replacement for DBSDMP and DBUTIL

     5.  Use of ENQ/DEQ to control access to areas

     6.  Much more comprehensive DMCL

     7.  The OCCURS phrase and additional data types

   V5 ONLY:

     8.  Simultaneous update of data bases

     9.  Various journaling enhancements

These and the other enhancements are discussed in  section  2.   Where
relevant,  incompatibilities  are  presented  in  order  of decreasing
importance.  However the incompatibilities presented  in  section  5.0
are   all   "benign"  in  the  sense  that  they  are  transparent  to
applications that  use  the  supported  functionality  of  DBMS-V5  as
defined in the documentation.  They are presented only in the interest
of thoroughness.
DBMS5.DOC                                                       Page 3



The primary enhancements to DBMS-10/20 are the following:

     1.  Support of sorted sets via indexed sequential access

     2.  Greatly improved performance in SCHEMA and DBCS

     3.  The OWNER IS SYSTEM clause

     4.  DBINFO as a replacement for DBSDMP and DBUTIL

     5.  Use of ENQ/DEQ to control access to areas

     6.  Much more comprehensive DMCL

     7.  The OCCURS phrase and additional data types

These and the other enhancements are discussed in section 2.1.

2.1  Functional Enhancements and Differences

2.1.1  The DMCL

The general form of  the  DMCL  is:   at  most  one  RECORDS-PER-PAGE,
JOURNAL,  IMAGES,  INTERCEPT,  and  NOTE  statement,  in  any order...
followed by one or more ASSIGN statements.

Incidental  change:    RPP   is   now   a   legal   abbreviation   for
RECORDS-PER-PAGE. File Specification


A file spec which appears in the DMCL must comform  to  the  following
rules.  Blanks, commas, and semi-colons are ignored as elsewhere.  The
allowed components may appear in any order and are  a  device-name,  a
file-name, and a project-programmer number.  The form of a device-name
is an alphanumeric followed by colon (:);  the form of a file-name  is
simply  an  alphanumeric;   and  the  form of a PPN is [<octal number>
<octal number>].  The default device is DSK:.  The default PPN is  the
current  path.   The  file-name component has no default value , being
always required.

For example, DSK:FILE[1,1].
DBMS5.DOC                                                       Page 4


All components except the  file-name  are  optional.   The  components
which  are present must conform to the following order and formatting:
"device:  <directory> filename Aaccount Pprotection".  The entire spec
must  not  exceed  100  characters.   The default device is DSK:.  The
default directory is the connected directory.

For example, <allmydbs>file. JOURNAL Statement -  When present,  this  statement  specifies
the  file  spec  that  this schema's journal file will have.  If it is
absent, SCHEMA simulates a JOURNAL statement in which  the  device  is
JRN and the file name is the schema-name.  The syntax of the statement
                       JOURNAL [IS] file-spec. IMAGES Statement -  This statement  serves  to  delineate  the
granularity  of  journaling  that  will  occur in an application.  The
syntax of this statement is:
                 IMAGES [NOT] [IN ORDER] BY COMMAND.

The default is for images to be ordered by command.  When  images  are
ordered  by  command,  the  buffers  of  each  open area are in effect
checkpointed after execution of each DML  updating-verb.   This  means
that  "more"  writing is done to the data base and to the journal--but
conversely that the data base can be backed up in increments of single DBMEND and at run-time.

When one requests images to not be ordered by  command,  checkpointing
occurs  only after each user-specified transaction (ie.  during a call
to JETRAN).  Thus "less" writing is done to the data base and  to  the
journal--but  conversely  the  data  base  can  be  backed  up only in
increments of user  DBMEND  and  as  importantly  at
run-time.   The  mechanism  of  per-transaction  database  backup, the
JBTRAN call, is presented in subsection

(The CODASYL DBMS specification states that, when an exception  occurs
during execution of a DML updating-verb, the DBCS must return the data
base to the state it was in at the beginning  of  the  verb.   However
this  is  somewhat  expensive as implied above.  Consequently, what we
are doing is allowing the programmer to decide.   By  specifying  that
images  are not ordered by command, the programmer will be saying, "It
benefits me to decrease  the  cost  of  journaling  even  though  that
reduces  the  control  with  which  I can backup my data base and even
though  that  reduces  exception  transparency  with  respect  to  the
validity of a data base".)

There are certain applications which have to backup completely if  the
application aborts for any reason.  Such an application should specify
that images are not ordered by command since, even  if  there  are  no
user  transactions  or  command-ordering,  DBMEND  always allows total
backup via:  "START<CRLF>...  END<CRLF>...  MERGE BEFORE".
DBMS5.DOC                                                       Page 5 INTERCEPT/NOTE Statement -  These related statements  allow  a
user to tell DBCS the classes of exceptions for which it should type a
message and exit, or just type  a  message,  respectively.   In  other
words  the  facility constitutes a debugging tool, exception trace, or
means  of  reducing  the  number  of   ERROR-STATUS   checks   in   an
application--depending  on  how  it  is  used.   The  syntax  of these
statements is:


That is, either ALL or one or more of the  others  may  be  specified.
When  a  designated  exception  occurs,  the message printed is of the

[STATUS/AREA/RECORD/SET=status/area-name/others if known]

If interception was specified, an EXIT 1 is  then  done...which  means
the    user   can   still   type   CONTINUE   if   he   wishes.    The
exception-partitioning implied here is described in ASSIGN Statement -  The syntax of the this statement is now:

     ASSIGN [SYSTEM AREA] area-name TO file-spec
      [RECORDS-PER-PAGE [IS] integer]
      [BUFFER [COUNT IS] integer]
       FIRST PAGE [IS] integer
       LAST PAGE [IS]  integer
       PAGE SIZE [IS] integer WORDS
      [RANGE [OF] name [IS PAGE] integer [TO PAGE] integer]
      [more RANGE phrases].

Except for the RANGE clause, each clause  can  appear  at  most  once.
Ordering  is as presented except that the RPP, BACKUP, BUFFER and CALC
optional clauses are interchangable.

The SYSTEM AREA phrase serves to support the OWNER  IS  SYSTEM  clause
added  to  the SET statement, see  Its effect is to cause the
system record (if there is need for one) to be  stored  in  this  area
(along with any other record types allowed in this area).  If there is
a non-null system record and no area contains this phrase,  the  first
area assigned will become the system area.
DBMS5.DOC                                                       Page 6

The RECORDS-PER-PAGE clause is used to specify the maximum  number  of
records  that  can  be  on  a  page  of  this  area.   (It overrides a
RECORDS-PER-PAGE statement if one is  present).   If  this  clause  is
absent,  a  RECORDS-PER-PAGE statement must have appeared earlier--and
the  value  specified  there  will  be  used.   In  other   words,   a
RECORDS-PER-PAGE statement is necessary unless each area specified has
its own RECORDS-PER-PAGE  clause.   Whether  a  global  or  local  RPP
applies  to this ASSIGN statement, it must specify at least 2 and less
than 512 records per page.

The BUFFER clause is used to specify how many page-buffers  this  area
will have.  A buffer count of 2 is the minimum allowed.  If the clause
is absent, 3 buffers will be created.

The CALC clause allows  one  to  trade  off  the  amount  of  per-area
overhead  associated  with  calc  records  with  the  average  time to
access/store a calc record.  In earlier  versions,  there  was  always
precisely  one  calc-chain  per page (one list==one word of overhead).
Thus if one expected 500 calc records in an area that had  100  pages,
the average calc-chain would unavoidably have 5 records in it.  But in
V4 one could specify  CALC  5  RPP  and  thereby  reduce  the  average
calc-chain  length to 1.  Conversely if there are no calc record types
in a particular area, one can now say CALC 0 RPP.

Each RANGE clause controls where in this area a particular record type
can  be STOREd.  If a record type can be WITHIN this area, it may have
a RANGE clause for this area.  If a record type that can be STOREd  in
this  area  has  no  RANGE clause for this area, each page of the area
will constitute its range.  This clause has two purposes.  Its obvious
purpose  is  to enable the administrator to cluster records based upon
record type.  Its other purpose is to make calc records insensitive to
a  change in the number of pages in an area.  Previously the number of
pages in  an  area  (that  contained  calc  records)  could  never  be
increased since that would "throw the calc algorithm off".

2.1.2  The Schema DDL AREA PRIVACY Clause -  Because V4 supports a wider set of area
usage-modes, this clause has been expanded.  There is no change in the
syntax for specifying that an area's locks are all the same,  but  the
separate-locks syntax is now:


A description of the six usage-modes is in subsection The Data-name Entry -  This statement has  been  expanded  and
made    more   host-language   independent.    The   nature   of   the
incompatibility so induced is described in 2.2, notes 1  and  2.   The
new syntax is:
DBMS5.DOC                                                       Page 7

02 data-name picture!size!type [OCCURS integer [TIMES]].
  picture-->PICTURE [IS] same-as-v3 [usage]
  size-->   SIZE [IS] integer [WORDS!usage]
  type-->   TYPE [IS] numeric!DBKEY
   numeric->FLOAT [DECIMAL!BINARY] [REAL!COMPLEX] [integer]
     -->[FIXED] [DEC!BIN] [REAL!COMPLEX] [integer [integer]]

The OCCURS clause is of course used to define an  array  and  describe
its  length.   (This  does not affect GET and MODIFY;  each will still
process entire 02-data-names:  if 02 A OCCURS 3 appeared in a  schema,
GET  A  would  get  the whole array and GET A(2) would be flagged as a
syntax error).

The PICTURE clause is used to describe elementary  string  data;   the
SIZE  clause is used to describe data structures;  and the TYPE clause
is used to describe numeric data (and DBKEYS).  Thus the USAGE  phrase
can  no  longer be used to described numeric data.  The USAGE phrase's
sole purpose now is to  state  what  type  of  string  data  is  being
allocated:  respectively SIXBIT, ASCII, or EBCDIC.  Note also that the
programmer now has complete control of the unit of storage  allocation
in  the  SIZE  clause:  whole words as well as any of the three string
representations.  The string host-language  mappings  are,  where  !x!
=smallest integer>=x:

     KEYWORDS    LENGTH          FORTRAN         COBOL
     DISPLAY-6    N              INTEGER(!N/5!)  AS IN DDL
     DISPLAY-7    N              INTEGER(!N/5!)  AS IN DDL
     DISPLAY-9    N              INTEGER(!N/4!)  AS IN DDL

The NUMERIC phrase in the TYPE clause  allows  six  types  of  numeric
encoding;   the  defaults for each pair are respectively FIXED, BINARY
and REAL.  The first optional integer at the end of the NUMERIC phrase
is the data-name's precision (in binary or decimal digits according to
the 2nd keyword pair).  The second  integer,  if  applicable,  is  its
scale  factor.   A  scale factor indicates that the internal form of a
fixed-point number is some number of powers-of-10 different  than  the
external  form.   The default is of course 0 (ie.  no difference);  -1
means external is 10 times as large;  1  means  external  is  1/10  as

If no supported  host-language  intrinsically  supports  a  particular
combination  of  NUMERIC  keywords  and the chosen precision, a syntax
error will be signalled during translation of the  TYPE  clause.   The
default  precisions  for  FIXED  BIN,  FLOAT  BIN,  and  FIXED DEC are
respectively  35,27,  and  10.   The  legal   combinations   and   the
host-language mappings are as follows:
DBMS5.DOC                                                       Page 8

     FIXED BIN REAL       < 36      INTEGER         COMP S9(X2)
     FIXED BIN REAL       36-71     INTEGER(2)      COMP S9(X3)
     FLOAT BIN REAL       < 28      REAL            COMP-1
     FLOAT BIN REAL       28-62     REAL*8          COMP S9(18)
     FLOAT BIN COMPLEX    < 28      COMPLEX         COMP S9(18)
     FIXED DEC REAL       < 19      INTEGER(X1)     COMP-3 S9(prec)

Note  that  where  only  one  host-language   supports   the   keyword
combination  intrinsically,  the  other  declares it as "best it can".
For example, for FIXED DEC REAL, FORDML  simply  allocates  4  decimal
digits/word   (ie.   X1=prec/4),  in  terms  of  a  "reasonable"  data

The values X2 and X3 are computed according to the following  mapping.
However  it  is  suggested  that  one  use  either  FIXED  BIN (35=the
default)-- or FIXED BIN 71 for double  precision--unless  there  is  a
specific  need  to cause numeric truncation at run-time.  Consistently
using full-word precision leads  to  COBOL  generating  better  object

         4                               1
         7                               2
         10                              3
         14                              4
         17                              5
         20                              6
         24                              7
         27                              8
         30                              9
         35                              10
     (switch to double precision)
         38                              11
         41                              12
         44                              13
         48                              14
         51                              15
         54                              16
         58                              17
         >58                             18 The SET Entry -  There are several small changes  to  the  SET

The owner of a set can  now  be  the  system.   In  other  words,  the
programmer need no longer create a dummy record type when he wishes to
have a singular set.  This affects  the  OWNER  clause,  and  its  new
syntax is:

                    OWNER [IS] record-name!SYSTEM
DBMS5.DOC                                                       Page 9

The few special rules governing singular sets are:

The system area must be placed in all sub-schemas, but it need be open
only  if  the  system record will be referenced (see on how to
allocate area space to the system record).

No member clause in the set entry of a singular set  may  have  a  SET
SELECTION  phrase.   The  reason  for  this is intuitively reasonable:
since the DBCS knows the set is singular, it can always correctly (and
quickly) locate the "proper" set occurrence.

FIND OWNER will be allowed relative to singular sets so  that  a  FIND
NEXT loop for a singular set can be coded as it would be for any other
set.  However the meaning of a succeeding GET, MODIFY, INSERT, REMOVE,
OR DELETE is of course ill-defined and will return exception xx20.

The SET entry may optionally be separated from its MEMBER entries by a
period.   Multiple  MEMBER entries can also be optionally separated by

When ORDER SORTED or ORDER SORTED  WITHIN  is  specified  as  a  set's
ORDER, the record-name of each member record is each's major sort key.
In order to speed processing and decrease  the  amount  of  data  base
space  required,  DBMS-10/20 uses the record's type ID rather than the
record-name itself.  Type ID's are assigned in increasing sequence  as
each  RECORD  entry  is processed.  This has two effects.  One is that
the member record types will not  be  sorted  in  alphabetic  sequence
unless they appear in alphabetic sequence;  and two, that the user now
has  complete  control  and  can  specifically  cause   non-alphabetic

Signed RANGE KEYs will be supported in V4.  Also all keys to the right
of the first RANGE will be treated as RANGE KEYs.  Absence or presence
of the keyword RANGE, after its first appearance, will be  transparent
to  the SCHEMA processor.  Finally, the existing syntactic description
is somewhat vague, the actual syntax is:

     key-phrase [key-phrase ...] [duplicates-phrase]
     key-phrase --> key-type [KEY IS] data-name-1, [dn-2,...]
     duplicates-phrase -->

When sort/calc keys  consist  of  more  than  one  data  item,  it  is
allowable  to not ALIAS all of the items.  Presumably this would be of
use when one wished to alias the minor key(s) and not the  major  key.
In any event, these examples portray each of the possible cases:



DBMS5.DOC                                                      Page 10 Guaranteeing Source Program Consistency -  Earlier versions of
SCHEMA  were  somewhat lax in detecting if the subtler requirements of
the DDL were being satisfied.  Version 4 attempts to guarantee that no
invalid  program  will  translate  error-free.   (There is of course a
CATCH-22 incompatibility in this since  some  existing  .DDL  programs
will  display  errors  when translated with V4).  The more interesting
checks are as follows:

     1.  Table 4-1 on p.  4-17 in the Administrator's Manual  will  be

     2.  When SET SELECTION is thru LOCATION MODE OF OWNER, any key so
         referenced  must  have been declared such that DUPLICATES ARE
         NOT ALLOWED for the key.

     3.  If an ALIAS OR USING argument  is  not  valid,  an  error  is

     4.  For each RECORD entry in which there is a  LOCATION  MODE  IS
         VIA clause, there must be a corresponding SET.

     5.  For each RANGE clause, the corresponding WITHIN  clause  must

     6.  If a record is declared in the same set more  than  once,  an
         error is reported.

     7.  If a RECORD entry contains a LOCATION MODE VIA clause and  is
         a member of a sorted set in which (one of) the sort key(s) is
         the record's dbkey, an error is reported.   This  is  because
         such  a  situation  is a deadlock:  VIA says store the record
         physically near its logical neighbors, while sorted-on-dbkeys
         says  logically  place the record on the basis of where it is

2.1.3  The Sub-schema DDL

Conceptually there has been only one change  to  the  sub-schema  DDL;
any  text  (eg.   03  data-name...)  that  the  programmer  wishes  to
associate with an 02-data-name will be so associated in the sub-schema
DDL.   The  reasons  for  making  this change are twofold:  to isolate
COBOL  dependencies  in  sub-schemas  intended  for   use   by   COBOL
applications   and   to   allow  a  programmer  to  associate  FORTRAN
information with an 02-data-name. General Text-specifying Rules -  Text is specified on  a  line
basis;  the presence or absence of a terminating period is irrelevant.
The line(s) following a sub-schema DATA entry will be treated as  text
unless  its first word is COPY, 02, 01, or SET.  If one wishes to have
a line of text that starts with one of these symbols, the line must be
prefixed  by  a plus (+).  (Note that the means of explicitly entering
null text is a line consisting of +<CRLF>.)
DBMS5.DOC                                                      Page 11

Since it is likely that a  data-name  will  have  the  same  usage  in
different  sub-schemas,  there  must be a way to associate a data-name
with the same text in more than one  sub-schema.   The  mechanism  for
doing  this  explicitly  is  described  in,  but  the default
mechanism is as follows.  Let data-name-1 be associated with text-a in
the  (i)th  sub-schema  in the program, and let the next sub-schema in
which data-name-1 is declared be the (j)th.  Then text-a will again be
associated  with  data-name-1  unless  text-b is actually present with
data-name-1(j)--in which case  text-b  will  become  the  default  for
data-name-1 in later sub-schemas. The COPY OTHERS Statement -  This statement is used  to  place
the  "remaining"  DATA entries of a RECORD entry in a sub-schema.  For
example, if REC1's DATA entries were A1, A2, A3, A4 and A5, saying:

     01 REC1.

would be equivalent to:

     01 REC1.
     02 A2.
     02 A4.

However the usual usage of COPY OTHERS would  be  something  analogous

     01 REC1.
     02 A2.
     02 A4.
     COPY OTHERS. The COPY TEXT Statement -  To  associate  data-name-1(j)  with
the text associated with data-name-1 in an earlier sub-schema, one may
type the following, rather than the actual text:

                     COPY sub-schema-name [TEXT].


     02 D1 SIZE 4 WORDS.
     02 D2 TYPE FLOAT BIN.
     02 D3 PIC X(5) OCCURS 4.
DBMS5.DOC                                                      Page 12

     01 R1.
     02 D1.
     03 DD1 PIC X(12).
     03 DD2 PIC S9(18) USAGE COMP.
     01 R1.
     01 R1.
     02 D1.
     EQUIVALENCE (D1(1),D6BIT), (D1(3),DPINT)
     02 D2.
     01 R1.
     02 D1.
     COPY SS1.

Sub-schemas SS1,  SS2,  and  SS4  lead  to  exactly  the  same  record
description  being  placed  in the COBOL host program.  Sub-schema SS3
places  INTEGER  D1(4)  AND  REAL  D2,  as  well  as  the  EQUIVALENCE
statement, in the FORTRAN host program.

2.1.4  The SCHEMA Program Interface

The V4 command line processor utilizes SCAN  and  WILD.   The  general
form of the command line is as follows:

                  [file-spec=] file-spec [switches]

If all or part of the output file spec is absent,  the  missing  parts
are derived from the input file spec.  The default extension for input
files is .DDL.  Any extension in the output file spec is ignored.  The
extension of the output file is always forced to .SCH.

In V4 there is just one class  of  switch,  the  /CREATE  switch.   It
controls whether the .DBS files are (re)created or left as they are:

     1.  If no switch is present, a .DBS file is created  only  if  it
         does not exist already.

     2.  If /CREATE is present, the .DBS files are always created.

     3.  If /NOCREATE is present, the .DBS files are never created.
DBMS5.DOC                                                      Page 13

There has been  a  slight  change  of  philosophy  in  how  areas  are
addressed.   Areas  generally  have  the  property that they stay put:
once they contain live data their name and  directory  seldom  change.
Consequently  when  SCHEMA initializes an area, the area is associated
to its directory of creation permanently.  In other words,  if  during
the  running of SCHEMA AREA1 is ASSIGNed to FILE1, it is also ASSIGNed
to the directory which constituted the current directory path.

As noted earlier, the error detecting capability of  SCHEMA  has  been
expanded.   Additionally  the  error messages are now in standard form
(ie.  preceded by ?DDLxxx or %DDLxxx).  Lastly  an  error  message  is
accompanied  by  the  first  (and  last)  line of the offending source
statement, if applicable.

Important:  the distinction between warnings (%)  and  errors  (?)  is
functional as well as descriptive.  If the error count is greater than
0, the .SCH file (and .DBS files) will not  be  (re)created.   If  the
warning  count  is greater than 0 and the error count is 0, processing
will not be curtailed.

2.1.5  Exception Handling The ERROR  Special  Registers -   Each  time  a  DML  verb  is
executed, ERROR-STATUS and ERROR-COUNT are set to well-defined values.
If no exception occurred, ERROR-STATUS equals the null-string (ie.  it
is  a 0-word) and ERROR-COUNT equals 0.  The other three ERROR special
registers have the same value as before the verb was executed.

If an exception did occur, ERROR-STATUS equals " xxyy" and ERROR-COUNT
equals  1, where "xx" is a statement code (see and "yy" is an
exception code (see

ERROR-AREA will always equal the last area actually referenced.

Except for OPEN and CLOSE, ERROR-RECORD will be  blanks  only  if  the
exception occurred while DBCS was still processing the verb's argument
list.  Otherwise it will be the object record's type unless  the  verb
"traverses"  the  data base.  A qualified DELETE recursively traverses
the data base, FIND NEXT with a  non-null  record-name  traverses  the
data  base,  and  FIND OWNER traverses the data base.  In these cases,
ERROR-RECORD will be the record type of the last record operated upon.

ERROR-SET will be blanks unless at least one set  operation  has  been
started  at  the  time  of  the  exception.   Each  of  the  following
constitutes a set  operation:   FIND  NEXT/PRIOR/OWNER  OF  SET,  each
auto-insert  during a STORE, each actual insert during an INSERT, each
remove in a  REMOVE  and  each  auto-remove  in  a  DELETE,  and  each
resorting of a set occurrence during a MODIFY.
DBMS5.DOC                                                      Page 14  Classes  of  Exceptions -   There  are  several  classes   of
exceptions  explicitly  defined.   ALL  is  of  course  all  the valid
statement-code/exception-code  combinations,   SYSTEM   is   all   the
exceptions  with  a  code  greater  than  or  equal to 55.  The SYSTEM
exceptions are discussed  in  some  detail  in  the  next  subsection,
Failsofting.    The  other  defined  classes  are  partitions  of  the
statement-codes, which are:

     STATEMENT               CODE
     HOST                     00
     CLOSE                    01
     DELETE                   02
     FIND                     03
     UNUSED                   04
     GET                      05
     UNUSED                   06
     INSERT                   07
     MODIFY                   08
     OPEN                     09
     UNUSED                   10
     REMOVE                   11
     STORE                    12
     RESERVED                 13
     RESERVED                 14
     BIND                     15
     CALL                     16

The HOST statement-code is associated with the IF predicates  and  the
MOVE  STATUS  command.  The BIND statement-code is associated with the
SBIND,  BIND,  EBIND,  and  SETUSE  entry  points.   Also  note   that
exceptions  31 thru 36 can only be generated during binding.  The CALL
statement-code is associated with all of the DBCS  entry  points  that
are  explicitly  called  (ie.   the journaling entry points Jxxxxx and
SETDB and UNSET).  The  UPDATE  class  of  exceptions  refers  to  any
exception  that  happens  during  execution of DELETE, INSERT, MODIFY,
REMOVE or STORE. Failsofting -  V4 of DBCS attempts to guarantee two things  as
regards the execution of a run-unit.

First it operates on the assumption that a  critical  application  may
want  to  maintain  complete  control and never be returned to monitor
level against its will.  DBCS  serves  this  goal  by  associating  an
exception code with all the exceptional conditions that it detects--it
never does an EXIT that  the  user  did  not  request  (the  INTERCEPT
facility  is  a  means  of  requesting  EXITs).   This  rule is broken
precisely once:  to place a value in ERROR-STATUS, DBCS must have been
associated  with  a sub-schema--consequently if the first call to DBCS
is at other than SBIND, it types the ?DBSSNI message and exits.

Secondly it attempts to guarantee that no one  accesses  a  data  base
while it or DBCS is in an undefined state.
DBMS5.DOC                                                      Page 15

One aspect of this control is the area-status-record (ASR),  which  is
created the first time an area is OPENed (and always has a dbkey equal
to first-page/1).  When an area is OPENed for update, DBCS  decrements
by  1  FH.STAT  in  the ASR to indicate that the area is in a state of
flux.  FH.STAT is not incremented by 1 until the programmer closes the
area.   If  the run-unit aborts for any reason, DBMEND must be used to
revalidate the area (and reset FH.STAT to 0) before it can  be  OPENed
for normal usage again.

The other major aspect of control is DBCS's status word (one for  each
sub-schema   INVOKEd).    The   two   user-relevant   flags   are  the
system-in-undefined-state (SUS) flag and cannot-backup-updates  (CBUU)
flag.   CBUU  is  turned  on  in  the following circumstances:  during
exceptions 61 and 63, during OPEN if the journal device is MTA, during
the  OPENing  of  an  area  for  update  when  BEFORE  IMAGES  are not
requested, and in conjunction with the SUS flag if an exception occurs
during  binding  or  while  an exception is being processed (this also
causes typing of the ?DBSXWX message).  The SUS flag  gets  turned  on
for  only one other reason, when an exception occurs after an updating
verb has altered one or more data base pages.

The effect of the SUS flag is as follows.  If one tries to enter  DBCS
while  the  SUS  flag  is  set  (at  other than JBTRAN or a sub-schema
changing entry point), DBCS will return immediately with  ERROR-STATUS
set to " xx62".  However, if CBUU is not set, there is one of two ways
in which the SUS flag may get turned off.

If images are ordered by command, DBCS will automatically restore  the
data  base to the state it was in before the verb was entered and turn
the SUS bit off.  But if for some exceptional reason  the  restoration
cannot  be  completed,  the  ?DBSUCR message is typed and CBUU is also
turned on.

If images are not ordered by command  the  program  will  be  able  to
explicitly  restore the data base to its proper state even though DBCS
will have returned with the SUS bit still set.  It can do this via the
JBTRAN  entry  point.  Calling JBTRAN after an updating-exception will
restore the data base to the beginning of  the  in-doubt  transaction,
turn the SUS bit off, and (IMPORTANT!) leave all currency indicators 0
(to  eliminate  the  possibility  of  reference  to  now  non-existent
records).   If, for some exceptional reason JBTRAN fails, ERROR-STATUS
will be set to " 1663" and CBUU turned on.

In summary, there is no way for the programmer to turn  off  the  CBUU
flag.   In  and  of  itself  this is no problem since the CBUU flag is
transparent to the application unless the SUS flag is also turned  on.
In  this latter state however, the run-unit can essentially do nothing
with the sub-schema...  and in effect DBCS no longer trusts itself.
DBMS5.DOC                                                      Page 16 The Exception Codes

    00          A WARNING:  the compile-time and run-time versions  of
                the  .SCH  file differ.  However if a "real" exception
                occurs during binding DBCS always returns the code  of
                that  exception...   but to indicate that exception 00
                has occurred as well, DBCS types the %DBSCED  message.
                However,  as a general rule, the "real" exception will
                not persist after the program-unit is recompiled  with
                the up-to-date .SCH file.

    01          Area not open

    02          Dbkey inconsistent with area-name.  Can also  indicate
                that  a  referenced  page number is in an area that is
                not in the sub-schema.

    03          Record affected by concurrent application--V5 only

    04          Data-name invalid or inconsistent (ie.  during GET  or
                MODIFY with data-name list)

    05          Violation of DUPLICATES NOT ALLOWED phrase

    06          Current of (set/record/area) not known

    07          End of set or area

    08          Referenced name not in sub-schema.  This can occur for
                many  reasons:   (1)  In traversing a set, if a record
                type not in the sub-schema is encountered.  (2) During
                STORE  OR  DELETE,  if  set  type  owned by the object
                record type is not in the sub-schema.  (3) During  set
                occurrence  selection  if  the  VIA  set is not in the
                sub-schema.   (4)  During  calc   processing   or   in
                searching  a sorted set, if not all subkeys are in the
                sub-schema.  (5) During MODIFY, if the sort key  of  a
                set not in the sub-schema is modified.

                The solution to this problem is of course to place the
                offending name in the sub-schema.

    09          An update usage mode required (eg.  attempt to STORE a
                record while the area is OPEN for RETRIEVAL)

    10          Privacy breach attempted

    11          Data space exhausted (ie.  no more  room  to  STORE  a
                record).   Note  that  this  can  occur  while DBCS is
                trying  to  store  an  internal   record   type:    in
                particular, the index blocks in a sorted set.

    12          Unused
DBMS5.DOC                                                      Page 17

    13          No current record of the run-unit

    14          Object record is mandatory  automatic  member  of  the

    15          Attempt to REMOVE a record which is either a MANDATORY
                member or not a member type at all.

    16          Record is already member of set.

    17          Need a record which is current of "-----", but it  has
                been  deleted  (eg.   can occur during FIND CURRENT OF
                "-----";  or during GET, if the record was deleted  by
                a concurrent run-unit).

    18          Unused

    19          Data conversion unsuccessful--unused for now

    20          Current record of run-unit not of right record type

    21          Unused

    22          Record not currently member of set, analogous to xx17.

    23          Illegal area-name was passed in an AREA-ID.

    24          Temporary and permanent areas referenced in  same  DML

    25          No set occurence satisfies argument values (eg.   calc
                value in UWA matched no owner record)

    26          No record satisfied RSE, catch-all exception for  FIND

    27          Unused

    28          Area already open

    29          Unused

    30          Unqualified DELETE attempted on non-empty set


    31          Unable to open the .sch file

    32          Insufficient  space  allocated   (eg.    SIZE   clause
                specified  less  space that what the compiler actually

    33          None of the areas a record type can be WITHIN  are  in
                the sub-schema.
DBMS5.DOC                                                      Page 18

    34          A set is in the sub-schema, but its owner record  type
                is not.

    35          Dynamic use-vector full

    36          Attempt to INVOKE too many sub-schemas (currently more
                than 8), attempt to UNSET an empty sub-schema stack or
                SETDB a full stack.

    37          Argument  to   SETDB   is   not   an   already-INVOKEd

    38          Duplicate operation on resource:  you  have  attempted
                to  open  the  journal  twice;   you  have  opened  it
                EXCLUSIVE and are now opening an area with  USAGE-MODE
                UPDATE;  you are calling JSTRAN while a transaction is
                already active;  or you have multiple INVOKEs and have
                attempted to open the same area twice.

    39          DBS file not found

    40          Requested access conflicts with existing  access.   In
                other  words,  the resource is not available:  (1) you
                attempt to open an area in a  USAGE-MODE  incompatible
                with  another  run-unit's  control  (eg.  you try EXCL
                RETRIEVAL and he already has it open with PROT UPDATE)
                (2)  you  attempt to open the journal and a USAGE-MODE
                conflict results.  (3) you attempt to delete a  record
                retained by another run-unit.  (4) you attempt to open
                an area (or the journal) and the file-system signals a
                file protection error.

    41          No channel available...attempt to open too many areas

    42          Area  in   undefined   state   (eg.    after   crash).
                Internally  this means that FH.STAT in the ASR is less
                than 0.  DBMEND should be used to FORCEOPEN  the  area
                and return it to a valid state.

    43          Area in creation state.  This can happen to the system
                area  only.   It will happen if the run-unit aborts at
                just the right time during the very first  OPENing  of
                the  system  area.   DBCS  recognizes  this  state  by
                leaving FH.STAT equal to 1 until initialization of the
                system area is completed.

                If this exception is returned, the  programmer  should
                either  rerun  SCHEMA  or,  more simply, just create a
                0-length file with one of the text editors.

    44          Attempt  to  call  a  journal-processing  entry  point
                before  the journaling system has been initialized (by
                the first OPEN that requires journaling).
DBMS5.DOC                                                      Page 19

    45          Attempt to backup the  data  base  with  JBTRAN  while
                DBCS's  CBUU  bit  is set (see or when a file
                (ie.  journal or area) is shared for update in command
                mode or for JBTRAN(gtr 0) when it is shared for update
                in transaction mode.

    46          Magtape  service  is  unavailable--DAEMDB  returned  a
                failure code.

    47          Reserved

    48          Reserved

    49          Reserved

    50          Unused

    51          Unused

    52          Unused

    53          Unused

    54          Unused

                SYSTEM EXCEPTIONS

    55          Pseudo-exception:   DBCS   types   message   that   no
                sub-schema has been initialized yet

    56          Inconsistent data in .DBS file.  DBMEND should be used
                to  restore  the  data  base to a valid state.  If the
                problem can be reproduced, it probably  indicates  the
                presence of a DBCS software error.

    57          DBCS software error probably

    58          Illegal argument was passed by user (or setup by  host

    59          No more core-memory available

    60          I/O error attempting to access a .DBS file -- is  DBCS
                bug,  is  spurious,  or is disk quota exceeded or file
                protection failure.

    61          Unable to append to journal either in normal operation
                or  in  trying  to  open  a journal for appending (ie.
                journal in an aborted-state but not designated as done
                with).   This  exception  turns on CBUU as well as SUS

    62          Attempt to enter DBCS at  other  than  JBTRAN,  SBIND,
                SETDB, or UNSET while the SUS bit is on (see
DBMS5.DOC                                                      Page 20

    63          Unable to complete restoration of the proper data base
                state--either   in   JBTRAN  or  when  initializing  a
                run-unit at the start of an  interleaving-unit.   This
                exception turns on CBUU as well as SUS (see

    64          Internal use only

    65          Monitor space for ENQ entries exhausted or  ENQ  quota

    66          ENQ/DEQ/ENQC  failure:   user  does   not   have   ENQ
                capabilities set or some DBCS problem

    67          Unable to initialize magtape service--as opposed to it
                being  unavailable  (eg.  SYS INFO not running, DAEMDB
                not running, or some DBCS problem)

    68-99       Reserved

2.1.6  The Data Manipulation Language The OPEN Statement -  The only part of the OPEN statement that
has changed is the USAGE-MODE clause.  The syntax is now:


Although the syntactic change is small, three  USAGE-MODEs  will  have
been  added  (the  last in V5), and the meaning of each USAGE-MODE has
been brought into alignment with the CODASYL spec.

EXCLUSIVE RETRIEVAL means that no one else will be able to access  the
area  while  you  have it OPEN and that you will not be able to STORE,
DELETE, MODIFY, INSERT or REMOVE.  Conversely if anyone has  the  area
OPEN for any reason, you will be denied access.

EXCLUSIVE UPDATE means that no one else will be  able  to  access  the
area  while  you have it OPEN and that you will be able to execute any
verb.  Conversely if anyone has the area OPEN for any reason, you will
be denied access.

PROTECTED RETRIEVAL means that no one else will be able to update  the
area  while you have it OPEN and that you will not be able to call the
updating verbs listed above.  Conversely if anyone has the  area  OPEN
for EXCLUSIVE access or PROTECTED UPDATE or UPDATE, you will be denied

PROTECTED UPDATE means that no one else will be  able  to  update  the
area  while  you have it OPEN and that you will be able to execute any
verb.  Conversely if anyone has the area OPEN for EXCLUSIVE access  or
PROTECTED UPDATE or UPDATE, you will be denied access.
DBMS5.DOC                                                      Page 21

RETRIEVAL means that anyone else will be  able  to  access/update  the
area  while  you have it OPEN and that you will not be able to execute
the updating verbs listed above.  Conversely if anyone  has  the  area
OPEN for EXCLUSIVE access, you will be denied access.

UPDATE means that anyone else will be able to access/update  the  data
base  while  you have it OPEN and that you will be able to execute any
verb.  Conversely if  anyone  has  the  area  OPEN  for  EXCLUSIVE  or
PROTECTED access, you will be denied access.

Some general comments:

All update USAGE-MODEs actually modify the .DBS file when a buffer  is
written  to  disk.  A temporary area is the only circumstance in which
there is an after-image directory, in which case a file by the name of
ASSIGNed-name.TMP   is  created.   See  section  2.4  note  7,  for  a
description of the organization of an area .TMP file.

The idea that different USAGE-MODEs  were  synonymous  with  different
accessing  algorithms was a corruption of the USAGE-MODE concept.  The
concept of USAGE-MODE has just two components:  the  level  of  shared
access  to  be  allowed  and whether modification of the area is to be
allowed. The MOVE Statement -  The syntax of  this  statement  has  not
been  changed.   The  change  is  that  it  will now alter the special
registers AREA-NAME and RECORD-NAME to describe the currency indicator
being MOVEd.  Also see subsection 2.2, note 3. DELETing or REMOVing Current of "-----" -  The meaning of FIND
NEXT of SET when current of set has been REMOVEd or DELETEd is apriori
somewhat  ambiguous.   Consequently,  to  allow  this  and  the  other
currency-based  operations  in this situation, some convention must be
established.  The convention employed by DBMS-10/20 V4 is as follows.

The record which  was  NEXT  of  the  eliminated  record  becomes  the
canonical  NEXT  of  SET.   What  this  means  is that, no matter what
happens to the set (short of establishing a new current of set),  this
record is NEXT of SET and the record which is PRIOR to it at any point
in time is PRIOR of SET.

DELETing current of area has no effect on the operation of  FIND  NEXT
of  AREA.  This is the case because DBKEY+1 and DBKEY-1 are inherently
NEXT and PRIOR of the dbkey being deassigned--whereas  the  identities
of  NEXT  and  PRIOR  of  a  set  depend on values in the record being
DBMS5.DOC                                                      Page 22 The JBTRAN Routine -  The topic of the JBTRAN routine has been
broached  in  subsections and as well.  To reiterate,
the primary reason to call JBTRAN is to turn off the SUS flag  (turned
on  by  an updating-exception) by backing up the data base to the most
recent transaction-header.   To  use  JBTRAN  for  this  purpose,  the
calling sequence is:


There  is  potentially  a  second  reason  to  call  JBTRAN.   If   an
application,  for  its  own  reason,  wants  to  wipe  out one or more
transactions, it can do this (even though SUS is off)  by  giving  the
number  of transactions it wishes to backup as the argument to JBTRAN.
(Thus CALL JBTRAN(1) can be used in place of CALL JBTRAN(0),  but  the
reverse  is not true because CALL JBTRAN(0) will do nothing if the SUS
bit was already off.)

It is unnecessary  to  do  a  JETRAN  after  cleaning  up  an  aborted
transaction  with  JBTRAN  because  JBTRAN  simulates  a JETRAN of the
following form:  JETRAN ("JBTRAN", number backed up). The STATS Routine -  There  have  been  some  changes  to  the
information  that  is  output  when  STATS  is called.  Most of the V4
output is self-explanatory, but a couple of things do require comment.

Some of the simpler routines in DBCS have a CPU duration which  is  at
the  border-line of resolution of the RUNTIM UUO.  This means that the
statistics for these entry points may be erratic.  Also  the  cost  of
generating  detailed  timings  is rather large.  Consequently detailed
timing statistics will not be generated unless the  user  specifically
requests  them.   He  does  this by setting the global symbol "STATS."
non-0.  The simplest way to accomplish this is:

     .R LINK

The STATS information is output  on  a  sub-schema  basis.   In  other
words,   if  one  has  invoked  two  sub-schemas,  one  will  get  two
subsections of output.  Also each figure for  sub-schema  run-time  is
the  result  of  subtracting  the  value  of  RUNTIM  at the time each
sub-schema was SBINDed from its current value.

"Same-page  data  base  accesses"   is   a   measure   of   intra-page
localization.   It  is incremented by 1 each time the page accessed is
the same page as was accessed the preceding time.

Lastly, reads of a temporary area's directory page are included in the
count of pages actually read from disk.
DBMS5.DOC                                                      Page 23 Passing Strings to DBCS -   There  are  several  entry  points
which  take  string arguments (eg.  JSTRAN, JRTEXT).  Particularly for
the benefit of FORTRAN users, the  convention  for  how  to  interpret
string  arguments  has  been expanded.  In particular, V3 allowed just
the DATA DIVISION with PIC X(30)) and only one way  for  FORTRAN  (eg.
CALL  JSTRAN('MYTRAN',I)).   In V4, these plus several other ways will
be possible (see example below).

     unspecified (ie. 0)           string pointer
     FORTRAN LOGICAL               data-varying
     INTEGER/COMP                  5 characters
     REAL/COMP-1                   5 characters
     REAL*8                        10 characters
     DOUBLE COMP                   string pointer
     COMPLEX                       string pointer
     COBOL string                  string pointer
     FORTRAN literal               ASCIZ

A string pointer is a two-word quantity:  its first  word  is  a  byte
pointer,  and  the  right  half  of  the  second word is the number of
characters in the string.  A data-varying string is an  actual  string
in  which  the  length is stored in the word preceding the string.  An
ASCIZ string is a string that is terminated by a 0 byte.

For example, let a data-varying string be used as follows:

     DATA DVLEN/30/
     TYPE 101
 102 FORMAT(6A5)
DBMS5.DOC                                                      Page 24

2.1.7  The Host-language Interface   Compile-time/run-time   .SCH   File   Compatibility -    The
possibility of compile-time/run-time .SCH file incompatibility will be
made explicit.  This will be  done  by  incrementing  an  edit  number
within   the  .SCH  file  each  time  SCHEMA  is  run  and  by  having
FORDML/COBOL place the value that they see in  the  argument  list  of
SBIND.  Then at run-time, SBIND will compare the edit-number passed to
it and the actual edit number of the .SCH file.  If these two  numbers
differ,   ERROR-STATUS   will  be  set  to  " 1500"  (usually...   see
subsection, exception 00 for details).

(Note that INTERCEPT/NOTE can be used to  detect  this  condition,  if
that is desired). Record/data Formats in the Host-language -  The order  of  the
data-names  in  the UWA will always be the same as it is in the schema
DDL.  In other words, the calc keys will not be moved to the front  of
a   record.    Also  AREA-IDs,  DIRECT  keys,  and  ALIASes  will  not
incorrectly be made part of the record with which they are associated.
Also see subsection 2.2, notes 4 and 5. DBCS symbols that are user-referencable -  This set  of  names
is  important  for two reasons.  It identifies the routines for use in
explicit calls, and it identifies which names  the  programmer  cannot
use for naming his own routines.

A starred (*) name identifies a synonym for the immediately  preceding
entry  point  name.   KEY  X identifies the negative number associated
with a keyword, as described in section 2.4, note 2.  A data base word
(ie.  area, set, record, data) refers to the name ID (see section 2.4,
note 1) for the particular data-base-name or  the  string  that  would
represent that name (ie.  "REC1" for REC1).

     CLOSED       (KEY ALL)
     CLOSED       (KEY AREA, area-list)
     FIND1        (record!0, USING-value)
     FIND2        (set!0, currency, KEY currency-keyword)
     FIND3        (KEY relative, record!0, area!set, KEY AREA!KEY SET)
     FINDO        (integer, record!0, area!set, KEY AREA!KEY SET)
     FIND4        (set)
     FIND5        (KEY DUPLICATES!0, record)
     GETS         (record [,data-list]) !  (0)
     INSERT       (record!0, set-list)
     MODIF        (same-as-GET)
     MOVEC        (currency, KEY currency-keyword, result)
     OPEND        (KEY   RETR!KEY   UPDATE,   0!KEY   PROT!KEY   EXCL,
                  privacy-key, KEY ALL!area-list)
DBMS5.DOC                                                      Page 25

     REMOVE       (same-as-INSERT)
     STORE        (record)
     SBIND        (schema,edit, subschema,ss-mask, SYSCOM-address)
     BIND         (record,data-address-list)
     EBIND        (0,DBMS-NULL)

Additionally, the FINDs and STORE can have appended a  SUPPRESS  list:

The other undotted names are:

     SETDB      UNSET       SAVESS     JMNAME
     JMAFT      JMBEF       JMBOTH     JMNONE
     EMPTY      *SETCON     MEMBER     *RECMEM
     OWNER      *RECOWN     TENANT     *RECMO
     STATS Validating data aggregates -  When the SIZE clause is used  in
a data-name entry, the programmer has to tell SCHEMA how much space to
reserve in the host-language's UWA.  There  are  no  serious  pitfalls
associated  with  providing extra space, but to protect the programmer
from losing data, DBCS will  signal  exception  32  when  insufficient
space is provided.

(However there is  no  intrinsic  way  to  determine  the  size  of  a
data-name at run-time (without passing a prohibitive additional amount
of information during binding).  The best DBCS can do is calculate how
far  apart  two  consecutive  data-names  are.   Unfortunately, when a
referenced name (eg.  DIRECT key) is shared between two  record  types
or  a FORTRAN application does not have pseudonyms for all data-names,
data is not necessarily sequential.  In other  words,  the  validation
check DBCS makes is negated under these two circumstances.) Loading DBMS applications -  DBMS applications are  loaded  in
the  same fashion as any other COBOL or FORTRAN program.  This is true
whether or not one is using a private  library  or  a  system  default
library.  For example, .LOAD COBPRG and .LOAD FORPRG, MYFLIB /SEARCH.

2.1.8 The DBINFO utility

This program can be used to  dump  data  from  a  data  base,  make  a
cross-reference  of  the  names in a sub-schema, and calculate certain
statistical information about the state of a data base.

It is similar to DBMEND in that its command interface is verb oriented
and  has  the same lexical rules (eg.  names containing dashes must be
enclosed  with  quote  marks).   Also  it  shares  some  of  the  same
"background"  commands since, in both contexts, the user has to select
a schema and open and close areas.
DBMS5.DOC                                                      Page 26  APPEND/SUPERSEDE  commands -   This  command  specifies   the
destination  file  spec  for  any INFO to be displayed.  Its syntax is

                      APPEND!SUPERSEDE file-spec

If APPEND is specified, any existing information in the file will  not
be   overwritten.   If  SUPERSEDE  is  specified,  the  file  will  be
overwritten. CLOSE command -  This command is used to  CLOSE  one  or  more
areas that the programmer has OPENed.  its syntax is:

                 CLOSE ALL ! area-name[,area-name...] DISPLAY command -  This is the primary action  command.   Each
time  the  user  gives  a  DISPLAY  command he causes the current INFO
output file to be appended to.  The syntax for this command is:

     DISPLAY CREF ! MAP ! free ! data ! usage
       usage-->USAGE [:set-name]
       data -->DATA [:set-name]
       free -->FREE [:integer]

If USAGE  is  not  followed  by  a  set-name,  the  number  of  record
occurrences  for each record type is printed for each object-page (see  If a  set-name  argument  is  present,  each  owner  record
occurrence  which  is  on  an object page is described:  the number of
member records on the same page as the owner and  the  number  in  the
entire set occurrence are displayed.

If DATA is not followed by a set-name, each record  occurrence  on  an
object  page  and in the sub-schema is dumped (ie.  each of its fields
is displayed).  Empty pages do not print any information.  If DATA  is
followed  by  a  set-name,  the  NEXT  pointers  of  each  object  set
occurrenceusage) are followed, and the  records  are  dumped  in  that
order.   A  set  occurrence  is  an object of the command if its owner
record is on an object page (see

FREE not followed by an "integer" is equivalent to FREE followed by 0.
DISPLAY  FREE  will  consider  any  page which has less than "integer"
words free to be full.  For each page which is neither full nor empty:
the   page   number,   the  count  of  free  words,  and  some  number
(1/10-free-words) asterisks (*) will be printed.   Additionally  empty
(or  full)  page-sequences  (at  least  3  consecutive  pages) will be
displayed as "(empty pages) low - high".

The CREF option causes DBINFO to generate an alphabetical  listing  of
the  symbols in the sub-schema:  what each is, plus how and where each
is used.
DBMS5.DOC                                                      Page 27

The MAP option causes DBINFO to generate a pictorial representation of
each  record type in the sub-schema.  It shows which words contain set
(and calc) linkages and exactly what user data is in each word.   Each
byte  of  user  data  is  represented by an asterisk.  In other words,
there can be at most 6, 5, and 4 asterisks per word in a SIXBIT, ASCII
and EBCDIC record.  Conversely, full-word bytes (ie.  in computational
numeric  items)  are  represented  by  one  left-justified   asterisk.
Lastly,   the   index  associated  with  each  data-name  in  the  map
corresponds to the index printed to the left of its value in the  data
dump. OPEN command -  This command OPENs  each  specified  area  for

           OPEN ALL![area-name[,area-name]] [:privacy-key]

In other words, it OPENs all areas in the relevant sub-schema or  just
those   explicitly   specified.    Each   area  named  (explicitly  or
implicitly) in the command must have the same privacy-lock value.  The
privacy-key  phrase  is  required  only  if  the areas have a non-null
privacy lock. PAGES command -  This command enables the user to control  the
pages to which a DISPLAY comand will apply.  Its syntax is:

     PAGES [range-list]
       range-list -->range-tuple [,range-list]
       range-tuple-->integer ! integer-integer ! area-name

If no range-list is specified, the range-list is defaulted to the list
of  OPEN areas.  And specifying an area as a range-tuple is equivalent
to specifying area-first-page - area-last-page.  Lastly, specifying  a
single  integer,  say  (n),  is  the same as specifying n-n.  In other
words, PAGES' argument is a list of zero or  more  (maximum  16)  page
ranges.   For  example,  PAGES 4,7,13-25 would localize future DISPLAY
commands to pages 4, 7, and 13 thru 25. SCHEMA command -  This command identifies the schema  file  to
DBINFO.  Its syntax is simply:

                          SCHEMA schema-name SS command -  This command identifies the sub-schema that will
be the context for DBINFO's evaluation of future DISPLAY commands.  It
is an action command;  the  sub-schema  specified  will  be  bound  by
DBINFO  each  time  the command is given.  (Note:  use of this command
does cause the run ID in the .SCH file to be incremented by 1).
DBMS5.DOC                                                      Page 28

Understanding this concept is crucial to effective use of DBINFO.   By
judicious  sub-schema  specification,  one  can precisely control what
record types are DISPLAYed, what data-names  within  the  records  are
DISPLAYed,  and what areas constitute ALL.  The syntax of this command

                         SS [sub-schema-name]

If  the  sub-schema-name  is  absent,  the  "improper"  sub-schema  is
identified;   that  is,  the  sub-schema which would correspond to the
entire (current) schema.  However,  repeating  this  form  of  the  SS
command  within  one  running  of DBINFO will merely reset the current
sub-schema to the original "improper" sub-schema.

2.2  Functional Incompatibilities

The  list  of  functional  incompatibilities  between  V3  and  V4  of
DBMS-10/20 is as follows:

     1.  Only 02-data-names can appear  in  a  data-name  entry  in  a
         schema, see and 2.1.3.

     2.  A data-name entry in a schema may not contain a USAGE  COMP-x
         phrase, see

     3.  Successful FINDs and STOREs will no longer set up the special
         registers  AREA-NAME  and  RECORD-NAME;   only  the MOVE verb
         will--see subsection

     4.  Calc keys will appear in a host-language program just as they
         do  in  a  RECORD/DATA  entry  in  a  schema,  see subsection   (This  incompatibility  is  transparent   to   all
         applications  except  those COBOL applications that do a MOVE
         record-name TO temp-name.)

     5.  AREA-IDs, DIRECT keys, and ALIASes are declared as  01  names
         in COBOL, see subsection  This is not truly a change
         but a fix for a bug.  Unfortunately it affects usage  of  the
         ACCESS  statement  in  COBOL.   If  you  had  been  passing a
         record-name to an  ACCESSing  subprogram,  and  expected  its
         DIRECT key or AREA-ID or anALIAS to be implicitly passed, the
         call will have to be altered to make  explicit  reference  to
         the ancillary variable.

     6.  The accessing algorithm for PROTECTED UPDATE will  no  longer
         involve  what  is  called  an  .RCV  file;   areas  OPEN  for
         PROTECTED UPDATE will be  updated  in  place.   Also  if  one
         program has an area OPEN for PROTECTED UPDATE and another has
         it OPEN for RETRIEVAL,  the  retriever  (and/or  updater)  is
         responsible  for  not  getting  messed  up by the changes the
         updater makes.  If this is a problem,  the  retriever  should
         OPEN  for  PROTECTED RETRIEVAL.  For a thorough discussion of
         USAGE-MODEs see subsection
DBMS5.DOC                                                      Page 29

     7.  Sub-schema-names must be unique  across  any  run-unit  which
         INVOKEs  more than one sub-schema.  This was already required
         for FORTRAN usage and is being generalized for  the  sake  of
         simplicity and DBCS efficiency.

     8.  If the owner of a set is to be  SELECTed  thru  the  LOCATION
         MODE  OF  OWNER  phrase and its LOCATION MODE is VIA, the SET
         entry of the VIA set must precede the SET entry in which  the
         record  in  question  is  the owner.  (This sounds much worse
         than it is.  If one places SET entries that  are  nearer  the
         root  of  a  data  base structure before SET entries that are
         farther from the root, one will never have a problem.)

     9.  The name (and device and directory) of the .SCH file will  be
         derived  from  the (possibly implicit) output file spec given
         on the command line to SCHEMA.   Earlier  versions  used  the
         schema-name  in  the  SCHEMA statement for this purpose--this
         name is now ignored.

    10.  The PRINTA entry point no longer  exists  within  DBCS.   Its
         functionality  is  subsumed  by DBINFO.  (See for the
         complete list of V4 entry points).

    11.  A BINDing  failure  now  returns  an  exception  rather  than
         EXITing, see and

    12.  Exception 34 may happen to an existing applications  program,
         see   (The  solution is to remove the set-name from
         the  sub-schema  or  add  the  owner   record-type   to   the

    13.  The  exception  numbers  above  30   bear   no   relationship
         whatsoever  to  what  they  were  in  earlier  versions,  see

    14.  Privacy locks/keys will be truncated to 5  characters  rather
         than 6 characters.

    15.  The exact mechanism  for  handling  REMOVEd/DELETEd  currency
         indicators  in  earlier  versions is unclear.  See subsection for a description of how V4 handles this situation.

    16.  In cases where a schema-defined name is always  syntactically
         paired  with  a  keyword  designating the type of name it is,
         DBCS will ignore the keyword.  For example, if one said  MOVE
         STATUS  FOR  REC1 RECORD TO X, DBCS would determine that REC1
         was a record-name from the its symbol block.  In other words,
         keywords in this context serve purely as visual documenation.

    17.  The V4 mechanism for explicitly specifying the  buffer  count
         of an area is described in subsection

    18.  On a SCHEMA command line, "A." does not == "a.ddl", only  "a"
         or "a.ddl" does.
DBMS5.DOC                                                      Page 30

    19.  Two statements may not be on the same line in a DDL program.

2.3  Functional Definition of DBMS-V5

2.3.1  V3 --> V5 conversion utility

This utility is a program named V3TOV5--and by definition it  will  be
useful  only  to existing DBMS-V3 users.  This program is used on-line
by giving a sequence of commands which identifies (by its schema)  the
data base to be converted and requests initiation(continuation) of the
actual conversion. Conversion Steps and V3TOV5 Usage -  A  successful  conversion
will  always  conform to the following sequence of user actions.  Also
it is suggested (although not required) that you keep around your  old
DDL  file  and give your V5 DDL program an extension of .ddn until you
have completed your conversion.

     1.  Read section 4.1.  This section contains instructions on  how
         to  change  V3  source  files  into valid V4/5 files.  (It is
         unlikely any file other than the .DDL file will  have  to  be

     2.  Run SCHEMA (V5) and specify the /CONVERT switch:


         This will cause SCHEMA to generate all  the  files  it  would
         normally  generate,  but  such  that  the  3rd letter of each
         file's extension will be  "N".   In  other  words,  it  would
         create  a  .SCN  file and some number of .DBN files.  This is
         done to facilitate concurrent existence of the  old  and  new
         copies of the data base.

     3.  The actual conversion protocol is as follows:

         R V3TOV5            ;START UP THE PROGRAM
         SCHEMA schema-name  ;IDENTIFY THE DATA BASE
                             ;BEING CONVERTED
         TRACE integer       ;IF ABSENT, TRACE 10 IS SIMULATED.
                             ;ALLOWS CONTINUATION OF CONVERSION
                             ;AFTER A CRASH BY TYPING 
                             ;[COMPLETED PAGE n]
                             ;EVERY integer PAGES.
                             ;ALSO [COMPLETED AREA name]
                             ;MESSAGES ARE TYPED.
         PAUSE               ;OPTIONAL, IF PRESENT IT CAUSES
                             ;V3TOV5 TO EXIT EACH TIME IT FINISHES
                             ;PROCESSING AN AREA, THEREBY ALLOWING
                             ;THE USER TO DO SOMETHING (EG.
                             ;CHANGE DISKS) BEFORE RESUMING--BY
                             ;TYPING CONTINUE.
DBMS5.DOC                                                      Page 31

                             ;(NECESSARY IF THERE ARE ANY
                             ; PARTIALLY DELETED RECORDS IN THE
                             ; DATA BASE--SEE
         START               ;START (OR CONTINUE) EXPUNGE
         V3TOV5              ;REQUEST TO MAP V3 DATA
                             ;INTO THE .DBN FILES
         START               ;START (OR CONTINUE) THE MAPPING
                             ;USER-KEY (IE. SORT/CALC) CHAINS
         START               ;START (OR CONTINUE) THE REKEYING

     4.  Delete all the old files (ie.  the .DBS files  and  the  .SCH

     5.  Rename *.DBN to *.DBS and schema-name.SCN to schema-name.SCH Understanding the Conversion Process Purpose  of  Multiple  Conversion  Steps -   The  conversion
process  is  divided  into  phases  (EXPUNGE,  V3TOV5,  REKEY) for two
reasons.  The first reason is that  the  data  base  will  be  out  of
commission  less  completely--even though the total time of conversion
is probably increased slightly.  This is because  the  possibility  of
interleaving  normal  usage  is much higher than otherwise.  The rules
for interleaving normal usage are as follows:

     1.  During the 1st (ie.   EXPUNGE)  phase,  no  normal  usage  is

     2.  After the 1st phase, and until the 2nd (ie.  V3TOV5) phase is
         started, any accessing other than DELETEs is permitted.

         (Note:  until the 2nd phase is started  the  .DBN  files  are

     3.  During the 2nd phase, and thru  the  completion  of  the  3rd
         phase  (REKEY),  retrieval  usage-mode  is allowed on the old
         data base.

         (Note:  the earliest the old data  base  can  be  deleted  is
         after completion of the 2nd phase).

The second reason for multiple phases is that it achieves isolation of
functional processes:

     1.  The 1st phase may  be  omitted  by  some  installations  (see

     2.  Only the 2nd phase simultaneously references both the old and
         new data bases.

     3.  Only the  3rd  phase  requires  journaling  in  order  to  be
         continuable after a crash (see section
DBMS5.DOC                                                      Page 32 Why/when the EXPUNGE phase is necessary -   DBMS-V3  and  V5
handle  record  deletion  differently.   In DBMS-V5, the DELETion of a
record completely eliminates it from the  data  base.   On  the  other
hand,  the DBMS-V3 deletion algorithm will not return the entire space
of a DELETEd record to the free space manager  until  the  record  has
been  referenced  thru  each set in which it participates.  Until this
has occurred, the remaining part of the record is kept "invisible"  by
the  mechanism  of  having  its  "deleted"  flag turned on in its line
header.  Consequently before the old data base can be  mapped  to  the
new format, any deleted records must be eliminated from the data base.
Conversely the 1st phase may be omitted by an installation if it knows
that  no  records in its data base have the "delete" flag on.  This is
not a life-and-death decision, however, because  the  2nd  phase  will
detect  such  records and inform the user that he must execute the 1st
phase before starting the 2nd phase. User-data Dbkeys -  Any field containing  a  dbkey  must  be
described as TYPE DBKEY in the schema because the format of a dbkey in
DBMS-V5 is different than in V3.  If the user does not describe such a
field  as  TYPE  DBKEY,  V3TOV5  will have no way of knowing that each
occurrence of the datum needs reformatting. Adding OWNER IS SYSTEM -  If you wish to  add  new  set  and
record  types  to  your  DDL  program, you should wait until after the
conversion process has been completed.  Additionally, you should  read
section 2.4 in the Data Base Administrator's Manual to understand just
what sort of changes are feasible.

In the particular case that you wish to create a  system  record  (ie.
one  or  more new member entries specifies OWNER IS SYSTEM) , you will
have to define a new area and designate it as your system area.   This
is  necessary  because DBCS expects to allocate the system record when
an area is accessed for  the  first  time--and  there  is  no  way  to
simulate  that  pattern of access during the conversion of an existing
area.  Hustling -   V3TOV5  allows  you  to  operate  outside  the
prescribed  protocol  if  you  feel  it  necessary.   But  these  more
error-prone activities  are  isolated  here  to  protect  the  average

     1.  Any number of new pointers can be added to a record type.  In
         particular,  you  might add prior pointers to certain sets to
         improve updating efficiency.  (IMPORTANT REMINDER:  the order
         and number of 02-data-names must not be changed however).

     2.  The REENTER monitor command can be used (in conjunction  with
         /PAUSE)  to control the flow of conversion more closely.  For
         example, one can do all three steps  for  a  single  area  by
         specifying  to  /START with that area for each step and doing
         REENTER/next-step after each pause.
DBMS5.DOC                                                      Page 33 Exceptional Conditions -  There are certain "bad" things  that
can  happen  during the conversion process.  The following subsections
enumerate the known possibilities and describe what the user should do
in each eventuality.  Recovering  from  a  System  Crash -   The  mechanism   for
recovering  from  an abortion of either the EXPUNGE or V3TOV5 phase is
the same.  The mechanism for recovering from the REKEY phase is as for
the  other  phases  plus an additional preliminary step.  The critical
parameter during a restart is the last TRACE message printed.  It will
contain   the  last  page  that  is  known  to  have  been  processed.
Conversely the argument to the TRACE command controls how often  these
messages  are  printed.   (Presumably,  in  a very large data base one
might increase the interval from the default of  one  message  per  10
pages processed.) The recovery scenario is as follows:

     1.  If aborted during REKEYing,

         CONVERT             ;INDICATE THE USE OF .??N FILES
         START               ;GIVE THE MERGE'S "LEFT" BOUNDARY 
         END                 ;...AND THE "RIGHT" BOUNDARY

     2.  Then for all phases,

         R V3TOV5
         SCHEMA schema-name         ;IDENTIFY THE SCHEMA
         START last-trace-value     ;TO RESUME AT RIGHT PAGE
                                    ;ie.  restart at 1st page after
                                    ;last trace value  Area  or  its  Page  Size  Too  Small -   Except  for   one
circumstance,  the  number  of  pages in a V3 area will suffice in V5.
The exceptional circumstance can manifest itself during conversion  if
a  V3  area is nearly full and the area contains occurrences of sorted
set types.  The circumstance is that the  amount  of  space  available
will  be inadeqaute for storing each sorted-set index structure during
REKEYing.  To correct the problem, either increase the  last  page  of
the  area  or  increase  the  area's  page  size.  (The comments about
detection and restarting at the end of the next paragraph  also  apply
DBMS5.DOC                                                      Page 34

Except for one circumstance, the information on a page in  a  V3  data
base  can  be  mapped  into  the  same or fewer words in DBMS-V5.  The
exception is a sorted set in which PRIOR pointers are  not  explicitly
specified.   DBMS-V5 always puts a PRIOR pointer into each record in a
sorted set.  Consequently, if an old page is very full  and  has  some
such  records, the conversion process would overflow the page.  If you
are sure this will happen  to  one  or  more  of  your  areas,  simply
increase  that area's page size to the next 128-word-multiple.  If you
do not anticipate this eventuality and it occurs, V3TOV5  will  simply
abort  with  an appropriate message.  At this point, you should modify
the appropriate page size(s) of your  DDL  program  (give  SCHEMA  the
command  line  "schema-name/CREATE/CONVERT")  and  restart  the V3TOV5
phase from its beginning. Improperly Converted .DDL File -  Although it  is  unlikely,
it  is  possible  that  you will improperly convert your old .DDL file
into the new format.  (It is unlikely because the changes  are  either
mechanical,  such  as  USAGE COMP to TYPE FIXED BIN, or involve moving
lines into the sub-schema.) The more likely danger is  that  you  will
try to slip an extra change into your schema--in which case you are on
your own.  In any event, any flaw in the converted schema should  show
up  in  a widespead fashion.  Consequently, after you have renamed the
.??N files to their standard  extensions,  you  should  use  the  DUMP
and/or  USAGE  commands  of  DBINFO  to  validate  that  the  data, as
represented in the new format, is valid.  Abnormal  Abort  during  Conversion -   This  situation  is
defined  by  a  true  abort (eg.  ill mem ref), or the V3TOV5 messages
?VTVSAF or ?VTVDAF.  Basically, it can  be  caused  by  one  of  three

     1.  An improperly converted schema.  Before retrying, check  over
         your changes.

     2.  A spurious monitor error.

     3.  If the problem persists each time you  restart,  it  must  be
         assumed  you  have discovered a bug and the problem should be

Phase specific restart rules:

     1.  If aborted during 1st phase, it  cannot  be  schema  problem.
         Get a fresh copy of your data base and restart the phase from
         the beginning.

     2.  If aborted during the 2nd phase:  check the schema,  recreate
         the  .DBN  files  with SCHEMA, and restart the phase from its

     3.  If aborted during the 3rd phase:   delete  V3TOV5.JRN,  check
         the  schema,  then  restart with the 2nd phase--see preceding
DBMS5.DOC                                                      Page 35 Other V3TOV5 error messages

     ?VTVDUK   V3TOV5 found a sort or calc key in a record that equals
               the  key  in another record, but the schema states that
               duplicates are not allowed.

     ?VTVICS   it is not meaningful to repeat a phase or follow it  by
               an earlier phase (eg.  V3TOV5 followed by EXPUNGE).

     ?VTVNAS   you gave a START without preceding it with a conversion

     ?VTVNMF   in processing your old schema, V3TOV5  found  an  area,
               set,  record,  or  data  name  that  is not in your new
               schema...correct the discrepancy.

     ?VTVOOS   V3TOV5 detects this condition so as  to  guarantee  its
               integrity;  just type R V3TOV5 to do more work.

     %VTVUFA   if the file associated with an  area  is  null  or  not
               found,  V3TOV5  will  automatically  skip that area and
               continue with the next one.  If the  file  should  have
               been found, report the problem or correct your scheam.

     ?VTVUAJ   you have a V3TOV5.JRN file  that  is  in  an  undefined
               state.   You  should  either delete it or run DBMEND as
               described in Resource requirements -  The resource requirements  of  V3TOV5
are  approximately as follows.  It statically requires 15K of core and
will expand its core as necesary for  area  buffers  and  the  in-core
sub-schemas.   The  average expansion will be on the order of 5K.  The
disk space required is phase dependent and is the  entire  data  base:
plus  nothing during the EXPUNGE phase, plus a second copy of the data
base during the V3TOV5 phase, plus a 1-transaction journal during  the
REKEY  phase.   However  by  appropriate  use of the PAUSE switch (see, you can cause "data base" to be replaced by "area".

2.3.2  Simultaneous Update

DBMS-V5 will allow a user to update (or retrieve) data  while  another
updates   data   in   the   same   area/file.    It  will  handle  the
valid-copy-of-data  problem  inherent  in  this  facility   thru   the
mechanism of the ENQ/DEQ monitor calls.

(Note:  the facility relies on the fact that  users  of  a  particular
data base all access the same schema).

Four DBMS components control whether and how  simultaneous  update  is
involved in a run-unit's operation.
DBMS5.DOC                                                      Page 36

     1.  It is the OPEN statement which controls whether a run-unit is
         within  the  domain of the simultaneous update facility.  The
         simultaneous  update  facility  really  consists   of   three
         separate  OPEN  USAGE-MODEs:   UPDATE,  PROTECTED UPDATE, and
         RETRIEVAL.  PROTECTED UPDATE is included because a  PROTECTED
         UPDATER  must  block  out  RETRIEVERS  (and vice versa).  The
         three non-simultaneous usage-modes are  PROTECTED  RETRIEVAL,
         EXCLUSIVE  RETRIEVAL,  and  EXCLUSIVE UPDATE.  The meaning of
         each  USAGE-MODE  is  presented  in  section  3   sub-section

     2.  The OPEN JOURNAL statement communicates to DBCS if a  journal
         will be shared by more than one run-unit -- see

     3.  The IMAGES  statement  of  the  DMCL  controls  the  form  of
         interleaving-unit  employed  by a data base's applications --
         see and

     4.  The interval between a call to JSTRAN and a  call  to  JETRAN
         defines one transaction -- see

The following two tables are intended to provide an  overview  of  the
trade-offs involved in using the simultaneous update facility.


RETRIEVAL               you   intend    other    run-units    to    be
                        simultaneously open for (PROTECTED) UPDATE.

UPDATE                  use only if you really intend for there to  be
                        simultaneous updaters.

PROTECTED RETRIEVAL     use if you expect concurrent retrievers but no
                        concurrent updaters.

PROTECTED UPDATE        use only if you really intend for there to  be
                        simultaneous retrievers.

EXCLUSIVE RETRIEVAL     use only if you need to be selfish.

EXCLUSIVE UPDATE        use rather than (PROTECTED) UPDATE unless  you
                        really  intend  for  there  to be simultaneous
                        updaters or retrievers.
DBMS5.DOC                                                      Page 37

none                        inexpensive     EXCL RETR!UPDATE
simultaneous retrievers     inexpensive     PROT RETR
pseudo-simul updaters       see F1          see H1
command-interleaving        see F2          see H2
  with default transactions see F3          see H3
transaction-interleaving    see F4          see H4

(F1)  Inexpensive but complicates the design/control problem  for  the

(F2)  Minimizes blocking time.

(F3)  Minimizes    blocking    time    while    still     accomodating
      non-interruptable DML command sequences.

(F4)  Minimizes CPU usage and handles  non-interruptable  DML  command
      sequences.   (Note  that  F4 and F3 exist on a continuum, rather
      than being distinct modes).


H2-H4 apply to all the simultaneous update USAGE-MODES.

(H1)  You have run-units that simultaneously open  disjoint  areas  in

(H2)  You optionally define transactions and specify that  images  are
      ordered by command -- see
      (However if this  run-unit  did  not  involve  the  simultaneous
      update  facility, specifying images not ordered by command would
      be an efficiency consideration -- see section

(H3)  You specify that images are not ordered by  command  and  divide
      into  transactions  just those command sequences that require no
      intervention -- see

(H4)  You specify that images are not ordered by  command  and  divide
      all  the  operations  of your run-units into transactions -- see How Simultaneous? -  One makes simultaneous update  "work"  by
recognizing  which microscopic actions of simultaneous updaters cannot
be truly simultaneous.  In other words, one defines the ways in  which
the  operations  of  two run-units can be interleaved (underline it!).
Thus the amount of simultaneity supported is controlled by  the  scope
of  the  resource(s) interleaved upon and/or by the (average) duration
for which a given resource is controlled (ie.  the interleaving-unit).
DBMS5.DOC                                                      Page 38

Let it be stated without proof that the following (increasing)  scopes
of  resource  are  at  least plausible:  a data base page, a data base
area, or the data base;  and that the following  (increasing-duration)
interleaving-units are plausible:  DML verb/command, user transaction,
or  run-unit.   However  as  you  decrease  the  scope   of   resource
controlled,  the  potential  for  two run-units needing resources in a
sequence that will cause deadly embrace is increased.  In  particular,
a  DML  verb  can  manipulate  pages in an arbitrary sequence, thereby
making the data base page an unacceptable scope of resource because of
the  stigma  of  deadly  embrace.  The data base area is an acceptable
scope of resource, but the existing functionality of ENQ/DEQ presently
makes  its  use  unfeasible.   (A  proposal  to  correct  this will be
generated in a separate memo.) Thus, in  DBMS-V5  the  only  scope  of
resource  supported  will  be  control  of  the  data  base itself, in
conjunction with either a DML command as the  interleaving-unit  or  a
user-specified  transaction  as the interleaving-unit (or the run-unit
as   the   interleaving-unit,   ie.    the   three    non-simultaneous

To control which interleaving-unit applies to a particular schema, one
must  use  the IMAGES statement of the DMCL (see section 3 sub-section  In particular, specifying that images are  not  ordered  by
command  will  result  in  transactional interleaving;  and specifying
that images are  ordered  by  command  will  result  in  command-level
interleaving.  Command-interleaving  case -   In  practice,  command-level
interleaving  translates  to:   when DBCS initiates a command, it will
automatically ENQ upon the data base resource (not at all for binding,
STATS, etc.;  shared for FIND, GET, and IF;  and exclusive otherwise);
and  when  it  completes  the  command,  it  will  automatically  DEQ.
Consequently,  even  though  command-level interleaving guarantees the
physical integrity of the data base, it has one limitation;  it  gives
one  no  way  to handle the case where a run-unit requires that no one
intervene while it executes several DML verbs  that  affect  a  single
desired  change  (e.g.   a  passenger wants to change his airplane set
occurrence without being left with no seat at all). Transaction-interleaving case -  There  are  benefits  to  a
large  interleaving-unit,  particularly  in  an  application  in which
simultaneous run-units have a lot of dormant  time  anyway.   One,  an
appropriate  large unit will enforce the logical integrity of the data
base by preventing intervention for a user-determined period of  time.
Two, decreasing the frequency with which a second run-unit manipulates
"your" data base and journal, will decrease the  amount  of  defensive
processing  DBCS  will  have  to  do  (ie.  in a CPU usage sense, your
run-unit will  operate  more  efficiently).   What  should  the  large
interleaving-unit be?  clearly the transaction (ie.  use of JSTRAN and
JETRAN).  First, user-specified transactions  are  by  definition  the
mechanism  by  which a run-unit defines logical operations on the data
base.  Secondly, run-unit interleaving puts a special  burden  on  the
journal  processor, so coordinating journaling and interleaving in the
same units has to be a good idea.
DBMS5.DOC                                                      Page 39

In practice, transaction-interleaving means that:  when DBCS initiates
a  transaction,  it  will  automatically ENQ exclusively upon the data
base resource;   and  when  it  completes  the  transaction,  it  will
automatically DEQ.  However commands not executed in the context of an
active  transaction  (eg.   before  the  first  JSTRAN)  are   handled
specially.   Each  such command will constitute a default transaction,
and the rules of will  apply  to  it.   Also  if  it  is  an
updating  command,  it  will  be given a command header and trailer as
when images are ordered by command.  There are two reasons for default
transactions.    One,   run-units  that  only  retrieve  (particularly
existing  ones)  will  not  have  to   be   troubled   with   explicit
transactions.   Two,  run-units  that  would like the minimum blocking
time   of   command-interleaving   and   wish   to   contain   a   few
non-intervenable  command sequences, can do this with selective use of
explicit transactions.

There   are   two   exception   conditions   directly    related    to
transaction-interleaving.   Exception 38 will occur if you call JSTRAN
while a transaction is already active.  A LIBOL/FOROTS error  will  be
signalled  if  you attempt to do a non-DBMS RETAIN while in the middle
of a transaction. Protection of the current record of the run-unit -  It  is  an
underlying  premise  of  DBMS that all operations on the data base are
done  thru  one  window:   the  current  record   of   the   run-unit.
Consequently,  it  is  necessary that DBCS ensure that a run-unit will
not have its operation confused/aborted because someone  else  deleted
that  record.  The implicit philosophy is that the burden of conflicts
should be on those who perform anti-social activities, ie.  DELETE.

This protection does exist and is completely automatic,  but  it  does
affect the user's environment as follows.

     1.  The FINDing run-unit will retain the found record  shared  if
         it  is  in  an  area  open  for UPDATE or PROTECTED UPDATE or
         RETRIEVAL.  Otherwise it will not retain the found record  at
         all.   It will of course DEQ the old current of run-unit when
         a new one is found.

     2.  When the area in which the current  record  of  the  run-unit
         resides is closed, current of run-unit is dequeued.

     3.  If one does a DELETE  which  eventually  tries  to  delete  a
         record  which  is retained by another run-unit, the DELETE is
         terminated with exception 40 (ie.  resource not available).
DBMS5.DOC                                                      Page 40 New Journal-related Functionality Shared Journals -  If two run-units are  updating  the  same
area simultaneously, they obviously are also updating the journal file
simultaneously.  When a journal is shared like  this,  several  things
must  be  periodically  done to it to ensure its continuing integrity.
And the cost  of  that  work  makes  it  imperative  that  a  run-unit
communicate   to   DBCS   when   its   journal  need  not  be  shared.
Consequently, before OPENing any areas, the  run-unit  should  execute
the following statement:


The EXCLUSIVE keyword should be absent if and  only  if  the  run-unit
will be backing up one or more areas OPENed with USAGE-MODE UPDATE.

Although  its  use  is  suggested,  it  must  be  legal  to  omit   an
open-journal  statement  so  that  existing  DBMS programs will not be
impacted.  So the following rules apply when a open-journal  statement
has  not  been  executed  by  the  time  the  first  updating  open is
attempted.  If the area is being opened  for  exclusive  or  protected
update, an OPEN JOURNAL USAGE-MODE EXCLUSIVE UPDATE will be simulated.
Conversely an OPEN JOURNAL USAGE-MODE UPDATE will be simulated if  the
area is being opened with USAGE-MODE UPDATE.

A secondary benefit of the OPEN JOURNAL statement is that  it  can  be
used  to  force open the journal even when only temporary areas are to
be opened.  Previously this situation was a problem because  usage  of
JSTRAN,  JRTEXT,  etc.   could not be checked out conveniently when it
applied. Journal lifetime -  When a run-unit opens  a  journal,  DBCS
must  decide  whether  it should append to the journal, start anew and
overwrite the journal, or abort because the journal is in an undefined

DBCS will overwrite the journal only if it is in a done-with state.  A
journal is done-with if the images in it have already been merged (see, or you have indicated that all run-units have successfully
completed.   You  indicate this via use of the CLOSE JOURNAL statement
(as opposed to CLOSE RUN-UNIT).  If you  are  the  last/only  run-unit
active  when  you  do  a  CLOSE JOURNAL, DBCS will alter the journal's
label page to indicate that the journal is done-with.  Otherwise CLOSE
JOURNAL  will  be  equivalent  to  CLOSE  RUN-UNIT.   Also  both CLOSE
RUN-UNIT and CLOSE JOURNAL will be  equivalent  to  CLOSE  ALL  if  no
journal is open when either is called.
DBMS5.DOC                                                      Page 41

If a journal is not in a done-with state, DBCS will append  to  it  if
the journal's label page correctly represents the current state of the
journal.  Otherwise it will abort  with  exception  61.   A  journal's
label  page  is  made to correctly reflect the state of the journal by
CLOSE  RUN-UNIT,  CLOSE   JOURNAL,   and   at   the   end   of   every
interleaving-unit  in a run-unit in which the journal is shared.  Thus
exception 61 will occur only when you have previously aborted  one  or
more  updating run-units and not merged the images they generated back
into the data base -- see  (Note:   DBCS  never  supersedes
the  journal (for efficiency reasons).  So if the journal somehow gets
clobbered -- ie.  DBCS generates exception 61 or  63  when  it  should
not--simply delete the journal.) Changes to DBMEND and the journal file -  The  most  obvious
change  is  that  the  journal  must  contain run-unit IDs so that the
changes of a particular run-unit can be isolated when  you  are  using
DBMEND;   and  conversely  DBMEND  must  have  semantics  for denoting
run-unit IDs:

     1.  The form of a boundary indicator goes from "[name:] index" to
         "[name:] index [(run-unit ID)]".

     2.  If a run-unit ID is absent from a boundary indicator,  DBMEND
         ignores  the  run-unit  IDs  in the journal when attempting a
         boundary match.

     3.  The run-unit ID  in  a  completely  unshared  journal  is  0.
         However, the "journal characteristics" message generated when
         a run-unit opens a journal will indicate  in  any  event  the
         run-unit's ID.  The form of the message is:

                  RUN-UNIT ID    id-value
                  schema-name RUN  schema-run-of-last-overwriter

     4.  An  abstract  will  show   which   run-unit   generated   any
         transactions, text, and commands displayed if you specify the
         RUNUNITID option to the DISPLAY command.

(Note:  the addition of the run-unit ID plus expansion of the  journal
label  means  that  V4  journal  files  will  not  be  processable  by
DBMEND-V5;  however  there  is  nothing  to  prevent  one  from  using
DBMEND-V4 to merge V4 journal files).

(Note:  because  a  journal  can  now  contain  updates  of  different
run-units,  it  may  no  longer  be  sorted  by command index and each
transaction index.  Thus DBMEND will no longer be able to determine if
current journal position is "past" the first-processed boundary except
by encountering beginning/end of  journal  before  it  encounters  the
DBMS5.DOC                                                      Page 42

Two other changes to  DBMEND  relate  to  placing  the  journal  in  a
done-with  state.   Specifying  the  /UNLOAD switch for a disk journal
will place it in a done-with state.  Specifying the  /COMPLETE  switch
(see  as well) for a magtape journal will place the journal
(temp file) in a done-with state.

To achieve the DBMS-V3 effect of  a  /COMPLETE  switch  (ie.   journal
truncation), specify COMPLETE jpage.  This will cause a POSITION jpage
followed by placement of an EOF marker after that page. Magtape journaling -  (The program DAEMDB  is  described  in

Magtape journaling works  as  follows.   DBCS  will  initiate  magtape
journaling  if  any  of  the  conditions  in  the  next  paragraph are
satisfied.  It initiates magtape  journaling  by  (1)  using  IPCF  to
communicate  to DAEMDB the MTA unit which is to be the journal and (2)
opening a file called DSK:  journal-name.JRNrest-of-spec.   This  file
is  an  ordinary  journal  file other than for the fact that DAEMDB is
aware of its existence--and from  DBCS's  point  of  view  it  is  the

If any of these conditions are satisfied, magtape journaling  will  be

     1.  DEVCHR of the device in the journal file  spec  (see  section has magtape characteristics.

     2.  If the device in the journal file spec is not  associated  to
         an  actual  disk  device and the text of the device is "MTA",
         magtape journaling will be initiated on the magtape unit  the
         operator chooses.

    However if the magtape service is unavailable, you are  given  the
    opportunity  to  select  disk  instead.   Unless  you  have  a USE
    condition for 0946, DBCS exits after typing:


    You should then (give up or) ASSIGN/DEFINE the journal name  to  a
    disk  device  and  then  type  CONTINUE.  If a DBCS-caused exit is
    incompatible with your application, you should have created a  USE
    condition for 0946 and have made the USE procedure:

     CALL JMDISK     ...merely makes journal device "DSK"
     OPEN the journal as before
     IF error-status not = 0 then abort presumably to get a disk

(Note:  if a DBCS software error is not an issue, also associate  this
USE procedure with exception 0967).
DBMS5.DOC                                                      Page 43

The DAEMDB-interaction codes are:

     0         success, the message will not occur
     1         DAEMDB unavailable (SHUTDOWN already given)
     2         magtape could not be opened
     3         unable to open journal temp file
     4         improper device type after ASSIGN/DEFINE
     5         DBCS software error during initialization
     6         JMDISK already done once
     7         DAEMDB already managing 8 journals

Also the generality of journal device selection is somewhat restricted
under  TOPS-10.   If your journal device on the DECSYSTEM-10 were JRN:
for instance, you would be pretty much restricted  to  having  a  disk
journal.   You  would have to be able to gain control of MTAn in order
to ASSIGN MTAn JRN;  whereas on the DECSYSTEM-20  DEFINE  JRN:   MTAn:
would  allow  you to specify MTAn without your job having control over

The run-unit and DAEMDB interact in essentially the same  way  as  two
concurrent  updating run-units;  each maintains knowledge of the state
of the journal (temp file) by reading and updating the journal's label
page  as  necessary.   And  as  when  a run-unit opens an area (or the
journal) with  USAGE-MODE  UPDATE,  the  run-unit  will  automatically
follow  the  applicable  rules of and retain the data base for
the duration of each interleaving-unit.  Conversely  DAEMDB  does  its
work  by periodically copying the information in the journal temp file
to magtape and then retaining the data base ONLY LONG ENOUGH  TO  MAKE

Because  DAEMDB/run-unit  interaction  is  interleaved,  the  cost  of
magtape  journaling  is  nearly  the  cost of operating with a journal
opened with USAGE-MODE UPDATE.  Thus the cost  of  magtape  journaling
for  a  single  updater  is  somewhat  greater  than  the cost of disk
journaling  for  a  single  updater.   However  the  cost  of  magtape
journaling   and   disk  journaling  is  approximately  the  same  for
simultaneous updaters.

Just as with a shared journal, it  is  the  user's  responsibility  to
guarantee  that  the  protection of the journal temp file is such that
each accessing run-unit can update it.  Note also that  the  name  and
location  of  the journal temp file is established simply by replacing
the device field of the user specified journal spec  with  DSK.   Thus
the JOURNAL statement of the DMCL gives the user complete control over
the name and characteristics of the journal temp file.
DBMS5.DOC                                                      Page 44

There are some beneficial side-effects to the fact  that  the  journal
temp  file is an ordinary disk journal and that DAEMDB is a background
task.  First, when DAEMDB reaches end-of-reel on a magtape,  there  is
no  pause  in user processing--the run-unit's journal temp file simply
grows a little bigger than usual before it is copied  to  magtape  and
truncated  again.   Second,  if DAEMDB aborts for some bizarre reason,
your run-unit will not be  impacted--it  will  simply  become  a  disk
journaler  in effect.  Third, the magtape part of the journal need not
be involved at all in your use of  DBMEND  if  the  images  which  are
relevant are all still in the journal temp file--in this case, you may
simply specify the journal temp file spec (see /UNLOAD  in
to  the  /JOURNAL  switch  rather than the magtape spec and proceed as
usual.  (IMPORTANT NOTE:  keep in mind that journal page  two  of  the
journal  temp  file,  its first data page, is actually at an arbitrary
point in the permanent journal.  In other words, to get an abstract of
the journal temp file, you must "/posit 2" so that DBMEND will know it
must follow "middle of the journal"  protocol  when  initializing  the
abstract).   Fourth,  magtape  management  messages  are  not  seen by
application programs.  Only the job controlling DAEMDB  sees  new-reel
messages or magtape errors reported.

When you do wish to have DBMEND operate  on  a  magtape  journal,  the
following  rules  should be observed.  One, give the /JOURNAL the same
file spec that was given by the aborted run-unit(s) so that DBMEND can
automatically  locate  the  journal  temp  file  as well.  Two, do not
forget to give a /REELS command  if  this  is  a  multi-reel  journal.
Three, if not all the data in the journal temp file has been copied to
magtape (eg.  the system crashed  while  your  run-unit  was  active),
specify  the  /COMPLETE  switch  to cause DBMEND to merge any unmerged
journal temp data with the magtape  journal.   (Note  that  this  will
place  the journal temp file into the done-with state).  Four, proceed
as with a disk journal.

You must be aware of the nature of  the  /COMPLETE  algorithm  to  the
following extent.  DBMEND backspaces three journal pages and simulates
a /POSITION "page the 1st journal-temp-file-page  will  be".   If  the
magtape is in a random position, this operation may fail.  However you
can guarantee success of this positioning by simply  doing  a  /REWIND
before the /COMPLETE. The background MTA journal processor -  DAEMDB is  simply  a
utility to copy data from one or more journal temp files to a matching
set of MTA journals.  It runs as a background task  concurrently  with
application  run-units  and  can  be  run  under OPSER/PTYCON or as an
ordinary time-sharing job.
DBMS5.DOC                                                      Page 45

Application jobs have to can communicate with it via IPCF when opening
or closing the journal--and can because the IPCF name "[SYSTEM]DAEMDB"
is reserved to it.  During an OPEN, the  application  waits  until  it
receives  a  message  back  from DAEMDB before continueing.  Note that
this waiting period includes the time for the operator  to  mount  the
tape  unless  another apllication has already started or a /CREATE was
done at the DAEMDB terminal.  Similarly on a  CLOSE,  the  application
waits  when  it  does  a  "real"  CLOSE  JOURNAL.  Also during a CLOSE
JOURNAL, DAEMDB unloads the magtape and eliminates  the  journal  from
its  table of journal.  CLOSEs when someone else still has the journal
open merely cause some trivial accounting to occur.  Finally, a  CLOSE
RUN-UNIT,  when  you  are  the only run-unit, copies all the currently
remaining data from the journal temp file but leaves the magtape  open
and the journal in DAEMDB's table of journals.

To initialize DAEMDB as an ordinary timesharing job,  just  login  and
type  R  DAEMDB.   To  run  DAEMDB  under OPSER, give this sequence of
commands to OPSER:

     :SLOG 1/2
     :DEF DB=

To run DAEMDB under PTYCON, give this sequence of commands (the  $  is
an altmode):

     DB-LOG OPERATOR ANY a-number

DAEMDB relies heavily upon the schema name associated with each of the
journals  it is managing.  The reliance is realized in terms of volume
ids.  A volume id tells the  operator/DAEMDB  user  which  magtape  to
mount,  and it will conventionally be of the form "aaaabb" so that the
operator can use pre-labeled tapes.  the "a"s are the first letters of
the  schema  name  and  "bb" is the current reel number.  Thus if your
installation supports multiple schemas their initial letter  sequences
must be different.  As well as identifying tapes for the operator, the
volume id tells DAEMDB (in ABORT, CREATE, MOUNT, RETRY) which  of  the
"many" journals it is managing to make "current".  Thus volume ids are
optional only if DAEMDB can identify the journal from  an  immediately
preceding prompt it typed.

The operation of DAEMDB is controlled by the following switches.   Any
unique  abbreviation  is acceptable except for ABORT, EXIT and STOP --
these must be spelled out.  When DAEMDB is  started,  it  presumes  it
just  did  a  polling and goes to sleep for the default polling period
(=100 seconds).  However, whether DAEMDB is active,  sleeping,  or  in
TTY wait, any switch will be processed when it is presented to DAEMDB.
The switches are as follows.
DBMS5.DOC                                                      Page 46

SWITCH                   FUNCTION
ABORT [dev:][volid]      DAEMDB has requested an  operator  action  in
                         response  to  EOT or a magtape error, and the
                         operator has decided that processing  of  the
                         magtape  portion  of  this  journal should be
                         stopped.  The device is for clarity only.

CREATE dev:  volid       Pre-associate  a  magtape  to  its  journal's
                         schema.    No   application  requesting  this
                         journal  will  experience  a  real-time  wait
                         while  the  operator  mounts  his  tape.   Of
                         incidental note:  DAEMDB  will  not  actually
                         know  the  schema  name  until an application
                         starts   will    only    know    it
                         approximately via the volume id.

CURRENT                  Type out the current setting for  each  mode.
                         This is basically a debugging switch.

EXIT                     Exit to the monitor after clearing all active
                         queue requests.  Do not allow a CONTINUE.

GO                       Continue after a STOP

HELP                     Print this table

MOUNT [dev:][volid]      The operator has mounted  a  new  magtape  on
                         dev:   (or  the  device in the prompt if dev:
                         is absent).  Note that MOUNT  and  ABORT  are

POLL seconds             Define and initiate  a  new  polling  period.
                         DAEMDB  will  sleep for n-seconds or until it
                         has something to  do.   The  default  polling
                         period  is  100  seconds.  (It is the journal
                         temp  files  which  are  being   polled   for
                         uncopied data).

RESET                    Simulate    starting     DAEMDB--with     one
                         difference--the  existing  table  of journals
                         remains intact.  It is difficult  to  predict
                         whether this switch is useful, but the intent
                         is to give the operator a  means  of  getting
                         DAEMDB back to a defined state without losing
                         its table of journals.

RETRY [dev:][volid]      Tells DAEMDB to ignore the error it  reported
                         and  repeat  the  operation that failed.  The
                         device would be specified for  clarity  only.
                         This    command    prevents    DAEMDB    from
                         unnecessarily aborting after a  spurious  I/O
                         error  such  as  something  going temporarily
DBMS5.DOC                                                      Page 47

[NO]SHUTDOWN             Tell DAEMDB to not accept  any  new  journals
                         and  to  do  an  EXIT  when all of the active
                         magtape journals  have  been  closed  by  the
                         users.   Prefixing  NO  takes DAEMDB out of a
                         SHUTDOWN  state,  ie.   it  will  accept  new

STOP                     Return to DAEMDB command  level  immediately.
                         The operator would presumably use this switch
                         to give him time to fix  a  magtape  or  some
                         such problem.

THRESHOLD pages          Tells DAEMDB to bother to copy and truncate a
                         journal  temp  file  only  if  it is at least
                         n-pages long.  The default  threshold  is  50
                         journal pages.

WHAT                     Type the state  of  each  journal  DAEMDB  is

DAEMDB does an "action prompt" when a magtape is initially opened  and
each  time the current reel of a journal must be replaced.  The prompt
is:  [ACTION REQUIRED FOR VOLUME volid ON mta].  Also, the prompt  may
have  been  preceded  by a magtape or journal temp file error message.
In any event, you should respond with either the /MOUNT or  /ABORT  or
/RETRY  switch  as appropriate.  Note that the prompt always refers to
the current reel (via the volid), so that to mount a  new  volume  you
should explicitly give the volume id when you do the /MOUNT.  Finally,
in order to protect  against  partially  copied  sequences  that  span
reels,  DAEMDB  types  a message when the first copy-sequence has been
completed on a new reel.   In  other  words,  when  a  reel  is  being
replaced, its replacement should not be considered part of the journal
until DAEMDB responds with [VOLUME volid NOW INITIALIZED]. Guarding Against Non-cooperation  of  Run-units -   There  are
forms of non-cooperation that are not detectable except from long-term
side-efects.  As noted, DBCS can guarantee the physical  integrity  of
the  data  base,  but  only  you  can  ensure  world-view consistency.
However the following forms of non-cooperation are either detected  by
DBCS or declaratively inhibited.

(Declarative Restraints)

     1.  There is one journal per schema unless a run-unit  explicitly
         circumvents this by calling JMNAME.

     2.  The  IMAGES  statement  provides  inherent  co-ordination  of
         journaling and run-unit interleaving.

(Procedural Constraints)

     3.  If you attempt to open an area  with  USAGE-MODE  UPDATE  and
         already  have OPENed your journal exclusively, exception code
         0938 will be returned.
DBMS5.DOC                                                      Page 48

     4.  If you have a shared journal, the only way in which  you  can
         use  JBTRAN  is  as follows:  in transaction mode and with an
         argument of 0.  Otherwise, exception code 1645 is returned.

There is one  "special"  form  of  non-cooperation.   If  an  updating
run-unit  aborts  abnormally,  other  run-units  are  "in  danger"  of
accessing a data base which is  potentially  in  an  undefined  state.
However it is only an illusion for a very simple reason.  So long as a
RESET is not done by the aborted job, all the locks it had in place to
prevent trespass are still in place.  Thus, if the site does not panic
by allowing a RESET to be executed by the aborted job,  it  will  have
all  the  time  in  the  world  to  evaluate  the  situation and react
accordingly (eg.  terminate all the run-units and restart entirely, do
a  RESET because the aborting run-unit did not injure the integrity of
the data base).

2.3.3  Miscellaneous Changes Unrounded Logical Page  Size -   Before  V5,  each  page  size
specified  in the DMCL was rounded up to the next monitor-defined unit
of disk storage (ie.   128-word  multiples  on  the  10  and  512-word
multiples  on  the  20).  However this is not strictly necessary...the
physical page size must be such a multiple, but there is no reason why
the  logical  page  size  cannot  be  as  was  specified  in the DMCL.
Additionally there are two reasons to support this  distinction:   (1)
it  enables a site to account for data expansion by filling an area in
layers (ie.  by gradually increasing page  size)  (2)  as  implied  in
section, it would make a general purpose conversion utility
somewhat easier to use.

This feature does not impact  existing  data  bases;   the  effect  of
unrounded  logical page sizes is felt at precisely one time only, when
a new record is stored. Specifying a Limit to Journal Size -  The JOURNAL statement of
the DMCL has been extended to provide you a means of preventing a disk
journal from growing to an arbitrary size.  By appending,

                   SIZE [IS] integer [TRANSACTIONS]

to the end of a JOURNAL statement, you will cause DBCS  to  reposition
its  journal  file pointer to the beginning of the journal after every
(integer)th transaction.  Thus, a site could use this feature  if  its
situation  is  such  that it knows it will never need to backup a data
base more than (integer) transactions.  This  clause  applies  to  any
run-unit that has a disk journal which is either unshared or for which
images are not ordered by command.

(Note:  a secondary benefit of  this  feature  is  that  disk  journal
efficiency is improved because it is cheaper to rewrite a journal page
than to extend a journal.)
DBMS5.DOC                                                      Page 49 /CONVERT switch for SCHEMA and DBMEND -  The  /CONVERT  switch
has  been  added  to  support  V3TOV5  and to lay the groundwork for a
general purpose data base redefinition utility.

/CONVERT tells SCHEMA to generate .DBN files and a  .SCN  file  rather
than .DBS files and a .SCH file.

Conversely /CONVERT sets DBMEND to process .??N files  and  /NOCONVERT
returns DBMEND to its normal mode.  When you need to use a [NO]CONVERT
switch, it should precede the JOURNAL or (SCHEMA) switch and all OPENs
so that all relevant files will be processed in the correct/same mode. UNANTICIPATED as  an  INTERCEPT  option -   If  one  specifies
than 307 and 326 will be intercepted (or noted).  The purpose of  this
option is to suppress interception only for those exceptions which are
(normally) used to control program flow. The /UNFLAGGED switch  for  FORDML -   This  switch  allows  a
FORDML user to (optionally) omit the "* DBMS" line for single-line DML
statements, provided no other line in the program has "period" as  its
last non-blank non-remark character.  The purpose of this switch is to
allow for smaller, more readable  FORDML  programs  at  the  price  of
conforming to one additional lexical rule. The USE statement -  It has been made easier  to  associate  a
variety  of exceptions with a USE procedure.  Generic exception codes:
one can specify xx00 to associate the procedure to any  exception  for
statement  "xx".   Generic  statement  codes:  one can specify 00yy to
associate the procedure to the exception regardless of  the  executing
statement.    Grab  bag  procedure:   USE  ERROR-STATUS.   will  cause
application of its procedure to each exception which is not covered by
an  earlier USE statement in the program (conversely any USE statement
after this statement would be a no-op).

2.3.4  Summary of Environmental Changes

The following  keywords  have  been  added  to  the  DML:   JMDISK  (a
user-callable  entry)  and  JOURNAL.  The following keywords have been
added to SCHEMA:  TRANSACTIONS.  The /CONVERT switch has been added to
SCHEMA  and  DBMEND.   Exceptions  46, 65, 66, and 67 have been added.
Exceptions 38 have been given a different definition.  Exceptions  31,
40,  45, 61 and 63 have been given more general meanings.  See section
2 subsection 2.1.5 for the updated exceptions table.
DBMS5.DOC                                                      Page 50


     1.  A DBMS  applications  program  cannot  be  restarted  by  the
         ctrl-C/START  sequence;   one can only RUN (GET/START) a DBMS

     2.  If the CLOSE statement signals an exception, the state of the
         system will not be backed up to what it was before the CLOSE.

     3.  Explicit SFD's are not supported in file specs.

     4.  No .DBS file (ie.  DBMS-10 area) may have a page  range  such
         that  it  could  grow to larger than 256,000 disk blocks (one
         block=128 words).

     5.  The word DBMS is a reserved word in the COBOL  compiler,  but
         this  fact is not properly documented nor properly flagged as
         an error.

     6.  User symbols in an INVOKE or ACCESS statement constitute user
         variables   as  far  as  the  COBOL  compiler  is  concerned.
         Therefore they may not be declared anywhere else in the  DATA

     7.  If exception  03  (data-names  from  wrong  record)  occurred
         during  a  GET,  the  UWA  may not be left the same as it was
         before the verb was executed.

     8.  An area cannot be simultaneously  OPEN  twice  (ie.   by  two
         sub-schemas of the same schema) in a run-unit.

     9.  Floating point numbers cannot be dumped by DBINFO on a KA10.

    10.  COBOL  and  FORTRAN   program-units   both   containing   DML
         statements  cannot be mixed in the same load-unit because the
         form of the special  registers  is  different  in  COBOL  and

    11.  The "name" special registers (eg.   ERROR-RECORD)  cannot  be
         simply  compared  to  COBOL  literals  because the former are
         ASCIZ strings (to facilitate displaying them).  To accomplish
         the  comparison,  do  an  EXAMINE LOW-VALUES TO SPACES to the
DBMS5.DOC                                                      Page 51


To install DBMS-10, follow the instructions below:

     1.  To place DBMS-10 on SYS:, follow this procedure:

         a.  Mount the DBMS-10 distribution  tape  (marked  QH101)  on
             MTA0:, and type the following commands:

             R BACKUP
             TAPE MTA0:
             DENSITY installation-dependent
             RESTORE SYS:*.*=DSKB:[10,6]*.EXE
             RESTORE SYS:*.*=DSKB:[10,6]*.HLP

     2.  To prepare to (re)load DBMS-10 (or parts thereof):

         a.  Mount the DBMS-10 distribution  tape  (marked  QH101)  on
             MTA0:, and type the following commands:

             R BACKUP
             TAPE MTA0:
             DENSITY installation-dependent
             restore *.*=dskb:[10,6]*.*

The components of the DBMS package, are as follows:

     COBOL interface

4.1  Converting Existing Applications

There is an inherent overlap between this section  and  section  2.3.1
since V3TOV5 is really a utility to facilitate installation of DBMS-V5
by version 3 sites--rather than a software product.  Accordingly  this
section  attempts  to  explain where V3TOV5 fits into the installation
procedure, while section 2.3.1 explains in detail the  steps  involved
in using it.
DBMS5.DOC                                                      Page 52

Steps to convert your V3 data base:

     1.  Section 2.2 should be read carefully, and application  source
         files  should  be  changed  to  reflect the incompatibilities
         described there.

         The primary change is to the schema DDL data-name entry,  and
         involves  changing  USAGE COMP...  to TYPE...  and moving all
         text (ie.  03 names) into the appropriate sub-schemas.

         The only DML change  that  is  likely  to  cause  any  source
         alterations  at  all  is  that successful FINDs and STOREs no
         longer set up AREA-NAME and RECORD-NAME...the MOVE  statement
         must be used instead.

     2.  Read section 2.3.1 on how to use V3TOV5.
         However if you intend to reload  rather  than  convert,  just
         delete  your  DBS  files  and  SCH  file  and  translate your
         converted DDL program with  SCHEMA  V5  before  running  your
         reloading program.

     3.  The host-language interface has changed.   Existing  programs
         must  be  (re-preprocessed  and)  recompiled  with  the COBOL
         and/or FORTRAN systems built from this tape.

4.2  Configuring the System Software

     1.  DBMSn0 is shorthand for DBMS10/DBMS20.

         TOPS-10 sets should read it as DBMS10
         TOPS-20 sets should read it as DBMS20

     2.  If COBOL support is desired:

         a.  Read  COBOL.MEM  in  the  1st  save  set  of  the   COBOL
             distribution tape (marked QH504).  It will explain how to
             place LIBOL.REL AND LIBSHR.REL onto disk.

         b.  Make sure  that  your  non-DBMS  copy  of  LIBOL.REL  and
             LIBSHR.REL  are  in  the  directory from which DBMSn0.CTL
             will be submitted.

     3.  If FORTRAN support is desired:

         a.  Read FORTRA.MEM in  the  1st  save  set  of  the  FORTRAN
             distribution tape (marked QH500).  It will explain how to
             place FORLIB.REL onto disk.

         b.  Make sure that your non-DBMS copy of FORLIB.REL is in the
             directory from which DBMS10/20.CTL will be submitted.
DBMS5.DOC                                                      Page 53

     4.  Read DBMSn0.CTL.

         a.  In particular, there are DEFINEs  (TOPS-20)  and  ASSIGNs
             (TOPS-10)  at  the  beginning of the CTL file.  Alter the
             logical assignments therein as necessary for your site.

         b.  To load just the OTSs, do this submit:

                  SUB DBMSn0/RES/TIM:15:.

             To load all the  non-OTS  components  as  well,  do  this
             submit instead:

                  SUB DBMSn0/RES/TIM:30:/TAG:DBALL.

         c.  If execution  of  DBMSN0.CTL  should  abort,  you  should
             reperform steps 2b and/or 3b before repeating step 4b.

     5.  Copy the built host systems to SYS:

             LIBOL.REL to SYS:LIBOL.REL
             Cdbots.exe to SYS:LIBO11.EXE

     6.  Copy *.HLP and *.EXE from the 2nd save set of the  DBMS  tape
         to the appropriate system device.

     7.  If support of MTA journaling is desired and you wish  to  run
         DAEMDB  under  OPSER/PTYCON,  insert  at least these commands
         into your system-restart auto file (see for how  to
         setup non-defalt values for DAEMDB's controlling parameters):

         For TOPS-10:

              :SLOG 1/2
              :DEF DB=
              DB-R DAEMDB

         For TOPS-20 (the $ is an altmode):

              DEFINE $DB
              DB-LOG OPERATOR ANY 77777

         If you wish to run DAEMDB as an  ordinary  time-sharing  job,
         simply  login  a  job and type R DAEMDB each time your system
         starts up.

         IMPORTANT:  for the time being at least, one must  pre-assign
         magtapes to the DAEMDB job on TOPS-10.  To do this, simply do
         1 or more MOUNT commands before typing R DAEMDB.
DBMS5.DOC                                                      Page 54

     8.  DBMS-V5 utilizes  the  ENQ/DEQ  facility.   Consequently  you
         should  ensure  that  your  system  is  configured  such that
         sufficient monitor free  space  is  available  to  your  DBMS
         users,  and  that  each DBMS user has global-ENQ capabilities
         and an adequate ENQ quota.  For  TOPS-10  use  REACT  to  set
         quotas  and  capabilities  (ENQ  capability  is  bit  11 (ie.
         100,,0) of the capabilities word).  For TOPS-20, use ^Ecreate
         to  set  ENQ  capability.   Also,  see ENQ/DEQ in the monitor
         installation guide.  As regards quantifying your needs,  they
         are  approximately:   2 locks for each open area plus 2 locks
         per run-unit.

     9.  If magtape journaling  is  desired,  the  comments  regarding
         ENQ/DEQ  apply  to IPCF as well.  As regards quantifying your
         needs, they are approximately 1 send and 1 receive  for  each
         application run-unit;  and (n) sends and receives for DAEMDB,
         where (n) is the number of simultaneous magtape journalers.


The list of internal differences is not truly ordered,  but  there  is
some  attempt to group the DML changes and to group the file-affecting
changes.  Except where noted, these notes are differences  between  V3
and V4 (or V5).  Differences between V4 and V5 are noted individually.

     1.  In earlier versions each reference to a record,  area,  data,
         or  set  name  in  a  DML  statement  would cause a character
         string, representing the name, to be  passed  to  DBCS.   For
         example,  GET  REC1 would have translated to CALL GET('REC1')
         in FORTRAN and ENTER MACRO GET USING  "REC1"  in  COBOL.   In
         version 4, the reference to REC1 will be replaced by an index
         into a table (assigned during schema processing), rather than
         a character string.

         However if the user wishes to explicitly call  a  DBCS  entry
         point,  he may still pass a string--which will be dynamically
         converted to its  table  index.   In  other  words,  although
         FORDML(or  COBOL)  will  generate CALL GET(integer), the user
         can still code CALL GET('REC1') in  his  programs.   However,
         this  string  processing ability applies only to record, set,
         and area names--and not to data-names because data-names  are
         simply not maintained internally at run-time.
DBMS5.DOC                                                      Page 55

     2.  Similarly, keywords such as NEXT  were  passed  as  character
         strings.   These  are  now  passed  as  negative  numbers (to
         distinguish them from the table indexes) and are as follows:

                KEYWORD         CODE
                ONLY             -10
                SELECTIVE        -11
                FIRST            -12
                LAST             -13
                PRIOR            -14
                NEXT             -15
                DUPLICATES       -16
                ALL              -17
                AREA             -18
                RECORD           -19
                SET              -20
                UPDATE           -21
                RETRIEVAL        -22
                RUNUNIT          -23
                PROTECTED        -24
                EXCLUSIVE        -25
                RESERVED         -26
                RESERVED         -27
                JOURNAL          -28     (V5 only)

         When a keyword is expected, a 0 argument indicates a  default
         (or  absent)  keyword.   And the argument indicates an absent
         user-name when a name is expected.

     3.  An indexed sequential access  method  will  be  used  to  add
         members  to  and to search sorted set occurrences.  This will
         greatly speed up STOREs, INSERTs,  and  MODIFYs  that  access
         sorted  sets.   The index structure will be a B-tree in which
         each index block is big enough to contain  16  sort-key/dbkey
         pairs,  unless 16 keys would require more than 120 words.  In
         this circumstance, the index block size will  be  n*pair-size
         where  (n) is such that the product is as near as possible to
         120 and still less than 120.

     4.  The DELETE verb will always completely delete any record that
         it  processes.   In  other  words, the record will be removed
         from each set it is in and  all  space  associated  with  the
         record will be returned to the free pool.
DBMS5.DOC                                                      Page 56

     5.  FIND integer of SET/AREA will no longer generate  a  call  to
         FIND3.   Instead  it  will  generate  a call to the new entry
         point, FINDO.

     6.  The FUNCT.  OTS interface facility, created to  support  LINK
         overlays,  will  be used by DBCS for its own OTS interfacing.
         FUNCT.  is documented in an appendix of the LINK manual.

     7.  The format of an after-image directory file (.RCV files  were
         an  example  of this type of file) has been changed slightly.
         The first (n) pages of an area .TMP file are  the  directory,
         and  there are PAGESIZE*2 entries per directory-page (ie.  18
         bits per entry).  Thus n=!PAGERANGE/PAGESIZE*2!.  The entries
         are  arranged  such  that  the  left-half  of  the first word
         contains the first page pointed to  by  this  directory-page,
         the  left-half  of the 2nd word contains the 2nd page, and so
         on...   thus  the  right-half  of  the  first  word  of   the
         directory-page points to the (PAGESIZE + 1)th page.

         Also, the mechanism by which .DBS files are extended in V4 is
         such  that  unreferenced pages will not be placed in the area
         .TMP file.  Thus temporary areas are now ideal for  debugging
         when  calc  records (which arbitrarily extend .DBS files) are

     8.  The symbol blocks in a .SCH file  and  those  created  during
         BINDing  are  somewhat  different  than  they were in earlier
         versions.  (A complete description of  each  type  of  symbol
         block  will  appear in the version 4 manuals--and does appear
         in  the  UNV  source  file  DBSDCL.MAC,  which  is   on   the
         distribution tape.)

     9.  The format of a page in a  .DBS  file  has  been  changed  to
         improve  record  accessing  efficiency  (and  generalized  to
         support multiple calc-chains per page).   The  format  is  as
         follows (where PAGESIZE is p):

            word 0:       page-number
            word 1:       i ! j
            n words:      calc-chain pointers
            word n+2:     data word
            word j-1:     last data word
            (word j  thru  word p-i-1 are not in use)
            word p-i:     see DBSDCL!offset of record i
            word p-1:     see DBSDCL!offset of record 1
DBMS5.DOC                                                      Page 57

         The value (i) is the highest record number ever used on  this
         page.   The  value  (j) is the offset of the first word which
         does not contain data.  The value (n) is 0 or more and is the
         integer  given in the CALC RPP clause in the ASSIGN statement
         for this area.  Word p-1 back thru  word  p-i  are  the  line
         headers  of  line-1  thru  line-i.  For details, see PH.* and
         LH.* in DBSDCL.MAC.

    10.  The 128-word prefix sector has been supplanted  by  the  area
         status record, see subsection

    11.  The ENQUEUE/DEQUEUE facility, rather than reader  counts,  is
         used  in  version  4 to control concurrent access to an area.
         Note that this means that retrieval-only areas no longer have
         to be protected <022>.

    12.  All system processed strings will  be  represented  in  ASCII
         (rather  than  SIXBIT),  ie.  the relevant special registers,
         AREA-IDs, and privacy locks.

    13.  [V5 only] Journal page headers have been expanded from 4 to 6
         words  and logical blocks have been expanded to 3 words, both
         to accomodate simultaneous  update.   The  make-up  of  these
         headers is detailed in DBSDCL.MAC.

         Because this is such a complicated upgrade, no bug fixes will
         be described.  We wish this upgrade to consolidate DBMS.



[End of DBMS5.DOC]