Google
 

Trailing-Edge - PDP-10 Archives - BB-H548C-BM - iql-documentation/dbmspg.mem
There are 2 other files named dbmspg.mem in the archive. Click here to see a list.
                     CREATING AND EDITING A QUERY


                                 FIND
                      (for DBMS data base files)


FUNCTION:


     The FIND statement locates and reads a record from  a  DBMS  data
     base file.

FORMATS:


     The IQL FIND DBMS verbs are modelled  after  the  syntax  of  the
     Codasyl  DBMS  FIND  verbs, of which there are five variations in
     the current (V5A) implementation of DBMS-10/20.   Each  of  these
     variations is called a "record selection expression", or rse, and
     each variation has several options.  The FIND rse's are described
     in detail in the TOPS-20 Data Base Management System Programmer's
     Procedures Manual.  They are summarized below,  along  with  some
     comments  on  slight  variances  from the usages described in the
     referenced manual.


                                   NOTE

         In IQL, the use of the FIND verb always causes a  GET  of
         that  record, unlike the Codasyl usage, wherein those are
         separate functions.




     1.  FIND rse 1



         FIND record-name USING data-item.


         This  rse  gets  the  data  base   record   which   has   the
         direct-access  data  base  key  value given by the data-item.
         The only difference from the Codasyl rse syntax is  that  the
         record-name MUST be specified in IQL.










                                 3-24
                     CREATING AND EDITING A QUERY


     2.  FIND rse 2



         FIND [OWNER IN set-name-1 SET OF] CURRENT OF
                                        record-name RECORD.
                                        set-name-2 SET.
                                        area-name AREA.
                                        RUN-UNIT.

         This rse is used to get the "current" record,  as  identified
         by  record  name,  set  name,  area  name,  or RUN-UNIT.  The
         current record simply means the last accessed record  of  the
         named  entity,  e.g.   the  "current of set-name" is the last
         accessed record from that set, the "current  of  record-name"
         is  the  last  accessed record of that particlar record type,
         the "current of area" is the last accessed record  from  that
         area,  and  the  "current  of  RUN-UNIT" is the last accessed
         record by the query, of any type, from any area or set.


         If the phrase "OWNER IN ..." is used, the record accessed  is
         the   owner   of   the  named  current  record  via  the  set
         relationship named in the OWNER phrase.  The only  difference
         from  the  Codasyl rse syntax is that the keyword SET must be
         given in the OWNER phrase in IQL.


     3.  FIND rse 3

                FIND NEXT [record-name] RECORD OF set-name SET.
                                                  area-name AREA.
                     PRIOR
                     FIRST
                     LAST


         This FIND rse is used to access records in a relative fashion
         within  an area or set.  The NEXT record is the one following
         the current record, the PRIOR record is  the  one  preceeding
         the  current  record,  the  FIRST and LAST records are at the
         beginning or end, respectively.  The record name is optional,
         meaning  that  if it is not specified, the record accessed is
         any record which meets  the  specified  relation.   The  only
         difference from the Codasyl rse syntax is that the ability to
         specify a number as the relation operator  is  not  supported
         (i.e.   FIND  integer  RECORD  ...).  Since this is extremely
         rare in actual use, this should not be a limitation.






                                 3-25
                     CREATING AND EDITING A QUERY


         This is one of the most frequently used rse's,  particularily
         the FIND NEXT, since it will in fact find the first record of
         the set in case no previous record has been  found.   A  very
         common  construct  to use in queries which need to access all
         of the records of some type within an area is the following:

                IF FIRSTIME FIND FIRST record-name ...
                        ELSE FIND NEXT record-name ...


         In writing queries, you should always check the  ERROR-STATUS
         data  item,  as  it  will  be set to a non-zero value in case
         there is no record satisfying the relation  specified.   This
         will  occur,  for  example,  if  all  of  the  records in the
         set/area you are accessing have been found, and there are  no
         more records in that set/area.  This is somewhat analagous to
         an "end-of-file" condition.


     4.  FIND rse 4



         FIND OWNER RECORD OF set-name SET.


         This rse is used to find the owner of the current  record  of
         the  named  set.   This  is  identical  to using rse 2 if you
         specified the same set names for set-name-1 and set-name-2.


     5.  FIND rse 5



         FIND [NEXT DUPLICATE WITHIN] record-name RECORD.


         This rse is used to access records which are defined as  CALC
         records.   This  is  somewhat  like an ISAM facility, wherein
         certain fields within a record are  identified  as  CALC  (or
         key)  fields,  and  the  value within these fields is used to
         calculate a physical location for that record within the data
         base.   To  use  this  rse,  you must pre-initialize the CALC
         fields with the data values of the record you wish to access,
         and then issue the FIND verb.  For example,

                SET PERSON-NAME TO "SMITH".
                FIND NAME-RECORD RECORD.





                                 3-26
                     CREATING AND EDITING A QUERY


         The NEXT DUPLICATE phrase would be used to  access  the  next
         record with the same "key" value, for example the next record
         containing  SMITH.   The  schema  describing  the  data  base
         defines   records  as  having  CALC  fields,  and  allows  or
         prohibits the existence of duplicate key records.


         A special data item is provided by IQL for  use  with  rse  5
         FIND's,  in  the case of a certain CALC record type occurring
         in more than one area.  Since the area name is used  as  part
         of the CALC algorithm to find the record, this area name must
         be provided to the  DBMS  run-time  system.   The  data  item
         AREA-ID  is  used  for  this  purpose.   It is a 30 character
         alpha-numeric item which must be initialized with the name of
         the  area  which  is  to be used when searching for a certain
         record with a certain key.  If you have a record which occurs
         in  more than one area, and you use rse 5 without setting the
         AREA-ID, you will get an error with ERROR-STATUS set to 323.




CURRENCY UPDATING:


     Normally, whenever a record is accessed, the so-called  "currency
     indicators"  are  updated.  This means that the record just found
     is made the current record of its record type, the current record
     of  the  area,  the  current  record of any sets in which it is a
     member, and the current  record  of  the  RUN-UNIT.   In  certain
     applications,  however,  it  may  be  desireable  to suppress the
     currency updates, thereby causing some previously accessed record
     to  remain  as the current record.  This is expressed by adding a
     SUPPRESS phrase to the FIND rse statement, as follows:

        FIND rse SUPPRESS ALL     CURRENCY UPDATES.
                          RECORD
                          AREA
                          SET


     The only difference here from the  Codasyl  syntax  is  that  the
     ability  to  give  a  list  of  individual set names for which to
     suppress currency updates is not supported by IQL.










                                 3-27
                     CREATING AND EDITING A QUERY


DBMS STATUS INFORMATION:


     Certain status information about the results of DBMS  FIND  verbs
     is  made  available to a query in the form of special pre-defined
     data items.  These are:


     1.  ERROR-COUNT


         This is a numeric data item which is set by the DBMS run-time
         system  whenever  a  FIND is executed.  It is set to 0 if the
         FIND was successful, and set to non-zero if the  FIND  failed
         for any reason.


     2.  ERROR-STATUS


         This is a numeric data item which is set by the DBMS run-time
         whenever  a FIND is executed.  It is set to 0 if the FIND was
         successful, and is set to a non-zero error code  to  indicate
         the  nature of the error.  These error codes are described in
         the DBMS Programmer's Manual.  Most of the errors encountered
         by  the IQL user will be FIND errors, which are of the format
         03xx, where the 03 means that this is a FIND error,  and  the
         xx is the specific error code.


         Some of the more frequently  encountered  errors  are  listed
         below:

                356     no record found with this data base key
                        (rse 1)

                317/322 the specified current record does not 
                        participate as a member of the specified set
                        (rse 2 and rse 4)

                307/326 no record matches the specified relational
                        selection, or the set is empty
                        (rse 3)

                306     no current record for the named set exists
                        (rse 4)

                326     no record exists with these CALC values
                        (rse 5)

                323     the value given in the AREA-ID is invalid
                        (rse 5)


                                 3-28
                     CREATING AND EDITING A QUERY


     3.  RECORD-NAME


         This is an alpha-numeric data item, 30 characters long, which
         contains  the  actual record name of the record most recently
         accessed by a successful FIND, provided that currency updates
         were not suppressed.


     4.  AREA-NAME


         This is an alpha-numeric data item, 30 characters long, which
         contains  the  actual  area  name of the record most recently
         accessed by a successful FIND, provided that currency updates
         were not suppressed.


     5.  CURRENT-RECORD-KEY


         This is a numeric data item which contains  the  actual  data
         base  key  value  of  the  record most recently accessed by a
         successful FIND, provided  that  currency  updates  were  not
         suppressed.





























                                 3-29