Trailing-Edge - PDP-10 Archives - iqlv30 - iql3a.bwr
There is 1 other file named iql3a.bwr in the archive. Click here to see a list.
IQL3A Beware File                                                 Page 1

     1.  IQL3A changes the convention of naming saved (compiled) queries
         with file extension .QRY to .INQ.  This is because TOPS-20 uses
         the convention *.Q* for EDIT  backup  files.   Therefore  under
         both  TOPS-10  and TOPS-20 it will be necessary to RENAME saved
         query files from *.QRY to *.INQ.

     2.  The maximum record size in IQL is 4096 SIXBIT characters  (3410
         ASCII  characters).   For DBMS files, this means that the total
         combined number of characters in all the  record  participating
         in  the particular subschema defining the dictionary must be no
         more than 4096 characters, counting each FIXED BINARY  REAL  35
         and each DBKEY item as 6 characters, and each FIXED BINARY REAL
         70 item as 12 characters.

     3.  The maximum number of dictionary entries which may be generated
         by  IQSCH is 2160, which means that the total number of all FD,
         SD, DD, etc entries in any given  sub-schema's  diction  cannot
         exceed  2160.  If your schema contains more than this number of
         entries, create a sub-schema which includes a smaller number of

     4.  The maximum number of BIND arguments which can be generated  is
         512.   This  means  that  no one record may cause more than 512
         "parameters", which includes item  names,  area-id's,  aliases,
         and direct keys, to be bound at one time.

     5.  The maximum decimal scaling factor is 9;  therefore, DBMS  data
         items are limited to TYPE FIXED BINARY REAL 70,9.

     6.  The maximum number of item picture characters  in  dictionaries
         is  19  characters.   This  is only a problem when dealing with
         double-precision   binary   numbers   and   with    non-default
         alphanumeric  fields  (for  instance, when including extra "/",
         "-", etc.) The default alphanumeric picture is all "X"'s, which
         does not have to appear in the dictionary.

     7.  DBMS dictionaies must contain the byte size in the RD  entries,
         in  the  form  "006"  for  SIXBIT  records  and "007" for ASCII
         records.  Records which contain  all  COMPUTATIONAL-type  items
         are considered to be size "006".

         Dictionaries generated by version 3 of  IQSCH  do  not  contain
         this  information,  and  it  must be provided before using them
         with IQL3A.  The easiest way to do this is  to  regenerate  the
         dictionaries  with  Version  3A  IQSCH (the Replace command now
         works correctly).  However,  if  significant  effort  would  be
         required  to  reinstall  customized  item  column titles and/or
         pictures, the IQL DEFINE command can be used to modify  the  RD
         entries.   The  C (change) action code should be used to modify
         the RD entries by responding to the "Record type:" prompt  with
         S for SIXBIT or A for ASCII.

             RD entries have been used by some  sites  for  non-DBMS
             applications.   The information in these entries is now
             used in different ways, so it is  strongly  recommended
             that  these  sites  use  the DEFINE command in IQL3A to
             re-create these RD's.

     8.  IQSCH V3A will accept schema  names  and  sub-schema  names  in
         lower  case  and  correctly  convert  to  uper  case.  HOWEVER,
         privacy keys are NOT converted to upper-case,  since  they  are
         maintained  in  the  .SCH  file  as  ASCII  characters, and may
         legitimately contain lower-case, so  use  caution  if  you  are
         using a lower-case terminal.

     9.  IQSCH  V3A  now  computes  DBMS  record  lengths  and   origins
         correctly.    This   was  a  problem  mainly  with  data  bases
         containing ASCII records.   Users  should  carefully  check  RD
         entries  in  existing DBMS dictionaries, or should recreate the
         dictionaries with IQSCH V3A.

    10.  All  DBMS  FIND  rse's  are  supported   with   the   following

         1.  FIND USING identifier.  (rse 1)

         2.  FIND integer record-name RECORD OF ...  (rse 3)

         3.  FIND identifier record-name RECORD OF ...  (rse 3)

         4.  The SUPPRESS CURRENCY UPDATES options are  limited  to  the
             keywords  ALL, RECORD, AREA, and SET.  This only means that
             currency suppression is not supported for explicitly  named

         5.  In addition, the IQL3A syntax of rse 2 is

             FIND OWNER IN set-name SET OF ...

             where the keyword SET is required (this is  different  than
             the COBOL syntax).

    11.  It has been observed that it is somewhat faster to do FIND  rse
         2  to  reposition  after some intervening FIND's than to save a
         record key and do a FIND rse 1 to reposition.  In other  words,
         do  "FIND  CURRENT ...  RECORD" whenever possible in preference
         to "FIND ...  USING ...".

    12.  IQL3A no longer requires a FIND rse 3 to preceed a FIND  rse  1
         or FIND rse 5.
IQL3A Beware File                                                 Page 3

    13.  DBMS data types which are not supported by IQL3A are:




         4.  TYPE DISPLAY-9.

         Additionally, the use of the OCCURS clause at the 02 data  item
         definition  level  in  schemas  is  not supported.  In order to
         define a data structure, you must define it as

                SIZE nnn WORDS USAGE DISPLAY

         You may then use an OCCURS clause in the record descriptions in
         the SUB-SCHEMA section, but be aware that IQSCH does not create
         data items below the 02 level.

    14.  IQL3A considers any item name starting with "X" or "ZZ" to be a
         created  numeric variable.  Therefore, care should be used when
         generating dictionaries from DBMS schemas that no  item  names,
         record names, etc, begin with either "X" or "ZZ".

    15.  Caution must be used when using the  special  logical  variable
         FIRSTIME  in DBMS queries.  The interpretation of this variable
         is that it is TRUE on the first ACCESS to the  data  base,  and
         FALSE  on  subsequent ones, even though the multiple FIND's may
         be within the same statement.  Thus, the construct

            IF FIRSTIME
            IF NOT FIRSTIME

         will result in having both the FIND FIRST  ...   and  the  FIND
         NEXT  ...   statements  executed  on the first pass through the

    16.  IQL is quite sensitive to COBOL/LIBOL versions with which it is
         compiled,  linked,  and  executed.   The distributed .EXE files
         were built with  COBOL  V12,  and  should  only  be  used  with
         LIBO12.EXE  V12.   If  any  IQL  modules are to be rebuilt, use
         caution  that  the  same  versions  of  COBOL/LIBOL/LIBO12  are
         consistently used.  Also see the next note.

    17.  The  Field  Test  version  of  COBOL  V12A  is  not  completely
         compatible  with  IQL3A.   The  last patch line of Edit 535 was
         inadvertently left out of the Field Test LIBOL.  If COBOL  V12A
         Field  Test will be used with IQL V3A, then the fix file on the
IQL3A Beware File                                                 Page 4

         IQL3A tape called LIB12A.FIX must  be  installed  in  LIBOL.REL
         V12A  (and  in  LIBO12.EXE if sharable LIBOL is desired).  This
         will be corrected in the Field  Image  release  of  COBOL/LIBOL

    18.  All IQL modules  are  now  built  and  loaded  using  reentrant
         LIBO12.EXE, except for IQE and IQSCH.  This is due to a problem
         in one of the DBMS subroutines used by these  modules.   It  is
         possible  to build a version of IQE to use reentrant LIBO12.EXE
         but it will not support any DBMS queries.  (IQSCH is only  used
         for DBMS anyway).  The procedure is

         1.  Be sure Edit 535 is installed in LIBO12.EXE

         2.  Recompile IQE, IQES, and IQCALL without the "/R" switch

         3.  Remove the "LIBOL.REL/LIB" from IQEBAS.CMD

         4.  Reload by saying "LOAD @IQEBAS"

         5.  Save the result as IQE.EXE


                 Be sure to SAVE and not CSAVE on the DEC-20

         IQU is also loaded with private LIBOL, because of the Edit  535
         problem.  If LIBO12.EXE is rebuilt to include Edit 535, IQU may
         be relinked for reentrant LIBOL by recompiling without the "/R"
         switch,  and  by  removing  %"SEG:LOW"  and  LIBOL.REL/LIB from

    19.  FIND rse 6 is not officially supported by DBMS V5 and so is not
         supported  by  IQL3A.  It is possible to get access to the DBMS
         subroutine FINS6 which does a sorted set search, but  the  CALL
         verb  must be used.  A sample version of IQCALL which does this
         is provided on the  tape  called  IQFND6.CBL  for  illustration
         purposes only, and will be considered a Category C product.  In
         any event, the FINS6 subroutine will not be available  in  DBMS
         V6.   FIND  rse  6  will be officially supported in DBMS V6 and

    20.  IQL3A will accept queries  up  to  about  200  statement  long,
         depending on the actual statements used and the number of items
         used in the query.  It is possible to increase the  query  size
         acceptable to IQL by making source code changes in IQA and IQE,
         with a corresponding  increase  in  memory  requirements.   See
         BIGRQS.MEM for more details.
IQL3A Beware File                                                 Page 5

    21.  IQL3A does not like to  have  two  consecutive  FD  entries  in
         QPDICT.SEQ,  with  no  intervening  other  entries.  If nothing
         else, put a CD (comment definition) entry after each FD in your
         dictionaries (this is a good practice to follow in any case).

    22.  All files CREATE'd  from  DBMS  source  files  will  be  SIXBIT
         sequential  files with record size equal to the total number of
         characters in the items being used in the CREATE statement.  In
         addition,  files  are  SORT'ed using a SIXBIT key, so sort keys
         which contain lower-case characters will not be sorted strictly
         in ASCII collating sequence.

         Sequential files generated with the COPY statement will  be  in
         the same character set as the originating data file in the case
         of sequential and ISAM files.  However, because DBMS  allows  a
         mixture  of  character  types  in  the  same  data  base, IQL3A
         attempts  to  copy  the  composite  record  consisting  of  the
         concatenation  of  all  of  the  extracted  DBMS records into a
         sequential  SIXBIT  file,  but  without  doing  any   character
         conversion.   The  resulting  output file might then consist of
         intermixed SIXBIT, ASCII, and even computational  bit  strings.
         Because of these complications, it is recommended that the COPY
         statement be used with great caution with DBMS input files, and
         then  only  when  the data base consist entirely of SIXBIT data

    23.  Since  IQL3A  works  internally  in  SIXBIT,  all  lower   case
         characters  used  in  replying to ACCEPT's will be converted to
         upper-case.  This means that it is not  possible  to  ACCEPT  a
         CALC key which contains lower-case characters (upper case ASCII
         is OK, though).

    24.  All output from IQL3A will be in upper-case,  even  though  the
         data  files  may  contain  lower-case.   ASCII  nulls (000) are
         ignored, i.e.  they are not converted  to  spaces  or  anything
         else, they are just skipped over.

         Similarly, although it is possible to create data  item  titles
         in lower case, the output will always be upper case anyway.

    25.  Comment lines are now defined as they are in COBOL,  i.e.   any
         line  in  which  the  first  non-blank  character  is  an  * is
         considered to be all comment.  No attempt is made  to  scan  to
         the next period to terminate the comment.

         IQL now looks for comment lines in a  query  which  start  with
         "**"  and  changes them to "* ".  This is because the "**" is a
         flag signalling the beginning of a new query, and comment lines
         with  two  consecutive  "**"  are  indistinguishable  from this
         start-of-query  flag.   The  user  should  not  be   surprised,
         therefore, if comment lines are changed from "**" to "* ".

    26.  Numeric items used in CREATE verbs will be written as  18-digit
         numeric  fields with implied decimal scale of 5.  Note that the
         PICTURE defined for such items is only  followed  for  printing
IQL3A Beware File                                                 Page 6

         the value of the item in PRINT or DISPLAY statements.

    27.  A problem exists when using the "R" picture character to  round
         a  data  item  up.  If the item has a value which will overflow
         the picture field upon rounding,  the  printed  value  will  be
         zeroes.   This  occurs,  for  example,  when rounding the value
         99.998 into a picture "ZZ.99R" which will yield a printed value
         ".00".   (Incidentally,  the  correct  way to express a rounded
         picture  under  parenthesis  control  for  negative  values  is
         "(((9.99)R".  In this case, the value -123.456 would be printed
         "(123.46)" ).

    28.  The correct way to express literals which are  to  be  used  in
         centered  headings  is  to put the "//" (new line) marks at the
         beginning of the literal, not the end, otherwise the  centering
         algorithm  does not work completely correctly (it misses by one
         space too many on the left).  For instance, the correct way  to
         do this would be:

                HEADING "LINE 1//LINE 2"
                        "//LINE 3//LINE 4".

    29.  In order  to  resolve  a  syntatic  parsing  conflict,  numeric
         literals used in queries or when used in BROWSE/UPDATE may only
         contain the characters 0-9, ".", '+",  or  "-",  which  follows
         COBOL standards.  This means that the numeric literal 12,345.00
         is not allowed, but 12345.00 is allowed

    30.  When using Immediate  mode  to  access  an  ISAM  file,  it  is
         recommended  that  BROWSE  be used whenever possible instead of
         UPDATE.  This is because the run-time system invokes much  more
         overhead  when  the  file is opened for I/O instead of just for
         INPUT.  Also, ISAM files  opened  for  OUTPUT  are  effectively
         locked for the exclusive use of one user at a time.

    31.  The number of .LPT files which can exist at one time is limited
         to  36 per job per directory.  This is because of the manner in
         which file names are constructed from  the  job  number  and  a
         sequentially  increasing  "uniqueness"  character,  from "0" to
         "Z".  If is expected that a large number of .LPT files will  be
         created  during an IQL session, it recommended that a RENAME be
         done occassionally to make available more "creatable" .LPT file

    32.  The IQL3A DEFINE command can change almost  any  field  of  any
         entry  in  a  dictionary  EXCEPT the names of the dictionaries,
         data items, etc.  The  dictionary  (item,  etc.)  name  CAN  be
         changed  by  using  a  text editor on the QPDICT.SEQ dictionary
         file, but care must be taken.  To do this, find  the  FD  entry
         (the  record will start with the characters "FD") which contain
         the name of the dictionary to be  changed.   Replace  the  name
         with  exactly the same number of characters as there are in the
         record, i.e.  if the new name is shorter than the old one,  pad
         the  replacement  string  with  spaces, or if the new string is
IQL3A Beware File                                                 Page 7

         longer, replace the old name plus as many spaces  as  it  takes
         for  the  new  name.  The dictionary file entries are read by a
         COBOL program  which  expects  fields  to  occur  in  precisely
         defined  positions, and errors will be introduced if any fields
         become offset  from  their  expected  positions.   Remember  to
         remove  line  numbers  from  the  QPDICT.SEQ  file if you use a
         line-numbering editor like EDIT-20 or SOS.  (Also  be  sure  to
         change  any  queries  which refer to the old dictionary name to
         refer to the new one.)

    33.  In order to completely  delete  a  dictionary  field  with  the
         DEFINE command, give the key word BLANK (or BLANKS) in response
         to the prompt.  Any field may be blanked this way,  except  for
         the name of the entry itself.

    34.  The maximum length of any given query line  is  80  characters.
         Query  statements,  however,  can extend over several lines, as
         long as literals or item names are completely contained  within
         a single line (no word can be broken across two lines).
         For example, a query might contain:

                PRINT A,B,

    35.  The intention of the HOLD verb is to preserve the contents of a
         record  item.   It  is  possible  to  use  it to hold a created
         variable item, but remember that  this  is  not  sufficient  to
         cause  the variable to be created in the first place.  The HOLD
         essentially "reads" the contents of the item mentioned, and  if
         a  variable  is used in a HOLD without first creating it with a
         COMPUTE, SET, etc., IQL will assume that an undefined  item  is
         being referenced.

    36.  IQL3A has a  special  logical  test  variable  called  NEWGROUP
         (synonym is NEWGRPV) which can be tested in an IF statement (IF
         NEWGROUP OF item ...).  It is FALSE as long as the  named  item
         does  not change value from one data record to the next;  it is
         TRUE whenever the data item changes value in the  same  fashion
         as  occurs  with  the  TALLY  BY  statement.   This  allows for
         conditional actions to be taken other than just the effects  of
         the  various  summary  verbs  (this  exists  in  IQL3,  it  was
         inadvertently left out of the manual).

    37.  Created variables do not preserve their contents across  phases
         of a query (which are separated by SORT statements).

    38.  IF statements MUST have a TRUE clause.
         In other words, "IF A = B ELSE ..." is an illegal construct.
IQL3A Beware File                                                 Page 8

    39.  When defining a dictionary for an ISAM file, the file  name  to
         use  when  responding  to the DEFINE prompts is the name of the
         index file (usually the file with  the  .IDX  extension).   The
         file name to use when defining DBMS files is the .SCH file, but
         since this is done automatically by IQSCH, there should  seldom
         be occassion to change this.

    40.  Although the system text editor is available to  write  queries
         in IQL for TOPS-20, it is not possible to do the same thing for
         TOPS-10.  This  is  due  to  the  generalized  process  forking
         mechanism available in TOPS-20 but absent from TOPS-10.

    41.  The reserved word list has necessarily grown  as  a  result  of
         on-going  development  of  IQL.   Since it is possible that old
         dictionaries may contain some of these reserved words  as  data
         item  names,  it  is recommented that the list be consulted and
         compared to item definitions in older dictionaries.   The  list
         is distributed on the tape as RESERV.LIS.

    42.  Because IQL3A must provide dummy .IDX files to satisfy LIBOL at
         RESET  time,  certain  assumptions  have  to be made concerning
         "universally" common  parameters  of  users'  ISAM  files.   In
         particular,  the  dummy  files  ISAMF6.IDX  and  ISAMF7.IDX are
         constructed describing a data file blocked 10  and  index  file
         blocked 50.  As long as user files are less than these blocking
         factors, LIBOL will issue a warning message but will  correctly
         process  the  files.   However,  if  these blocking factors are
         EXCEEDED, different actions must be taken for each case.

         1.  If the INDEX  blocking  factor  is  greater  than  50,  the
             easiest way to fix the problem is to COPY (not RENAME) from
             the real data index file to the dummy file (ISAMF6  if  the
             data file is SIXBIT, ISAMF7 if the data file is ASCII).

         2.  If the DATA blocking factor is greater than 10, it will  be
             necessary  to modify the source code in modules IQE.CBL and
             IQU.CBL.  See the file named RECLEN.MEM on the distribution
             tape for more details on this procedure.

    43.  If column titles are turned  off  in  the  middle  of  a  query
         ("TITLES  OFF"),  columnar data such as decimal points will not
         be lined up properly.  Titles  should  either  be  left  on  or
         turned  off  for  the entire generation of a particular page to
         avoid this problem.

    44.  Caution should be used when using the same name for  more  than
         one  entity  in IQL3A.  For instance, it is all right to have a
         dictionary, a query, and a file name all with  the  same  name,
         but  it  is  incorrect  to  have  a  dictionary  and an item or
         password with the same name.  The best policy to follow  is  to
         never use the same name twice for anything.
IQL3A Beware File                                                 Page 9

    45.  IQL3 does not supported nested  IF  statements.   In  order  to
         properly  detect  and  diagnose  an  attempt to use a nested IF
         statement, IQL3A will not accept any use of  the  keyword  "IF"
         more  than  once in a statement.  This has the consequence that
         constructs of the form

                IF a = b OR (or AND) IF c = d ...

         which previously were accepted  as  a  compound  IF  expression
         (i.e.   the  second "IF" was discarded as a guide word) will no
         longer be acceptable.  If you have any queries which  use  this
         construct,  you will have to edit them to remove the extraneous
         "IF"s.  Notice that this makes  IQL  use  of  compound  logical
         expressions compatible with COBOL usage.

    46.  The REWRITE verb now works correctly when used in  a  query  to
         replace   an   existing  ISAM  record.   Caution,  however,  is
         recommended when using this verb that your data  files  are  in
         fact being correctly updated.

    47.  An undocumented, but very useful, feature of the DEFINE command
         when used to define a NEW dictionary is:

                DEFINE AUTO

         which will automatically  compute  and  fill  in  the  starting
         positions of DD entries being defined for this dictionary.  The
         "Loc of first char of item" prompt will be suppressed, and will
         be  filled  in automatically by the next sequential position in
         the  record  being  defined.   If  is  is  desired  to   define
         overlapping data items, these can be added later.

    48.  Statement  numbers  may  be  places  on  any   statement,   but
         statements  MUST  be two, and exactly two digits, and they must
         be places in columns 1 and 2 of the line.  Thus, use 01, not  1
         as  a  statement number.  Also, use some caution when doing "GO
         TO"'s.  Do not GO TO  an  OPEN  statement  after  it  has  been
         executed  once.  Do not GO TO statements outside of the current
         phase, i.e.  do not GO TO statements above a preceeding open or
         SORT, nor to statements below a succeeding SORT.

    49.  The example definition of the logical name DSK:  given on  page
         1-4 of the IQL User's Guide is incorrect.  All redefinitions of
         DSK:  should include DSK:  itself as the first element  of  the
         search  string,  so  that the user's connected directory is the
         first directory to be  used  when  accessing  DSK:   Thus,  the
         example should read:

                @DEFINE DSK:  DSK:,<DIRECT1>,<DIRECT2>

         Any other use of redefinitions of DSK:  must be done with great
         care, as problems may occur in the functioning of PA1050.
IQL3A Beware File                                                Page 10

    50.  A panic interrupt feature is available to  TOPS-20  IQL  users.
         See file SETINT.MEM for more details.

    51.  Alpha-numeric variables are those which start with  the  letter
         "A".  Dictionary data items may also begin with the letter "A".
         Alpha-numeric variables default  to  12  characters  in  length
         UNLESS  they  are  initially  set  to a value with more or less
         characters.  For example, if AVAR is to be used in a query, and
         it  needs  to be 20 characters long, the first statement in the
         query should set AVAR to 20 blanks to define the  size  of  the
         variable, as follows:

                SET AVAR TO "                    ".

    52.  Numeric variabled are scaled 13.5  always.   Thus,  even  in  a
         PICTURE  verb  is  used  to  redefine  the display picture, any
         ACCEPT verbs will prompt for a 13.5 numeric quantity,  and  the
         internal  representation  of  the  variable  will  be similarly
         scaled 13.5.

    53.  File DBMSPG.MEM replaces the DBMS FIND  verb  documentation  in
         the IQL USER'S GUIDE.

    54.  The SCAN feature when used with numeric data  items  now  works

    55.  Internal calculations when using the COMPUTE verb  are  carried
         out in 13.5 precision (13 whole number digits, and 5 fractional
         decimal  places,  for  a  total  of  18   digits).    This   is
         satisfactory  for  most  applications,  but if calculations are
         done with small fractions, appropriate scaling should  be  done
         to preserve accuracy.