host.mem

************************************************************************
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                             SYSTEM 1022                              *
*                                                                      *
*                       HOST LANGUAGE INTERFACE                        *
*                                                                      *
*                       USER'S REFERENCE MANUAL                        *
*                                                                      *
*                               FORTRAN                                *
*                                                                      *
*                                COBOL                                 *
*                                                                      *
*                                MACRO                                 *
*                                                                      *
*                                                                      *
*                        Revision 4, May 1986                          *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
*                           SOFTWARE HOUSE                             *
*                                                                      *
*                      Cambridge, Massachusetts                        *
*                                                                      *
*                                                                      *
*                                                                      *
*                                                                      *
************************************************************************












































Copyright 1984 by Software House.  All rights reserved.

Software House, 1105 Massachusetts Avenue
Cambridge, Massachusetts 02138, USA

ISBN 0-912055-17-0

Printed in USA.

Revision 1:  October 1980
Revision 2:  October 1981
Revision 3:  September 1983
Revision 4:  June 1984
Revision 5:  May 1986














               To order any System 1022  documentation,
               call or write to:

                         Documentation Distribution
                         Software House
                         1105 Massachusetts Avenue
                         Cambridge, MA 02138
                         USA
                         (617)661-7023


























This manual reflects version  117B  of  System  1022.   Changes  since
Revision  4,  June  l984,  are  marked  with  bars in the left margin.
Please send any comments or  suggestions  about  this  manual  to  the
Software House Documentation Department.



               Documentation Available for System 1022


Introductory Literature Kit
____________ __________ ___

The Kit provides a cursory introduction to the  System.   Included  in
the Kit are:
        o A brief description of the major features in System 1022
        o A copy of The Data Base, the System 1022 newsletter
                    ___ ____ ____
        o Two DATA DECISIONS reports which describe System 1022
          and Software House
        o The Price Schedule

User's Reference Manual
______ _________ ______

The User's Reference Manual contains complete  information  about  the
interactive use of System 1022.  This is the primary documentation for
the  System.   This  manual  is  available   in   both   printed   and
machine-readable form.  450 pages.


Host Language User's Reference Manual
____ ________ ______ _________ ______

The Host Language (HL) Manual contains information needed to write and
run  FORTRAN,  COBOL,  and MACRO application programs using the System
1022 subroutine library.  This manual is available in both printed and
machine-readable form.  150 pages.


Data Base Administrator's Manual
____ ____ _______________ ______

The Data Base Administrator's (DBA's) Manual explains to the data base
administrator  how  to  install  and maintain System 1022.  The Manual
describes interfacing 1022 to host languages,  patching,  and  control
features  used  by  the  DBA.   The  Manual is specific to the current
version of 1022.   This  manual  is  available  in  both  printed  and
machine-readable form.  100 pages.


Primer
______

The Primer introduces the interactive use of System 1022  to  the  new
user.  The Primer is available in printed form only.  140 pages.


Report Writer Manual:  Operation and Examples
______ ______ _______  _________ ___ ________

The Report Writer Manual contains a collection of reports and detailed
descriptions  of  each  to  illustrate how custom reports are written.
The Manual is available in both printed and machine-readable form.  50
pages.



CHAPTER 1       USING THE SYSTEM 1022 HOST LANGUAGE INTERFACE

        1.1     INTRODUCTION . . . . . . . . . . . . . . . . . . . 1-1
        1.2     SUMMARY OF HOST LANGUAGE ROUTINES  . . . . . . . . 1-2
        1.3     I/O ERROR MESSAGES . . . . . . . . . . . . . . . . 1-5
        1.4     I/O EFFICIENCY -- PMAP . . . . . . . . . . . . . . 1-6


CHAPTER 2       FORTRAN INTERFACE ROUTINES

        2.1     RULES FOR USING THE FORTRAN INTERFACE  . . . . . . 2-1
        2.2     SUBROUTINE ARGUMENTS . . . . . . . . . . . . . . . 2-6
        2.2.1     The ERRT. Option . . . . . . . . . . . . . . . . 2-7
        2.3     TERMINATION OF ARGUMENT LISTS  . . . . . . . . . . 2-8
        2.4     VARIABLE ARGUMENT ARRAYS . . . . . . . . . . . . . 2-8
        2.4.1     FIX. Option  . . . . . . . . . . . . . . . . . . 2-8
        2.4.2     PNT. Option  . . . . . . . . . . . . . . . . . . 2-9
        2.4.3     FXB. Option  . . . . . . . . . . . . . . . . .  2-11
        2.4.4     PTB. Option  . . . . . . . . . . . . . . . . .  2-12
        2.5     RUNTIME TYPE CONVERSIONS . . . . . . . . . . . .  2-14
        2.6     INITIALIZATION ROUTINES  . . . . . . . . . . . .  2-15
        2.6.1     Initializing FORTRAN-10 Or FORTRAN-20 -- DBF6 
                  And DBFOR  . . . . . . . . . . . . . . . . . .  2-16
        2.6.2     Initializing FORTRAN Version 10 With Extended 
                  Sections -- DBFX . . . . . . . . . . . . . . .  2-16
        2.6.3     Initializing FORTRAN-IV -- DBSTRT  . . . . . .  2-16
        2.6.4     Terminating System 1022 Processing -- DBEND  .  2-17
        2.7     DATA SET SELECTION ROUTINES  . . . . . . . . . .  2-18
        2.7.1     The OPEN Command -- DBOPEN . . . . . . . . . .  2-18
        2.7.2     The CLOSE Command -- DBCLOS  . . . . . . . . .  2-19
        2.7.3     The DBSET Command -- DBSET . . . . . . . . . .  2-20
        2.7.4     Data Set Numbers -- DBCSET And DBNSET  . . . .  2-21
        2.8     DATA SET INQUIRY ROUTINES  . . . . . . . . . . .  2-21
        2.8.1     The FIND Command -- DBFIND . . . . . . . . . .  2-21
        2.8.1.1     Advanced DBFIND Features . . . . . . . . . .  2-24
        2.8.2     The SAVE Command -- DBSAVE . . . . . . . . . .  2-25
        2.8.3     The SEARCH Command -- DBSRCH . . . . . . . . .  2-26
        2.8.4     The SELECT Command -- DBSEL  . . . . . . . . .  2-26
        2.8.5     The MAP Command -- DBMAP . . . . . . . . . . .  2-26
        2.8.5.1     Example Of DBMAP . . . . . . . . . . . . . .  2-28
        2.8.6     The Current Number Of Records -- DBNREC  . . .  2-29
        2.8.6.0.1     The GETREC Command -- DBGREC   . . . . . .  2-29
        2.8.7     The DROP Command -- DBDROP . . . . . . . . . .  2-30
        2.8.8     The LET Command -- DBVAL . . . . . . . . . . .  2-30
        2.8.9     Retrieving An Entire Record -- DBGET   . . . .  2-31
        2.8.9.0.1     The LOCK Command -- DBLOCK   . . . . . . .  2-33
        2.8.10    The STARTREC Command -- DBSREC . . . . . . . .  2-34
        2.8.11    The SORT Command -- DBSORT . . . . . . . . . . 2-34A
        2.8.12    The VALUES Command -- DBVALU . . . . . . . . . 2-34B
        2.9     DATA SET UPDATE ROUTINES . . . . . . . . . . . .  2-36
        2.9.1     The CHANGE Command -- DBCHNG . . . . . . . . .  2-36
        2.9.2     The DELETE Command -- DBDEL  . . . . . . . . .  2-38
        2.9.3     The ADD Commands -- DBADD And DBADDR . . . . .  2-38
        2.9.4     The UPDATE Command -- DBUPD  . . . . . . . . .  2-39
        2.9.5     The SET BUFFER Command -- DBBUF  . . . . . . .  2-39



        2.9.6     The ALLOCATE Command -- DBALLO . . . . . . . .  2-40
        2.10    SPECIAL PURPOSE ROUTINES . . . . . . . . . . . .  2-40
        2.10.1    The INFORM ATTRIBUTE Command -- DBINFO . . . .  2-40
        2.10.2    The PERMIT Command -- DBPSWD . . . . . . . . .  2-42
        2.10.3    The Number Of Attributes -- DBNATT . . . . . .  2-42
        2.10.4    Resetting Internal Buffers -- DBCLR  . . . . .  2-42
        2.10.5    Error Handling Routines  . . . . . . . . . . .  2-43
        2.10.5.1    The DBERR Subroutine . . . . . . . . . . . .  2-43
        2.10.5.2    The DBERRH Subroutine  . . . . . . . . . . .  2-44
        2.10.5.3    The DBRETN Subroutine  . . . . . . . . . . .  2-46
        2.10.5.4    The DBERRT Subroutine  . . . . . . . . . . .  2-46
        2.10.6    Converting System Dates -- DBNDAT And DBDATN .  2-47
        2.10.7    Supplying Or Receiving System Variables -- 
                  DBSYSV . . . . . . . . . . . . . . . . . . . .  2-48
        2.10.7.1    Value-passing With System Variables -- 
                    SYSUSER__  . . . . . . . . . . . . . . . . .  2-52
        2.10.8    Executing Interactive Commands And Procedures 
                  -- DBEXEC  . . . . . . . . . . . . . . . . . .  2-52
        2.10.9    Passing Records In Nonstandard Format To 1022 
                  -- DBLODR  . . . . . . . . . . . . . . . . . .  2-55
        2.10.10   DBDBUG Routines  . . . . . . . . . . . . . . .  2-57
        2.10.11   The DBVAR Routine  . . . . . . . . . . . . . .  2-58
        2.11    AUDIT ROUTINES . . . . . . . . . . . . . . . . .  2-58
        2.11.1    Starting The AUDIT Trail . . . . . . . . . . .  2-58
        2.11.2    Writing AUDIT File Checkpoints . . . . . . . .  2-59
        2.11.3    Custom AUDIT Entries . . . . . . . . . . . . .  2-59
        2.11.4    Retrieving AUDIT File Information  . . . . . .  2-59
        2.11.5    Random Access Audit Trail Input  . . . . . . .  2-64
        2.11.6    Loading Programs Containing DBAxxx Calls . . .  2-65
        2.11.7    Examples . . . . . . . . . . . . . . . . . . .  2-65
        2.12    SAMPLE FORTRAN PROGRAMS  . . . . . . . . . . . .  2-67


CHAPTER 3       COBOL INTERFACE

        3.1     RULES FOR USING THE COBOL INTERFACE  . . . . . . . 3-1
        3.2     DATA TYPES . . . . . . . . . . . . . . . . . . . . 3-2
        3.2.1     COBOL Over-Punch Characters  . . . . . . . . . . 3-2
        3.2.2     INTEGER Attributes . . . . . . . . . . . . . . . 3-3
        3.2.3     REAL Attributes  . . . . . . . . . . . . . . . . 3-4
        3.2.4     TEXT Attributes  . . . . . . . . . . . . . . . . 3-5
        3.2.5     DATE Attributes  . . . . . . . . . . . . . . . . 3-5
        3.3     SUBROUTINE ARGUMENTS . . . . . . . . . . . . . . . 3-6
        3.3.1     The ERRT. Option . . . . . . . . . . . . . . . . 3-7
        3.4     SPECIAL RESTRICTIONS . . . . . . . . . . . . . . . 3-7
        3.5     INITIALIZING COBOL -- DBCBL, DBC68, DBC74  . . . . 3-7
        3.6     TERMINATING SYSTEM 1022 PROCESSING -- DBEND  . . . 3-8
        3.7     DATA SET SELECTION ROUTINES  . . . . . . . . . . . 3-8
        3.7.1     The OPEN Command -- DBOPEN . . . . . . . . . . . 3-8
        3.7.2     The CLOSE Command -- DBCLOS  . . . . . . . . .  3-10
        3.7.3     The DBSET Command -- DBSET . . . . . . . . . .  3-10
        3.7.4     Data Set Numbers -- DBCSET And DBNSET  . . . .  3-11
        3.8     DATA SET INQUIRY ROUTINES  . . . . . . . . . . .  3-11
        3.8.1     The FIND Command -- DBFIND . . . . . . . . . .  3-11
        3.8.1.1     Suppression Of Trailing Spaces . . . . . . .  3-14



        3.8.1.2     Advanced DBFIND Features . . . . . . . . . .  3-15
        3.8.2     The SAVE Command -- DBSAVE . . . . . . . . . .  3-16
        3.8.3     The SEARCH Command -- DBSRCH . . . . . . . . .  3-17
        3.8.4     The SELECT Command -- DBSEL  . . . . . . . . .  3-17
        3.8.5     The MAP Command -- DBMAP . . . . . . . . . . .  3-18
        3.8.5.1     Example Of DBMAP . . . . . . . . . . . . . .  3-20
        3.8.6     The Current Number Of Records -- DBNREC  . . .  3-20
        3.8.6.0.1     The GETREC Command -- DBGREC   . . . . . .  3-20
        3.8.7     The DROP Command -- DBDROP . . . . . . . . . .  3-21
        3.8.8     The LET Command -- DBVAL . . . . . . . . . . .  3-22
        3.8.9     Standard Record Format . . . . . . . . . . . .  3-22
        3.8.10    Retrieving An Entire Record -- DBGET   . . . . 3-24A
        3.8.10.0.1    The LOCK Command -- DBLOCK   . . . . . . . 3-24A
        3.8.11    The STARTREC Command -- DBSREC . . . . . . . . 3-24C
        3.8.12    The SORT Command -- DBSORT . . . . . . . . . . 3-24C
        3.8.13    The VALUES Command -- DBVALU . . . . . . . . .  3-25
        3.9     DATA SET UPDATE ROUTINES . . . . . . . . . . . .  3-28
        3.9.1     The CHANGE Command-- DBCHNG  . . . . . . . . .  3-28
        3.9.2     The DELETE Command -- DBDEL  . . . . . . . . .  3-30
        3.9.3     The ADD Command -- DBADD And DBADDR  . . . . .  3-30
        3.9.4     The UPDATE Command -- DBUPD  . . . . . . . . .  3-31
        3.9.5     The SET BUFFER Command -- DBBUF  . . . . . . .  3-31
        3.9.6     The ALLOCATE Command -- DBALLO . . . . . . . .  3-32
        3.10    SPECIAL PURPOSE ROUTINES . . . . . . . . . . . .  3-32
        3.10.1    The INFORM ATTRIBUTE Command -- DBINFO . . . .  3-32
        3.10.1.1    Attribute Numbers  . . . . . . . . . . . . .  3-34
        3.10.2    The PERMIT Command -- DBPSWD . . . . . . . . .  3-34
        3.10.3    The Number Of Attributes -- DBNATT . . . . . .  3-35
        3.10.4    Resetting Internal Buffers -- DBCLR  . . . . .  3-35
        3.10.5    Error Handling Routines  . . . . . . . . . . .  3-36
        3.10.5.1    The DBERR Subroutine . . . . . . . . . . . .  3-36
        3.10.5.2    The DBERRH Subroutine  . . . . . . . . . . .  3-37
        3.10.5.3    The DBRETN Subroutine  . . . . . . . . . . .  3-38
        3.10.5.4    The DBERRT Subroutine  . . . . . . . . . . .  3-39
        3.10.6    Converting System 1022 Dates -- DBNDAT And 
                  DBDATN . . . . . . . . . . . . . . . . . . . .  3-40
        3.10.7    Supplying Or Receiving System Variables -- 
                  DBSYSV . . . . . . . . . . . . . . . . . . . .  3-40
        3.10.7.1    Value-passing With System Variables -- 
                    SYSUSER__  . . . . . . . . . . . . . . . . .  3-45
        3.10.8    Executing Interactive Commands And Procedures 
                  -- DBEXEC  . . . . . . . . . . . . . . . . . .  3-45
        3.10.9    Passing Records In Nonstandard Format To 1022 
                  -- DBLODR  . . . . . . . . . . . . . . . . . . 3-48A
        3.10.10   DBDBUG Routine . . . . . . . . . . . . . . . . 3-48C
        3.10.11   The DBVAR Routine  . . . . . . . . . . . . . . 3-48D
        3.11    AUDIT ROUTINES . . . . . . . . . . . . . . . . . 3-48D
        3.11.1    Starting The AUDIT Trail . . . . . . . . . . . 3-48E
        3.11.2    Entering AUDIT File Checkpoints  . . . . . . . 3-48E
        3.11.3    Custom AUDIT Entries . . . . . . . . . . . . . 3-48E
        3.11.4    Retrieving AUDIT File Information  . . . . . .  3-49
        3.11.4.1    Initialization For AUDIT Retrievals  . . . .  3-49
        3.11.4.2    Random Access AUDIT Trail Input  . . . . . .  3-54
        3.11.5    Loading Programs Using DBAxxx Routines . . . .  3-55
        3.11.6    Examples . . . . . . . . . . . . . . . . . . .  3-56


      3.12    SAMPLE COBOL PROGRAMS  . . . . . . . . . . . . .  3-58


CHAPTER 4       THE SYSTEM 1022 MACRO INTERFACE

        4.1     INTRODUCTION . . . . . . . . . . . . . . . . . . . 4-1
        4.2     SUBROUTINE LINKAGE . . . . . . . . . . . . . . . . 4-2
        4.3     INITIALIZATION . . . . . . . . . . . . . . . . . . 4-3
        4.4     MEMORY MANAGEMENT  . . . . . . . . . . . . . . . . 4-3
        4.4.1     Allocating Dynamic Arrays  . . . . . . . . . . . 4-4
        4.5     I/O MANAGEMENT . . . . . . . . . . . . . . . . . . 4-5
        4.6     LOADING MACRO PROGRAMS . . . . . . . . . . . . . . 4-5
        4.7     SUMMARY  . . . . . . . . . . . . . . . . . . . . . 4-6
        4.8     EXAMPLE MACRO PROGRAM  . . . . . . . . . . . . . . 4-7
        4.9     THE S1022$ MACRO DEFINITION  . . . . . . . . . .  4-10
        4.10    EXAMPLE PROGRAM USING S1022$ . . . . . . . . . .  4-12
        4.11    USERCALL . . . . . . . . . . . . . . . . . . . .  4-13
        4.11.1    Calling Conventions  . . . . . . . . . . . . .  4-14
        4.11.1.1    Calling Sequence . . . . . . . . . . . . . .  4-14
        4.11.1.2    Parameters . . . . . . . . . . . . . . . . .  4-14
        4.11.1.3    Conversions  . . . . . . . . . . . . . . . .  4-15
        4.11.2    Loading Conventions (TOPS-20)  . . . . . . . .  4-16
        4.11.3    Configuring The MACRO Library As A Host 
                  Language Program . . . . . . . . . . . . . . .  4-17
        4.11.4    Example USERCALL Routine . . . . . . . . . . .  4-17


APPENDIX A      HOST LANGUAGE ERROR MESSAGES


APPENDIX B      DATE REPRESENTATIONS

        B.1     RADIX DATE FORM  . . . . . . . . . . . . . . . . . B-1
        B.2     SYSTEM 1022 ENCODED DATE . . . . . . . . . . . . . B-1
        B.3     UNIVERSAL DATE-TIME FORMAT . . . . . . . . . . . . B-1


APPENDIX C      OTHER HOST LANGUAGES

        C.1     REQUIREMENTS . . . . . . . . . . . . . . . . . . . C-1
        C.2     INITIALIZATION . . . . . . . . . . . . . . . . . . C-1
        C.3     CORE MANAGEMENT  . . . . . . . . . . . . . . . . . C-2
        C.4     CHANNEL MANAGEMENT . . . . . . . . . . . . . . . . C-2
        C.5     EXAMPLES: DBMAC, DBCORE, DBCHAN  . . . . . . . . . C-3
        C.6     ARGUMENTS -- XGARG.  . . . . . . . . . . . . . . . C-4
        C.6.1     XGARG. Call  . . . . . . . . . . . . . . . . . . C-4
        C.6.2     GARGL. Definition  . . . . . . . . . . . . . . . C-5
        C.6.3     Requirements Of XGARG. . . . . . . . . . . . . . C-6
        C.6.4     Example: XGARG.  . . . . . . . . . . . . . . . . C-7












                                 CHAPTER 1

               USING THE SYSTEM 1022 HOST LANGUAGE INTERFACE



   1.1  INTRODUCTION

   The System 1022 FORTRAN, COBOL, and MACRO interfaces are used to write
   data  base  applications  using the capabilities of System 1022 from a
   host language.  The Host Language Interface is a group of  subroutines
   which  perform  functions analogous to the commands of the interactive
   System.  We assume  that  the  reader  knows  the  interactive  System
   described in the System 1022 User's Reference Manual.

   Host language routines have the names DBXXXX, where  XXXX  stands  for
   the identifier of the routine.  For example, DBFIND is the analogue of
   the FIND command.  The routines are executed by the CALL statement  in
   FORTRAN and by the ENTER MACRO statement in COBOL.  They are available
   in either a reentrant  (HR1022)  or  non-reentrant  (HL1022)  version.
   Load  your  program with these libraries by a monitor level command of
   the form:

        LOAD file-descriptor(s), SYS:HR1022/LIB     (Reentrant)

                       or

        LOAD file-descriptor(s), SYS:HL1022/LIB     (Non reentrant)

   The following pages summarize the routines and indicate  the  parallel
   command or feature in the interactive System.
   USING THE SYSTEM 1022 HOST LANGUAGE INTERFACE                 Page 1-2
   Revision 5


   1.2  SUMMARY OF HOST LANGUAGE ROUTINES

   The routines are in the following categories:

        Initialization
        Data Set Selection
        Data Set Inquiry
        Data Update
        Special Purpose

   All routines are  useable  from  FORTRAN-IV,  FORTRAN-10,  FORTRAN-20,
   COBOL,  and MACRO, after the appropriate initialization call depending
   on the host language.



                          Initialization Routines
                          ______________ ________

        DBCBL   Initializes the COBOL interface.

        DBEND   Marks the end of System 1022 activities, parallel to
                the QUIT command.

        DBFOR   Initializes the FORTRAN-10 or FORTRAN-20 interface.

        DBMAC   Initializes the MACRO interface.

        DBSTRT  Initializes the FORTRAN-IV interface.




                        Data Set Selection Routines
                        ____ ___ _________ ________

        DBCLOS  Closes the current data set.   Parallels  the  CLOSE
                command.

        DBCSET  Returns  the  number  of  the  current   data   set.
                Parallels the INFORM SET command.

        DBNSET  Returns the number of open data sets.  Parallels the
                INFORM BASE command.

        DBOPEN  Opens one or more data  sets.   Parallels  the  OPEN
                command.

        DBSET   Selects one of several open  data  sets.   Parallels
                the DBSET command.
   USING THE SYSTEM 1022 HOST LANGUAGE INTERFACE                 Page 1-3
   Revision 5


                         Data Set Inquiry Routines
                         ____ ___ _______ ________

        DBDROP  Drops a record from  the  current  selection  group.
                Parallels the DROP command.

        DBFIND  Selects records by KEYED attributes.  Parallels  the
                FIND command.

        DBGET   Returns values for all attributes in a record.

        DBGREC  Enters Local  mode  for  single  record  processing.
                Parallels the GETREC command.

        DBMAP   Selects records from a  second  data  set  based  on
                common  attribute  values  shared  with  the current
                selection group.  Parallels the MAP command.

        DBNREC  Returns the number of  records  currently  selected.
                Parallels the SYSNREC System variable.

        DBSAVE  Saves  retrieval  information  for   the   currently
                selected  group  of  records.   Parallels  the  SAVE
                command.

        DBSEL   Is like DBSRCH, but selection is delayed  until  the
                records are retrieved by another command.  Parallels
                the SELECT command.

        DBSORT  Sorts the currently selected records.  Parallels the
                SORT command.

        DBSRCH  Selects records from  the  current  selection  group
                using  any  attribute  values.  Parallels the SEARCH
                command.

        DBSREC  Halts single record processing and returns to Global
                mode.  Parallels the STARTREC command.

        DBVAL   Retrieves attribute values by name  from  a  record.
                Parallels the LET command.

        DBVALU  For  a  specified  keyed  attribute,  returns   each
                different  value and the number of times each occurs
                in  the  current  selection  group.   Parallels  the
                interactive VALUES command.
   USING THE SYSTEM 1022 HOST LANGUAGE INTERFACE                 Page 1-4
   Revision 5


                          Data Set Update Routines
                          ____ ___ ______ ________

        DBADD   Adds a  record  to  the  data  set.   Parallels  the
                ADD command.

        DBADDR  Adds a record using Standard Record Format.

        DBALLO  Allocates disk space for new records to be added  to
                the data set.  Parallels the ALLOCATE command.

        DBBUF   Allocates  I/O  buffers  for  increased   efficiency
                during  update  and retrieval activities.  Parallels
                the SET BUFFER command.

        DBCHNG  Changes the values of specified attributes  for  the
                currently   selected   record(s).    Parallels   the
                CHANGE command.

        DBDEL   Deletes the currently selected records from the data
                set.  Parallels the DELETE command.



                          Special Purpose Routines
                          _______ _______ ________

        DBAGET  Retrieves entries from the audit trail.

        DBAINI  Initializes the audit file reader.

        DBALOC  Specifies where to begin reading an audit trail.

        DBAUD   Controls audit trails from Host Language programs.

        DBCLR   Resets  internal  buffer  sizes  following  a   core
                expansion to handle large argument strings.

        DBDATN  Converts a month, day, and year  to  a  System  1022
                encoded  date,  the  number of days since January 1,
                1800.

        DBDBUG  Provides a call for debugging programs.

        DBERR   Specifies error handling procedures.

        DBERRH  Specifies error handling procedures.

        DBERRT  Types the error message for the last error that 1022
                encountered.

        DBEXEC  Executes  commands  and  procedures  in  interactive
                System 1022.

        DBINFO  Returns information  about  the  current  data  set.
                Parallels the INFORM ATTRIBUTE command.
   USING THE SYSTEM 1022 HOST LANGUAGE INTERFACE                 Page 1-5
   Revision 5


        DBNATT  Returns the number of attributes in the current data
                set.

        DBNDAT  Converts  a  System  1022  encoded   date   to   the
                corresponding month, day, and year.

        DBPSWD  Specifies passwords for attributes.   Parallels  the
                PERMIT command.

        DBRETN  Returns to user's program after performing an  error
                procedure.  For COBOL users only.

        DBSYSV  Returns or supplies the value of a System variable.

        DBVAR   Determines if a 1022 user variable has been  defined
                and  returns  the variable's type.  If type text, it
                also returns the text length.




   1.3  I/O ERROR MESSAGES

   The I/O error messages print detailed  information  about  I/O  errors
   encountered  during  System 1022 operations.  The messages include the
   DECsystem-10 error code and the file-descriptor  to  which  the  error
   corresponds.

   For example, consider a DBOPEN on a data set  which  does  not  exist.
   The following messages print:

        1022 LOOKUP error (0) File not found File: CHECK.DMS

        1022 error in routine DBOPEN called from 152
        ? (OP2) Data set not found

   The error code (0) indicates that the file does not exist.  The  error
   codes are described in the DEC-10 Software Notebooks, I/O programming,
   Volume 4.  These messages are automatic unless suppressed by using the
   DBSYSV routine to set system variable SYSIOMSG equal to 1.

   The following System variables allow  the  Host  Language  program  to
   handle errors:


             NAME       TYPE             CONTAINS
             ____       ____             ________

           SYSERRDEV   SIXBIT    Structure name or DSK.
           SYSERRFILE  SIXBIT    File name.
           SYSERREXT   SIXBIT    File extension.
           SYSERRPPN   OCTAL     Project-programmer number or directory
                                 number.
           SYSERRCODE  OCTAL     Error code or File Status bits.
   USING THE SYSTEM 1022 HOST LANGUAGE INTERFACE                 Page 1-6
   Revision 5


           Each of these values is 1 word long.

   I/O error messages print for three types of errors:

        o INIT  UUO  errors,  in  which  the  disk  structure  cannot  be
          accessed.

        o LOOKUP, RENAME or ENTER UUO errors, in which the file cannot be
          accessed as needed.

        o Data read/write errors.


   For INIT errors, the variable SYSERRDEV contains the SIXBIT  structure
   name.  It is set to DSK if no structure name was requested.


   All of these System variables are set when a LOOKUP, ENTER, or  RENAME
   error  occurs.   The  variables  SYSERRFILE  and SYSERREXT contain the
   SIXBIT file name and extension.   The  variable  SYSERRPPN  holds  the
   octal  project-programmer  number  or  directory number pair, with the
   project number in the left halfword and the programmer number  in  the
   right halfword.

   The variable SYSERRCODE contains the integer I/O  error  code.   These
   codes are the same ones printed in the error message.


   For read or write errors, the right halfword  of  SYSERRCODE  contains
   the  file status bits of the file in which the error occurred, instead
   of the error code.  File status bits are explained in the DECsystem-10
   Software Notebooks, Volume 4.



   1.4  I/O EFFICIENCY -- PMAP

   System 1022 running under  TOPS-20  uses  the  TOPS-20  PMAP  call  to
   improve most I/O efficiency.

   PMAP requires buffers.  By  default,  systems  with  extended  section
   buffers  use  a  64  page  buffer.   Systems  without extended section
   buffers (2020's or version 4 or earlier of TOPS-20) use  the  defaults
   shown in the table below.


   USING THE SYSTEM 1022 HOST LANGUAGE INTERFACE                 Page 1-7
   Revision 5


         Table: Buffer Defaults, Systems without Extended Sections

                     Pages(decimal)  First Page(octal)  Last Page(octal)

|            COBOL        16              670                677
             FORTRAN      32              600                637
             MACRO        32              600                637
             Stand Alone  32              600                637

   You may specify different buffers for PMAP use with the FPAG.,  LPAG.,
   and XPAG. initialization arguments.  FPAG. and LPAG. specify the first
   and last pages of the buffer.  They are used to  tune  performance  in
   systems without extended section buffers.  For example,

        DBFOR('FPAG.',"600,'LPAG.',"677)

   This defines a 64 page buffer between pages 600 and 677 (octal).

   XPAG. specifies the number of pages  of  buffer.   XPAG.  is  used  in
   systems  with  extended  section  buffers;  specifying location is not
   necessary.  For example,

        DBCBL USING "XPAG.","100"

   Whether you specify or use the default buffers, be certain you are not
   using this memory for other purposes.

   When PMAP arguments and NOSETNAME (see SYSHLNAME in  the  DBA  Manual)
   are  specified  in  the  initialization call, NOSETNAME must be first.
   For example,

        DBFOR('NOSETNAME','XPAG.',100)
   USING THE SYSTEM 1022 HOST LANGUAGE INTERFACE                 Page 1-8
   Revision 5















                                 CHAPTER 2

                         FORTRAN INTERFACE ROUTINES



   2.1  RULES FOR USING THE FORTRAN INTERFACE

   Calls to 1022 using Host Language Interface pass data and keywords  as
   arguments.  These data items are:

        A. Literals, which FORTRAN constructs for the user.

        B. FORTRAN  variables  with  values  assigned  by  the   program,
           including text values.

        C. Arrays containing data constructed  by  the  program,  usually
           when  there  is  not enough space in a simple variable to hold
           the data.

   System 1022 processes three forms of data:

        A. Numeric binary.  The value  of  the  data  item  is  a  single
           computational number in binary form, one word long.

        B. ASCII.  This is also called DISPLAY-7.  Data is  a  string  of
           characters,  as might be typed at the computer terminal.  Each
           character is coded into 7  bits  of  computer  storage.   Five
           characters  usually  fit into each array location, or computer
           word.  In FORTRAN-7, CHARACTER data type array  locations  and
           CHARACTER variables hold varying numbers of characters.

           ASCII data is represented using the following conventions:

                (1) Counted Length
                (2) Delimited by Characters
                    a. Space Delimited and/or
                    b. Null Delimited

           Counted Length, or "counted", means that the proper number  of
           characters  are  included  in  the string when it is passed as
           data.  There must be at least n characters in  the  string  if
           the  routine expects n characters.  Usually, there may be more
           than  n  characters,  in  which  case  the   extra   rightmost
           characters  are  ignored.   Strings  shorter than n characters
           must be filled out to that length, usually with  spaces.   The
   FORTRAN INTERFACE ROUTINES                                    Page 2-2
   Revision 5


           value n is known by 1022 and is not part of the data string.

           FORTRAN-7 allows character data  type  variables,  a  kind  of
           counted  ASCII.   Use  the  DBF6 call to initialize FORTRAN-7.
           CHARACTER variables cannot be EQUIVALENCE'd to  other  FORTRAN
           data  types;   so avoid using CHARACTER arrays with calls that
           return mixed-type data, such as DBINFO.  Set  SYSHLDISP  to  0
           when  returning  data  to  a CHARACTER variable to ensure that
           data returned is ASCII.  See FXB. and PTB. below.

           Delimited strings  have  a  length  determined  by  the  first
           occurrence  of the delimiting character.  In System 1022, this
           delimiting character is the first space,  or  the  first  null
           (the  character  with 7 bit value 0), and sometimes either one
           may be the delimiter.  A null delimited string may  always  be
           formed  by  following  the  string  with a zero computer word.
           This places 5 null characters after the string;  the first one
           delimits  the string.  The delimiting character is not counted
           as part of the data in the string.

           Delimited strings may be "space filled".  This means that  the
           last  computer  word used by the data characters in the string
           is filled out with spaces, unless it  is  originally  full  of
           data.   A  string is space filled by adding spaces until there
           is a multiple of five characters, because each  computer  word
           holds five characters.  An additional null character (or word)
           follows, when the string is "space filled, null delimited".

           FORTRAN constructs a space filled, null  delimited  string  as
           the  value  when  a  quoted  literal string is specified.  The
           program  must  construct  the  proper  type  of  string   when
           constructing its own arguments in arrays.

           1022 ignores Bit 35 (the  last  bit)  in  each  computer  word
           holding  an  ASCII  text  or  ASCII  display value.  Bit 35 is
           cleared when this data is returned to the program from 1022.

        C. SIXBIT.  This is also called  DISPLAY-6.   A  FORTRAN  program
           rarely  uses  this type of data;  it is common in COBOL files.
           SIXBIT data is a string of characters limited  to  the  SIXBIT
           character set.  The SIXBIT character set is the ASCII printing
           character set without lower case  letters  and  without  curly
           brackets,   vertical  bar,  accent  grave,  and  tilde.   Each
           character is coded into  6  bits  of  computer  storage.   Six
           characters fit into each array location or computer word.

           SIXBIT data items are only "counted";  there is  no  delimited
           pattern  as  with  ASCII.   The program may only supply SIXBIT
           values as data for attributes, not as  keywords  or  attribute
           names.   The  last  computer  word  of  a SIXBIT value must be
           filled out with null (zero) SIXBIT characters to a multiple of
           6  characters.   This  is  similar  to  space filling of ASCII
           values.
   FORTRAN INTERFACE ROUTINES                                    Page 2-3
   Revision 5


   System 1022 processes five types of data which have the  above  forms.
   The type needed for an argument is determined by the use of the value,
   by what is expected in the routine,  or  by  the  setting  of  control
   variables  which  specify  to 1022 what form of data, and what type of
   data, to expect.  These types do not depend in any way on the  FORTRAN
   data  type  of  the variable or array which holds the data value.  The
   FORTRAN data type is  only  important  to  the  operation  of  FORTRAN
   statements on the data.

   In what follows, we refer to either ASCII or SIXBIT data with the term
   "text", assuming the proper rules applying to the use of either one.

   An item of data is "supplied" when its  value  is  read  by  1022  for
   processing.  It is "received" when 1022 returns a value to the program
   in a variable or array.  An item is "passed" to 1022 when  it  may  be
   supplied  or received in the context of the discussion.  The rules for
   supplying and receiving an item are the same  unless  differences  are
   described.

   The  five  data  types  and  their  properties  are  described  below.
   Wherever  "variable"  or "array" is mentioned, an array or variable of
   the same FORTRAN type will do as well.  "Array" is used when the  most
   common cases require more than one word of storage for the data.

        A. INTEGER  values   are   either   computational   or   display.
           Computational values are ordinary FORTRAN integer constants or
           single precision variables.  FORTRAN computes with this  value
           properly  when  it  is  stored  in  an  INTEGER  variable.   A
           computational integer is supplied and received in a  variable,
           and occupies one word of computer storage.

           Display integers are text literals, or text values in  arrays.
           A display integer may contain leading spaces, a preceding plus
           or minus sign, digits, a following plus or minus sign (if none
           precedes)  and trailing spaces.  An all blank value is treated
           as zero.  An ASCII display integer is a text literal,  a  null
           delimited  text  string, or a counted string of 15 characters.
           A SIXBIT display integer is a  counted  string  of  12  SIXBIT
           characters.

           Supply a display integer in any of the above forms.

           An ASCII  display  integer  is  received  in  a  field  of  15
           characters,  right  justified,  and  filled  on  the left with
           blanks.  Negative numbers have a preceding minus  sign.   This
           occupies 3 single precision FORTRAN array locations.  A SIXBIT
           display integer is received in a field of 12 characters,  with
           preceding  minus  sign if negative, right justified and filled
           on the left with SIXBIT  null  characters.   This  occupies  2
           single  precision  FORTRAN  array  locations,  or  one  double
           precision variable.  In either case, a zero value is  returned
           as a single 0 character on the right.

           The range for integer values, either display or computational,
   FORTRAN INTERFACE ROUTINES                                    Page 2-4
   Revision 5


           is between + or - 34,359,738,637.

        B. DOUBLE INTEGER values have  the  same  properties  as  integer
           values  except the length and range of values are greater.  An
           ASCII display  double  integer  is  a  counted  string  of  25
           characters  and  a  SIXBIT display double integer is a counted
           string of 24 SIXBIT characters.

           The  range  of  double  integer  values,  either  display   or
           computational,       is       between       +       or       -
           1,180,591,620,717,411,303,423.

        C. REAL   values   are   either   computational    or    display.
           Computational  values  are  ordinary FORTRAN real constants or
           single precision variables.  FORTRAN computes with this  value
           properly  when  it  is  stored  in  a  single  precision  REAL
           variable.  A computational real is supplied and received in  a
           single  variable  or  array location, and occupies one word of
           computer storage.

           Display reals are text literals, or  text  values  in  arrays.
           They  may  contain  the  following  characters:   the  digits,
           optional decimal point, optional preceding sign, and  optional
           "E  field"  as  in  FORTRAN  scientific representation.  Space
           characters may precede and/or follow  the  characters  of  the
           number without changing its value.  Spaces may not be included
           between the characters of the number.  A display real which is
           all space characters is evaluated as zero.

           A  display  real  is  supplied  as  a  FORTRAN  literal,  null
           delimited value, or counted value of length 15 if ASCII, or 18
           if SIXBIT.  This means that a counted display real is always 3
           computer words.

           The program receives a display real in the following form:

             1. The result is right justified in a  field  of  15  or  18
                characters,  whichever  applies, with preceding blanks or
                SIXBIT nulls to fill the field.

             2. If 8 significant digits  can  be  displayed,  the  simple
                decimal  representation (without an E field) is used.  At
                most 15 positions are used to decide this.

             3. If fewer than 8 significant digits  would  display,  then
                the  value  is  displayed  in  scientific  format, namely
                S.nnnnnnnnESnn, where each S stands for a sign or  space,
                E  is  the  E  field  identifier, and each n stands for a
                digit.

           A data set can compute with real values in the range  +  or  -
           1.0*(10**(+ or - 38)).   Eight  digits of precision are stored
           in the data set with small errors in the eighth  digit  during
           computations.
   FORTRAN INTERFACE ROUTINES                                    Page 2-5
   Revision 5


           Double precision FORTRAN real values are  not  accepted  as  a
           System data type.
        D. DATE values are either computational integers, or display.   A
           computational  date is the integer number of days from January
           1, 1800 to the represented date.   For  example,  the  integer
           date  value  of  5  represents  the  day January 6, 1800.  The
           conversion of a date to this number  takes  into  account  the
           leap year rules of the calendar.  See the 1022 routines DBNDAT
           and DBDATN for calls which convert three integers holding  the
           month, day, and year to the computational form.  Display dates
           are text literals, or a two word  counted  text  value  in  an
           array  or  double precision variable.  The format of a display
           date is MM/DD/YYYY or MM/DD/YY, or the ANSI forms YYYYMMDD  or
           YYMMDD.  The two character year implies the years in the range
           1900 to 1999.  For example, '5/26/55' is an acceptable display
           date  representing  the  date  May  26,  1955.  Furthermore, a
           display date can be supplied to 1022 in any form recognized by
           the  interactive  System  if  it  fits  10  ASCII or 12 SIXBIT
           characters.  See  the  description  of  Dates  in  the  User's
           Reference Manual.

           Display dates are supplied as a two word counted, space filled
           text  value,  or  a FORTRAN literal.  An invalid date causes a
           runtime error message and supplies the null  date  January  1,
           1800.

           Display dates are received as a two  word  text  value,  right
           justified and filled on the left with blanks, in the ANSI form
           YYYYMMDD.

        E. TEXT values are counted or null  delimited,  ASCII  or  SIXBIT
           values.  Any FORTRAN literal is a valid text value, like 'AGE'
           and 'EQ'.  Earlier FORTRANs supply such literals  to  1022  as
           space  filled,  null delimited ASCII text.  FORTRAN-7 supplies
           such literals as counted ASCII text.

           Text literals  are  routinely  used  to  supply  keywords  and
           attribute names as arguments in System calls.  The program may
           also construct any null delimited, or  space  delimited,  left
           justified ASCII item for a keyword or attribute name.


           Values for text attributes are supplied as null delimited,  if
           they  are  shorter than the attribute field, and as counted if
           they are longer than or equal to the  attribute  field.   Null
           delimited  values which are supplied for longer attributes are
           used as if they were filled out to the attribute  length  with
           blanks.

           Only the counted form of text  value  is  acceptable  in  some
           cases.  The supplied value must be as long as, or longer than,
           the attribute field being supplied.  See DBADDR for an example
           of this.
   FORTRAN INTERFACE ROUTINES                                    Page 2-6
   Revision 5


           File-descriptors  are  text  values  containing  any  of   the
           characters  normally  included when file-descriptors are typed
           at the terminal.  They may be  literals,  null  delimited,  or
           space   delimited.    Embedded   blanks  are  not  allowed  in
           file-descriptors;  a file descriptor terminates on a space  or
           null, and following text is ignored.


           Text values are received into program variables or  arrays  as
           counted  strings,  space  filled,  and at least as long as the
           field length of the attribute or item being received.

   See also Runtime Type Conversions for details on  runtime  conversions
   between numeric and display items, and between SIXBIT and ASCII.



   2.2  SUBROUTINE ARGUMENTS

   Keywords are passed as text values  to  a  routine  as  shown  in  any
   example.   For  example,  the  NOCLOSE option in the DBOPEN routine is
   selected by including the argument keyword 'NOCLOSE':

        CALL DBOPEN('NOCLOSE','TEST')

   Attribute identifiers are either the text name, text abbreviation,  or
   integer   identification   number  of  the  attribute.   The  name  or
   abbreviation is a literal, or array containing  text.   The  attribute
   number  is  an  integer  constant  or  variable.   The  program  gains
   efficiency by using the attribute number rather than the  name;   this
   avoids  a  runtime  table  lookup,  but  this  is  only significant in
   production programs and often executed loops.  Obtain the  number  for
   any  attribute  with  the  DBINFO  routine,  to preserve complete data
   independence in a  program  using  attribute  numbers.   For  example,
   assume  that  AGE is the third attribute in a data set.  The following
   statements are equivalent:

        CALL DBVAL ( 3, IAGE)
        CALL DBVAL ('AGE', IAGE)
        CALL DBVAL (NAGE, IAGE)    Where NAGE has the value 3
        CALL DBVAL (TAGE, IAGE)    Where TAGE contains 'AGE  '

   Rather than use the literal 3 in the first call, it is correct to  use
   the  attribute  name  as  a  literal,  or to use a variable NAGE which
   supplies the attribute number as retrieved from a call to DBINFO.  The
   program  will  not  be  invalid if AGE is in a different position in a
   future version  of  the  data  set.   The  fourth  form  provides  the
   attribute  name  as  text in a variable.  It is no more efficient than
   the second form, but may be convenient in general applications.

   The following rules apply  to  text  values  passed  in  variables  or
   arrays:

           a) Values start  on  a  word  boundary  and  are  left
   FORTRAN INTERFACE ROUTINES                                    Page 2-7
   Revision 5


              justified within the word.

           b) File-descriptors are terminated  by  at  least  one
              blank or null, and do not contain embedded blanks.

              Example:

                   CALL DBOPEN('DSKB:TEST[400,15]')

                             is equivalent to

                   FILE(1)='DSKB:'
                   FILE(2)='TEST['
                   FILE(3)='400,1'
                   FILE(4)='5]   '
                   CALL DBOPEN(FILE)

           c) Follow keywords or attribute names which contain  a
              multiple  of  five characters with a zero word or a
              blank word, 'bbbbb'.  Fill  the  remainder  of  the
              last storage word with blanks when the last word is
              not filled with characters.   Embedded  blanks  are
              not allowed.

           d) Text received from an attribute  contains  as  many
              characters  as  the attribute.  For example, if the
              value LAURA is received  as  a  value  for  the  10
              character  attribute  NAME,  two computer words are
              received;   the  first  contains  'LAURA'  and  the
              second contains blanks.



   2.2.1  The ERRT.  Option

   When DBERR error handling is in effect, the argument list for any 1022
   host  language  call  in  which  an  error  is  possible,  except  the
   initialization routines, may begin with:

        ('ERRT.',$label-1,...)

   Control transfers to  $label-1  if  an  error  occurs  executing  this
   statement.  System 1022 performs all error actions specified to DBERR,
   for example, error message type  out  or  suppression,  but  does  not
   execute the central error routine which may have been specified.
   FORTRAN INTERFACE ROUTINES                                    Page 2-8
   Revision 5


   2.3  TERMINATION OF ARGUMENT LISTS

   The argument  list  for  any  interface  routine  may  be  prematurely
   terminated  with  the  string  'END.' as an argument.  This is used to
   construct calling sequences  at  run  time,  especially  with  DBFIND,
   DBADD, and DBCHNG.


   Examples:

       1.  CALL DBFIND('NAME','EQ','FRED')

                is equivalent to

           CALL DBFIND('NAME','EQ','FRED','END.',0,0,0,0)

       2.  CALL DBCHNG('NAME','FRED')

                is equivalent to

           AT1 = 'NAME '
           VAL1 = 'FRED'
           AT2 = 'END. '
           CALL DBCHNG(AT1,VAL1,AT2,VAL2,AT3,VAL3,AT4,VAL4)



   2.4  VARIABLE ARGUMENT ARRAYS

   System 1022 accepts long argument  strings  stored  in  arrays.   This
   allows  easier  modification  of  the  argument strings at runtime, in
   programs designed to handle more than one data set structure.

   Four schemes exist  for  passing  the  argument  arrays:   the  first,
   denoted  by  the  keyword  'FIX.', uses a fixed storage length for all
   arguments;  the second, denoted by 'PNT.', uses  a  pointer  array  to
   locate  successive  arguments  in  the  main  array.  The fixed length
   scheme is the simplest to use, but can be  wasteful  of  array  space.
   The  pointer  array scheme may save this space.  The third and fourth,
   denoted by 'FXB.' and 'PTB.', parallel 'FIX.' and 'PNT.' for character
   arrays.



   2.4.1  FIX. Option

   The 'FIX.' scheme uses a single array, with  each  argument  occupying
   the  same  number  of  array  locations,  and  is  used in any CALL as
   follows:

        CALL DBXXXX('FIX.',SPACE,COUNT,ARRAY)

   Where:
   FORTRAN INTERFACE ROUTINES                                    Page 2-9
   Revision 5


   'FIX.'    Is the option identifier, usually a quoted literal.

   SPACE     Is  the  integer  number  of  locations  occupied  by   each
             argument.

   COUNT     Is the integer number of arguments being passed.

   ARRAY     Is the array containing the argument string.

   For example, consider the following CALL to DBFIND:

        CALL DBFIND('SYSID','NE',20)

   which can be passed in an array with the FORTRAN fragment shown below:

                DIMENSION IARR(10)
                DO 12 I=1,10
        12      IARR(I)='     '
                IARR(1)='SYSID'
                IARR(3)='NE'
                IARR(5)=20
                CALL DBFIND('FIX.',2,3,IARR)

   A spacing of two words  per  argument  is  used  because  the  keyword
   'SYSID'  must be followed by a null word (see the rules for using text
   arguments above).

   The program allocates the  same  amount  of  storage  space  for  each
   argument  when  using  the  FIX.  scheme.   The  size required for the
   largest argument is used for all the arguments.

   Consider as a comparison, adding records to a data set containing  the
   titles,  authors, and abstracts of documents.  This is not the easiest
   way to do the example, but illustrates the  technique.   This  is  the
   easiest way for complex systems to construct calls at runtime.

   The length for each item is:  50 characters for the title, 25 for  the
   author,  and 500 for the abstract.  The FIX. scheme requires a minimum
   array size of 600 words for a CALL  to  DBADD,  because  the  abstract
   requires 100 words and there are six arguments in the CALL.



   2.4.2  PNT. Option

   The 'PNT.' scheme is an alternative to the 'FIX.' scheme  when  'FIX.'
   requires  too  much  space.   In  the  'PNT.'  scheme, a pointer array
   locates the position of each argument in the main array.  The form  of
   the CALL is:

        CALL DBXXXX('PNT.',IPTR,IARR)

   Where:
   FORTRAN INTERFACE ROUTINES                                   Page 2-10
   Revision 5


   'PNT.'  Is the option keyword.

   IPTR    Is the pointer array name.

   IARR    Is the main array name.

   The previous example of a DBFIND is done as  follows  using  the  PNT.
   scheme:

                DIMENSION IARRAY(10),IPTR(5)

                IPTR(1)=1
                IARRAY(1)='SYSID'
                IARRAY(2)='     '

                IPTR(2)=3
                IARRAY(3)='NE'

                IPTR(3)=4
                IARRAY(4)=20

                IPTR(4)=0

                CALL DBFIND('PNT.',IPTR,IARRAY)

   1022 retrieves the arguments starting at  the  location  specified  by
   each  successive pointer word, until reaching a zero pointer word.  In
   the above example the first argument starts at the first word in IARR,
   the  second  argument starts at the third word, and the third argument
   starts at the fourth  word.   Because  IPTR(4)  is  zero,  no  further
   arguments are retrieved.

   FORTRAN INTERFACE ROUTINES                                   Page 2-11
   Revision 5


   The pointer option is most useful with arguments  varying  greatly  in
   length,  such  as  the  application  for document titles, authors, and
   abstracts mentioned above.  The following FORTRAN fragment reads these
   items  from  a  formatted  ASCII  file  and adds them to a data set by
   successive CALLs to DBADD using the PNT. scheme:

                IMPLICIT INTEGER (A-Z)
                DIMENSION TITLE(10),AUTHOR(5),ABSTRT(100)
                DIMENSION POINT(7),ARRAY(150)
                EQUIVALENCE (ARRAY(3),TITLE)
                EQUIVALENCE (ARRAY(15),AUTHOR)
                EQUIVALENCE (ARRAY(22),ABSTRT)
                DATA POINT/1,3,13,15,20,22,0/
                 .
                 .
                DO 10 I=1,150
        10      ARRAY(I)='     '
                ARRAY(1)='TITLE'
                ARRAY(13)='AUTHO'
                ARRAY(14)='R    '
                ARRAY(20)='ABSTR'
                ARRAY(21)='ACT  '
                 .
                 .
        100     READ(1,105) TITLE, AUTHOR, ABSTRT
        105     FORMAT(10A5,1X,5A5 / 5(20A5 / ))
                CALL DBADD('PNT.',POINT,ARRAY)
                 .
                 .
                GOTO 100
                 .
                 .
                STOP

   Fewer than 150 words of storage are required here by the PNT.  method,
   compared  to  the  600 words required for this application by the FIX.
   scheme.

   1022 ignores the FORTRAN data type (real or integer) of an array  used
   as  in  the  above  example.   However,  FORTRAN will perform unwanted
   conversions on data that is transferred to  an  array,  to  match  the
   FORTRAN  array  type.  A solution is to define two arrays, one integer
   and the other real, and equivalence them.  Then,  reference  the  real
   array  to  process real data, and the integer array to process integer
   data.



   2.4.3  FXB. Option

   The FXB. option parallels the FIX. option.   It  allows  you  to  pass
   arguments  to  1022 routines using CHARACTER arrays.  Argument strings
   need not be word-aligned.  Since using FXB. indicates that strings are
   being used, DISP. is assumed (see "Runtime Type Conversion").
   FORTRAN INTERFACE ROUTINES                                   Page 2-12
   Revision 5


   The call is as follows:

        CALL DBxxxx('FXB.',SPACE,COUNT,ARRAY)

   Where:

   'FXB.'  Is the option identifier, usually a quoted literal.

   SPACE   Is the integer number of characters occupied by each argument.

   COUNT   Is the integer number of arguments being passed.

   ARRAY   Is the array containing the arguments.

   For example:

        CALL DBFIND('SYSID','NE',20)

   becomes:

             CHARACTER*4 IARR(10)
             DO 12 I=1,10
        12   IARR(I)='    '
             IARR(1)='SYSI'
             IARR(2)='D   '
             IARR(3)='NE  '
             IARR(5)='20  '
             CALL DBFIND('FXB.',8,3,IARR)



   2.4.4  PTB. Option

   The PTB. option parallels the PNT. option.   It  allows  you  to  pass
   arguments  to  1022 routines using CHARACTER arrays.  Argument strings
   need not be word-aligned.  Since using PTB. indicates that strings are
   being  used,  DISP.  is  assumed (see "Runtime Type Conversion").  The
   call is as follows:

        CALL DBxxxx('PTB.',IPTR,IARR)

   Where:

   'PTB.'  Is the option identifier, usually a quoted literal.

   IPTR    Is the  integer  array  that  contains  character  numbers  of
           arguments in IARR.

   IARR    Is the array containing the arguments.

   FORTRAN INTERFACE ROUTINES                                   Page 2-13
   Revision 5


   For example:

        CALL DBFIND('SYSID','NE',20)

   becomes:

             INTEGER IPTR(5)
             CHARACTER*7 IARR(10)
             IARR(1)='SYSID N'
             IARR(2)='E      '
             IARR(3)='     20'
             IPTR(1)=1
             IPTR(2)=7
             IPTR(3)=10
             IPTR(4)=0
             CALL DBFIND('PTB.',IPTR,IARR)

   When using PTB., there is no length specified for each argument.   The
   length  is  determined  by the argument.  Keywords, attributes, system
   variable names, and so on are all terminated by a space or a null.

   Values being supplied or returned must be of the proper length for the
   attribute  type  and  length.   In  the preceding example, the display
   value of 20 begins at character number 10 and is  12  characters  long
   (because  it  is  integer).  For text attributes, the attribute length
   should be used to allow for embedded spaces.  For supplied values, the
   value may be terminated with a null if a shorter string is desired.

   Note that in many cases results equivalent to a call using 'PTB.'  can
   be  achieved  using  FORTRAN-7 substrings.  The following examples are
   equivalent, but the second uses somewhat less  memory  and  uses  1022
   more  efficiently.   In  the following examples "FN" and "LN" are text
   length 6.

   Example using PTB.:

        CHAR*6 ARGS(4)
        INTEGER PTR(5)
        DATA (ARGS(I),I=1,4)/'FN    ','ANGELA','LN    ','DAVIS '/
        DATA (PTR(I),I=1,5)/1,7,13,19,0/
        CALL DBADD ('PTB.',PTR,ARGS)


   Example using substrings:

        CHAR*15 ARGS
        DATA ARGS/'FNANGELALNDAVIS'/
        CALL DBADD (ARGS(1:2),ARGS(3:8),ARGS(9:10),ARGS(11:15))
   FORTRAN INTERFACE ROUTINES                                   Page 2-14
   Revision 5


   2.5  RUNTIME TYPE CONVERSIONS

   The program may supply/receive attribute  values  in  either  numeric,
   DISPLAY-7,  or  DISPLAY-6  modes  to/from  any  of  the  Host Language
   routines.

   Type conversions are controlled globally with  System  variables,  and
   locally in a subroutine call with keywords.

   Define  global  conventions  by  setting  the  values  of  the  system
   variables  SYSHLMODE and SYSHLDISP.  The routine DBSYSV assigns values
   to these System variables.  They have the following effect:

        1. SYSHLDISP

           This System Variable specifies the  display  type  of  display
           attribute  values  in  the  program.   This  does  not  affect
           keywords and attribute names, which are always DISPLAY-7.

             A. A value  of  zero  (the  default)  directs  that  display
                attribute values are passed as DISPLAY-7.

             B. A value of +1 directs that display attribute  values  are
                passed as DISPLAY-6.

        2. SYSHLMODE

           SYSHLMODE specifies whether numeric attribute values are to be
           passed in computational form or in display form.

             A. A value of zero directs that numeric values be passed  in
                the  same  form  that they have in the data set:  numeric
                values in computational form are passed in  computational
                form,  and  values  in display form are passed in display
                form.  When  values  are  passed  in  display  form,  the
                setting  of  SYSHLDISP determines whether they are passed
                as  DISPLAY-6  or  as  DISPLAY-7.   Numeric  values   for
                attributes  are passed in display form for unbundled data
                sets, and in computational form for bundled data sets.

             B. A value of +1 directs that numeric values for  attributes
                are  passed in display form, in DISPLAY-7 or DISPLAY-6 as
                determined by SYSHLDISP.

             C. A value of -1 (the default) directs that  numeric  values
                for attributes are passed in computational, binary form.

   Change the mode for a single argument  with  the  following  keywords.
   Precede  the  attribute  name  in any subroutine call with the keyword
   'DISP.' to pass a display numeric value, or 'BIN.' to  pass  a  binary
   numeric   value.   These  individual  argument  keywords  have  effect
   regardless of the setting of SYSHLMODE.  Display numeric arguments are
   passed in ASCII or SIXBIT depending on the setting of SYSHLDISP.
   FORTRAN INTERFACE ROUTINES                                   Page 2-15
   Revision 5


   For example, consider the following calls:

        CALL DBVAL ('AGE', IAGE)

           IAGE receives the value of AGE in the current mode as  set  by
           SYSHLMODE.   This statement works properly only when AGE is in
           a bundled data set,  or  when  SYSHLMODE  is  set  for  binary
           numeric, because the variable IAGE is a single word integer.

        CALL DBVAL ('DISP.', 'AGE', IARRAY)

           IARRAY receives the value of AGE in display  form,  regardless
           of global flag settings.

        CALL DBVAL ('BIN.', 'AGE', IAGE, 'SALARY', ISAL)

           The integer variable IAGE receives the  binary  value  of  AGE
           regardless  of  its form in the data set, or of the setting of
           SYSHLMODE.  The effect of 'BIN.' stops with  AGE;   SALARY  is
           received according to SYSHLMODE.

   The default settings of SYSHLDISP and SYSHLMODE usually make the above
   keywords unnecessary.  DISPLAY-7 (ASCII) is the default text mode, and
   binary is the default numeric mode.  FORTRAN  applications  will  work
   consistently  regardless  of the form of the data set, whether bundled
   or  unbundled.   The  keywords  'DISP.'  and  'BIN.'  are  useful   in
   applications which access any data set.

   Values are passed following these data type conversion  rules  in  the
   following  routines:   DBADD,  DBADDR,  DBCHNG, DBFIND, DBSEL, DBSRCH,
   DBSYSV, and  DBVAL.   No  automatic  conversions  are  made  in  other
   routines.



   2.6  INITIALIZATION ROUTINES

   1022 accepts FORTRAN-10,  FORTRAN-20,  or  FORTRAN-IV  programs.   The
   initial  call  starts  1022,  and specifies which language and FORTRAN
   object time system are used.  The initial CALLs are:

        DBF6      When the FORTRAN-10  or  FORTRAN-20  compiler  and  the
|                 FOROTS object time system are used with FORTRAN version
|                 6 or later.
|  
|       DBFOR     When the FORTRAN-10 or FORTRAN-20 compiler  and  FOROTS
|                 object  time  system  are used with FORTRAN-5.  At some
|                 sites, DBFOR may also be used interchangeably with DBF6
|                 to  initialize  programs in FORTRAN version 6 or later.
                  Consult your System Administrator to determine if yours
                  is such a site.

                  At all sites, DBF10 may be  used  interchangeably  with
                  DBFOR.  DBF10 is simply the old name for DBFOR.
   FORTRAN INTERFACE ROUTINES                                   Page 2-16
   Revision 5


|       DBFX      When the  FORTRAN-20  compiler  is  used  with  FORTRAN
|                 version  10  to  run programs that make use of extended
|                 sections.

        DBSTRT    When the older  F40  compiler  and  FORSE  object  time
                  system are used.

|  The call to DBF6, DBFOR, DBFX, or DBSTRT  is  made  before  any  other
   System  calls.   After  all  System  1022  activity  is  finished in a
   program, a call to DBEND performs any cleanup needed by 1022.  After a
|  call  to  DBEND, another call to DBF6, DBFOR, DBFX, or DBSTRT restarts
   1022.



   2.6.1  Initializing FORTRAN-10 Or FORTRAN-20 -- DBF6 And DBFOR

   Initialize the FORTRAN-10 or FORTRAN-20 interface by  a  CALL  to  the
   DBF6 routine if you are running FORTRAN-6 or FORTRAN-7:

        CALL DBF6

   If you are running FORTRAN-5 or if the Data Base Administrator at your
   site  has  installed  1022  in such a way as to allow DBFOR to be used
   interchangeably with DBF6, initialize  the  FORTRAN-10  or  FORTRAN-20
   interface by a CALL to DBFOR:

        CALL DBFOR
|  
|  
|  
|  2.6.2  Initializing FORTRAN Version 10 With Extended Sections -- DBFX
|  
|  Initialize the FORTRAN-20 interface by a CALL to the DBFX  routine  if
|  you  are  running FORTRAN version 10 and your applications make use of
|  extended addressing mode:
|  
|       CALL DBFX
|  
|  To use extended sections with System 1022, you must load with  HR1022.
|  System 1022 reserves sections 0 and 36 for its own use.



   2.6.3  Initializing FORTRAN-IV -- DBSTRT

   Initialize the FORTRAN-IV interface by a CALL to the DBSTRT routine:

        CALL DBSTRT(IUNIT1,ICODE1, IUNIT2,ICODE2,...)

   This initializes 1022 and reserves space for  FORTRAN  devices.   Each
   FORTRAN  logical  unit  number to be used later in the program must be
   represented in the call.  The parameters are:
   FORTRAN INTERFACE ROUTINES                                   Page 2-17
   Revision 5


        1.  IUNIT1 - A FORTRAN logical unit  number  which  will  be
                     used in the FORTRAN program.

        2.  ICODE1 -  0 - The unit is used only for input.
                      1 - The unit is used only for output.
                     -1 - The unit is used for input and output.

        3.  IUNIT2 - Additional unit number(s) to  be  used  by  the
                     FORTRAN  program,  accompanied by corresponding
                     ICODE(s).  The program must represent  all  I/O
                     devices  by a pair of IUNIT and ICODE arguments
                     in the CALL to DBSTRT.

   No harm is done by reserving more unit numbers than the program  uses,
   or by specifying -1 (input/output) for a unit used for input or output
   only.  The effect is to  reserve  more  memory  than  needed  for  I/O
   operations.

   If the following FORTRAN statements  are  used  in  the  program,  the
   specified unit numbers must be given:

             Statement             Unit Number

             TYPE                       -1
             PUNCH                      -2
             PRINT                      -3
             ACCEPT                     -4
             READ                       -5

   Example:

        CALL DBSTRT(1,-1,-4,0,-1,1)

   The program initializes System 1022.  The  program  uses  unit  1  for
   input and output, as well as ACCEPT and TYPE statements.



   2.6.4  Terminating System 1022 Processing -- DBEND

   Terminate System processing by a CALL to the DBEND routine:

        CALL DBEND

   Use the DBEND routine in the  FORTRAN  program  after  all  data  base
   operations  are  completed.   It  closes  all  data  sets and performs
   cleanup operations such as releasing memory.
   FORTRAN INTERFACE ROUTINES                                   Page 2-18
   Revision 5


   2.7  DATA SET SELECTION ROUTINES

   These routines select data sets for later  operations.   The  routines
   parallel  the  interactive  commands described in the section Choosing
   the Data set in the User's Reference Manual.



   2.7.1  The OPEN Command -- DBOPEN

   The DBOPEN routine connects the program to one or more data sets.  The
   CALL is:
|       CALL DBOPEN(['NOCLOSE',] [DS1,'IN',] IDS1 [,'PASSWORD',password]
|  
|                    { 'READONLY' }
|         [,'ACCESS' {            }] [,'AS',alias]
|                    { 'RO'       }
|  
|            [ [,DS2,'IN'],IDS2... ])

   Each DSn is a data set name and each IDSn is a  file-descriptor  which
   names  a  data  set  file.   All  of  the  named  data sets are opened
   simultaneously, for later access using the DBSET routine.   Previously
   open  data  sets  are  closed unless the NOCLOSE keyword is used.  All
   data sets in a file are opened when no data set name is provided in an
   "IN" clause of an OPEN command.

   Example:    CALL DBOPEN ('DSB', 'IN', 'TEST', 'INVNT')

        We assume that the file TEST.DMS contains the two data  sets  DSA
        and DSB, and that the file INVNT.DMS contains the data sets PARTS
        and ORDER.  The above call opens the data sets  DSB,  PARTS,  and
        ORDER  at  the  same time.  Each data set is assigned a "data set
        number" starting from 1 in the order that it  is  opened.   Thus,
        DSB  is  data set #1, PARTS is data set #2, and ORDER is data set
        #3.  These numbers can be used in DBSET  and  other  routines  to
        select the current data set from among the open data sets.

   If the first argument to DBOPEN is the  keyword  'NOCLOSE',  then  any
   data sets already open will remain open.  The new data set numbers are
   assigned starting one greater than the highest data set number already
   assigned,  except  NOCLOSE  first  assigns  any  data set numbers left
   available by data sets that were closed (see DBCLOS).

   Each DSn is a text string containing the data set name as used in  the
   interactive System.

   Each IDSn file-descriptor is a text string naming  the  file,  like  a
   file-descriptor  in  the  interactive System.  Parts of the descriptor
   may be omitted, and default to device DSK and the current disk area.

   FORTRAN INTERFACE ROUTINES                                   Page 2-19
   Revision 5


|  If a password is required to open  a  data  set,  use  the  'PASSWORD'
|  clause in the call, following the file-descriptor to which it refers:
|  
|       For example:
|  
|       CALL DBOPEN('ACCTS','PASSWORD','ABC','INVNT')
|  
|  This opens both the data set ACCTS.DMS, for which the password ABC  is
|  required,  and  the  unprotected  data  set  INVNT.DMS.   The  keyword
|  PASSWORD may be abbreviated PASSW.
|  
|  You can open a data set in readonly  mode  with  the  ACCESS  READONLY
|  clause of the DBOPEN call.
|  
|  For example:
|  
|       CALL DBOPEN('ACCTS','PASSWORD','ABC','ACCESS','READONLY')
|  
|  This opens the password-protected data set  ACCTS  in  readonly  mode.
|  The keyword READONLY may be abbreviated RO.
|  
|  As in stand-alone 1022, you can assign an alias to a data set when you
|  open it.  An alias may be up to 25 characters long.  It may not be the
|  same as the internal name  or  alias  of  any  other  open  data  set,
|  including any named in the DBOPEN call.
|  
|  For example:
|  
|       CALL DBOPEN('PARTS','IN','INVNT','AS','OLD')
|  
|  This opens the data set PARTS in the file  INVNT.DMS  with  the  alias
|  OLD.



   2.7.2  The CLOSE Command -- DBCLOS

   This CALL is:

        CALL DBCLOS

   This routine closes the current data set.  A single, open data set  is
   always  the  current one.  When a data set is closed, its contents are
   unavailable for retrieval or modification until it  is  opened  again.
   Also, its data set number is available for reassignment to a different
   data set on a later call to DBOPEN with the NOCLOSE option.

   The lowest numbered data set remaining open becomes the  current  data
   set after a DBCLOS.
   FORTRAN INTERFACE ROUTINES                                   Page 2-20
   Revision 5


   2.7.3  The DBSET Command -- DBSET

   At any instant, one data set is the current one.  The current data set
   is  initially  determined by the actions of DBOPEN, DBCLOS, and DBMAP.
   Change the current data set by a call to DBSET:

        CALL DBSET(DSN)

   where DSN is:

        1) the number of the data set, either a constant  or  an  integer
        variable

   or

        2) the internal name of the data set,  either  a  literal  or  an
        integer variable.

   The data set number is obtained by the routines DBNSET or DBCSET.

   Consider the following program fragment as an example for using DBSET,
   DBCLOS,  and  DBOPEN NOCLOSE.  We assume the data set files introduced
   before.


        CALL DBOPEN('DSB', 'IN', 'TEST', 'INVNT')

        Data set #1, DSB, is now the current data set.


        CALL DBSET('ORDER')

        ORDER, data set #3, is now the current data set.


        I=2
        CALL DBSET(I)

        Data set #2, PARTS, is now the current data set.


        CALL DBCLOS

        Data set #1, DSB, is now the current data set.
        There is no longer a data set #2.


        CALL DBOPEN('NOCLOSE', 'DSA', 'IN', 'TEST')

        DSA is opened on the first free data set number, #2,
        and becomes the current data set.
   FORTRAN INTERFACE ROUTINES                                   Page 2-21
   Revision 5


   2.7.4  Data Set Numbers -- DBCSET And DBNSET

   The routines DBCSET and DBNSET return the number of the  current  data
|  set,  and  the  total  number  of open data sets.  If no data sets are
|  open, DBCSET and DBNSET return a zero.

   The DBCSET routine returns the data set number of the current data set
   into an integer variable.  The CALL is:

        CALL DBCSET(NUM)

   The DBNSET routine returns the total number of open data sets into  an
   integer variable.  The CALL is:

        CALL DBNSET(NUM)



   2.8  DATA SET INQUIRY ROUTINES

   These  routines  parallel  the  commands  of  the  interactive  System
   described in Chapter 4 of the User's Reference Manual.



   2.8.1  The FIND Command -- DBFIND

   The DBFIND routine parallels the  FIND  command  and  selects  records
   using criteria on KEYED attributes.  The CALL is:

        CALL DBFIND(selector-group [, logical, selector-group] ...)

   A selector group identifies a group of records and may be any  of  the
   following:

         1.  A series of 3 arguments of the form:

                   IAI,IREL,IVAL

             Where:

            a)  IAI is an attribute identifier or 'SYSID'.  The
                attribute  identifier may be the attribute name
                or  abbreviation  in  ASCII,  or  the   integer
                attribute number.

   FORTRAN INTERFACE ROUTINES                                   Page 2-22
   Revision 5


            b)  IREL is a relational identifier,  either  ASCII
                or an integer numeric code as follows:

                        ASCII form       Code

                             'EQ'          1
                             'NE'          2
                             'LT'          3
                             'LE'          4
                             'GT'          5
                             'GE'          6
                             'BET'         7
                             'NBET'        8
                             'CT'          9
                             'NCT'        10
                             'BEG'        11
                             'NBEG'       12

                As with attribute identifiers, a  table  lookup
                is eliminated by use of the codes.

            c)  IVAL is the value of  the  attribute.   If  the
                relational  'BET'  or  'NBET' is used, then two
                values follow in the argument list.

                Example:  CALL DBFIND('AGE','BET',25,35)

        2.  The ASCII string 'ALL', to select  all  records  in  the
            data  set.   If this is used, it is the only argument to
            DBFIND.

        3.  The  ASCII  string  'LAST'  to  represent  the   records
            currently selected when the call is made.

        4.  The ASCII string 'FILE' followed in the next argument by
            a  file-descriptor  in  text form naming a pointer file.
            The pointer file locates records  previously  found  and
            remembered with a call to DBSAVE.

         5. The ASCII string 'NOT', followed by anything but  'ALL'.
            This   results  in  all  records  other  than  the  ones
            determined  by  the  following  selector   group.    For
            example:

                  'NOT','LAST'
                  'NOT','FILE','GRP1'
                  'NOT','AGE','EQ',30


   FORTRAN INTERFACE ROUTINES                                   Page 2-23
   Revision 5


   The logical is either an ASCII string or a numeric code as follows:

                  ASCII       Code

                  'AND'         1
                  'OR'          2
                  'EQV'         3
                  'XOR'         4


   The selection criteria are processed from left to right without regard
   to the precedence of logical operators.  For example:

        CALL DBFIND ('LAST','OR','AGE','EQ',30,'AND','SEX','EQ','M')

   is evaluated like the interactive command:

        FIND (LAST OR AGE EQ 30) AND SEX EQ M.

   All logical operators and comparison  relationals  must  appear  in  a
   DBFIND call, unlike in an equivalent FIND command.

   The following are examples of FIND commands, and  their  corresponding
   calls using the FORTRAN interface:

        FIND ALL.

        CALL DBFIND('ALL')

     ------

        FIND NAME JOHN.

        CALL DBFIND('NAME','EQ','JOHN')
               or
        CALL DBFIND(3,1,'JOHN')   assuming NAME is attribute number 3

     ------

        FIND LAST AND AGE 25.

        CALL DBFIND('LAST','AND','DISP.','AGE','EQ','25')
               or
        CALL DBFIND('LAST','AND','BIN.','AGE','EQ',25)

        The above two calls are identical.
   FORTRAN INTERFACE ROUTINES                                   Page 2-24
   Revision 5


   2.8.1.1  Advanced DBFIND Features

   Unlike the interactive 1022 FIND command, DBFIND evaluates expressions
   containing  logical  operators  in  a  strict  left-to-right  order of
   precedence.  Thus, while

        FIND SEX M OR SEX F AND RH NEG

   first selects the records of those females who  are  Rh  negative  and
   then combines these with the records of all males,

        CALL DBFIND ('SEX','EQ','M','OR','SEX','EQ','F','AND',

           'RH','EQ','NEG')

   first selects the records of all males, then combines these  with  the
   records  of  all  females,  and  then forms a final selection group of
   those males and females who are Rh negative.

   Although parenthetical expressions are not allowed with DBFIND, it  is
   still  possible  to  replicate  the  order  of  precedence followed in
   interactive 1022 by using the SAV.  and REF.  features.

      'SAV.',n  Is used after a selection expression to temporarily  save
                pointers to the records found thus far in the evaluation,
                under the reference number n.

      'REF.',n  Is used instead of a selection expression to refer to the
|               records  previously saved under reference number n.  When
|               REF.,n is referenced, the corresponding SAV.,n ceases  to
|               exist.   Thus,  REF.,n  may  only be used to refer to the
|               corresponding SAV.,n once per DBFIND command.

   The call is:

        CALL DBFIND (<expression>,'SAV.',n,

           <expression>,logical operator,'REF.',n)

|  where  n  is  an  integer  less  than  or  equal   to   20,   assigned
   "consecutively"  by  the  user  program  starting  at 1.  That is, the
   lowest integer not already in use as a reference number is assigned as
   n.  After the 'REF.',n clause appears, its n can be reused if the data
   that it represents is no longer needed.

   The groups produced by 'SAV.' are available only in the same  call  to
   DBFIND.   Using  'SAV.'  in  a single DBFIND command is more efficient
   than several DBFIND calls, each using a file from DBSAVE.

   The  following  are  examples  of  complex  FIND  commands  and  their
   corresponding calls using the 'SAV.' and 'REF.' features:

   FORTRAN INTERFACE ROUTINES                                   Page 2-25
   Revision 5


        FIND SEX M OR (SEX F AND RH NEG)

        CALL DBFIND ('SEX','EQ','M','SAV.',1,

           'SEX','EQ','F','AND','RH','EQ','NEG','OR','REF.',1)

   ______

        FIND (TYPE A OR TYPE B) AND RH POS

        CALL DBFIND ('TYPE','EQ','A','OR','TYPE','EQ','B','SAV.',1,

           'RH','EQ','POS','AND','REF.',1)



   2.8.2  The SAVE Command -- DBSAVE

   The DBSAVE routine parallels the interactive SAVE command and writes a
   System  readable disk file of the retrieval pointers for the currently
   selected group of records.  The call is:

        CALL DBSAVE(IFN)

   where IFN  is a file-descriptor,  either  an  ASCII  literal  or  text
   string  stored in an array.  If no extension is specified, the default
   extension DMV is used.  The file-descriptor can later be referenced in
   the FILE clause of a DBFIND call.

   Examples:

        CALL DBSAVE('ABC')

             Pointers to the currently selected records are saved on  the
             file ABC.DMV.

        CALL DBSAVE('ABCDEF.EXT')

             Pointers to the currently selected records are saved on  the
             file ABCDEF.EXT.

   Files saved apply only to the data sets from which they are generated.
   An  error  occurs  if  the  program  attempts to use a SAVEd file on a
   different data set.
   FORTRAN INTERFACE ROUTINES                                   Page 2-26
   Revision 5


   2.8.3  The SEARCH Command -- DBSRCH

   The DBSRCH routine searches the data  set  in  the  same  way  as  the
   interactive SEARCH command.  The CALL has the following format:

        CALL DBSRCH(selector-group [, logical, selector group] ...)

   Where:

   Selector-group is:  ['ATTR.',] IA1,IREL,IVAL1

   The optional keyword 'ATTR.' tells 1022 to evaluate the value in IVAL1
   as an attribute name rather than as a value, for comparison.

   In the following example, MONTH1 and  MONTH2  are  attributes  in  the
   current  data  set.  1022 searches for all records for which the value
   of MONTH1 equals the value of MONTH2.

        CALL DBSRCH('ATTR.','MONTH1','EQ','MONTH2')

   DBSRCH uses any attributes, not  just  keyed  ones.   "SAV.",  "REF.",
   "ALL", and "FILE" are not available.



   2.8.4  The SELECT Command -- DBSEL

   The DBSEL routine parallels the SELECT command and  defers  processing
   of SEARCH selection criteria until a later procedure reads through the
   records.  Using DBSEL avoids doing an immediate search as  in  DBSRCH,
   and  is  followed  by  a  second record retrieval procedure.  DBSEL is
   called using the same argument  string  as  in  DBSRCH.   The  'ATTR.'
   keyword  has  the same function as in DBSRCH.  (See The SEARCH Command
   -- DBSRCH, above.)

   Any routine which selects a record respects the criteria specified  in
   DBSEL.   This  includes  DBSORT, DBCHNG, DBDEL, DBGREC, DBGET, DBSRCH,
   and DBMAP.



   2.8.5  The MAP Command -- DBMAP

   The DBMAP routine parallels the MAP command and locates records  in  a
   second  data set using common attribute values shared with the records
   in the current selection group.  Execution of DBMAP leaves the  second
   data set as the current data set.  The selection group is unchanged in
   the data set from which the DBMAP is done.  The CALL is:

        CALL DBMAP(['BY',METHOD,] ['LOGICAL',LOG,]

             DSET,SATTR1 [,DATTR1] [ ,'AND',SATTR2 [,DATTR2] ]...)

   Where:
   FORTRAN INTERFACE ROUTINES                                   Page 2-27
   Revision 5


        METHOD  Is either 'KEY'  or  'GETREC'.   It  specifies  that  MAP
                locate  records using the key table (KEY) or by examining
                one record at a time (GETREC).  Without this clause, 1022
                usually  chooses  the best method.  Specifying the method
                sometimes improves performance.

        LOG     Specifies how the records selected as a  result  of  this
                MAP  command  are  combined  with  the records previously
                selected in the destination  data  set.   'AND'  forms  a
                selection  group  of  records  that share values with the
                first data set and were previously selected in the second
                               ___
                data  set.   'OR'  selects records that share values with
                the first data set or were  previously  selected  in  the
                                   __
                second data set.  'CLEAR', also the default if no LOGICAL
                clause is specified, ignores the previous selection group
                in the second data set.

        DSET    Is either the data set name or number of the  destination
                data set.  Using the data set name selects the named data
                set of lowest number if more than one open data  set  has
                that  name.  The data set number may be either an integer
                constant or variable.

        SATTR1  Is an attribute in the source data set to be used in  the
                mapping,  represented  by the integer attribute number or
                by its text name.  The keyword 'SYSID' may also be used.

        DATTR1  Is the attribute  in  the  destination  data  set  to  be
                compared  to  SATTR1.   It need not be named if it is the
                same name as SATTR1.  If attribute  numbers  rather  than
                names  are  used, DATTR must be specified.  The attribute
                in the destination data set must be  a  KEYed  attribute.
                It may be 'SYSID'.

        'AND'   More than one attribute in the source  data  set  can  be
                used  to  select  records  in  the  destination data set.
                'AND' introduces additional attributes to be used in  the
                mapping.   Any records that are selected match on all the
                specified source attributes.

        SATTR2  Is the second source attribute to be used in comparisons.

        DATTR2  Is the attribute in the destination  to  be  compared  to
                SATTR2  in  the source data set.  It may be omitted if it
                is the same name as SATTR2.  If attribute numbers  rather
                than names are used, DATTR must be specified.

   Examples:

   FORTRAN INTERFACE ROUTINES                                   Page 2-28
   Revision 5


        CALL DBMAP (2,'NAME')

             Map to data set 2 using the values of NAME in both data sets
             for comparisons.

        CALL DBMAP ('ORDER', 'NAME', 'NEWNAME')

             Map to the ORDER data set comparing NAME in the source  data
             set to NEWNAME in the destination data set.

        CALL DBMAP ('LOGICAL', 'OR', 2, 'AGE', 'NEWAGE')

             Map to data set 2 comparing the values of AGE in the  source
             data set to NEWAGE in the destination data set.  The records
             selected are added (ORed) to the previous selection group in
             the destination data set.

        CALL DBMAP (2, 'NAME', 'NEWNAME', 'AND', 'AGE', 'NEWAGE')

             Select records in data set 2 which have the same values  for
             both  NEWNAME  and NEWAGE as in the source data set for NAME
             and AGE.  This does a different selection than selecting  by
             just NAME and then ANDing or ORing records selected by AGE.



   2.8.5.1  Example Of DBMAP


   Assume we have two data sets, P.DMS and C.DMS, which  are  parent  and
   child  data  sets.  We want to find all parents between the ages of 35
   and 40 and print out their children.  The  files  are  linked  by  the
   parent's  social security number, called SSN in the P file and PSSN in
   the C file.

            CALL DBFOR
            CALL DBOPEN('P','C')
            CALL DBFIND('AGE','BET',35,40)
   10       CALL DBSET(1)
            CALL DBGREC($50)
            CALL DBMAP(2,'SSN','PSSN')
   15       CALL DBGREC($10)
            .
            .  WRITE OUT INFORMATION FROM THE CHILD RECORDS
            .
            GO TO 15
   50       CONTINUE
   FORTRAN INTERFACE ROUTINES                                   Page 2-29
   Revision 5


   2.8.6  The Current Number Of Records -- DBNREC

   The DBNREC routine returns the number of records  currently  selected.
   The call usually follows a DBFIND, DBSRCH, or DBMAP.  The CALL is:

        CALL DBNREC(I)

   where the integer variable I is  returned  containing  the  number  of
   records  in  the  current  selection  group.   The  value excludes any
   records removed from the selection group  by  the  DBDROP  routine  or
   DBSEL conditions.



   2.8.6.0.1  The GETREC Command -- DBGREC

   The DBGREC routine parallels the interactive GETREC command and enters
   local mode for single record processing.  The CALL is:

|       CALL DBGREC ($label [,'$LOCK'] [,IRECNO])

   The DBGREC routine is called after a group of records is  selected  by
   the DBFIND, DBSRCH, DBSEL, or DBMAP routine.  It makes the next record
   in the selection group available for individual processing.

   A call to DBGREC places the program into local mode.  While  in  local
   mode,  DBDEL  or  DBCHNG  affects  only the record last retrieved with
   DBGREC.  The  first  call  selects  the  first  record.   Later  calls
   sequentially select the remaining records.

   Control transfers to $label when the program sequentially exhausts the
   currently  selected  records.   When a DBGREC call branches to $label,
   the program is placed into global mode, as if a DBSREC call  had  been
   made.   The  program  can  start  sequential processing again from the
   first record with further calls to DBGREC.

   DBGREC  does  not  transfer  attribute  values.   The  DBVAL  routine,
   described   later,  retrieves  attribute  values  from  the  currently
   selected record.

   Example:

           CALL DBGREC($25)

           The next record  is  selected  for  processing.   Control
           transfers  to  statement 25 when the program exhausts all
           records in the selection group.

|  ,rm 70 The optional $LOCK argument to DBGREC locks the record  so
|  that  no  other  user can update it.  The record is unlocked when
|  you get the next record, return to global mode,  close  the  data
|  set,  drop the record, delete the record, or give a CALL DBLOCK (
|  'OFF' , 'RECORD') call.  The $LOCK argument works only  for  data
|  sets that are ENQ and RECLOCK.
   FORTRAN INTERFACE ROUTINES                         er
   SSN (Social Security Number) is placed  into  the  first  3  words  of
   IARRAY.   The  display value of an integer always requires three words
   of storage.  (See  RULES  FOR  USING  THE  FORTRAN  INTERFACE  at  the
   beginning  of this chapter for a discussion of display-numeric storage
   requirements.)



   2.8.9  Retrieving An Entire Record -- DBGET

   The DBGET routine retrieves the values of all attributes for a  single
   record,  and  places them in an array dimensioned large enough to hold
   them.  Its effect is that of a DBGREC call followed by  a  DBVAL  call
   for  all  of  the  attributes.   Thus, it enters local mode for single
   record processing.  The CALL is:

|       CALL DBGET(IAR, $label [,'$LOCK'] [,IRECNO])
|  
|  where:
|  
|           1) IAR is an array to receive the entire record. 
|  
|           2) $label is where to go when there are no more records. 
|  
|           3) $LOCK locks the record. 

            4) IRECNO is an optional record number for random retrieval.

   The record is returned into IAR in 'Standard Record Format'.  In  this
   format,  each attribute value begins on a new word boundary, and has a
   length  large  enough  to  represent  the  entire   attribute.    Text
   attributes are returned space filled (ASCII) or null filled (SIXBIT).

|  The optional $LOCK argument to DBGET locks the record so that no other
|  user  can  update  it.   The  record is unlocked when you get the next
|  record, return to global mode, close the data set,  drop  the  record,
|  delete  the  record, or give a CALL DBLOCK ('OFF','RECORD') call.  The
|  $LOCK argument works only for data sets that are ENQ and RECLOCK.

   If IRECNO is included, the nth record is  selected,  where  n  is  the
   value of IRECNO.  This is similar to a DBGREC with IRECNO.

   The system variables SYSHLMODE and SYSHLDISP affect this record format
   because   display  numerics  are  longer  than  binary  numerics,  and
   DISPLAY-7 values are packed  into  words  differently  than  DISPLAY-6
   values.   In  DISPLAY-7  mode, 5 characters fill a word.  In DISPLAY-6
   mode 6 characters fill a word.
   FORTRAN INTERFACE ROUTINES                                   Page 2-32
   Revision 5


   EXAMPLE:

   Assume the data set has three attributes:

            (#1) ATTRIBUTE R REAL
            (#2) ATTRIBUTE T TEXT LENGTH 6
            (#3) ATTRIBUTE D DATE

   Assume that  SYSHLDISP  is  its  default  value  of  0  (ASCII).   The
   following  explanation applies to different settings of SYSHLMODE:  -1
   (binary), 0 (as in the data set), and +1 (display).

        1.  The  following  applies  when  a  record  is  retrieved   and
            SYSHLMODE = -1 (binary mode):

             IAR(1)          Contains R in binary floating point.
             IAR(2) - IAR(3) Contain T  with  the  last  four  characters
                             filled with blanks.
             IAR(4)          Contains D as an  integer  in  encoded  date
                             format.

            A real variable  must  be  EQUIVALENCEd  to  IAR(1)  for  the
            FORTRAN  program to correctly use the real attribute R.  This
            is done by equivalencing a real  array  RAR  to  the  integer
            array  IAR.   Then, use RAR whenever a real attribute must be
            referenced in FORTRAN.

            The 20th  position  of  the  INF  array  returned  by  DBINFO
            contains  the  index for the attribute in the Standard Record
            Format array.  In the above example:

                 CALL DBINFO('R',INF1) 
                 CALL DBINFO('T',INF2) 
                 CALL DBINFO('D',INF3) 

            sets: 

                 INF1(20)=1 
                 INF2(20)=2 
                 INF3(20)=4 

        2.  The following applies when SYSHLMODE = +1 (display mode):

            IAR(1) - IAR(3) Contain R, right justified and blank  filled,
                            in ASCII.
            IAR(4) - IAR(5) Contain T, left justified and  blank  filled,
                            in ASCII.
            IAR(6) - IAR(7) Contain D, right justified and blank  filled,
                            in ASCII.

   FORTRAN INTERFACE ROUTINES                                   Page 2-33
   Revision 5


            The 20th position of the INF array returned by a DBINFO  call
            contains  the index for an attribute into the Standard Record
            Format array.  In the above example:

                 CALL DBINFO('R',INF1)
                 CALL DBINFO('T',INF2)
                 CALL DBINFO('D',INF3)

            sets:

                 INF1(20)=1
                 INF2(20)=4
                 INF3(20)=6

   The attribute field in the Standard Record Format array is filled with
   blanks or zero if an attribute is protected from being read.

   The value of the index returned in location 20  of  the  DBINFO  array
   applies  under  the  settings of SYSHLMODE and SYSHLDISP that exist at
   the time that DBINFO is called.  Thus, changing modes  from  DISPLAY-7
   to DISPLAY-6, or from numeric to display, changes the indices returned
   by DBINFO.  Call DBINFO under the same conditions as  apply  when  you
   receive the record with DBGET, or supply the record with DBADDR.
|  
|  
|  
|  2.8.9.0.1  The LOCK Command -- DBLOCK
|  
|  The DBLOCK routine locks and unlocks update access to  single  records
|  and  turns  on and off user-defined locks on a data set.  It parallels
|  the interactive LOCK command.  The CALL is:
|  
|                  { 'ON'  } , { 'RECORD'           }
|                { { non-0 }   { 'USERLOCK', string }     }
|  CALL DBLOCK ( {                                        } )
|                { { 'OFF' } , { 'RECORD'               } }
|                  {   0   }   { 'USERLOCK', { string } }     
|                                            { 'ALL'  } 
|  
|  where:
|  
|       'ON' or non-0  Is the quoted keyword 'ON' or  any  integer  other
|                      than 0 to turn the lock on.
|  
|       'OFF' or 0     Is the quoted keyword 'OFF' or 0 to turn the  lock
|                      off.
|  
|       'RECORD'       Indicates record-level locking.
|  
|       'USERLOCK'     Indicates a user-defined lock on the data set.
|  
|       string         Is a text string of up to 25 characters naming the
|                      userlock.  It terminates with a space.
   FORTRAN INTERFACE ROUTINES                                   Page 2-34
   Revision 5


|       'ALL'          Is the keyword to turn off all userlocks currently
|                      turned on by this program in this data set.
|  
|  Examples:
|  
|       CALL DBLOCK ('ON','RECORD') 
|       CALL DBLOCK (1,'RECORD') 
|       CALL DBLOCK ('ON','USERLOCK','FRANCE_RECS')
|       CALL DBLOCK ('OFF','USERLOCK','ALL') 
|  
|  The DBLOCK ON RECORD routine, in single record mode, ensures  that  no
|  other  user can update your current record.  Unlike the UPDATE command
|  and DBUPD, other users may have full access, including update  access,
|  to the other records in the data set.  They may also read your current
|  record when you have it locked, but you are  the  only  user  who  can
|  update  that  current  record  while the lock is on.  DBLOCK RECORD is
|  similar to DBGREC or DBGET with $LOCK but  is  less  efficient.   (See
|  "Locking Records with LOCK ON RECORD").
|  
|  The record remains locked until you  get  another  record,  return  to
|  global  mode,  close  the data set, form a new selection set, drop the
|  record from the selection set, delete the record, or give  the  DBLOCK
|  OFF (or 0) RECORD routine.
|  
|  The data set must be ENQ and RECLOCK to use DBLOCK RECORD.
|  
|  The DBLOCK routine with USERLOCK turns on and off user-defined  locks.
|  The  userlock  created  by  DBLOCK ON (or a non-0 integer) USERLOCK is
|  identified by the specified string.  It  does  not  actually  restrict
|  access  to  the  data  set.   But  if your process and other processes
|  cooperate to use userlocks of the same names, you can specify  exactly
|  the  access  each  assumes.  When your process requests a userlock, it
|  will succeed if no other process has already locked the data set  with
|  that  string.   If  another  process has locked the data set with that
|  string, 1022 returns an error message.
|  
|  The data set must be ENQ to use DBLOCK USERLOCK.  The lock remains  in
|  effect  until  you  close  the  data  set  or  explicitly turn off the
|  individual lock or all userlocks.



   2.8.10  The STARTREC Command -- DBSREC

   The DBSREC routine ends sequential processing.  The CALL is:

        CALL DBSREC

   The routine parallels the STARTREC command and returns the program  to
   Global  mode.   A later CALL to DBGREC selects the first record in the
   group.  DBSREC preserves any sorted order in the selection group.   In
   contrast, DBFIND('LAST') does not preserve sorted order.
   FORTRAN INTERFACE ROUTINES                                  Page 2-34A
   Revision 5


   2.8.11  The SORT Command -- DBSORT

   The DBSORT command sorts the current selection group of records in the
   same way as the interactive SORT command.  The CALL is:

        CALL DBSORT( ['CORE',n,] ['USING',device,]

                     ATTR1 [,sequence]   [, ATTR2 [,sequence] ]...)

   or

        CALL DBSORT ('KEY',ATTR)


   Where:

        1.  'CORE', n, - Is an optional clause which  specifies  how
            large  a sort buffer to use.  The number n is the number
            of 1024 word blocks (called  "K")  to  be  allocated  in
            storage  for sorting.  The default is 5K and is adequate
            for all but very large sorts.  "n" must be greater  than
            or equal to 3.

        2.  'USING', device - Is an optional clause which  specifies
            a scratch disk device for the sort.

        3.  ATTRn, sequence - Is  a   clause   included   for   each
            attribute  the program sorts by.  The records are sorted
            using the order precedence of  the  sort  clauses.   The
            first  attribute  is  the  major  sort  key.  The second
            attribute affects the record order among equal values of
            the  first  attribute.   Later  attributes determine the
            order among equal values of all previous attributes.

   The SEQUENCE identifier is optional in each attribute clause, and
   can  be either ASCENDING or DESCENDING.  This specifies the order
   in which that attribute should be sorted.  If omitted,  ASCENDING
   is  assumed.   The  sequence  keywords  may be shortened to their
   first 5 characters.
   FORTRAN INTERFACE ROUTINES                                  Page 2-34B
   Revision 5


   DBSORT with the KEY option establishes a  sorted  order  using  a
   single  keyed  attribute.  This call is analogous to the SORT KEY
   command.  The records are always sorted in ascending order and no
   other  options are allowed.  Only one sort field is allowed.  The
   key option is not always faster than a  regular  sort.   See  the
   User's Reference Manual for a detailed discussion.
   ______ _________ ______


   Examples:

        CALL DBSORT('CORE',10,'USING','DSKX','FN','ASCEN','LN','DESCE')
        CALL DBSORT('FN','LN','DESCENDING')
        CALL DBSORT('STATE','COUNTY','CITY')



   2.8.12  The VALUES Command -- DBVALU

   The DBVALU command parallels the interactive VALUES  command.   For  a
   specified  keyed  attribute,  it  returns each different value and the
   number of times each occurs in the current  selection  group.   Values
   and  occurrence  counts  are  returned  to a user array in pairs, each
   value followed by the corresponding count.  Count is always  a  binary
   integer.  CALL is:

        CALL DBVALU(ATTR, ARRAY-START, ARRAY-END, NV [, IVLEN])

   Where:

        ATTR        Is the keyed attribute name or number.

        ARRAY-START Is  the  first  location  in  the  array   to   which
                    value/occurrence data is returned.

        ARRAY-END   Is  the  last  location  in  the   array   to   which
                    value/occurrence data is returned.

                    ARRAY-START and ARRAY-END need not be the  first  and
                    last  locations in the array, but they must delimit a
                    contiguous block of memory.  At least n+1  words  are
                    required,   where  n  is  the  length  of  the  value
                    returned;  the extra word  is  for  the  count.   For
                    efficiency   dimension  the  array  as  large  as  is
                    practical.

        NV          Is the integer number of value/occurrence pairs  that
                    DBVALU has loaded into the array.  For the first call
                    the user sets this to -1.   Subsequent  calls  return
                    non-zero  integers  in  NV until all values have been
                    read and counted.  Then DBVALU sets NV to 0.

                    When NV is not -1,  DBVALU  uses  it  to  resume  key
                    searching.   Tampering  with  NV between DBVALU calls
                    will cause incorrect results or errors.
   FORTRAN INTERFACE ROUTINES                                   Page 2-35
   Revision 5


                    If the program sets NV to a value  greater  than  the
                    maximum  number  of  value/count  pairs  that  can be
                    contained within the bounds  defined  by  ARRAY-START
                    and ARRAY-END, 1022 returns an error message (HL40).

        IVLEN       Is the value's length in words.  This is returned  by
                    1022,  when  specified,  for use in retrieving values
                    from the array.

   After the first call, DBVALU uses the NVth value in the user array  to
   locate  the  next  set of values.  Because of this, the program should
   not modify NV or any elements of the array.

   The following example uses DBVALU to return attribute values/counts to
   a  user array.  For AGE, DBVALU is called in a loop until the keys are
   exhausted (NV .EQ.  0).  After the DBVALU call, all values and  counts
   are  displayed.   NV and IVLEN (VALLEN) are used to compute indices to
   data within the array.  Default conversions are  in  effect.   Display
   values are returned padded to the word boundary.

   Example:

                  INTEGER VALARR(10),VALLEN,NV

        C  VALARR holds VALUE/OCCURRENCE pairs
        C  VALLEN holds the VALUE length as returned by DBVALU
        C  NV holds the number of values returned by DBVALU

        C  Initialize and select records

                  CALL DBFOR
                  CALL DBOPEN( 'NAMES')
                  CALL DBFIND( 'ALL' )

        C  Set up for first DBVALU call

                  NV = -1

        100       CALL DBVALU( 'AGE', VALARR(1), VALARR(10), NV, VALLEN )

        C  Check for out of values

                  IF ( NV .EQ. 0 ) STOP

        C  Print value/occurrence pairs

        C  VALLEN+1 = # Words in value + 1 word for occurrence count

                  DO 150  I = 1, NV*(VALLEN+1), VALLEN+1
        150         TYPE 1,VALARR(I),VALARR(I+VALLEN)

        1            FORMAT(' Value= ', I3, ', Occurrences= ', I3)

        C  Repeat DBVALU to get next set of values
   FORTRAN INTERFACE ROUTINES                                   Page 2-36
   Revision 5


                  GOTO 100

                  END

   You may also specify runtime type conversions using the BIN. and DISP.
   keywords (see "Runtime Type Conversions").

   Examples:

        CALL DBVALU ('BIN.','AGE',IARR,IARR(10),NV,IVLEN)
        CALL DBVALU ('DISP.','AGE',IARR,IARR(10),NV,IVLEN)

   The system variables SYSHLMODE and SYSHLDISP may be  used  for  global
   runtime type conversions.



   2.9  DATA SET UPDATE ROUTINES

   These routines correspond to the commands and  features  described  in
   Chapter 5 of the User's Reference Manual.
                    ______ _________ ______



   2.9.1  The CHANGE Command -- DBCHNG

   The DBCHNG routine parallels the CHANGE command and changes the values
   of attributes in the currently selected records.  The CALL is:

        CALL DBCHNG(['UPDE.',$label,] change-group [,change-group]...)

   Where:

        'UPDE.',$label   Is an optional clause which specifies  where  to
                         transfer  control if the record has been changed
                         due to simultaneous update since the  last  call
                         to DBGREC or DBGET.

        Change-group     Is ['ATTR.',] IA1,IVAL1

        'ATTR.'          Is an  optional  keyword  which  specifies  that
                         IVAL1  is  an attribute.  The value of the first
                         attribute is changed to the value of the second.

        IA1              Is an attribute  identifier,  either  the  ASCII
                         attribute name or abbreviation, or the attribute
                         number.

        IVAL1            Is the new value for the attribute.  It  is  the
                         name of an attribute when 'ATTR.' appears.

   In the 'ATTR.' form of the command, the value of IA1 is changed to the
   value  of  IVAL1.   The program may change many attributes in a single
   CALL to DBCHNG by providing a pair of arguments  for  each  attribute.
   FORTRAN INTERFACE ROUTINES                                   Page 2-37
   Revision 5


   It is more efficient to place many pairs in one CALL than to make many
   calls.

   The changes apply to all records currently selected, unless  a  single
   record  is  selected in Local mode.  Only the single record is changed
   in Local mode.

   Examples:

        1022:       CHANGE AGE 25.
        FORTRAN:    CALL DBCHNG('AGE',25)
                    CALL DBCHNG('DISP.','AGE','25')

        1022:       CHANGE AGE 30 CITY BOSTON.
        FORTRAN:    CALL DBCHNG('AGE',30,'CITY','BOSTON')

   Control can be transferred using the "UPDE." clause in local  mode  if
   another  updater  has  changed any attribute in the record between the
   time of the DBGREC and the DBCHNG.  In global mode,  control  will  be
   transferred  only if another updater changes an attribute in the first
   record between the time the selection group was made and the  DBCHNG's
   action  on the first record.  Other records can be changed without any
   transfer of control;  thus, it is better to do a DBCHNG in local mode.
   See  Chapter  5  of the User's Reference Manual, System Protection for
                           ______ _________ ______
   Interactive Simultaneous Updates, for more information on  how  System
   1022 handles this interaction.

   On transfer, the altered record has been read, so there is no need  to
   DBGREC again.  For example, a user wants to decrement the count of all
   the tools by 1 and print a warning if any of the counts equals zero.
   The FORTRAN program is:

                                  .
                                  .
                                  .
                     CALL DBFIND ('TYPE','EQ','TOOL')
             100     CALL DBGREC ($400)
             110     CALL DBVAL ('COUNT',ICOUNT)
                     IF (ICOUNT .EQ. 0) GO TO 300
                     ICOUNT = ICOUNT-1
             150     CALL DBCHNG ('UPDE.',$110,'COUNT',ICOUNT)
                     GO TO 100
             300     TYPE 310
             310     FORMAT (' WARNING--OUT OF STOCK')
                     GO TO 100
             400
                                  .
                                  .
                                  .

             Line 150 institutes  the  CHANGE,  and  checks  whether  the
             record  was  altered  since the DBGREC.  If it was, it sends
             the record through the zero  checking  procedure  again,  to
             make  sure that COUNT was not decremented to zero by someone
   FORTRAN INTERFACE ROUTINES                                   Page 2-38
   Revision 5


             else.



   2.9.2  The DELETE Command -- DBDEL

   The DBDEL  routine  parallels  the  DELETE  command  and  deletes  all
   currently selected records from the data set.  The CALL is:

        CALL DBDEL [('UPDE.',$label)]

   'UPDE.',$label is an optional clause which specifies where to transfer
   control  if  the  record  has  been changed due to simultaneous update
   since the call to  DBGREC.   See  the  previous  section,  The  CHANGE
   Command  --  DBCHNG,  and  Chapter  5  of the User's Reference Manual,
                                                 ______ _________ ______
   System Protection for Interactive Simultaneous Updates.

   Like DBCHNG, the action affects only a single record if in local mode.
   All selected records are deleted in global mode.



   2.9.3  The ADD Commands -- DBADD And DBADDR

   Two routines add records to a data set.  The  first  is  DBADD,  which
   parallels the ADD command.  Its CALL is:

        CALL DBADD(IA1,IVAL1 [,IA2,IVAL2]...)

   Where:

        IA1     Is an attribute identifier, either  the  ASCII  attribute
                name or abbreviation, or the attribute number.

        IVAL1   Is the value of the attribute to be added.

   Example:

         CALL DBADD('NAME','JOHN','AGE',25,'CITY','CLEVELAND')
         CALL DBADD('NAME','JOHN','DISP.','AGE','25','CITY','CLEVELAND')

   Any attributes not specified in the  CALL  to  DBADD  are  given  null
   values, zero or blank.

   After an ADD, the selection group contains only the ADDed record.

   The DBADDR routine also adds  records  to  a  data  set.   Instead  of
   specifying  each  attribute  name  in the CALL, the program places the
   attribute values into an array in Standard Record Format (see  DBGET).
   This array is the single argument to the DBADDR CALL:

        CALL DBADDR(IARRAY)

   Attribute values passed to DBADDR in  the  array  may  be  numeric  or
   FORTRAN INTERFACE ROUTINES                                   Page 2-39
   Revision 5


   display, SIXBIT or ASCII, as set by the system variables SYSHLMODE and
   SYSHLDISP.

   DBADD provides independence from the data set;  a change in  data  set
   structure  from adding new attribute names does not affect it.  DBADDR
   is  convenient,  but  ties  the  program  to  a  particular  data  set
   structure,  unless  the  program  is  careful  to  use only the DBINFO
   Standard Record Format indices to place/retrieve values in the array.



   2.9.4  The UPDATE Command -- DBUPD

   The DBUPD routine parallels the UPDATE  command  for  use  when  large
   scale updates are done to a data set.  The CALL is:

        CALL DBUPD(I)

   Where:

        I   Is 0 to set update mode OFF.
            Is nonzero to set update mode ON.

   The DBUPD routine should be called if much updating is to be done to a
   data  set.  It prevents the data set file from being reopened for each
   update command.  It also prevents other users from updating  the  data
   set while update is on.

   The program must turn update mode off to allow others  to  update  the
   data  set.   This is done by another CALL to DBUPD or automatically by
   the DBEND routine.

   The DBUPD routine sets UPDATE ON and UPDATE OFF only for  the  current
   data  set.   If several data sets are open simultaneously, the program
   calls DBSET and DBUPD for each data set.  Refer to the DBSET call  for
   information about data set selection.



   2.9.5  The SET BUFFER Command -- DBBUF

   The DBBUF routine parallels the  interactive  SET BUFFER  command  and
   assigns   I/O   buffers   for  more  efficient  update  and  retrieval
   operations.  The CALL is:

        CALL DBBUF(I)

   where I contains the number of I/O buffers to use for the current data
   set.  The DBBUF routine is used along with the DBUPD routine when many
   additions or changes are to be made to the data set.
   FORTRAN INTERFACE ROUTINES                                   Page 2-40
   Revision 5


   2.9.6  The ALLOCATE Command -- DBALLO

   The DBALLO routine simulates the ALLOCATE command and  reserves  space
   for new records to be added to the data set.  The CALL is:

        CALL DBALLO(NUM)

   where NUM specifies the number of records which will be added  to  the
   data set.  This improves System efficiency, because the space is added
   in one continuous cluster of blocks.  NUM can have a value  between  1
   and 5000.  NUM is the number of records, not the number of blocks that
   are allocated.  1022 calculates the number of blocks necessary.



   2.10  SPECIAL PURPOSE ROUTINES

   These routines perform special functions.  Except for DBEXEC, they are
   parallel to commands in the interactive System.



   2.10.1  The INFORM ATTRIBUTE Command -- DBINFO

   The DBINFO routine obtains information about attributes  in  the  data
   set.   It  parallels the INFORM ATTRIBUTE command and provides all the
   information available about a single attribute.  The CALL is:

        CALL DBINFO(IAI,INF)

        Examples:  CALL DBINFO('AGE', INF)

                   CALL DBINFO(3, INF)

   Where:

        1.  IAI is an attribute identifier, which  is  either  the  ASCII
            name or abbreviation, or the integer attribute number.

            Many  System  routines  require  attribute   identifiers   as
            arguments.   The  program  saves  a  table  lookup  for  each
            occurrence of one  attribute  name  by  using  the  attribute
            number  rather  than  the  name or abbreviation.  To do this,
            start the program with calls to DBINFO  to  obtain  attribute
            numbers  corresponding to attribute names.  These numbers are
            then used as attribute identifiers in other routines.

            The program always uses DBINFO to  obtain  attribute  numbers
            where  data  set  independence  is  needed.  The numbers will
            change if the data set attributes are later  reordered.   The
            program  may  assume the proper attribute numbers in programs
            where the data set structure will not change.   Or,  use  the
            text  names  in all references;  the efficiency difference is
            not large.
   FORTRAN INTERFACE ROUTINES                                   Page 2-41
   Revision 5


        2.  INF is an integer array  of  25  words  where  the  following
            information  about  the attribute is returned.  INF(1) is set
            to 0 when no attribute corresponds to IAI.


       Subscript   Information Required

       1-5    Attribute name in ASCII.
       6      Attribute abbreviation in ASCII, or  binary  0  if  no
              abbreviation.
       7      Attribute number.

       8      Type of attribute as follows:
                 0 INTEGER   5 DISPLAY-7 INTEGER   10 DISPLAY-6 REAL
                 1 REAL      6 DISPLAY-7 REAL      11 DISPLAY-6 DATE
                 2 TEXT      7 DISPLAY-7 DATE      12 DBL
                 3 unused    8 DISPLAY-6 TEXT      13 DISPLAY-6 DBL
                 4 DATE      9 DISPLAY-6 INTEGER   14 DISPLAY-7 DBL

       9      Number of characters if type TEXT, 0 otherwise.

       10     Access type, as follows:
                 -1 Keyed-active
                  0 Unkeyed
                  1 Keyed-inactive

       11     [Reserved for future use]

       12     -1 if the attribute requires a password, 0 otherwise.

       13     [Reserved for future use]

       14     Lower bound for the RANGE or 0 if text.
       15     Upper bound for the RANGE or 0 if text.

       16     Starting column for the attribute on the input record
       17     Ending column for the attribute on the input record

       18     Special attribute type, as follows:
                 0 Not special
                 1 Date Of Entry
                 2 Date Of Change
                 3 Integer of Identification

       19     Attribute protection value, as follows:
                 0 Update
                 5 Readonly
                 7 Locked

       20     Index into the Standard Record Format  array  used  by
              DBGET and DBADDR.

       21-25  [Reserved for future expansion]
   FORTRAN INTERFACE ROUTINES                                   Page 2-42
   Revision 5


   2.10.2  The PERMIT Command -- DBPSWD

   The DBPSWD routine parallels the PERMIT command.  It is used  to  gain
   access  to  password-protected attributes of the data set and may also
   be used to assign readonly access to data set attributes that are  not
   protected.  The call is:

        CALL DBPSWD(IAI,IPSWD,IRO [,IAI2,IPSWD2,IRO2]...)

   Where:

        IAI       Is an attribute identifier.

        IPSWD     Is  the  password.   When  DBPSWD  is  used  to  assign
                  readonly   access   to   an   attribute   that  is  not
                  password-protected, this argument is 0.

        IRO       Is the access type.  For readonly access, the  argument
                  is 'RO'.  Otherwise, the argument is 0.


        Example:  CALL DBPSWD('NAME','ABC',0,'AGE',0,'RO')

                  Provide the password ABC for the  attribute  NAME,  and
                  assign readonly access to the attribute AGE.



   2.10.3  The Number Of Attributes -- DBNATT

   The DBNATT routine returns the number of  attributes  in  the  current
   data set.  The CALL is:

        CALL DBNATT(I)

   The integer variable I  receives  the  number  of  attributes.   I  is
   returned as a meaningless value if no data set is open.

   Use the DBNATT routine along with DBINFO.  DBINFO can be called  in  a
   DO  loop  using  the  value  returned by DBNATT as the upper limit, to
   obtain complete information about the data set structure.



   2.10.4  Resetting Internal Buffers -- DBCLR

   During the  execution  of  some  routines,  internal  buffers  may  be
   expanded to accommodate long argument strings.  There is not usually a
   space problem, but DBCLR is provided to reset the  1022  buffer  space
   back to its initial values.  The CALL is:

        CALL DBCLR

   The commands that expand the buffer  space,  like  DBADD,  have  large
   FORTRAN INTERFACE ROUTINES                                   Page 2-43
   Revision 5


   argument  strings.  There is overhead in contracting and expanding the
   buffers;  the program should reset them only if it will not  do  these
   types  of  commands  for  a  significant  time  interval.  There is no
   advantage in resetting after every DBADD.

   Do not confuse the function performed by the DBCLR  routine  with  the
   CLEAR command.



   2.10.5  Error Handling Routines

   The routines DBERR and DBERRH instruct  1022  to  take  one  of  three
   actions when an error occurs.  These actions are:

       1) Trap to the FORTRAN program on errors.
       2) Abort the program on errors.
       3) Ignore errors.

   The DBERRT routine can print the message text for the last error  onto
   a terminal.  It can also store that text in a variable.



   2.10.5.1  The DBERR Subroutine


   The CALL is:

        CALL DBERR($label [,IERT,IERC,IFLAG])

   Where:

        $label  Is the statement to which control transfers when  an
                error  occurs.   Provide a value, instead of $label,
                if trapping is not desired.  A value of 0 causes  an
                error  message to type and aborts the program run in
                the event of an error.  A value of -1 continues  the
                program after typing any required error messages.

        IERT    Is a variable which  receives  the  error  type-code
                number on trapping.

        IERC    Is a variable which receives the error code  number.
                Refer  to  the  appendix  in  this manual and to the
                User's Reference Manual for a list  of  error  types
                ______ _________ ______
                and codes.

        IFLAG   1: Print error messages on the terminal (default).
                0: Suppress error messages.

   All the arguments after the first are optional.  DBERR is called  once
   to provide the trapping information, or again to change it.  It is not
   called to test the presence of an error.
   FORTRAN INTERFACE ROUTINES                                   Page 2-44
   Revision 5


   Normally, 1022 types an error message and terminates the job  when  an
   error  occurs  during execution.  The program may call DBERR to do its
   own error handling.  A call to DBERR enables or disables program error
   trapping.

   The variables IERT and IERC receive the error code numbers as  defined
   in  the appendix.  Thus, if IERT is set to 4 and IERC is set to 2, the
   error that occurs is "OP2  DATA SET NOT FOUND."

   Examples:

        CALL DBERR($25,IERT,IERC,0)

        On an error, control  transfers  to  statement  25.   No  typeout
        occurs.  The variables IERT and IERC receive the error codes.

        CALL DBERR(0)

        Set 1022 to its default state of no error trapping and  automatic
        error message typeout.

        CALL DBERR(-1)

        This call disables  program  termination  on  errors.   An  error
        message  still  prints  on the terminal to report errors, but the
        program continues running.

        CALL DBERR(-1,IERT,IERC,0)

        This call disables both program  termination  and  error  message
        typeout.   This  is not recommended, because any number of errors
        could occur and go unnoticed.  IERT and IERC are set.

        CALL DBERR(-1,IERT,IERC,1)

        This call disables  program  termination  on  errors.   An  error
        message  prints  on  the  terminal to report errors, and IERT and
        IERC receive the error codes.



   2.10.5.2  The DBERRH Subroutine


   The CALL is:
|  
|                     { subrtn, }
|       CALL DBERRH ( {  value  } IERT,IERC,IFLAG)
|                     { $label, }
|  
|  Where:
|  
|       subrtn  Is the  name  of  the  subroutine  to  which  control  is
|               transferred  when  an  error occurs.  The subroutine ends
   FORTRAN INTERFACE ROUTINES                                   Page 2-45
   Revision 5


|               with the statement RETURN.  At  this  point,  control  is
|               transferred   to   the  user's  program  at  the  command
|               following the 1022 call that caused the error.
|  
|       value   Signals 1022 that no error trapping is desired.   In  the
|               event  of  an  error, a value of 0 aborts the program run
|               after any error messages are  printed.   A  value  of  -1
|               continues the program after printing any error messages.
|  
|       $label  Is the statement to which control is transferred when  an
|               error  occurs.   If a label is used, the program executes
|               the error-trapping statements that follow it.   The  last
|               of  these is a call to DBRETN, which transfers control to
|               the command following  the  1022  call  that  caused  the
|               error.   Naturally,  the error-trapping statements should
|               be constructed in such a way that they only execute  when
|               there is an error.
|  
|       IERT    Is a variable that receives the error type-code number on
|               trapping.  If the user sets this variable to 0 during the
|               error subroutine operation, the label  specified  in  the
|               'ERRT.' option (if present) is ignored.
|  
|       IERC    Is a variable that receives the error code number.
|  
|       IFLAG   1:  Print error messages at the terminal (default).
|               0:  Suppress error messages.
|  
|  If a 1022 error occurs  during  the  error  subroutine  execution,  no
|  additional   error   trapping  occurs.   Program  execution  continues
|  sequentially.  If the 'ERRT.' option was present in the 1022 call that
|  caused  the  error,  the  error  subroutine is still executed, but the
|  return is to the label specified after the 'ERRT.' keyword.

   FORTRAN INTERFACE ROUTINES                                   Page 2-46
   Revision 5


   The following is a sample program fragment using DBERRH.

                            .
                            .
                            .
             EXTERNAL ERRTRP
             COMMON/FLAGS/IERT,IERC
                            .
                            .
                            .
             CALL DBFOR
             CALL DBERRH(ERRTRP,IERT,IERC,1)
                            .
                            .
                            .
             CALL DBEND
             END
             SUBROUTINE ERRTRP
             COMMON/FLAGS/IERT,IERC
                            .
                            .
                            .
             RETURN
             END


   When an error occurs, the error message types out and then  ERRTRP  is
   executed.   The  return from ERRTRP is to the next command in the main
   program after the error occurred.
|  
|  
|  
|  2.10.5.3  The DBRETN Subroutine
|  
|  The routine DBRETN marks the end of a set of error-handling statements
|  to which control has been transferred through a call to DBERRH.
|  
|  The CALL is:
|  
|       CALL DBRETN
|  
|  DBRETN transfers control to the command  following  the  1022  command
|  that caused the error.



   2.10.5.4  The DBERRT Subroutine


   The routine DBERRT can print the message text for the last error  onto
   the user's terminal.  It can also store that text in a variable.

   The CALL is:
   FORTRAN INTERFACE ROUTINES                                   Page 2-47
   Revision 5


        CALL DBERRT(IFLAG,[IBUFF])

   Where:

        IFLAG     0:  Print the message on the terminal.
                  1:  Suppress printing the message.

        IBUFF     Is a variable that receives the error message  text  in
                  FORTRAN  A5 format.  The text is exactly 80 characters,
                  so IBUFF should be dimensioned at 16.

   This routine is useful when the user suppresses the automatic type out
   of  error  messages,  but  decides  during  error recovery to see that
   message.



   2.10.6  Converting System Dates -- DBNDAT And DBDATN

   The  routines  DBNDAT  and  DBDATN   convert   dates   to   and   from
   system-encoded  date  format.   DBNDAT  (number  to  date) converts an
   encoded date to the  corresponding  month,  day,  and  year  that  are
   returned  in separate variables.  DBDATN (date to number) performs the
   reverse operation.  The CALLs are:

        CALL DBNDAT(IDATE,IMONTH,IDAY,IYEAR)

             Provide IDATE;  and receive IMONTH, IDAY, IYEAR.

                       and

        CALL DBDATN(IDATE,IMONTH,IDAY,IYEAR)

             Provide IMONTH, IDAY, IYEAR;  and receive IDATE.

   Where:

        IDATE   Is an encoded date, the integer number of days since  Jan
                1, 1800.

        IMONTH  Is the corresponding month 1 to 12;  Jan=1, Feb=2, etc.

        IDAY    Is the corresponding day 1 to 31.

        IYEAR   Is the corresponding year 1970, 1973, etc.  If  IYEAR  is
                between 0 and 99, 1022 assumes the twentieth century.

   All values are integer.  These routines do not handle  dates  in  text
   form.   If an impossible date is given to DBDATN (such as IDAY greater
   than 31), IDATE is set to -1.
   FORTRAN INTERFACE ROUTINES                                   Page 2-48
   Revision 5


   2.10.7  Supplying Or Receiving System Variables -- DBSYSV

|  The DBSYSV routine retrieves the value or the address of the value  of
   any  system variable, or assigns values to system variables.  The CALL
   is:

        CALL DBSYSV(SYSVN,SETF,IVAR)

   The first argument, SYSVN, is:

        1) a system variable number from Table 2-1 below, or

        2) the name of the system variable, either an ASCII literal or  a
        variable.

   Using a system variable number or  FORTRAN  variable  is  faster  than
   using a name.

   The second argument, SETF, specifies whether to supply or receive  the
   value of the system variable.

        SETF is  0  To receive the value.
                 1  To supply the value.
|                2  To store the address of a user routine
|                   in the system variable. 
|  
|  The third argument, IVAR, supplies or receives the value  or  supplies
|  the address to be used as the value.  IVAR receives the user-specified
   data type unless such automatic conversion is  overridden  by  setting
   the DISP., BIN., SYSHLMODE, or SYSHLDISP flags.
   FORTRAN INTERFACE ROUTINES                                   Page 2-49
   Revision 5


                 TABLE 2-1. SYSTEM VARIABLE CHARACTERISTICS

           NAME    NUMBER  DATA TYPE      USER   STANDARD   DEFAULT
                                        SETTABLE DEFAULT    SETTABLE

        SYSADDMSG    105   INTEGER         YES     0          YES
        SYSADMCDIR   126   INTEGER         NO      0          YES
        SYSALCMSG    104   INTEGER         YES     0          YES
        SYSAMBATTR   132   INTEGER         YES     0          YES
        SYSAUXCHK    128   INTEGER         YES     0          YES
        SYSBETWEEN   131   INTEGER         YES     0          YES
        SYSCASE      3     INTEGER         YES     0          YES
        SYSCBLSIGN   41    INTEGER         YES     1          YES
        SYSCHANGED   79    INTEGER         NO      0          NO
        SYSCLOSE2    115   INTEGER         NO      0          YES
        SYSCOLNAME   72    TEXT 25         NO      blanks     NO
        SYSCORESS    74    INTEGER         YES     50000      YES
        SYSCUSTDMI   88    INTEGER         YES     0          YES
        SYSCVTERR    113   INTEGER         YES     0          YES
        SYSDAMAGE    200   INTEGER         NO      0          NO
        SYSDATE      1     DATE            NO      0          NO
        SYSDATEFMT   112   INTEGER         YES     0          YES
        SYSDAYTIME         TEXT            NO      0          NO
        SYSDBEXMSG   44    INTEGER         YES     0          YES
        SYSDCORESS   75    INTEGER         YES     0          NO
        SYSDELIM     24    TEXT            YES     ,          YES
        SYSDEQFAST   68    INTEGER         YES     0          YES
        SYSDIV       110   INTEGER         YES     0          YES
        SYSDIVMSG    108   INTEGER         YES     0          YES
        SYSDIVP      111   INTEGER         YES     0          YES
        SYSDMETRID   133   INTEGER         YES     0          YES
        SYSDSALIAS   70    TEXT 25         YES     blanks     NO
        SYSDSENQ     65    INTEGER         NO      1          NO
        SYSDSFILE    69    TEXT 80         NO      blanks     NO
        SYSDSNAME    58    TEXT 25         NO      blanks     NO
        SYSENQDEF    123   INTEGER         NO      1          YES
        SYSENQTYPE   67    INTEGER         YES     1          YES
        SYSERRCODE   21    OCTAL           NO      0          NO
        SYSERRDEV    17    SIXBIT INT      NO      0          NO
        SYSERREXT    19    SIXBIT INT      NO      0          NO
        SYSERRFILE   18    SIXBIT INT      NO      0          NO
        SYSERRPPN    20    OCTAL           NO      0          NO
        SYSERRTEXT   78    INTEGER         YES     0          YES
        SYSEURODAT   120   INTEGER         YES     0          YES
        SYSEXECKP    85    INTEGER         YES     0          YES
        SYSEXP       7     DATE            NO      0          NO
        SYSEXPTYPE   29    INTEGER         YES     0          YES
        SYSFDMATT    16    INTEGER         NO      0          NO
        SYSFMSG      59    INTEGER         YES     0          NO
        SYSGTABERR   129   INTEGER         NO      0          NO
        SYSHLCVT     34    INTEGER         YES     0          YES

   FORTRAN INTERFACE ROUTINES                                   Page 2-50
   Revision 5


           TABLE 2-1 SYSTEM VARIABLE CHARACTERISTICS (continued)

           NAME    NUMBER  DATA TYPE      USER   STANDARD   DEFAULT
                                        SETTABLE DEFAULT    SETTABLE

        SYSHLDISP    26    INTEGER         YES     0          YES
        SYSHLMODE    27    INTEGER         YES     0          YES
        SYSHLNAME    63    INTEGER         NO      0          YES
        SYSID        8     INTEGER         NO      0          NO
        SYSIFTYPE    42    INTEGER         YES     0          YES
        SYSIOMSG     102   INTEGER         YES     0          YES
        SYSJOBNO     25    INTEGER         NO      0          NO
        SYSKEEPBUF   125   INTEGER         YES     0          YES
        SYSKEEPPSI   121   INTEGER         YES     1          YES
        SYSLINE      4     INTEGER         NO      0          NO
        SYSMSTIME          INTEGER         NO      0          NO
        SYSNOFILOP   118   INTEGER         NO      1          YES
        SYSNOYMD     87    INTEGER         YES     0          YES
        SYSNOPSI     122   INTEGER         YES     0          YES
        SYSNOSEG     100   INTEGER         YES     0          YES
        SYSNOSEGP    61    INTEGER         NO      -1         YES
        SYSNOXCHAN   119   INTEGER         NO      0          YES
        SYSNREC      9     INTEGER         NO      0          NO
        SYSNRETRY    15    INTEGER         YES     10         YES
        SYSOVF       106   INTEGER         YES     0          YES
        SYSOVFMSG    109   INTEGER         YES     0          YES
        SYSOVFP      107   INTEGER         YES     0          YES
        SYSPAGE      2     INTEGER         YES     0          NO
        SYSPCCOL     82    INTEGER         YES     0          NO
        SYSPCRESET   84    INTEGER         YES     0          NO
        SYSPCROW     83    INTEGER         YES     0          NO
        SYSPPN       37    INTEGER         NO      0          NO
        SYSPROT20    28    TEXT 6          YES     blanks     YES
        SYSRECLOCK   86    INTEGER         NO      0          NO
        SYSRECMODE   60    INTEGER         NO      0          NO
        SYSRECNO     5     INTEGER         NO      0          NO
        SYSREP1      10    INTEGER         YES     0          YES
        SYSREP2      11    INTEGER         YES     0          YES
        SYSREP3      12    INTEGER         NO      0          NO
        SYSREPMODE   13    INTEGER         YES     0          YES
        SYSREPSYNC   14    INTEGER         YES     1          YES
        SYSRESET     23    INTEGER         YES     0          YES
        SYSRNGMSG    103   INTEGER         YES     0          YES
        SYSSCRDEV    64    TEXT 6          YES     DSK        YES
        SYSSCRFILE   76    INTEGER         YES     1          YES
        SYSSFDFLAG   114   INTEGER         NO      0          YES
        SYSSWEDSRT   77    INTEGER         YES     0          YES
        SYSTENQ      66    INTEGER         YES     2000       YES
        SYSTEXTDOT   127   INTEGER         YES     0          YES
        SYSTIME      6     TEXT 8          NO      0          NO
        SYSTOPIID    80    INTEGER         NO      0          NO
        SYSTOPSID    81    INTEGER         NO      0          NO
        SYSTRAPUP3   124   INTEGER         YES     0          YES

   FORTRAN INTERFACE ROUTINES                                   Page 2-51
   Revision 5


           TABLE 2-1 SYSTEM VARIABLE CHARACTERISTICS (continued)

           NAME    NUMBER  DATA TYPE      USER   STANDARD   DEFAULT
                                        SETTABLE DEFAULT    SETTABLE

        SYSTRETRY    43    INTEGER         YES     200        YES
        SYSUPROG     39    INTEGER         NO      0          NO
        SYSUPROJ     38    INTEGER         NO      0          NO
        SYSUSERADR   30    INTEGER         YES     0          YES
        SYSUSERD1    54    DATE            YES     01/01/1800 NO
        SYSUSERD2    55    DATE            YES     01/01/1800 NO
        SYSUSERD3    56    DATE            YES     01/01/1800 NO
        SYSUSERI1    45    INTEGER         YES     0          NO
        SYSUSERI2    46    INTEGER         YES     0          NO
        SYSUSERI3    47    INTEGER         YES     0          NO
        SYSUSERR1    48    REAL            YES     0          NO
        SYSUSERR2    49    REAL            YES     0          NO
        SYSUSERR3    50    REAL            YES     0          NO
        SYSUSERT10   52    TEXT 10         YES     blanks     NO
        SYSUSERT40   53    TEXT 40         YES     blanks     NO
        SYSUSERT5    51    TEXT 5          YES     blanks     NO
        SYSUSRADRP   71    INTEGER         NO      0          YES
        SYSWRITE20   57    INTEGER         YES     1          YES

   See the list of system variables in the General  Use  chapter  of  the
   User's  Reference  Manual for explanations of these variables.  DBSYSV
   ______  _________  ______
   respects all the runtime conversion flags.

   Examples:

             CALL DBSYSV(15,1,20)

        This sets SYSNRETRY to a value of 20.

             CALL DBSYSV('SYSDATE',0,IDAT)

        This puts today's date in encoded format into the variable IDAT.

             CALL DBSYSV('SYSNREC',0,NRECS)

        This call returns the number of currently selected  records,  the
        same  value that DBNREC returns.  It is usually used after a call
        to DBFIND, DBSRCH, or DBMAP.

|            CALL DBSYSV('SYSCUSTDMI',2,DMIRDR)
|  
|       This call stores the address of the routine DMIRDR in the  system
|       variable SYSCUSTDMI.
|  
|  DBSYSV can return or receive  values  for  the  subscripted  variables
|  SYSLINE,  SYSPAGE,  SYSPCCOL,  SYSPCRESET,  and SYSPCROW only when the
|  subscript is omitted.  In this case, the subscript  1  is  assumed  by
|  default.  Thus,
   FORTRAN INTERFACE ROUTINES                                   Page 2-52
   Revision 5


|       CALL DBSYSV('SYSLINE',0,LVAL)
|  
|  reads the value of the system variable SYSLINE(1)  into  the  variable
|  LVAL.   To receive or assign a value to a subscripted variable on some
|  channel other than 1, it is  necessary  to  use  a  DBEXEC  call  (see
|  "Executing Interactive Commands and Procedures--DBEXEC").



   2.10.7.1  Value-passing With System Variables -- SYSUSER__

   The SYSUSER__ system variables can be used to pass values between host
   language  programs  and 1022 through calls to DBEXEC (see below).  The
   values are assigned and retrieved with DBSYSV.

   SYSUSERD1, SYSUSERD2, and SYSUSERD3 are used  for  dates.   SYSUSERI1,
   SYSUSERI2, and SYSUSERI3 are used for integers.  SYSUSERR1, SYSUSERR2,
   and SYSUSERR3 are used for real numbers.  SYSUSERT5 is used  for  text
   of up to 5 characters, SYSUSERT10 for text of up to 10 characters, and
   SYSUSERT40 for text of up to 40 characters.

   Examples:

             CALL DBSYSV ('SYSUSERI1',1,IVAR)

        This sets SYSUSERI1 to the value of the variable IVAR.

             CALL DBEXEC ('LET SYSUSERD1 $FMONTH(BILL_DATE)')
             CALL DBSYSV ('SYSUSERD1',0,NEWBIL)

        This DBEXEC call uses a date function to give SYSUSERD1 the value
        of  the  first  day of the month of the attribute BILL_DATE.  The
        DBSYSV call puts the value of SYSUSERD1 into the variable NEWBIL.



   2.10.8  Executing Interactive Commands And Procedures -- DBEXEC

   The DBEXEC routine executes any command in interactive System 1022, or
   transfers  control  completely  to interactive System 1022.  There are
   two forms to the CALL:

        (1) CALL DBEXEC
        (2) CALL DBEXEC(cmd-string [, $label])

   DBEXEC is supported only in HR1022.REL, the reentrant version  of  the
   subroutine library.

   Use DBEXEC whenever you need to execute  a  command  which  cannot  be
   performed   by  the  Host  Language  CALLs.   A  CALL  to  DBEXEC  has
   significantly more overhead than a call to the other System  routines.
   Most  retrieval,  sorting,  and updating functions can be accomplished
   without DBEXEC,  but  report  writing,  PL1022  programming,  and  the
   command   file   capabilities   of  System  1022  require  the  DBEXEC
   FORTRAN INTERFACE ROUTINES                                   Page 2-53
   Revision 5


   subroutine.

   In addition, DBEXEC can transfer control to the interactive System and
   then  return to the FORTRAN program, permitting interactive use in the
   middle of a program.

   The DBEXEC CALL with no arguments in (1) above  transfers  control  to
   interactive  System  1022  command  level.  All of the capabilities of
   1022 are then available to the user.  The command:

        HOST

   returns control to the FORTRAN program at the statement following  the
   call to DBEXEC.  Errors are handled interactively until HOST is given.

   The conditions in the data set are not altered by either the  call  to
   DBEXEC  or  the  HOST command.  For example, the user may find records
   for the program to process when it resumes, or the  program  can  find
   records  for  review  by  the user during the call (1) to DBEXEC.  The
   following FORTRAN fragment relies on the user to  create  the  desired
   selection group of records.

        C ENTER INTERACTIVE COMMAND LEVEL FOR THE USER TO
        C SELECT RECORDS.

               CALL DBEXEC

        C PROCESS SELECTED RECORDS WHEN THE USER
        C TYPES THE HOST COMMAND

        100    CALL DBGREC($999)
               .
               .
               GOTO 100
        999    CALL DBEND
               END


   The DBEXEC call in (2) above supplies a command string to be  executed
   by the interactive System.  This is either a quoted text literal ('USE
   DAYRPT'), or an array containing a null delimited string in ASCII.

   The optional second  argument  specifies  a  statement  label  in  the
   FORTRAN  program  to  go  to  when  the  System 1022 command processor
   requires more input.  More input is needed when  a  line  continuation
|  character  ends  the  command  string argument, or when the command or
|  command block is incomplete.  Any Pl1022 or report program segment  or
|  structured  command  must  be  fully specified in a single DBEXEC call
|  unless the statement label is specified.  If more input is required by
   the  command  processor, but no second argument appears in the call to
   DBEXEC, then an error is generated.  The action taken  on  this  error
   condition  or  any  other  error  arising  from  the call to DBEXEC is
   controlled with the routine DBERR.
   FORTRAN INTERFACE ROUTINES                                   Page 2-54
   Revision 5


   The second argument is used in applications where  the  program  reads
   commands  from  the  terminal,  and passes them to DBEXEC.  The $label
   argument is needed  if  the  user  types  a  line  continuation.   The
   continuation is supplied to 1022 by repeating the DBEXEC call with the
|  new information.  The $label is also needed when you enter a PL1022 or
|  report  program segment or any structured commands using DBEXEC and do
|  not enter the full command string.
|  
|  
|  Examples:
|  
|  1. The following FORTRAN program executes a PL1022  segment  in  which
|     the  user is prompted to enter the names of attributes to which the
|     interactive 1022 INFORM ATTRIBUTE command will be applied.
|              CHARACTER*25 NAME
|              CALL DBF6
|              CALL DBOPEN('FOO')
|              TYPE *,'Enter attribute names one per line; end with blank line'
|              CALL DBEXEC('PL START .',$10)
|       10     ACCEPT 30,NAME
|       30     FORMAT(A)
|              IF (NAME .NE. ' ') CALL DBEXEC('INF ATTR '//NAME//' LENGTH .',$10)
|              CALL DBEXEC('PL END .')
|              CALL DBEND
|              END
|  
|  
     2. The following FORTRAN  program  uses  DBEXEC.   It  executes  the
        command  file  WEEKLY.DMC,  and  then transfers control to System
        1022 interactive command level.

               CALL DBFOR
               CALL DBERR($2,ERT,ERC,1)
               CALL DBEXEC('USE WEEKLY.DMC')
               TYPE 1
        1      FORMAT(/' WEEKLY RUN COMPLETED'/)
               CALL DBEXEC
        C  RETURN HERE FROM INTERACTIVE MODE WHEN THE USER TYPES "HOST"
               GO TO 4
        2      TYPE 3
        3      FORMAT(/' ?WEEKLY RUN ABORTED DUE TO ERROR'/)
        4      CALL DBEND
               END


        This program calls the routine DBERR to trap to  statement  2  in
        the   event  of  an  error  while  processing  the  command  file
        WEEKLY.DMC.  This trapping is not enabled while the program is in
        interactive  mode,  during the second call to DBEXEC, but it goes
        back into effect when control returns to the FORTRAN program.
   FORTRAN INTERFACE ROUTINES                                   Page 2-55
   Revision 5


|  2.10.9  Passing Records In Nonstandard Format To 1022 -- DBLODR
|  
|  It is possible to load, append, and transact fixed-length  records  in
|  formats  other  than 7-bit ASCII, ASCII ISAM, SIXBIT, and SIXBIT ASCII
|  with a user-written host language routine that reads and reformats the
|  data and passes it to 1022 through the DBLODR routine, one record at a
|  time.   This  process  is  made  possible  by  the   system   variable
|  SYSCUSTDMI, which is set to the address of the user's data translation
|  routine, the DBSYSV routine, and the  CUSTDMI  keyword  of  the  LOAD,
|  APPEND, and TRANSACT commands.
|  
|  The general procedure for loading records in nonstandard format is  as
|  follows:
|  
|       1.  The user writes a host language program  that  calls  DBSYSV,
|           which  stores  the  address  of  the  user's data translation
|           routine in the system variable  SYSCUSTDMI.   You  store  the
|           address  of  the  data  translation  routine in SYSCUSTDMI by
|           specifying a 2 for the SETF argument in the DBSYSV call  (see
|           above).
|  
|       2.  The program then calls DBEXEC, specifying the LOAD (or APPEND
|           or TRANSACT) command with the appropriate DESC clause and the
|           keyword CUSTDMI.  The CUSTDMI keyword signals 1022 to use the
|           data   translation   routine   whose  address  is  stored  in
|           SYSCUSTDMI instead of using the standard DMI reader.
|  
|       3.  The user's data translation routine is then executed.  If you
|           are  running  TOPS-10,  your  data  translation  routine must
|           consist entirely of low-segment code.  If your  routine  uses
|           FORTRAN I/O, the FORTRAN run-time library must be forced into
|           the low segment as well.
|  
|           The user's data translation routine should do the following:
|  
|           a.  Open the file containing the data to be  reformatted  and
|               passed to 1022.
|  
|           b.  Read a record's worth of data into an array, reformatting
|               the data as needed.
|  
|           c.  Use the DBLODR call to pass the contents of the array  as
|               a single record to 1022.  The CALL is:
|  
|                    CALL DBLODR(IAR,IFLAG)
|  
|               The DBLODR call takes two arguments.  The first of  these
|               (IAR)  is  an  integer  array that holds the record to be
|               passed in A5 format.  The second is an  integer  variable
|               (IFLAG),  which  1022 automatically resets to 0 unless an
|               error is encountered or the record limit imposed by a MAX
|               clause  is  reached.   A  0  setting  signals  the user's
|               routine that 1022 is ready to accept more  data.   If  an
|               error is encountered or the record limit imposed by a MAX
   FORTRAN INTERFACE ROUTINES                                   Page 2-56
   Revision 5


|               clause is reached, 1022 returns  a  value  of  -1,  which
|               signals  the  user's  routine  that  1022 will ignore any
|               further input.
|  
|           d.  Repeat steps (a)-(c) until  the  desired  data  has  been
|               passed  from  the foreign source to 1022.  Then exit from
|               the data translation routine.
|  
|  
|       4.  Complete execution of the main program.
|  
|  System  1022  passes  a  number  of  arguments  to  the  user's   data
|  translation.   You  may  wish to hard-code these or ignore them.  They
|  are the following:
|  
|       1.  The file specification  (80  characters,  blank  padded,  the
|           extension ".DMI" not defaulted);
|  
|       2.  The number of columns of useful data in a  record,  that  is,
|           the  minimum  length  of the record image passed back through
|           DBLODR;
|  
|       3.  The length of the record in the source  file,  or  -1  if  of
|           variable length;
|  
|       4.  The user-specified format, encoded as 0 if ASCII, 1 if  ASCII
|           ISAM, -1 if SIXBIT ISAM, and -2 if SIXBIT;
|  
|       5.  The blocking factor, if specified;
|  
|       6.  The block size for magtapes, if specified.
|  
|  Example:
|  
|  The following FORTRAN program uses the data translation routine LODRDR
|  to read the contents of the file DIRECT.DMI, loading the data into the
|  1022 data set DIRECT.
   FORTRAN INTERFACE ROUTINES                                   Page 2-57
   Revision 5


|              EXTERNAL LODRDR
|              CALL DBFOR
|              CALL DBSYSV('SYSCUSTDMI',2,LODRDR)
|  C           ALLOCATE SOME CORE
|              OPEN(UNIT=20,DEVICE='NUL:',FILE='FOO.BAR')
|              CALL DBEXEC('LOAD DESC DIRECT CUSTDMI')
|              CALL DBEND
|              STOP
|  
|              SUBROUTINE LODRDR
|              INTEGER ADRCT(14)
|              OPEN(UNIT=20,FILE='DIRECT.DMI')
|  10          READ(20,20,END=30)
|  20          FORMAT(14A5)
|              CALL DBLODR(ADRCT,IFLAG)
|              IF (IFLAG.EQ.0) GOTO 10
|  30          RETURN
|              END



   2.10.10  DBDBUG Routines

   DBDBUG provides a call for debugging  user  programs.   The  user  can
   determine  whether a program is inadvertently writing into 1022 memory
   areas and producing bugs.  The call is:

        CALL DBDBUG ('MCHK', status)

   Where:

        'MCHK'    Is an ASCII literal that is a keyword.

        status    Is either 'ON' or 'OFF'.  Status can be changed at  any
                  time  in  the execution of a program.  Status begins as
                  OFF.

   When status is 'ON', 1022 generates a checksum at  the  beginning  and
   end  of  each  1022  routine.   If,  at the beginning of the next 1022
   routine, the newly generated checksum does not  match  the  last  one,
   1022 prints:

        "%1022 Memory modified by user program"

   If 1022 can determine the location that was modified, it prints:

        "%1022 Memory modified by user program at location nnnnnn".

   System 1022 then continues execution.
   FORTRAN INTERFACE ROUTINES                                   Page 2-58
   Revision 5


   2.10.11  The DBVAR Routine

   The DBVAR routine determines if a 1022 user variable has been  defined
   and  returns  the  variable's type.  If type text, it also returns the
   text length.

   The CALL is:

        CALL DBVAR (NAME, TYPE [, LENGTH])

   Where:

        NAME      Is either an array of DIMENSION 2 or a double-precision
                  variable  containing  a 1022 user variable name, or the
                  variable name as a text literal.

        TYPE      Is the variable that receives the 1022 variable type:

                  -1  UNDEFINED
                   0  INTEGER
                   1  REAL
                   2  TEXT
                   4  DATE
                  12  DOUBLE INTEGER

        LENGTH    Is the optional variable that receives  the  length  of
                  the text variable.



   2.11  AUDIT ROUTINES

   The DBAUD routine controls audit trails from  FORTRAN  programs.   The
   program  may  record  its  own  audit  trail  entries,  in addition to
   executing audit commands parallel to the interactive  audit  commands.
   See the audit trail chapter in the User's Reference Manual.



   2.11.1  Starting The AUDIT Trail

   Start an audit trail for the current data set with:

        CALL DBAUD('START' [,'FILE',file] [,'LOCK'] [,'JOB']
              [,'PRE'] [,'POST'] ['NOMSG'] ['AUTO'] ['NOREAD'])

   where the optional keywords and possible  defaults  are  the  same  as
   those in the interactive AUDIT START command.
   FORTRAN INTERFACE ROUTINES                                   Page 2-59
   Revision 5


   2.11.2  Writing AUDIT File Checkpoints

   Enter checkpoints into the current audit file with:

        CALL DBAUD('CHECK',checkname)

   which performs the same function as the AUDIT CHECKPOINT command.  The
   checkname argument is a null delimited text string or literal.



   2.11.3  Custom AUDIT Entries

   Audit file entry codes 700 through 777 octal (448 through 511 decimal)
   are  reserved  for  users.   Insert these entries into the audit trail
   with:

        CALL DBAUD('PLACE', ICODE, LEN, ENTRY)

   Where:

   ICODE   Is the code (700-777 octal) that the program has  assigned  to
           this entry.

   LEN     Is the length in words of the entry array.

   ENTRY   Is an array that contains the entry data.

   These entries are later read from the  audit  trail  with  the  DBAGET
   routine.



   2.11.4  Retrieving AUDIT File Information

   The DBAxxx family of  routines  reads  audit  file  entries,  allowing
   customized  audit  file  reports  as  well as the retrieval of program
   defined entries (codes 700-777 octal).


   Initialization for AUDIT Retrievals
   ______________ ___ _____ __________

   Initialize reading the audit file with the following call:

        CALL DBAINI(FNAME [,'ALL'])

   FNAME      Is the name of the audit trail file.

   'ALL'      Indicates that entries for all data sets, including  others
              than the one currently opened, are returned.

   After calling DBAINI, entries may be retrieved from  the  audit  trail
   with the call:
   FORTRAN INTERFACE ROUTINES                                   Page 2-60
   Revision 5


        CALL DBAGET(LENF, FLAGS, LENE, ENT, EOF)

   LENF    Is the length of the FLAGS array.

   FLAGS   Receives information about the entry as follows:

        FLAGS(1)    Entry code.

        FLAGS(2)    Entry length in words.

        FLAGS(3)    Data set handle.

        FLAGS(4)    The date  and  time  that  the  entry  was  made,  in
                    universal  date-time  standard format (TOPS-10) or in
                    internal  date  and  time  format   (TOPS-20).    See
                    Appendix C.

        FLAGS(5)    The project-programmer number (TOPS-10) or logged  in
                    directory  number (TOPS-20) of the program making the
                    entry.

        FLAGS(6)    The job number of the program making the entry.

        FLAGS(7)    The location  of  the  entry.   If  the  entry  is  a
                    checkpoint,  this  is  the  1022  assigned checkpoint
                    number.

        FLAGS(8)    1 if the entry  was  made  through  a  Host  Language
                    program, 0 otherwise.

        FLAGS(9)    1 if the data set had UPDATE ON when  the  entry  was
                    made, 0 otherwise.

        FLAGS(10)   1 if this entry is a CHECKPOINT, 0 otherwise.

   LENE    Is the length of the ENT array.

   ENT     Is the array that receives the entry from the audit file.

   EOF     Is zero when the audit file being read is not at  end-of-file.
           If  EOF  is  nonzero,  the file is at the end, and no FLAGS or
           entry data are returned.

   The data in a program defined entry is identical to  what  was  placed
   into the audit file with DBAUD.



   The following system defined entries are returned.  Each code is given
   as octal, and decimal "(n.)".  A "user number" is the directory number
   pair under TOPS-20, or it is the project-programmer number pair  under
   TOPS-10.  Those entries marked "versions before 116" are returned by a
   version of 1022 earlier than 116 or from a data set  created  under  a
   version  earlier  than  116  which has not been transformed by an UPTO
   FORTRAN INTERFACE ROUTINES                                   Page 2-61
   Revision 5


   command into a 116-style data set.

   Entry type 4 (4.):  Data set Opened [Versions before 116]
   _____ ____ _ _____  ____ ___ ______

   ENT(1) - ENT(5)   The internal data set name.  If  FOOTBALLPLAYERS  IN
                     SPORTS    is    opened,    ENT(1) - ENT(3)   contain
                     FOOTBALLPLAYERS and ENT(4) - ENT(5) contain blanks.

   ENT(6)            The file ID, or "handle", of the first data  set  in
                     the file.

   ENT(7)            1 if the data set was opened for READ ONLY access, 0
                     otherwise.

   ENT(8)            1 if the data set was DAMAGED, 0 otherwise.

   ENT(9)            1 if the data set was opened before the audit  entry
                     was  written,  0 if the audit file was opened at the
                     same time as the data set as the result of an  AUDIT
                     START AUTO condition.

   ENT(10)           1 if UPDATE was  ON  when  the  entry  was  made,  0
                     otherwise.

   ENT(11)           The user number of the data set that was opened.

   ENT(12) - ENT(13) The file name and  extension  of  the  data  set  in
                     ASCII.

   ENT(14) - ENT(15) The device name of the data set in ASCII.


   Entry type 5 (5.):  Audit Trail Started
   _____ ____ _ _____  _____ _____ _______

   ENT(1)   The format version number of the audit trail file.


   Entry type 6 (6.):  Comment
   _____ ____ _ _____  _______

   ENT(1) - ENT(FLAGS(2))   Contains the text of the comment.


   Entry type 7 (7.):  Pre-image Block
   _____ ____ _ _____  _________ _____

   Pre-image block.


   Entry type 10 (8.):  Post-image Block
   _____ ____ __ _____  __________ _____

   Post-image block.
   FORTRAN INTERFACE ROUTINES                                   Page 2-62
   Revision 5


   Entry type 11 (9.):  End Audit Trails
   _____ ____ __ _____  ___ _____ ______

   No information is returned.


   Entry type 13 (11.):  Data set Closed [Versions before 116]
   _____ ____ __ ______  ____ ___ ______

   This entry is identical to Entry type 4, Data set Opened.


   Entry type 14 (12.):  End Write Operation
   _____ ____ __ ______  ___ _____ _________

   This entry is  generated  whenever  an  update  operation  ends.   For
   pre-image  audit  trails  this contains only a header.  For post-image
   audit trails this contains a checkpoint.


   Entry type 15 (13.):  Begin Write Operation [Versions before 116]
   _____ ____ __ ______  _____ _____ _________

   This entry may be used as a checkpoint.

   ENT(3)    Size of the file in blocks (4 blocks = 1 TOPS-20 page).

   ENT(4)    Size of the DMS file in words.

   ENT(5)    0, or the date the file was damaged,  in  radix  date  form.
             See Appendix C.

   ENT(6)    0, or the time the file was damaged, in  milliseconds  since
             midnight.

   ENT(7)    0, or the user number of the update job when  the  file  was
             damaged.

   ENT(8)    The number of active records in the data set.

   ENT(9)    The number of deleted records in the data set.

   ENT(10)   The number of records allocated in the data set.

   ENT(11)   The  last  update  number  for  the  data  set.    This   is
             incremented by 1 when the data set is opened for writing.

   ENT(12)   The date of last update, in radix date form.

   ENT(13)   The time of last update, in milliseconds since midnight.

   ENT(14)   The user number of the update job.

   ENT(15)   1 if the data set had ADMIT criteria, 0 if the data set  had
             no ADMIT criteria.
   FORTRAN INTERFACE ROUTINES                                   Page 2-63
   Revision 5


   Entry type 16 (14.):  Checkpoint [Versions before 116]
   _____ ____ __ ______  __________

   This is a checkpoint entry, identical to Entry type  15  (Begin  Write
   Operation) except that:

   ENT(1) - ENT(2)   The checkpoint name in ASCII.


   Entry type 17 (15.):  Begin Write Operation [Version 116 and later]
   _____ ____ __ ______  _____ _____ _________

   This entry is identical to Entry type 15 (versions  before  116  Begin
   Write Operations) except that:

   For pre-image audit trails it contains a checkpoint.   For  post-image
   audit trails it contains only a header.


   Entry type 20 (16.):  Checkpoint Pre-image [Version 116 and later]
   _____ ____ __ ______  __________ _________

   This is a pre-image checkpoint entry, identical to Entry type 16.


   Entry type 21 (17.):  Data set Opened [Version 116 and later]
   _____ ____ __ ______  ____ ___ ______

   ENT(1) - ENT(5)   The internal data set name.  If  FOOTBALLPLAYERS  IN
                     SPORTS    is    opened,    ENT(1) - ENT(3)   contain
                     FOOTBALLPLAYERS and ENT(4) - ENT(5) contain blanks.

   ENT(6)            The file ID, or "handle", of the first data  set  in
                     the file.

   ENT(7)            1 if the data set was opened for READ ONLY access, 0
                     otherwise.

   ENT(8)            1 if the data set was DAMAGED, 0 otherwise.

   ENT(9)            1 if the data set was opened before the audit  entry
                     was  written,  0 if the audit file was opened at the
                     same time as the data set as the result of an  AUDIT
                     START AUTO condition.

   ENT(10)           1 if UPDATE was  ON  when  the  entry  was  made,  0
                     otherwise.

   ENT(11)           The user number of the data set that was opened.

   ENT(12) - ENT(17) The  the  first  30  characters  of  the  DMS   file
                     specification.


   Entry type 22 (18.):  Data set Closed [Version 116 and later]
   _____ ____ __ ______  ____ ___ ______

   This entry is identical to Entry type 21, Data set Opened.
   FORTRAN INTERFACE ROUTINES                                   Page 2-64
   Revision 5


   Entry type 23 (19.):  Checkpoint Post-image [Version 116 and later]
   _____ ____ __ ______  __________ __________

   This is a post-image checkpoint entry, identical to Entry type 16.



   2.11.5  Random Access Audit Trail Input

   The DBALOC routine sets the  position  in  the  audit  file  at  which
   reading  or  processing  begins.  It searches the audit file, counting
   checkpoints.  If DBALOC  is  not  called,  processing  starts  at  the
   beginning  of  the  audit  file.  DBAINI must be called before DBALOC.
   The call is:

                            {[,PRE]}
        CALL DBALOC(LOCODE,N{      })
                            {,POST }

   Where:

   LOCODE   Is the locator code:

            0 = Start of file
            1 = Checkpoint number N
            2 = Checkpoint name N
            3 = Last Nth checkpoint
            4 = First Nth checkpoint

   N        Is a name or integer as indicated by LOCODE

   PRE      Specifies pre-images;  the default.

   POST     Specifies post-images.

   To start input at checkpoint "HEREGOES", for example, the call is:

        CALL DBALOC (2, 'HEREGOES')

   To start input at the last checkpoint:

        CALL DBALOC(3,1)

   To start input at the next to last post-image checkpoint:

        CALL DBALOC(3,2,'POST')
   FORTRAN INTERFACE ROUTINES                                   Page 2-65
   Revision 5


   2.11.6  Loading Programs Containing DBAxxx Calls

   The DBAxxx family of routines is included only in HL1022.REL, but  you
   may  want  to combine them with programs searching HR1022.REL in order
   to use both DBEXEC + HL audit routines.  To load FORTRAN programs with
   both DBEXEC and DBAxxx calls, issue the following commands:

         RUN LINK
        *NEW.REL
        *SYS:HR1022.REL/INCLUDE:(DBEXEC,EXECF.)
        *SYS:HL1022.REL/SEARCH
        *NEW.EXE/SAVE/GO
        *...(other LINK commands)...

   Note that not only must HR1022.REL be referenced before HL1022.REL but
   all  programs  linked  in  this  way  must be relinked each time a new
   System 1022 release is installed to avoid version skew errors.



   2.11.7  Examples

   The following program starts a LOCKed audit trail on the current  data
   set.   The  audit  file  has  an  extension equal to the program's job
   number.  A checkpoint named "STARTUP" is then placed  into  the  audit
   trail, and the program continues.

                    CALL DBFOR
                    CALL DBOPEN('PAYROL')
                    CALL DBAUD('START','LOCK','JOB')
                    CALL DBAUD('CHECK','STARTUP')
                    .
                    .
                    .


   The following fragment writes  a  custom  audit  entry.   The  program
   accepts  the user's name and authorization code in the initialization.
   These values are placed in the custom audit entry with code 700 octal.

                    .
                    .
                    .
                    (Initialization - accept and verify
                     NAME and AUCODE)
                    .
                    .
                    .
                    CALL DBOPEN('PAYROL')
                    CALL DBAUD('START','FILE','PAYAUD','LOCK')
                    ENTRY(1)=NAME(1)
                    ENTRY(2)=NAME(2)
                    ENTRY(3)=AUCODE
                    CALL DBAUD('PLACE',"700,3,ENTRY)
   FORTRAN INTERFACE ROUTINES                                   Page 2-66
   Revision 5


                    .
                    .
                    .


   Given an application  using  the  previous  custom  AUDIT  ENTRY,  the
   following  program  reports  the authorization codes for all users who
   have accessed the data set.

                    DIMENSION ENTRY(3)
                    CALL DBFOR
                    CALL DBAINI('PAYAUD.DML','ALL')
            10      CALL DBAGET(1,FLAG,3,ENTRY,IEND)
                    IF (IEND .NE. 0) GO TO 100
                    IF (FLAG .NE. "700) GO TO 10
                    TYPE 1000,ENTRY
            1000    FORMAT(2A5,10X,I6)
                    GO TO 10
            100     STOP
                    END


   FORTRAN INTERFACE ROUTINES                                   Page 2-67
   Revision 5


   2.12  SAMPLE FORTRAN PROGRAMS

   The following is  a  sample  FORTRAN  application  program.   All  the
   persons  whose first name is FRED are selected from a data set.  Their
   social security number is typed, followed by  a  question  mark.   The
   user  replies Y or N to the question mark.  If the user replies Y, the
   record is deleted from the data set.   If  the  user  replies  N,  the
   record is kept but the person's age is incremented by one.

            DIMENSION ISSN(3)
            CALL DBFOR
            CALL DBOPEN('PSN')
   C FIND THE RECORDS
            CALL DBFIND('NAME','EQ','FRED')
   C LOOP IN LOCAL MODE PROCESSING EACH RECORD
   10       CALL DBGREC($25)
   C GET SSN
            CALL DBVAL('SSN',ISSN)
            TYPE 100,ISSN
   100      FORMAT(1X,2A5,A1,'?',$)
            ACCEPT 200,IAN
   200      FORMAT(A1)
            IF(IAN.EQ.'Y') GO TO 300
   C INCREMENT AGE BY ONE
            CALL DBVAL('AGE',IAGE)
            IAGE=IAGE+1
            CALL DBCHNG('AGE',IAGE)
            GO TO 10
   C DELETE RECORD
   300      CALL DBDEL
            GO TO 10
   C ALL DONE
   25       CALL DBEND
            END
   FORTRAN INTERFACE ROUTINES                                   Page 2-68
   Revision 5


   The following is a more advanced FORTRAN  application  program.   Note
   that  because  this  program  calls  DBEXEC  it  must  be  loaded with
   HR1022.REL.

   !THIS PROGRAM INTERACTIVELY CORRECTS ERRORS IN A DATA SET AFTER IT
   !   HAS BEEN LOADED.  IT PROMPTS FOR THE NAME OF THE DATA SET AND
   !   AN ERROR LOG FILE AND THEN CREATES AN UNBUNDLED DATA SET
   !   FROM THE ERROR FILE.  USING THE TWO DATA SETS, IT GOES THROUGH THE
   !   ERROR DATA SET AND LOCATES THE CORRESPONDING RECORDS WITH ERRORS.
   !   THE USER CHOOSES TO DELETE, IGNORE, OR CORRECT THE BAD RECORD.

            IMPLICIT INTEGER (A-Z)
            DIMENSION CMDBUF(14),DSNAME(5),ERRFIL(5)
            EQUIVALENCE (ERRFIL(1),CMDBUF(10))

   !SET UP CMDBUF FOR DBEXEC CALL

            DATA (CMDBUF(I),I=1,9)/'CREAT','E NOM','SG SE','T COR',
            1       'REC D','ESC C','ORREC',' DATA','     '/

   !INITIALIZE FOR FORTRAN

            CALL DBFOR

   !READ DATA SET NAME AND OPEN IT.  TRY AGAIN IF IT IS NOT THERE.

   50       TYPE 1
   1        FORMAT(//,' DATA SET:' $)
            ACCEPT 2,DSNAME
   2        FORMAT(5A5)
            DSNAME(5)=0             !TERMINATE WITH NULL WORD
            CALL DBERR($50,I,I,-1)  !TRY AGAIN IF NO DATA SET
            CALL DBOPEN(DSNAME)

   !READ NAME OF 1022 ERROR LOG FILE.

            TYPE 3
   3        FORMAT(' ERROR FILE:' $)
            ACCEPT 2,ERRFIL
            ERRFIL(5)=0             !TERMINATE WITH NULL WORD

   !CREATE AN UNBUNDLED DATA SET FOR THE ERROR FILE.  FIRST, WRITE OUT
   !   A DESCRIPTION (.DMD) FILE

            OPEN (UNIT=20,DEVICE='DSK',FILE='CORREC.DMD')
            WRITE(20,4)
   4        FORMAT('ATTR ID INT LEN 10',/,'FILLER 3',/,
            1      'ATTR NAME TEXT LEN 25',/,'FILLER 1',/,
            1      'ATTR WHY  TEXT LEN  6',/,'FILLER 1',/,
            1      'ATTR DATA TEXT LEN 24')
            CLOSE (UNIT=20)

   !ALL SYSTEM 1022 ERRORS ARE FATAL FROM NOW ON.
   FORTRAN INTERFACE ROUTINES                                   Page 2-69
   Revision 5


            CALL DBERR($999,I,I,-1)

   !NOW CREATE THE UNBUNDLED DATA SET

            CALL DBEXEC(CMDBUF)

   !OPEN THE UNBUNDLED DATA SET AND KEY THE ID ATTRIBUTE

            CALL DBOPEN('NOCLOSE','CORREC')
            CALL DBEXEC('KEY NOMSG ID')

   !TELL THE USER THE SIZE OF THE ERROR FILE

            CALL DBFIND('ALL')
            CALL DBNREC(NUMBER)
            TYPE 5,NUMBER
   5        FORMAT(//,1X,I6,' LINES IN ERROR FILE')

   !QUIT IF THIS WOULD BE A WASTE OF TIME

            IF(NUMBER.EQ.0) GOTO 999

   !TELL THE USER THE NUMBER OF RECORDS WITH ERRORS IN THE
   !   DATA SET IF HE WANTS IT.

            TYPE 6
   6        FORMAT(/,' WANT NUMBER OF BAD RECORDS? ' $)
            ACCEPT 7,ANSWER
   7        FORMAT(A1)
            IF(ANSWER.NE.'Y') GOTO 60

            CALL DBMAP(1,'ID','SYSID')
            CALL DBNREC(NUMBER)
            TYPE 8,NUMBER
   8        FORMAT(/,1X,I6,' RECORDS WITH ERRORS',//)

   !TELL THE USER WHAT HIS OPTIONS WILL BE

   60       TYPE 10
   10       FORMAT(' OPTIONS ARE:',/,
            1      ' D -- DELETE THE RECORD',/,
            1      ' I -- IGNORE THE RECORD',/,
            1      ' Q -- QUIT NOW',/,
            1      ' C -- CHANGE RECORD WITH 1022,',/,
            1      '      TYPE "HOST" WHEN DONE',//)

   !SET UP A RECORD POINTER

            NUMBER=1

   !THIS IS THE PROGRAM LOOP.  SELECT NEXT GROUP OF RECORDS.

   100      CALL DBSET(2)                   !POINT TO ERROR DATA SET
            CALL DBFIND('ALL')              !FIND ALL RECORDS
   FORTRAN INTERFACE ROUTINES                                   Page 2-70
   Revision 5


            CALL DBGREC($999,NUMBER)        !GET FIRST REC IN NEXT GROUP
            CALL DBVAL('ID',ID)             !READ THE ID ATTRIBUTE
            CALL DBFIND('ID','EQ',ID)       !FIND ALL RECS WITH THAT ID
            CALL DBNREC(NUMREC)             !HOW MANY WE FOUND
            NUMBER=NUMBER+NUMREC            !BUMP POINTER FOR NEXT TIME

   !TYPE THE ID AND THE DATA FROM THE ERROR DATA SET

            TYPE 11,ID
   11       FORMAT(//,' SYSID:',I6,/)
            CALL DBEXEC('PRINT NAME DATA WHY
            1        FMT "ATTR:" A " DATA:" A " REASON:" A END')

   !LOCATE THE CORRESPONDING RECORDS IN THE REAL DATA SET

            CALL DBSET(1)
            CALL DBFIND('SYSID','EQ',ID)

   !FIND OUT WHAT HE WANTS TO DO AND DO IT

            TYPE 12
   12       FORMAT(' OPTION? ' $)
            ACCEPT 7,ANSWER

            IF(ANSWER.EQ.'D') CALL DBDEL
            IF(ANSWER.EQ.'I') GOTO 100
            IF(ANSWER.EQ.'Q') GOTO 999
            IF(ANSWER.EQ.'C') CALL DBEXEC

            GOTO 100

   !HERE WHEN ALL DONE.  CLEAN UP AND EXIT.

   999      CALL DBEXEC('FILE DELETE CORREC.DMD. FILE DELETE CORREC.DMS')
            CALL DBEND

            END












                                 CHAPTER 3

                              COBOL INTERFACE



   3.1  RULES FOR USING THE COBOL INTERFACE

   Subroutine ENTERs in the PROCEDURE DIVISION of a COBOL program perform
   all  System 1022 initialization and input/output operations.  Literals
   or WORKING-STORAGE items supply data to  System  1022  data  sets  and
   receive   data   from   them.    No   FILE-CONTROL   entries   in  the
   ENVIRONMENT DIVISION or FILE SECTION entries in the DATA DIVISION  are
   required  unless the program does input or output to other than System
   1022 files.


   The System 1022 Host Language Interface makes all reasonable data type
   conversions  between  data  set  attributes and WORKING-STORAGE items.
   1022 ignores the PICTURE clause of the WORKING-STORAGE item except for
   the length of a DISPLAY-6 or DISPLAY-7 item.  System 1022 expects that
   COMPUTATIONAL items have PICTUREs no larger than S9(10),  except  that
   DOUBLE   INTEGER   items   may  have  PICTUREs  as  large  as  S9(18).
   COMPUTATIONAL-3 and DISPLAY-9 items are not  recognized,  and  produce
   runtime errors if they appear in a System subroutine ENTER.

   Conversions are required between data  set  attributes,  other  System
   values,   and  WORKING-STORAGE  items  of  different  data  types.   A
   WORKING-STORAGE item that agrees in data type requires  no  conversion
   and   is   most   efficient.   However,  1022's  automatic  data  type
   conversions give programming flexibility at little cost.


   Automatic data type conversion  is  disabled  by  setting  the  system
   variable  SYSHLCVT  to 1.  Conversion may be disabled and enabled in a
   subroutine argument list by use of the XCV. and CVT. local  operators.
   Preceding  an  attribute  identifier  with  CVT.  has  the  effect  of
   cancelling automatic conversions for the value  associated  with  that
   attribute.

   When conversion is disabled, 1022 ignores the  COBOL  data  type,  and
   instead  assumes  the  data  type  which  is  determined by the system
   variables and conventions normally used in FORTRAN.  These are  System
   variables SYSHLMODE and SYSHLDISP, subroutine keywords DISP. and BIN.,
   and the context  of  the  subroutine  being  ENTERed.   This  type  of
   operation  can  be  used  to  create runtime, variable length argument
   COBOL INTERFACE                                               Page 3-2
   Revision 5


   lists for System ENTERs.  See Chapter  2  for  a  description  of  the
   FORTRAN  conventions, and the creation of argument lists with the FIX.
   and PNT. options.

   Routines such as DBGET and DBADDR which transfer  entire  records  are
   always  affected  by  the  settings  of  SYSHLMODE and SYSHLDISP.  The
   correct COBOL record description depends on the data  types  that  are
   used to return the data into the record.  See DBGET and DBADDR.



   3.2  DATA TYPES

   Attributes in a bundled data  set  have  data  types  INTEGER,  DOUBLE
   INTEGER,  REAL,  TEXT,  and DATE.  Attributes in an unbundled data set
   have additional data types DISPLAY INTEGER, DISPLAY REAL, and  DISPLAY
   DATE.   Both types of data set may have text items of either DISPLAY-6
   or DISPLAY-7.

   Automatic conversions are done when values are supplied to or received
   from  attributes and other items of different data types.  This occurs
   in the routines DBADD, DBADDR, DBCHNG, DBFIND, DBGET,  DBSEL,  DBSRCH,
   DBSYSV,  and  DBVAL.   No  automatic  conversions  are  made  in other
   routines.

   Performance is improved by using  COBOL  WORKING-STORAGE  items  which
   match  the  types  of  their  associated  attributes.   It  is  always
   efficient to use COMP items for numeric attributes which are used  for
   computation  or  comparison  within the COBOL program.  The conversion
   that COBOL would do cancels whatever savings come from elimination  of
   the 1022 conversion.

   An item of any usage may be used  to  supply  or  receive  values  for
   attributes, if convenient.



   3.2.1  COBOL Over-Punch Characters

   COBOL over-punch characters are allowed in integer  input  data.   For
   example,  -12345  can  appear  as  1234N,  with  N  in  the last digit
   representing both the negative  sign  and  the  value  5.   Over-punch
   characters are allowed in data input files for LOAD, APPEND, TRANSACT,
   CREATE and subsequent unbundled operations, and  in  COBOL  parameters
   passed through DBxxxx calls.

   1022 recognizes the following over-punch characters:

   COBOL INTERFACE                                               Page 3-3
   Revision 5


                        COBOL OVER-PUNCH CHARACTERS

             VALUE CHARACTER  VALUE CHARACTER  VALUE CHARACTER
             _____ _________  _____ _________  _____ _________

             1     A          -1    J          +0    ?
             2     B          -2    K          +0    [
             3     C          -3    L          +0    {
             4     D          -4    M          +0    !
             5     E          -5    N          -0    :
             6     F          -6    O          -0    ]
             7     G          -7    P          -0    }
             8     H          -8    Q              
             9     I          -9    R


   The user can control 1022's processing of COBOL over-punch  characters
   by  setting  the  system  variable  SYSCBLSIGN.   These  are the three
   possible values of SYSCBLSIGN:

        VALUE               MEANING
        _____               _______

          0        Over-punch characters are disallowed.

          1        Over-punch characters are  allowed  on  integer  input
                   data in data files (default).

          2        Over-punch   characters   are    allowed    as    when
                   SYSCBLSIGN=1,  in  integers typed as input to commands
                   like ADD and  ACCEPT,  and  as  arguments  to  integer
                   conversion functions like INT("123N").





   3.2.2  INTEGER Attributes

   A COMPUTATIONAL item is the most natural and efficient way  to  supply
   and receive integer attribute values.


   A DISPLAY item that receives an integer attribute value must be  large
   enough to hold the significant digits plus a sign character if needed.
   A PICTURE of 9(12) suffices.  1022 places the integer attribute  value
   into  the  item  right justified, with a leading "-" sign if negative,
   and  space  filled  on  the  left.   The  rightmost   digit   is   not
   over-punched,  even if the PICTURE for the item contains an S.  A zero
   value is received as the single digit 0.

   A DISPLAY item that  supplies  an  integer  attribute  value  contains
   optional  leading  spaces,  an  optional  preceding  "+"  or "-" sign,
   digits, and possibly trailing spaces.  Over-punched values (where  the
   PICTURE  contains  an  S)  are  legal  for  supplying values.  An item
   containing only spaces evaluates to the number 0.
   COBOL INTERFACE                                               Page 3-4
   Revision 5


   A COMPUTATIONAL item may supply or receive an integer attribute value.
   1022  truncates the COMP value to the integer next closer to 0, if not
   already an integer, before using it or storing it into the COMP item.


   In summary, WORKING-STORAGE items for integer attributes should be  in
   the forms:

        ITEM COMP PIC S9(10).              /Best and most efficient/

        ITEM PIC 9(12).

        ITEM DISPLAY-7 PIC 9(12).




   3.2.3  REAL Attributes

   A COMPUTATIONAL-1 item is the most natural and efficient way to supply
   and receive a real attribute value.


   A DISPLAY item that receives a real  attribute  value  must  be  large
   enough  to  hold  the  value  in  standard  or scientific notation.  A
   PICTURE of 9(15)  is  always  large  enough.   1022  places  the  real
   attribute value into the item right justified, with a leading "-" sign
   if negative, and space filled on the left.  A real  attribute  with  a
   zero value is received into the item as .00000000 .

   A DISPLAY item that supplies a real attribute value contains  optional
   leading  spaces,  an  optional  leading  "+"  or "-" sign, a number in
   standard or scientific notation, and  possibly  trailing  spaces.   An
   item containing only spaces evaluates to the number 0.0 .


   Any COMPUTATIONAL-1 item may supply or receive a real attribute value,
   with 1022 performing conversion and truncation if necessary.
   In summary, WORKING-STORAGE items for real attributes should be in the
   forms:

        ITEM COMP-1.                       /Best and most efficient/

        ITEM PIC 9(15).

        ITEM DISPLAY-7 PIC 9(15).
   COBOL INTERFACE                                               Page 3-5
   Revision 5


   3.2.4  TEXT Attributes

   Text attributes are DISPLAY-6 or DISPLAY-7 depending on  the  type  of
   description file used to LOAD or CREATE the data set.

   DISPLAY-6 items may supply  and  receive  data  from  text  attributes
   stored as DISPLAY-7, but the DISPLAY-6 character set includes no lower
   case characters.  Mixed case text attributes are  converted  to  upper
   case when received in DISPLAY-6 items.

   A DISPLAY item longer than a text  attribute  receives  the  attribute
   value  space  filled on the right, to match the length of the item.  A
   DISPLAY item shorter than  a  text  attribute  receives  the  leftmost
   characters of the item.

   A DISPLAY item longer than a text  attribute  supplies  the  attribute
   value  from  its  leftmost  characters.  A DISPLAY item shorter than a
   text attribute supplies the attribute value space filled on the  right
   to match the length of the attribute.


   In summary, a WORKING-STORAGE item for a text attribute should have  a
   PICTURE  as  long  as  the attribute length.  Its most efficient USAGE
   clause matches the  storage  form  (DISPLAY-7  or  DISPLAY-6)  of  the
   attribute.



   3.2.5  DATE Attributes

   Date attributes are stored in bundled  data  sets  in  binary  integer
   form,  representing the number of days since the date January 1, 1800.
   A COMP item supplies and receives a date value in this binary form.

   The DBNDAT and DBDATN subroutines convert a System COMPUTATIONAL  date
   to and from the corresponding month, day, and year.


   A DISPLAY item receives a date attribute value in the form YYYYMMDD if
   its  PICTURE  is 9(8) or larger, and in the form YYMMDD if its PICTURE
   is 9(6) or 9(7) and the date is in the range 1900 to 1999.  A  PICTURE
   smaller than 9(6) produces a runtime error.  The date item is received
   right justified and space filled on the left.  For example,  the  date
   December 31, 1979 is received as 19791231 in a PICTURE 9(8) or larger,
   and as 791231 in a PICTURE 9(6) or 9(7).

   A DISPLAY item supplies a date attribute value in  any  of  the  forms
   that  interactive  System  1022  recognizes  for  input.  Refer to the
   System 1022 User's Reference Manual.  For example, 12/31/79, 12-31-79,
   791231,  and DECEMBER 31, 1979 are acceptable DISPLAY date values.  An
   invalid date produces a runtime warning message, and supplies the null
   date  January  1,  1800.  A date of only space characters evaluates to
   January 1, 1800.  An item receives this date as zero if the  receiving
   item is COMP, or spaces if the receiving item is DISPLAY.
   COBOL INTERFACE                                               Page 3-6
   Revision 5


   In summary, WORKING-STORAGE items for date attributes have the forms:

        ITEM COMP PIC S9(10)               /Most efficient/

        ITEM PIC 9(6)                      /Or larger/

        ITEM DISPLAY-7 PIC 9(6)            /Or larger/



   3.3  SUBROUTINE ARGUMENTS

   Keywords are supplied as DISPLAY-7 values.  For example,  the  NOCLOSE
   option  in  the  DBOPEN  routine is selected by including the argument
   keyword "NOCLOSE":

        ENTER MACRO DBOPEN USING "NOCLOSE","TEST".

   Attribute identifiers are either the name,  abbreviation,  or  integer
   identification number of the attribute.  The name or abbreviation is a
   literal or DISPLAY-7 item.  The attribute number is a literal or  COMP
   item.   The  program  gains  efficiency  by using the attribute number
   rather than the name;  this avoids a runtime table lookup, but this is
   significant  only in production programs and often executed loops.  To
   preserve data independence  in  a  program  using  attribute  numbers,
   obtain  the  number  for  any  attribute with the DBINFO routine.  For
   example, assume that AGE is the third attribute in a  data  set.   The
   following statements are equivalent:

        ENTER MACRO DBVAL USING 3, EMPL-AGE.
        ENTER MACRO DBVAL USING "AGE", EMPL-AGE.
        ENTER MACRO DBVAL USING EMPL-AGE-ID, EMPL-AGE.
        ENTER MACRO DBVAL USING EMPL-AGE-NAME, EMPL-AGE.

             Where EMPL-AGE-ID contains the COMP value 3,
                   EMPL-AGE-NAME contains the DISPLAY-7 value AGE.

   Rather than use the literal 3 in the first ENTER, it is correct to use
   the  attribute  name as a literal, or to use an item EMPL-AGE-ID which
   supplies the attribute number as retrieved from a call to DBINFO.  The
   program  will  not  be  invalid if AGE is in a different position in a
   future version of  the  data  set.   The  fourth  ENTER  provides  the
   attribute  name  as text in a DISPLAY-7 item, EMPL-AGE-NAME.  It is no
   more efficient than the second form, but may be convenient in  general
   applications.

   The following rules apply to text values supplied in DISPLAY items:

        a) Values are left justified within the item.

        b) File-descriptors are terminated by the first blank, or by  the
           end of the item.

   COBOL INTERFACE                                               Page 3-7
   Revision 5


           Example:

               ENTER MACRO DBOPEN USING "PS:<SMITH>TEST".

                    is equivalent to

               A WORKING-STORAGE section with the following entry:

               01 FILE-NAME-VALUE DISPLAY-7  PIC X(30)
                                           VALUE "PS:<SMITH>TEST".

                    And the statement:

               ENTER MACRO DBOPEN USING FILE-NAME-VALUE.



   3.3.1  The ERRT.  Option

   When DBERR error handling is in effect, the argument list for all 1022
   host   language   ENTERs   in  which  an  error  is  possible,  except
   initialization routines and DBRETN, may begin with:

        "ERRT.",proc-name-1,...

   Control transfers to proc-name-1 if an error  occurs  while  executing
   this  statement.   System 1022 performs all error actions specified to
   DBERR, for example, error-message type out or  suppression,  but  does
   not execute the central error routine which may have been specified.



   3.4  SPECIAL RESTRICTIONS


   The program should avoid writing records which contain new keys to  an
   ISAM  file, because the top level index block may be split, and System
   1022 will not function properly from that point on.  System 1022  does
   not  support  implied decimals.  See your 1022 data base administrator
   for other restrictions.



   3.5  INITIALIZING COBOL -- DBCBL, DBC68, DBC74

   At TOPS-20 sites, the following ENTER is made before any other  System
   routine is used:

        ENTER MACRO DBCBL.

   At TOPS-10 sites, any or all of  the  following  may  be  required  to
   initialize COBOL programs:
   COBOL INTERFACE                                               Page 3-8
   Revision 5


        ENTER MACRO DBCBL.

        ENTER MACRO DBC68.

        ENTER MACRO DBC74.

   TOPS-10 users  should  consult  with  their  System  Administrator  to
   determine which of these ENTERs to use.



   3.6  TERMINATING SYSTEM 1022 PROCESSING -- DBEND

   Terminate System processing with an ENTER to DBEND:

        ENTER MACRO DBEND.

   Use this routine after all data base  operations  are  completed.   It
   closes all data sets and performs cleanup operations such as releasing
   memory.  After an ENTER to DBEND, another ENTER to DBCBL restarts 1022
   for further use.



   3.7  DATA SET SELECTION ROUTINES

   These routines select System 1022 data sets for later operations.  The
   routines parallel the commands described in "Choosing the Data set" in
   the User's Reference Manual.



   3.7.1  The OPEN Command -- DBOPEN

   The DBOPEN routine connects the program to one or more data sets.  The
   form is:
|  
|       ENTER DBOPEN USING ["NOCLOSE",] [DS1,"IN",] IDS1
|  
|                                          { "READONLY" }
|         ["PASSWORD",password] [,"ACCESS" {            }] [,"AS",alias]
|                                          { "RO"       }
|  
|            [ [,DS2,"IN"],IDS2... ]

   Each DSn is a data set name and each IDSn is a  file-descriptor  which
   names  a  data  set  file.   All  of  the  named  data sets are opened
   simultaneously, for later access using the DBSET routine.   Previously
   open  data  sets  are  closed unless the NOCLOSE keyword is used.  All
   data sets in a file are opened when no data set name is provided in an
   "IN" clause of an OPEN command.

   Example:    ENTER DBOPEN USING "DSB", "IN", "TEST", "INVNT"
   COBOL INTERFACE                                               Page 3-9
   Revision 5


        We assume that the file TEST.DMS contains the two data  sets  DSA
        and DSB, and that the file INVNT.DMS contains the data sets PARTS
        and ORDER.  The above call opens the data sets  DSB,  PARTS,  and
        ORDER  at  the  same time.  Each data set is assigned a "data set
        number" starting from 1 in the order that it  is  opened.   Thus,
        DSB  is  data set #1, PARTS is data set #2, and ORDER is data set
        #3.  These numbers can be used in DBSET  and  other  routines  to
        select the current data set from among the open data sets.

   If the first argument to DBOPEN is the  keyword  "NOCLOSE",  then  any
   data sets already open will remain open.  The new data set numbers are
   assigned starting one greater than the highest data set number already
   assigned,  except  NOCLOSE  first  assigns  any  data set numbers left
   available by data sets that were closed (see DBCLOS).

   Each DSn is a DISPLAY-7 string containing the data set name as used in
   the interactive System.

   Each IDSn file-descriptor is a DISPLAY-7 string naming the file,  like
   a  file-descriptor in the interactive System.  Parts of the descriptor
   may be omitted, and default to device DSK and the current disk area.

|  If a password is required to open  a  data  set,  use  the  "PASSWORD"
|  clause in the call, following the file-descriptor to which it refers:
|  
|       For example:
|  
|       ENTER DBOPEN USING "ACCTS","PASSWORD","ABC","INVNT"
|  
|  This opens both the data set ACCTS.DMS, for which the password ABC  is
|  required,  and  the  unprotected  data  set  INVNT.DMS.   The  keyword
|  PASSWORD may be abbreviated PASSW.
|  
|  You can open a data set in readonly  mode  with  the  ACCESS  READONLY
|  clause of the DBOPEN call.
|  
|  For example:
|  
|       ENTER DBOPEN USING "ACCTS","PASSWORD","ABC","ACCESS","READONLY"
|  
|  This opens the password-protected data set  ACCTS  in  readonly  mode.
|  The keyword READONLY may be abbreviated RO.
|  
|  As in stand-alone 1022, you can assign an alias to a data set when you
|  open it.  An alias may be up to 25 characters long.  It may not be the
|  same as the internal name  or  alias  of  any  other  open  data  set,
|  including any named in the DBOPEN call.
|  
|  For example:
|  
|       ENTER DBOPEN USING "PARTS","IN","INVNT","AS","OLD"
|  
|  This opens the data set PARTS in the file  INVNT.DMS  with  the  alias
|  OLD.
   COBOL INTERFACE                                              Page 3-10
   Revision 5


   3.7.2  The CLOSE Command -- DBCLOS

   This ENTER is:

        ENTER MACRO DBCLOS.

   This routine parallels the CLOSE command and closes the  current  data
   set.   A  single, open data set is always the current one.  Use DBSET,
   among other routines, to establish the current  data  set  from  among
   many  open  data  sets.   When  a data set is closed, its contents are
   unavailable for retrieval or modification until it  is  opened  again.
   Also, its data set number is available for reassignment to a different
   data set on a later DBOPEN with the NOCLOSE option.

   The lowest numbered data set remaining open becomes the  current  data
   set after a DBCLOS.



   3.7.3  The DBSET Command -- DBSET

   At any instant, one data set is the current one.  The current data set
   is  initially  determined by the actions of DBOPEN, DBCLOS, and DBMAP.
   Change the current data set with DBSET:

        ENTER MACRO DBSET USING SET-NAME.

   where SET-NAME is either:

     1) the number of the data set, either a constant or a COMP item.

   or

     2) the internal name  of  the  data  set,  either  a  literal  or  a
        display-7 item.

   A data set number is obtained with the routines DBNSET or  DBCSET,  or
|  it is the number determined by the order of opening the data sets.  If
|  no data sets are open, DBCSET and DBNSET return a zero.

   Routines other than DBSET can change the current data set.   See  also
   DBMAP and DBCLOS.

   Consider the following program fragment as an example for using DBSET,
   DBCLOS, and DBOPEN (NOCLOSE).  We assume the data set files introduced
   in the DBOPEN description.


      ENTER MACRO DBOPEN USING "DSB", "IN", "TEST", "INVNT".

      Data set #1, DSB, is now the current data set.


      ENTER MACRO DBSET USING "ORDER".
   COBOL INTERFACE                                              Page 3-11
   Revision 5


      ORDER, data set #3, is now the current data set.


      MOVE 2 TO COMP-ITEM.
      ENTER MACRO DBSET USING COMP-ITEM.

      Data set #2, PARTS, is now the current data set.


      ENTER MACRO DBCLOS.

      Data set #1, DSB, is now the current data set.
      There is no longer a data set #2.


      ENTER MACRO DBOPEN USING "NOCLOSE", "DSA", "IN", "TEST".

      DSA is opened on the first free data set number, #2,
      and becomes the current data set.




   3.7.4  Data Set Numbers -- DBCSET And DBNSET

   The routines DBCSET and DBNSET return the number of the  current  data
   set and the total number of data sets open.

   The DBCSET routine returns the data set number of the current data set
   into a COMP item.  The ENTER is:

        ENTER MACRO DBCSET USING SET-NUMBER.

   The DBNSET routine returns the total number of open data sets  into  a
   COMP item.  The ENTER is:

        ENTER MACRO DBNSET USING NUM-DATA SETS.



   3.8  DATA SET INQUIRY ROUTINES

   These  routines  parallel  the  commands  of  the  interactive  System
   described in Chapter 4 of the System 1022 User's Reference Manual.



   3.8.1  The FIND Command -- DBFIND

   The DBFIND routine parallels the  FIND  command  and  selects  records
   using criteria on KEYED attributes.  The ENTER is:

   COBOL INTERFACE                                              Page 3-12
   Revision 5


        ENTER MACRO DBFIND USING selector-group

                     [, logical, selector-group] ...  .


   Selector-Group
   ______________

   A selector-group identifies a group of records and may be any  of  the
   following:

   1.  A series of 3 arguments of the form:

             ATTR-ID, RELATIONAL, VALUE

       Where:

       a) ATTR-ID is an attribute identifier or "SYSID".   The  attribute
          identifier  may be either the attribute name or abbreviation in
          DISPLAY-7, or the COMP attribute number returned by the  DBINFO
          routine.   Use of the number is more efficient because it saves
          a table lookup.

       b) RELATIONAL is a relational identifier, either  DISPLAY-7  or  a
          COMP numeric code as follows:

              DISPLAY-7 Form   Code

                  "EQ"           1
                  "NE"           2
                  "LT"           3
                  "LE"           4
                  "GT"           5
                  "GE"           6
                  "BET"          7
                  "NBET"         8
                  "CT"           9
                  "NCT"         10
                  "BEG"         11
                  "NBEG"        12

          As with attribute identifiers, using the codes  saves  a  table
          lookup.

       c) VALUE is the value of the attribute.  If either "BET" or "NBET"
          is used, then two values follow in the argument list.

          Example:  ENTER MACRO DBFIND USING "AGE","BET",25,35.

   2.  The DISPLAY-7 string "ALL", to select all records in the data set.
       If this is used, it is the only argument to DBFIND.

   3.  The DISPLAY-7 string "LAST" to  represent  the  records  currently
       selected when the ENTER is made.
   COBOL INTERFACE                                              Page 3-13
   Revision 5


   4.  The DISPLAY-7 string "FILE" followed in the  next  argument  by  a
       file-descriptor  naming  a pointer file.  The pointer file locates
       records previously found and remembered with an ENTER to DBSAVE.

   5.  The DISPLAY-7 string "NOT", followed  by  anything  except  "ALL".
       This  selects  all  records  other than the ones determined by the
       following selector group.  For example:

                  "NOT","LAST"
                  "NOT","FILE","GRP1"
                  "NOT","AGE","EQ",30



   Logical
   _______

   The logical is either a DISPLAY-7 string or a COMP code as follows:

                  TEXT        Code

                  "AND"         1
                  "OR"          2
                  "EQV"         3
                  "XOR"         4


   The selection criteria are processed from left to right without regard
   to the precedence of logical operators.  For example:

        ENTER MACRO DBFIND
        USING "LAST","OR","AGE","EQ",30,"AND","SEX","EQ","M".

   is evaluated like the interactive command:

        FIND (LAST OR AGE EQ 30) AND SEX EQ M.

   All logical operators and comparison relationals  must  appear  in  an
   ENTER to DBFIND, unlike in an equivalent FIND command.


   The following are examples of  interactive  FIND  commands  and  their
   corresponding ENTERs using the COBOL interface:

        FIND ALL.

        ENTER MACRO DBFIND USING "ALL".

   COBOL INTERFACE                                              Page 3-14
   Revision 5


     ------

        FIND NAME JOHN.

        ENTER MACRO DBFIND USING "NAME","EQ","JOHN".
               or
        ENTER MACRO DBFIND USING 3,1,"JOHN".   (If Name is attribute #3)

     ------

        FIND LAST AND SEX F.

        ENTER MACRO DBFIND USING "LAST","AND","SEX","EQ","F".



   3.8.1.1  Suppression Of Trailing Spaces


   Substring matching with the relational operators  CT,  NCT,  BEG,  and
   NBEG  is  performed using the exact value specified in the argument to
   the ENTER.  For example,

        ENTER MACRO DBFIND USING "SURNAME", "CT", "VON".

   selects records in which the attribute SURNAME contains the string VON
   anywhere within it.

   Suppose that the matched value is moved into  a  WORKING-STORAGE  item
   MATCH-VAL of PIC X(20).  Then,

        MOVE "VON" TO MATCH-VAL.
        ENTER MACRO DBFIND USING "STS.","SURNAME","CT",MATCH-VAL.
                                  or
        ENTER MACRO DBFIND USING "SURNAME","CT",MATCH-VAL.

   will select records in which the attribute SURNAME contains the string
   VON  and  will  suppress  any trailing spaces because when the keyword
   "STS." precedes the attribute identifier, it causes matching  only  on
   the  leftmost  significant characters and embedded spaces.  (Note that
   STS.  suppresses only trailing spaces  and  not  leading  or  embedded
   ones.) In selection conditions containing the relational operators CT,
   NCT, BEG, and NBEG,  STS.   is  the  default  and  thus  need  not  be
   expressed  to suppress trailing spaces.  STS.  has no practical effect
   on other operators, though  it  may  be  used  in  any  routine  which
   processes selection conditions:  DBFIND, DBSEARCH, and DBSEL.

   To include trailing  spaces,  the  keyword  "ITS."  must  precede  the
   attribute identifier in a selection condition containing CT, NCT, BEG,
   or NBEG.  Thus,

        ENTER MACRO DBFIND USING "ITS.","SURNAME","CT","VON_".

   will select records in which the attribute SURNAME contains the string
   COBOL INTERFACE                                              Page 3-15
   Revision 5


   VON  followed by a space (which the STS.  default would otherwise have
   overridden).  ITS.  is the default in selection conditions  containing
   relative operators other than CT, NCT, BEG, and NBEG.



   3.8.1.2  Advanced DBFIND Features

   Unlike the interactive 1022 FIND command, the normal ENTER  to  DBFIND
   evaluates   expressions  containing  logical  operators  in  a  strict
   left-to-right order of precedence.  Thus, while

        FIND SEX M OR SEX F AND RH NEG

   first selects the records of those females who  are  Rh  negative  and
   then combines these with the records of all males,

        ENTER MACRO DBFIND USING "SEX","EQ","M","OR","SEX","EQ","F",

           "AND","RH","EQ","NEG".

   first selects the records of all males, then combines these  with  the
   records  of all females, and then forms a final selection set of those
   males and females who are Rh negative.

   Although parenthetical expressions are not allowed with DBFIND, it  is
   still  possible  to  replicate  the  order  of  precedence followed in
   interactive 1022 by using the SAV.  and REF.  features.

      "SAV.",n  Is used after a selection expression to temporarily  save
                pointers to the records found thus far in the evaluation,
                under the reference number n.

      "REF.",n  Is used instead of a selection  expression  to  refer  to
|               records  previously saved under reference number n.  When
|               REF.,n is referenced, the corresponding SAV.,n ceases  to
|               exist.   Thus,  REF.,n  may  only be used to refer to the
|               corresponding SAV.,n once per DBFIND command.

   The ENTER is:

        ENTER MACRO DBFIND USING <expression>,"SAV.",n,

           <expression>,logical operator,"REF.",n.

|  where  n  is  an  integer  less  than  or  equal   to   20,   assigned
   "consecutively"  by  the  user  program  starting  at 1.  That is, the
   lowest integer not already in use as a reference number is assigned as
   n.   After  the  "REF.",n  clause  appears,  its  n  can be reused for
   efficiency if the data that it represents is no longer needed.

   The groups produced by "SAV." are available only in the same ENTER  to
   DBFIND.   Using  "SAV."  in  a single DBFIND command is more efficient
   than several DBFIND ENTERs, each using a different DBSAVE.
   COBOL INTERFACE                                              Page 3-16
   Revision 5


   The following are  examples  of  complex  DBFIND  commands  and  their
   corresponding ENTERs using the "SAV." and "REF." features:

        FIND SEX M OR (SEX F AND RH NEG)

        ENTER MACRO DBFIND USING "SEX","EQ","M","SAV.",1,

           "SEX","EQ","F","AND","RH","EQ","NEG","REF.",1.

   _____

        FIND (TYPE A OR TYPE B) AND RH POS

        ENTER MACRO DBFIND USING "TYPE","EQ","A","OR","TYPE","EQ","B",

           "SAV.",1,"RH","EQ","POS","AND","REF.",1.



   3.8.2  The SAVE Command -- DBSAVE

   The DBSAVE routine parallels the interactive SAVE command and writes a
   System  readable disk file of the retrieval pointers for the currently
   selected group of records.  The ENTER is:

        ENTER MACRO DBSAVE USING SAVE-FILE.

   where SAVE-FILE is a file-descriptor, either a  literal  or  DISPLAY-7
   item.   If  no  extension  is  specified, the default extension DMV is
   used.  Later, the file-descriptor can be referenced in the FILE clause
   of an ENTER to DBFIND.

   Examples:

                ENTER MACRO DBSAVE USING "ABC".

        SYSIDs of the currently selected records are saved  on  the  file
        ABC.DMV.

                ENTER MACRO DBSAVE USING "ABCDEF.EXT".

        SYSIDs of the currently selected records are saved  on  the  file
        ABCDEF.EXT.

   Files saved apply only to the data sets from which they are generated.
   An  error  occurs  if  the  program attempts to use a DBSAVE file on a
   different data set.
   COBOL INTERFACE                                              Page 3-17
   Revision 5


   3.8.3  The SEARCH Command -- DBSRCH

   The DBSRCH routine searches the data set in the  same  manner  as  the
   interactive SEARCH command.  The ENTER has the format:

        ENTER MACRO DBSRCH USING selector-group

                     [, logical, selector-group ]...  .

   Where:

   Selector-group is:  ["ATTR.",] ATTR-ID, RELATIONAL, VALUE

   The optional keyword "ATTR." tells 1022 to evaluate the value in VALUE
   as an attribute identifier.

   In the following example, MONTH1 and  MONTH2  are  attributes  in  the
   current  data  set.  System 1022 searches for all records in which the
   value of MONTH1 equals the value of MONTH2.

        ENTER MACRO DBSRCH USING "ATTR.","MONTH1","EQ","MONTH2".


   DBSRCH operates on any  attributes,  not  just  keyed  ones.   "SAV.",
   "REF.", "ALL", and "FILE" are not available.

   Usually, use DBSEL in place of DBSRCH whenever it  is  followed  by  a
   procedure which retrieves the records in the selection group.



   3.8.4  The SELECT Command -- DBSEL

   The DBSEL routine parallels the SELECT command and  defers  processing
   of SEARCH selection criteria until a later procedure reads through the
   records.  Using DBSEL avoids doing an immediate search (as in  DBSRCH)
   and  is  followed  by  a  second record retrieval procedure.  DBSEL is
   entered using the same argument list as DBSRCH.  The  "ATTR."  keyword
   has  the  same  function  as  in  DBSRCH.   (See The SEARCH Command --
   DBSRCH, above.)

   Any later  routine  which  selects  a  record  respects  the  criteria
   specified  in  DBSEL.   These  routines include DBSORT, DBCHNG, DBDEL,
   DBGREC, DBGET, DBMAP, and DBSRCH.
   COBOL INTERFACE                                              Page 3-18
   Revision 5


   3.8.5  The MAP Command -- DBMAP

   The DBMAP routine parallels the MAP command and locates records  in  a
   second  data set using common attribute values shared with the records
   in the current selection group.  Execution of DBMAP leaves the  second
   data set as the current data set.  The selection group is unchanged in
   the data set from which the DBMAP is done.  The ENTER is:

        ENTER MACRO DBMAP USING ["BY", METHOD,] ["LOGICAL", LOG-NAME,]

                          SET-ID, SOURCE-ATTR-1 [,DEST-ATTR-1]

                        [ ,"AND", SOURCE-ATTR-2 [,DEST-ATTR-2] ]...  . 

   Where:

      METHOD         Is either "KEY" or "GETREC".  It specifies that  MAP
                     locate  records  using  the  key  table  (KEY) or by
                     examining one record at a  time  (GETREC).   Without
                     this  clause,  1022 usually chooses the best method.
                     Specifying    the    method    sometimes    improves
                     performance.

      LOG-NAME       Specifies how the records selected as  a  result  of
                     this  MAP  command  are  combined  with  the records
                     previously selected in  the  destination  data  set.
                     "AND"  forms a selection group of records that share
                     values with the first data set and  were  previously
                                                    ___
                     selected  in  the  second  data  set.   "OR" selects
                     records that share values with the first data set or
                                                                       __
                     were  previously  selected  in  the second data set.
                     "CLEAR", also the default if no  LOGICAL  clause  is
                     specified,  ignores  the previous selection group in
                     the second data set.

      SET-ID         Is either  the  data  set  name  or  number  of  the
                     destination  data  set.   Using  the  data  set name
                     selects the named data set of lowest number if  more
                     than one open data set has that name.

      SOURCE-ATTR-1  Is an attribute in the source data set to be used in
                     the mapping, specified by its attribute number or by
                     its DISPLAY-7 name.  The keyword "SYSID" may also be
                     used.

      DEST-ATTR-1    Is the attribute in the destination data  set  which
                     is compared to SOURCE-ATTR-1.  It need not appear if
                     it is the same name as SOURCE-ATTR-1.  If  attribute
                     numbers rather than names are used, DEST-ATTR-1 must
                     be specified.  The attribute in the destination data
                     set must be KEYed.  It may be the quantity "SYSID".

      "AND"          More than one attribute in the source data  set  can
                     be  used  to  select records in the destination data
   COBOL INTERFACE                                              Page 3-19
   Revision 5


                     set.  "AND" introduces additional attributes  to  be
                     used  in the mapping.  Any records that are selected
                     match on all the specified source attributes.

      SOURCE-ATTR-2  Is the second source attribute which is compared.

      DEST-ATTR-2    Is the attribute in the destination data  set  which
                     is  compared to SOURCE-ATTR-2.  It may be omitted if
                     it is the same name as SOURCE-ATTR-2.  If  attribute
                     numbers rather than names are used, DEST-ATTR-2 must
                     be specified.

   Examples:

        ENTER MACRO DBMAP USING 2, "NAME".

             Map to data set 2 using the values of NAME in both data sets
             for comparisons.

        ENTER MACRO DBMAP USING "ORDER", "NAME", "NEWNAME".

             Map to the ORDER data set comparing NAME in the source  data
             set to NEWNAME in the destination data set.

        ENTER MACRO DBMAP USING "LOGICAL", "OR", 2, "AGE", "NEWAGE".

             Map to data set 2 comparing the values of AGE in the  source
             data set to NEWAGE in the destination data set.  The records
             selected are added (ORed) to the previous selection group in
             the destination data set.

        ENTER MACRO DBMAP USING 2, "NAME", "NEWNAME",
             "AND", "AGE", "NEWAGE".

             Select records in data set 2 which have the same values  for
             both  NEWNAME  and NEWAGE as in the source data set for NAME
             and AGE.  This does a different selection than selecting  by
             just NAME and then ANDing or ORing records selected by AGE.
   COBOL INTERFACE                                              Page 3-20
   Revision 5


   3.8.5.1  Example Of DBMAP

   Assume we have two data sets, P.DMS and C.DMS, which  are  parent  and
   child  files.   We want to find all parents between the ages of 35 and
   40 and print information on their children.  The files are  linked  by
   the parent's social security number, called SSN in the P file and PSSN
   in the C file.

            ENTER MACRO DBCBL.
            ENTER MACRO DBOPEN USING "P","C".
            ENTER MACRO DBFIND USING "AGE","BET",35,40.
   LOOP1.
            ENTER MACRO DBSET USING 1.
            ENTER MACRO DBGREC USING NOMORECS.
            ENTER MACRO DBMAP USING 2, "SSN", "PSSN".
   LOOP2.
            ENTER MACRO DBGREC USING LOOP1.
            .
            .  (WRITE OUT INFORMATION ON THE CHILD RECORDS)
            .
            GO TO LOOP2.
   NOMORECS.



   3.8.6  The Current Number Of Records -- DBNREC

   The DBNREC routine returns the number of  records  currently  selected
   after a DBFIND, DBSRCH, or DBMAP.  The ENTER is:

        ENTER MACRO DBNREC USING REC-COUNT.

   where the COMP item REC-COUNT is returned as the number of records  in
   the  current  selection group.  The value excludes any records removed
   from the selection group by the DBDROP routine or DBSEL conditions.



   3.8.6.0.1  The GETREC Command -- DBGREC

   The DBGREC routine parallels the interactive GETREC command  to  enter
   local mode for single record processing.  The ENTER is:

|       ENTER MACRO DBGREC USING OUT-OF-RECS [,"$LOCK"] [,SEQ-NUM].
|  
|  ENTER is given for the DBGREC routine after  a  group  of  records  is
|  selected  by  the DBFIND, DBSRCH, DBSEL, or DBMAP routine.  The DBGREC
   routine makes the next record in the  selection  group  available  for
   individual processing.

   An ENTER to DBGREC places the program into local mode.  While in local
   mode,  DBDEL  or  DBCHNG  affects  only the record last retrieved with
   DBGREC.
   COBOL INTERFACE                                              Page 3-21
   Revision 5


   Control  transfers  to  paragraph   OUT-OF-RECS   when   the   program
   sequentially  exhausts  all  the  currently selected records.  When an
   ENTER to DBGREC branches to OUT-OF-RECS, the program  is  placed  into
   global  mode  as if an ENTER to DBSREC had been made.  The program can
   resume sequential processing of  this  record  group  from  the  first
   record with further ENTERs to DBGREC.

   DBGREC does not transfer attribute values.   Obtain  attribute  values
   for  the  currently  selected  record with the DBVAL routine described
   below.

   Example:

           ENTER MACRO DBGREC USING END-EMPLOYEE-RECS.

   The next record is selected for further processing.  Control transfers
   to  paragraph  END-EMPLOYEE-RECS when the program exhausts all records
   in the selection group.

|  The optional $LOCK argument to DBGREC locks  the  record  so  that  no
|  other  user  can  update  it.  The record is unlocked when you get the
|  next record, return to global mode,  close  the  data  set,  drop  the
|  record,  delete  the  record,  or  give  an  ENTER  MACRO DBGREC USING
|  "OFF","RECORD." The $LOCK argument works only for data sets  that  are
|  ENQ and RECLOCK.
|  
|  The optional third argument to DBGREC selects the nth record from  the
   beginning  of  the  current  group,  where  n is the value of SEQ-NUM.
   Further ENTERs  without  the  optional  argument  continue  from  that
   record.  If no nth record exists, control transfers to OUT-OF-RECS.



   3.8.7  The DROP Command -- DBDROP

   The DBDROP routine parallels the DROP command  and  removes  a  single
   record  from  the  current  selection group, after an ENTER to DBGREC.
   The ENTER is:

        ENTER MACRO DBDROP.

   The record is not deleted from the data set;  it is only dropped  from
   the current selection group.

   The DBDROP routine narrows down a selection group with  criteria  that
   would  be  too  clumsy for the DBFIND or DBSRCH routines.  The program
   examines each record and drops undesired ones.
   COBOL INTERFACE                                              Page 3-22
   Revision 5


   3.8.8  The LET Command -- DBVAL

   The DBVAL routine parallels the LET command  and  retrieves  attribute
   values   from   the   currently   selected   record   into  individual
   WORKING-STORAGE items in the program.  The ENTER is:

        ENTER MACRO DBVAL USING ATTR-1,ITEM-1 [,ATTR-2,ITEM-2]...  .

   Where:

        ATTR-1    Is  an  attribute  identifier,  either  the   DISPLAY-7
                  attribute name or abbreviation, or the COMP code.

        ITEM-1    Is a WORKING-STORAGE item where DBVAL puts the value of
                  the attribute.

   The program must be in local mode to ENTER DBVAL;  an ENTER to  DBGREC
   must precede the ENTER to DBVAL.

   Example:  ENTER MACRO DBVAL USING "NAME",NAME-VAL,"AGE",AGE-VAL.

        The value for attribute NAME is placed in  NAME-VAL.   The  value
        for  attribute  AGE  is  placed in AGE-VAL.  NAME-VAL and AGE-VAL
        might be declared as follows in the WORKING-STORAGE SECTION:

        77 NAME-VAL DISPLAY-7 PIC X(20).
        77 AGE-VAL COMP PIC 9(2).

        If the declaration for the data item AGE-VAL were:

        77 AGE-VAL DISPLAY-7 PIC X(10).

        then  DBVAL  would  return  the  value  of  attribute  AGE  right
        justified in AGE-VAL as DISPLAY-7 text.




   3.8.9  Standard Record Format

   DBGET and DBADDR work with entire COBOL records supplied  or  received
   in  Standard  Record  Format.   A  value is "passed" when it is either
   supplied or received in the context of the discussion.

   The system variables SYSHLMODE and SYSHLDISP determine how values  are
   passed  to  the  COBOL  record,  and  so  determine  the  exact record
   description which  is  necessary.   They  affect  the  record  because
   display numerics are longer than binary numerics, and DISPLAY-7 values
   are packed into words differently than DISPLAY-6 values.  5 characters
   of  a  DISPLAY-7 value fill a word;  6 characters of a DISPLAY-6 value
   fill a word.

   The way that values are passed to the COBOL record is specified by the
   following values of SYSHLDISP and SYSHLMODE:
   COBOL INTERFACE                                              Page 3-23
   Revision 5


        1. SYSHLDISP

           This System variable specifies the  display  type  of  display
           attribute values.

           A. A  value  of  zero  (the  default)  directs  that   display
              attribute values are passed as DISPLAY-7.

           B. A value of +1 directs that display  values  are  passed  as
              DISPLAY-6.

        2. SYSHLMODE

           SYSHLMODE specifies whether numeric attribute values are to be
           passed in computational form or in display form.

           A. A value of zero directs that numeric values  be  passed  in
              the  same  form  that  they  have in the data set:  numeric
              values in computational form are  passed  in  computational
              form,  and  values  in  display  form are passed in display
              form.  When values are passed in display form, the  setting
              of   SYSHLDISP   determines  whether  they  are  passed  as
              DISPLAY-6 or DISPLAY-7.  Numeric values for attributes  are
              passed  in  display  form  for  unbundled data sets, and in
              computational form for bundled data sets.

           B. A value of +1 directs that numeric  values  for  attributes
              are  passed  in  display form, in DISPLAY-7 or DISPLAY-6 as
              determined by SYSHLDISP.

           C. A value of -1 (the default) directs that numeric values for
              attributes are passed in computational, binary form.

   The default values of SYSHLDISP and SYSHLMODE ensure that a record  is
   passed  identically  for bundled and unbundled data sets with the same
   record structures.


   The COBOL record must conform in structure and  usage  to  the  System
   1022  Standard Record Format.  Each item in the WORKING-STORAGE record
   corresponds to one attribute.  Use the following  USAGE  clauses  when
   values are returned in the matching mode.

   1.  Numeric attributes are returned as binary items:

        ATTRIBUTE TYPE  COBOL USAGE  PICTURE SIZE
        _________ ____  _____ _____  _______ ____

        INTEGER         COMP         LE S9(10)
        REAL            COMP-1       LE S9(10)
        DATE            COMP         LE S9(10)
        DOUBLE INTEGER  COMP         GT S9(10) and LE S9(18)

   COBOL INTERFACE                                              Page 3-24
   Revision 5


   2.  Numeric attributes are returned as DISPLAY items:

        Under DISPLAY-7 Conversion:

        ATTRIBUTE TYPE      COBOL USAGE
        _________ ____      _____ _____

        INTEGER             DISPLAY-7 SYNC LEFT PIC X(15)
        REAL                DISPLAY-7 SYNC LEFT PIC X(15)
        DATE                DISPLAY-7 SYNC LEFT PIC X(10)
        DOUBLE INTEGER      DISPLAY-7 SYNC LEFT PIC X(25)

        Under DISPLAY-6 Conversion:

        ATTRIBUTE TYPE      COBOL USAGE
        _________ ____      _____ _____

        INTEGER             DISPLAY-6 SYNC LEFT PIC X(12)
        REAL                DISPLAY-6 SYNC LEFT PIC X(18)
        DATE                DISPLAY-6 SYNC LEFT PIC X(12)
        DOUBLE INTEGER      DISPLAY-6 SYNC LEFT PIC X(24)

   3.   Text attributes of length n are returned in the appropriate item,
        depending on the display conversion:

        DISPLAY-7 SYNC LEFT PIC X(n)    For DISPLAY-7 Conversion
        DISPLAY-6 SYNC LEFT PIC X(n)    For DISPLAY-6 Conversion


   Example:

   Assume that the data set contains three attributes:

              (#1)  ATTRIBUTE I INTEGER
              (#2)  ATTRIBUTE T TEXT LENGTH 6
              (#3)  ATTRIBUTE D DATE

   The setting of SYSHLDISP to 0 (DISPLAY-7 conversion) and of  SYSHLMODE
   to   -1   (binary   numeric   items)  requires  the  following  record
   description:

        01  1022-RECORD  DISPLAY-7.
          02  ATTR-I  COMP PIC S9(10).
          02  ATTR-T  PIC X(6) SYNC LEFT.
          02  ATTR-D  COMP PIC S9(10).

   The COBOL program can then retrieve a whole record with:

        ENTER MACRO DBGET USING 1022-RECORD, OUT-OF-RECS.

   If any attributes are protected  from  being  read,  those  items  are
   filled with blanks or zero.
   COBOL INTERFACE                                             Page 3-24A
   Revision 5


   3.8.10  Retrieving An Entire Record -- DBGET

   The DBGET routine retrieves the values of all attributes for a  single
   record  and  places them into a COBOL record.  It has the effect of an
   ENTER to DBGREC, followed  by  an  ENTER  to  DBVAL  for  all  of  the
   attributes.   Thus, it enters local mode for single record processing.
   The ENTER is:

|       ENTER MACRO DBGET USING DSET-RECORD, OUT-OF-RECS
|          [,"$LOCK"] [,SEQ-NUM].

   where:

        1) DSET-RECORD is a WORKING-STORAGE record to receive the  entire
           data set record.

        2) OUT-OF-RECS is a paragraph name  to  which  control  transfers
           when the program exhausts all currently selected records.

|       3) $LOCK locks update access to the record.

        4) SEQ-NUM is an optional record number for random retrieval.

   The record is returned into DSET-RECORD in "Standard  Record  Format".
   In  this  format,  each  attribute value begins on a new word boundary
   (SYNCHRONIZED), and has a length  large  enough  to  hold  the  entire
   attribute value.  Text attributes are returned space filled.

|  The optional $LOCK argument to DBGET locks the record so that no other
|  user  can  update  it.   The  record is unlocked when you get the next
|  record, return to global mode, close the data set,  drop  the  record,
|  delete the record, or give an ENTER MACRO DBLOCK USING "OFF","RECORD".
|  The $LOCK argument works only for data sets that are ENQ and RECLOCK.

   The next selected record is retrieved when SEQ-NUM is  omitted.   This
   is  similar  to  a sequential DBGREC.  If SEQ-NUM is included, the nth
   record is selected, where n is the value of SEQ-NUM.  This is  similar
   to a DBGREC with SEQ-NUM.
|  
|  
|  
|  3.8.10.0.1  The LOCK Command -- DBLOCK
|  
|  The DBLOCK routine locks and unlocks update access to  single  records
|  and  turns  on and off user-defined locks on a data set.  It parallels
|  the interactive LOCK command.  The ENTER is:
|  
|                         { "ON"  } , { "RECORD"           }
|                       { { non-0 }   { "USERLOCK", string }     }
|  ENTER DBLOCK USING ( {                                        } )
|                       { { "OFF" } , { "RECORD"               } }
|                         {   0   }   { "USERLOCK", { string } }     
|                                                   { "ALL" } 
   COBOL INTERFACE                                             Page 3-24B
   Revision 5


|  where:
|  
|       "ON" or non-0  Is the quoted keyword "ON" or  any  integer  other
|                      than 0 to turn the lock on.
|  
|       "OFF" or 0     Is the quoted keyword "OFF" or 0 to turn the  lock
|                      off.
|  
|       "RECORD"       Indicates record-level locking.
|  
|       "USERLOCK"     Indicates a user-defined lock on the data set.
|  
|       string         Is a text string of up to 25 characters naming the
|                      user lock.  it terminates with a space.
|  
|       "ALL"          Is the keyword to turn off all userlocks currently
|                      turned on by this program in this data set.
|  
|  Examples:
|  
|       ENTER MACRO DBLOCK USING "ON","RECORD" 
|       ENTER MACRO DBLOCK USING 1 "RECORD" 
|       ENTER MACRO DBLOCK USING "ON","USERLOCK","FRANCE_RECS"
|       ENTER MACRO DBLOCK USING "OFF","USERLOCK","ALL" 
|  
|  The DBLOCK ON RECORD routine, in single record mode, ensures  that  no
|  other  user can update your current record.  Unlike the UPDATE command
|  and DBUPD, other users may have full access, including update  access,
|  to the other records in the data set.  They may also read your current
|  record when you have it locked, but you are  the  only  user  who  can
|  update  that  current  record  while the lock is on.  DBLOCK RECORD is
|  similar to DBGREC or DBGET with $LOCK but is less efficient.
|  
|  The record remains locked until you  get  another  record,  return  to
|  global  mode,  close  the data set, form a new selection set, drop the
|  record from the selection set, delete the record, or give  the  DBLOCK
|  OFF (or 0) RECORD command.
|  
|  The data set must be ENQ and RECLOCK to use DBLOCK RECORD.
|  
|  The DBLOCK routine with USERLOCK turns on and off user-defined  locks.
|  The  userlock  created  by  DBLOCK ON (or a non-0 integer) USERLOCK is
|  identified by the specified string.  It  does  not  actually  restrict
|  access  to  the  data  set.   But  if your process and other processes
|  cooperate to use userlocks of the same names, you can specify  exactly
|  the  access  each  assumes.  When your process requests a userlock, it
|  will succeed if no other process has already locked the data set  with
|  that  string.   If  another  process has locked the data set with that
|  string, 1022 returns an error message.
|  
|  The data set must be ENQ to use DBLOCK USERLOCK.  The lock remains  in
|  effect  until  you  close  the  data  set  or  explicitly turn off the
|  individual lock or all userlocks.
   COBOL INTERFACE                                             Page 3-24C
   Revision 5


   3.8.11  The STARTREC Command -- DBSREC

   The DBSREC routine ends Local mode sequential processing.   The  ENTER
   is:

        ENTER MACRO DBSREC.

   The routine parallels the STARTREC command and returns the program  to
   Global  mode.   A  later  ENTER  to  DBGREC or DBGET selects the first
   record in the group.  DBSREC preserves sorted order in  the  selection
   group.  In contrast, DBFIND USING "LAST" forgets sorted order.



   3.8.12  The SORT Command -- DBSORT

   DBSORT sorts the currently selected group of records and parallels the
   interactive SORT command.  The ENTER is:
   COBOL INTERFACE                                             Page 3-24D
   Revision 5



























                     [ This page intentionally left blank ]
   COBOL INTERFACE                                              Page 3-25
   Revision 5


        ENTER MACRO DBSORT USING ["CORE",n,] ["USING",device,]

                      ATTR-1 [,sequence]  [, ATTR-2 [,sequence] ]...  .

   or

        ENTER MACRO DBSORT USING "KEY",ATTR.


   Where:

      1.  "CORE",n, - Is an optional clause which specifies the  size  of
          the sort buffer.  "n" is the number of 1024 word blocks (called
          "K") to be allocated in storage for sorting.  The default of 5K
          is  adequate for all but very large sorts.  "n" must be greater
          than or equal to 3.

      2.  "USING", device - Is  an  optional  clause  which  specifies  a
          scratch disk for the sort.

      3.  ATTR, sequence - Is a sort  clause  for  each  attribute.   The
          records  are  sorted  using  the  order  precedence of the sort
          clauses.  The first attribute  is  the  major  sort  key.   The
          second attribute affects the record order among equal values of
          the first attribute.   Later  attributes  determine  the  order
          among equal values of all previous attributes.

   The sequence identifier is optional in each attribute clause, and  can
   be  either  "ASCENDING"  or "DESCENDING".  This specifies the order in
   which that attribute is sorted.  If omitted, "ASCENDING"  is  assumed.
   The sequence keywords may be shortened to their first 5 characters.

   DBSORT with the KEY option establishes a sorted order using  a  single
   keyed  attribute.   This  ENTER  is analogous to the SORT KEY command.
   The records are always sorted in ascending order and no other  options
   are  allowed.   Only one sort field is allowed.  The key option is not
   always faster to use than a regular sort.  See  the  User's  Reference
                                                        ______  _________
   Manual for a detailed discussion.
   ______


   Examples:

        ENTER MACRO DBSORT USING "CORE",10,"FN","ASCEN","LN","DESCE".
        ENTER MACRO DBSORT USING "FN","LN","DESCENDING".
        ENTER MACRO DBSORT USING "STATE","COUNTY","CITY".



   3.8.13  The VALUES Command -- DBVALU

   The DBVALU command parallels the interactive VALUES  command.   For  a
   specified  keyed  attribute,  it  returns each different value and the
   number of times each occurs in the current  selection  group.   Values
   and  occurrence  counts  are  returned  to a user array in pairs, each
   COBOL INTERFACE                                              Page 3-26
   Revision 5


   value followed by the corresponding count.  Count is always  a  binary
   integer.  ENTER is:

        ENTER MACRO DBVALU USING
                  ATTR, ARRAY-START, ARRAY-END, NV [, IVLEN]

   Where:

        ATTR        Is the keyed attribute name or number.

        ARRAY-START Is  the  first  location  in  the  array   to   which
                    value/occurrence data is returned.

        ARRAY-END   Is  the  last  location  in  the   array   to   which
                    value/occurrence data is returned.

                    ARRAY-START and ARRAY-END need not be the  first  and
                    last  locations in the array, but they must delimit a
                    contiguous block of memory.  At least n+1  words  are
                    required,   where  n  is  the  length  of  the  value
                    returned;  the extra word  is  for  the  count.   For
                    efficiency, dimension the array as large as possible.

        NV          Is the integer number of value/occurrence pairs  that
                    DBVALU has loaded into the array.  For the first call
                    the user sets this to -1.   Subsequent  calls  return
                    non-zero  integers  in  NV until all values have been
                    read and counted.  Then DBVALU sets NV to 0.

                    When NV is not -1,  DBVALU  uses  it  to  resume  key
                    searching.   Tampering  with  NV between DBVALU calls
                    will cause incorrect results or errors.

                    If the program sets NV to a value  greater  than  the
                    maximum  number  of  value/count  pairs  that  can be
                    contained within the bounds  defined  by  ARRAY-START
                    and ARRAY-END, 1022 returns an error message (HL40).

        IVLEN       Is the value's length in words.  This is returned  by
                    1022,  when  specified,  for use in retrieving values
                    from the array.
   After the first call, DBVALU uses the NVth value in the user array  to
   locate  the  next  set of values.  Because of this, the program should
   not modify NV or any elements of the array.

   The following example uses DBVALU to return attribute values/counts to
   a  user array.  For AGE, DBVALU is called in a loop until the keys are
   exhausted (NV = 0).  After the DBVALU call, all values and counts  are
   displayed.

   COBOL INTERFACE                                              Page 3-27
   Revision 5


   Example:

   IDENTIFICATION DIVISION.
   PROGRAM-ID. VALS.
   *********************************************************************
   ** VALUE-ARRAY holds value/occurrence pairs, it contains:
   **   VALUE-VALUE (the value)
   **   VALUE-OCCURRENCE (number of occurrences for the value)
   ** VALUE-LENGTH holds the length of the value (returned by DBVALU)
   ** NUMBER-OF-VALUES holds the number of values (returned by DBVALU)
   *********************************************************************
   ENVIRONMENT DIVISION.
   DATA DIVISION.
   WORKING-STORAGE SECTION.
   01 VALUE-ARRAY OCCURS 10 TIMES.
      05 VALUE-VALUE     COMP      PIC 9(9).
      05 VALUE-OCCURRENCE COMP      PIC 9(9).
   01 VALUE-DISPLAY.
      05 FILLER          DISPLAY-7 PIC X(7) VALUE IS "Value= ".
      05 VALUE-DISPLAY-V DISPLAY-7 PIC X(10).
      05 FILLER          DISPLAY-7 PIC X(14) VALUE IS ", Occurrences= ".
      05 VALUE-DISPLAY-O DISPLAY-7 PIC X(10).
   77 VALUE-LENGTH       COMP      PIC 9(9).
   77 NUMBER-OF-VALUES   COMP      PIC 9(9).
   77 I                  COMP      PIC 9(9).
   PROCEDURE DIVISION.
   **  Initialize and select records
                 ENTER MACRO DBCBL.
                 ENTER MACRO DBOPEN USING "NAMES".
                 ENTER MACRO DBFIND USING "ALL".
   **  Set up for first DBVALU call
                 MOVE -1 TO NUMBER-OF-VALUES.
   DBVALU-CALL.
                 ENTER MACRO DBVALU USING
                     "AGE",
                     VALUE-VALUE(1),
                     VALUE-OCCURRENCE(10),
                     NUMBER-OF-VALUES,
                     VALUE-LENGTH.
   **  Check for out of values
                 IF NUMBER-OF-VALUES IS EQUAL TO ZERO GO TO ALL-DONE.
   **  Print value/occurrence pairs
                 PERFORM DISPLAY-VALUE VARYING I FROM 1 BY 1 
                    UNTIL I IS EQUAL TO 10.
   **  Repeat DBVALU to get next set of values
                 GO TO DBVALU-CALL.
   DISPLAY-VALUE.
                 MOVE VALUE-VALUE(I) TO VALUE-DISPLAY-V.
                 MOVE VALUE-OCCURRENCE (I) TO VALUE-DISPLAY-O.
                 DISPLAY VALUE-DISPLAY.
   ALL-DONE.
                 ENTER MACRO DBEND.
                 STOP RUN.
   COBOL INTERFACE                                              Page 3-28
   Revision 5


   3.9  DATA SET UPDATE ROUTINES

   These routines correspond to the commands and  features  described  in
   Chapter 5 of the System 1022 User's Reference Manual.
                                ______ _________ ______



   3.9.1  The CHANGE Command-- DBCHNG

   The DBCHNG routine parallels the CHANGE command and changes the values
   of attributes in the currently selected records.  The ENTER is:

        ENTER MACRO DBCHNG USING ["UPDE.",procedure-name,]

             ["ATTR.",] ATTR-ID-1, VALUE-1
             [,["ATTR.",] ATTR-ID-2, VALUE-2] ...  .

   Where:

        "UPDE.",procedure-name   Is an  optional  clause  that  specifies
                                 where  to transfer control if the record
                                 has been changed by another  user  since
                                 the last call to DBGREC or DBGET.

        "ATTR."                  Is an optional  keyword  that  specifies
                                 that  VALUE  is an attribute identifier.
                                 The value  of  the  first  attribute  is
                                 changed to the value of the second.

        ATTR-ID                  Is an attribute identifier,  either  the
                                 DISPLAY-7      attribute     name     or
                                 abbreviation, or the COMP code.

        VALUE                    Is the new value for the attribute.   It
                                 is the name of an attribute when "ATTR."
                                 appears.

   The program may change many attributes in a single ENTER to DBCHNG  if
   you  provide  a  pair  of  arguments  for  each attribute.  It is more
   efficient to  place  many  pairs  in  one  ENTER  than  to  make  many
   individual ENTERs.

   In global mode, all currently selected records are changed.  In  local
   mode, after DBGREC or DBGET, only the one chosen record is changed.

   COBOL INTERFACE                                              Page 3-29
   Revision 5


   Examples:

        INTERACTIVE:   CHANGE AGE 25.
        COBOL:         ENTER MACRO DBCHNG USING "AGE",25.

        INTERACTIVE:   CHANGE AGE 30 CITY BOSTON.
        COBOL:         ENTER MACRO DBCHNG USING "AGE",30,"CITY","BOSTON".

   Control can be transferred using the "UPDE." clause in local  mode  if
   another  updater  has  changed any attribute in the record between the
   time of the DBGREC  and  the  DBCHNG.   In  global  mode,  control  is
   transferred  only if another updater changes an attribute in the first
   record between the time the selection group was made and the  DBCHNG's
   action  on the first record.  Other records can be changed without any
   transfer of control;  thus, it is better to do a DBCHNG in local mode.

   See Chapter 5 of the User's Reference Manual,  System  Protection  for
                        ______ _________ ______
   Interactive  Simultaneous  Updates, for more information on how System
   1022 handles this interaction.

   On transfer, the new (altered) record has been read, so  there  is  no
   need  to  DBGREC  again.   For  example, a user wants to decrement the
   count of all the tools by 1 and print a warning if any of  the  counts
   equals zero.  The COBOL program is:

                                 .
                                 .
                                 .
                     ENTER MACRO DBFIND USING "TYPE", "EQ", "TOOL".
        GREC-LINE.
                     ENTER MACRO DBGREC USING OUT-OF-RECS.
        VAL-LINE.
                     ENTER MACRO DBVAL USING "COUNT", ICOUNT.
                     IF ICOUNT IS EQUAL TO 0 GO TO PRINT-WARN.
                     SUBTRACT 1 FROM ICOUNT.
        CHNG-LINE.
                     ENTER MACRO DBCHNG USING "UPDE.", VAL-LINE,
                           "COUNT", ICOUNT.
                     GO TO GREC-LINE.
        PRINT-WARN.          
                     DISPLAY "WARNING--OUT OF STOCK".
                     GO TO GREC-LINE.
        OUT-OF-RECS.
                                 .
                                 .
                                 .

   CHNG-LINE institutes the CHANGE, and checks  whether  the  record  was
   altered  since the DBGREC.  If it was, it sends the record through the
   zero checking procedure  again,  to  make  sure  that  COUNT  was  not
   decremented to zero by someone else.
   COBOL INTERFACE                                              Page 3-30
   Revision 5


   3.9.2  The DELETE Command -- DBDEL

   The DBDEL  routine  parallels  the  DELETE  command  and  deletes  all
   currently selected records from the data set.  The ENTER is:

        ENTER MACRO DBDEL [USING "UPDE.",procedure-name] .

   "UPDE.",procedure-name is an optional clause which specifies where  to
   transfer  control  if  the  record  has been changed since the call to
   DBGREC due to simultaneous updates.  This is only useful in DBDELs  in
   local  mode.   See  Chapter  5  of the User's Reference Manual, System
                                          ______ _________ ______
   Protection for Interactive Simultaneous Updates.

   In global mode, all currently selected records are deleted.  In  local
   mode, after DBGREC or DBGET, only the one chosen record is deleted.



   3.9.3  The ADD Command -- DBADD And DBADDR

   Two routines add records to a data set.  The  first  is  DBADD,  which
   parallels the ADD command.  Its ENTER is:

        ENTER MACRO DBADD USING ATTR-ID-1, VALUE-1

                             [, ATTR-ID-2, VALUE-2 ]...  .

   Where:

      ATTR-ID-1  Is  an  attribute  identifier,  either   the   DISPLAY-7
                 attribute  name  or  abbreviation, or the COMP attribute
                 number.

      VALUE-1    Is the value of the attribute to be added.

   Example:

        ENTER MACRO DBADD USING "NAME","JOHN","AGE",25,
             "CITY","CLEVELAND".

   Any attributes not specified in the ENTER to DBADD receive null values
   of zero or space.

   After DBADD, the selection group contains only the added record.

   The DBADDR routine also adds records to a  data  set.   Unlike  DBADD,
   DBADDR  has  only  one  argument.   This  argument  is  the  name of a
   WORKING-STORAGE record in Standard  Record  Format.   DBADDR  supplies
   values from this record into a record of the data set.

        ENTER MACRO DBADDR USING DSET-RECORD.

   Attribute values in the DBADDR record may be  numeric,  DISPLAY-6,  or
   DISPLAY-7 as set by the system variables SYSHLMODE and SYSHLDISP.
   COBOL INTERFACE                                              Page 3-31
   Revision 5


   DBADD provides  independence  from  the  data  set.   Changes  in  the
   structure  of  the  data set do not affect retrieval of the attributes
   which have not changed, and rarely affect the retrieval of the changed
   attributes.   DBADDR  is  convenient,  but  binds  the  program  to  a
   particular data set  structure.   The  efficiency  difference  between
   DBADD and DBADDR is not significant.



   3.9.4  The UPDATE Command -- DBUPD

   The DBUPD routine parallels the UPDATE command,  for  use  when  large
   scale updates are done to a data set.  The ENTER is:

        ENTER MACRO DBUPD USING UPDATE-VAL.

   Where:

        UPDATE-VAL   Is 0 to set update mode OFF.
                     Is nonzero to set update mode ON.

   The DBUPD routine should be used if much updating is to be done  to  a
   data  set.   It eliminates reopening the data set file for each update
   command.  It also prevents other users  from  updating  the  data  set
   while update is on.

   The program must turn update mode off to allow others  to  update  the
   data set.  This is done by another ENTER to DBUPD, or automatically in
   the ENTER to DBEND.

   The DBUPD routine sets UPDATE ON and UPDATE OFF only for  the  current
   data  set.   If several data sets are open simultaneously, the program
   ENTERs DBSET and DBUPD for each data set for which UPDATE ON or OFF is
   required.



   3.9.5  The SET BUFFER Command -- DBBUF

   The DBBUF routine parallels the SET BUFFER  command  and  assigns  I/O
   buffers for more efficient update and retrieval operations.  The ENTER
   is:

        ENTER MACRO DBBUF USING NUM-BUFFERS.

   where NUM-BUFFERS specifies the number of I/O buffers to use  for  the
   current  data  set.   The  DBBUF  routine is used along with the DBUPD
   routine when many additions or changes are to be made to the data set.
   COBOL INTERFACE                                              Page 3-32
   Revision 5


   3.9.6  The ALLOCATE Command -- DBALLO

   The DBALLO routine parallels the ALLOCATE command and  reserves  space
   for new records to be added to the data set.  The ENTER is:

        ENTER MACRO DBALLO USING NUM-RECS.

   where NUM-RECS specifies the number of records which will be added  to
   the  data  set.  This improves System efficiency, because the space is
   allocated in one continuous cluster of blocks.  NUM-RECS  can  have  a
   value  between 1 and 5000.  NUM-RECS is the number of records, not the
   number of blocks or pages that are  allocated.   1022  calculates  the
   number necessary.



   3.10  SPECIAL PURPOSE ROUTINES

   These routines perform special functions.  Except for DBEXEC, they are
   parallel to commands in the interactive System.



   3.10.1  The INFORM ATTRIBUTE Command -- DBINFO

   The DBINFO routine obtains information about attributes  in  the  data
   set.   It  parallels  the INFORM ATTRIBUTE command and returns all the
   information about a single attribute.  The ENTER is:

        ENTER MACRO DBINFO USING ATTR-ID, INFORM-RECORD.

              Examples:

              ENTER MACRO DBINFO USING "AGE", INFORM-RECORD.
              ENTER MACRO DBINFO USING 3, INFORM-RECORD.

   Where:

      1. ATTR-ID is an attribute identifier, either the DISPLAY-7 name or
         abbreviation,  or  the  COMP  attribute  number.   The attribute
         number is usually obtained from an ENTER to DBINFO.

      2. INFORM-RECORD is a record where information on the attribute  is
         returned.   INFORM-RECORD  is  a  WORKING-STORAGE  record in the
         following format:


          01 INFORM-RECORD.

             02 ATT-NAME DISPLAY-7 PIC X(25).
             02 ATT-ABBREV DISPLAY-7 PIC X(5).
             02 ATT-NUMBER COMP PIC 9(5).
                88 NO-SUCH-ATT  VALUE 0.
   COBOL INTERFACE                                              Page 3-33
   Revision 5


             02 ATT-TYPE COMP PIC 9(2).
                88 TYPE-INTEGER  VALUE 0.
                88 TYPE-REAL  VALUE 1.
                88 TYPE-DISP-7-TEXT  VALUE 2.
                88 TYPE-DATE  VALUE 4.
                88 TYPE-DISP-7-INTEGER  VALUE 5.
                88 TYPE-DISP-7-REAL  VALUE 6.
                88 TYPE-DISP-7-DATE  VALUE 7.
                88 TYPE-DISP-6-TEXT  VALUE 8.
                88 TYPE-DISP-6-INTEGER  VALUE 9.
                88 TYPE-DISP-6-REAL  VALUE 10.
                88 TYPE-DISP-6-DATE  VALUE 11.

             02 ATT-LENGTH COMP PIC 9(6).
          *        Number of characters if type text,
          *        zero otherwise.

             02 ATT-KEYED-FLAG COMP PIC S9.
                88 KEYED-ACTIVE  VALUE -1.
                88 NOT-KEYED  VALUE 0.
                88 KEYED-INACTIVE  VALUE 1.

             02 FILLER COMP PIC S9(10).
             02 ATT-PSWRD-FLAG COMP PIC S9.
                88 PASSWORD-REQUIRED  VALUE -1.
                88 NO-PASSWORD-REQUIRED  VALUE 0.

             02 FILLER COMP PIC S9(10).

             02 ATT-LOWER-RANGE COMP PIC S9(10).
          *        Lower bound on RANGE or 0 if text.

             02 ATT-UPPER-RANGE COMP PIC S9(10).
          *        Upper bound on RANGE or 0 if text.

             02 ATT-START-COL COMP PIC 9(6).
          *        Starting column on input record.

             02 ATT-END-COL COMP PIC 9(6).
          *        Ending column on input record.

             02 ATT-SPECIAL COMP PIC 9.
                88 NOT-SPECIAL  VALUE 0.
                88 DATE-OF-ENTRY  VALUE 1.
                88 DATE-OF-CHANGE  VALUE 2.
                88 INTEGER-OF-ID  VALUE 3.

             02 ATT-PROTECTION COMP PIC 9.
                88 UPDATE-POSSIBLE  VALUE 0.
                88 READONLY  VALUE 5.
                88 LOCKED  VALUE 7.

   COBOL INTERFACE                                              Page 3-34
   Revision 5


             02 ATT-INDEX COMP PIC 9(6).
          *        Index for this attribute by computer word
          *        into the record returned by DBGET.

             02 FILLER DISPLAY-7 PIC X(25)

        The item ATT-NUMBER is returned as 0 if no attribute  corresponds
        to the value of ATTR-ID.

        The item names need  not  be  those  in  this  example,  but  the
        structure  of  the  record  and  the data types must be the same.
        FILLER may be substituted for those items that are not used.



   3.10.1.1  Attribute Numbers


   Many System  routines  require  attribute  identifiers  as  arguments.
   Attribute  numbers are slightly more efficient than attribute names or
   abbreviations because they save table lookups in 1022.  But, attribute
   numbers  change  when  existing  data  set attributes are reordered or
   removed, or when new ones are added.

   The DBINFO  routine  preserves  the  program's  data  independence  if
   attribute numbers change.  For example:

        01  EQUALS  COMP PIC S9 VALUE 1.
        01  SEX-ID  COMP PIC 9(5).
        01  SEX-VALUE  PIC X.
              .
              .
              .
        ENTER MACRO DBINFO USING "SEX", INFO-RECORD.
        MOVE ATT-NUMBER OF INFO-RECORD TO SEX-ID.
              .
              .
              .
        ENTER MACRO DBFIND USING SEX-ID, EQUALS, SEX-VALUE.



   3.10.2  The PERMIT Command -- DBPSWD

   The DBPSWD routine parallels the PERMIT command.  It is used  to  gain
   access  to  password-protected attributes of the data set and may also
   be used to assign readonly access to data set attributes that are  not
   protected.  The ENTER is:

        ENTER MACRO DBPSWD USING ATTR-ID-1, PASSWORD-1, READ-PROT-1

                 [, ATTR-ID-2, PASSWORD-2, READ-PROT-2]...  .

   COBOL INTERFACE                                              Page 3-35
   Revision 5


   Where:

      ATTR-ID-1    Is an attribute identifier.

      PASSWORD-1   Is the  password.   When  DBPSWD  is  used  to  assign
                   readonly   access   to   an   attribute  that  is  not
                   password-protected, this argument is 0.

      READ-PROT-1  Is the access type.  For readonly access, the argument
                   is "RO".  Otherwise, the argument is 0.


   Example:  ENTER MACRO DBPSWD USING "NAME","ABC",0,"AGE",0,"RO".

             Provide the password ABC for the attribute NAME, and  assign
             readonly access to the attribute AGE.



   3.10.3  The Number Of Attributes -- DBNATT

   The DBNATT routine returns the number of  attributes  in  the  current
   data set.  The ENTER is:

        ENTER MACRO DBNATT USING ATTR-COUNT.

   The item ATTR-COUNT receives the number of attributes.  ATTR-COUNT  is
   returned as a meaningless value if no data set is open.

   Use the DBNATT routine along with DBINFO.  DBINFO can  be  used  in  a
   procedure  to sequentially investigate the attributes, using the value
   returned by DBNATT as the upper index in a  loop  to  obtain  complete
   information about the data set structure.



   3.10.4  Resetting Internal Buffers -- DBCLR

   During the execution of System 1022  routines,  internal  buffers  may
   expand  to  accommodate long argument strings.  Space usually is not a
   problem, but DBCLR resets the 1022 buffer space to its initial  value.
   The ENTER is:

        ENTER MACRO DBCLR.

   The DBADD command  requires  larger  System  buffers  when  processing
   argument lists with many attributes.

   Expansion and contraction of command buffers causes  overhead.   Reset
   buffers  only  if  physically  long DBADDs execute infrequently in the
   program.

   Do not confuse the DBCLR routine with the System 1022 CLEAR command.
   COBOL INTERFACE                                              Page 3-36
   Revision 5


   3.10.5  Error Handling Routines

   The routines DBERR and DBERRH instruct  1022  to  take  one  of  three
   actions when an error occurs:

       1) Trap to the COBOL program on errors.
       2) Abort the program on errors.
       3) Ignore errors.

   The DBRETN routine marks the end of an error procedure set  up  by  an
   ENTER to DBERRH.

   The DBERRT routine can print the message text for the last error  onto
   your terminal.  It can also store that text in a variable.



   3.10.5.1  The DBERR Subroutine


   The ENTER is:

        ENTER MACRO DBERR USING ERROR-PROCEDURE

             [, ERROR-TYPE, ERROR-CODE, FLAG].

   Where:

   ERROR-PROCEDURE  Is the paragraph name where control transfers when an
                    error  occurs.   Provide  a  COMP  value  instead  of
                    ERROR-PROCEDURE if trapping is not desired.   In  the
                    event  of  an  error, a value of 0 aborts the program
                    run after any error messages are printed.  A value of
                    -1   continues   the  program  after  printing  error
                    messages.

   ERROR-TYPE       Is a COMP item which receives the error  type  number
                    when an error is detected.

   ERROR-CODE       Is a COMP item which receives the error  code  number
                    Refer  to  Appendix  A  and  to  the User's Reference
                                                         ______ _________
                    Manual for a list of error types and codes.
                    ______

   FLAG             1: Print error messages on the terminal (default).
                    0: Suppress error messages.

   All the arguments after the first are optional.  DBERR is entered once
   to provide the trapping information, or again to change it.  It is not
   entered to test the presence of an error.


   COBOL INTERFACE                                              Page 3-37
   Revision 5


   Normally, 1022 types an error message and terminates the job  when  an
   error  occurs during System 1022 execution.  The program may use DBERR
   to do its own error handling.  An ENTER to DBERR enables  or  disables
   program error trapping.

   If trapping is enabled,  the  COMP  items  ERROR-TYPE  and  ERROR-CODE
   receive  the  error numbers listed in Appendix A.  Thus, if ERROR-TYPE
   is set to 4 and ERROR-CODE is set to 2, the error is "OP2  Dataset Not
   Found".

   Examples:

        ENTER MACRO DBERR USING PART-1-ERROR, ERROR-TYPE, ERROR-CODE, 0.

        On an  error,  control  passes  to  paragraph  PART-1-ERROR.   No
        typeout occurs.  The COMP items ERROR-TYPE and ERROR-CODE receive
        the error numbers.

        ENTER MACRO DBERR USING 0.

        Sets 1022 to its default state of no error trapping and automatic
        error message typeout.

        ENTER MACRO DBERR USING -1.

        This ENTER disables program  termination  on  errors.   An  error
        message  appears  on  the  terminal,  but  the  program continues
        running.

        ENTER MACRO DBERR USING -1, ERROR-TYPE, ERROR-CODE, 0.

        This disables both the program abort and the error typeout.  This
        is  not recommended, because any number of errors could occur and
        go unnoticed.  ERROR-TYPE and ERROR-CODE receive the error codes.

        ENTER MACRO DBERR USING -1, ERROR-TYPE, ERROR-CODE, 1.

        This disables program termination on errors.   An  error  message
        prints  on  the  terminal  to  report  errors, and ERROR-TYPE and
        ERROR-CODE receive the error codes.



   3.10.5.2  The DBERRH Subroutine


   The ENTER is:

        ENTER MACRO DBERRH USING ERROR-PROCEDURE, ERROR-TYPE,

             ERROR-CODE, FLAG .

   Where:
   COBOL INTERFACE                                              Page 3-38
   Revision 5


   ERROR-PROCEDURE  Is the name of the procedure performed when an  error
                    occurs.   At  the  end  of the procedure, an ENTER to
                    DBRETN transfers control to the user's program at the
                    command following the 1022 call in error.

                    If a 1022 error  occurs  during  the  error-procedure
                    execution,  no  additional  error trapping occurs but
                    codes and types are set.  Program execution continues
                    sequentially.   If  the "ERRT." option was present in
                    the 1022 ENTER during which the error  occurred,  the
                    error  procedure is still executed, but the return is
                    to the procedure name  specified  after  the  "ERRT."
                    keyword.

   ERROR-TYPE       Is a COMP item which receives the  error-type  number
                    on  trapping.   If  the  user moves zero to this item
                    during  the  error-procedure  execution,   then   any
                    procedure  name  specified  by  the "ERRT." option is
                    ignored.

   The rest of the arguments are the same as those in DBERR.




   3.10.5.3  The DBRETN Subroutine


   The routine DBRETN marks the end of the error procedure set up  by  an
   ENTER to DBERRH.  The ENTER is:

        ENTER MACRO DBRETN.

   DBRETN causes program execution to return to the next command after  a
   1022 error.  DBRETN may be called only from an error procedure.

   COBOL INTERFACE                                              Page 3-39
   Revision 5


   The following is a sample program fragment using DBERRH.

                  .
                  .
                  .
        01 ERROR-FLAGS
           05 ERROR-TYPE COMP PIC 99.
           05 ERROR-CODE COMP PIC 9(3).
           05 FLAG COMP PIC S9.
                 .
                 .
                 .
        PROCEDURE DIVISION.
           ENTER MACRO DBCBL.
           ENTER MACRO DBERRH USING ERROR-TRAP, ERROR-TYPE,
               ERROR-CODE, 1.
                 .
                 .
                 .
        ERROR-TRAP.
                 .
                 .
                 .
           ENTER MACRO DBRETN.
        ANOTHER-PROCEDURE.
                 .
                 .
                 .

   When an error occurs, the  error  message  prints  and  ERROR-TRAP  is
   performed until the ENTER to DBRETN.




   3.10.5.4  The DBERRT Subroutine


   The routine DBERRT controls the error-message text associated with the
   last  error.  It can print this text to the terminal or store the text
   in a variable.

   The ENTER is:

        ENTER MACRO DBERRT USING TYPE-FLAG [,ERR-STRING] .

   Where:

   TYPE-FLAG      0: Print the message on the terminal.
                  1: Suppress the printing of the message.

   ERR-STRING     Is a display-7 item which  receives  the  error-message
                  text.  The text is exactly 80 characters long.
   COBOL INTERFACE                                              Page 3-40
   Revision 5


   Use DBERRT when you have suppressed the type out  of  error  messages,
   but decide during error recovery to see the last message.



   3.10.6  Converting System 1022 Dates -- DBNDAT And DBDATN

   The routines DBNDAT and DBDATN convert dates to and from  System  1022
   encoded date format.  DBNDAT (number-to-date) converts an encoded date
   to the corresponding month, day, and  year  in  separate  COMP  items.
   DBDATN  (date-to-number)  performs  the reverse operation.  The ENTERs
   are:

        ENTER MACRO DBNDAT USING DATE, MONTH-NO, DAY-NO, YEAR-NO.

             Provide DATE, and receive MONTH-NO, DAY-NO, YEAR-NO.


        ENTER MACRO DBDATN USING DATE, MONTH-NO, DAY-NO, YEAR-NO.

             Provide MONTH-NO, DAY-NO, YEAR-NO, and receive DATE.

   Where:

      DATE      Is a System 1022 encoded date, the integer number of days
                since Jan 1, 1800.

      MONTH-NO  Is the corresponding month, 1 to 12.  (Jan=1, Feb=2,  and
                so on.)

      DAY-NO    Is the corresponding day, 1 to 31.

      YEAR-NO   Is the corresponding year, for example, 1970,  1973,  and
                so  on.  If YEAR-NO is between 0 and 99, 1022 assumes the
                twentieth century.

   All values are COMP having PICTUREs  no  larger  than  S9(10).   These
   routines  do  not handle dates in text form.  If an impossible date is
   given to DBDATN (such as DAY-NO greater than 31), DATE is set to -1.



   3.10.7  Supplying Or Receiving System Variables -- DBSYSV

|  The DBSYSV routine retrieves the value or the address of the value  of
|  a  system variable or assigns a value to a system variable.  The ENTER
   is:

        ENTER MACRO DBSYSV USING

                           VARIABLE-ID, ACTION-FLAG, VARIABLE-VALUE.

   VARIABLE-ID is:
   COBOL INTERFACE                                              Page 3-41
   Revision 5


        1) a system variable number from Table 3-1 below (a  COMP  item),
        or

        2) the name of one of the system variables in Table 3-1, either a
        literal or a DISPLAY-7 item.

   Using a system variable number is faster than using a name.

   ACTION-FLAG is a COMP  item  which  specifies  whether  to  supply  or
   receive the value of a system variable:

        ACTION-FLAG is   0  Receive the value.
                         1  Supply the value.
|                        2  Store the address of a user routine
|                           in the system variable
|  
|  VARIABLE-VALUE supplies or receives the value or supplies the  address
|  to  be  used as the value.  VARIABLE-VALUE receives the user-specified
   data type unless such automatic conversion is  overridden  by  setting
   the DISP., BIN., SYSHLMODE, or SYSHLDISP flags.


                 TABLE 3-1. SYSTEM VARIABLE CHARACTERISTICS


           NAME    NUMBER  DATA TYPE      USER   STANDARD   DEFAULT
                                        SETTABLE DEFAULT    SETTABLE

        SYSADDMSG    105   INTEGER         YES     0          YES
        SYSADMCDIR   126   INTEGER         NO      0          YES
        SYSALCMSG    104   INTEGER         YES     0          YES
        SYSAMBATTR   132   INTEGER         YES     0          YES
        SYSAUXCHK    128   INTEGER         YES     0          YES
        SYSBETWEEN   131   INTEGER         YES     0          YES
        SYSCASE      3     INTEGER         YES     0          YES
        SYSCBLSIGN   41    INTEGER         YES     1          YES
        SYSCHANGED   79    INTEGER         NO      0          NO
        SYSCLOSE2    115   INTEGER         NO      0          YES
        SYSCOLNAME   72    TEXT 25         NO      blanks     NO
        SYSCORESS    74    INTEGER         YES     50000      YES
        SYSCUSTDMI   88    INTEGER         YES     0          YES
        SYSCVTERR    113   INTEGER         YES     0          YES
        SYSDAMAGE    200   INTEGER         NO      0          NO
        SYSDATE      1     DATE            NO      0          NO
        SYSDATEFMT   112   INTEGER         YES     0          YES
        SYSDAYTIME         TEXT            NO      0          NO
        SYSDBEXMSG   44    INTEGER         YES     0          YES
        SYSDCORESS   75    INTEGER         YES     0          NO
        SYSDELIM     24    TEXT            YES     ,          YES
        SYSDEQFAST   68    INTEGER         YES     0          YES
        SYSDIV       110   INTEGER         YES     0          YES
        SYSDIVMSG    108   INTEGER         YES     0          YES
        SYSDIVP      111   INTEGER         YES     0          YES
        SYSDMETRID   133   INTEGER         YES     0          YES
   COBOL INTERFACE                                              Page 3-42
   Revision 5


        SYSDSALIAS   70    TEXT 25         YES     blanks     NO
        SYSDSENQ     65    INTEGER         NO      1          NO
        SYSDSFILE    69    TEXT 80         NO      blanks     NO
        SYSDSNAME    58    TEXT 25         NO      blanks     NO
        SYSENQDEF    123   INTEGER         NO      1          YES
        SYSENQTYPE   67    INTEGER         YES     1          YES
        SYSERRCODE   21    OCTAL           NO      0          NO
        SYSERRDEV    17    SIXBIT INT      NO      0          NO
        SYSERREXT    19    SIXBIT INT      NO      0          NO
        SYSERRFILE   18    SIXBIT INT      NO      0          NO
        SYSERRPPN    20    OCTAL           NO      0          NO
        SYSERRTEXT   78    INTEGER         YES     0          YES
        SYSEURODAT   120   INTEGER         YES     0          YES
        SYSEXECKP    85    INTEGER         YES     0          YES
        SYSEXP       7     DATE            NO      0          NO
        SYSEXPTYPE   29    INTEGER         YES     0          YES
        SYSFDMATT    16    INTEGER         NO      0          NO
        SYSFMSG      59    INTEGER         YES     0          NO
        SYSGTABERR   129   INTEGER         NO      0          NO
        SYSHLCVT     34    INTEGER         YES     0          YES

   COBOL INTERFACE                                              Page 3-43
   Revision 5


           TABLE 3-1 SYSTEM VARIABLE CHARACTERISTICS (continued)

           NAME    NUMBER  DATA TYPE      USER   STANDARD   DEFAULT
                                        SETTABLE DEFAULT    SETTABLE

        SYSHLDISP    26    INTEGER         YES     0          YES
        SYSHLMODE    27    INTEGER         YES     0          YES
        SYSHLNAME    63    INTEGER         NO      0          YES
        SYSID        8     INTEGER         NO      0          NO
        SYSIFTYPE    42    INTEGER         YES     0          YES
        SYSIOMSG     102   INTEGER         YES     0          YES
        SYSJOBNO     25    INTEGER         NO      0          NO
        SYSKEEPBUF   125   INTEGER         YES     0          YES
        SYSKEEPPSI   121   INTEGER         YES     1          YES
        SYSLINE      4     INTEGER         NO      0          NO
        SYSMSTIME          INTEGER         NO      0          NO
        SYSNOFILOP   118   INTEGER         NO      1          YES
        SYSNOYMD     87    INTEGER         YES     0          YES
        SYSNOPSI     122   INTEGER         YES     0          YES
        SYSNOSEG     100   INTEGER         YES     0          YES
        SYSNOSEGP    61    INTEGER         NO      -1         YES
        SYSNOXCHAN   119   INTEGER         NO      0          YES
        SYSNREC      9     INTEGER         NO      0          NO
        SYSNRETRY    15    INTEGER         YES     10         YES
        SYSOVF       106   INTEGER         YES     0          YES
        SYSOVFMSG    109   INTEGER         YES     0          YES
        SYSOVFP      107   INTEGER         YES     0          YES
        SYSPAGE      2     INTEGER         YES     0          NO
        SYSPCCOL     82    INTEGER         YES     0          NO
        SYSPCRESET   84    INTEGER         YES     0          NO
        SYSPCROW     83    INTEGER         YES     0          NO
        SYSPPN       37    INTEGER         NO      0          NO
        SYSPROT20    28    TEXT 6          YES     blanks     YES
        SYSRECLOCK   86    INTEGER         NO      0          NO
        SYSRECMODE   60    INTEGER         NO      0          NO
        SYSRECNO     5     INTEGER         NO      0          NO
        SYSREP1      10    INTEGER         YES     0          YES
        SYSREP2      11    INTEGER         YES     0          YES
        SYSREP3      12    INTEGER         NO      0          NO
        SYSREPMODE   13    INTEGER         YES     0          YES
        SYSREPSYNC   14    INTEGER         YES     1          YES
        SYSRESET     23    INTEGER         YES     0          YES
        SYSRNGMSG    103   INTEGER         YES     0          YES
        SYSSCRDEV    64    TEXT 6          YES     DSK        YES
        SYSSCRFILE   76    INTEGER         YES     1          YES
        SYSSFDFLAG   114   INTEGER         NO      0          YES
        SYSSWEDSRT   77    INTEGER         YES     0          YES
        SYSTENQ      66    INTEGER         YES     2000       YES
        SYSTEXTDOT   127   INTEGER         YES     0          YES
        SYSTIME      6     TEXT 8          NO      0          NO
        SYSTOPIID    80    INTEGER         NO      0          NO
        SYSTOPSID    81    INTEGER         NO      0          NO
        SYSTRAPUP3   124   INTEGER         YES     0          YES

   COBOL INTERFACE                                              Page 3-44
   Revision 5


           TABLE 3-1 SYSTEM VARIABLE CHARACTERISTICS (continued)

           NAME    NUMBER  DATA TYPE      USER   STANDARD   DEFAULT
                                        SETTABLE DEFAULT    SETTABLE

        SYSTRETRY    43    INTEGER         YES     200        YES
        SYSUPROG     39    INTEGER         NO      0          NO
        SYSUPROJ     38    INTEGER         NO      0          NO
        SYSUSERADR   30    INTEGER         YES     0          YES
        SYSUSERD1    54    DATE            YES     01/01/1800 NO
        SYSUSERD2    55    DATE            YES     01/01/1800 NO
        SYSUSERD3    56    DATE            YES     01/01/1800 NO
        SYSUSERI1    45    INTEGER         YES     0          NO
        SYSUSERI2    46    INTEGER         YES     0          NO
        SYSUSERI3    47    INTEGER         YES     0          NO
        SYSUSERR1    48    REAL            YES     0          NO
        SYSUSERR2    49    REAL            YES     0          NO
        SYSUSERR3    50    REAL            YES     0          NO
        SYSUSERT10   52    TEXT 10         YES     blanks     NO
        SYSUSERT40   53    TEXT 40         YES     blanks     NO
        SYSUSERT5    51    TEXT 5          YES     blanks     NO
        SYSUSRADRP   71    INTEGER         NO      0          YES
        SYSWRITE20   57    INTEGER         YES     1          YES


   See the section on system variables in the General Use chapter of  the
   User's Reference Manual.  DBSYSV respects the runtime conversion flags
   ______ _________ ______
   and the data type of VARIABLE-VALUE.

   Examples:

        Assume the following WORKING-STORAGE section:

             01 SVFETCH       PIC 9 COMP VALUE 0.
             01 SVSTORE       PIC 9 COMP VALUE 1.
             01 DATE-TODAY    PIC 9(10) COMP.
             01 RECS-FOUND    PIC 9(10) COMP.
|            01 LINE-VALUE    PIC 9(10) COMP.


        ENTER MACRO DBSYSV USING 15,SVSTORE,20.

             This sets SYSNRETRY to a value of 20.

        ENTER MACRO DBSYSV USING "SYSDATE", SVFETCH, DATE-TODAY.

             This puts today's date in  system-encoded  format  into  the
             item DATE-TODAY.

        ENTER MACRO DBSYSV USING "SYSNREC", SVFETCH, RECS-FOUND.

             This returns the number of  records  selected  by  the  most
             recent  find,  search,  or  map request, the same value that
             DBNREC returns.
   COBOL INTERFACE                                              Page 3-45
   Revision 5


|       ENTER DBSYSV USING "SYSCUSTDMI",2,DMIRDR.
|  
|            This stores the address of the routine DMIRDR in the  system
|            variable SYSCUSTDMI.
|  
|  DBSYSV can return and receive values  for  the  subscripted  variables
|  SYSLINE,  SYSPAGE,  SYSPCCOL,  SYSPCRESET,  and SYSPCROW only when the
|  subscript is omitted.  In this case, the subscript  1  is  assumed  by
|  default.  Thus,
|  
|       ENTER MACRO DBSYSV USING "SYSLINE", SVFETCH, LINE-VALUE
|  
|  reads the value of  the  system  variable  SYSLINE(1)  into  the  item
|  LINE-VALUE.  To receive or assign a value to a subscripted variable on
|  some channel other than 1, it is necessary to use a DBEXEC  call  (see
|  "Executing Interactive Commands and Procedures--DBEXEC").



   3.10.7.1  Value-passing With System Variables -- SYSUSER__

   The SYSUSER__ system variables can be used to pass values between host
   language  programs  and 1022 through calls to DBEXEC (see below).  The
   values are assigned and retrieved with DBSYSV.

   SYSUSERD1, SYSUSERD2, and SYSUSERD3 are used  for  dates.   SYSUSERI1,
   SYSUSERI2, and SYSUSERI3 are used for integers.  SYSUSERR1, SYSUSERR2,
   and SYSUSERR3 are used for real numbers.  SYSUSERT5 is used  for  text
   of up to 5 characters, SYSUSERT10 for text of up to 10 characters, and
   SYSUSERT40 for text of up to 40 characters.

   Examples:

        ENTER MACRO DBSYSV USING IVAR,SVFETCH,"SYSUSERI1"

             This sets SYSUSERI1 to the value of the variable IVAR.

        ENTER MACRO DBEXEC USING "LET SYSUSERD1 $FMONTH(BILL_DATE)"
        ENTER MACRO DBSYSV USING "SYSUSERD1",SVFETCH,NEWBIL

             This DBEXEC call uses a date function to give SYSUSERD1  the
             value  of  the  first  day  of  the  month  of the attribute
             BILL_DATE.  The DBSYSV call puts the value of SYSUSERD1 into
             the variable NEWBIL.



   3.10.8  Executing Interactive Commands And Procedures -- DBEXEC

   The DBEXEC routine executes any command in interactive System 1022, or
   transfers  control  completely  to interactive System 1022.  There are
   two forms to the ENTER:

   COBOL INTERFACE                                              Page 3-46
   Revision 5


        (1) ENTER MACRO DBEXEC.

        (2) ENTER MACRO DBEXEC USING CMD-STRING [, END-OF-COMMAND].

   DBEXEC is supported only in HR1022.REL, the reentrant version  of  the
   subroutine library.

   Use DBEXEC whenever you need to execute a 1022 command which cannot be
   performed  by  the  Host  Language  ENTERs.   An  ENTER  to DBEXEC has
   significantly  more  overhead  than  an  ENTER  to  the  other  System
   routines.   Most  retrieval,  sorting,  and  updating functions can be
   accomplished without DBEXEC, but report writing,  PL1022  programming,
   and  the  command  file capabilities of System 1022 require the DBEXEC
   subroutine.

   In addition, DBEXEC can transfer control to the interactive System and
   then  return  to the COBOL program, permitting interactive use of 1022
   in the middle of a program run.


   The ENTER to DBEXEC with no arguments in (1) above  transfers  control
   to  interactive  command  level.   All of the capabilities of 1022 are
   then available to the user.  The command:

        HOST

   returns control to the COBOL program at the  statement  following  the
   ENTER  to  DBEXEC.   Errors  are  handled  interactively until HOST is
   typed.

   The conditions in the data set are not altered by either the  call  to
   DBEXEC  or  the  HOST command.  For example, the user may find records
   for the program to process when it resumes, or the  program  can  find
   records  for  review  by  the user during the call (1) to DBEXEC.  The
   following COBOL fragment relies on the  user  to  create  the  desired
   selection group of records.

        * ENTER INTERACTIVE COMMAND LEVEL FOR THE USER TO
        * SELECT RECORDS.

                ENTER MACRO DBEXEC.

        * PROCESS SELECTED RECORDS WHEN THE USER
        * TYPES THE HOST COMMAND

        RECORD-LOOP.
                ENTER MACRO DBGREC USING OUT-OF-RECORDS.
                .    (Process records here)
                .
                GO TO RECORD-LOOP.
        OUT-OF-RECORDS.
                .
                .
   COBOL INTERFACE                                              Page 3-47
   Revision 5


   The ENTER to DBEXEC in (2) above  supplies  a  command  string  to  be
   executed.   This  is  either  a literal ("USE DAYRPT"), or a DISPLAY-7
   item containing a command string.

   The optional argument END-OF-COMMAND is  a  paragraph  name  to  which
   control  transfers  when 1022 requires more input text than appears in
   the  first  argument.   More  input  text  is  required  when  a  line
|  continuation  character  terminates  the  first argument, or the first
|  argument is an incomplete command or command  block.   Any  PL1022  or
|  report  program  segment or structured command must be fully specified
|  in a single ENTER to DBEXEC unless  the  END-OF-COMMAND  statement  is
|  specified.   The  continuation  is  supplied  to 1022 by repeating the
   ENTER to DBEXEC with the additional command line(s).

   An error occurs when the second argument is absent and more input text
   is required.  The DBERR routine controls such an error.  Examples:

   The following COBOL program reads  an  interactive  command  from  the
   user's terminal and passes it to the interactive System using DBEXEC.

   IDENTIFICATION DIVISION.
   PROGRAM-ID. EXAMP1.
   ENVIRONMENT DIVISION.

   DATA DIVISION.
   WORKING-STORAGE SECTION.
   01 CMD-STRING DISPLAY-7 PIC X(80).

   PROCEDURE DIVISION.
           ENTER MACRO DBCBL.
           ENTER MACRO DBOPEN USING "TEST".
   CMD-READ.
           ACCEPT CMD-STRING.
   *TRAP BACK TO THE ACCEPT STATEMENT IF CMD IS INCOMPLETE
           ENTER MACRO DBEXEC USING CMD-STRING,CMD-READ.
           ENTER MACRO DBEND.
           STOP RUN.

|  The following COBOL program executes a PL1022 segment in which the
|  user
|  is prompted to enter the names of attributes to which the interactive
|  1022 INFORM ATTRIBUTE command will apply.
|  
|  IDENTIFICATION DIVISION.
|  PROGRAM-ID.  ATTR-NAMES.
|  ENVIRONMENT DIVISION.
|  DATA DIVISION.
|  WORKING-STORAGE SECTION.
|  01 EXEC-STRING.
|     05 FILLER DISPLAY-7 PIC X(9)  VALUE IS "INF ATTR ".
|     05 ATTR-NAME   DISPLAY-7 PIC X(25).
|     05 FILLER DISPLAY-7 PIC X(8)  VALUE IS " LENGTH.".
|  PROCEDURE DIVISION.
|          ENTER MACRO DBCBL.
   COBOL INTERFACE                                              Page 3-48
   Revision 5


|          ENTER MACRO DBOPEN USING "FOO".
|          DISPLAY "Enter attribute names one per line; end with blank line".
|          ENTER MACRO DBEXEC USING "PL START .",MORE-IN.
|  MORE-IN.
|          ACCEPT ATTR-NAME.
|          IF ATTR-NAME NOT EQUAL SPACES
|             ENTER MACRO DBEXEC USING EXEC-STRING,MORE-IN.
|          ENTER MACRO DBEXEC USING "PL END .".
|          ENTER MACRO DBEND
|          STOP RUN.
   The following COBOL program uses DBEXEC.  It executes the command file
   WEEKLY.DMC, and then transfers full control to interactive System 1022
   command level.

   IDENTIFICATION DIVISION.
   PROGRAM-ID. EXAMP2.
   ENVIRONMENT DIVISION.
   DATA DIVISION.
   WORKING-STORAGE SECTION.
   77 ERR-TYPE COMP PIC 999.
   77 ERR-CODE COMP PIC 999.
   PROCEDURE DIVISION.
           ENTER MACRO DBCBL.
           ENTER MACRO DBERR USING ERROR-TRAP,ERR-TYPE,
                ERR-CODE,1.
           ENTER MACRO DBEXEC USING "USE WEEKLY.DMC".
           DISPLAY "WEEKLY RUN COMPLETED".
           ENTER MACRO DBEXEC.
   *RETURN HERE FROM INTERACTIVE MODE WHEN THE USER TYPES "HOST"
           GO TO FINISH-UP.

   ERROR-TRAP.
           DISPLAY "?WEEKLY RUN ABORTED DUE TO ERROR".
           DISPLAY "ERROR TYPE: ",ERR-TYPE.
           DISPLAY "ERROR CODE: ",ERR-CODE.
   COBOL INTERFACE                                             Page 3-48A
   Revision 5


   FINISH-UP.
           ENTER MACRO DBEND.
           STOP RUN.


   This program uses the routine  DBERR  to  transfer  to  the  paragraph
   ERROR-TRAP  in the event of an error while processing the command file
   WEEKLY.DMC.  This trapping is not enabled  while  the  program  is  in
   interactive  mode (during the second ENTER to DBEXEC) but it goes back
   into effect when control returns to the COBOL program.
|  
|  
|  
|  3.10.9  Passing Records In Nonstandard Format To 1022 -- DBLODR
|  
|  It is possible to load, append, and transact fixed-length  records  in
|  formats  other  than 7-bit ASCII, ASCII ISAM, SIXBIT, and SIXBIT ASCII
|  with a user-written host language routine that reads and reformats the
|  data and passes it to 1022 through the DBLODR routine, one record at a
|  time.   This  process  is  made  possible  by  the   system   variable
|  SYSCUSTDMI, which is set to the address of the user's data translation
|  routine, the DBSYSV routine, and the  CUSTDMI  keyword  of  the  LOAD,
|  APPEND, and TRANSACT commands.
|  
|  The general procedure for loading records in nonstandard format is  as
|  follows:
|  
|       1.  The user writes a host language program  that  calls  DBSYSV,
|           which  stores  the  address  of  the  user's data translation
|           routine in the system variable  SYSCUSTDMI.   You  store  the
|           address  of  the  data  translation  routine in SYSCUSTDMI by
|           specifying a 2 for the ACTION-FLAG  argument  in  the  DBSYSV
|           enter (see above).
|  
|       2.  The program then calls DBEXEC, specifying the LOAD (or APPEND
|           or TRANSACT) command with the appropriate DESC clause and the
|           keyword CUSTDMI.  The CUSTDMI keyword signals 1022 to use the
|           data   translation   routine   whose  address  is  stored  in
|           SYSCUSTDMI instead of using the standard DMI reader.
|  
|       3.  The user's data translation routine is then executed.  If you
|           are  running  TOPS-10,  your  data  translation  routine must
|           consist entirely of low-segment code.  If your  routine  uses
|           COBOL I/O, the COBOL run-time library must be forced into the
|           low segment as well.  If you are running TOPS-20, your  COBOL
|           data translation must either be compiled with the "/U" switch
|           or else must force the code into the  low  segment  with  the
|           link switch "/SEG:LOW."
|  
|           The user's data translation routine should do the following:
|  
|           a.  Open the file containing the data to be  reformatted  and
|               passed to 1022.
   COBOL INTERFACE                                             Page 3-48B
   Revision 5


|           b.  Read a record's worth of data into an array, reformatting
|               the data as needed.
|  
|           c.  Use the DBLODR enter to pass the contents of the array as
|               a single record to 1022.  The ENTER is:
|  
|                    ENTER DBLODR USING RECORD FLAG
|  
|               The DBLODR enter takes two arguments.  The first of these
|               (RECORD) is a DISPLAY-7 field (or, if SIXBIT is specified
|               in the data description file, a DISPLAY-6 field) to  hold
|               the  record  to  be  passed.  The second (FLAG) is a COMP
|               variable, which 1022 automatically resets to 0 unless  an
|               error is encountered or the record limit imposed by a MAX
|               clause is  reached.   A  0  setting  signals  the  user's
|               routine  that  1022  is ready to accept more data.  If an
|               error is encountered or the record limit imposed by a MAX
|               clause  is  reached,  1022  returns  a value of -1, which
|               signals the user's routine  that  1022  will  ignore  any
|               further input.
|  
|           d.  Repeat steps (a)-(c) until  the  desired  data  has  been
|               passed  from  the foreign source to 1022.  Then exit from
|               the data translation routine.
|  
|  
|       4.  Complete execution of the main program.
|  
|  System  1022  passes  a  number  of  arguments  to  the  user's   data
|  translation.   You  may  wish to hard-code these or ignore them.  They
|  are the following:
|  
|       1.  The file specification  (80  characters,  blank  padded,  the
|           extension ".DMI" not defaulted);
|  
|       2.  The number of columns of useful data in a  record,  that  is,
|           the  minimum  length  of the record image passed back through
|           DBLODR;
|  
|       3.  The length of the record in the source  file,  or  -1  if  of
|           variable length;
|  
|       4.  The user-specified format, encoded as 0 if ASCII, 1 if  ASCII
|           ISAM, -1 if SIXBIT ISAM, and -2 if SIXBIT;
|  
|       5.  The blocking factor, if specified;
|  
|       6.  The block size for magtapes, if specified.
|  
|  Example:
|  
|  The following COBOL program uses the data translation  routine  DMIRDR
|  to  read the contents of the file DIRECTDMI, loading the data into the
|  1022 data set DIRECT.  This program  must  be  compiled  with  the  /U
   COBOL INTERFACE                                             Page 3-48C
   Revision 5


|  switch.
|  
|  IDENTIFICATION DIVISION.
|  ENVIRONMENT DIVISION.
|  INPUT-OUTPUT SECTION.
|  FILE-CONTROL.
|          SELECT INPFILE ASSIGN TO DSK RECORDING MODE IS ASCII.
|  DATA DIVISION.
|  FILE SECTION.
|  FD INPFILE VALUE OF ID 'DIRECTDMI'.
|          01 INPREC USAGE DISPLAY-7 PIC X(120).
|  WORKING-STORAGE SECTION.
|          77 NUM COMP PIC 9(9).
|  
|  
|  PROCEDURE DIVISION.
|  
|          ENTER MACRO DBCBL.
|          ENTER MACRO DBSYSV USING "SYSCUSTDMI", 2, DMIRDR.
|          ENTER MACRO DBEXEC USING "LOAD DIRECT CUSTDMI".
|          ENTER MACRO DBEND.
|          STOP RUN.
|  
|  DMIRDR.
|          OPEN INPUT INPFILE.
|  DMIXXX.
|          READ INPFILE RECORD AT END GO TO READ-FIN.
|          ENTER MACRO DBLODR USING INPREC, NUM.
|          IF NUM = 0 GO TO DMIXXX.
|  READ-FIN.
|          ENTER MACRO DBRETN.
|          STOP RUN.
|  



   3.10.10  DBDBUG Routine


   DBDBUG is  an  ENTER  for  debugging  user  programs.   The  user  can
   determine  whether a program is inadvertently writing into 1022 memory
   areas and producing bugs.  The ENTER is:

        ENTER MACRO DBDBUG USING "MCHK", status .

   Where:

        'MCHK'    Is a display-7 literal.

        status    Is either "ON" or "OFF".  Status can be changed at  any
                  time  in  the execution of a program.  Status begins as
                  OFF.

   When status is "ON", 1022 generates a checksum at  the  beginning  and
   COBOL INTERFACE                                             Page 3-48D
   Revision 5


   end of each 1022 routine.  If, at the beginning of a 1022 routine, the
   newly generated checksum does not match the last one, 1022 prints:

        "%1022 Memory modified by user program"

   If 1022 can determine the location that was modified, it prints:

        "%1022 Memory modified by user program at location nnnnnn".

   System 1022 then continues execution.



   3.10.11  The DBVAR Routine


   The DBVAR routine determines if a 1022 user variable has been  defined
   and  returns  the  variable's type.  If type text, it also returns the
   text length.  The ENTER is:

        ENTER MACRO DBVAR USING NAME, TYPE [,LENGTH].

   Where:

        NAME      Is either a display-7 PIC  X(10)  working-storage  item
                  containing  a  1022  user variable name, or the literal
                  1022 variable name.

        TYPE      Is the COMP working-storage item that receives the 1022
                  variable type:

                  -1  UNDEFINED
                   0  INTEGER
                   1  REAL
                   2  TEXT
                   4  DATE
                  12  DOUBLE INTEGER

        LENGTH    Is the optional COMP working-storage item that receives
                  the length of the text variable.



   3.11  AUDIT ROUTINES

   The DBAUD  routine  controls  System  1022  audit  trails  from  COBOL
   programs.   The  program  may  record  its own audit trail entries, in
   addition to executing audit commands parallel to the interactive audit
   commands.
   COBOL INTERFACE                                             Page 3-48E
   Revision 5


   3.11.1  Starting The AUDIT Trail

   Start an audit file for the current data set with:

        ENTER MACRO DBAUD USING "START" [,"FILE",file]  [,"LOCK"][,"JOB"]
             [,"PRE"] [,"POST"] [,"NOMSG"] [,"AUTO"] [,"NOREAD"].

   where the optional keywords and possible  defaults  are  the  same  as
   those in the interactive AUDIT START command.



   3.11.2  Entering AUDIT File Checkpoints

   Enter checkpoints into the current audit file with:

        ENTER MACRO DBAUD USING "CHECK", checkname.

   which performs the same function as the AUDIT CHECKPOINT command.  The
   checkname argument is a DISPLAY-7 literal or item.



   3.11.3  Custom AUDIT Entries

   Audit file entry type codes 700 through 777  octal  (448  through  511
   decimal)  are reserved for users.  Insert these entries into the audit
   trail with:

        ENTER MACRO DBAUD USING "PLACE", CODE, LENGTH, ENTRY-DATA.
   COBOL INTERFACE                                             Page 3-48F
   Revision 5



























                     [ This page intentionally left blank ]
   COBOL INTERFACE                                              Page 3-49
   Revision 5


   Where:

   CODE        Is the code 448-511 that the program has assigned to  this
               entry.

   LENGTH      Is the length of the entry record in words.

   ENTRY-DATA  Is a WORKING-STORAGE record that contains the entry data.

   These entries are later read from the  audit  trail  with  the  DBAGET
   subroutine.



   3.11.4  Retrieving AUDIT File Information

   The DBAxxx family of routines accesses audit file entries from  COBOL,
   allowing  customized  audit  file  reports as well as the retrieval of
   program defined entries (codes 448-511).



   3.11.4.1  Initialization For AUDIT Retrievals

   Initialize reading the audit file with the following ENTER:

        ENTER MACRO DBAINI USING filename [,"ALL"].

   filename   Is the name of the audit trail file.

   "ALL"      Indicates that entries for data sets  other  than  the  one
              currently opened are also returned.

   After using DBAINI, entries may be retrieved from the audit trail with
   the command:

        ENTER MACRO DBAGET USING LEN-FLAGS, FLAGS, LEN-ENTRY, ENTRY, EOF.


   LEN-FLAGS  Is a COMP item holding the length of the FLAGS record.

   FLAGS      Receives information about the entry as follows.  LEN-FLAGS
              should contain 10 for the following record.
   COBOL INTERFACE                                              Page 3-50
   Revision 5


      01   FLAGS.
        02   ENTRY-TYPE                     PIC 999   COMP.
           88   DATA SET-OPEN-ENTRY         VALUE 4.
           88   AUDIT-TRAIL-STARTED-ENTRY   VALUE 5.
           88   COMMENT-ENTRY               VALUE 6.
           88   END-AUDIT-TRAILS-ENTRY      VALUE 9.
           88   DATA SET-CLOSED-ENTRY       VALUE 11.
           88   END-WRITE-OPERATION-ENTRY   VALUE 12.
           88   BEGIN-WRITE-OPERATION-ENTRY VALUE 13.
           88   CHECKPOINT-ENTRY            VALUE 14.
           88   CUSTOM-ENTRY                VALUES 448 THRU 511.
        02   ENTRY-LENGTH                   PIC 9999  COMP.
        02   DATA SET-HANDLE                PIC 9(10) COMP.
        02   ENTRY-DATE-TIME                PIC 9(10) COMP.
        02   PPN                            PIC 9(10) COMP.
        02   JOB-NUMBER                     PIC 999   COMP.
        02   CHECKPOINT-NUMBER              PIC 9(6)  COMP.
        02   HOST-LANGUAGE-FLAG             PIC 9     COMP.
           88   ENTRY-FROM-HL               VALUE 1.
           88   ENTRY-FROM-SA               VALUE 0.
        02   UPDATE-ON-FLAG                 PIC 9     COMP.
           88   ENTRY-HAD-UPDATE-ON         VALUE 1.
           88   ENTRY-HAD-UPDATE-OFF        VALUE 0.
        02   CHECKPOINT-FLAG                PIC 9     COMP.
           88   ENTRY-IS-CHECKPOINT         VALUE 1.
           88   ENTRY-IS-NOT-CHECKPOINT     VALUE 0.

        Notes:

        1.  ENTRY-DATE-TIME is in  universal  date-time  standard  format
            (TOPS-10) or in internal date and time format (TOPS-20).

        2.  PPN is the project-programmer number (TOPS-10) or  logged  in
            directory number (TOPS-20) of the program making the entry.


   LEN-ENTRY  Is a COMP item holding the length of the ENTRY record.

   ENTRY      Is the record that receives the entry from the audit  file.
              The length of each example entry record is 15.

   EOF        Is a COMP item returned as zero when the audit file is  not
              at  end-of-file.   If  EOF  is non-zero, the file is at the
              end, and no FLAGS or entry data are returned.

   The form of a program defined entry is identical to its form  when  it
   was placed into the audit file with DBAUD.



   The following System defined entries are returned.  Each code is shown
   as  octal,  and decimal "(n.)".  "user number" is the directory number
   pair on TOPS-20 systems or the project-programmer  number  on  TOPS-10
   systems.  Those entries marked "versions before 116" are returned by a
   COBOL INTERFACE                                              Page 3-51
   Revision 5


   version of 1022 earlier than 116 or from a data set  created  under  a
   version  earlier  than  116  which has not been transformed by an UPTO
   command into a 116-style data set.

   Entry type 4 (4.):  Data set Opened [Versions before 116]
   _____ ____ _ _____  ____ ___ ______

   01  THE-ENTRY.
       02   DATA SET-OPEN.
            03   DATA SET-NAME                  PIC X(25) DISPLAY-7.
            03   FILE-ID                        PIC 9(10) COMP.
            03   ACCESS-FLAG                    PIC 9     COMP.
               88   READ-ONLY-ACCESS            VALUE 1.
               88   NOT-READ-ONLY-ACCESS        VALUE 0.
            03   DAMAGED-FLAG                   PIC 9     COMP.
               88   FILE-NOT-DAMAGED            VALUE 0.
               88   FILE-DAMAGED                VALUE 1.
            03   AUTO-OPEN-FLAG                 PIC 9     COMP.
               88   AUDIT-AUTOMATICALLY-STARTED VALUE 0.
               88   EXPLICIT-AUDIT-START        VALUE 1.
            03   UPDATE-ON-FLAG                 PIC 9     COMP.
               88   STARTED-WITH-UPDATE-ON      VALUE 1.
               88   STARTED-WITH-UPDATE-OFF     VALUE 0.
            03   DATA SET-FILE-DIRECTORY        PIC 9(10) COMP.
            03   FILENAME                       PIC X(10) DISPLAY-7.
            03   DEVICENAME                     PIC X(10) DISPLAY-7.

   Notes:

        1.  AUDIT-AUTOMATICALLY-STARTED means that the  audit  trail  was
            opened  at the same time as the data set, as the result of an
            earlier AUDIT START AUTO command.

        2.  EXPLICIT-AUDIT-START means  that  the  data  set  was  opened
            before the audit trail was begun.



   Entry type 5 (5.):  Audit Trail Started
   _____ ____ _ _____  _____ _____ _______

       02   AUDIT-TRAIL-START      REDEFINES DATA SET-OPEN.
            03   THE-VERSION-NUMBER             PIC 999 COMP.
               88   PRESENT-VERSION             VALUE 0.
               88   BAD-VERSION-NUMBER          VALUES 1 THRU 999.
            03   FILLER                         PIC X(70) DISPLAY-7.


   Entry Type 6 (6.):  Comment
   _____ ____ _ _____  _______

       02   COMMENT     REDEFINES DATA SET-OPEN.
            05   COMMENT-TEXT                   PIC X(75) DISPLAY-7.

       A comment  may  be  longer.   Its  actual  length  (in  words)  is
       specified  by  ENTRY-LENGTH  in  FLAGS.   The user must expand all
       redefinitions if the comment item is lengthened.
   COBOL INTERFACE                                              Page 3-52
   Revision 5


   Entry type 7 (7.):  Pre-image Block
   _____ ____ _ _____  _________ _____

   Pre-image block.


   Entry type 10 (8.):  Post-image Block
   _____ ____ __ _____  __________ _____

   Post-image block.


   Entry type 11 (9.):  End Audit Trails
   _____ ____ __ _____  ___ _____ ______

       02   END-AUDIT-TRAIL     REDEFINES DATA SET-OPEN.
            03   FILLER                         PIC X(75) DISPLAY-7.


   Entry Type 13 (11.):  Data set Closed [Versions before 116]
   _____ ____ __ ______  ____ ___ ______

       02   DATA SET-CLOSED     REDEFINES DATA SET-OPEN.
                <IDENTICAL TO DATA SET-OPENED>


   Entry type 14 (12.):  End Write Operation
   _____ ____ __ ______  ___ _____ _________

   This entry is  generated  whenever  an  update  operation  ends.   For
   pre-image  audit  trails  this contains only a header.  For post-image
   audit trails this contains a checkpoint.

       02   END-WRITE-OPERATION     REDEFINES DATA SET-OPEN.
            03   FILLER                         PIC X(75) DISPLAY-7.


   Entry Type 15 (13.):  Begin Write Operation [Versions before 116]
   _____ ____ __ ______  _____ _____ _________

       02   BEGIN-WRITE-OPERATION     REDEFINES DATA SET-OPEN.
            03   FILLER                         PIC X(10) DISPLAY-7.
            03   FILE-SIZE                      PIC 9(6)  COMP.
            03   SET-SIZE                       PIC 9(6)  COMP.
            03   DAMAGE-DATE                    PIC 9(10) COMP.
               88   NO-DAMAGE-DATE              VALUE 0.
            03   DAMAGE-TIME                    PIC 9(10) COMP.
               88   NO-DAMAGE-TIME              VALUE 0.
            03   DAMAGE-USER                    PIC 9(10) COMP.
               88   NO-DAMAGE-USER              VALUE 0.
            03   NUMBER-ACTIVE-RECORDS          PIC 9(10) COMP.
            03   NUMBER-DELETED-RECORDS         PIC 9(10) COMP.
            03   NUMBER-ALLOCATED-RECORDS       PIC 9(10) COMP.
            03   LAST-UPDATE-NUMBER             PIC 9(10) COMP.
            03   LAST-UPDATE-DATE               PIC 9(10) COMP.
            03   LAST-UPDATE-TIME               PIC 9(10) COMP.
            03   LAST-UPDATE-PPN                PIC 9(10) COMP.
            03   ADMIT-FLAG                     PIC 9     COMP.
               88   ADMIT-CRITERIA-PRESENT      VALUE 1.
               88   ADMIT-CRITERIA-ABSENT       VALUE 0.
   COBOL INTERFACE                                              Page 3-53
   Revision 5


   Notes:

        1.  This entry may be used as a checkpoint.

        2.  FILE-SIZE is in blocks (4 blocks = 1 TOPS-20 page).

        3.  SET-SIZE is the size of the unbundled data set in words.

        4.  DAMAGE-DATE and LAST-UPDATE-DATE  are  in  radix  date  form.
            (See Appendix B.)

        5.  DAMAGE-TIME and LAST-UPDATE-TIME are  in  milliseconds  since
            midnight.

        6.  DAMAGE-USER is the user number of the data set  updater  when
            the file was damaged.

        7.  LAST-UPDATE-NUMBER is incremented whenever the  data  set  is
            opened for writing.

        8.  LAST-UPDATE-PPN is the project-programmer number (TOPS-10) or
            logged-in  directory  number  (TOPS-20)  of the last data set
            updater.



   Entry type 16 (14.):  Checkpoint [Versions before 116]
   _____ ____ __ ______  __________

       02   CHECKPOINT     REDEFINES DATA SET-OPEN.
            03   CHECKPOINT-NAME PIC X(10) DISPLAY-7.
                   <identical to BEGIN-WRITE-OPERATION starting
                     from FILE-SIZE>


   Entry type 17 (15.):  Begin Write Operation [Version 116 and later]
   _____ ____ __ ______  _____ _____ _________

   This entry is identical to Entry type 15 (Begin Write  Operations  for
   versions before 116) except that:

   For pre-image audit trails it contains a checkpoint.   For  post-image
   audit trails it contains only a header.


   Entry type 20 (16.):  Checkpoint Pre-image [Version 116 and later]
   _____ ____ __ ______  __________ _________ ________ ___ ___ ______

   This is a pre-image checkpoint entry, identical to Entry type 16.
   ____ __ _ _________ __________ ______ _________ __ _____ ____ ___


   COBOL INTERFACE                                              Page 3-54
   Revision 5


   Entry type 21 (17.):  Data set Opened [Version 116 and later]
   _____ ____ __ ______  ____ ___ ______

   01  THE-ENTRY.
       02   DATA SET-OPEN.
            03   DATA SET-NAME                  PIC X(25) DISPLAY-7.
            03   FILE-ID                        PIC 9(10) COMP.
            03   ACCESS-FLAG                    PIC 9     COMP.
               88   READ-ONLY-ACCESS            VALUE 1.
               88   NOT-READ-ONLY-ACCESS        VALUE 0.
            03   DAMAGED-FLAG                   PIC 9     COMP.
               88   FILE-NOT-DAMAGED            VALUE 0.
               88   FILE-DAMAGED                VALUE 1.
            03   AUTO-OPEN-FLAG                 PIC 9     COMP.
               88   AUDIT-AUTOMATICALLY-STARTED VALUE 0.
               88   EXPLICIT-AUDIT-START        VALUE 1.
            03   UPDATE-ON-FLAG                 PIC 9     COMP.
               88   STARTED-WITH-UPDATE-ON      VALUE 1.
               88   STARTED-WITH-UPDATE-OFF     VALUE 0.
            03   DATA SET-FILE-DIRECTORY        PIC 9(10) COMP.
            03   FILESPEC                       PIC X(30) DISPLAY-7.

       Notes:

        1.  AUDIT-AUTOMATICALLY-STARTED means that the  audit  trail  was
            opened  at the same time as the data set, as the result of an
            earlier AUDIT START AUTO command.

        2.  EXPLICIT-AUDIT-START means  that  the  data  set  was  opened
            before the audit trail was begun.



   Entry type 22 (18.):  Data Set Closed [Version 116 and later]
   _____ ____ __ ______  ____ ___ ______

   This entry is identical to Entry type 21, Data Set Opened.


   Entry type 23 (19.):  Checkpoint Post-image [Version 116 and later]
   _____ ____ __ ______  __________ __________

   This is a post-image checkpoint entry, identical to Entry type 16.



   3.11.4.2  Random Access AUDIT Trail Input

   The DBALOC routine sets the  position  in  the  audit  file  at  which
   reading  or  processing  begins.  It searches the audit file, counting
   checkpoints.  If DBALOC  is  not  called,  processing  starts  at  the
   beginning  of  the  audit  file.  DBAINI must be called before DBALOC.
   The ENTER is:

                                               {,[PRE]}
        ENTER MACRO DBALOC USING LOCODE, VALUE {      }.
                                               {,POST }
   COBOL INTERFACE                                              Page 3-55
   Revision 5


   Where:

   LOCODE  Is the locator code:

           0 = Start of file.
           1 = Checkpoint number N.
           2 = Checkpoint name N.
           3 = Last Nth checkpoint.
           4 = First Nth checkpoint.

   VALUE   Is a DISPLAY-7 name or COMP item as indicated by LOCODE.

   PRE     Specifies pre-images;  the default.

   POST    Specifies post-images.


   To begin input at checkpoint "HEREGOES", for example, the ENTER is:

        ENTER MACRO DBALOC USING 2, "HEREGOES".

   To begin input at the next to last post-image checkpoint:

        ENTER MACRO DBALOC USING 3, 2, "POST".

   To begin input at the last checkpoint:

        ENTER MACRO DBALOC USING 3, 1.



   3.11.5  Loading Programs Using DBAxxx Routines

   The DBAxxx routines are included only in HL1022.REL, but you may  want
   to  combine  them  with  programs searching HR1022.REL in order to use
   both DBEXEC and HL audit routines.  To load COBOL programs  with  both
   DBEXEC and DBAxxx ENTERs, issue the following commands:

         RUN LINK
        *NEW.REL
        *SYS:HR1022.REL/INCLUDE:(DBEXEC,EXECF.)
        *SYS:HL1022.REL/SEARCH
        *NEW.EXE/SAVE/GO
        *...(other LINK commands)...

   Note that not only must HR1022.REL be referenced before HL1022.REL but
   all  programs  linked  in  this  way  must be relinked each time a new
   System 1022 release is installed to avoid version skew errors.
   COBOL INTERFACE                                              Page 3-56
   Revision 5


   3.11.6  Examples

   The following program starts a LOCKed audit trail on the current  data
   set.   The  audit  file  has  an  extension equal to the program's job
   number.  A checkpoint (named  "STARTUP")  is  placed  into  the  audit
   trail, and the program continues.

               ENTER MACRO DBCBL.
               ENTER MACRO DBOPEN USING "PAYROL".
               ENTER MACRO DBAUD USING "START","LOCK","JOB".
               ENTER MACRO DBAUD USING "CHECK","STARTUP".
               .
               .
               .

   The following fragment writes  a  custom  audit  entry.   The  program
   accepts  the user's name and authorization code in the initialization.
   These values are placed in the custom audit entry with code 448.

   WORKING-STORAGE SECTION.
       01   FLAGS.
            02   ENTRY-TYPE           PIC 999    COMP.
       01   CUSTOM-ENTRY-SIZE         PIC 9      COMP VALUE 3.
       01   CUSTOM-ENTRY-NUMBER       PIC 999    COMP VALUE 448.
       01   CUSTOM-ENTRY.
            02   USER-NAME            PIC X(10) DISPLAY-7.
            02   AUTHORIZATION        PIC X(5)   DISPLAY-7.
       01   EOF-FLAG                  PIC 9      COMP.
           88     END-OF-AUDIT-FILE   VALUE 1.

   PROCEDURE DIVISION.
            .
            .
            .
            (INITIALIZATION - ACCEPT AND VERIFY
             NAME and AUCODE)
            .
            .
            .
       ENTER MACRO DBOPEN USING "PARTS".
       ENTER MACRO DBAUD
            USING "START","FILE","PRTAUD","LOCK".
       MOVE NAME TO USER-NAME IN CUSTOM-ENTRY.
       MOVE AUCODE TO AUTHORIZATION IN CUSTOM-ENTRY.
       ENTER MACRO DBAUD
            USING "PLACE",CUSTOM-ENTRY-NUMBER,
            CUSTOM-ENTRY-SIZE,CUSTOM-ENTRY.
            .
            .
            .
   COBOL INTERFACE                                              Page 3-57
   Revision 5


   In an application using the previous custom AUDIT ENTRY, the following
   program  fragment reports all users who have accessed the data set and
   their authorization codes.

            .
            .
            .
   START.
       ENTER MACRO DBCBL.
       ENTER MACRO DBAINI USING "PRTAUD.DML","ALL".
    
   LOOP.
       ENTER MACRO DBAGET USING
            1,FLAGS,CUSTOM-ENTRY-SIZE,CUSTOM-ENTRY,EOF-FLAG.
       IF END-OF-AUDIT-FILE   GOTO ALL-DONE.
       IF ENTRY-TYPE = CUSTOM-ENTRY-NUMBER
            DISPLAY USER-NAME,"       ",AUTHORIZATION.
       GOTO LOOP.

   ALL-DONE.
       STOP RUN.


   COBOL INTERFACE                                              Page 3-58
   Revision 5


   3.12  SAMPLE COBOL PROGRAMS

   The following is a sample 1022 COBOL  application  program.   All  the
   persons  whose first name is FRED are selected from a data set.  Then,
   their social security number is typed, followed by  a  question  mark.
   The user replies Y or N.  If the user replies Y, the record is deleted
   from the data set.  If the user replies N, the record is kept, and the
   person's age is incremented by one.

   IDENTIFICATION DIVISION.
   PROGRAM-ID. EXAMPL1.
   REMARKS. DEMONSTRATE 1022 SUBPROGRAM USAGE.
   ENVIRONMENT DIVISION.
   DATA DIVISION.
   WORKING-STORAGE SECTION.
   01 PERSON-RECD.
            02 NAME DISPLAY-7.
             03 FNAME SYNC LEFT PIC X(12).
             03 LNAME SYNC LEFT PIC X(18).
            02 SSN COMP PIC 9(9).
            02 AGE COMP PIC 9(3).
   77 Y-OR-N DISPLAY-7 PIC X.
   PROCEDURE DIVISION.
   *INITIALIZE 1022 AND OPEN DATA SET
            ENTER MACRO DBCBL.
            ENTER MACRO DBOPEN USING "PSN".
   *FIND THE RECORDS WITH FNAME=FRED
            ENTER MACRO DBFIND USING "FNAME","EQ","FRED".
   *LOOP FOR EACH RECORD FOUND IN LOCAL MODE
   LOOP1.
            ENTER MACRO DBGET USING PERSON-RECD, DONE.
            DISPLAY SSN, " ? " WITH NO ADVANCING.
            ACCEPT Y-OR-N.
            IF Y-OR-N IS EQUAL TO "Y" GO TO DELREC.
   *INCREMENT AGE BY 1 IF OPERATOR RESPONSE IS "N"
            ADD 1 TO AGE.
            ENTER MACRO DBCHNG USING "AGE",AGE.
            GO TO LOOP1.
   *DELETE RECORD IF OPERATOR RESPONSE IS "Y"
   DELREC.
            ENTER MACRO DBDEL.
            GO TO LOOP1.
   *HERE WHEN ALL RECORDS PROCESSED
   DONE.
            ENTER MACRO  DBEND.
            STOP RUN.
   COBOL INTERFACE                                              Page 3-59
   Revision 5


   The following is a more advanced COBOL application program.
   Because this program uses DBEXEC, it must be loaded with HR1022.REL.

   IDENTIFICATION DIVISION.
   *THIS PROGRAM INTERACTIVELY CORRECTS ERRORS IN A DATA SET AFTER IT
   *   HAS BEEN LOADED.  IT PROMPTS FOR THE NAME OF THE DATA SET AND
   *   AN ERROR LOG FILE AND THEN CREATES AN UNBUNDLED DATA SET FOR
   *   THE ERROR FILE.  USING THE TWO DATA SETS, IT GOES THROUGH THE
   *   ERROR DATA SET AND LOCATES THE CORRESPONDING RECORDS WITH
   *   ERRORS.  THE USER CHOOSES TO DELETE, IGNORE, OR CORRECT THE
   *   BAD RECORD.

   ENVIRONMENT DIVISION.
   INPUT-OUTPUT SECTION.
   FILE-CONTROL.
            SELECT DESCRIPTION-FILE ASSIGN TO DSK.

   DATA DIVISION.
   FILE SECTION.
   FD       DESCRIPTION-FILE
                    VALUE OF ID IS "CORRECDMD"
                    RECORDING MODE IS ASCII
                    DATA RECORD IS DESCRIPTION-RECORD.

   01       DESCRIPTION-RECORD DISPLAY-7 PIC X(25).

   WORKING-STORAGE SECTION.

   01       DR1 PIC X(18) VALUE "ATTR ID INT LEN 10".
   01       DR2 PIC X(8)  VALUE "FILLER 3".
   01       DR3 PIC X(21) VALUE "ATTR NAME TEXT LEN 25".
   01       DR4 PIC X(8)  VALUE "FILLER 1".
   01       DR5 PIC X(19) VALUE "ATTR WHY TEXT LEN 6".
   01       DR6 PIC X(8)  VALUE "FILLER 1".
   01       DR7 PIC X(21) VALUE "ATTR DATA TEXT LEN 24".

   01       COMMAND-BUFFER DISPLAY-7.
            02      FILLER PIC X(41) VALUE
                    "CREATE NOMSG SET CORREC DESC CORREC DATA ".
            02      ERROR-FILE PIC X(20) VALUE SPACES.

   01       DATA SET-NAME DISPLAY-7 PIC X(20) VALUE SPACES.

   01       ANSWER DISPLAY-7 PIC X.
            88      DELETE-RECORD VALUE "D".
            88      IGNORE-RECORD VALUE "I".
            88      CHANGE-RECORD VALUE "C".
            88      QUIT   VALUE "Q".
            88      YES    VALUE "Y".

   01       RECORD-NUMBER COMP PIC S9(9) VALUE ZERO.
   01       NUMBER-OF-RECORDS COMP PIC S9(9) VALUE ZERO.
   01       RECORD-ID COMP PIC S9(9) VALUE ZERO.
   01       SCRATCH COMP PIC S9(9) VALUE ZERO.
   COBOL INTERFACE                                              Page 3-60
   Revision 5



   PROCEDURE DIVISION.

   *INITIALIZE FOR COBOL

            ENTER MACRO DBCBL.

   *READ DATA SET NAME AND OPEN IT.  TRY AGAIN IF IT IS NOT THERE.

   READ-DATA SET.
            DISPLAY " ". DISPLAY " ".
            DISPLAY "DATA SET:" WITH NO ADVANCING.
            ACCEPT DATA SET-NAME.
            ENTER MACRO DBERR USING READ-DATA SET,SCRATCH,SCRATCH,-1.
            ENTER MACRO DBOPEN USING DATA SET-NAME.

   *READ NAME OF 1022 ERROR LOG FILE

            DISPLAY "ERROR FILE:" WITH NO ADVANCING.
            ACCEPT ERROR-FILE.

   *CREATE AN UNBUNDLED DATA SET FOR THE ERROR FILE.  FIRST,
   *   WRITE OUT A DESCRIPTION (.DMD) FILE.

            OPEN OUTPUT DESCRIPTION-FILE.
            WRITE DESCRIPTION-RECORD FROM DR1.
            WRITE DESCRIPTION-RECORD FROM DR2.
            WRITE DESCRIPTION-RECORD FROM DR3.
            WRITE DESCRIPTION-RECORD FROM DR4.
            WRITE DESCRIPTION-RECORD FROM DR5.
            WRITE DESCRIPTION-RECORD FROM DR6.
            WRITE DESCRIPTION-RECORD FROM DR7.
            CLOSE DESCRIPTION-FILE.

   *ALL 1022 ERRORS ARE FATAL FROM NOW ON

            ENTER MACRO DBERR USING END-OF-JOB,SCRATCH,SCRATCH,-1.

   *NOW CREATE THE UNBUNDLED DATA SET

            ENTER MACRO DBEXEC USING COMMAND-BUFFER.

   *OPEN THE UNBUNDLED DATA SET AND KEY UP THE ID ATTRIBUTE

            ENTER MACRO DBOPEN USING "NOCLOSE","CORREC".
            ENTER MACRO DBEXEC USING "KEY NOMSG ID".

   *TELL THE USER THE SIZE OF THE ERROR FILE

            ENTER MACRO DBFIND USING "ALL".
            ENTER MACRO DBNREC USING NUMBER-OF-RECORDS.
            DISPLAY " ". DISPLAY " ".
            DISPLAY NUMBER-OF-RECORDS," LINES IN ERROR FILE".

   COBOL INTERFACE                                              Page 3-61
   Revision 5


   *QUIT NOW IF THIS WOULD BE A WASTE OF TIME

            IF NUMBER-OF-RECORDS EQUAL 0 GO TO END-OF-JOB.

   *TELL THE USER THE NUMBER OF RECORDS WITH ERRORS IN THE
   *   DATA SET IF HE WANTS IT.

            DISPLAY " ".
            DISPLAY "WANT NUMBER OF BAD RECORDS? " WITH NO ADVANCING.
            ACCEPT ANSWER.
            IF NOT YES GO TO DISPLAY-OPTIONS.

            ENTER MACRO DBMAP USING 1,"ID","SYSID".
            ENTER MACRO DBNREC USING NUMBER-OF-RECORDS.
            DISPLAY " ".
            DISPLAY NUMBER-OF-RECORDS," RECORDS WITH ERRORS".
            DISPLAY " ". DISPLAY " ".

   *TELL THE USER WHAT HIS OPTIONS WILL BE

   DISPLAY-OPTIONS.
            DISPLAY "OPTIONS ARE:".
            DISPLAY "D -- DELETE THE RECORD".
            DISPLAY "I -- IGNORE THE RECORD".
            DISPLAY "Q -- QUIT NOW".
            DISPLAY "C -- CHANGE RECORD WITH 1022,".
            DISPLAY "     TYPE 'HOST' WHEN DONE".
            DISPLAY " ". DISPLAY " ".

   *SET UP THE RECORD POINTER

            MOVE 1 TO RECORD-NUMBER.

   *THIS IS THE PROGRAM LOOP

   LOOP.

   *POINT TO ERROR DATA SET
            ENTER MACRO DBSET USING 2.
   *FIND ALL RECORDS
            ENTER MACRO DBFIND USING "ALL".
   *GET FIRST RECORD IN NEXT GROUP
            ENTER MACRO DBGREC USING END-OF-JOB,RECORD-NUMBER.
   *READ THE ID ATTRIBUTE
            ENTER MACRO DBVAL USING "ID",RECORD-ID.
   *FIND ALL RECORDS WITH THAT ID
            ENTER MACRO DBFIND USING "ID","EQ",RECORD-ID.
   *HOW MANY WE FOUND
            ENTER MACRO DBNREC USING NUMBER-OF-RECORDS.
   *BUMP POINTER FOR NEXT TIME
            ADD NUMBER-OF-RECORDS TO RECORD-NUMBER.

   *TYPE THE ID AND THE DATA FROM THE ERROR DATA SET

   COBOL INTERFACE                                              Page 3-62
   Revision 5


            DISPLAY " ". DISPLAY " ".
            DISPLAY "SYSID: ",RECORD-ID.
            DISPLAY " ".
            ENTER MACRO DBEXEC USING "PRINT NAME DATA WHY
   -                " FMT 'ATTR:' A ' DATA:' A ' REASON:' A END".
            DISPLAY " ".

   *LOCATE THE CORRESPONDING RECORDS IN THE REAL DATA SET

            ENTER MACRO DBSET USING 1.
            ENTER MACRO DBFIND USING "SYSID","EQ",RECORD-ID.

   *FIND OUT WHAT HE WANTS TO DO AND DO IT

            DISPLAY "OPTION? " WITH NO ADVANCING.
            ACCEPT ANSWER.

            IF DELETE-RECORD ENTER MACRO DBDEL, GO TO LOOP.
            IF IGNORE-RECORD GO TO LOOP.
            IF QUIT          GO TO END-OF-JOB.
            IF CHANGE-RECORD ENTER MACRO DBEXEC.
            GO TO LOOP.

   *HERE WHEN ALL DONE. CLEAN UP AND EXIT.

   END-OF-JOB.
            ENTER MACRO DBEXEC USING
                    "FILE DELETE CORREC.DMD. FILE DELETE CORREC.DMS".
            ENTER MACRO DBEND.
            STOP RUN.

     












                                 CHAPTER 4

                      THE SYSTEM 1022 MACRO INTERFACE



   4.1  INTRODUCTION

   System 1022 interfaces to a MACRO program in the same way it does to a
   FORTRAN  program.   Data  types, descriptions, and conventions are the
   same.  This chapter describes how to construct a MACRO subroutine call
   which parallels any FORTRAN call.

   Two resources must be shared between the MACRO program and 1022  which
   are not used directly from a high level language such as FORTRAN.  The
   resources are monitor I/O channels and runtime memory.  1022  provides
   routines for requesting and releasing these resources.

   The resource allocation routines are  the  same  ones  called  by  the
   FORTRAN  object  time  system  when  resources are needed by a FORTRAN
   program.  A result is that combination MACRO and FORTRAN programs work
   properly  when  the  MACRO  portions  follow the conventions described
   here.  Further, a sophisticated FORTRAN  program  can  call  the  1022
   memory allocation routine to dynamically allocate array storage.

   Any language can be interfaced to System 1022.  Modify the object time
   system for the language to use the System 1022 allocation routines.
   THE SYSTEM 1022 MACRO INTERFACE                               Page 4-2
   Revision 5


   4.2  SUBROUTINE LINKAGE

   The MACRO subroutine call to System routines is the same  as  the  one
   used by FORTRAN.  The form is:

                .
                .
                .
                MOVEI   16, ARGS
                PUSHJ   17, DBXXXX##
                  ; RETURN HERE -- ACS 0-16 ARE DESTROYED
                .
                .
                .
                XWD     -n, 0           ;ARGUMENT LIST HEADER
        ARGS:   XWD     0, ARG1
                XWD     0, ARG2
                .
                .
                .
                XWD     0, ARGn
                .
                .
                .
        ARG1:   BLOCK 1         ; BLOCK LENGTHS ARE EXAMPLES ONLY
        ARG2:   BLOCK 3
                .
                .
                .
        ARGn:   BLOCK 2


   The above is the machine code generated by  the  following  FORTRAN-10
   call:

        CALL DBXXXX (ARG1, ARG2, ..., ARGn)


   Any accumulators may change from the execution of  a  System  routine,
   except the stack register AC17.

   The FORTRAN language CALLs are  used  to  describe  the  routines  and
   arguments  that  follow.  Construct equivalent calls directly in MACRO
   by using the universal file shown in this  chapter  and  available  in
   machine readable form on the System 1022 distribution tape.

   All text arguments must be space-filled, not null-filled.
   THE SYSTEM 1022 MACRO INTERFACE                               Page 4-3
   Revision 5


   4.3  INITIALIZATION

   Call DBMAC to initialize 1022 for  MACRO  use.   DBMAC  is  the  first
   routine which is called, before other routines can be used.  DBMAC has
   no arguments, but AC16 must be properly set  to  indicate  this.   For
   example:

            MOVEI   16,1+[0]
            PUSHJ   17,DBMAC##

   After initialization, the user may call any System routines, using the
   same arguments as in FORTRAN.

   System 1022 running  under  the  TOPS-20  operating  system  uses  the
   compatibility package PA1050 at its default location.

   Combined FORTRAN and MACRO programs are initialized by a call to DBFOR
   if the FOROTS system is used.  Do not call DBMAC in this case.



   4.4  MEMORY MANAGEMENT

   1022 is not affected by memory allocation  done  before  the  call  to
   DBMAC.

   The call to DBMAC  allocates  core  for  System  use  at  the  address
   contained  in  location  .JBFF.   .JBFF  is  always set to point to an
   address one greater than the last word of assigned memory.

   After initialization of 1022, the program must  allocate  memory  only
   through  the  routine  DBCORE.   Calls to DBCORE allocate space in one
   continuous region which grows  and  shrinks  with  repeated  requests.
   This  region  begins  after  the  MACRO  program, in runtime allocated
   memory.  Memory is zeroed when allocated.  The addresses of  allocated
   blocks of memory do not change after allocation.

   The call is:

        CALL DBCORE (LENGTH, ADDRESS)

   Where:

        LENGTH    Is the number of words of memory needed.

        ADDRESS   Receives the  address  of  the  first  word  of  memory
                  allocated  by  the  call.  ADDRESS is returned with the
                  value 0 if the memory is not available.

   Call DBCORE with a negative number of words to release that number  of
   words  from  the  memory  area.   These  words are freed from the last
   allocations of memory, from the end of  the  allocation  region.   The
   ADDRESS argument is returned as zero if the request failed, or nonzero
   normally.  Failure of a deallocation is unlikely.   Under  TOPS-10  it
   THE SYSTEM 1022 MACRO INTERFACE                               Page 4-4
   Revision 5


   may indicate that the program's runtime core limit has changed.



   4.4.1  Allocating Dynamic Arrays

   A three argument call to DBCORE allocates dynamic  arrays.   The  call
   is:

        CALL DBCORE (LENGTH, OFFSET, IBASE)

   Where:

        LENGTH    Is the number of words to allocate.

        OFFSET    Is returned as the offset to  the  first  word  of  the
                  allocated area, or as zero if the request failed.

        IBASE     Is  the  base  address  from  which   the   offset   is
                  calculated, and is supplied by the user.

   The address of the memory area allocated by  this  call  is  therefore
   IBASE + OFFSET.

   As an example, consider how this call is used in FORTRAN  to  allocate
   an array at runtime:

        INTEGER A(1)
           .
           .
           .
        CALL DBCORE (100, POS, A)

   The array A is the address used as a base for  the  future  references
   into  the  allocated  area.   The  N'th  word of the 100 word array is
   referenced  by  writing  the  FORTRAN  subscripted   array   reference
   A(POS+N).
   THE SYSTEM 1022 MACRO INTERFACE                               Page 4-5
   Revision 5


   4.5  I/O MANAGEMENT

|  On TOPS-20, programs can request JFN's (Job File Numbers) directly and
|  will  not  conflict  with  1022.  Because 1022 does not use the PA1050
|  compatibility package, TOPS-10 programs that are run under TOPS-20 may
|  use their own I/O system.
|  
|  On TOPS-10, 1022 uses extended channels if provided by the  particular
|  version of the operating system.  In this case, users may manage their
|  own  channels  without  conflict.   If  extended  channels   are   not
|  supported,  1022  automatically  uses  the  original  I/O  scheme that
|  provides 16 channels.  The value of  the  system  variable  SYSNOXCHAN
|  indicates whether or not extended channels are available.  If they are
|  not available, the MACRO program cannot assign them directly, but must
|  assign them through the DBCHAN routine.

   The call is:

        CALL DBCHAN (ICHAN)

   Where:

   ICHAN is  ZERO to request any available channel.  The assigned channel
             number  is returned in ICHAN.  There are no free channels if
             zero is returned.

             POSITIVE to  request  a  particular  channel  number.   That
             channel is in use if ICHAN is returned as zero.

             NEGATIVE to release the channel number which is the absolute
             value of ICHAN.  Do not release channels which have not been
             previously assigned.

   It is impossible to request channel 0 through DBCHAN.   Channel  0  is
   always used by 1022, and cannot be used by the MACRO program.



   4.6  LOADING MACRO PROGRAMS

   Load MACRO programs with  either  the  HL1022.REL  (non reentrant)  or
   HR1022.REL (reentrant) library.

   MACRO programs using HL1022 may be loaded into either the low or  high
   segments.   The resulting program contains all needed System routines,
   and needs no special object time system.


   The HR1022 library loads only into the low segment under TOPS-10.   It
   interfaces  at  runtime  to  a  separate  high  segment containing the
   program's object time system and System 1022 routines.  The user  must
   build  this  high  segment  using  the 1022SA program which is part of
   System 1022.  See the System 1022 Data Base Administrator's manual.
   THE SYSTEM 1022 MACRO INTERFACE                               Page 4-6
   Revision 5


   The HR1022 library may be loaded into the high segment under  TOPS-20.
   Information  is  written during initialization into the body of HR1022
   in the high segment, which is not allowed under TOPS-10.



   4.7  SUMMARY

   The MACRO program must interface  with  System  1022  I/O  and  memory
   management operations.

   Initialization

            MOVEI   16,1+[0]
            PUSHJ   17,DBMAC##

   ALLOCATE N Words of CORE

            MOVEI   16,1+[EXP <-2,,0>,[N],ADR]
            PUSHJ   17,DBCORE##
            SKIPN   ADR
            JRST    NOCORE
                            ;ADDRESS OF CORE IN ADR

   DEALLOCATE N Words of CORE

            MOVEI   16,1+[EXP <-2,,0>,[-N],ADR]
            PUSHJ   17,DBCORE##
            SKIPN   ADR
            JRST    NOCORE          ;SHOULD NOT HAPPEN

   REQUEST CHANNEL N

            MOVEI   16,1+[EXP <-1,,0>,CHAN]
            MOVEI   AC,N
            MOVEM   AC,CHAN
            PUSHJ   17,DBCHAN##
            SKIPN   CHAN
            JRST    NOCHAN

   RESERVE NEXT FREE CHANNEL

            MOVEI   16,1+[EXP <-1,,0>,CHAN]
            SETZM   CHAN
            PUSHJ   17,DBCHAN##
            SKIPN   CHAN
            JRST    NOCHAN

   RETURN CHANNEL N TO THE SYSTEM

            MOVNI   AC,N
            MOVEM   AC,CHAN
            MOVEI   16,1+[EXP <-1,,0>,CHAN]
            PUSHJ   17,DBCHAN##
   THE SYSTEM 1022 MACRO INTERFACE                               Page 4-7
   Revision 5


   4.8  EXAMPLE MACRO PROGRAM

   The following is a sample MACRO application program.

   ;THIS PROGRAM ASSUMES CHART.DMS IS A DATA SET WHOSE ATTRIBUTES ARE:
   ;        NAME --         TEXT, LENGTH 25, PERSON'S NAME
   ;        EMPNO --        INTEGER, PERSON'S EMPLOYEE NUMBER
   ;        BOSSNO --       INTEGER, EMPLOYEE NUMBER OF PERSON
   ;                        THAT THIS PERSON REPORTS TO.  BOSSNO IS ZERO
   ;                        IF THE PERSON IS THE BOSS OF EVERYBODY.
   ;THIS PROGRAM PRINTS AN ORGANIZATION CHART FROM THE DATA SET IN
   ;   THE FORM:
   ;        BOSS'S NAME
   ;            LEVEL 2 NAME
   ;                LEVEL 3 NAME
   ;                LEVEL 3 NAME
   ;            LEVEL 2 NAME
   ;                LEVEL 3 NAME
   ;        ETC.....
   ;THE ONLY LIMIT ON THE NUMBER OF LEVELS IS THE AMOUNT OF USER CORE.
   ;THE DATA SET IS OPENED AS MANY TIMES AS THERE ARE LEVELS IN THE
   ;CHART, BUT 1022'S CHANNEL POOLING ENSURES THAT EACH INCARNATION
   ;OF THE DATA SET HAPPENS ON THE SAME CHANNEL.
   ;THE MAIN ROUTINE RECURSIVELY CALLS ITSELF TO PRINT THE NAMES ON
   ;THE NEXT LEVEL.

   ;        TITLE CHART -- PRINT ORGANIZATION CHART

            T1=1            ;SCRATCH AC
            AG=16           ;ARG LIST POINTER
            P=17            ;STACK POINTER

            STKLEN==500     ;STACK LENGTH

   ;IT STARTS HERE

   CHART:   RESET                   ;CLEAR THE WORLD
            MOVE    P,[IOWD STKLEN,STACK] ;SET UP STACK PTR

            MOVEI   AG,1+[0]        ;INIT THE MACRO INTERFACE
            PUSHJ   P,DBMAC##

            MOVEI   AG,ARG1         ;* OPEN CHART
            PUSHJ   P,DBOPEN##

            MOVEI   AG,ARG2         ;* FIND BOSSNO EQ 0
            PUSHJ   P,DBFIND##      ;FINDS THE BOSS

            MOVEI   T1,1
            MOVEM   T1,DSNUM        ;CURRENT DATA SET NUMBER
            MOVEM   T1,DSHIGH       ;HIGHEST DATA SET THAT IS OPEN

            PUSHJ   P,SUBR          ;CALL ROUTINE TO DO THE WORK

   THE SYSTEM 1022 MACRO INTERFACE                               Page 4-8
   Revision 5


   ;HERE WHEN EVERYTHING HAS BEEN PRINTED

            MOVEI   AG,1+[0]
            PUSHJ   P,DBEND##       ;LET 1022 CLEAN THINGS UP
            EXIT                    ;EXIT

   ;SUBROUTINE THAT DOES ALL THE WORK

   SUBR:    MOVEI   AG,ARG3         ;* DBSET DSNUM
            PUSHJ   P,DBSET##       ;POINT TO DATA SET

            MOVEI   AG,ARG4         ;* GETREC DONE
            PUSHJ   P,DBGREC##      ;GET NEXT REC, GOTO DONE WHEN DONE

            MOVEI   AG,ARG5         ;* LET PNAME EQ NAME
            PUSHJ   P,DBVAL##       ;PUT NAME INTO PNAME

            MOVE    T1,DSNUM        ;FETCH DATA SET NUMBER
            SOJE    T1,SUBR1        ;JUMP IF NO INDENTING NEEDED
            ASH     T1,2            ;COMPUTE 4*(LEVEL#-1)
            OUTCHR  [" "]           ;OUTPUT THAT MANY SPACES
            SOJG    T1,.-1

   SUBR1:   OUTSTR  PNAME           ;OUTPUT THE NAME
            OUTSTR  [BYTE (7) 15,12,0] ;AND A CRLF

            MOVE    T1,DSHIGH       ;FETCH HIGHEST DATA SET NUMBER
            SUB     T1,DSNUM        ;SUBTRACT CURRENT DATA SET NUMBER
            JUMPG   T1,SUBR2        ;JUMP IF NEXT LEVEL ALREADY OPEN

            MOVEI   AG,ARG6         ;* OPEN NOCLOSE CHART
            PUSHJ   P,DBOPEN##      ;OPEN DATA SET FOR NEXT LEVEL

   SUBR2:   MOVEI   AG,ARG3         ;* DBSET DSNUM
            PUSHJ   P,DBSET##       ;POINT BACK TO THIS LEVEL

            AOS     T1,DSNUM        ;INCREMENT DATA SET NUMBER
            CAMLE   T1,DSHIGH       ;IS THIS HIGHEST LEVEL SO FAR?
             AOS    DSHIGH          ;NO--MAKE IT SO

            MOVEI   AG,ARG7         ;* MAP TO DSNUM VIA EMPNO TO BOSSNO
            PUSHJ   P,DBMAP##       ;FIND EMPLOYEES AT NEXT LEVEL

            PUSHJ   P,SUBR          ;RECURSE TO PRINT NEXT LEVEL
            JRST    SUBR            ;CONTINUE PRINTING THIS LEVEL

   ;HERE WHEN GETREC ABOVE FAILS
   DONE:    SOS     DSNUM           ;DECREMENT DATA SET NUMBER
            POPJ    P,              ;RETURN FROM THIS SUBROUTINE

   ;DATA STORAGE AND ARGUMENT LISTS

   STACK:   BLOCK   STKLEN          ;PUSHDOWN STACK
   DSNUM:   BLOCK   1               ;CURRENT DATA SET NUMBER
   THE SYSTEM 1022 MACRO INTERFACE                               Page 4-9
   Revision 5


   DSHIGH:  BLOCK   1               ;HIGHEST DATA SET OPENED
   PNAME:   BLOCK   6               ;HOLDS THE NAME ATTRIBUTE

            -1,,0
   ARG1:    0,,[ASCIZ/CHART     /]  ;* OPEN CHART

            -3,,0
   ARG2:    0,,[ASCIZ/BOSSNO    /]  ;* FIND BOSSNO EQ 0
            0,,[ASCIZ/EQ   /]
            0,,[0]

            -1,,0
   ARG3:    0,,DSNUM                ;* DBSET DSNUM

            -1,,0
   ARG4:    0,,DONE                 ;* GETREC DONE

            -2,,0
   ARG5:    0,,[ASCIZ/NAME /]       ;* LET PNAME EQ NAME
            0,,PNAME

            -2,,0
   ARG6:    0,,[ASCIZ/NOCLOSE   /]  ;* OPEN NOCLOSE CHART
            0,,[ASCIZ/CHART     /]

            -3,,0
   ARG7:    0,,DSNUM                ;* MAP TO DSNUM VIA EMPNO TO BOSSNO
            0,,[ASCIZ/EMPNO     /]
            0,,[ASCIZ/BOSSNO    /]

            END     CHART
   THE SYSTEM 1022 MACRO INTERFACE                              Page 4-10
   Revision 5


   4.9  THE S1022$ MACRO DEFINITION

   The following file defines the S1022$ macro.   It  is  distributed  in
   machine readable form on the System 1022 distribution tape.  Reference
   this macro to define the $1022 macro call for building argument  lists
   in  the proper form for calling System 1022 routines.  Useful keywords
   are defined as labels for convenience in specifying them.

             UNIVERSAL       S1022
             SUBTTL  JOHN L. MOSS, SOFTWARE HOUSE, 1979

   ;TO INCLUDE THESE DEFINITIONS IN A MACRO PROGRAM, INVOKE THE
   ;S1022$ MACRO.

   DEFINE S1022$,<

   ;$1022 - MACRO TO GENERATE 1022 ARGUMENT LISTS FROM MACRO CODE
   ;
   ;Call is:
   ;         $1022   (<routine>,<argument list>)
   ;
   ;The macro generates a call to the routine via PUSHJ 17, after
   ;declaring the routine external. The argument list contains the
   ;addresses of data as in a FORTRAN call. $1022 sets up the argument
   ;list, points to it in AC16, and calls the routine.
   ;
   ;$1022 calls the routine $SAVAC to save ACs on the stack before
   ;calling the 1022 subroutine. It calls $RETAC to retrieve the ACs
   ;from the stack when the subroutine returns in line. If the subroutine
   ;does not return in line, the user must call $RETAC to retrieve the
   ;stored ACs or subsequent POPJs will not operate properly.
   ;
   DEFINE $1022($DBNAM,$ARGS),<
             .ARG.==0
             IRP <$ARGS>,<
                     .ARG.==.ARG.+1
                 >
             MOVEI   16,[     -.ARG.,,0
             IRP <$ARGS>,<
                             $ARGS> ]+1
             PUSHJ   17,$SAVAC
             PUSHJ   17,$DBNAM##
             PUSHJ   17,$RETAC
   PURGE     .ARG.
   >

   DEFINE MPUSH(ACS),< IRP <ACS>,<PUSH 17,ACS>>
   DEFINE MPOP(ACS),<IRP <ACS>,<POP 17,ACS>>
   THE SYSTEM 1022 MACRO INTERFACE                              Page 4-11
   Revision 5


   $SAVAC:
             EXCH    0,(17)          ;"PUSH" AC0
             MPUSH   (<1,2,3,4,5,6,7,10,11,12,13,14,15>)
                                     ;PUSH THE REST
             JRST    @0              ;RETURN TO CALLER

   $RETAC:
             MPOP    (<0,15,14,13,12,11,10,7,6,5,4,3,2,1>)
             EXCH    0,(17)          ;REPLACE AC0 AND RETURN ADDR
             POPJ    17,             ;RETURN TO CALLER

   ;DEFINE USEFUL KEYWORDS
   ;
   ;A technique which makes argument lists clear and saves time is to
   ;define the keywords to various commands. Attribute names are also
   ;defined in this manner.
   ;
   ;Define the logicals:
   ;
   .AND.:    ASCII/AND  /
   .OR.:     ASCII/OR   /
   .NOT.:    ASCII/NOT  /
   .EQV.:    ASCII/EQV  /
   .XOR.:    ASCII/XOR  /

   ;Define the relationals:
   ;
   .EQ.:     ASCII/EQ   /
   .NE.:     ASCII/NE   /
   .BET.:    ASCII/BET  /
   .NBET.:   ASCII/NBET /
   .GT.:     ASCII/GT   /
   .GE.:     ASCII/GE   /
   .LT.:     ASCII/LT   /
   .LE.:     ASCII/LE   /
   .CT.:     ASCII/CT   /
   .NCT.:    ASCII/NCT  /
   .BEG.:    ASCII/BEG  /
   .NBEG.:   ASCII/NBEG /

   ;Define special keywords for DBxxxx subroutines:
   ;
   DISP.:    ASCII/DISP./    ;FOR CONTROL OVER ARGUMENT CONVERSIONS
   BIN.:     ASCII/BIN. /

   ALL:      ASCII/ALL  /            ;FOR DBAINI, DBFIND
   LAST:     ASCII/LAST /
   SYSID:    ASCII/SYSID     /

   LOGICA:   ASCII/LOGICAL   /       ;FOR DBMAP

   THE SYSTEM 1022 MACRO INTERFACE                              Page 4-12
   Revision 5


   NOCLOS:   ASCII/NOCLOSE   /       ;FOR DBOPEN
   PASSWO:   ASCII/PASSWORD  /
   ACCESS:   ASCII/ACCESS    /

   PAGE

   >;;END OF S1022$ MACRO

             END



   4.10  EXAMPLE PROGRAM USING S1022$

   The following MACRO program uses the S1022$ macro to define the macros
   and names used in the program.


             TITLE CRYPT - ENCRYPTION USING THE 1022 MACRO INTERFACE
             SUBTTL COPYRIGHT (C) 1979 SOFTWARE HOUSE
    
    ;This program opens a data set (NAMES.DMS) of college student
    ;records. It selects all records and encrypts the values of
    ;GPA (grade point average). Running the program once encodes
    ;all GPAs and running it a second time decodes them.
    
             SEARCH  S1022   ;GET DECLARATIONS FROM S1022.UNV
    
             S1022$          ;EXPAND 1022 DEFINITIONS HERE
    
             AC1==1
             AC2==2
             AC3==3
             AC4==4
             P==17
             PD$LEN==60      ;STACK LENGTH
    
    ;TOKENS IN USE HERE
    ;
    NAMES:   ASCIZ/NAMES/    ;DATA SET IN USE
    GPA:     ASCIZ/GPA  /    ;GRADE POINT AVERAGE ATTRIBUTE
    ON:      EXP 1           ;"ON" VALUE FOR DBUPD
    
   THE SYSTEM 1022 MACRO INTERFACE                              Page 4-13
   Revision 5


    CRYPT:
             RESET                   ;RESET IO
             MOVE    P,[IOWD PD$LEN,PDL];SET UP STACK
             SETZM   OLDID           ;CLEAR OLDID
             MOVE    AC2,[137537,,233137]    ;LOAD "SEED" VALUE
             $1022   (DBMAC)         ;INIT THE 1022 INTERFACE
             $1022   (DBOPEN,<NAMES>);"OPEN NAMES"
             $1022   (DBUPD,<ON>)    ;"UPDATE ON"
             $1022   (DBFIND,<ALL>)  ;"FIND ALL"
    CRYP10:
             $1022   (DBGREC,<NOMORE>);"GETREC" AND GOTO NOMORE IF OUT
             $1022   (DBVAL,<GPA,GRADE,SYSID,ID>)
                                     ;GET VALUE OF GPA IN GRADE
                                     ;AND SYSID IN ID
             PUSHJ   P,MAKMSK        ;MAKE XOR MASK FOR THIS REC
             MOVE    AC1,GRADE       ;GET GPA VALUE
             XOR     AC1,AC2         ;XOR VALUE WITH MASK
             MOVEM   AC1,GRADE       ;RESTORE VALUE AND
             $1022   (DBCHNG,<GPA,GRADE>) ;REPLACE VALUE IN RECORD
             JRST    CRYP10          ;LOOP TILL DONE
    MAKMSK:
             MOVE    AC3,OLDID       ;GET OLD ID
             CAMN    AC3,ID          ;SAME AS CURRENT SYSID?
              POPJ   P,              ;YES, MASK IS READY
             MUL     AC2,AC2         ;NO, SQUARE THE MASK
             XOR     AC2,AC3         ;XOR THE HALVES
             AOS     OLDID           ;BUMP THE OLD ID
             JRST    MAKMSK          ;AND RETURN IF MASK IS READY
    NOMORE:
                                     ;HERE WHEN OUT OF RECS
             $1022   (DBEND)         ;END 1022 OPERATIONS
             EXIT                    ;USE "HALTF" UNDER TOPS-20
             JRST    .-1
    
    ;STORAGE
    
    PDL:     BLOCK   PD$LEN          ;STACK
    OLDID:   BLOCK   1               ;HOLDS SYSID FOR CURRENT MASK
    GRADE:   BLOCK   1               ;VALUE FOR GPA
    ID:      BLOCK   1               ;HOLDS SYSID
    
             END     CRYPT



   4.11  USERCALL

   USERCALL is an interactive  1022  command  that  passes  values  to  a
   user-written  MACRO program.  USERCALL does not return values from the
   MACRO program to interactive 1022.

|  Both TOPS-10 and TOPS-20 sites that have the Host  Language  Interface
|  module  can implement USERCALL by configuring their MACRO library as a
|  host language program that initializes 1022 by  calling  DBMAC,  using
   THE SYSTEM 1022 MACRO INTERFACE                              Page 4-14
   Revision 5


|  DBSYSV  to  enter  the  address  of  the  MACRO  routine in the system
|  variable SYSUSERADR, and  calling  DBEXEC.   TOPS-20  sites  have  the
|  alternative  option  of  merging the MACRO routines called by USERCALL
|  with the appropriate segments of 1022 so that they  may  be  accessed,
|  thereby  doing  away  with  the  necessity of setting up a subfork for
|  DBEXEC.
|  
|  In either case, the address of the MACRO routine must be placed in the
   system   variable   SYSUSERADR  or  SYSUSRADRP  prior  to  any  calls.
   SYSUSERADR  is  user-settable  and  local  for  the  current  session.
   SYSUSRADRP   is   settable   only  by  the  System  Administrator,  is
   system-wide, and overrides SYSUSERADR.

   The syntax of the interactive command is:

             USERCALL [ expression [ , ] ...  ]

   where each expression evaluates to a value to be passed to  the  MACRO
   routine.



   4.11.1  Calling Conventions

   4.11.1.1  Calling Sequence

   USERCALL causes 1022  to  call  the  MACRO  routine  via  a  PUSHJ  17
   instruction.  A return of +1 (error) causes 1022 to issue a "[Error in
   USERCALL routine]" message.  A return of +2 is the normal  (non-error)
   return.   The  address  of  the  user's  routine must be placed in the
   system variable SYSUSERADR or SYSUSRADRP prior to any calls.  The call
   takes the following form:

             PUSHJ   17,@<address of SYSUSERADR or SYSUSERADRP>
             ->->error return
             ->normal return



   4.11.1.2  Parameters

   Parameters specified to the USERCALL command are  evaluated  prior  to
   calling  the user's MACRO routine.  The values of these parameters are
   assembled into a temporary memory area pointed  to  by  the  parameter
   block.   Accumulator  1  points to the parameter block.  The format of
   this parameter block is:

   THE SYSTEM 1022 MACRO INTERFACE                              Page 4-15
   Revision 5


                     -----------------------------------
   Word 0:           !     CVROUT    ,,     # PARAMS   !
                     -----------------------------------
   Word 1:           !            SYSNREC              !
                     -----------------------------------
   Word 2:           !    BYTE POINTER TO PARAMETER 1  !
                     -----------------------------------
   Word 3:           ! LENGTH PARAM 1,,   TYPE PARAM 1 !
                     -----------------------------------
                     !               .                 !
                     -----------------------------------
                     !               .                 !
                     -----------------------------------
                     !               .                 !
                     -----------------------------------
   Word 2*N:         !    BYTE POINTER TO PARAMETER N  !
                     -----------------------------------
   Word 2*N+1:       ! LENGTH PARAM N,,   TYPE PARAM N !
                     -----------------------------------

   where:

   CVROUT        is the address of a conversion routine (see below)
   # PARAMS      is the number of parameters specified in the command
   SYSNREC       is the number of records in the current selection group
   LENGTH PARAM  is the number of characters in the string if text
   TYPE PARAM    is the type of the parameter (see below)



   4.11.1.3  Conversions

   Since the data type of each parameter expected  by  the  user's  MACRO
   routine   is  unknown  to  1022,  conversions  may  be  required.   To
   facilitate these conversions, word 0 provides the  address  of  1022's
   general  conversion  routine  (CVROUT).   The  calling conventions for
   CVROUT are as follows:

   Call:   AC1/    src-cv-addr,,dest-cv-addr

           PUSHJ   17,CVROUT
             Return here if illegal conversion
             Return here if error on conversion
           Return here if all is ok

   src-cv-addr is the address of the source conversion block.
   dest-cv-addr is the address of the destination conversion block.

   A conversion block has the following format:

    Word 0:  Byte pointer to field, such that an ILDB will load the first
             byte of the field.

   Word 1:  shft/bytlen,,type
   THE SYSTEM 1022 MACRO INTERFACE                              Page 4-16
   Revision 5


   Where:  type=0      for type INTEGER
           type=1      for type REAL
           type=2      for type DISPLAY-7 TEXT
           type=4      for type DATE
           type=5      for type DISPLAY-7 INTEGER
           type=6      for type DISPLAY-7 REAL
           type=7      for type DISPLAY-7 DATE
           type=10     for type DISPLAY-6 TEXT
           type=11     for type DISPLAY-6 INTEGER
           type=12     for type DISPLAY-6 REAL
           type=13     for type DISPLAY-6 DATE
           type=14     for type DOUBLE INTEGER, COMP
           type=15     for type DOUBLE INTEGER, SIXBIT
           type=16     for type DOUBLE INTEGER, ASCII

   If type is 2 or 5-13, shft/bytlen is the length of the field in bytes.

   If type is 0, shft/bytlen is the "shift count" for a  packed  integer.
   The "shift count" (SC) is the number that causes the following code to
   leave the proper full-word representation of the integer in AC:

        ILDB   AC,[byte pointer to packed integer]
        LSH    AC,SC
        ASH    AC,-SC

   SC is (decimal) 36 minus <size of packed integer field>.



   4.11.2  Loading Conventions (TOPS-20)

|  To make the USERCALL routine accessable to  1022  on  TOPS-20  without
|  configuring  the  MACRO  library as a Host Language program, merge the
   routine with the 1022 segment from which it is called:  QN1600.EXE  in
   version  116.   When merging the code with this segment, take care not
   to overlap 1022 code and the user's code.  We suggest that  you  place
   the USERCALL routine at or above page 630.

   The following procedure loads a routine at page 630.

           @LINK
           */SEGMENT:HIGH/SET:.HIGH.:630000 PROG.REL/GO
           @SAVE PROG 630 630 !first page, last page
           @GET QN1600
           @MERGE PROG
           @SAVE QN1600

   Note that LINK uses the first  10  (octal)  locations  for  job  data.
   SYSUSERADR  should  be  set  to  208904  (630010 octal).  To place the
   routine in a different location, modify the numbers above accordingly.
   THE SYSTEM 1022 MACRO INTERFACE                              Page 4-17
   Revision 5


|  4.11.3  Configuring The MACRO Library As A Host Language Program
|  
|  TOPS-10 users must (and  TOPS-20  users  may)  configure  their  MACRO
|  library  as  a  Host  Language program in order to implement USERCALL.
|  The program initializes 1022 through a call to DBMAC.   SYSUSERADR  is
|  set  through a call to DBSYSV.  A call to DBEXEC then puts the user in
|  stand-alone 1022.  A USERCALL command results in a PUSHJ to the  MACRO
|  program  to  the  address  stored  in  SYSUSERADR  or SYSUSRADRP.  The
|  routine executes and the user returns to 1022 with a POPJ.   The  1022
|  HOST command results in a POPJ back to the MACRO program.
|  
|  An example showing the proper MACRO configuration follows.



   4.11.4  Example USERCALL Routine

   The following is part of a TOPS-20 USERCALL routine embedded in a Host
   Language  program.   It  is a dispatching routine which can be used to
|  call various other routines with USERCALL.  TOPS-20 users  wishing  to
|  merge  the  MACRO  routine  with 1022 instead of treating it as a Host
|  Language program would simply omit the lines of code beginning with
|  
|          PDLEN==50            ;Stack size.
|  
|  and ending with
|  
|  STACK:  BLOCK   PDLEN


   SEARCH      MONSYM,MACSYM ENTRY DISP

   COMMENT\
   DISP is  dispatching  routine  for  all  USERCALLS  starting  at  this
   address.

   Calling convention is USERCALL <procedure-name>,[[arg1,],[arg2],..]
   where procedure-name is desired routine.

   USERCALL will go to  DISP,  which  will  look  up  procedure-name  and
   dispatch  to  that routine.  Routines will have argument block address
   and number of arguments set up, and A2  and  A3  preserved.   Routines
   will have to return +1 for failure, +2 for success.

   Table entries are in SIXBIT to avoid problem of case matching.
   \

   THE SYSTEM 1022 MACRO INTERFACE                              Page 4-18
   Revision 5


   ;Definitions
               A0==0
               A1==1
               A2==2
               A3==3
               P==17  
|              PDLEN==50       ;Stack size.
|              AP==16          ;Pointer to argument block.
|  MY1022:     RESET
|              MOVE    P,[IOWD PDLEN,STACK]    ;Init stack.
|              MOVEI   AP,1+[XWD -1,0
|                      [ASCIZ\NOSETNAME\]]   
|              PUSHJ   P,DBMAC                 ;Start 1022.
|  
|              MOVEI   AP,1+[XWD -3,0
|                      [ASCIZ\SYSUSERADR\]     ;Supply SYSUSERADR.
|                      [1]
|                      [DISP]]                 ;All USERCALLs go to DISP.
|              PUSHJ   P,DBSYSV
|  
|              MOVEI   AP,1+[0]
|              PUSHJ   P,DBEXEC                ;Go to stand-alone.
|              MOVEI   AP,1+[0]                ;"HOST" eq "QUIT".
|              PUSHJ   P,DBEND                 ;Say goodbye.
|              EXIT                            ;Use HALTF% on TOPS-20.
|              JRST    .-1                     ;And mean it.
|  
|  STACK:      BLOCK   PDLEN

   DISP:       PUSH P,A2 ;Preserve ACs.
               PUSH P,A3
               MOVE A2,A1 ;Keep argument block address in A2.
               MOVEM A1,ARGADR ;and preserve it for other routines.
               HRRZ A0,(A1) ;How many arguments?
               JUMPLE A0,ARGERR ;If none, can't dispatch.
                MOVEM A0,NUMARG ;Else, preserve # arguments,
                 ;and set up conversion to SIXBIT.
               DMOVE A0,2(A2) ;Move byte pointer
               DMOVEM A0,SRCBLK ;and status bits to SRCBLK.
               MOVE A1,[SRCBLK,,DSTBLK] ;Point to conversion blocks,
               HLRZ A2,(A2) ;point to the conversion routine,
               PUSHJ P,(A2) ;and do it.
                JRST CNVER1 ;Conversion error.
                JRST CNVER2

               MOVE A2,RETVAL ;A2 contains procedure-name.
               MOVE A1,[-TABLEN,,DSPTAB] ;Set up A1 for AOBJN loop.
   TABLP:      MOVE A3,(A1) ;Get the table entry.
               CAME A2,(A3) ;If it matches, we're done.
                AOBJN A1,TABLP ;Doesn't match, try the next one.
               JUMPGE A1,BADRET ;Trouble if we've run out of table.
                HLRZS A3 ;Get dispatch address in R.H.,
               PUSHJ P,(A3) ;and go there.
               CAIA  ;Trouble if called routine returns +1.
   THE SYSTEM 1022 MACRO INTERFACE                              Page 4-19
   Revision 5


   GOOD:        AOS -2(P) ;Good return.
   BADRET:     POP P,A3 ;Restore ACs.
               POP P,A2
               POPJ P, ;Go home.

   DSPTAB:       ;Table of procedures.
               ADR1,,[SIXBIT\RTN1 \]
               ADR2,,[SIXBIT\RTN2 \]
   ;Table entries as needed.

               TABLEN=.-DSPTAB ;Table length

   SRCBLK:     BLOCK 2 ;Source conversion block.
   DSTBLK:     POINT 6,RETVAL ;SIXBIT byte pointer to RETVAL.
               6,,10  ;<#chars>,,<sixbit data type>
   RETVAL:     BLOCK 1
   NUMARG: BLOCK 1
   ARGADR: BLOCK 1
               END














                                 APPENDIX A

                        HOST LANGUAGE ERROR MESSAGES



   The error messages  listed  in  this  appendix  are  those  which  are
   specific to the host language interface environment.  They are denoted
   as Error Type 14, of the various types of errors which  can  occur  in
   1022.   For  a  complete  list of the other error types and associated
   messages, refer to Appendix E of the 1022 User's Reference Manual.


   HL1    NUMERIC DATA REQUESTED IN TEXT ARGUMENT
          A call to the DBVAL or DBGET subroutine from a COBOL program is
          requesting  numeric  data  to be placed in a COBOL DISPLAY-type
          variable.

   HL2    INVALID ATTRIBUTE NAME
          An attribute name was expected, but did  not  match  any  legal
          name  or  synonym.   Attributes  must  match  a name or synonym
          exactly.

   HL3    INVALID RELATIONAL
          1022 does not recognize the relational name or number.

   HL4    ATTRIBUTE NOT KEYED
          The user has attempted to use an unkeyed attribute in a  DBFIND
          call.

   HL5    INVALID OR NO VALUE
          A value was expected, but none was given, or the value was  out
          of any legal range.

   HL6    INVALID LOGICAL
          The logical given was unrecognized.

   HL7    DBVAL CALLED BEFORE DBGREC
          The user must be in local mode with a  call  to  DBGREC  before
          calling DBVAL.

   HL8    DOUBLE ATTRIBUTE IN ADD OR CHANGE
          The same attribute can not  be  specified  twice  in  DBADD  or
          DBCHNG.

   HOST LANGUAGE ERROR MESSAGES                                  Page A-2
   Revision 4


   HL9    TOO FEW ARGUMENTS
          Another argument was required, but the list ended.

   HL10   OUT OF CORE
          1022 needed more core for internal table space, but a CORE  UUO
          failed to get it.

   HL11   DATA SET NOT OPEN
          The command just attempted requires that a data set be open for
          operations.  None was open when attempted.

   HL12   INVALID COBOL DISPLAY TYPE
          The user declared a variable as DISPLAY-9 which the COBOL  Host
          Language interface does not recognize.

   HL13   SAV.  ARGUMENT NOT SEQUENTIAL OR NOT IN RANGE
          For efficiency, the user is required to  use  the  lowest  SAV.
          number  that  he  can  at  any time.  Here he used one that was
          greater than 10, or skipped a number or two.

   HL14   ADD OR CHANGE ON PROTECTED ATTRIBUTE
          The user has attempted to  specify  a  value  for  one  of  the
          attributes  that  are  protected  from change, i.e., Integer Of
          Identification, Date Of Change, Date Of Entry.

   HL15   ILLEGAL TYPE CONVERSION
          The host language interface attempted a type  conversion  which
          was illegal, e.g., text to numeric.

   HL16   TOO MANY SORT FIELDS
          The user has tried to specify more than 20 attributes  to  sort
          on.

   HL17   ILLEGAL OR REPEATED SORT SPECIFICATION
          The scan hit an unknown word, or two  keywords  processing  the
          same attribute in a sort description.

   HL18   UNAUTHORIZED COMMAND
          Either the ADMIT protection on the data set does not allow  the
          last  command  to  be  executed,  or  DBRETN  was called from a
          FORTRAN or MACRO program.

   HL19   UNAUTHORIZED ATTRIBUTE REQUEST
          The ADMIT protection  on  the  data  set  does  not  allow  the
          attribute  specified  in  the operation requested.  (Usually in
          DBCHNG).

   HL20   "FILE" INVALID IN SEARCH
          The user can not  use  the  FILE  <file-descriptor>  option  in
          DBSRCH.

   HL21   INVALID FILE DESCRIPTOR
          The routines detected  an  irregularity  in  a  file-descriptor
          argument.
   HOST LANGUAGE ERROR MESSAGES                                  Page A-3
   Revision 4


   HL22   INVALID PASSWORD
          A password supplied in a DBPSWD command was not correct.

   HL23   INVALID KEYWORD
          A third argument was passed to the 'CHECK' call to  DBAUD,  and
          it was not 'FAST'.

   HL26   INVALID DATA SET SPECIFIED
          A call to DBSET  specified  a  data  set  number  that  is  not
          currently assigned to an opened data set.

   HL27   INVALID DBAUD SUBCOMMAND
          The first argument to DBAUD is not  a  valid  subcommand.   The
          legal DBAUD subcommands are:  START, CHECK, and PLACE.

   HL28   AUDIT FILE NOT OPEN
          An attempt was made to write data into an audit file before the
          file was initialized.

   HL29   ILLEGAL AUDIT FILE BLOCK TYPE
          User defined audit file entries are  permitted  to  have  entry
          codes only in the range 700-777 octal (448-511 decimal).

   HL30   INVALID DBAUD 'START' KEYWORD
          One or more of the keywords specified  in  a  'START'  call  to
          DBAUD  was  not  recognized.  The possible keywords are:  FILE,
          LOCK, JOB and FAST.

   HL31   SYSID ILLEGAL HERE
          The user has specified the attribute SYSID in a call to DBPSWD.
          SYSID can not be protected.

   HL32   DBEND NOT ALLOWED HERE
          DBEND may not be called during an error trapping subroutine  or
          procedure.

   HL33   NO RETURN ADDRESS FOR DBRETN
          DBRETN was entered outside of an error trapping  procedure  and
          1022 has no return address set up.

   HL34   INVALID DATA SET SPECIFIED -- DATA SET NAME AMBIGUOUS
          A call to DBSET specified a data set  name  that  matches  more
          than  one  open  data  set.   Close  the  unwanted data sets or
          reference the correct one with the data set number.

   HL35   INVALID SYSTEM VARIABLE NAME OR NUMBER
          The system variable name in a call to DBSYSV was not recognized
          or the number in that call was out of range.

   HL36   SYSTEM VARIABLE NOT USER ASSIGNABLE
          User attempted to change the value of a system  variable  which
          may only be read.

   HOST LANGUAGE ERROR MESSAGES                                  Page A-4
   Revision 4


   HL37   SCALING NOT SUPPORTED FOR COBOL ARGUMENTS
          COBOL picture editing and picture  scaling,  including  implied
          decimal,  are  not  supported  by 1022.  Do editing in COBOL by
          moving a returned item to a COBOL edited field.

   HL38   INVALID ARGUMENT, LITERALS CANNOT BE CHANGED
          The user has specified a constant where an indication of change
          is expected.

   HL39   SIZE OF VALUE/COUNT PAIR EXCEEDS USER ARRAY BOUNDS
          In issuing a DBVALU command, the user has made the  ARRAY-START
          and  ARRAY-END  specifications  too narrow to allow room in the
          array for a single value/occurrence pair.

   HL40   REQUESTED NUMBER OF VALUES EXCEEDS ALLOWABLE MAXIMUM
          In issuing a DBVALU command, the user has set  NV  to  a  value
          greater  than the maximum number of value/occurrence pairs that
          can be contained within the bounds defined by  ARRAY-START  and
          ARRAY-END.

   HL41   UNEXPECTED EOF DURING KEY SEARCH
          The data file  has  been  damaged.   An  internal  pointer  has
          directed a read past the end of the file during a key search.

   HL42   UNEXPECTED EOF WHILE COUNTING KEY VALUES
          The data file  has  been  damaged.   An  internal  pointer  has
          directed  a  read  past  the end of the file during a key value
          count.

   HL43   REFERENCE TO AN ELEMENT OF A COLLECTION IS ILLEGAL
          Data sets serving as constituents of a collection can  only  be
          referenced or accessed as part of that collection.

   HL44   COMMAND NOT ALLOWED WHEN SET TO A COLLECTION
          The user has attempted to  apply  a  disallowed  command  to  a
          current collection.

   HL45   INVALID ARGUMENT DESCRIPTION RETURNED FROM XGARG.
          The XGARG.  routine  that  identifies  the  argument  type  was
          unable  to  do so either because a particular argument contains
          an invalid argument description or else  because  there  is  an
          error  in  the  XGARG.   routine  itself.   Consult your system
          manager.












                                 APPENDIX B

                            DATE REPRESENTATIONS



   B.1  RADIX DATE FORM

   DATE=((YEAR-1964)*12+(MONTH-1))*31+DAY-1

   where:

   YEAR   is the year (e.g.  1977)

   MONTH  Is 1 for January, 2 for February, ..., 12 for December.

   DAY    Is the day of the month



   B.2  SYSTEM 1022 ENCODED DATE

   System dates are represented as the number of days since 1/1/1800.

        For example:

        The value 4 represents the date January 5, 1800



   B.3  UNIVERSAL DATE-TIME FORMAT

   This is a single word value that contains both a date and a time.

   The left halfword is the number of days since 11/17/1858.

   The right halfword contains the time, expressed as a  binary  fraction
   of  one day.  Under TOPS-10 the time is usually the local time.  Under
   TOPS-20 the time is Greenwich Mean Time.

   The entire universal date-time word may be described as a real  number
   of days since the base date, with a "binary point" between bits 17 and
   18.
   DATE REPRESENTATIONS                                          Page B-2
   Revision 4















                                 APPENDIX C

                            OTHER HOST LANGUAGES



   System 1022 may be interfaced to  host  languages  other  than  COBOL,
   FORTRAN, and MACRO.



   C.1  REQUIREMENTS

   To interface 1022 to a new host language, the run-time system of  that
   language must be changed in four areas.

        1.  The user program or the runtime system must call  DBMAC  when
            the user program is initialized.

        2.  The runtime system must obtain free core from  1022's  DBCORE
            subroutine.

        3.  Runtime  systems   operating   under   TOPS-10   or   TOPS-20
            compatibility  mode  must  obtain  I/O  channels  from 1022's
            DBCHAN subroutine.

        4.  System 1022 XGARG. routine must be modified to interpret host
            language arguments.

   The Host Language Interface Manual describes the calling sequences for
   the  DBMAC,  DBCORE,  and  DBCHAN  subroutines.  The XGARG. routine is
   described below.  These subroutines need be called only if  a  program
   will be accessing System 1022.



   C.2  INITIALIZATION

   The user program or the runtime system must be loaded with  the  DBMAC
   subroutine  from  HL1022.REL.   The  runtime system may determine if a
   program has been loaded with 1022 routines by examining location  136.
   If location 136 is non-zero, 1022 routines have been loaded.  The left
   half of location 136 points to a parameter  block  that  contains  the
   following information.

   OTHER HOST LANGUAGES                                          Page C-2
   Revision 4


               Word 0:  version number of 1022
               Word 1:  4 (number of words following)
               Word 2:  address of a variable that contains the number
                 of words that DBMAC will allocate for a fixed
                 storage area
               Word 3:  address of the DBMAC subroutine
               Word 4:  address of the DBCHAN subroutine
               Word 5:  address of the DBCORE subroutine

   On startup, either the user program or the runtime  system  must  call
   the  DBMAC subroutine.  This subroutine allocates 1022's fixed storage
   area at the location pointed to by .JBFF (location 121).   It  expands
   core,  if  necessary, after examining the contents of .JBREL (location
   44).  Thus if the runtime system wants  1022  to  allocate  its  fixed
   storage  area  at  a  particular location, it should set .JBFF to that
   address before it calls DBMAC and then restore the  previous  contents
   of  .JBFF  after  returning  from  DBMAC.   Note  that  word  2 of the
   parameter block points to a location that contains the amount of  core
   needed by 1022 for its fixed storage area.

   DBMAC changes the contents of location 136.  You must  save  away  any
   pointers   from   the  parameter  block  before  you  call  the  DBMAC
   subroutine.



   C.3  CORE MANAGEMENT

   The  runtime  system  must  request  free  core  with  1022's   DBCORE
   subroutine.  The DBCORE subroutine simulates the monitor by allocating
   and deallocating contiguous core areas.

   The Host Language Interface Manual describes the calling sequence  for
   this subroutine.



   C.4  CHANNEL MANAGEMENT

   The runtime system must obtain and release software channels with  the
   DBCHAN  subroutine.   The Host Language Interface manual describes the
   calling sequence for this subroutine.
   OTHER HOST LANGUAGES                                          Page C-3
   Revision 4


   C.5  EXAMPLES:  DBMAC, DBCORE, DBCHAN

   At system initialization

               SKIPN 1,136  ;IS 1022 LOADED?
               JRST NO1022  ;NO
               HLRZ 1,1  ;YES, LOAD PARAM BLOCK ADDRESS
               MOVE 0,4(1)  ;FETCH ADDRESS OF DBCHAN
               MOVEM 0,CHAN%% ;STORE FOR LATER USE
               MOVE 0,5(1)  ;FETCH ADDRESS OF DBCORE
               MOVEM 0,CORE%% ;STORE FOR LATER USE
               MOVEI 16,1+[0] ;NO ARGS TO DBMAC
               PUSHJ 17,@3(1) ;CALL DBMAC
   NO1022:

        To obtain core

   ;SUBROUTINE TO ALLOCATE CORE.
   ;CALLING SEQUENCE:
   ;           MOVE 0, # WORDS OF CORE TO ALLOCATE
   ;           PUSHJ 17,GETCOR
   ;           RETURN HERE IF NO CORE AVAILABLE
   ;           RETURN HERE WITH AC 1 CONTAINING ADDRESS OF ALLOCATED CORE

   GETCOR:
               SKIPN 136  ;USE 1022 CORE ROUTINES?
               JRST REGCOR  ;NO
               MOVEM 0,SIZE  ;YES, STORE AMOUNT NEEDED
               MOVEI 16,1+[XWD -2,0 ;SET UP ARGUMENT LIST
                      XWD 0,SIZE
                      XWD 0,LOC]
               PUSHJ 17,@CORE%% ;CALL DBCORE
               SKIPE 1,LOC  ;FETCH ADDRESS OF ALLOCATED CORE
   GOTCOR:
               AOS (17)  ;SKIP RETURN
               POPJ 17,
   REGCOR:
               MOVE 1,.JBFF  ;SAVE LOCATION OF CORE BLOCK
               ADDB 0,.JBFF  ;INCREASE .JBFF
               CAMG 0,.JBREL ;NEED WE EXPAND CORE?
               JRST GOTCOR  ;NO, ALL DONE
               CORE 0,  ;YES, DO IT
               POPJ 17,  ;NO CORE AVAILABLE
               JRST GOTCOR  ;ALL DONE
   OTHER HOST LANGUAGES                                          Page C-4
   Revision 4


   C.6  ARGUMENTS -- XGARG.

   Host language arguments are interpreted by  XGARG. routines  in  1022.
   Each  different  host language uses a different XGARG. routine.  These
   are supplied for standard versions of FORTRAN and  COBOL.   A  systems
   programmer  can write an XGARG. routine for another version or another
   language.  XGARG. can also perform  dynamic  string  allocation.   The
   following sections describe XGARG. and GARGL. and give an example of a
   COBOL XGARG. routine.



   C.6.1  XGARG. Call

   XGARG. describes a host language argument to 1022  given  an  argument
   pointer  from  the language.  This allows you to define your own rules
   for argument handling.  System 1022 calls XGARG. for each argument and
   then processes the argument using XGARG. output.

   The call to XGARG. is:

        AC0/ Flags,,Description bits (see both below)
        AC1/ Attribute length, 0 means not a user data argument
        AC2/ Argument pointer (from argument block)
        AC3/ GARGL. address (see below)
        AC4/ Address of Useable memory locations (4 words)

   PUSHJ   17,XGARG.##
   +1 return always, ACs returned:

        AC0/ Original Flag bits,,Description bits (see below),  error  if
             no Description bits on
        AC1/ Bits 9-35:  Length in bytes if text type,  or  in  words  if
                         binary type, (see Requirements below)
             Bits 0-8:   0 if not fixed-point, number of  decimal  places
                         (XG%FXP) if fixed-point (not yet supported)
        AC2/ Byte pointer to data
        AC3/ Reserved for future use (should be zero)
        AC4/ Address of routine to call (PUSHJ to)  after  the  data  has
             been  transferred,  or zero if no call is desired.  AC1 will
             contain the byte pointer to the destination where  the  data
             was transferred.

   All Flags and Description bits  are  defined  in  the  universal  file
   PXGARG.UNV.

   OTHER HOST LANGUAGES                                          Page C-5
   Revision 4


   Flags          Meaning/Usage
   ------------   -----------------------------
   XG%M2D (1B0)   Memory to data set flag.  Off means from  data  set  to
                  user  memory;   on  means from user memory to data set.
                  See also Requirements below.

   XG%CVT (1B1)   The user either specified "CVT." in his DBxxxx call, or
                  SYSHLCVT  was  set  to 1 (and neither "CVT." nor "XCV."
                  was specified).

   XG%ERR (1B2)   An error occurred during the argument handing in XGARG.
                  It  indicates  that  the right half of AC1 contains the
                  1022 error number (see below).  This bit is set only by
                  XGARG.


                  Description Bits
                  ----------------
   Type bits (XG%TYP)              Form bits (XG%FRM)
   ----------------------          ---------------------
   XG%INT (1B18)  Integer          XG%BIN (1B27)  Binary
   XG%REA (1B19)  Real             XG%ASC (1B28)  ASCII
   XG%DAT (1B20)  Date             XG%6BT (1B29)  SIXBIT
   XG%TXT (1B21)  Text

   XG%DSC (740700B35) is all description bits



   C.6.2  GARGL. Definition

   The global symbol GARGL., passed in AC3, is  a  block  of  low-segment
   memory  that  the  user defines.  Data, routine dispatch addresses for
   dynamic allocation, or whatever the user wants may be put there.   For
   example,  a  specialized  FORTRAN includes dynamic allocation routines
   ALLOC.  and  DEALC.   For  XGARG.  to  call  the  ALLOC.  routine,  it
   references GARGL. with

        PUSHJ   P,0(AC3)

   To call DEALC., it references GARGL.  with

        PUSHJ   P,1(AC3)

   For these example routines, the  user  defines  the  following  GARGL.
   table:

                ENTRY   GARGL.
        GARGL.: JRST    ALLOC.##
                JRST    DEALC.##

   XGARG. may be in the high or  low  segment;   GARGL.  allows  LINK  to
   satisfy  global  requests  so  that XGARG. can use external references
   from either segment.
   OTHER HOST LANGUAGES                                          Page C-6
   Revision 4


   Each Software House defined XGARG.  has GARGL. defined  as  zero.   If
   you  do wish to define GARGL. and/or XGARG., you must either MAKLIB it
   into HL1022.REL and HR1022.REL or load it before HL1022 or HR1022.



   C.6.3  Requirements Of XGARG.

   The Flag bits in the left half of AC0, with the exception  of  XG%ERR,
   should be preserved.

   The location before XGARG. should contain the XGARG. version number.

   If the XG%M2D flag is on, allocation should not be  done  for  dynamic
   strings.

   If  the  user  wishes  the  general  error  HL45   "Invalid   argument
   description  returned from XGARG." to be printed, the description bits
   should all be turned off.  If a more specific 1022  error  message  is
   desired,  set  the XG%ERR bit in AC0, and put the 1022 error number in
   the right half of AC1.  The error number is the  error  type  in  bits
   18-26  and the error code in bits 27-35.  For example, the instruction
   "MOVEI 1,(BYTE (9)^D14,^D12)" means return  the  error  HL12  "Invalid
   COBOL  DISPLAY  type"  (type  14  is  "HL").  Use only "HL" type error
   messages.

   If the XG%CVT bit is on, do not change the description  bits  at  all.
   When  this bit is on, it indicates that the call to the DBxxxx routine
   requested that no type conversion be done (the way that Fortran  works
   with 1022).

   The length returned for ASCII or SIXBIT forms in the right half of AC1
   should  reflect  whether the host language expects the number of bytes
   to be rounded up to a word boundary.  For example, 11 bytes  of  ASCII
   should  return  15  bytes as the length, and 11 bytes of SIXBIT should
   return 12 bytes as the length.  If, however, the  host  language  does
   not require word padded results (e.g.  COBOL) or uses dynamic strings,
   do not round up to the next word boundary.

   At least one Type bit and at least one Form bit will  be  on  for  the
   call  to  XGARG.,  and  the  same can be said for the Description bits
   returned by XGARG.  If XGARG. does not know  what  the  argument  type
   should  be,  then  it should leave the Description bits alone.  If the
   Form as determined by XGARG. is either ASCII or SIXBIT, the Type  bits
   should be left unchanged.

   For example,  since  Fortran  argument  types  are  ignored,  whatever
   Description  bits are passed to Fortran's XGARG. should be returned as
   is.  If the Form is  ASCII  or  SIXBIT,  the  length  returned  should
   reflect   word   padding.    COBOL's  XGARG.  should  always  set  the
   Description bits as determined by the COBOL argument types.

   If the user expects bit 35 to be off when returning 1 or more words of
   ASCII,  he  must  program  XGARG.  to  turn  off  bit 35 for all words
   OTHER HOST LANGUAGES                                          Page C-7
   Revision 4


   returned.  Turn off only bit 35;  do not zero the  whole  word.   (See
   the 6 lines before "XGRG00:" in the COBOL XGARG. as an example).

   The byte pointer returned in AC2 should contain  byte  information  in
   the left half only if one specific Form bit (binary, ASCII, or SIXBIT)
   is returned (right half of AC0).

   AC0-AC7 may be used freely (arguments are in AC0-AC4 and return values
   are  in  AC0-AC4).   AC10-AC16  must  be preserved.  AC17 is used as a
   stack pointer.



   C.6.4  Example:  XGARG.

   The following example shows the standard COBOL XGARG. routine.

           TITLE   XGGCBL
           SEARCH  PXGARG

           ENTRY   XGARG.

           A0==0
           A1==1
           A2==2
           A3==3
           A4==4
           A5==5
           A6==6
           A7==7
           P==17

           OCT     1                  ;XGARG. VERSION NUMBER
   XGARG.: LDB     A5,[POINT 4,0(A2),12] ;GET THE ARGUMENT TYPE
           TLNN    A0,(XG%CVT)        ;SHOULD WE DO THE CONVERSION?
            JRST   @XGGCBT(A5)        ;YES, GO TO HANDLING ROUTINE
           CAIN    A5,15              ;NO, DISPLAY TYPE?
            MOVEI  A2,@0(A2)          ;YES, GET ADDRESS OF BYTE POINTER
           MOVE    A6,A1              ;GET ORIGINAL LENGTH
           MOVSI   A5,(POINT 36,0)    ;ASSUME BINARY
           TRNE    A0,XG%ASC          ;IS IT REALLY ASCII?
            MOVE   A5,[POINT 7,5]     ;YES, ASSUME ASCII
           TRNE    A0,XG%6BT          ;IS IT REALLY SIXBIT?
            MOVE   A5,[POINT 6,6]     ;YES, ASSUME SIXBIT
           TRNE    A0,XG%BIN          ;IS IT BINARY?
            JRST   XGRG01             ;YES, DON'T FIDDLE WITH THE LENGTH
           JUMPE   A1,XGRG01          ;NO LENGTH, THIS WON'T CHANGE
           ADDI    A6,-1(A5)          ;ADJUST THE LENGTH TO PAD TO FULL WORD
           IDIVI   A6,0(A5)
           TDNE    A0,[XG%6BT!XG%M2D] ;IS IT NOT ASCII TO USER MEMORY?
            JRST   XGRG00             ;NO, DON'T WORRY ABOUT BIT 35
           MOVN    A3,A6              ;NEGATIVE COUNT OF WORDS
           HRLZS   A3                 ;IN LEFT HALF
           HRRI    A3,@0(A2)          ;ADDRESS IN RIGHT HALF
   OTHER HOST LANGUAGES                                          Page C-8
   Revision 4


           MOVEI   A7,1B35            ;BIT TO TURN OFF
           ANDCAM  A7,0(A3)           ;TURN THE BIT OFF
           AOBJN   A3,.-1             ;LOOP THROUGH ALL WORDS
   XGRG00: IMULI   A6,0(A5)
   XGRG01: MOVEI   A2,@0(A2)          ;RETURN ARGUMENT POINTER
           HLL     A2,A5              ;CREATE BYTE POINTER
           MOVE    A1,A6              ;RETURN LENGTH
           JRST    XGGDUN             ;DONE

   XGGBAD: TRZ     A0,-1              ;NO DESCRIPTION BITS (FORCE A FAILURE)
           JRST    XGGDUN             ;DONE

   XGGCMP: MOVEI   A1,1               ;BINARY LENGTH OF 1
           JRST    XGGCMX
   XGGDP:  MOVEI   A1,2               ;BINARY LENGTH OF 2
   XGGCMX: MOVEI   A2,@0(A2)          ;GET ADDRESS OF THE ARGUMENT
           HRLI    A2,(POINT 36,0)    ;MAKE IT A FULL-WORD BYTE POINTER
           TRZ     A0,XG%DSC          ;MAKE IT INTEGER/BINARY
           TRO     A0,XG%INT!XG%BIN
           JRST    XGGDUN             ;DONE

   XGGCM1: MOVEI   A1,1               ;BINARY LENGTH OF 1
           MOVEI   A2,@0(A2)          ;GET ADDRESS OF THE ARGUMENT
           HRLI    A2,(POINT 36,0)    ;MAKE IT A FULL-WORD BYTE POINTER
           TRZ     A0,XG%DSC          ;MAKE IT REAL/BINARY
           TRO     A0,XG%REA!XG%BIN
           JRST    XGGDUN             ;DONE

   XGGDSP: MOVEI   A2,@0(A2)          ;GET 2 WORD DESCRIPTOR ADDRESS
           TRZ     A0,XG%FRM          ;TURN OFF THE FORM BITS
           LDB     A5,[POINT 4,1(A2),4] ;GET SPECIAL DESCRIPTION TYPE
           CAIN    A5,1               ;DISPLAY-6?
            JRST   XGGDS6             ;YES,
           CAIE    A5,2               ;DISPLAY-7?
            JRST   [MOVEI A1,(BYTE (9)^D14,^D12)
                    JRST  XGGERR]     ;NO, BAD NEWS
           TROA    A0,XG%ASC          ;INDICATE ASCII
   XGGDS6:  TRO    A0,XG%6BT          ;INDICATE SIXBIT
           MOVE    A1,1(A2)           ;GET DISPLAY DESCRIPTOR
           MOVE    A2,0(A2)           ;GET BYTE POINTER
           TLNN    A1,(1B7)           ;IS IT NUMERIC?
            JRST   [TLZ  A1,(7777B11) ;NO, WE WANT BITS 12 THROUGH 35
                    JRST XGGDUN]      ;DONE
           TDNE    A1,[17777777B30] ; HAVE A PICTURE (BITS 9-30)?
            JRST   [MOVEI A1,(BYTE (9)^D14,^D37)
                    JRST  XGGERR]     ;YES, NO CAN DO
           ANDI    A1,37B35           ;YES, WE ONLY WANT BITS 31 THROUGH 35
   ;       JRST    XGGDUN             ;DONE, DROP THROUGH

   XGGDUN: SETZB   A3,A4              ;NOTHING SPECIAL
           POPJ    P,                 ;DONE

   XGGERR: TLO     A0,(XG%ERR)        ;INDICATE A SPECIFIC ERROR
           POPJ    P,                 ;RETURN
   OTHER HOST LANGUAGES                                          Page C-9
   Revision 4


   ;       ROUTINE                    TYPE   MEANING
   ;       -------                    ----   ----------------
   XGGCBT: XGGCMP                     ;  0   None (assume 1 word COMP)
           XGGBAD                     ;  1   None
           XGGCMP                     ;  2   1 word COMP
           XGGBAD                     ;  3   None
           XGGCM1                     ;  4   COMP-1
           XGGBAD                     ;  5   None
           XGGBAD                     ;  6   None
           XGGCMP                     ;  7   Procedure name (treat as COMP)
           XGGBAD                     ; 10   None
           XGGDP                      ; 11   2 word COMP (D.P.)
           XGGBAD                     ; 12   None
           XGGBAD                     ; 13   None
           XGGBAD                     ; 14   None
           XGGDSP                     ; 15   Display of some sort
           XGGBAD                     ; 16   None
           XGGBAD                     ; 17   None

           END
   OTHER HOST LANGUAGES                                         Page C-10
   Revision 4



   OTHER HOST LANGUAGES                                      Page Index-1
   Revision 4


                                   INDEX



   $1022 macro, 4-10                    DBNSET, 3-11
                                        DBOPEN, 3-8
   Argument interpretation              DBPSWD, 3-34
     XGARG., C-4                        DBRETN, 3-38
   Argument lists, 2-8                  DBSAVE, 3-16
   Arrays for arguments, 2-8            DBSEL, 3-17
   ATTR. option, 2-26, 3-17             DBSET, 3-10
                                        DBSORT, 3-24C
   BIN. option, 2-14                    DBSRCH, 3-17
   Bit 35, 2-2                          DBSREC, 3-24C
                                        DBSYSV, 3-40
   CHARACTER data type                  DBUPD, 3-31
     FORTRAN, 2-2                       DBVAL, 3-22
   COBOL over-punch character, 3-3      DBVALU, 3-25
   COBOL routines                       DBVAR, 3-48D
     DBADD, 3-30                        SYSUSER__, 3-45
     DBADDR, 3-30                     COBOLN routines
     DBAGET, 3-49                       DBLOCK, 3-24A
     DBAINI, 3-49                     COBOLroutines
     DBALLO, 3-32                       DBGET, 3-24A
     DBALOC, 3-54                     CVT. option, 3-1
     DBAUD, 3-48D                         
     DBBUF, 3-31                      DBCHAN, 4-5
     DBC68, 3-7                         with other host languages, C-2
     DBC74, 3-7                       DBCORE, 4-3
     DBCBL, 3-7                         with other host languages, C-2
       FPAG. argument, 1-7            DBMAC, 4-3
       LPAG. argument, 1-7              with other host languages, C-1
       XPAG. argument, 1-7            DISP. option, 2-14
     DBCHNG, 3-28                     Dynamic arrays, 4-4
     DBCLOS, 3-10                         
     DBCLR, 3-35                      Efficiency of
     DBCSET, 3-11                       PMAP, 1-6
     DBDATN, 3-40                     Error recovery, 2-43, 3-36
     DBDBUG, 3-48C                    Errors, 1-5
     DBDEL, 3-30                      ERRT. option, 2-7, 3-7
     DBDROP, 3-21                         
     DBEND, 3-8                       FIX. option, 2-8, 3-2
     DBERR, 3-36                      FORTRAN argument arrays, 2-8
     DBERRH, 3-37                     FORTRAN routines, 2-1
     DBERRT, 3-39                       DBADD, 2-38
     DBEXEC, 3-45                       DBADDR, 2-38
     DBFIND, 3-11                       DBAGET, 2-59
     DBGREC, 3-20                       DBAINI, 2-59
     DBINFO, 3-32                       DBALLO, 2-40
     DBMAP, 3-18                        DBALOC, 2-64
     DBNATT, 3-35                       DBAUD, 2-58
     DBNDAT, 3-40                       DBBUF, 2-39
     DBNREC, 3-20                       DBCHNG, 2-36
   OTHER HOST LANGUAGES                                      Page Index-2
   Revision 4


     DBCLOS, 2-19                     Locking Access
     DBCLR, 2-42                        COBOL, 3-24A
     DBCSET, 2-21                       FORTRAN, 2-33
     DBDATN, 2-47                     LPAG. argument, 1-7
     DBDBUG, 2-57                         
     DBDEL, 2-38                      MACRO
     DBDROP, 2-30                       IO management, 4-5
     DBEND, 2-17                        memory management, 4-3
     DBERR, 2-43                        USERCALL command, 4-13
     DBERRH, 2-44                         
     DBERRT, 2-46                     Other host languages, C-1
     DBEXEC, 2-52                       DBCHAN, C-2
     dbf10, 2-15                        DBCORE, C-2
     DBF6, 2-15 to 2-16                 DBMAC, C-1
     DBFIND, 2-21                       XGARG., C-4
     DBFOR, 2-15 to 2-16                  
       FPAG. argument, 1-7            PMAP, 1-6
       LPAG. argument, 1-7            PNT. option, 2-8, 3-2
       XPAG. argument, 1-7            PTB. option, 2-8
     DBFX, 2-15 to 2-16                   
     DBGET, 2-31                      Radix date form, B-1
     DBGREC, 2-29                     REF. option, 2-24, 3-15
     DBINFO, 2-40                     Retrieving an Entire Record
     DBLOCK, 2-33                       COBOL, 3-24A
     DBMAP, 2-26                        FORTRAN, 2-31
     DBNATT, 2-42                         
     DBNDAT, 2-47                     S1022$ macro, 4-10
     DBNREC, 2-29                     SAV. option, 2-24, 3-15
     DBNSET, 2-21                     Standard Record Format
     DBOPEN, 2-18                       COBOL, 3-22
     DBPSWD, 2-42                       FORTRAN, 2-31
     DBRETN, 2-46                     STS. option, 3-14
     DBSAVE, 2-25                     SYSCBLSIGN, 3-3
     DBSEL, 2-26                      SYSERRCODE, 1-5
     DBSET, 2-20                      SYSERRDEV, 1-5
     DBSORT, 2-34A                    SYSERREXT, 1-5
     DBSRCH, 2-26                     SYSERRFILE, 1-5
     DBSREC, 2-34                     SYSERRPPN, 1-5
     DBSTRT, 2-15 to 2-16             SYSHLCVT, 3-1
     DBSYSV, 2-48                     SYSHLDISP, 2-14
     DBUPD, 2-39                      SYSHLMODE, 2-14
     DBVAL, 2-30                      System variables, 2-48, 3-40
     DBVALU, 2-34B                      table of, 2-49, 3-41
     DBVAR, 2-58                        value-passing, 2-52, 3-45
     SYSUSER__, 2-52                  SYSUSER__, 2-52, 3-45
   FPAG. argument, 1-7                SYSUSERADR, 4-14
   FXB. option, 2-8                   SYSUSERADRP, 4-14
                                          
   I/O Errors, 1-5                    Termination of argument lists,
   Initialization                       2-8
     COBOL, 3-7                           
     FORTRAN, 2-15                    Universal date-time format, B-1
   ITS. option, 3-14                  UPDE. option, 2-36, 3-28
   OTHER HOST LANGUAGES                                      Page Index-3
   Revision 4


   USERCALL command, 4-13             
     syntax of, 4-14                  
                                      
   Value-passing system variables,    
     2-52, 3-45                       
                                      
   XCV. option, 3-1                   
   XGARG.                             
     with other host languages, C-4   
   XPAG. argument, 1-7                
                                      
N@Q