117b.mem




 ***********************************************************************
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                             SYSTEM 1022                             *
 *                                                                     *
 *                    DOCUMENTATION OF NEW FEATURES                    *
 *                                                                     *
 *                             VERSION 117B                            *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 *                                                                     *
 ***********************************************************************




























                            Software House
                      1105 Massachusetts Avenue
                   Cambridge, Massachusetts   02138
                                 ----
                            (617)661-9440










                        Version 117B, May 1986

                    copyright 1986, SOFTWARE HOUSE



        1.0     INTRODUCTION . . . . . . . . . . . . . . . . . . . . 1
        2.0     SYSTEM 1022 DOCUMENTATION  . . . . . . . . . . . . . 1
        3.0     SUMMARY OF CHANGES TO 1022 . . . . . . . . . . . . . 3
        4.0     INTRODUCTION . . . . . . . . . . . . . . . . . . . . 4
        5.0     THE LARGE DATA SETS MODULE . . . . . . . . . . . . . 5
        5.1       Multifile Data Sets  . . . . . . . . . . . . . . . 5
        5.1.1     Overview . . . . . . . . . . . . . . . . . . . . . 5
        5.1.2     Determining File Size  . . . . . . . . . . . . . . 7
        5.1.3     Relocating Auxiliary Files . . . . . . . . . . . . 7
        5.1.4     Checking For Auxiliary File Damage, Loss, Or Skew  9
        6.0     PC EXTRACT: CREATING DIF AND WKS FILES   . . . . .  11
        6.1       Introduction . . . . . . . . . . . . . . . . . .  11
        6.2       DIF Files  . . . . . . . . . . . . . . . . . . .  11
        6.2.1     The INIT DIF Command . . . . . . . . . . . . . .  11
        6.2.2     Printing To A 1022 DIF File  . . . . . . . . . .  13
        6.2.2.1   Data Type Conversion . . . . . . . . . . . . . .  13
        6.2.2.2   Print Formats  . . . . . . . . . . . . . . . . .  13
        6.2.2.3   Example  . . . . . . . . . . . . . . . . . . . .  14
        6.2.2.4   Data-Positioning Information . . . . . . . . . .  17
        6.3       WKS Files  . . . . . . . . . . . . . . . . . . .  19
        6.3.1     The INIT 123 Command . . . . . . . . . . . . . .  19
        6.3.2     Printing To A WKS File . . . . . . . . . . . . .  21
        6.3.2.1   Data Type Conversion . . . . . . . . . . . . . .  21
        6.3.2.2   Print Formats  . . . . . . . . . . . . . . . . .  22
        6.3.2.2.1 L Format . . . . . . . . . . . . . . . . . . . .  23
        6.3.2.2.2 Other Formats  . . . . . . . . . . . . . . . . .  25
        6.3.2.2.3 Other Formats  . . . . . . . . . . . . . . . . .  25
        6.3.2.2.3.1X, /, And $ Formats . . . . . . . . . . . . . .  25
        6.3.2.2.3.2Other 1022 Formats  . . . . . . . . . . . . . .  29
        6.3.2.3   Example  . . . . . . . . . . . . . . . . . . . .  30
        6.3.2.4   Data-Positioning Options . . . . . . . . . . . .  33
        6.4       Error Handling . . . . . . . . . . . . . . . . .  37
        7.0     WILDCARD MATCHING WITH FIND AND SEARCH . . . . . .  38
        7.1       Overview . . . . . . . . . . . . . . . . . . . .  38
        7.2       Examples . . . . . . . . . . . . . . . . . . . .  40
        7.3       Comments . . . . . . . . . . . . . . . . . . . .  41
        8.0     RECORD-LEVEL LOCKING . . . . . . . . . . . . . . .  41
        8.1       Record-level Locking   . . . . . . . . . . . . .  41
        8.1.1     Enabling Record-level Locking For A Data Set   .  42
        8.1.2     Locking Records With GETREC $LOCK  . . . . . . .  43
        8.1.3     Locking Records With LOCK ON RECORD  . . . . . .  44
        8.2       User-defined Locks On A Data Set   . . . . . . .  45
        8.2.1     Userlocks With Collections   . . . . . . . . . .  48
        8.3       Host Language Calls For Record Level And 
                  User-defined Locking   . . . . . . . . . . . . .  48
        8.3.1     FORTRAN  . . . . . . . . . . . . . . . . . . . .  48
        8.3.1.1   The GETREC Command -- DBGREC   . . . . . . . . .  48
        8.4       Retrieving An Entire Record -- DBGET   . . . . .  49
        8.4.0.1   The LOCK Command -- DBLOCK   . . . . . . . . . .  51
        8.4.1     COBOL  . . . . . . . . . . . . . . . . . . . . .  53
        8.4.1.1   The GETREC Command -- DBGREC   . . . . . . . . .  53
        8.5       Retrieving An Entire Record -- DBGET   . . . . .  54
        8.5.0.1   The LOCK Command -- DBLOCK   . . . . . . . . . .  54
        8.6       Locking Error Messages . . . . . . . . . . . . .  56
        9.0     PL1022 DEBUGGING TOOLS . . . . . . . . . . . . . .  57



        10.0    TOPS-20 FORTRAN VERSION 10 WITH EXTENDED SECTIONS   58
        11.0    EXPANDED INFORM COMMAND  . . . . . . . . . . . . .  58
        11.1      INFORM DMX . . . . . . . . . . . . . . . . . . .  58
        11.1.1    Overview . . . . . . . . . . . . . . . . . . . .  58
        11.1.2    Example  . . . . . . . . . . . . . . . . . . . .  60
        11.1.3    Comments . . . . . . . . . . . . . . . . . . . .  61
        11.2      INFORM STRUCTURE . . . . . . . . . . . . . . . .  62
        11.3      INFORM STRUCTURE TABLE . . . . . . . . . . . . .  63
        11.4      INFORM STRUCTURE DATA  . . . . . . . . . . . . .  65
        11.5      INFORM ATTRIBUTE . . . . . . . . . . . . . . . .  65
        11.6      INFORM STATUS  . . . . . . . . . . . . . . . . .  66
        11.7      INFORM VERSION . . . . . . . . . . . . . . . . .  66
        12.0    WILDCARDED ADMIT LISTS (TOPS-20) . . . . . . . . .  67
        13.0    DBA AS DIRECTORY STRING (TOPS-20)  . . . . . . . .  67
        14.0    1022SA INFORM DBA COMMAND  . . . . . . . . . . . .  68
        15.0    1022SA BANNER COMMAND  . . . . . . . . . . . . . .  68
        16.0    CUSTOM DMI READER  . . . . . . . . . . . . . . . .  69
        16.1      Overview . . . . . . . . . . . . . . . . . . . .  69
        16.2      Examples . . . . . . . . . . . . . . . . . . . .  70
        16.2.1    FORTRAN Example  . . . . . . . . . . . . . . . .  70
        16.2.2    COBOL Example  . . . . . . . . . . . . . . . . .  71
        17.0    THE NODME OPTION OF LOAD, APPEND, AND TRANSACT . .  72
        18.0    THE SCRATCH AREA . . . . . . . . . . . . . . . . .  73
        18.1      Overview . . . . . . . . . . . . . . . . . . . .  73
        18.2      SYSDCORESS And SYSCORESS . . . . . . . . . . . .  74
        18.3      SET SCRATCH  . . . . . . . . . . . . . . . . . .  74
        18.4      SYSSCRFILE . . . . . . . . . . . . . . . . . . .  75
        19.0    KEY $SCAN, KEY $CHECKSUM, AND KEY $VERIFY  . . . .  75
        20.0    SYSERRTEXT AND THE ERFCHK UTILITY  . . . . . . . .  77
        21.0    SYSTOPSID AND SYSTOPIID  . . . . . . . . . . . . .  78
        22.0    TEXT CONVERSION FUNCTIONS  . . . . . . . . . . . .  78
        22.1      $TEXT  . . . . . . . . . . . . . . . . . . . . .  78
        22.2      $TEXTL And $TEXTR  . . . . . . . . . . . . . . .  79
        23.0    $MOD FUNCTION  . . . . . . . . . . . . . . . . . .  80
        24.0    SYSFMSG  . . . . . . . . . . . . . . . . . . . . .  80
        25.0    SYSEXECKP  . . . . . . . . . . . . . . . . . . . .  81
        26.0    SYSNOYMD . . . . . . . . . . . . . . . . . . . . .  81
        26.1      Eight-Digit Dates  . . . . . . . . . . . . . . .  81
        26.2      Six-Digit Dates  . . . . . . . . . . . . . . . .  82
        26.3      Seven-Digit And Five-Digit Dates . . . . . . . .  82
        27.0    MAP BY SORT  . . . . . . . . . . . . . . . . . . .  82
        28.0    ENFORCEMENT OF RESERVED WORDS  . . . . . . . . . .  82
        29.0    DBRETN (FORTRAN) . . . . . . . . . . . . . . . . .  83
        30.0    DBEND DEBUGGING MESSAGE  . . . . . . . . . . . . .  84
        31.0    SORT22 . . . . . . . . . . . . . . . . . . . . . .  84
        32.0    FEATURES RELATING TO TOPS-20 MONITOR VERSION 6.1 .  85
        33.0    MISCELLANEOUS IMPROVEMENTS . . . . . . . . . . . .  85
        34.0    TABLE OF SYSTEM VARIABLES  . . . . . . . . . . . .  87
                                                                Page 1


1.0  INTRODUCTION

This document lists the 1022  documentation  and  summarizes  the  new
features of version 117B.



2.0  SYSTEM 1022 DOCUMENTATION

The current documentation for System 1022 is:

     1.  User's Reference Manual, Revision 4, May 1986.  This contains         ______ _________ ______
         complete information about the interactive use of 1022.  This
         manual is MANUAL.MEM on the distribution tape.   It  is  also
         available in printed form from Software House.

     2.  Documentation of New Features, Version 117B.  This  documents         _____________ __ ___ _________ _______ ____
         new  features  and  improvements  in  version  117B.   It  is
         available in the file 117B.MEM on the 1022 distribution tape.

     3.  Host Language Interface User's Reference Manual, Revision  5,         ____ ________ _________ ______ _________ ______
         May  1986.  This contains information needed to write and run
         FORTRAN, COBOL, and  MACRO  application  programs  using  the
         System  1022  subroutine library.  This manual is HOST.MEM on
         the distribution tape.  It is also available in printed  form
         from Software House.

     4.  Data Base Administrator's Manual, Revision 12, January, 1986.         ____ ____ _______________ ______
         This  explains  to the data base administrator how to install
         and maintain 1022.  This is available in  printed  form  from
         Software House.  The file is DBA.MEM on the 1022 distribution
         tape.

     5.  INSTAL.EXE.  This file enables the data base administrator to
         generate  a set of instructions for the installation of MACRO
         and the particular versions of FORTRAN and COBOL used at  the
         site.  INSTAL.EXE is included on the 1022 distribution tape.

     6.  Primer, 1st edition, October 1982.  This is  an  introduction         ______
         to  the  interactive  use  of  1022.  It is available only in
         printed form from Software House.

     7.  Report Writer Manual.  This contains a collection of reports,         ______ ______ ______
         each  with  a  detailed  description to illustrate how custom
         reports are written.  It supplements the Reports  chapter  of
         the  User's  Reference  Manual.  This is available in printed              ______  _________  ______
         form from Software House and in the file  REPMAN.MEM  on  the
         1022 distribution tape.

     8.  System 1022 Reference Book.  This is a pocket guide to  using         ______ ____ _________ ____
         1022  published  by  CompuServe.   It is available in printed
         form from Software House.
                                                                Page 2


     9.  1022.BWR.  This "beware" file contains  warnings  of  version
         incompatibilities  and potential problems in using the system
         for the  current  release.   It  is  available  in  the  file
         1022.BWR  on the 1022 distribution tape.  All of the items in
         this file belong to the data set  BEWARE.DMS  which  Software
         House also includes on the distribution tape.

    10.  BEWARE.DMC.  This report program uses BEWARE.DMS to report on
         version  incompatibilities  as  well as fixed and outstanding
         bugs.

    11.  BEWARE.DMS.  This data set lists outstanding bugs and changes
         made  to  System 1022.  This information is also given in the
         beware file, 1022.BWR.


To order printed copies of 1022 manuals, contact:

          Documentation Distribution
          Software House
          1105 Massachusetts Avenue
          Cambridge, MA  02138
          USA

          (617) 661-9440
                                                                Page 3


3.0  SUMMARY OF CHANGES TO 1022


      o  The Large Data Sets Module

      o  Multifile Data Sets for the Large Data Sets Module

      o  PC Extract:  Creating DIF and WKS Files

      o  Wildcard Matching with FIND and SEARCH

      o  Record-Level Locking

      o  PL1022 Debugging Tools

      o  TOPS-20 FORTRAN Version 10 with Extended Sections

      o  Expanded INFORM Command

          -  INFORM DMX

          -  INFORM STRUCTURE

          -  INFORM STRUCTURE TABLE

          -  INFORM STRUCTURE DATA

          -  INFORM ATTRIBUTE

          -  INFORM STATUS

          -  INFORM VERSION


      o  Wildcarded ADMIT Lists (TOPS-20)

      o  DBA as Directory String (TOPS-20)

      o  1022SA INFORM DBA Command

      o  1022SA BANNER Command

      o  CUSTOM DMI READER

      o  The NODME Option of LOAD, APPEND, and TRANSACT

      o  The Scratch Area

          -  SYSDCORESS and SYSCORESS

          -  SET SCRATCH

          -  SYSSCRFILE

                                                                Page 4


      o  KEY $SCAN, KEY $CHECKSUM, and KEY $VERIFY

      o  SYSERRTEXT and the ERFCHK Utility

      o  SYSTOPSID and SYSTOPIID

      o  Text Conversion Functions

      o  $MOD Function

      o  SYSFMSG

      o  SYSEXECKP

      o  SYSNOYMD

      o  MAP BY SORT

      o  Enforcement of Reserved Words

      o  DBRETN (FORTRAN)

      o  DBEND Debugging Message

      o  SORT22

      o  Features Relating to TOPS-20 Monitor Version 6.1

      o  Miscellaneous Improvements

      o  Table of System Variables




4.0  INTRODUCTION

Version 117B introduces two  major  internal  changes:   version  117B
contains  the internal structures that make it possible to support the
Large Data Sets Module, and each distribution  tape  has  been  custom
tailored for a site's particular licensed configuration.

Data sets created under 117A and 117B have an internal format that  is
different  from  that  of data sets created under previous versions of
1022.  117B supports both formats but  operates  more  efficiently  on
data  sets  in new format than on data sets in pre-117A format.  Thus,
conversion from old format to new is recommended.

Conversion from old to new format is a two-stage process.  First,  the
user  issues an UPTO command.  If there are key tables or delete lists
in the old format, UPTO issues a warning.  The  UPTO  command  sets  a
flag  in the data set so that subsequent KEY or OPTIcommands will
produce key tables in the new format.  Then, OPTIMIZE or KEY  is  used
to perform the actual format conversion.  The user can then repeat the
UPTO command to verify that all conversions have been done.  Until the
                                                                Page 5


old format structures are converted, data sets cannot exceed the block
and record maxima of previous versions of System 1022.

To use 117A or 117B data sets with previous versions of System 1022, a
similar  conversion  is necessary.  A BACKTO command specifies the old
format for creating key tables, and  it  issues  a  warning  that  key
tables  are  in  the  new  format.   After applying OPTIMIZE or KEY to
produce key tables in the old format, the user can repeat  the  BACKTO
command to verify that the data set is ready for the pre-117 version.

A new DMV file format is used in 117A and  117B.   Versions  117A  and
117B  can  read DMV files from prior versions of System 1022, but they
only write DMV files in the new format.  Prior versions of 1022 cannot
read new-format DMV files.



5.0  THE LARGE DATA SETS MODULE

The Large Data Sets Module increases  to  more  than  134,000,000  the
number  of  records  that  can be contained in a System 1022 data set.
Data sets can now occupy up to 268,000,000  blocks  each.   The  Large
Data Sets Module also supports multifile data sets.

Further enhancements to System 1022 optimize  the  handling  of  large
data  sets.  Users can now choose the appropriate format for selection
sets and can control the amount of scratch space that is allocated  to
selection  set  formation.   There  are tools that provide statistical
information about the key tables and data set inconsistencies.  All of
these features are described in detail below.



5.1  Multifile Data Sets

5.1.1  Overview

As of version 117A, it is possible for sites that  have  acquired  the
Large  Data  Sets  module  to  split  large System 1022 data sets over
several files on multidisk devices.  The  user  can  place  groups  of
records  or  the  key  tables  for  individual  attributes in separate
auxiliary files.  The user can thereby maintain the contiguity of  the
data  and  can  also  control  the allocation of space and balance the
system load.

The distribution of records and key  tables  over  separate  files  is
specified  in  the DMD file with the SET and AUXFILE statements in the
LOADING  SECTION,  and  with  the  KEYFILE  clause  of  the  ATTRIBUTE
statements  in  the  STRUCTURE SECTION.  Consider the following sample
DMD file:

LOADING SECTION
  SET MYFILE.DMS RECORDS 0
  AUXFILE AUX1.DMM RECORDS 10000
  AUXFILE AUX2.DMM
                                                                Page 6


  AUXFILE AUX3.DMM RECORDS 10000
          .
          .
          .
STRUCTURE SECTION
  ATTRIBUTE LAST_NAME ABBREV LN KEYED TEXT KEYFILE AUX2.DMM LENGTH 15
          .
          .
          .

In this case, the SET statement specifies that no records  are  to  be
stored in MYFILE.DMS.  Instead, they are to be stored in the auxiliary
files AUX1.DMM and AUX3.DMM.  If the RECORDS argument is omitted  from
the SET statement, the default number of records that the DMS file may
hold is the maximum (134,000,000).  The SET statement with an explicit
RECORDS  specification  must appear in the DMD file if auxiliary files
are to be used to store records.  The SET statement need not appear if
auxiliary files are to be used for storing key tables.

Auxiliary files, whether to hold records or key tables, are  specified
in  the  LOADING SECTION of the DMD file after the SET statement.  The
keyword AUXFILE precedes the name of each auxiliary file.  The default
extension for auxiliary files is DMM.  If an auxiliary file is to hold
records, the keyword RECORDS followed by a number must appear  in  the
AUXFILE  statement.   Otherwise, it is assumed that the file will hold
key tables.

When an auxiliary file is  named  without  a  RECORDS  clause  in  the
LOADING SECTION of a DMD file, that file may only be used to store key
tables.  In the STRUCTURE SECTION of that file, the KEYFILE clause  of
an  ATTRIBUTE  statement  assigns  the  key table associated with that
attribute to that auxiliary file as shown in the example given  above.
It is not necessary that the attribute be KEYED in the DMD file to use
the KEYFILE clause.  The KEYFILE clause can mean that if the attribute
is keyed in the future, the key tables will be stored in the specified
auxiliary file.



5.1.2  Determining File Size

SET and AUXFILE statements may include a BLOCKS clause to specify  the
maximum   size  that  the  file  can  reach.   (On  TOPS-20,  a  PAGES
specification may take the place of the BLOCKS clause.)  For example,

     SET MYFILE.DMS RECORDS 100000000 PAGES 10000000

or

  AUXFILE AUX1.DMM RECORDS 60000000 BLOCKS 6000000

If no BLOCKS (or PAGES) specification is explicitly made,  each  named
file,  except the last, defaults to an upper limit of 8,000,000 blocks
(2,000,000 pages).  The last file named in the LOADING SECTION may  be
as  large  as the difference of the combined limits of the other named
                                                                Page 7


files and  the  maximum  of  268,000,000  blocks  (67,000,000  pages).
User-specified  limits  on the last file are ignored by System 1022 up
to this number.

As a general rule, it suffices to let the size of the key  tables  (or
the  set  of  records)  limit  the size of the files to which they are
assigned with no explicit mention of  blocks  or  pages.   The  BLOCKS
(PAGES)  clause has essentially two uses.  When the default limits are
too small for the projected size of  your  auxiliary  files,  you  may
specify  a  larger  number  of  blocks (pages) with the BLOCKS (PAGES)
clause.  Numbers smaller than the default may be  specified  when  the
key  tables  and  records  are  to be split over more than 64 separate
files (the maximum number of blocks for a file as a whole  divided  by
the 8,000,000 block auxiliary file default).

The BLOCKS (PAGES) clause should be used with caution.   Suppose  that
the  block  limits  for a record-holding auxiliary file are too low to
accommodate the number of records specified.  System 1022 then  stores
the excess records in the next auxiliary file capable of holding them.
If no other auxiliary file named in the DMD can hold  the  records,  a
warning is issued and no more records are added.



5.1.3  Relocating Auxiliary Files

The user has the option of moving an auxiliary file to a new location,
such  as to a different device, by following a six-step procedure, the
first step of which is optional:

     1.  Before entering 1022, create an empty file  whose  descriptor
         names the new location;.le;Enter 1022 and open the main file

     2.  Issue the RELOCATE AUXFILE command

     3.  Close the main file

     4.  Exit from 1022

     5.  Either rename the auxfile to its new location or copy  it  to
         the new location and delete the original.

If you omit step  1,  the  following  message  will  appear  when  the
RELOCATE AUXFILE command finishes executing:

     %WARNING:  New AUXFILE does not currently exist

For example, on TOPS-20

     *OPEN MYFILE

     *RELOCATE AUXFILE AUX2.DMM PS:<LOPEZ>MYAUX2.DMM

     *CLOSE                     
                                                                Page 8


     *EXIT

     @RENAME AUX2.DMM PS:<LOPEZ>MYAUX2.DMM

                        or

     @COPY AUX2.DMM PS:<LOPEZ>MYAUX2.DMM
     @DELETE AUX2.DMM

Or, on TOPS-10

     *OPEN MYFILE

     *RELOCATE AUXFILE AUX2.DMM DSKA:MYAUX2.DMM[203,507]

     *CLOSE

     *EXIT

     .RENAME DSKA:MYAUX2.DMM[203,507] = AUX2.DMM

                      or

     .COPY DSKA:MYAUX2.DMM[203,507] = AUX2.DMM
     .DELETE AUX2.DMM

Note that both the old and new names for the auxiliary  file  must  be
given  in  issuing  the RELOCATE AUXFILE command.  The device on which
the file is  to  reside  must  also  be  specified.   To  successfully
relocate  (and  later  retrieve) an auxiliary file, all of these steps
must be executed in the order given here.



5.1.4  Checking For Auxiliary File Damage, Loss, Or Skew

When an OPEN command is given for a multifile data  set,  System  1022
automatically checks to make sure that all of the data set's auxiliary
files are present.  When the system variable SYSAUXCHK set to  0  (the
default),  1022  gives  an  error  message  if  any  of the data set's
auxiliary files are damaged or skewed.  When SYSAUXCHK is set to 1, no
such  checking  is performed and no such error messages are displayed.
SYSAUXCHK is both user settable and default settable.

If an auxiliary file is lost, whether  through  improvident  deletion,
renaming,  relocation, or disk damage, an attempt to open the data set
to which it belongs will produce a system error message:

     1022 GTJFN error (600104) File not found, File:  <filespec>

                                   or

     1022 GTJFN error (600077) No such file type, File:  <filespec>

where <filespec> is the file specification of the first auxiliary file
                                                                Page 9


that  1022 discovers missing from the data set.  This is followed by a
1022 error message:

     ? (OP15) Auxiliary file not found or has invalid dataset ID.

To open the data set when one or more of its auxiliary files has  been
lost, issue the command:

     OPEN <data set name> $MISSING

The system error message is then repeated, followed by the message:

     %%MISSING AUXFILE, CONTINUING...

If more than one auxiliary  file  has  been  lost,  the  system  error
message  is  repeated with the name of the next missing file, followed
by  another  %%MISSING  AUXFILE,  CONTINUING...  These  messages   are
repeated until all the missing auxiliary files have been listed.

At this point, 1022 distinguishes among three types of auxiliary  file
loss.   If  all that has been lost is an empty file (an auxiliary file
with no records or key tables in it), no further  error  messages  are
issued.   If an empty file was lost, a replacement will be created for
it when the user issues an update command (such as UPDATE ON, ADD,  or
KEY).   If  key  tables  were  lost,  1022  issues  a  warning message
informing the user of that fact when the first command  involving  key
tables  is  issued.   The  user  should  then rekey with a KEY NOREUSE
command.  System 1022 will create a new auxiliary file to hold the key
tables.   Note  that  when key tables have been lost, rekeying must be
accomplished before any update commands can be safely issued.

The other two kinds of loss involve missing records.  If an  auxiliary
file   holding  records  becomes  lost,  another  warning  message  is
displayed.  It lists the SYSIDs of the missing records and  gives  the
file  specification  of  the lost file.  For example, if the auxiliary
file AUX1.DMM of the data set MYFILE.DMS holds records  1000-2000  and
this file is lost, the command

     OPEN MYFILE $MISSING

will produce the following messages:

     1022 GTJFN error (600104) File not found:  File DSK:AUX1.DMM
     %%MISSING AUXFILE, CONTINUING ...
     %%WARNING:  records 1000 through 2000  in  AUXFILE  AUX1.DMM  are
     missing!

If the lost file does not contain the last records in  the  data  set,
the user has two options:

     1.  FIND the missing records, DELETE them, and then, if possible,
         append  a  back-up copy of the records in the lost file.  You
         will probably then wish to DUMP all of the records to  a  new
         file, since you cannot rekey until you do so.
                                                               Page 10


     2.  FIND all but the lost records, DUMP the found  records  to  a
         new file, and reload.


If the lost file holds the last records in the  data  set,  1022  will
only  open  the  data  set  READONLY  and  will  issue  the  following
additional message:

     %%New records would be liable to be added to this AUXFILE
     %%Data set restricted to READONLY access

This restriction keeps users from trying to add records to the end  of
the  data  set after that part of the data set has been lost.  When an
auxiliary file holding the last records in the data set is  lost,  the
best  the user can do is to FIND all of the records except those whose
SYSIDs are listed as missing, DUMP the found  records  to  a  new  DMI
file, and reload.



6.0  PC EXTRACT:  CREATING DIF AND WKS FILES

6.1  Introduction

Enhancements to the INIT and PRINT commands enable the user to  create
files in Data Interchange Format (DIF) and Lotus 1-2-3 worksheet (WKS)
format from within 1022 and to write 1022 data  directly  to  them  *.
These files can then be down-loaded to a personal computer with any of
the standard communications protocols (such as Kermit) or accessed
with an integration tool (such as Mobius) for spreadsheeting or  other
PC  applications  **.  DIF files created from within 1022 are in 8-bit
ASCII format, and WKS files created from  within  1022  are  in  8-bit
binary format.  Care should therefore be taken when down-loading these
files to make sure that your communication protocol expects  an  8-bit
file rather than a standard TOPS-10 or TOPS-20 7-bit file.



6.2  DIF Files

6.2.1  The INIT DIF Command

The DIF option of the INIT command lets you create an 8-bit ASCII  DIF
file  from  within 1022.  A DIF file may be seen as a table of data in
which vectors and tuples correspond, respectively, to the columns  and
rows  of  a standard spreadsheet grid.  Each tuple (row) of a DIF file
is a uniform number of vectors  (columns)  wide.   Tuples  are  either
filled  with data or padded out with blanks.  A 1022 DIF file can have
.............
* DIF is a trademark of Software  Arts  Products  Corporation.   Lotus
1-2-3 is a registered trademark of Lotus Development Corporation.

............
** Mobius  is  a  trademark  of  FEL  Computing,  a  division  of  FEL
Industries.
                                                               Page 11


up to 2^18-1 columns (vectors) and 2^18-1 rows (tuples).   The  syntax
of the INIT DIF command is:

     INIT DIF [ COL <c> ] [ ROW <r> ]

       [ NCOLS <n> ] <channel number> <file name>

where:

COL <c>         Directs 1022 to begin printing data at column  <c>  of
                the  DIF file when the first PRINT ON <channel number>
                command is given (see below).  <c>  is  an  alphabetic
                string   representing  a  spreadsheet  column  in  the
                sequence A,B,C,...Z,AA,AB...  within the range of A to
                NWTL.  The default is A.  When a letter greater than A
                is specified in the COL clause, 1022 prints blanks  in
                each  of  the  columns from A to column <c-1> and then
                begins printing data at column <c>.

ROW <r>         Directs 1022 to begin printing data at row <r> of  the
                DIF  file  when  the  first  PRINT ON <channel number>
                command is given.  <r> is a positive integer between 1
                and  2^18-1.   The  default  is  1.   When  an integer
                greater than 1 is specified in the  ROW  clause,  1022
                fills each row of the file from 1 to <r-1> with blanks
                before printing data at row <r>.

NCOLS <n>       Specifies the number of columns that the DIF  file  is
                to  have  in addition to any included as blanks as the
                result of a COL specification greater than A.  <n>  is
                a  positive integer between 1 and 2^18-1.  The default
                is 100.

                System 1022 enforces the NCOLS limit  by  padding  out
                the  row  with  blanks  when  more  columns  have been
                specified than are needed to  hold  the  data  and  by
                truncating  any  print  list  that is too long for the
                number of columns specified.  In the  latter  case,  a
                warning  is  issued.   It is strongly recommended that
                you use the NCOLS option to limit the size of your DIF
                file for greatest efficiency.

channel number  Is the number of the channel on which the DIF file  is
                to be created.  The number is between 1 and 8.

file name       Is the name of the DIF file.  The default extension is
                .DIF.

For example:

     INIT DIF 2 MYFILE

       This command creates the file MYFILE.DIF  on  channel  2.   The
       file  will  be  100 vectors (columns) wide, and 1022 will begin
       printing data at cell A1 (column A, row 1) when the first PRINT
                                                               Page 12


       ON  2  command  is given.  Rows only partially filled with data
       will be padded out to 100 columns with blanks.

     INIT DIF COL B NCOLS 20 2 MYFILE

       This command creates the file MYFILE.DIF  on  channel  2.   The
       file  will  be  21  vectors  wide.   When  the first PRINT ON 2
       command is given, 1022 will write a blank in column A of row  1
       and  then begin printing data at column B of row 1, padding out
       any unfilled columns in the row with blanks.   Each  succeeding
       PRINT  ON  2  command  will  write  a  blank in column A, begin
       printing data at column B, and pad  out  any  unfilled  columns
       with blanks.




6.2.2  Printing To A 1022 DIF File

Once you have created a DIF file on a specified channel with the  INIT
DIF  command,  you  direct  1022  data  to that file with the PRINT ON
<channel number> command.  System 1022 data  types  are  automatically
converted  to  DIF  data  types.   Most of the conventional 1022 print
formats and defaults can be used to format the data written to the DIF
file.



6.2.2.1  Data Type Conversion

The DIF file standard  recognizes  only  two  data  types:   text  and
numeric.   Numeric  data  is represented by ASCII digit strings.  Text
data is represented by ASCII  character  strings  enclosed  in  double
quotation  marks.   When  1022  data  is  printed  to  a DIF file, its
representation as a string is essentially the same as it would  be  if
it  were  the output of a regular 1022 PRINT command.  Whether a given
string is interpreted as text or numeric is determined by an automatic
translation  between  1022 and DIF data types.  This translation takes
the following form:

          1022 Data Type --> DIF Data Type          ____ ____ ____     ___ ____ ____

          Integer            Numeric
          Double Integer     Numeric
          Real               Numeric
          Date               Text
          Text               Text

Note the conversion of the 1022 Date type to  DIF  text.   This  means
that a 1022 date will appear as a text string in the DIF file and will
therefore not be able  to  be  used  in  any  calculations.   If  your
application  needs  a computational date, you can write one to the DIF
file with the 1022 command:

     PRINT ON <channel number> $INT(date-item)
                                                               Page 13


This will return the number of days since 1/1/1800  in  integer  form,
which  may  or  may  not  correspond  to  the  way in which the target
spreadsheet or application calculates computational dates.  If it does
not,  you can offset the $INT result by the appropriate amount to make
up the difference.



6.2.2.2  Print Formats

Most of the conventional 1022 print formats can be used in writing  to
a  DIF  file  with PRINT ON <channel number> commands.  The 1022 print
formats that are not supported in writing to DIF files are $, $3,  $4,                 ___
S, T, C, and L.

With only two exceptions (X and /),  format  statements  in  PRINT  ON
<channel number> commands directed to DIF files produce text and digit
strings that are essentially the same as the ones normally produced by
1022  PRINT  commands.  PRINT ON <channel number> commands in which no
format statement is included assume the  customary  1022  defaults  (G
format).   The  default formats for Date, Text, Integer, and Real data
are illustrated in the example in the following section.

Ordinarily, the X specification  in  a  1022  print  format  statement
generates a blank.  In a PRINT ON <channel number> command directed to
a DIF file, the X causes a vector (column) to be written as  a  blank.
Thus,  if  you  had  created  a DIF file with the standard defaults on
channel 2, the command

     PRINT ON 2 LAST_NAME FIRST_NAME FMT G 2X G END

would print the value of the attribute LAST_NAME in  column  A,  print
blanks  in  columns  B  and  C,  and  print the value of the attribute
FIRST_NAME in column D.

Similarly, while the / specification in a PRINT  command  generates  a
blank  line, in a PRINT ON <channel number> directed to a DIF file a /
causes a tuple (row) to be filled with blanks.  Thus, the command

     PRINT ON 2 LAST_NAME FIRST_NAME FMT 2A / END

would print the value of LAST_NAME  in  column  A  and  the  value  of
FIRST_NAME  in column B of tuple (row) n and would fill the next tuple
(row n+1) with blanks before writing any more data to the file.



6.2.2.3  Example

A university administration  maintains  two  System  1022  data  sets,
STDNTS.DMS and WRKRS.DMS.  STDNTS.DMS contains information about every
currently enrolled student, including the grade point average (GPA) of
each  student.   WRKRS.DMS  contains  information  about every student
employed by  the  university,  including  the  number  of  hours  each
employee  has worked during the past month (MTOT) and the total number
                                                               Page 14


of hours each student has worked up to the beginning  of  the  present
month  (TOTH).   Every  student  is  uniquely identified by his or her
student-identification number (ID).  ID  is  an  attribute  common  to
STDNTS and WRKRS.

The description files for the two data sets look like this:

                              STDNTS.DMD

     ATTRIBUTE STUDENT_ID ABBREV ID INTEGER KEYED COL 1 6
     ATTRIBUTE GRADE_POINT_AVERAGE ABBREV GPA REAL COL 7 10

                              WRKRS.DMD

     ATTRIBUTE LAST_NAME ABBREV LN TEXT KEYED COL 1 15
     ATTRIBUTE FIRST_NAME ABBREV FN TEXT COL 16 30
     ATTRIBUTE STUDENT_ID ABBREV ID INTEGER KEYED COL 31 36
     ATTRIBUTE YEAR_OF_BIRTH ABBREV YOB DATE COL 37 42
     ATTRIBUTE HOURS_THIS_MONTH ABBREV MTOT REAL COL 43 48
     ATTRIBUTE RATE_OF_PAY ABBREV RATE REAL COL 49 52
     ATTRIBUTE HOURS_TO_DATE ABBREV TOTH REAL COL 53 58

Periodically, someone at the university monitors the academic standing
of all student employees by running a PL1022 program (WARNEM.DMC) that
extracts information from STDNTS.DMS and WRKRS.DMS and writes it to  a
DIF  file (WARNEM.DIF) that is then down-loaded to a personal computer
and read into a spreadsheet.

WARNEM.DMC and a sample of  its  output  (WARNEM.DIF)  are  reproduced
below.

                              WARNEM.DMC

     !WARNEM.DMC locates the student employees whose GPA's
     !have fallen below 3.5 and writes their names, ID's,
     !current GPA's, and total hours worked to date to
     !the file WARNEM.DIF.

     OPEN STDNTS WRKRS.
     JOIN STDNTS WRKRS VIA ID.
     DBSET WRKRS.
     FIND ALL.
     SORT LN.
     LET SYSIFTYPE 1.
     INIT DIF NCOLS 5 2 WARNEM.DIF.  !We only need 5 columns
                                     !to hold the data
     PL START.
     PRINT ON 2 SYSDATE.
     REPEAT
     GETREC LEAVE.
     IF 1.GPA LT 3.5 THEN
     PRINT ON 2 LN FN ID 1.GPA MTOT+TOTH.
     ENDIF.
     UNTIL 1 EQ 2.  !Or until we run out of records
     PL END.
                                                               Page 15


     RELEASE 2.


                    WARNEM.DIF

                    TABLE
                    0,1
                    ""
                    VECTORS
                    0,00000005
                    ""
                    TUPLES
                    0,00000006
                    ""
                    DATA
                    0,0
                    ""
                    -1,0
                    BOT
                    1,0
                    "11/19/1985"
                    1,0
                    ""
                    1,0
                    ""
                    1,0
                    ""
                    1,0
                    ""
                    -1,0
                    BOT
                    1,0
                    "AKHMAJIAN      "
                    1,0
                    "ARAM           "
                    0,22446
                    V
                    0, 3.2500000
                    V
                    0, 460.00000
                    V
                    -1,0
                    BOT
                    1,0
                    "GINGOLD        "
                    1,0
                    "SETH           "
                    0,22296
                    V
                    0, 3.0000000
                    V
                    0, 80.000000
                    V
                    -1,0
                    BOT
                                                               Page 16


                    1,0
                    "JONES          "
                    1,0
                    "ALBA           "
                    0,22441
                    V
                    0, 3.0000000
                    V
                    0, 263.00000
                    V
                    -1,0
                    BOT
                    1,0
                    "LENK           "
                    1,0
                    "MARGARET       "
                    0,22223
                    V
                    0, 3.0000000
                    V
                    0, 320.00000
                    V
                    -1,0
                    BOT
                    1,0
                    "NICHOLS        "
                    1,0
                    "JOSHUA         "
                    0,22004
                    V
                    0, 3.2500000
                    V
                    0, 230.00000
                    V
                    -1,0
                    EOD




If WARNEM.DIF were  then  read  into  a  spreadsheet,  it  would  look
something like this:

                                                               Page 17



         A           B         C         D         E         F        G
1    11/19/1985
2    AKHMAJIAN     ARAM       22446     3.25      460.00
3    GINGOLD       SETH       22296     3.00       80.00
4    JONES         ALBA       22441     3.00      263.00
5    LENK          MARGARET   22223     3.00      320.00
6    NICHOLS       JOSHUA     22004     3.25      230.00
7
8
9
10




6.2.2.4  Data-Positioning Information

When writing to a DIF file, 1022 uses three internal counters to  keep
track  of  the tuple (row) and vector (column) to which it is printing
or is about to print.  One of these counters points to the tuple (row)
to which 1022 is printing or is about to print.  Another points to the
vector (column) to which 1022 is printing or is about to  print.   And
the  third  points  to the vector (column) to which 1022 will begin to
print data (as opposed to blanks) when a  PRINT  ON  <channel  number>
command is given.

The user can ascertain the current position of  each  of  these  three
pointers  by  printing  the  current  value  of  each  of three system
variables:  SYSPCROW, SYSPCCOL, and SYSPCRESET.  SYSPCROW(n) points to
the  row (tuple) to which 1022 is printing or will begin printing when
the next PRINT ON <n> command is given.  And SYSPCCOL(n) points to the
column  (vector) to which 1022 is printing or will begin printing when
the next PRINT ON <n> command is given.  SYSPCRESET(n) points  to  the
column  (vector)  to which 1022 will begin printing data when the next
PRINT ON <n> command is given.

SYSPCROW and SYSPCCOL are set by  default  to  0  when  the  INIT  DIF
command  is  given.   This means that 1022 will begin printing at cell
A1,  that  is,  at  tuple  1,  vector  1.   (SYSPCROW,  SYSPCCOL,  and
SYSPCRESET  are  all "zero-origin," so that the value of each variable
is  always  one  less  than  the  row  or  column  to  which   it   is
pointing.)  If  no  COL  clause  is specified in the INIT DIF command,
SYSPCRESET will also be set to 0 by  default.   Otherwise,  SYSPCRESET
has the value determined by the argument of the COL clause.  The value
of SYSPCROW(n) is incremented when each PRINT ON <n> command  finishes
executing.   A  /  print  format  statement  also  causes the value of
SYSPCROW(n) to be incremented during the execution of a PRINT  ON  <n>
command.   The  value  of SYSPCCOL(n) is incremented as a PRINT ON <n>
command executes and is reset to 0 when execution is completed.  An  X
format  statement also causes SYSPCCOL(n) to be incremented during the
execution of a PRINT ON <n> command.

For example, suppose that the following two commands have been given:
                                                               Page 18


     INIT DIF COL C ROW 3 2 MYFILE
     PRINT ON 2 FIRST_NAME LAST_NAME FMT A X A /

The command

     PRINT SYSPCROW(2)

will return the value 4, since 1022 has printed two rows of blanks  as
a result of the ROW clause in the INIT command, has printed FIRST_NAME
and LAST_NAME on the third row, and  has  filled  the  next  row  with
blanks as a result of the / format statement, so the next row to which
1022 will print is row 5.

The command

     PRINT SYSPCCOL(2)

will return a value of 0, since 1022 always begins printing at  column
A, even if it is only printing blanks.

The command

     PRINT SYSPCRESET(2)

will return a value of 2 because the COL clause  specified  that  1022
was to begin printing data at column C.

Another way of finding out the  tuple  and  vector  (row  and  column)
coordinates  of  the  cell  to  which 1022 is currently pointing is to
print the  value  of  the  system  function  $SYSPCPOS.   $SYSPCPOS(n)
returns  the ASCII representation of the cell to which SYSPCROW(n) and
SYSPCCOL(n) are currently pointing.  If the command

     PRINT $SYSPCPOS(2)

were given immediately after the INIT and PRINT ON 2 commands  in  the
present example, the result would be A5.



6.3  WKS Files

6.3.1  The INIT 123 Command

You can create a WKS file from within 1022 with the INIT 123  command.
The INIT 123 command allows you to create a WKS format file with up to
2^16-1 columns and 2^16-1 rows.  The WKS files produced  by  the  1022
INIT  123 command are in Lotus 1-2-3 version 1A format.  The syntax of
the INIT 123 command is:

                                      { [ RWISE ] }
     INIT 123 [ COL <c> ] [ ROW <r> ] {           }
                                      { [ CWISE ] }

       [ [ NRANGE <name> <c1> <r1> <c2> <r2> ]... ]
                                                               Page 19


         <channel number> <file name>

where:

COL <c>         Directs 1022 to begin printing at column  <c>  of  the
                WKS  file  when  the  first  PRINT ON <channel number>
                command is given (see below).  <c>  is  an  alphabetic
                letter  (A,  B,  C...Z)  or  or  string  of alphabetic
                letters (AA,  AB,  AC...AAA,  AAB...)  representing  a
                spreadsheet column within the range of A to CRXP.  The
                default is A.

ROW <r>         Directs 1022 to begin printing at row <r> of  the  WKS
                file  when the first PRINT ON <channel number> command
                is given.  <r> is a positive  integer  between  1  and
                2^16-1.  The default is 1.

RWISE           Directs 1022 to print to the WKS file top  to  bottom,
                filling  the  cells  of  a  single  column, row by row
                (rowwise),  with  each  PRINT  ON   <channel   number>
                command,  instead  of  printing left to right, filling
                each of the  cells  of  each  row,  column  by  column
                (columnwise).   This  option  is  especially useful in
                writing keyboard macros (see below).

CWISE           Directs 1022 to print to the WKS file left  to  right,
                filling  the  cells  of a single row, column by column
                (columnwise), with  each  PRINT  ON  <channel  number>
                command.  CWISE is the default.

NRANGE          Allows you to specify a Named Range in  the  WKS  file
                that you are creating:

                  <name>      Is the character string that  identifies
                              the Named Range.  A name may be up to 15
                              characters.   Names   longer   than   15
                              characters  are  automatically truncated
                              with a warning.
                  <c1> <r1>   Are the column and row coordinates  that
                              define the beginning of the Named Range.
                              <c1> is  an  alphabetic  letter  (A,  B,
                              C...Z)   or   or  string  of  alphabetic
                              letters  (AA,  AB,   AC...AAA,   AAB...)
                              representing a spreadsheet column within
                              the range of  A  to  CRXP.   <r1>  is  a
                              positive  integer  between 1 and 2^16-1.
                              <c1> and <r1> must  be  separated  by  a
                              space.
                  <c2> <r2>   Are the column and row coordinates  that
                              define the end of the Named Range.  <c2>
                              is an alphabetic letter (A, B, C...Z) or
                              or string of alphabetic letters (AA, AB,
                              AC...AAA,   AAB...)    representing    a
                              spreadsheet column within the range of A
                              to CRXP.  <r2>  is  a  positive  integer
                                                               Page 20


                              between  1  and  2^16-1.   <c2> and <r2>
                              must be separated by a space.

                You can specify as many Named Ranges as you wish.

channel number  Is the number of the channel on which the WKS file  is
                to be created.  The number is between 1 and 8.

file name       Is the name of the WKS file.  The default extension is
                .WKS.

For example:

     INIT 123 2 MYFILE

       This command creates the file MYFILE.WKS  on  channel  2.   The
       first  PRINT  ON  2 command will start writing 1022 data to the
       file at cell A1.

     INIT 123 COL B 2 MYFILE

       This command creates the file MYFILE.WKS  on  channel  2.   The
       first  PRINT  ON  2 command will start writing 1022 data to the
       file at cell B1.

     INIT 123 COL J RWISE NRANGE \0 J 1 J 12 2 MYMAC

       This command creates the file MYMAC.WKS on channel 2.  The  COL
       clause  directs  1022 to begin printing at cell J1 of the file.
       The RWISE clause directs 1022 to  print  to  the  file  top  to
       bottom  rather than left to right, that is, to direct output to
       the cells in column J, row by row, with the first  PRINT  ON  2
       command.   Subsequent PRINT ON 2 commands will direct output to
       the cells in succeeding columns, row by  row,  top  to  bottom.
       The  NRANGE  clause  specifies  that the file is to contain the
       Named Range "\0" and that the range is to  consist  of  rows  1
       through 12 of column J.



6.3.2  Printing To A WKS File

Once you have created a WKS file on a specified channel with the  INIT
123  command,  you  direct  1022  data  to that file with the PRINT ON
<channel number> command.  System 1022 data  types  are  automatically
converted  to  Lotus  data types.  Most of the conventional 1022 print
formats, as well as the new "L" specifications, can be used to  format
the data written to a WKS file.  Three new system variables (SYSPCCOL,
SYSPCRESET, and SYSPCROW) and a new system function ($SYSPCPOS)  allow
you to control the positioning of the data in a WKS file.
                                                               Page 21


6.3.2.1  Data Type Conversion

When 1022 data  is  printed  to  a  WKS  file,  1022  data  types  are
automatically  translated  into Lotus data types.  The results of this
translation vary according  as  L  specifications,  conventional  1022
print format statements, or unformatted print statements appear in the
PRINT ON <channel number> commands used to  write  to  the  WKS  file.
When  L  specifications  or  no  print format statements appear in the
PRINT ON <channel number> commands that write to  the  WKS  file,  the
following translations between data types are automatically made:

     1022 Data Type -->  Lotus Data Type     ____ ____ ____      _____ ____ ____

     Integer             Integer or Real.  If the 1022  integer  value
                         is  greater  than +32767 or less than -32767,
                         it is converted to  a  real.   Otherwise,  it
                         remains an integer.

     Double Integer      Integer or real.  If the 1022 double  integer
                         value  is  greater  than  +32767 or less than
                         -32767,  it   is   converted   to   a   real.
                         Otherwise, it remains an integer.

     Real                Real.

     Date                Integer or Real.  System 1022 stores  a  date
                         as  a  binary integer equalling the number of
                         days since 1/1/1800 (1/2/1800  =  1).   Lotus
                         1-2-3  stores  a  date  as  a  binary integer
                         equalling the number of days since 12/31/1899
                         (1/1/1900   =   1).   When  a  1022  date  is
                         translated   to   a    Lotus    date,    1022
                         automatically  does  the necessary arithmetic
                         to perform  the  conversion  correctly.   If,
                         after  this  conversion,  the resulting Lotus
                         integer is larger than 32767, it is converted
                         to  a  real.   System 1022 defaults the Lotus
                         display format of a date to (Lotus) D1.

     Text                Label  (Text).   Lotus  limits  the   maximum
                         length   of   a   Label  to  240  characters,
                         including a Label Prefix  and  a  terminating
                         null,  both  of which are automatically added
                         to the string by 1022 during the  process  of
                         translation.  The Label Prefix that 1022 adds
                         is a single quotation  mark  (').   Any  1022
                         text  expression  or  literal longer than 238
                         characters will be truncated with  a  warning
                         to  238  characters when it is written to the
                         WKS file.

When conventional 1022 print formats (A, I, F, G, and so on) are  used
in  printing to a WKS file, all 1022 data types are converted to Lotus
Labels (Text), regardless of the original 1022 data  type.   The  same
constraints  on  length  and  composition  that  apply to Lotus Labels
                                                               Page 22


derived from 1022 Text  types  via  PRINT  ON  commands  containing  L
specifications  or  unformatted print statements apply in this case as
well.



6.3.2.2  Print Formats

In directing 1022 output to a WKS file  with  the  PRINT  ON  <channel
number>  command, you can control the format in which the data will be
represented by using a combination of format statements and  defaults.
A  special  set of specifications ("L formats") has been introduced to
facilitate this operation.  When no print  formats  are  specified,  L
formats, rather than the conventional 1022 G formats, are the default,
since it is through L formatting that binary data translation  between
1022  and Lotus 1-2-3 is enabled.  Most of the conventional 1022 print
formats can also be  used.   The  1022  print  formats  that  are  not                                                                   ___
supported in writing to WKS files are $3, $4, S, T, and C formats.

Two 1022 data sets will be referred to in the examples that illustrate
the different print formats in the sections that follow.  The first of
these is STDNTS.DMS, and the second is WRKRS.DMS.  Both are maintained
by   a   university.   STDNTS.DMS  contains  information  about  every
currently enrolled student, including the grade point average (GPA) of
each  student.   WRKRS.DMS  contains  information  about every student
employed by  the  university,  including  the  number  of  hours  each
employee  has worked during the past month (MTOT) and the total number
of hours each student has worked up to the beginning  of  the  present
month  (TOTH).   Every  student  is  uniquely identified by his or her
student-identification number (ID).  ID  is  an  attribute  common  to
STDNTS and WRKRS.

The description files for the two data sets look like this:

                              STDNTS.DMD

     ATTRIBUTE STUDENT_ID ABBREV ID INTEGER KEYED COL 1 6
     ATTRIBUTE GRADE_POINT_AVERAGE ABBREV GPA REAL COL 7 10

                              WRKRS.DMD

     ATTRIBUTE LAST_NAME ABBREV LN TEXT KEYED COL 1 15
     ATTRIBUTE FIRST_NAME ABBREV FN TEXT COL 16 30
     ATTRIBUTE STUDENT_ID ABBREV ID INTEGER KEYED COL 31 36
     ATTRIBUTE YEAR_OF_BIRTH ABBREV YOB DATE COL 37 42
     ATTRIBUTE HOURS_THIS_MONTH ABBREV MTOT REAL COL 43 48
     ATTRIBUTE RATE_OF_PAY ABBREV RATE REAL COL 49 52
     ATTRIBUTE HOURS_TO_DATE ABBREV TOTH REAL COL 53 58
                                                               Page 23


6.3.2.2.1  L Format

You use L ("Lotus") format statements in a PRINT ON  <channel  number>
command  to  enable  the  conversion  of 1022 data types to Lotus data
types and to write 1022 data to a WKS file so that each item
will be displayed in the appropriate Lotus  version  1A  format.   The
form of an L format specification is

          (<r>)L(<m>).(<n>)

where:

<r>     Is an integer specifying a repeat count.  The default is 1.

<m>     Is an integer specifying the Lotus format  type  (see  below).
        The default is 12.

<n>     Is an integer specifying the number of decimal  places  to  be
        displayed (where n is between 1 and 15).  The default is 2 for
        Lotus formats 1-5.

In the case of an unformatted print statement in a PRINT  ON  <channel
number>  command that directs output to a WKS file, the default format
is L.

The Lotus format types and their numbers are as follows:

     Value of <m>        Lotus Display Format     _____ __ ___        _____ _______ ______

               1         Fixed point
               2         Scientific notation
               3         Currency ($)
               4         Percent
               5         Comma
               6         +/- (bar graph)
               7         General
               8         Date (DD-MMM-YY)
               9         Date (DD-MMM)
               10        Date (MMM-YY)
               11        Text
               12        Default.    That   is,   both    no    format
                         specification  and  a  plain  L specification
                         with no following <m> default to L12.  L12 is
                         the  global  format established for the 1-2-3
                         worksheet, the sole exception being that  the
                         default for a 1022 date is (Lotus) D1.

The following command file  (WKS2.DMC)  and  its  output  (WRKRS2.WKS)
illustrate the use of L formats:

                                                               Page 24


     OPEN WRKRS.
     FIND ALL.
     INIT 123  2 WRKRS.WKS.
     PRINT ON 2 SYSDATE FMT L8 END. 
     PRINT ON 2 "Last name" "First name" "Student ID" "YOB" "Hours" "Wage" -
      FMT 6L END.
     PRINT ON 2 LN FN ID YOB MTOT RATE  -
       FMT  3L L10 L1.1 L3  END. 
     RELEASE 2.

When WRKRS2.WKS is loaded into Lotus 1-2-3 and the column  widths  are
adjusted, it looks like this:

A1: (D1) 31333                                                          READY

        A          B           C         D         E         F        G
1    12-Dec-85
2    First name   Last name  Student ID  YOB       Hours   Wage   
3    ARNOLDS      SARAH          22034   Feb-63      44.5    $3.50  
4    AKHMAJIAN    ARAM           22446   May-63      60.0    $3.50     
5    BARLOW       ELIZABETH      22330   Mar-63      40.0    $3.50     
6    GINGOLD      SETH           22296   Jul-63      20.0    $3.00      
7    ARMONICO     LESTRO         21502   Jun-62      80.0    $4.00  
8    MCMAHON      JEAN           22929   Oct-63      40.0    $3.50
9    NICHOLS      JOSHUA         22004   Mar-63      55.0    $3.50
10   LENK         MARGARET       22223   Apr-63      35.0    $3.50
11   JONES        ALBA           22441   Dec-62      20.0    $3.50
12
13
14
15


The following example illustrates the default case.  The command  file
(WKS1.DMC)  reads 1022 data of type Date, Text, Integer, and Real from
the data set WRKRS.DMS and writes it to a WKS file (WRKRS1.WKS)  using
PRINT  ON  <channel  number>  commands  in which there are unformatted
print statements:

     OPEN WRKRS.
     FIND ALL.
     INIT 123 2 WRKRS1.WKS.
     PRINT ON 2 SYSDATE.
     PRINT ON 2 "Last name" "First name" "Student ID" "YOB" "Hours" "Wage".
     PRINT ON 2 LN FN ID YOB MTOT RATE.
     RELEASE 2.

When WRKRS1.WKS is loaded into Lotus 1-2-3 and the column  widths  are
adjusted, it looks like this:
                                                               Page 25


A1: (D1) 31333                                                        READY

        A          B           C         D         E         F       G
1    12-Dec-85
2    First name   Last name  Student ID  YOB       Hours   Wage   
3    ARNOLDS      SARAH          22034   15-Feb-63    44.5    3.5 
4    AKHMAJIAN    ARAM           22446   01-May-63      60    3.5    
5    BARLOW       ELIZABETH      22330   06-Mar-63      40    3.5    
6    GINGOLD      SETH           22296   13-Jul-63      20      3     
7    ARMONICO     LESTRO         21502   22-Jun-62      80      4
8    MCMAHON      JEAN           22929   15-Oct-63      40    3.5
9    NICHOLS      JOSHUA         22004   22-Mar-63      55    3.5
10   LENK         MARGARET       22223   16-Apr-63      35    3.5
11   JONES        ALBA           22441   12-Dec-62      20    3.5
12
13
14
15





6.3.2.2.2  Other Formats

6.3.2.2.3  Other Formats

6.3.2.2.3.1  X, /, And $ Formats

X, /, and $ format statements produce different results  depending  on
whether  the  output  of  the  PRINT  command  in which they appear is
directed to a columnwise WKS file, a rowwise WKS file, or  a  standard
7-bit ASCII file.

When  1022  is  writing  to  a  standard  7-bit  ASCII  file,   an   X
specification  generates  a blank, a / specification generates a blank
line, and a $ suppresses the automatic <RET> that normally  occurs  at
the  end  of  a print list.  When you specify a $ format, 1022 directs
the output of the next PRINT command to the  same  line  as  the  last
instead of to a new line.

When 1022 writes to a columnwise WKS file, the items in the print list
are  written  left  to  right,  one item to a cell, along a row.  An X
specification causes a cell in the current row to be skipped, and a  /
specification   causes  a  row  to  be  skipped.   A  $  specification
suppresses the end-of-list (EOL) action  that  normally  signals  1022
when  writing  to  a  columnwise  file to reset the column counter and
begin writing to the next row when the next PRINT ON <channel  number>
command  is  given.   When  you  specify  a $ format, 1022 directs the
output of the next PRINT ON <channel number> command to the next  cell
in current row instead of to the initial cell in the next row.

When 1022 writes to a rowwise WKS file, the items in  the  print  list
are  written  top  to  bottom,  one item to a cell, in a column.  An X
specification causes a cell in the current column to be skipped, and a
                                                               Page 26


/  specification  causes  a  column  to be skipped.  A $ specification
suppresses the end-of-list (EOL) action  that  normally  signals  1022
when  writing  to  a  rowwise  file to reset the row counter and begin
writing to the next column when the next  PRINT  ON  <channel  number>
command  is  given.   When  you  specify  a $ format, 1022 directs the
output of the next PRINT ON <channel number> command to the next  cell
in  the  current  column  instead  of  to the initial cell in the next
column.

The following table summarizes the results  of  X,  /,  and  $  format
statements  when  printing  to  standard  7-bit,  columnwise  WKS, and
rowwise WKS files.


                                             Format
                     ------------------------------------------------------
                     |        X        |        /       |        $        |
                     ------------------------------------------------------
                     |Inserts a space. |Inserts a blank |Suppresses <RET>.|
 7-Bit ASCII File    |                 |line.           |Next PRINT writes|
                     |                 |                |to same line.    |
                     ------------------------------------------------------
                     |Skips a cell in  |Skips a row.    |Suppresses <EOL> |
   CWISE WKS File    |the current row  |                |action. Next     |
                     |                 |                |PRINT writes to  |
                     |                 |                |same row.        |
                     ------------------------------------------------------
                     |Skips a row.     |Skips a cell in |Suppresses <EOL> |
   RWISE WKS File    |                 |the current     |action. Next     |
                     |                 |column.         |PRINT writes to  |
                     |                 |                |to same column.  |
                     ------------------------------------------------------



The following command file (GPHRS1.DMC) and  its  output  (GPHRS1.WKS)
illustrate the use of X, /, and $ formats when writing to a columnwise
WKS file from within 1022.

                              GPHRS1.DMC

      !GPHRS1.DMC reads the names, student ID's, and grade point
      !averages of the student workers and calculates the total
      !number of hours that each has worked to date. This 
      !information, which is drawn from the data sets WRKRS.DMS
      !and STDNTS.DMS, is then written columnwise to a worksheet
      !file, GPHRS1.WKS.
 
OPEN WRKRS STDNTS.
DBSET WRKRS.
FIND ALL.
SORT LN.
INIT 123  2 GPHRS1.WKS.
PRINT ON 2 SYSDATE FMT 2X  L8 //  END.  !Skip two cells, print date in C1,
PRINT ON 2 "Last name" "First name" -   !then skip two rows. Print in cells 
                                                               Page 27


  "Student ID" "GPA" "Total Hours" -    !A4-E4, then skip a row. Next PRINT
   FMT 5L / END.                        !will start writing at A6.
PL START.
REPEAT
GETREC LEAVE.                      !Get ready to print on new row.
PRINT ON 2 LN FN ID FMT 3L $  END. !Print LN, FN, and ID and hold the row.
MAP TO STDNTS VIA ID.              !Go get the corresponding record in
SORT LN.                           !the other data set and print the GPA
GETREC LEAVE.                      !on the same row and hold the row.
PRINT ON 2 GPA FMT  L1 $  END.     !Then go back to the original record
DBS WRKRS.                         !in the first data set and print the 
P ON 2  MTOT+TOTH FMT  L1 END.     !total hours on the same row.
UNTIL 1 EQ 2.                      !Or until we run out of records.
PL END.
RELEASE 2.


When GPHRS1.WKS is loaded into Lotus 1-2-3 and the column  widths  are
adjusted, it looks like this:

 
A1:                                                                 READY

        A          B           C         D         E         F     G
1                            12-Dec-85
2
3
4    First name   Last name  Student ID  GPA      Total Hours
5
6    AKHMAJIAN    ARAM           22446      3.25     460.00
7    ARMONICO     LESTRO         21502      3.50     560.00
8    ARNOLDS      SARAH          22034      3.50     371.00
9    BARLOW       ELIZABETH      22330      3.75     400.00
10   GINGOLD      SETH           22296      3.00      80.00
11   JONES        ALBA           22441      3.00     263.00
12   LENK         MARGARET       22223      3.00     320.00
13   MCMAHON      JEAN           22929      4.00     295.50
14   NICHOLS      JOSHUA         22004      3.25     230.00
15


The following command file (GPHRS2.DMC) and  its  output  (GPHRS2.WKS)
illustrate  the  use  of X, /, and $ formats when writing to a rowwise
WKS file from within 1022.

                                                               Page 28


                              GPHRS2.DMC

      !GPHRS2.DMC reads the names, student ID's, and grade point
      !averages of the student workers and calculates the total
      !number of hours that each has worked to date. This 
      !information, which is drawn from the data sets WRKRS.DMS
      !and STDNTS.DMS, is then written rowwise to a worksheet
      !file, GPHRS2.WKS.

OPEN WRKRS STDNTS.
DBSET WRKRS.
FIND ALL.
SORT LN.
INIT 123 RWISE  2 GPHRS2.WKS.
PRINT ON 2 SYSDATE FMT ////  L8 2X  END.  !Skip four columns, print date
PRINT ON 2 "Last name" "First name" -     !in E1, then skip two rows. Print
 "Student ID" "GPA" "Total Hours" -       !in cells A4-A8, then skip a column.
 FMT 5L / END.                            !Next PRINT starts writing at C4.
PL START.
REPEAT
GETREC LEAVE.                      !Get ready to print in new column.
PRINT ON 2 LN FN ID FMT 3L $  END. !Print LN, FN, and ID and hold the column.
MAP TO STDNTS VIA ID.              !Go get the corresponding record in
SORT LN.                           !the other data set and print the GPA
GETREC LEAVE.                      !in the same column and hold the column.
PRINT ON 2 GPA FMT  L1 $  END.     !Then go back to the original record
DBS WRKRS.                         !in the first data set and print the 
P ON 2  MTOT+TOTH FMT  L1 END.     !total hours in the same column.
UNTIL 1 EQ 2.                      !Or until we run out of records.
PL END.
RELEASE 2.


When GPHRS2.WKS is loaded into Lotus 1-2-3 and the column  widths  are
adjusted, it looks like this:

A1:                                                                 READY

        A         B         C         D         E         F        G
1                                              12-Dec-85
2
3
4    Last name            AKHMAJIAN  ARMONICO   ARNOLDS    BARLOW     GINGOLD   
5    First name           ARAM        LESTRO    SARAH      ELIZABETH  SETH     
6    Student ID               22446       21502     22034       22330    22296  
7    GPA                       3.25        3.50      3.50        3.75     3.00
8    Total Hours             460.00      560.00    371.00      400.00    80.00
9
10
11
12
13
14
15

                                                               Page 29


6.3.2.2.3.2  Other 1022 Formats

PRINT commands that direct output to WKS files can contain  statements
specifying  1022  print  formats  other  than L, X, /, and $.  Each of
these writes the 1022 data item to the WKS file as a Lotus Label (text
value).   Thus,  in  the  following  example,  the  values of the 1022
attributes LN (Text),  FN  (Text),  ID  (Integer),  YOB  (Date),  MTOT
(Real),  and  RATE (Real) are all written to WRKRS.WKS as text values.
As such, none can be used for computation.

The following command file (WKS3.DMC) is essentially  a  copy  of  the
file  WKS2.DMC  that  was  used  to  illustrate  L  formats in Section
6.3.2.2.1 above but with the L formats changed to non-L formats.

                               WKS3.DMC

OPEN WRKRS.
FIND ALL.
INIT 123  2 WRKRS.WKS.
PRINT ON 2 SYSDATE FMT D1 END. 
PRINT ON 2 "Last name" "First name" "Student ID" "YOB" "Hours" "Wage" -
 FMT 6A END.
PRINT ON 2 LN FN ID YOB MTOT RATE  -
  FMT  2A I D2 G F$1.2  END. 
RELEASE 2.


When WRKRS.WKS is loaded into Lotus 1-2-3 and the  column  widths  are
adjusted, it looks like this:

A1: 'December 12, 1985


        A           B             C           D           E             F
1    December 18, 1985
2    First name   Last name  Student ID  YOB           Hours        Wage   
3    ARNOLDS      SARAH      22034       Feb-15-1963    44.500000   $3.50       
4    AKHMAJIAN    ARAM       22446       May-01-1963    60.000000   $3.50       
5    BARLOW       ELIZABETH  22330       Mar-06-1963    40.000000   $3.50       
6    GINGOLD      SETH       22296       Jul-13-1963    20.000000   $3.00     
7    ARMONICO     LESTRO     21502       Jun-22-1962    80.000000   $4.00
8    MCMAHON      JEAN       22929       Oct-16-1963    40.000000   $3.50
9    NICHOLS      JOSHUA     22004       Mar-22-1963    55.000000   $3.50
10   LENK         MARGARET   22223       Apr-16-1963    35.000000   $3.50
11   JONES        ALBA       22441       Dec-12-1962    20.000000   $3.50
12
13
14
15

                                                               Page 30


6.3.2.3  Example

The following example illustrates the way in which a user might use  a
keyboard macro to format a WKS file created from within 1022.

Using the WRKRS.DMS and STDNTS.DMS data sets, someone at a  university
periodically  monitors  the academic standing of all student employees
by running a PL1022 program  (WARNWK.DMC)  that  extracts  information
from STDNTS.DMS and WRKRS.DMS and writes it to a WKS file (WARNEM.WKS)
that is then down-loaded to a personal computer and  read  into  Lotus
1-2-3 for spreadsheeting.

WARNWK.DMC is as follows:

     !WARNWK.DMC locates the student employees whose GPA's
     !have fallen below 3.5 and writes their names, ID's,
     !current GPA's, and total hours worked to date to
     !the file WARNEM.WKS.

     OPEN STDNTS WRKRS.
     JOIN STDNTS WRKRS VIA ID.
     DBSET WRKRS.
     FIND ALL.
     SORT LN.
     LET SYSIFTYPE 1.
     INIT 123 2 WARNEM.WKS.
     PL START.
     PRINT ON 2 SYSDATE FMT X L10 / END.
     PRINT ON 2 "Last Name" "First Name" "Student ID" "GPA" "Hours" -
      FMT 5L / END.
     REPEAT
     GETREC LEAVE.
     IF 1.GPA LT 3.5 THEN                      !Alternate data set reference
     PRINT ON 2 LN FN ID 1.GPA MTOT+TOTH -     !to joined data set gives us GPA.
       FMT 3A 2L1 END.                         !LN, FN, and ID will be text.
     ENDIF.
     UNTIL 1 EQ 2.
     PL END.
     RELEASE 2.


If WARNEM.WKS were then loaded into Lotus 1-2-3, it  would  look  like
this:

                                                               Page 31


A1:                                                                  READY

         A         B         C         D         E         F        G
1                Nov-85
2    
3    Last NameFirst NamStudent IGPA         Hours
4
5    AKHMAJIANARAM     22446         3.25     460.00 
6    GINGOLD  SETH     22296         3.00      80.00
7    JONES    ALBA     22441         3.00     263.00
8    LENK     MARGARET 22223         3.00     320.00
9    NICHOLS  JOSHUA   22004         3.25     230.00
10
11
12
13
14
15


The user would presumably then adjust the column widths with a  series
of   1-2-3   /Worksheet   Column   Set   commands   before   beginning
spreadsheeting  activities.    Alternatively,   instead   of   loading
WARNEM.WKS  directly  into  1-2-3,  the user could execute the command
file MACRO.DMC, which produces the file MACRO.WKS.  When MACRO.WKS  is
loaded into 1-2-3, it formats and loads WARNEM.WKS.

                              MACRO.DMC

     !MACRO.DMC produces the file MACRO.WKS, which
     !contains a keyboard macro that sets the column
     !widths for the worksheet WARNEM.WKS, which
     !is then loaded with the Lotus File Combine command.

     INIT 123  COL J RWISE -     !Macro commands have to be in single
       NRANGE \0  J 1 J 12 -     !column; J is free; \0 executes 
         2 MACRO.WKS.            !immediately.
     PRINT ON 2 "{goto}A1~" -    
        "/WCS15~" -         !Make column A 15 characters wide.
        "{goto}B1~" -
        "/WCS15~" -         !Make column B 15 characters wide.
        "{goto}C1~" -
        "/WCS12~" -         !Make column C 12 characters wide.
        "{goto}D1~" -
        "/WCS5~" -          !Make column D 5 characters wide.
        "{goto}E1~" -
        "/WCS8~" -          ! Make column E 8 characters wide.
        "{goto}A1~" -
        "/FCCEWARNEM~".     !Load WARNEM.WKS.
     RELEASE 2.


When MACRO.WKS is loaded into Lotus 1-2-3, it looks like this:

                                                               Page 32


A1:                                                                 READY

              A             B            C        D     E         F
    G
1                            Nov-85       
2
3     Last Name      First Name     Student ID  GPA  Hours
4
5     AKHMAJIAN      ARAM           22446       3.25  460.00
6     GINGOLD        SETH           22296       3.00   80.00
7     JONES          ALBA           22441       3.00  263.00
8     LENK           MARGARET       22223       3.00  320.00
9     NICHOLS        JOSHUA         22004       3.25  230.00
10
11
12
13
14
15




6.3.2.4  Data-Positioning Options

When writing to a WKS file, System 1022 keeps track  of  the  cell  to
which  it  is about to print by means of three internal counters.  One
of these points to the row on which 1022 is printing or  is  about  to
print;   another  points to the column on which 1022 is printing or is
about to print;  and the third points to the column (in  a  columnwise
file) or the row (in a rowwise file) to which 1022 will begin to print
at the beginning of the next PRINT ON <channel number> command.

The user can assign initial values to these counters with the COL  and
ROW  clauses of the INIT 123 command and can manipulate these counters
in either of two additional ways in order to  direct  1022  output  to
specific rows and columns of a WKS file.

One way of controlling data positioning is to use  the  X,  /,  and  $
formats described above in section 6.3.2.2.3.1.  In a columnwise file,
an X has the effect of incrementing the counter  that  points  to  the
column  to  which  1022  is  about  to  print;  a / increments the row
counter;  and a $ keeps the row counter from being incremented.  In  a
rowwise  file,  X  increments the row counter, / increments the column
counter, and $ keeps the column counter from being incremented.

A second way  to  control  data  positioning  is  to  use  the  system
variables  SYSPCROW, SYSPCCOL, and SYSPCRESET.  SYSPCROW points to the
row to which 1022 is printing or is about to print.   SYSPCCOL  points
to  the  column  to which 1022 is printing or is about to print.  In a
columnwise file, SYSPCRESET points to the column to  which  1022  will
begin  printing  when  it  executes a PRINT command;  and in a rowwise
file, SYSPCRESET points to the row at which 1022 will  begin  printing
when it executes a PRINT command.
                                                               Page 33


In a columnwise file, SYSPCROW, SYSPCCOL, and SYSPCRESET are  all  set
by  default  to 0 when the INIT 123 command is given.  This means that
unless instructed otherwise, 1022 will begin printing to the WKS  file
at  cell A1.  (All three of these variables are "zero-origin," so that
the value of the variable is always one less than the row or column to
which  it is pointing.) At the end of each PRINT command, the value of
SYSPCROW is automatically incremented by 1, and SYSPCCOL is  reset  to
the  value  of  SYSPCRESET, so that the next PRINT command will direct
output to the next row, starting at column  A.   To  make  1022  start
printing at a column other than column A, assign the appropriate value
to SYSPCRESET and SYSPCCOL.

In a rowwise file, SYSPCROW, SYSPCCOL, and SYSPCRESET are all  set  by
default  to  0  when  the  INIT 123 command is given.  This means that
unless instructed otherwise, 1022 will begin printing to the WKS  file
at  cell  A1.  At the end of each PRINT command, the value of SYSPCCOL
is automatically incremented by 1, and SYSPCROW is reset to the  value
of  SYSPCRESET,  so  that the next PRINT command will direct output to
the next column, starting at row 1.  To make 1022 start printing at  a
row  other  than row 1, assign the appropriate value to SYSPCRESET and
SYSPCROW.

To make 1022 skip rows and columns when printing to a  WKS  file,  you
can assign values to SYSPCROW, SYSPCCOL, and SYSPCRESET.  For example,
if you are writing to a columnwise WKS file on channel 2 and you  want
to  make  1022  begin each succeeding print row at column C, you could
give the following commands:

     LET SYSPCRESET(2) 2.

     LET SYSPCCOL(2) 2.     or     LET SYSPCCOL(2) SYSPCRESET(2).

If you were about to print on row 4 and wanted to skip to row  5,  you
could issue the following command:

     LET SYSPCROW(2) 4.

The system function $SYSPCPOS(n) returns the ASCII  representation  of
the  cell  to  which SYSPCROW(n) and SYSPCCOL(n) currently point.  For
example, if SYSPROW(2) is 3 and SYSPCCOL(2) is 5, the command

     PRINT $SYSPCPOS(2)

will return the value F4.

The following examples illustrate more fully the  ways  in  which  the
system  variables  SYSPCROW,  SYSPCCOL,  and  SYSPCRESET work.  In the
first example, the command file GPHRS3.DMC uses  values  for  SYSPCROW
and  SYSPCCOL  instead  of  X,  /,  and  $ formats to produce the same
columnwise  output  as  the  GPHRS1.DMC  described  above  in  section
6.3.2.2.2.1.    The   second  example  uses  SYSPCROW,  SYSPCCOL,  and
SYSPCRESET to produce  the  same  rowwise  output  as  the  GPHRS2.DMC
described in that section.

                                                               Page 34


                              GPHRS3.DMC

      !GPHRS3.DMC reads the names, student ID's, and grade point
      !averages of the student workers and calculates the total
      !number of hours that each has worked to date. This
      !information, which is drawn from the data sets WRKRS.DMS
      !and STDNTS.DMS, is then written columnwise to a worksheet
      !file, GPHRS3.WKS.

OPEN WRKRS STDNTS.
DBSET WRKRS.
FIND ALL.
SORT LN.
INIT 123  2 GPHRS3.WKS.          !SYSPCCOL, SYSPCROW, SYSPCRESET all = 0.
LET SYSPCCOL(2) 2.               !Reset SYSPCCOL; go to C1 to start printing.
PRINT ON 2 SYSDATE FMT L8  END.  !END resets SYSPCCOL to 0, adds 1 to SYSPCROW.
LET SYSPCROW(2) 3.                    !Go to A4 to print some more.
PRINT ON 2 "Last name" "First name" - !The END of this command will put
 "Student ID" "GPA" "Total Hours" -   !us at A5 by automatically resetting
 FMT 5L  END.                         !SYSPCCOL to 0 and adding 1 to SYSPCROW.
LET SYSPCROW(2) 5.                 !Go to A6 to print some more.
PL START.
REPEAT
GETREC LEAVE.
PRINT ON 2 LN FN ID FMT 3L END.    !END automatically sends us to next  row.
LET SYSPCROW(2) SYSPCROW(2)-1.     !Put us back on row we were just on.
LET SYSPCCOL(2) 3.                 !Get ready to print at column 4.
MAP TO STDNTS VIA ID.
SORT LN.
GETREC LEAVE.                      !Get corresponding record from other d/s.
PRINT ON 2 GPA FMT  L1  END.       !Print GPA. END puts us on next row.
DBSET WRKRS.                       !Go back to first data set.
LET SYSPCROW(2) SYSPCROW(2)-1.     !Put us back on row we were just on.
LET SYSPCCOL(2) 4.                 !Get ready to print at column 5.
PRINT ON 2 MTOT+TOTH FMT L1 END.   !Print value and go to next row.
UNTIL 1 EQ 2.                      !Or we run out of records.
PL END.
RELEASE 2.


When GPHRS3.WKS is loaded into Lotus 1-2-3 and the column  widths  are
adjusted, it looks like this:

                                                               Page 35


A1:                                                                 READY

        A          B           C         D         E         F     G
1                            12-Dec-85
2
3
4    First name   Last name  Student ID  GPA      Total Hours
5
6    AKHMAJIAN    ARAM           22446      3.25     460.00
7    ARMONICO     LESTRO         21502      3.50     560.00
8    ARNOLDS      SARAH          22034      3.50     371.00
9    BARLOW       ELIZABETH      22330      3.75     400.00
10   GINGOLD      SETH           22296      3.00      80.00
11   JONES        ALBA           22441      3.00     263.00
12   LENK         MARGARET       22223      3.00     320.00
13   MCMAHON      JEAN           22929      4.00     295.50
14   NICHOLS      JOSHUA         22004      3.25     230.00
15


                              GPHRS4.DMC

     !GPHRS4.DMC reads the names, student ID's, and grade point
     !averages of the student workers and calculates the total
     !number of hours that each has worked to date. This
     !information, which is drawn from the data sets WRKRS.DMS
     !and STDNTS.DMS, is then written rowwise to a worksheet
     !file, GPHRS4.WKS.

OPEN WRKRS STDNTS.
DBSET WRKRS.
FIND ALL.
SORT LN.
INIT 123 RWISE 2 GPHRS4.WKS.       !SYSPCCOL, SYSPCROW, SYSPCRESET all = 0.
LET SYSPCCOL(2) 3.                 !Get ready to print at D1.
PRINT ON 2 SYSDATE FMT L8 END.     !END sends us to next column (E1).
LET SYSPCCOL(2) 0.                 !Put us at column 1.
LET SYSPCRESET(2) 2.               !Start each new PRINT at row 3.
LET SYSPCROW(2) 2.                 !Start the next PRINT at row 3.
PRINT ON 2 "Last name" "First name" -  !END of this command will put us
  "Student ID" "GPA" "Total Hours" -   !at row 3 (because we reset SYSPCRESET)
  FMT 5L END.                          !of the next column.
LET SYSPCCOL(2) 2.                !Get ready to print at column 3.
PL START.
REPEAT
GETREC LEAVE.                      
PRINT ON 2 LN FN ID FMT 3L END.   !END puts us at row 3 of next column.
MAP TO STDNTS VIA ID.              
LET SYSPCCOL(2) SYSPCCOL(2)-1.    !Put us back on the column we were just on.
LET SYSPCROW(2) 5.                !Get ready to print at row 6.
SORT LN.
GETREC LEAVE.
PRINT ON 2 GPA FMT L1 END.        !END puts us at row 3 of next column.
LET SYSPCCOL(2) SYSPCCOL(2)-1.    !Put us back on the column we were just on.
LET SYSPCROW(2) 6.                !Get ready to print at row 7.
                                                               Page 36


DBSET WRKRS.
PRINT ON 2 MTOT+TOTH FMT L1 END.
UNTIL 1 EQ 2.                     !Or until we run out of records.
PRINT $SYSPCPOS(2).               !Let's see where the next PRINT would start.
PL END.
RELEASE 2.


When GPHRS4.WKS is loaded into Lotus 1-2-3 and the column  widths  are
adjusted, it looks like this:

A1:                                                                 READY

        A         B         C         D         E         F        G
1                                              12-Dec-85
2
3
4    Last name            AKHMAJIAN  ARMONICO   ARNOLDS    BARLOW     GINGOLD   
5    First name           ARAM        LESTRO    SARAH      ELIZABETH  SETH     
6    Student ID               22446       21502     22034       22330    22296  
7    GPA                       3.25        3.50      3.50        3.75     3.00
8    Total Hours             460.00      560.00    371.00      400.00    80.00
9
10
11
12
13
14
15




6.4  Error Handling

Several new error messages have been added to 1022 to  help  the  user
pinpoint  any  problems encountered by the system in the creation of a
DIF or WKS file.

CS210  ILLEGAL DEVICE IN PC INIT
       INIT 123 and INIT DIF require output to a file.  Output to  the
       terminal is not allowed.

CS211  ILLEGAL COL DESCRIPTOR
       The column descriptors in COL and NRANGE clauses  of  the  INIT
       123  and  INIT DIF command must be alphabetic strings.  For 123
       files, these strings must be within the range  of  A  to  CRXP.
       For  DIF  files, these strings must be within the range of A to
       NWTL.

CS212  ILLEGAL ROW DESCRIPTOR
       The row descriptors in ROW and NRANGE clauses of the  INIT  123
       and  INIT  DIF  commands  must  be  positive integers.  For 123
       files, these integers must be between 1 and  2^16-1.   For  DIF
       files, these integers must be between 1 and 2^18-1.
                                                               Page 37


CS214  ILLEGAL NCOLS ARGUMENT
       The NCOLS keyword in an INIT DIF command  requires  a  positive
       integer argument.  This integer must be between 1 and 2^18-1.

MI29   ILLEGAL PRINT CHANNEL NUMBER
       The subscript for SYSPCCOL, SYSPCROW, SYSPCRESET,  and  SYSPAGE
       must  be  an integer between 1 and 8.  All other subscripts are
       out of range.

MI30   ATTEMPT TO WRITE ILLEGAL VALUE TO SYSPC FUNCTION
       SYSPCCOL, SYSPCROW, and SYSPCRESET require a  positive  integer
       as their argument.  This integer must be between 0 and 2^16-1.

MI31   ILLEGAL ATTEMPT TO READ SYSPC FUNCTION
       The subscript for SYSPCCOL, SYSPCROW, SYSPCRESET, and $SYSPCPOS
       must  be  the  same  as  the  channel  number  specified in the
       preceding INIT 123 or INIT DIF command.  You can read the value
       of  SYSPCCOL,  SYSPCROW,  SYSPCRESET,  or $SYSPCPOS only if the
       keyword 123 or DIF has been given in the preceding INIT command
       and  the subscript matches the channel number specified in that
       INIT command.

MI32   ILLEGAL ATTEMPT TO WRITE SYSPC FUNCTION
       The subscript for SYSPCCOL, SYSPCROW, and  SYSPCRESET  must  be
       the  same as the channel number specified in the preceding INIT
       123 command.  You can assign a value to SYSPCCOL, SYSPCROW,  or
       SYSPCRESET  only  if  the  keyword  123  has  been given in the
       preceding INIT command and the subscript  matches  the  channel
       number specified in that INIT command.

FO27   ILLEGAL PAGE-ORIENTED COMMAND ON PC PRINT CHANNEL
       The HEADING, FOOTING, BODY, PAGE,  and  TYPAGE  page-formatting
       commands  are  not allowed in PRINT commands that direct output
       to a channel specified in a preceding  INIT  123  or  INIT  DIF
       command.

FO28   ILLEGAL DIF FILE FORMAT
       System 1022 does not support $ format in  PRINT  commands  that
       direct  output  to  a channel specified in a preceding INIT DIF
       command.

FO29   ILLEGAL PC FILE FORMAT
       System 1022 does not support $3, $4, S,  T,  or  C  formats  in
       PRINT  commands  that direct output to a channel specified in a
       preceding INIT 123 or INIT DIF command.

FO30   "L" FORMAT ILLEGAL ON NON-123 PRINT CHANNEL
       System 1022 supports "L" format only  in  PRINT  commands  that
       direct  output  to  a channel specified in a preceding INIT 123
       command.

FO31   SYSPC COUNTER OVERFLOW ON EOL
       In printing to a 123 columnwise file, the value of SYSPCROW has
       exceeded  the  allowed limit of 2^16-1 or, in printing to a 123
       rowwise file, the value of SYSPCCOL has exceeded that value.
                                                               Page 38


FO32   SYSPC COUNTER OVERFLOW ON EOI
       In printing to a 123 columnwise file, the value of SYSPCCOL has
       exceeded  the  allowed limit of 2^16-1 or, in printing to a 123
       rowwise file, the value of SYSPCROW has exceeded that value.

FO33   SYSPCROW COUNTER OVERFLOW IN DIF FILE
       In printing to a DIF file, the value of SYSPCROW  has  exceeded
       the allowed limit of 2^18-1.

FO34   SYSPCCOL COUNTER OVERFLOW IN DIF FILE
       In printing to a DIF file, the value of SYSPCCOL  has  exceeded
       the allowed limit of 2^18-1.



7.0  WILDCARD MATCHING WITH FIND AND SEARCH

7.1  Overview

Version 117B introduces six wildcard characters that may  be  used  in
FIND,  DFIND,  SEARCH,  SELECT,  DBFIND, DBSRCH, and DBSEL commands to
locate records based on some portion of the value of a text attribute.
Wildcard  selection  expressions  consist  of  a  quoted  text  string
containing one or more wildcard  characters  and  are  used  with  the
relational  operators  MATCHES  and  NMATCHES.   The  operator MATCHES
creates a selection set of all the records whose values agree with the
wildcard  expression  that you specify.  The operator NMATCHES selects
all the records whose  values  do  not  meet  the  conditions  of  the
wildcard expression.

For example, the following command finds all the records with a  value
of MCDONALD or MACDONALD for the attribute SORT_NAME:

     FIND SORT_NAME MATCHES "M*DONALD@"

A user might issue the  following  command  to  isolate  all  obsolete
telephone numbers that are not in the standard form of three digits, a
dash, and then four digits:

     FIND PHONE NMATCHES "###-####"

MATCHES and NMATCHES may be abbreviated MAT and NMAT, respectively.

The following table lists the System 1022 wildcards and the characters
that they match.


                                                               Page 39


        Wildcard        What It Matches        ________        ____ __ _______

        *       Any number of characters or spaces,
                including no characters or spaces

        @       Any number of spaces or tab characters,
                including no spaces or tab characters

        %       Any single character or space

        &       Any single alphanumeric character

        $       Any single alphabetic character

        #       Any single numeric character


You can specify any of the 1022 wildcards in  a  selection  expression
with  MATCHES  or NMATCHES.  Like the other 1022 relational operators,
MATCHES and NMATCHES are case-sensitive when SYSCASE is 0.  And,  like
CONTAINS,  NCONTAINS, BEGINS, and NBEGINS, they ignore the distinction
between upper and lower case when SYSCASE is set to 1.  To  constitute
a  match, each character of the attribute value, including any spaces,                                                 _________ ___ ______
must correspond to a text character or the appropriate wildcard in the
corresponding   position   in  the  selection  expression.   Thus,  if
SORT_NAME is an attribute of length 15, the command

     FIND SORT_NAME MATCHES "M*CDONALD"

will find no  matches  because  1022  would  pad  the  "MCDONALD"  and
"MACDONALD"  values  for SORT_NAME out to fifteen characters each with
spaces.  To find the desired match,  the  selection  expression  would
have to end in a wildcard to account for these spaces:

     FIND SORT_NAME MATCHES "M*CDONALD@"
                  or
     FIND SORT_NAME MATCHES "M*CDONALD*"



7.2  Examples


    *    The  asterisk  wildcard  (*)  matches  any  number  of   text
         characters or spaces, including no character or space.  Thus,

              FIND SORT_NAME MATCHES "M*CDONALD*"

         matches   the   values   "MCDONALD   [ trailing    spaces ],"
         "MCDONALD'S  [  trailing  spaces  ],"  "MACDONALD  [ trailing
         spaces ]," and "MACDONALD'S [ trailing spaces ]," and so on.

    @    The at-sign wildcard (@) matches any number of spaces or  tab
         characters, including no space or tab.  Thus,
                                                               Page 40


              FIND SORT_NAME MATCHES "DI@ANGELIS@"

         matches the values "DIANGELIS [ trailing  spaces ]"  and  "DI
         ANGELIS [ trailing spaces ]."

    %    The  percent-sign  wildcard  (%)  matches  any  single   text
         character or space.  Thus,

              FIND SORT_NAME MATCHES "A%B*"

         matches "A&B PIZZA [ trailing spaces ],"  "A  B  C  MOVERS  [
         trailing spaces ]," and "ALBANO [ trailing spaces ]."

    &    The ampersand wildcard (&) matches  any  single  alphanumeric
         character (A-Z, 0-9, a-z).  Thus,

              FIND ZIP_CODE NMATCHES "&&&@&&&@"

         might be used to check for errors in a  data  set  containing
         Canadian zip codes (such as H3A 3C7 and H3C3H5), trapping all
         entries with non-alphanumeric characters.

    $    The dollar-sign wildcard ($) matches  any  single  alphabetic
         character  (A-Z, a-z).  The following command isolates all US
         zip codes (such as  02144  and  02144-6102)  in  a  data  set
         containing  both  numeric and hyphenated numeric US zip codes
         and Canadian alphanumeric zip codes:

              FIND ZIP_CODE NMATCHES "*$*"

    #    The  pound-sign  wildcard  (#)  matches  any  single  numeric
         character  (0-9).   The  following  command  might be used to
         check for errors in a data set  containing  only  non-numeric
         data:

              FIND SORT_NAME MATCHES "*#*"



7.3  Comments

For greatest efficiency  in  dealing  with  large  data  sets,  it  is
advisable  to  create  a  selection  set with a FIND CONTAINS command,
which may then be narrowed with a SEARCH MATCHES command.

Users are reminded to take account of trailing blanks when wildcarding
with MATCHES or NMATCHES.

In host language programs, users may wish to substitute numeric  codes
for  the operators MATCHES and NMATCHES.  The numeric codes are 13 and
14, respectively.
                                                               Page 41


8.0  RECORD-LEVEL LOCKING

   The  new  locking  commands  give  you  more   flexible   control   of
   simultaneous  access  to  a data set.  You can now lock single records
   with record-level locking.  And you can define your own locks with the
   1022 userlock.

   The record-level locking commands control access to individual records
   when you are in single record (GETREC) mode.  They prevent other users
   from getting update access to your current record while  you  have  it
   locked.

   The principal benefit of record-level locking  is  that  it  restricts
   access  for  only  one  record  at  a  time.   This  reduces long-term
   contention among users  of  the  same  data  set  or  among  users  of
   different  data  sets  in  the same file.  UPDATE locks the whole file
   that contains the data set.  Record-level locking guarantees  that  no
   other  users  can change your current record while you have it locked.
   Also, if you give a CHANGE, DELETE, or UNDELETE command for the record
   you have locked, 1022 issues an implicit UPDATE ON and UPDATE OFF.

   The new userlock features create a user-defined lock that  coordinates
   access  to  the  data set among cooperating users.  You can coordinate
   access using your own criteria and without simply locking other  users
   out of the data set.



   8.1  Record-level Locking

   The record-level locking commands are the LOCK command and the similar
   $LOCK  clause  of  the GETREC command.  Both are used in single record
   mode, and both ensure that no other  users  can  update  your  current
   record.  Other users may have full access, including update access, to
   the other records in the data set.  They may 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.  For example:

   *FIND ALL 
   97 RECS FOUND. 
   *GETREC $LOCK 
   *... 
   *GETREC $LOCK 

   or 
    

   *FIND ALL 
   97 RECS FOUND. 
   *GETREC 
   *LOCK ON RECORD 
   *... 
   *LOCK OFF RECORD 

   These commands are especially useful in ensuring that  a  record  does
                                                                  Page 42


   not  change after you select it and before you update it, print it, or
   use it in other operations.  And these commands lock only  one  record
   at  a  time  so that most of the data set is still available for other
   users.

   For efficiency reasons, the GETREC $LOCK command is always  preferable
   to  the  LOCK  ON  RECORD  command.  See "Locking Records with LOCK ON
   RECORD" below.



   8.1.1  Enabling Record-level Locking For A Data Set

   To use record-level locking, a data set must be  an  ENQ  and  RECLOCK
   data set.  You can include these keywords in the description file when
   you create the data set, or you can use the MODIFY command to make the
   data  set  ENQ and RECLOCK.  A MODIFY $ACCESS ENQ or NOENQ changes the
   ENQ status of the data set the next time the data set is opened.   But
   MODIFY  $ACCESS RECLOCK or NORECLOCK changes the RECLOCK status of the
   data set immediately.  A data set must be an ENQ data set  before  you
   can  make it a RECLOCK data set.  An OPEN ENQ command for the data set
   is not sufficient to make a NOENQ data set work with RECLOCK.  See ENQ
   in  the  1022  User's  Reference Manual for information about ENQ data            ____  ______  _________ ______
   sets.  Most users will create ENQ data sets and use MODIFY to turn  on
   and off RECLOCK.

   A RECLOCK data set has the following characteristics:


         o  It allows record-level locking.

         o  It does not allow global updates using  the  CHANGE,  DELETE,
            UNDELETE, or TRANSACT commands.

         o  It requires that a record be locked to do single record  mode
            updates with CHANGE, DELETE, or UNDELETE commands.


   A NORECLOCK data set does not  allow  record-level  locking  and  does
   allow global updates.

   In many cases you will want to create RECLOCK data sets and ordinarily
   use them for changes in single record mode.  Then for occasional batch
   jobs that make global updates to  the  data  set,  you  can  turn  off
   record-level  locking with a MODIFY $ACCESS NORECLOCK command.  At the
   end of the procedure, you can restore the data  set  to  its  ordinary
   condition with a MODIFY $ACCESS RECLOCK command.

   You must have exclusive access to the data  set  to  give  the  MODIFY
   $ACCESS  RECLOCK or NORECLOCK commands.  You cannot have the UPDATE ON
   command in effect when you give these MODIFY commands.

   The addition to the MODIFY command adds the following syntax:

   MODIFY { $ACCESS {NORECLOCK} }    ___      ____
                                                                  Page 43


          {         { RECLOCK } } 

   ENQ must be enabled for the data set before  you  can  enable  RECLOCK
   with  MODIFY.   You  can tell if a data set is RECLOCK with the INFORM
   STRUCTURE command or by printing the system variable SYSRECLOCK.  When
   SYSRECLOCK  is  0,  the  data  set  is  not  a RECLOCK data set.  When
   SYSRECLOCK is 1, the data set is RECLOCK.



   8.1.2  Locking Records With GETREC $LOCK

   You lock a record with the GETREC $LOCK command or the LOCK ON  RECORD
   command.   Though  their effects are similar, the GETREC $LOCK command
   is more efficient and is recommended for most cases.   Record  locking
   with  the  GETREC  command  locks  the  record at the time you get the
   record.  The format for the command is:

   GETREC [ { LEAVE } ] [$LOCK] [<expression>] 
          [ { label } ]

   The sequence of options is significant.  LEAVE or a label is  optional
   but,  if  used, must be given first.  Similarly, the $LOCK option must
   be next.  The expression that evaluates to a record number must be the
   last.

   When you give the GETREC $LOCK command, you can perform any operations
   on  the  record.   Other users can query the record but not update it.
   Other users who attempt to  update  a  record  that  you  have  locked
   receive an error message.  Other users who request a lock for the same
   record will have their request placed in  a  monitor  ENQ  queue.   If
   their  request  is  not  granted  in  SYSTENQ (or SYSNRETRY*SYSTRETRY)
   milliseconds, they are given a  timeout  error.   If  you  unlock  the
   record  while  they  are  waiting in the ENQ queue, their request will
   succeed.  See ENQ  in  the  1022  User's  Reference  Manual  for  more                               ____  ______  _________  ______
   information.   The  record  remains  locked  until  you  unlock  it by
   performing one of the following actions:


         o  Closing the data set

         o  Returning to global mode (with the  STARTREC  command  or  by
            forming a new selection set)

         o  Dropping the record from the selection  set  with  the  DROP,
            DELETE, or UNDELETE command

         o  Getting another record with a GETREC command

         o  Explicitly unlocking  the  record  with  a  LOCK  OFF  RECORD
            command


   Using GETREC  $LOCK  prevents  attribute  values  from  being  changed
   between  the time you get and lock the record.  This is different from
                                                                  Page 44


   using LOCK ON RECORD  (see  below).   However,  attribute  values  can
   change  between  the  time you form the selection set and the time you
   get and lock an individual record.  To make sure the original value is
   the  current value, you can use PL1022 code like that in the following
   example:

   LET SYSIFTYPE 1. 
   FIND AGE LT 40. 
   WHILE 0 EQ 0 DO 
      GETREC LEAVE $LOCK. 
      IF AGE LT 40 THEN 
         ;original value is still current value, so
         ;perform operations on record 
       ELSE
         ;original value of AGE has changed, so
         DROP. 
      ENDIF. 
   ENDWHILE. 




   8.1.3  Locking Records With LOCK ON RECORD

   The new LOCK command creates userlocks on the data set (see below)  or
   locks on individual records much like GETREC $LOCK.  The format of the
   command is:

              { RECORD          }                 ___
        { ON  { USERLOCK string }     }                ____
   LOCK {                             }
        { OFF { RECORD              } }                 ___
              { USERLOCK { string } }                ____
                         { ALL    } 

   LOCK ON RECORD differs from GETREC $LOCK in that it is less efficient,
   requiring  that  a  record be read one extra time, and in that it does
   not ensure that a record is unchanged between the  time  you  get  the
   record  and  lock  it.   After you give the GETREC command selecting a
   record in local mode,  another  user  could  change  attribute  values
   before  the  LOCK ON RECORD command locks the record.  You can use the
   system variable  SYSCHANGED  to  test  the  record  for  changes.   If
   SYSCHANGED  is 0, the record has not changed since the GETREC command;
   if SYSCHANGED is 1, the record has  changed.   The  procedure  in  the
   following example shows such testing:

   LET SYSIFTYPE 1. 
   FIND AGE LT 40. 
   WHILE 0 EQ 0 DO 
      GETREC. 
         PRINT AGE.
      LOCK ON RECORD. 
      IF SYSCHANGED EQ O THEN 
            ;perform operations on record 
       ELSE 
                                                                  Page 45


         PRINT AGE.
            ;perform operations on record or drop
      ENDIF. 
   ENDWHILE. 

   The IF statement tests for any change between the GETREC and the  LOCK
   ON  command.   It  does  not test for changes made between the initial
   FIND and the GETREC command.  To check for those changes, you need  to
   also test as in the GETREC $LOCK example above.

   You can unlock the record implicitly, as with GETREC $LOCK, by forming
   a  new selection set, dropping the record from the selection set (with
   the DROP, DELETE, or UNDELETE commands), or getting the  next  record.
   Or you can unlock the record with an explicit LOCK OFF RECORD command.



   8.2  User-defined Locks On A Data Set

   The user-defined lock,  created  with  a  LOCK  ON  USERLOCK  command,
   coordinates  access  to a data set among users.  The userlock does not
   actually restrict access to the data set.  Instead it  allows  you  to
   define a lock that users agree to request before performing a specific
   1022 operation on data.  You can define a lock that  only  applies  to
   the  parts  of  a  data  set  you need.  For example, you can restrict
   access to a specific attribute while allowing  users  free  access  to
   other data in the data set.

   To define userlocks for a data set, the data set must be an  ENQ  data
   set  (created ENQ or modified ENQ) or opened as ENQ.  It does not need
   to be a RECLOCK data set.  See ENQ in the 1022 User's Reference Manual                                             ____ ______ _________ ______
   for information about ENQ data sets.

   When you give the LOCK ON USERLOCK command, the "lock" you specify  is
   associated  by  your convention with the particular operation you want
   to lock.  The "lock" is a quoted string of up to 25  characters;   all
   printable  characters except spaces are allowed.  Users agree to check
   for a lock before performing the controlled operation.   The  LOCK  ON
   USERLOCK  command  is  your  request for access.  You specify the lock
   associated with the operation.  If your  request  succeeds,  you  have
   permission  to  perform the operation.  If it fails, wait until later,
   try the same LOCK command again, and if it succeeds, proceed with  the
   operation.   The  following example demonstrates the LOCK command with
   the USERLOCK option:

   *LOCK ON USERLOCK "FRANCE_RECS" 

   1022 displays an error message if your request is not successful.   If
   another  user  already  has  this  userlock  on, your request will not
   succeed.  If no message displays, then you have permission to  proceed
   with the operation.

   Userlocks are most useful when a  data  set  is  changed  or  accessed
   exclusively  through  programs.   Although  interactive  users can use
   userlocks, they must remember to request the locks  before  performing
                                                                  Page 46


   the controlled operations.

   If a program succeeds in getting a userlock, it can access  the  data.
   But  if  a program fails in getting the userlock, it should not access
   the data.  When a LOCK command fails in a  program,  1022  returns  an
   error  message.   Remember  that a userlock does not actually lock the
   data set.  Its usefulness depends on coordinated requests.

   Consider  the  following  example:   One  program,  MAPDIR,  uses  the
   DIRECTOR_ID  attribute  to  map  from  FILMS  to  DIRECT,  and another
   program, CHANGEDID, changes the value of the DIRECTOR_ID attribute  in
   these  data  sets.   You  can  define  a userlock "DID_ATTR" that both
   programs must request.  If a user is running  MAPDIR,  then  no  other
   user  can  run CHANGEDID.  And if a user is running CHANGEDID, then no
   other user can run MAPDIR until CHANGEDID finishes.  Any other program
   that  does  not  use  the  DIRECTOR_ID  attribute can change any other
   attribute without interfering with these programs.

   A second example shows the use of userlocks to avoid a  deadly-embrace
   situation.   An example of a deadly-embrace situation is when John has
   record A and Mary has record B.  Without releasing these records, John
   requests  B  and  Mary  requests A.  Neither is willing to give up the
   first record to the other user, so neither user can proceed.

   In the following example of a funds-transfer procedure, userlocks  are
   used  to  avoid  a  deadly-embrace  situation.  To transfer money from
   account A to account B, the ACCOUNTS data set is  opened  twice,  with
   aliases  ACCT1  and  ACCT2.  A different record is found in each.  The
   procedure uses a LOCK ON USERLOCK command to lock the data  set  while
   it locks the two records with GETREC $LOCK commands.

   Other  users  could  lock  other  single  records  without  causing  a
   deadly-embrace  situation.  By the userlock convention established for
   this procedure, no one would lock multiple records without  using  the
   userlock.  The userlock is turned off after the individual records are
   locked.  And the individual records  are  unlocked  with  a  LOCK  OFF
   RECORD if no transfer is made due to insufficient funds.

                                                                  Page 47


                     . . .  
                     OPEN ACCOUNTS AS ACCT1 ACCOUNTS AS ACCT2.  
                     . . .  
                     DBSET ACCT1.  
                     FIND ACCOUNT_NUMBER EQ ACCT_FROM.
                     IF SYSNREC NE 1 THEN
                        ;0 or more than one source accounts
                        PRINT "Source acct #" ACCT_FROM
                           "not found...transfer aborted".
                            GOTO NTFND.
                       ENDIF.
                     DBSET ACCT2.
                     FIND ACCOUNT_NUMBER EQ ACCT_TO.
                     IF SYSNREC NE 1 THEN
                        ;0 or more than one destination accounts
                        PRINT "Destination acct #" ACCT_TO
                           "not found...transfer aborted".
                           GOTO NTFND.
                       ENDIF.
                     LOCK ON USERLOCK "FUNDS-TRANSFER".
                     GETREC $LOCK.
                     DBSET ACCT1.
                     GETREC $LOCK.
                     LOCK OFF USERLOCK "FUNDS-TRANSFER".
                     LET NEWBAL EQ (BALANCE - TRANSFER_AMOUNT).
                     IF NEWBAL LT 0 THEN
                        PRINT "Transfer will overdraw acct #" ACCT_FROM
                           "...transfer aborted".
                           GOTO NOXFER.
                       ENDIF.
                     CHANGE BALANCE NEWBAL.
                     DBSET ACCT2.
                     CHANGE BALANCE (BALANCE + TRANSFER_AMOUNT).
   NOXFER: DBSET ACCT2.
                     LOCK OFF RECORD.
                     DBSET ACCT1.
                     LOCK OFF RECORD.
   NTFND:            . . . 

   A userlock stays on until you turn it off with LOCK  OFF  USERLOCK  or
   close  the  data  set.   You can either turn off a single userlock, by
   specifying a particular "lock," or you can turn off all the  userlocks
   in a data set, by using the ALL clause.  For example:

   *LOCK OFF USERLOCK "FRANCE_RECS" 

   or 

   *LOCK OFF USERLOCK ALL 

                                                                  Page 48


   8.2.1  Userlocks With Collections

   If you turn on a userlock while set  to  a  collection,  the  lock  is
   applied  to  all of the data sets in the collection.  The lock remains
   on for each data set even after a CLEAR  COLLECT  command.   You  must
   explicitly  turn  off  the userlock or turn it off by closing the data
   set.

   However, there is one exception.  When a data set is opened more  than
   once  in  a collection and a userlock is turned on for the collection,
   only the first opening of the data set will still have the userlock on
   after a CLEAR COLLECT command.

   While in a collection, a LOCK OFF USERLOCK ALL command unlocks all the
   userlocks  on  all  the  data sets in the collection.  Even a userlock
   turned on for a data set before the collection  was  formed  with  the
   COLLECT command will be turned off by LOCK OFF USERLOCK ALL.



   8.3  Host Language Calls For Record Level And User-defined Locking

   The host language calls equivalent to the interactive  GETREC  command
   also  include  the  new $LOCK clause.  And new host language calls are
   equivalent to the interactive  LOCK  command,  for  both  record-level
   locking and user-defined locking.



   8.3.1  FORTRAN

   8.3.1.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
                                                                  Page 49


   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.

|  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.
|  
|  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.



   8.4  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.
                                                                  Page 50


   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.

   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,
                                                                  Page 51


                            in ASCII.
            IAR(6) - IAR(7) Contain D, right justified and blank  filled,
                            in ASCII.

            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.



   8.4.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.
                                                                  Page 52


        string         Is a text string of up to 25 characters naming the
                       userlock.  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:

        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.
                                                                  Page 53


   8.4.1  COBOL

   8.4.1.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.

   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.
                                                                  Page 54


   8.5  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.



   8.5.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" } 

   where:
                                                                  Page 55


        "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.
                                                                  Page 56


   8.6  Locking Error Messages

   System 1022 includes the following new error messages for locking:

   CS215  KEYWORD ALL NOT ALLOWED WITH LOCK ON USERLOCK
          The LOCK ON USERLOCK command requires a  string  of  up  to  25
          characters  as its argument.  ALL is not allowed as an argument
          for the LOCK ON USERLOCK command.

   OP18   OPEN NOENQ NOT ALLOWED FOR RECLOCK DATASET
          A RECLOCK data set cannot be opened NOENQ unless you first open
          the  data set and issue the MODIFY $ACCESS NORECLOCK command to
          disable record-level locking for the data set.

   UP7    DATASET MUST BE ENQ TO DO LOCK
          To put a userlock  on  a  string  with  the  LOCK  ON  USERLOCK
          command,  the  data  set  containing that record must be opened
          ENQ.  In order to lock an individual  record  with  the  GETREC
          $LOCK  or LOCK ON RECORD command, the data set must be both ENQ
          and RECLOCK.

   UP8    RECORD WAS NOT PREVIOUSLY LOCKED
          The user either tried to change, delete, or undelete a  RECLOCK
          data  set  record  without  first  locking  the record with the
          GETREC $LOCK or LOCK ON RECORD command or else  issued  a  LOCK
          OFF RECORD command on a record that was not currently locked.

   UP9    USERLOCK STRING WAS NOT PREVIOUSLY LOCKED
          The user issued a LOCK OFF USERLOCK command on  a  string  that
          was not currently locked.

   UP10   CANNOT LOCK RECORD
          You have tried to lock a record that another user currently has
          locked.

   UP11   CANNOT LOCK USERLOCK STRING
          You have timed out of the queue while trying to lock  a  string
          on which some other user currently has a lock.

   UP12   USERLOCK STRING ALREADY LOCKED
          You have issued a LOCK ON USERLOCK command on a string on which
          you already have a lock.

   UP13   CANNOT LOCK ON/OFF RECORD WHILE IN GLOBAL MODE
          You must be in local (GETREC) mode to execute a LOCK ON  RECORD
          or LOCK OFF RECORD command.

   UP14   DATASET MUST BE NORECLOCK TO MODIFY ACCESS TO NOENQ
          If a data set is RECLOCK, it is also  by  definition  ENQ.   To
          make  a  data set NOENQ, you must first make certain that it is
          NORECLOCK.

   UP15   DATASET MUST BE ENQ TO MODIFY ACCESS TO RECLOCK
          Only ENQ data sets can be RECLOCK.
                                                                  Page 57


   UP16   MODIFY FAILED BECAUSE OTHER USERS ARE ACCESSING THE FILE
          You need exclusive update access to the data set to  execute  a
          MODIFY $ACCESS RECLOCK or MODIFY $ACCESS NORECLOCK command.

   UP17   ILLEGAL WHEN DATASET IS NORECLOCK
          The data set must be RECLOCK before you can lock a record  with
          the GETREC $LOCK or LOCK ON RECORD command.

   UP18   ILLEGAL WHEN DATASET IS RECLOCK
          Users cannot execute  CHANGE,  DELETE,  UNDELETE,  or  TRANSACT
          commands in global mode when the data set is RECLOCK.

   UP19   ILLEGAL WITH RECORD OR USERLOCK STRING LOCKED
          You cannot execute MODIFY $ACCESS RECLOCK/NORECLOCK commands if
          you  currently have a lock on a record or userlock string.  You
          should issue the appropriate LOCK OFF command before giving the
          MODIFY $ACCESS RECLOCK/NORECLOCK commands.



   9.0  PL1022 DEBUGGING TOOLS

   Version 117B introduces a special set of commands for use in debugging
   PL1022  programs.   These  commands  are similar to the ACCEPT, BREAK,
   CLEAR, NEXT, PROCEED, STOP,  TRACE  ON,  and  TRACE  OFF  commands  of
   COBDDT.   They  may be used to debug a PL1022 program that you will be
   entering interactively or have written to a file.

   To use these tools, enter the command PL DEBUG in place of  PL  START.
   At execution time, the debugging prompt will appear:

        1022DDT>

   You may then enter any of the following commands:

            HELP -- Displays a brief  summary  of  the  PL1022  debugging
            commands.

            BREAK <label> -- Sets a breakpoint at the specified label  in
            the  program.  There is no limit on the number of breakpoints
            that may be set in a series of BREAK commands.

            CLEAR <label> --  Clears  the  breakpoint  at  the  specified
            label.   If  no  label  is  specified,  all  breakpoints  are
            cleared.

            DISPLAY <item> -- Displays the contents of the specified user
            variable,  system  variable, or attribute of the current data
            set.  The PL1022 DISPLAY command does not accept wildcards or
            ranges as part of an argument.

            ACCEPT <item>  <RET>  <value>  --  Assigns  a  value  to  the
            specified user variable or system variable.
                                                                  Page 58


            PROCEED <n> -- Continues execution  of  the  program,  either
            until  completion,  until the nth occurrence of the preceding
            breakpoint is reached, or  until  some  other  breakpoint  is
            reached,  whichever happens first.  If no numeric argument is
            given, the default is 1.

            NEXT <n> -- Continues execution of the program, either  until
            completion,  until  the  next  n  labels have been passed, or
            until a breakpoint is reached, whichever happens  first.   If
            no numeric argument is given, the default is 1.

            TRACE ON -- Displays all labels as they are encountered.

            TRACE OFF -- Stops displaying labels as they are encountered.

            STOP -- Terminates execution of the  program,  returning  the
            user to the 1022 prompt.




   10.0  TOPS-20 FORTRAN VERSION 10 WITH EXTENDED SECTIONS

   System 1022 now supports the use  of  extended  addressing  mode  with
   TOPS-20  FORTRAN  version  10.  FORTRAN-10 applications using extended
   sections must be loaded with HR1022.  System 1022 reserves sections  0
   and 36 for its own use.

   If your FORTRAN-10 application makes use of extended addressing  mode,
   you initialize 1022 with the call

        CALL DBFX



   11.0  EXPANDED INFORM COMMAND

   A new DMX option has  been  added  to  the  INFORM  command,  and  the
   STRUCTURE,  ATTRIBUTE,  and  STATUS options of the INFORM command have
   all been expanded.



   11.1  INFORM DMX

   11.1.1  Overview

   The  INFORM  DMX  command  returns  information  about  the   run-time
   environment  that must exist for the execution of a precompiled PL1022
   or report program or for the recompilation of that  program  with  the
   COMPILE command.  The syntax is:

   INFORM [ON <file-descriptor-1>] DMX <file-descriptor-2>

   where <file-descriptor-2> is the name of the  precompiled  (DMX)  file
                                                                  Page 59


   about whose run-time environment you wish to know.  If no extension is
   specified, DMX is assumed.  If you specify the ON  <file-descriptor-1>
   clause,  the information is written to the named file.  Otherwise, the
   information is displayed at the terminal.

   The information returned  by  the  INFORM  DMX  command  includes  the
   following:

         *  The full name of the specified DMX file  (device,  directory,
            file name, extension);

         *  The numbers of the major and minor  versions  of  1022  under
            which the file was compiled;

         *  A warning that the version of System  1022  under  which  the
            file was compiled is incompatible with the present version if
            that is so;

         *  The full name of the source  file  (device,  directory,  file
            name, extension);

         *  A descriptive list (including data  type,  subscript  bounds,
            and  text length) of all user-defined variables referenced in
            the program;

         *  A descriptive list of all data sets,  collections,  and  join
            relations referenced explicitly or implicitly in the program.

             -  The information given for a referenced data set  includes
                the  internal  and external name, the alias (if any), the
                data set number, and the manner in which the data set  is
                referenced  by  the program (by internal name, file name,
                alias, or number).  If the data set must be  the  current
                data set at PERFORM or recompile time, this fact is noted
                as well.

             -  The  information  given  for  a   referenced   collection
                includes  the  collection  name  and  the  internal name,
                external name, the alias  (if  any),  and  the  data  set
                number of the collection's primary data set.

             -  The information given  for  a  referenced  join  relation
                includes  the  internal name or alias of each joined data
                set, the collection name of each joined  collection,  the
                attributes  by  which  the  data  sets  are  joined,  the
                specification UNI if the join is unilateral, and the name
                or  identifying number of the join relation.  If the join
                relation has been disabled, this fact is noted as well.


   If the DMX file has been damaged and contains any  structural  errors,
   the  INFORM DMX command returns the full name of the file and an error
   message.
                                                                  Page 60


   11.1.2  Example

   A university administration maintains two data  sets,  STDNTS.DMS  and
   WRKRS.DMS.   STDNTS  contains  the  grade point average (GPA) of every
   currently enrolled student.  WRKRS contains the job number (JOBNUM) of
   each   student   employed   by   the  university.   Periodically,  the
   administration writes information  from  these  two  data  sets  to  a
   spreadsheet  using  the  PL1022  program  STWKRS.DMX.   This  file was
   compiled  after  the  following  commands  had  been  given,   whether
   interactively or through the execution of a command file:

            OPEN STDNTS WRKRS

            JOIN STDNTS WRKRS VIA STUDENT_ID

                .

                .

                .

            DBSET WRKRS

            FIND ALL

            SORT LAST_NAME FIRST_NAME

            DEFINE I,J

            LET SYSIFTYPE 1

            INIT 123 2 STWKRS.WKS

   STWKRS.DMX is as follows:

            !This program produces a worksheet tallying the

            !number of student employees and identifying

            !those whose GPA has dropped below 3.0

            PL START.

            REPEAT

            GETREC LEAVE.

            LET I I+1.

            IF 1.GPA LT 3.0 THEN

            PRINT ON 2 LN FN ID 1.GPA JOBNUM.
                                                                  Page 61


            LET J J+1.

            ENDIF.

            UNTIL 1 EQ 2.

            PRINT ON 2 I J FMT "Total Workers " I / "Total Warnings  "  I
            END.

            PL END.

            RELEASE 2.

   If an INFORM DMX were issued for STWKRS under, say, version  117B(33),
   the following information might be returned:

   File:   PS:<ADMIN>STWKRS.DMX  Compiled  under  System  1022  116B(107)
   <SKEW>
   Source:  PS:<ADMIN>STWKRS.DMC

   Predefined variables:

   INTEGER I
   INTEGER J

   2 datasets or collections were referenced in the source code:

   Dataset WRKRS in WRKRS.DMS was d/s # 2
   Must be the current dataset
   Referenced by Dataset number, Internal name

   Dataset STDNTS in STDNTS.DMS was dataset # 1
   Referenced by Dataset number, Internal name

   Join STDNTS to WRKRS via STUDENT_ID to STUDENT_ID as 10000



   11.1.3  Comments

   In the example above, the <SKEW> message appears because  the  version
   of  1022  under which STWKRS was compiled is incompatible with the one
   under which the INFORM DMX command has been  given.   Recompiling  the
   file under the current version of 1022 eliminates this problem.

   The two variables (I and J) that the user defined at compile time  and
   that are referenced by the program are listed.  The fact that the user
   set the value of the system variable SYSIFTYPE to 1  at  compile  time
   (instead  of  leaving it set to 0, the default) is not revealed by the
   INFORM DMX command because system variable settings are not checked at
   perform time, though they are at compile time.

   WRKRS is identified as data set # 2, that is, as  the  second  of  the
   data  sets  opened at compile time.  The INFORM DMX command notes that
   WRKRS must be the current data set at  perform  time  because  it  was
                                                                  Page 62


   explicitly  made  so  with  a DBSET command at compile time.  WRKRS is
   referenced by the program twice,  both  times  implicitly.   WRKRS  is
   implicitly referenced by data set number at the PL START label.  It is
   also implicitly referenced by its internal name when the join relation
   to which it belongs is invoked in the PRINT command.

   STDNTS is identified as data set # 1, that is, as  the  first  of  the
   data  sets  opened at compile time.  STDNTS is referenced twice by the
   program, once explicitly and once implicitly.   STDNTS  is  explicitly
   referenced  by data set number in the PRINT command.  It is implicitly
   referenced by its internal name when the join  relation  to  which  it
   belongs is invoked.

   The join relation referenced by the program is described as well,  the
   number  10000  being the identifying number assigned by System 1022 to
   the join because no join name was specified by the user.



   11.2  INFORM STRUCTURE

   The INFORM STRUCTURE command  now  specifies  if  a  data  set  is  in
   pre-117A  format:  when an INFORM STRUCTURE command is executed on the
   data set, each keyed or keyed inactive attribute  in  a  pre-117A  DMD
   file appears with the comment

        !PRE-117

   In addition, if a data set has been restricted to ENQ  access,  either
   with  the  CREATE or MODIFY command, this information is revealed when
   an INFORM STRUCTURE command is executed on the data  set.   Similarly,
   if  the  data  set  is  further  restricted  to  RECLOCK  access, this
   information  is  provided  as  well  (see  Section  8.0  "Record-Level
   Locking").

   Further, INFORM STRUCTURE prints the names of all of a multifile  data
   set's  auxiliary files, together with the block or page limits (if any
   have been specified in the DMD file) for all but the  last  of  these.
   (As  noted earlier, System 1022 ignores user-specified block limits on
   the last auxiliary file listed in the DMD file.)  Where possible,  the
   limits  are  given in terms of pages rather than blocks.  In addition,
   if any  of  the  key  tables  are  stored  in  auxiliary  files,  this
   information is given.

   For example, consider a data set with this DMD file:

   LOADING SECTION
   ENQ
   RECLOCK
   SET MYFILE.DMS RECORDS 10000000
   AUXFILE AUX1.DMM RECORDS 60000000 BLOCKS 6000000
   AUXFILE AUX2.DMM BLOCKS 5000000
        .
        .
        .
                                                                  Page 63


   AUXFILE AUX6.DMM BLOCKS 5000000
   STRUCTURE SECTION
   ATTRIBUTE LAST_NAME ABBREV LN KEYED KEYFILE AUX2.DMM LENGTH 20
        .
        .
        .

   If an INFORM STRUCTURE command is given FOR this data set, the TOPS-10
   user receives the message:

   SET MYFILE.DMS RECORDS 10000000
   AUXFILE AUX1.DMM RECORDS 60000000 BLOCKS 6000000
   AUXFILE AUX2.DMM BLOCKS 5000000
        .
        .
        .
   AUXFILE AUX6.DMM
   ENQ
   RECLOCK
   ATTRIBUTE LAST_NAME ABBREV LN KEYED KEYFILE AUX2.DMM COL 1 20
        .
        .
        .

   The  TOPS-20  user  receives  a  similar  message  with  PAGES 1500000
   appearing  in  place  of BLOCKS 6000000, and PAGES 1250000 in place of
   BLOCKS 5000000.



   11.3  INFORM STRUCTURE TABLE

   The INFORM STRUCTURE TABLE command returns a variety of information in
   tabular form about the attributes of a data set.  The syntax is:

        INFORM [ ON <file-descriptor> ] STRUCTURE TABLE

   The informational table that this command returns  displays  the  name
   and  abbreviation  of  each  attribute  in the data set as well as its
   keyed status, its data type, the data mode in  which  its  values  are
   represented, its length and column fields, and its ERROR specification
   (if any).  In addition, if an attribute is one of  the  special  types
   (Date  of  Entry,  Date of Change, or Integer of Identification), this
   fact is displayed.  If such an attribute has been specified as  RESET,
   this information is also given.  Finally, if a computational attribute
   has been specified as ADDITIVE, this information appears in the table.

   For example, the following is the description file BLOOD.DMD:


   RECMODE ASCII DELIMIT ,
   ATTRIBUTE FIRST_NAME ABBREV FN TEXT COL 1 10
   ATTRIBUTE LAST_NAME ABBREV LN TEXT KEYED COL 11 25
   ATTRIBUTE AGE INTEGER KEYED RANGE 1 99 COL 26 27
   ATTRIBUTE BLOOD_GROUP ABBREV BG TEXT KEYED COL 28 29
                                                                  Page 64


   ATTRIBUTE RH_FACTOR ABBREV RH TEXT KEYED COL 30 30
   ATTRIBUTE SEX TEXT KEYED COL 31 31
   ATTRIBUTE COUNT INTEGER ADDITIVE ERROR TYPE COL 32 37
   ATTRIBUTE TEST_DATE ABBREV TD DATE OF ENTRY RESET COL 38 45


   The command INFORM STRUCTURE TABLE on  BLOOD  produces  the  following
   table:


   K Abbr  Name                      T SR M   Col   Len A E  Range
   =========================================================================
     FN    FIRST_NAME                T    7     1    10      
   * LN    LAST_NAME                 T    7    11    15      
   *       AGE                       I    B    26     2      1:99
   * BG    BLOOD_GROUP               T    7    28     2      
   * RH    RH_FACTOR                 T    7    30     1      
   *       SEX                       T    7    31     1      
           COUNT                     I    B    32     6 A T  
     TD    TEST_DATE                 D ER B    38     8      

    K       is keying: "*" = keyed, "=" = keyed-inactive.
                       (for keys before version 117, "+" = active, "-" = inactive)
    T    is data type: T = text, I = integer, R = real, D = date, I2 = dbl integer.
    S is special attr: E = date of entry, C = date of change, I = integer of id.
    R        is RESET: R = yes.
    M    is data mode: B = binary, 7 = ASCII, 6 = SIXBIT.
    A     is ADDITIVE: A = yes.
    E   is ERROR atom: T = TYPE, R = RECOVER, TR = both.

   For additional legend information, type HELP INFORM STRUCTURE TABLE KEY.


   The 1022 HELP message for INFORM STRUCTURE TABLE KEY is as follows:

   K  Refers to key status: * shows that the attribute is keyed in version 117 
       format; = shows that the attribute is keyed in 117 format and is keyed 
       inactive; + shows that the attribute is keyed in pre-117 format;
       - shows that the attribute is keyed in pre-117 format and is keyed inactive.
   T  Refers to the data type. Type T is Text, I is integer, R is Real, D is
       Date, and I2 is Double Integer.
   S  Refers to attributes that are treated specially. E is Date of Entry, C is 
       Date of Change, and I is Integer of Identification.
   R  Refers to the RESET specification used in LOAD  for Date of Entry, Date of 
       Change, and Integer of Identification. R shows that RESET is specified.
   M  Refers to the mode in which the attribute's values are represented. B
       shows that the representation is Binary, 7 that it is 7-bit ASCII,
       and 6 that it is SIXBIT.
   A  Refers to the ADDITIVE specification used in TRANSACT for computational
       attributes. A shows that the attribute is ADDITIVE.
   E  Refers to the ERROR specification for an attribute. T shows that ERROR TYPE
       has been specified for the attribute, R shows that ERROR RECOVER has
       been specified, and TR shows that ERROR TYPE and ERROR RECOVER have
       both been specified.

                                                                  Page 65


   11.4  INFORM STRUCTURE DATA

   The INFORM STRUCTURE DATA command  returns  the  same  information  in
   tabular  form  as  INFORM  STRUCTURE  TABLE except that the labels and
   legend are omitted.  The syntax is:

        INFORM [ ON <file-descriptor> ] STRUCTURE DATA

   For example, an INFORM STRUCTURE DATA command on the  BLOOD  data  set
   returns the following:

     FN    FIRST_NAME                T    7     1    10
   * LN    LAST_NAME                 T    7    11    15      
   *       AGE                       I    B    26     2      1:99
   * BG    BLOOD_GROUP               T    7    28     2      
   * RH    RH_FACTOR                 T    7    30     1      
   *       SEX                       T    7    31     1      
           COUNT                     I    B    32     6 A T  
     TD    TEST_DATE                 D ER B    38     8      

   The chief advantage of the INFORM STRUCTURE DATA command  is  that  it
   allows  you  to  use  the ON <file-descriptor> clause to create a data
   file.  This file can then be loaded into  a  data  dictionary  with  a
   description file like the following:

   ATTRIBUTE KEY_STATUS TEXT COL 1 1
   ATTRIBUTE ABBREV TEXT COL 3 7
   ATTRIBUTE ATTR_NAME TEXT COL 9 33
   ATTRIBUTE DATA_TYPE TEXT COL 35 36
   ATTRIBUTE SPEC_TYPE TEXT COL 37 37
   ATTRIBUTE RESET_SPEC TEXT COL 38 38
   ATTRIBUTE DATA_MODE TEXT COL 40 40
   ATTRIBUTE COL_START INTEGER COL 41 46
   ATTRIBUTE LEN_SPEC INTEGER COL 47 52
   ATTRIBUTE ADD_SPEC TEXT COL 54 54
   ATTRIBUTE ERROR_SPEC TEXT COL 56 57
   ATTRIBUTE RANGE_SPEC TEXT COL 59 70




   11.5  INFORM ATTRIBUTE

   The  INFORM  ATTRIBUTE  command  prints  the  information  about   the
   specified  attribute  that appears in the data set's description (DMD)
   file.  In addition, if the attribute is keyed or  keyed  inactive  and
   the  key  table  is  in pre-117A format, this information is displayed
   with the comment

        !PRE-117

   If key tables have been stored in an auxiliary file, the name of  this
   file is also displayed.  For example:

        *INFORM ATTRIBUTE LAST_NAME
                                                                  Page 66


   ATTRIBUTE LAST_NAME ABBREV LN TEXT KEYED KEYFILE AUX2.DMM COL 1 20



   11.6  INFORM STATUS

   The INFORM STATUS command displays a variety of information about  the
   current data set, including

         *  the message "Default update mode is ENQ" when access  to  the
            data  set  has been restricted to ENQ, either with the CREATE
            or MODIFY command;

         *  the message "Dataset is RECLOCK" when access to the data  set
            has been further restricted to record-locking mode;

         *  the message "UPDATE is ON"  when  the  user  has  issued  the
            UPDATE ON command after opening the data set;

         *  the message "UPDATE is PREVENTed" when the  user  has  issued
            the UPDATE PREVENT command after opening the data set;

         *  the specification "Dataset opened readonly" when that is  the
            case;

         *  the message "data set damaged" if damage has occurred;  and

         *  the number of records allocated to the data set.




   11.7  INFORM VERSION

   The INFORM VERSION command  displays  information  about  the  current
   version of System 1022, including the version banner, the file name of
   the current high segment, a list of all patches installed, the  system
   generation  date,  and  a  list  identifying  the optional System 1022
   modules that are installed at your site.  Modules not licensed by your
   site are listed in parentheses.

   For example:

   *INFORM VERSION
   System 1022A (117B(165))
   System Options:  Security, Audit Trails, LDS, HLI (no Accounting)
   Segment origin:  PS:<1022>QN1700
   (unpatched)
   System generation date:  1-May-86
                                                                  Page 67


   12.0  WILDCARDED ADMIT LISTS (TOPS-20)

   The support for wildcarding in ADMIT <directory  string>  commands  on
   TOPS-20  has  been expanded in two ways.  First, it is now possible to
   wildcard the device in an ADMIT command.  Second, it is  now  possible
   to  specify  a  wildcard  at  any point in the directory string, where
   formerly a wildcard could not appear  as  the  first  character  in  a
   directory string.

   For example,

        ADMIT *:<JONES> UPDATE

   gives the user who is logged in or connected to the directory  <JONES>
   update  privileges  on  all  devices  on  which  there  is  a  <JONES>
   directory.

        ADMIT PS*:<JONES> UPDATE

   gives the user at a CFS site who is logged  in  or  connected  to  the
   directory  <JONES>  update  privileges  on  all PS:  structures (PS1:,
   PS2:, and so on) on which there is a <JONES> directory.

        ADMIT PS:<*.TEST> UPDATE

   gives update privileges to all users  logged  in  or  connected  to  a
   subdirectory whose extension is TEST.



   13.0  DBA AS DIRECTORY STRING (TOPS-20)

   As of version 117B, when the 1022SA DBA  command  patches  HL1022.REL,
   1022.EXE,  NS1022.EXE,  and the object time systems at a TOPS-20 site,
   the designated DBA's directory string is stored as a directory  string
   and not as a project, programmer number (ppn).  The syntax is:

        DBA (device)<directory string>

   in which the default device is PS:.  The device may be wildcarded,  as
   may the rest of the string.  For example,

        DBA *:<JAMES>

   designates as the DBA  the  user  who  logs  in  or  connects  to  the
   directory <JAMES> on any device and then runs 1022.

        DBA PS:<JAMES*>

   designates as the DBA the user who logs in or connects  to  PS:<JAMES>
   or any subdirectory of PS:<JAMES> and then runs 1022.

   System 1022 establishes the identity of the DBA at start-up time, that
   is, when a user runs 1022 when logged in or connected to the DBA area.
   The user remains the DBA for the duration of the session, even  during
                                                                  Page 68


   a PUSH to another area.



   14.0  1022SA INFORM DBA COMMAND

   The purpose of the INFORM DBA command in 1022SA is to allow  users  of
   1022SA  to  display  the  TOPS-20  directory  string  or  the  TOPS-10
   project-programmer number (ppn) of the site's designated DBA, if  any.
   This  is particularly useful if the site wishes to designate a new DBA
   after the former DBA has left without  doing  so.   Someone  with  the
   appropriate  privileges  can  then build a new account with the former
   DBA's directory string or ppn, log into it, and designate the new DBA.

   The format of the command is

        INFORM DBA

   This will return the TOPS-20 directory string or the  TOPS-10  ppn  of
   the  designated  DBA, if there is one.  If there is no designated DBA,
   the command returns the message

        DBA not yet assigned.

   If your TOPS-10 site has elected to allow multiple users to  have  DBA
   status by specifying a mask in the DBA command, the INFORM DBA command
   will return the mask number as well as the DBA ppn.



   15.0  1022SA BANNER COMMAND

   It is now possible for sites to create their own  system  banner  with
   the 1022SA BANNER command.  The format of the command is

        BANNER

   When the 1022SA BANNER command  is  given,  the  following  prompt  is
   displayed:

        Enter banner:

   You may then enter a string of up  to  60  characters.   If  the  last
   character  in  the string is alphanumeric, a space will appear between
   the site banner and the Software House banner and version number.   If
   the  last  character in the string is a caret (^), the complete string
   up to but not including the caret will appear immediately  before  the
   Software House banner and version number.
                                                                  Page 69


   16.0  CUSTOM DMI READER

   16.1  Overview

   Prior to version 117B, the LOAD, APPEND, and TRANSACT  commands  could
   only  handle  records  in  7-bit ASCII, ASCII ISAM, SIXBIT, and SIXBIT
   ASCII formats.  It is now  possible  to  load,  append,  and  transact
   fixed-length  records  in  other  formats  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 facilitated by the system variable SYSCUSTDMI, which is set to  the
   address of the user's data translation routine, and by enhancements to
   the DBSYSV routine and 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  in
            FORTRAN  or  for the ACTION-FLAG argument in the DBSYSV enter
            in COBOL (see the examples below).

        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.   The
            syntax of the LOAD, APPEND, and TRANSACT commands is given in
            the "NODME Option of the LOAD, APPEND, and TRANSACT Commands"
            section below.

        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  or  COBOL I/O, the FORTRAN or 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.

            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 DBLODR call or enter takes
                two arguments.  The first of these identifies the  record
                to  be  passed.   The  second  is  an  integer  (or COMP)
                                                                  Page 70


                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.




   16.2  Examples

   16.2.1  FORTRAN 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.

                             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
                                                                  Page 71


                             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



   16.2.2  COBOL 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
   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.

                                                                  Page 72


   17.0  THE NODME OPTION OF LOAD, APPEND, AND TRANSACT

   The NODME option of the LOAD, APPEND, and TRANSACT commands suppresses
   the  creation  of  an  error (DME) file when the command executes.  If
   errors are  detected  during  the  execution  of  the  command,  error
   messages  are written to the terminal.  The NODME option allows you to
   conserve disk space and to  avoid  the  I/O  overhead  that  would  be
   involved in writing each error to a file.

   The syntax of the LOAD command is:


        LOAD [ DESC ] <file-descriptor>

             [ DATA <file-descriptor-2> ] [ SET <data set-descriptor> ]

             [ NOKEYS ] [ MAX <n> ] [ NOMSG ] [ NODME ] [ CUSTDMI ] [CORE <n> ] 

                                    { <n> }              {  IGNORE  }
             [ BUFFER <n> ] [ LRECL {     } ] [ FORMFEED {          } ]
                                    { [V] }              {TERMINATOR}


   The syntax of the APPEND command is:

          { DATA <file-descriptor-1> [ DESC <file-descriptor-2> ] }
   APPEND {                                                       }
          { SET <data set-descriptor>                             }

          [ NOMSG ] [ NODME ] [ CUSTDMI ]   [ LRECL <option> ]

          [ FORMFEED <option> ] [ CORE <n> ] [ BUFFER <n> ]



   The syntax of the TRANSACT command is:

                                                                  Page 73


            { DATA <file-descriptor1> DESC <file-descriptor2> }
   TRANSACT {                                                 }
            { SET <data set-descriptor>                       }

        [ SORTED  [ SYNC [MESSAGE] [TTYMSG] ] ]

          LOCATOR <attname>  [ , <attname> ] ...

        [ NOCHANGE BLANKS ] [ NODME ] [ CUSTDMI ]

                                           {  APPEND  }
        [  UNAPPLIED  [MESSAGE]  [TTYMSG]  {          } ]
                                           {  IGNORE  }

                                       { IGNORE  }
        [ APPLIED [MESSAGE] [TTYMSG]   { APPLY   } ] 
                                       { DELETE  }

                                                  { FIRST  }
        [ DUPLICATES TRANSACT [MESSAGE] [TTYMSG]  { LAST   } ]
                                                  { ALL    }
                                                  { IGNORE }

                                                { FIRST  }
        [ DUPLICATES MASTER [MESSAGE] [TTYMSG]  { LAST   } ]
                                                { ALL    }
                                                { IGNORE }

        [ LRECL <option> ]  [NOMSG]  [ FORMFEED <option> ]

        [ BUFFER <n> ]  [ CORE <n> ]





   18.0  THE SCRATCH AREA

   18.1  Overview

   System 1022 now includes a scratch area for use in  forming  selection
   sets  and  updating  key  tables.   By  default,  a 256-word buffer is
   allocated for every 8000 records per data set.  A minimum of two  such
   buffers  is  automatically  allocated.   If this amount of low-segment
   memory is not sufficient, overflow is handled by a scratch file.   The
   SET  SCRATCH  command  and the system variables SYSDCORESS, SYSCORESS,
   and SYSSCRFILE allow the user to regulate the  amount  of  low-segment
   memory allocated to the scratch area, specify whether the scratch area
   is to be used in forming selection sets, and choose whether  to  allow
   overflow  to  a  scratch  file.   These  options are described in more
   detail below.
                                                                  Page 74


   18.2  SYSDCORESS And SYSCORESS

   SYSCORESS and SYSDCORESS are two new system variables.  They allow the
   user  to control selection set format.  SYSCORESS is set to an integer
   value.  The default setting for SYSCORESS is 50,000, though  both  the
   Site  Administrator  and the user may reset this value.  If the number
   of records (including deleted records) in a data set is less  than  or
   equal  to  that  value, selection sets for that data set will be built
   entirely in core.  If the number of records in the data set is greater
   than that value, selection sets will be built as compressed bit tables
   that can spill over into a scratch file if they become too large.

   The user may override the  setting  of  SYSCORESS  with  the  variable
   SYSDCORESS.   By  default,  when  a  data set is opened, SYSDCORESS is
   automatically set to 1 if the number of records in  the  data  set  is
   less  than  or equal to the setting for SYSCORESS.  Selection sets for
   that data set are then formed entirely in  core.   If  the  number  of
   records  in  the  data  set is greater than the setting for SYSCORESS,
   SYSDCORESS is set to 0, and selection sets are formed using compressed
   bit  tables.   The  user  can  override  the default by specifying the
   appropriate setting for SYSDCORESS for any individual data set at  any
   time after opening the data set.  The setting takes effect at the next
   FIND command.

   Compressed bit tables should be used when most of  the  FIND  and  MAP
   commands  that are to be applied to the data set involve the selection
   of a small number of records.  Compressed bit tables  should  also  be
   used  when building bit tables entirely in core would take up too much
   space.  Bit tables that are built entirely in core are preferred  when
   working  with  a  small  data set or when the user anticipates issuing
   complex FIND commands on ranges of attribute values.  Bit tables built
   entirely in core also optimize the VALUES and SORT KEY commands.

   Note that the setting of SYSCORESS and SYSDCORESS has no effect on the
   amount  of low-segment memory that 1022 allocates to the scratch area,
   whether or not this area is used in forming selection sets.  To change
   the  amount  of  low-segment memory allocated to the scratch area, the
   user may use the SET SCRATCH command.



   18.3  SET SCRATCH

   The SET SCRATCH command allows the  user  to  specify  the  number  of
   buffers to be used by the scratch file that 1022 routinely creates for
   the session for building selection sets.  The syntax is:

        SET SCRATCH n

   where n is the number of buffers to be allocated to the  current  data
   set.

   The SET SCRATCH command is chiefly useful for limiting the  amount  of
   low-segment  memory  allocated  to the scratch area, and for expanding
   that amount if a scratch file is not  going  to  be  used  during  the
                                                                  Page 75


   session.



   18.4  SYSSCRFILE

   The system variable SYSSCRFILE allows the user to  prevent  1022  from
   opening  a  scratch  file  for  the  session.   If the user issues the
   command

        LET SYSSCRFILE 0 at the beginning of the session before any  data
   sets  are  opened,  no scratch file will be opened during the session,
   even if a subsequent

        LET SYSSCRFILE 1

   command is issued.  The default setting is 1.  Thus, if no LET command
   is  given  at  the  beginning  of  the  session,  a  scratch  file  is
   automatically opened and remains open for the session.

   Setting SYSSCRFILE to 0 spares you the overhead of a scratch file, but
   it may mean that you will run out of room in the low segment.  If this
   happens, you can try to make sufficient  room  with  the  SET  SCRATCH
   command.   If  that  yields insufficient space, you can rerun 1022 and
   LET SYSSCRFILE 1.



   19.0  KEY $SCAN, KEY $CHECKSUM, AND KEY $VERIFY

   The KEY $SCAN command returns statistical information  concerning  the
   average  space  used  per  key table block and the extent to which key
   tables have become fragmented.  The  KEY  $CHECKSUM  and  KEY  $VERIFY
   commands  allow  the  user  to  determine whether key tables have been
   damaged.  KEY $CHECKSUM simply shows whether or not the key tables for
   specified  attributes  are  damaged.   KEY  $VERIFY  also  shows  this
   information and, in addition, explains what the damage is, if any.

   Suppose, for example, that your data set contains the keyed  attribute
   LAST_NAME.   If the key table for that attribute has been damaged, the
   command

        KEY $CHECKSUM LAST_NAME

   will produce the message

        LAST_NAME
        ? checksums differ

   while the command

        KEY $VERIFY LAST_NAME

   will produce a message such as
                                                                  Page 76


        LAST_NAME
        SMITH
        7 from dataset

        SMITHE
        7 from key table

   This  message  shows  the  disagreement  between  the  value  for  the
   attribute  as it appears in the record and the value for the attribute
   as it appears in the key table.  The SYSID for the damaged record  and
   the associated key table value is also given.

   KEY $CHECKSUM operates more quickly than KEY $VERIFY and is  therefore
   preferred as a means of checking the key tables for damage.  If damage
   is discovered, then KEY $VERIFY may be used to pinpoint it.

   When damage such as that in the  above  example  is  encountered,  the
   CHANGE command may be used to repair it by making the attribute values
   in the data set and the key tables agree.   (Prior  to  version  117A,
   when the CHANGE command was issued on an attribute whose values in the
   data set and in the key table disagreed, an error message  was  issued
   and the update was terminated.)

   For example, suppose that you have issued the KEY  $CHECKSUM  and  KEY
   $VERIFY  commands  as  above.  To establish a single correct value for
   the attribute LAST_NAME in the data set and in the  key  table,  issue
   the following commands:

        FIND SYSID 7

        CHANGE LAST_NAME SMITHE

   This will produce error messages informing you of the original damage,
   but  will  perform the update.  The value of the attribute in the data
   set changes so that it agrees with the value in the key table.  If the
   desired  value  is  SMITH  and  not  SMITHE, then issue the additional
   command

        CHANGE LAST_NAME SMITH

   which will change the value of the attribute in both the data set  and
   the key table to SMITH.

   To make sure that  the  update  has  been  accomplished,  reissue  the
   command

        KEY $CHECKSUM LAST_NAME

   which now returns the message

        LAST_NAME verified
                                                                  Page 77


   20.0  SYSERRTEXT AND THE ERFCHK UTILITY

   Sites can create  an  alternative  1022  error  message  file  in  the
   language  of  their  choice  and use the system variable SYSERRTEXT to
   point to that file instead of to the standard  English  error  message
   file.   The utility ERFCHK.EXE should be used to assure that the error
   message file created by the site is of the correct format.  ERFCHK.EXE
   is included on the distribution tape.

   An alternate 1022 error message file may be created in  the  following
   way:

        1.  Copy the files 1022.ERR and ERFCHK.EXE from the  distribution
            tape to SYS:

        2.  Copy 1022.ERR  to  DSK:ERF.ERF.   1022.ERR  is  the  standard
            English  error  message file;  ERF.ERF is a copy of that file
            to be edited into the site language.

        3.  Edit ERF.ERF, replacing the English error messages with  text
            in the site language.  You may translate as many or as few of
            the messages as you choose.  Any messages  left  untranslated
            will appear in English.  Blank messages should be left blank.
            The text of each translated error message should be no longer
            than 72 characters (not including the error code and space at
            the beginning of the message line or the carriage return  and
            line  feed at the end).  ERFCHK will truncate messages longer
            than 72 characters and  will  pad  shorter  messages  out  to
            proper length with blanks.

        4.  Run ERFCHK.EXE.  This will produce the file 1022.ERF  in  the
            appropriate  format  for  System  1022.   If  any  errors are
            encountered in producing 1022.ERF, ERFCHK writes these  to  a
            file ERF.LOG.

        5.  Copy 1022.ERF to SYS:


   One Canadian  1022  site  has  produced  a  French-language  1022.ERF.
   Copies of this file are available from Software House.

   Users can now specify whether they wish to receive error  messages  in
   English  or  in the site language with the system variable SYSERRTEXT.
   The default setting (0) tells 1022 to read the standard English  file,
   1022.ERR,  when  an  error message is to be produced.  If the value of
   SYSERRTEXT is set to 1, the system will  instead  read  1022.ERF,  the
   file containing the translated error messages.

   SYSERRTEXT is system defaultable and user settable.  The user may  set
   the  value  of  the  variable  at  any  time during the session (or PL
   program).  However, once 1022  reads  the  error  file  designated  by
   SYSERRTEXT,  that  file  remains open for the remainder of the session
   (even if the user attempts to reset the value of the variable).
                                                                  Page 78


   21.0  SYSTOPSID AND SYSTOPIID

   The system variable SYSTOPSID returns the highest SYSID  in  the  data
   set.    The   variable   SYSTOPIID  returns  the  highest  integer  of
   identification in the data set.  For example, if the current data  set
   consists  of  90  deleted  records  and  1000  active  records,  PRINT
   SYSTOPSID will return a value of 1090, and PRINT SYSTOPIID will return
   a  value of 1090.  If you subsequently dump and reload, however, PRINT
   SYSTOPSID will return a value of  1000,  while  PRINT  SYSTOPIID  will
   still return a value of 1090.



   22.0  TEXT CONVERSION FUNCTIONS

   System 1022 now supports  three  text  conversion  functions:   $TEXT,
   $TEXTR, and $TEXTL.



   22.1  $TEXT

   The $TEXT function converts  its  argument  to  a  text  string.   The
   argument  may  be  any  System 1022 expression.  Input of type DATE is
   converted to ANSII-standard format (YYYYMMDD).  When $TEXT(arg) is  an
   expression  in  a  LET  command,  the  result is padded to length with
   trailing blanks if necessary.  Strings resulting from  input  of  type
   TEXT  are  truncated,  if  necesaary, while numeric input whose length
   exceeds the length of the variable produces an error.

   The following examples illustrate the ways in which $TEXT may be used,
   assuming that ID is an integer attribute and FOO is a text variable of
   length 10.

        * PRINT $TEXT(' abc ')
         abc
        *PRINT $TEXT(' abc '+' def ')
         abc  def

        * PRINT $TEXT(ID)
        62135
        * PRINT $TEXT(ID)+$TEXT(ID)
        6213562135

        * LET FOO $TEXT(ID)
        * PRINT FOO
        62135
        * PRINT FOO+FOO
        62135     62135

        * LET FOO 'ID: '+$TEXT(ID)
        * PRINT FOO
        ID: 62135

   It is in cases like the last one cited  that  $TEXT  is  most  useful,
                                                                  Page 79


   providing  an  easy  way to concatenate a value converted to text with
   some other value in a single text variable.



   22.2  $TEXTL And $TEXTR

   Like $TEXT, each of these functions converts its argument  to  a  text
   string.   The  argument may be any System 1022 expression.  The format
   of the result depends on the command and  on  the  complexity  of  the
   expression in which the function appears.

   When  $TEXTR(arg)  appears  in  a  PRINT  command,   the   result   is
   right-justified  to  the  default  length for the argument type.  When
   $TEXTL(arg) appears in a PRINT command, the result  is  left-justified
   to  the  default  length for the argument type.  Input of type DATE is
   converted to ANSII-standard  format  (YYYYMMDD).   The  default  field
   lengths are as follows:

        Type        Default Field Length        ____        _______ _____ ______

   Text             Same length as argument
   Integer          12
   Real             12
   Date             8
   Double Integer   24

   Output strings are padded to length, if necessary, with leading blanks
   in  the  case  of  $TEXTR(arg) and with trailing blanks in the case of
   $TEXTL(arg).

   When $TEXTL(arg) appears as the single expression in  a  LET  command,
   the result is left-justified in the receiving field.  When $TEXTR(arg)
   appears as the single expression in  a  LET  command,  the  result  is
   right-justified  in the receiving field.  Output strings are padded to
   length, if necessary, with leading blanks in the case  of  $TEXTR(arg)
   and  with  trailing  blanks  in  the  case  of  $TEXTL(arg).   Strings
   resulting from input of type TEXT are truncated if necessary, from the
   left  in  the case of $TEXTR and from the right in the case of $TEXTL.
   Numeric input whose length exceeds the length of the variable produces
   an error message.

   $TEXTL and $TEXTR perform exactly like $TEXT when  either  appears  as
   part  of  a  concatenated or nested expression in a LET command.  That
   is, the argument is converted to a text string with  no  justification
   or  padding.   As with other LET assignments, System 1022 will pad the
   result of the evaluation of the expression as a whole if necessary.

   The following examples illustrate the ways in which $TEXTL and  $TEXTR
   may  be used, assuming that ID is an integer attribute of length 8 and
   FOO is a text variable of length 10.

        * PRINT $TEXTL(' abc ')
        abc
        * PRINT $TEXTR(' abc ')
                                                                  Page 80


          abc
        * PRINT $TEXTL(' abc ')+$TEXTR(' abc ')
        abc   abc

        *PRINT $TEXTL(ID)
        62135
        * PRINT $TEXTR(ID)
               62135
        * PRINT $TEXTL(ID)+$TEXTR(ID)
        62135              62135

        * LET FOO $TEXTL(ID)
        * PRINT FOO
        62135
        * LET FOO $TEXTR(ID)
        * PRINT FOO+FOO
           62135   62135

        * LET FOO $TEXTL(ID)+$TEXTR(ID)
        * PRINT FOO
        6213562135



   23.0  $MOD FUNCTION

   The system function $MOD takes two arguments separated by a comma.  It
   converts these to integers and then returns the integer remainder that
   results from the division of the first by the second.

   For example,

        PRINT $MOD(13,4)

   returns the value 1.



   24.0  SYSFMSG

   The system variable SYSFMSG can  be  used  to  save  and  restore  the
   settings of the bit flags that are manipulated by the SET FMSG and SET
   FERR commands.  This is chiefly useful when you want to run a  command
   file  that  contains a SET FMSG or SET FERR command, or both, and want
   to leave the 1022 environment in its original state  with  respect  to
   these settings after execution has completed.

   The use of SYSFMSG is exemplified in the following  DMC,  which  saves
   the  current  settings of the bit flags determined by the SET FMSG and
   SET FERR commands (or the system defaults) in  the  variable  SAVEFSET
   and restores them after the rest of the file has executed:

   DEFINE INTEGER SAVEFSET.
   LET SAVEFSET SYSFMSG.    !Save the current settings in SAVEFSET.
   SET FMSG OFF.            !Temporarily turn off FMSG.
                                                                  Page 81


   SET FERR OFF.            !Temporarily turn off FERR.
        .
        .
        . 
   LET SYSFMSG SAVEFSET.    !Restore the original settings.




   25.0  SYSEXECKP

   The system variable SYSEXECKP allows TOPS-20 users to return to  their
   former  EXEC  rather than going to a new EXEC each time they PUSH from
   1022.  The standard default (0) puts the user in a new EXEC on a  PUSH
   from  1022.   If SYSEXECKP is set to 1, the user returns to his or her
   former EXEC on a PUSH.  The banner  is  not  redisplayed.   The  chief
   advantage  of  setting  SYSEXECKP  to  1  is one of speed, since, when
   SYSEXECKP is set to 1, TOPS-20  does  not  have  to  read  the  user's
   COMAND.COM file on each PUSH command.

   SYSEXECKP is both user settable and default settable.



   26.0  SYSNOYMD

   System 1022 accepts eight and  six  digit  all-numeric  dates  without
   delimiters.   The  settings  of  the  system  variables  SYSNOYMD  and
   SYSEURODAT and the composition of the digit string determine  the  way
   in  which  System  1022 interprets an all-numeric, non-delimited date.
   Both SYSNOYMD and SYSEURODAT are user-settable and default-settable.



   26.1  Eight-Digit Dates

   When SYSNOYMD is set to 0 (the default), System 1022  first  tries  to
   read  an  eight-digit  date as though it were in standard ANSII format
   (YYYYMMDD),  regardless  of  the  setting  of  the   system   variable
   SYSEURODAT.   For  example, if SYSNOYMD is set to 0, System 1022 reads
   the date 19550526 as May 26, 1955.

   If the two digits for the month are greater than 12, or the two digits
   for the day are greater than 31, then 1022 tries to read the string as
   an American date of the form MMDDYYYY (if  SYSEURODAT  is  set  to  0,
   which  is  the default) or as a European date of the form DDMMYYYY (if
   SYSEURODAT is set to 1).  For example, when SYSEURODAT is  set  to  0,
   the  date 05111956 is read as May 11, 1956.  When SYSEURODAT is set to
   1, 05111956 is read as November 5, 1956.

   When SYSNOYMD is set to 1, System 1022 does not try to read the string
   as  a  date of the form YYYYMMDD.  Rather, if SYSNOYMD is set to 1 and
   SYSEURODAT is set to 0, System 1022 tries to read  the  string  as  an
   American  date (MMDDYYYY).  If both SYSNOYMD and SYSEURODAT are set to
   1, System 1022 tries to read the string as a European date (DDMMYYYY).
                                                                  Page 82


   26.2  Six-Digit Dates

   When SYSNOYMD is set to 0, System 1022 first tries to read a six-digit
   date  as though it were in modified ANSII format (YYMMDD), in which YY
   represents the year with the  century  digits  omitted.   The  century
   digits  are assumed to be 19.  Thus, when SYSNOYMD is set to 0, System
   1022 interprets the date 550526 as May 26, 1955.

   If the two digits for the month are greater than 12, or the two digits
   for the day are greater than 31, then 1022 tries to read the string as
   an American date of the form MMDDYY (if SYSEURODAT is set to 0,  which
   is  the  default)  or  as  a  European  date  of  the  form DDMMYY (if
   SYSEURODAT is set to 1).  For example, when SYSEURODAT is  set  to  0,
   the date 051156 is read as May 11, 1956.  When SYSEURODAT is set to 1,
   051156 is read as November 5, 1956.

   When SYSNOYMD is set to  1,  System  1022  does  not  try  to  read  a
   six-digit  date  as YYMMDD.  Rather, if SYSEURODAT is set to 0, System
   1022 tries to read the string as an American date (MMDDYY).   If  both
   SYSNOYMD  and  SYSEURODAT  are set to 1, System 1022 tries to read the
   string as a European date (DDMMYY).



   26.3  Seven-Digit And Five-Digit Dates

   A leading zero may be omitted from an all-numeric date, thus  yielding
   a  seven-digit  or  a  five-digit  string.   In this case, System 1022
   follows the same procedures for interpreting the string as a  date  as
   it does for an eight-digit or six-digit string.

   For example, if SYSNOYMD is set to 0, System 1022 reads the date 50103
   as  January 3, 1905.  If SYSNOYMD is set to 1 and SYSEURODAT is set to
   0, 50103 is read as May 1, 1903.  If SYSNOYMD and SYSEURODAT are  both
   set to 1, the date is read as January 5, 1903.



   27.0  MAP BY SORT

   The BY SORT option of the MAP command accumulates and then  sorts  the
   locator values of the source data set before performing the MAP.  This
   means that duplicate values in the source data set do  not  come  into
   play  in  mapping  to  the target data set, reducing run time and disk
   access.



   28.0  ENFORCEMENT OF RESERVED WORDS

   System 1022 no longer allows reserved words to be used as the names of
   variables  or  attributes.  The LOAD, DEFINE, MODIFY, and LET commands
   all trap reserved words so used and generate an error message.

   The following are 1022 reserved words:
                                                                  Page 83


        ALL            END            NBEG           TEXT
        AND            EQ             NBEGINS        TEXTL
        ANY            EQUAL          NBET           TEXTR
        ASC            EQUALS         NBETWEEN       TO
        ASCENDING      EQV            NCONT          TOT
                                      NCT            TOTALS
        BEG            FALSE          NE             TRUE
        BEGINS         FILE           NEQ               
        BET            FMT            NOMSG          UP
        BETWEEN        FORMAT         NOREUSE        USING
        BUFFER                        NOT               
        BY             GE             NUL            VIA
                       GT             NULL              
        CONST                                        XOR
        CONT           INT            ON                
        CONTAINS       INTEGER        OR             $___
        CORE                                         
        CT             KEY            REAL              
                                      REMOVE         
        DATE           LAST           REUSE             
        DBL            LE                               
        DES            LT             SQ                
        DESCENDING                    SQRT              
        DINT           MAX            STDEV             
        DOUBLE         MEAN           SYS___
        DOWN           MIN



   29.0  DBRETN (FORTRAN)

   The DBRETN subroutine can now be used in a FORTRAN program to mark the
   end  of  a section of error-handling code whose beginning is a labeled
   statement to which control is transferred through a  call  to  DBERRH.
   Formerly, the DBERRH call could only transfer control to a subroutine.
   The call to DBERRH is:

                      { subrtn, }
        CALL DBERRH ( {         } IERT,IERC,IFLAG)
                      { $label, }

   Where:

        subrtn  Is the  name  of  the  subroutine  to  which  control  is
                transferred when an error occurs.  Such a subroutine ends
                with the statement  RETURN  followed  by  END.   At  this
                point,  control  is  transferred to the user's program at
                the command follow ing the  1022  call  that  caused  the
                error.

        $label  Is the statement to which control is transferred when  an
                error occurs.  You can give a value instead of a label if
                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
                                                                  Page 84


                program after printing any error messages.

                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.

        IERC    Is a variable that receives the error code number.

        IFLAG   1:  Print error messages at the terminal (default).
                0:  Suppress error messages.

   The DBRETN call is simply:

        CALL DBRETN



   30.0  DBEND DEBUGGING MESSAGE

   DBEND closes all data sets and performs cleanup operations,  releasing
   memory.   Prior  to  version  117A,  host language programs containing
   calls after a DBEND would continue executing past that point.  Now,  a
   warning  message is displayed if a call appears after a DBEND, and the
   process is aborted.  This now makes it possible  to  use  DBEND  as  a
   convenient debugging device.



   31.0  SORT22

   TOPS-20 users can now distribute the temporary  files  used  during  a
   SORT  over  multiple  structures.   To do this, you define SORT22 as a
   list of structures (or logical names) with the TOPS-20 DEFINE command,
   and  then  you can either include the clause USING SORT22 in your SORT
   or KEY command or set the system variable SYSSCRDEV to SORT22 with the
   command

        LET SYSSCRDEV "SORT22"

   The temporary files used by the sorter will then be  distributed  over
   the list defined by SORT22.

   By default, the scratch space for sorting will be  allocated  on  each
   device   listed   in   the  definition  of  SORT22  in  the  directory
   corresponding to your connected directory.  If  you  wish  to  specify
   some other directory, you can do so by defining SORT22 as X:  and then
   defining X:  as the device plus the directory.  For example,
                                                                  Page 85


        DEFINE SORT22:  X:,Y:,Z:
        DEFINE X:  PS:<JONES>,SP:<TEMP>,SP:<HOLD>

   The same effect can be achieved  on  TOPS-10  by  running  the  SETSRC
   program  before  doing  a  SORT  (for which the default is USING DSK).
   This will cause 1022 to distribute the temporary  files  used  by  the
   sorter  over  the  structures in the active portion of the disk search
   list established by SETSRC.



   32.0  FEATURES RELATING TO TOPS-20 MONITOR VERSION 6.1

   Prior to TOPS-20 monitor version 6.1,  a  PUSH  from  1022  would  run
   SYSTEM:EXEC.EXE.    As   of   version  6.1,  a  PUSH  from  1022  runs
   DEFAULT-EXEC:EXEC.EXE if one has been defined.  Otherwise, a PUSH from
   1022 runs SYSTEM:EXEC.EXE.

   Two additional features have been added for use  at  sites  running  a
   common file system with multiple PS:  structures.

        1.  The ADMIT list for a data set on  one  PS:   now  applies  to
            users  logged  in on other PS:  structures unless the dataset
            owner specified the particular PS:  structure  to  which  the
            security  provisions  were  to  apply  in  the original ADMIT
            command.  Thus, the command

                 ADMIT <JOE> RO

                          or

                 ADMIT PS:<JOE> RO

            gives the user logged into <JOE> on any PS:  (PS1:, PS2:,  or
            the like) readonly access to the data set.  The command

                 ADMIT PS1:<JOE> RO

            gives the user logged into <JOE> on PS1:  (but not  PS2:   or
            the like) readonly access to the data set.

        2.  If a user damages a data set, the user's  account  number  as
            well  as  his  or her logged-in PS:  is recorded and is saved
            until the pack is reformatted.




   33.0  MISCELLANEOUS IMPROVEMENTS


         *  PA1050 is the compatibility package that  allows  TOPS-20  to
            simulate  TOPS-10  monitor  calls.  Software House patches to
            PA1050 have been streamlined for greater efficiency.
                                                                  Page 86


         *  The procedures for applying Software House patches to  PA1050
            and  LIBOL  have  been simplified.  Software House patches to
            PA1050 and LIBOL are now  provided  in  Autopatch  format  in
            addition  to DIF format.  The new installation procedures are
            described in detail in the Data Base  Administrator's  Manual                                       ____ ____  _______________  ______
            (DBA.MEM on the distribution tape).

                                                                  Page 87


   34.0  TABLE OF SYSTEM VARIABLES

           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

                                                                  Page 88


            TABLE OF 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

                                                                  Page 89


            TABLE OF 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
   t_W t