hchng.mem

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











































Copyright 1986 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 . . . . . . . . . . . . . . . . . . . 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
                                                                Page 2


        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
                                                                Page 3


        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
                                                                Page 4


        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

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


         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 4




   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                                   Page 2-30
   Revision 5


|  The optional third argument to DBGREC selects the nth record from  the
   beginning  of  the  current  group,  where  n  is the value of IRECNO.
   Further calls without the optional argument will continue from  there.
   If no nth record exists, control transfers to $label.



   2.8.7  The DROP Command -- DBDROP

   The DBDROP routine parallels the DROP command  and  removes  a  single
   record  from the current selection group, after a CALL to DBGREC.  The
   CALL is:

        CALL DBDROP

   The record is not deleted from the data set;  it is only dropped  from
   the current selection group.

   The DBDROP routine is used to  narrow  down  a  selection  group  with
   criteria  that  are too clumsy for the DBFIND or DBSRCH routines.  The
   program examines each record and drops undesired ones.



   2.8.8  The LET Command -- DBVAL

   The DBVAL routine parallels the LET command  and  retrieves  attribute
   values  from the currently selected record into variables or arrays in
   the program.  The CALL is:

        CALL DBVAL(IAI1,IBUF1 [,IAI2,IBUF2]...)

   Where:

        IAI1      Is an attribute identifier, which  may  be  either  the
                  ASCII  attribute name or abbreviation, or the attribute
                  number

        IBUF1     Is a variable or array where DBVAL puts  the  value  of
                  the specified attribute from the current record.

   The program must be in Local mode in order to call DBVAL;  a  CALL  to
   DBGREC must precede the CALL to DBVAL.


   A text or display value  may  require  many  words  of  storage.   The
   program  must  insure that IBUF1 is large enough to hold the value, or
   other following variables will be overwritten.

   The binary one word value of an integer, real, or  date  attribute  is
   placed  in IBUF.  More than one word is returned when SYSHLMODE is set
   to return display values.   For  binary  numeric  values  the  FORTRAN
   variable type is usually REAL for real values, and INTEGER for integer
   and date values.  Otherwise the program will  experience  problems  in
   FORTRAN INTERFACE ROUTINES                                   Page 2-31
   Revision 5


   doing arithmetic in FORTRAN with those variables.

   Example:  CALL DBVAL('NAME',INAME,'AGE',IAGE,'DISP.','SSN',IARRAY)

   The value for attribute NAME  is  placed  in  INAME.   The  value  for
   attribute  AGE  is  placed in IAGE.  The display value for the integer
   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-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

   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-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 ]
   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-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


   THE SYSTEM 1022 MACRO INTERFACE                               Page 4-20                                                          Page Index-1


                                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
                                                          Page Index-2


  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
                                                          Page Index-3


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                
                                   
E@Fw