Adding functions to VAX-DTR

       If you are going to add functions to DATATRIEVE you should really
  read the "Guide to Programming and Customization" manual.  I will give
  a brief summary here, however.  You do not have to know how to program
  in  Macro-32  (or  any  other  language) to add the functions supplied
  here.

       To add  additional  functions  to  VAX-DTR  you  have  to  add  a
  definition of the function to the DATATRIEVE executable image, and you
  either have to add the function code itself, or the  code  has  to  be
  somewhere  where  DTR  can "get" at it on the system.  In the function
  library supplied here all of the functions use VMS  run  time  library
  functions,  and  DTR  is  automatically  linked  to  these  libraries:
  therefore, all that is required is to add the definitions.

       To add functions, set your default to DTR$LIBRARY, which is where
  the  DATATREIVE  object  libraries,  sample program sources, and other
  pieces of the source kit should be.  In this  directory  should  be  a
  file  DTRFND.MAR,  which  contains  the  definitions for the functions
  supplied with DATATRIEVE.  You should first make a copy of  this  file
  with a command such as:

  COPY DTRFND.MAR DTRFNDOLD.MAR

  just in case you make a mistake or have to go  back  to  the  original
  distribution.  Then you can edit DTRFND.MAR to add additional function
  definitons:  the easiest way is to  include  the  DTRFND.MAR  supplied
  here.   The  additional definitions must come after the line (about 10
  to 15 lines from the start of the file) which begins

  $DTR$FUN_INIT

  which you should see just before the definition for FN$ABS,  and  they
  must come before the lines

   $DTR$FUN_FINI

   .END

  which should be  the  last  lines  in  the  file.   Within  these  two
  limitations   the   definitions   can  be  placed  anywhere  which  is
  convenient:  I suggest placing them all at the beginning  (just  after
  $DTR$FUN_INIT) so you can easily see that you have made changes to the
  DEC supplied file.  Note  also  that  any  line  that  begins  with  a
  semi-colon  ";"  is a comment line (just like a line beginning with an
  exclamation point "!" in DATATRIEVE) and it's a good idea to put in  a
  few comments recording when and by whom the additions were made.

       When the functions are added, you then assemble this  file.   The
  command is:

  MACRO/OBJECT/LIST DTRFND

  and you should not get any errors.  The /LIST switch is optional,  and
                                                                Page 2


  it  gives  you  a listing which may be helpful if you do get an error.
  An error is most likely to be due to a "garbled" source  file.   There
  is  not  much  reason  to  keep  the  DTRFND.LIS file if there were no
  errors.  Now you have to add the new object file to the  DTR  function
  object library with the command:

  LIB/REPLACE DTRFUN DTRFND

  and you should receive a message stating  that  DTRFND  was  replaced.
  Now  you  can  re-link the DATATRIEVE executable image by invoking the
  DTRBLD.COM file supplied with DATATRIEVE.  Note  the  warning  in  the
  current  release  notes  that if you are running on a cluster that you
  may have to copy the executable images  to  the  cluster  common  disk
  directories as the build procedure places them in the machine specific
  directories by default.  Also, you  may  have  to  shut  down  use  of
  DATATRIEVE  while you replace the old installed executable images with
  the new ones.  Don't purge the old executable images from  the  system
  directories until you have tested the new version of DATATRIEVE.

  B. Z. Lederman

  DTR/4GL SIG Library Representative