___________________________________________________________



User Defined Functions (UDF's) for VAX Datatrieve

Donald E. Stern, Jr. - Warner Lambert Co., Milford CT
___________________________________________________________



Introduction

VAX Datatrieve provides a mechanism for easily extending the functionality  
provided in the "vanilla" product.  This additional functionality comes in the 
form of User Defined Functions or UDF's.  This article will deal with two major 
topics.  A system for creating and maintaining UDF's will be discussed first.  
Following this discussion, several specific UDF's, which have been added at our 
site, will be presented and discussed.


Creating and Maintaining UDF's

User Defined Functions are linked into the Datatrieve shareable image, DTRSHR. 
Several functions are already linked with DTRSHR when the product is installed.  
These functions include FN$ABS, FN$COS, FN$DAY, FN$LOG, FN$SHOW_TIMER, and 
FN$TRANS_LOG to name a few.  UDF's serve a wide variety of purposes.  Some 
functions are used in value expressions while others are used to modify the 
execution environment of a process.  

The functions linked with the Datatrieve image are specified in a Macro file 
called DFNFND.MAR.  The code in this file provides information regarding the 
name Datatrieve will use for this function, the name of the routine which will 
be linked with the image and called when the function is used, information 
regarding input and output arguments, etc.  The VAX DATATRIEVE Guide to 
Programming and Customization gives a fairly thorough explanation of what the 
various components of this file are and how to modify this file in order to add 
functions.

The specific routines called when the various functions are invoked can be a Run 
Time Library (RTL) routine, a System Service, or a user-written routine.  
Although extending Datatrieve by adding UDF's is a fairly straightforward 
procedure, many people are discouraged from doing so because of the need to deal 
with Macro, the linker, etc.  In a Wombat Magic presentation several years ago 
(Spring 1984) Phil Naecker described a process by which Datatrieve itself could 
be used to maintain the file DTRFND.MAR.  In fact, it was pointed out that the 
VAX Datatrieve development team uses a similar method to maintain the file which 
is ultimately shipped to customers.  We have implemented a system to create and 
maintain Datatrieve UDF's based upon this concept.  This system is described in 
the following paragraphs.


UDF Database Description

There is a one-to-many relationship between a function's attributes (DTR name, 
external name, value, query header, etc.) and its arguments.  A function can 
have 0 to n arguments, each having its own set of attributes (datatype, order, 
etc.)  Two domains have been created to contain the information needed to fully 
specify a UDF.  These domains are DTR_FUNCTION_INFO and DTR_FUNCTION_INPUTS and 
use the following record definitions.

DEFINE RECORD DTR_FUNCTION_INFO_REC USING
01 FUNCTION.
   03  DTR_FUNCTION_NAME           PIC X(31).
   03  FUNCTION_DESCRIPTION        PIC X(60).
   03  EXT_FUNCTION_NAME           PIC X(31).
   03  OUT_ARG_TYPE                PIC X(6)
       VALID IF (OUT_ARG_TYPE IN FUN_TYPE_TABLE).
   03  OUT_ARG_DTYPE               BYTE.
   03  OUT_ARG_DESCRIPTION         PIC X(60).
   03  EDIT_STR                    PIC X(31)
       MISSING VALUE " " QUERY_HEADER IS "EDIT STRING".
   03  QUERY_HDR                   PIC X(80)
       QUERY_NAME HDR MISSING VALUE " "
       QUERY_HEADER IS "QUERY HEADER".
   03  NOVALUE                     PIC X
       VALID IF NOVALUE EQ "Y","N" MISSING VALUE "N".
   03  NO_OPTIMIZE                 PIC X
       VALID IF NOVALUE EQ "Y","N" MISSING VALUE "N".
   03  IN_COUNT                    BYTE.
;


DEFINE RECORD DTR_FUNCTION_INPUTS_REC USING
01 INPUTS.
	03 DTR_FUNCTION_NAME  PIC X(31).
  	03 IN_ARG_TYPE        PIC X(5)
           VALID IF (IN_ARG_TYPE IN FUN_TYPE_TABLE).
  	03 IN_ARG_DESCRIPTION PIC X(60).
  	03 IN_ARG_DTYPE       BYTE.
  	03 ORDER              BYTE.
  	03 OUT_PUT            PIC X
           VALID IF OUT_PUT EQ "Y","N" MISSING VALUE "N".
  	03 ALL_LEN            WORD.
;

The fields used in these records are described in the following table.

     Field Name                           Description

Domain: DTR_FUNCTION_INFO

DTR_FUNCTION_NAME	     The name of the UDF.  This is the name that is used 
                             to reference the UDF from Datatrieve.

FUNCTION_DESCRIPTION	     This is a brief description of the functions 
                             intent.  The information is used to comment the 
                             MACRO code which is generated.

EXT_FUNCTION_NAME	     This is the name of the external function which 
                             will be called when the UDF is used.

OUT_ARG_TYPE		     This describes the value of the function.  It can 
                             be a value (eg. FN$LOG10(x)) or it can return a 
                             status.

OUT_ARG_DTYPE		     This is a code which specifies the datatype of the 
                             function.  A database of valid codes and 
                             corresponding datatypes is maintained.  (See 
                             Appendix IV for a listing of the domain, record, 
                             and table definitions, as well as, a listing of the 
                             valid datatypes.)

OUT_ARG_DESCRIPTION	     This describes the output and is used to comment 
                             the generated MACRO code.

EDIT_STR		     If a special edit-string is required, X(8) for 
                             example, this field is used to specify it.  It is 
                             not required information and can be left blank.

QUERY_HDR		     If a query header, other than the UDF name, is 
                             required then this field is used to specify it.

NOVALUE			     This field can contain a "Y" or an "N".  A "Y" 
                             indicates that no value is returned from the 
                             external function.  The UDFs FN$WIDTH and 
                             FN$CREATE_LOG are examples of such functions.

NO_OPTIMIZE		     This field can contain a "Y" or an "N".  If a "Y" 
                             is stored, then the UDF will not be optimized out 
                             of a loop.  The default value is "N".

IN_COUNT		     This specifies the number of arguments to be passed 
                             to/from the external function.  It corresponds 
                             exactly to the number of "member" records in 
                             DTR_FUNCTION_INPUTS.



Domain: DTR_FUNCTION_INPUTS

DTR_FUNCTION_NAME	     The DTR function name.  It relates records in this 
                             domain to records in DTR_FUNCTION_INFO.

IN_ARG_TYPE		     This field describes how the argument is passed, 
                             eg. by reference, by description, etc.

IN_ARG_DESCRIPTION	     This describes the argument.  The description is 
                             used to comment the generated MACRO code.

IN_ARG_DTYPE		     This describes the datatype of the argument.

ORDER			     This describes the order in which the argument 
                             appears in the argument list.

OUT_PUT			     Permitted values are "Y" and "N".  A "Y" indicates 
                             that this is a value returned from the external 
                             function rather than one passed to it.

ALL_LEN			     If the output is of predetermined length, it is 
                             specified here.  See FN$HEX and WL$OCTAL for 
                             examples.

Every UDF has one, and only one, record occurrence in the domain 
DTR_FUNCTION_INFO.  Each UDF must be identified by a unique function name, ie. 
FN$LOG10, this name is stored in the field DTR_FUNCTION_NAME.  Records in the 
domain DTR_FUNCTION_INPUTS contain information about a functions arguments.  
The field DTR_FUNCTION_NAME is used to relate records in this domain with the 
corresponding "owner" record in the DTR_FUNCTION_INFO domain.

Using the view definition given below the two domains are logically combined.  
Each record occurrence of this view contains sufficient information to 
completely define a UDF.

DEFINE DOMAIN DTR_FUNCTIONS OF DTR_FUNCTION_INFO,
   DTR_FUNCTION_INPUTS USING
01 DTR_FUNCTION OCCURS FOR DTR_FUNCTION_INFO.
       03 FUNCTION FROM DTR_FUNCTION_INFO.
       03 IN_ARGS OCCURS FOR DTR_FUNCTION_INPUTS WITH
                DTR_FUNCTION_NAME =
       	    	       DTR_FUNCTION_INFO.DTR_FUNCTION_NAME.
       	    05 INPUTS FROM DTR_FUNCTION_INPUTS.
;


As previously pointed out, UDF's reference external functions which are called 
and to/from which arguments are passed.  In the case of the User Defined 
Function FN$LOG10 the external function is the RTL routine MTH$ALOG10. The 
following shows the data stored for the Digital-supplied UDF FN$LOG10.

DTR_FUNCTION_NAME	    : FN$LOG10
FUNCTION_DESCRIPTION	    : Common logarithm
EXT_FUNCTION_NAME	    : MTH$ALOG10
OUT_ARG_TYPE		    : VALUE
OUT_ARG_DTYPE		    :   10
OUT_ARG_DESCRIPTION	    : output is a floating value in R0, R1
EDIT_STR		    :
QUERY_HDR		    :
NOVALUE			    : N
NO_OPTIMIZE		    : N
IN_COUNT		    :    1
   DTR_FUNCTION_NAME	           : FN$LOG10
   IN_ARG_TYPE		           : REF
   IN_ARG_DESCRIPTION	           : input is a floating value passed by reference
   IN_ARG_DTYPE		           :   10
   ORDER		           :    1
   OUT_PUT		           : N
   ALL_LEN		           :      0

The data shows us that the function FN$LOG10 uses the RTL function MTH$ALOG10; 
that the function returns a value which is a real number; no special 
EDIT_STRING or QUERY_HEADER are used; that the function can be optimized out 
of a loop (at Datatrieve compile time); and that the function requires a 
single argument, a real number passed by reference.


Maintaining the UDF Database

The procedures ADD_DTR_FUNCTION and ADD_DTR_FUNCTIONS were created in order to 
add data to the database.  The code for each is given in Appendix I.  Separate 
forms were created to capture the data for DTR_FUNCTION_INFO and 
DTR_FUNCTION_INPUTS.  While simplifying the data entry procedures, the existence 
of forms are not necessary; the procedures can be modified if the target system 
does not have FMS or TDMS installed. 

Two procedures, MAKE_DTRFND and PRINT_FUNCTION, are used to recreate the macro 
source file DTRFND.MAR.  The source code is assembled and linked into the 
Datatrieve shareable image. The code for these procedures is given in Appendix 
II.  MAKE_DTRFND, prints the Macro header information, executes PRINT_FUNCTION 
once for every record in DTR_FUNCTIONS, and prints the trailer information.  
PRINT_FUNCTION simply prints a DTR_FUNCTIONS record in the required format.  
Appendix II also contains the procedure MAKE_COMMAND which produces a DCL 
command file which, when executed, assembles DTRFND, copies the source, listing, 
and object files into a central location, and updates the library DTRFUN.OLB.

Since DTRFND.MAR is completely recreated by the use of these procedures, it is 
necessary to load data for Digital-supplied UDF's into the database as well as 
any site-specific UDF's.  


Site Specific UDF's


Naming Convention

We have developed a standard set of UDF's which are linked with the shareable 
Datatrieve images on each of the nodes in our network.  Almost without 
exception, UDF's previously described by users, in this and other 
publications, have followed the Digital naming convention.

                                    FN$name

We have found it more convenient to name our UDF's using a different 
convention.  All of our site specific UDF's are named using

                                    WL$name

as the convention.  By doing this, we can easily identify and separate Warner 
Lambert functions from those supplied by Digital.  Additionally, we are able 
to avoid naming conflicts as new versions of Datatrieve (with new functions) 
are released.  This significantly reduces the maintenance effort needed when 
re-installing Datatrieve.  The following is a list of some of the UDF's which 
have been implemented at our site.

Function Name                Function Description

WL$CHAR		     Convert an ASCII Code to an ASCII Character
WL$DAY		     Returns the number of days since the base date 17-Nov-1858
WL$DAY_OF_WEEK	     Returns a numeric day of the week for a date/time
WL$DELETE_FILE	     Delete a file
WL$DELETE_LOGICAL     Deletes a supervisor-mode logical from a specified table
WL$EDT		     Edit an ASCII file
WL$GET_SYMBOL	     Returns the value of a CLI symbol as a string
WL$OCTAL	     Convert an unsigned integer longword to an octal char. 
                     strg.
WL$POWER	     Computes the value of a number raised to a power
WL$RANDOM	     A random number generator
WL$RENAME_FILE	     Renames a file
WL$SET_LOGICAL	     (Re)defines a supervisor mode logical in a specified table
WL$SET_SYMBOL	     Define or redefine a CLI symbol
WL$WAIT		     Places current process in hibernation for specified time


WL$CHAR

We use this function primarily to generate non-printing ASCII characters, such 
as BELL (ASCII code 7) and ESCAPE (ASCII code 27), which tend to disrupt the 
printing of procedures when the character itself is embedded in the code.  In 
the Fall 1986 Wombat Magic session held in San Francisco, Pat Scopelletti 
demonstrated how the escape character could be programmed into a procedure 
using this function (Pat named his UDF FN$CHAR).

DECLARE ESC COMPUTED BY FN$CHAR(27).
	      :
	      :
PRINT ESC|"[?5i"     !Printer on
	      :
	      :
PRINT ESC|"[?4i"     !Printer off


WL$DAY_OF_WEEK

This function has a single argument, a DATE variable, and returns a value 
between 1 and 7 (Monday = 1 and Sunday = 7).  For example:

DTR> PRINT "TODAY" USING WWWWWWWWW, -
CON> "TODAY" USING DD-MMM-YYYY, WL$DAY_OF_WEEK("TODAY")

			WL$DAY
			   OF
			 WEEK

Sunday	   8-Feb-1987		7


WL$DELETE_FILE

This function has a single argument, a TEXT variable, which contains a valid 
file specification.  Unlike the DCL DELETE command, the file specification 
provided to this function does not require version number information.  For 
example:
                       DTR> WL$DELETE_FILE("YACHTS.DAT")

will delete the latest version of YACHTS.DAT.

This function is very useful in procedures which contain a DEFINE FILE 
command.  The UDF can be used to clear out any older versions of the file and 
thereby save disk space and the need to do this housekeeping outside of 
Datatrieve.


WL$DELETE_LOGICAL / WL$SET_LOGICAL

The Digital UDF FN$CREATE_LOG is used to create User Mode logical names.  
These functions are used to delete/create logical names in any specified 
logical name table (to which the user has write access of course.)  We found 
this particularly useful when spawning a subprocess from Datatrieve.  User 
mode logical names will not be defined for the subprocess but Process Mode 
logical names will.  For example, the statement

	   DTR> WL$SET_LOGICAL("DTR$LOGICAL","My logical name", 
                "LNM$PROCESS_TABLE")

will create a logical name called DTR$LOGICAL in the process logical name table 
and assign the value "My logical name" to it.  Similarly, the statement

           DTR> WL$DELETE_LOGICAL("DTR$LOGICAL","LNM$PROCESS_TABLE")

will delete the logical name from the table.


WL$EDT

This UDF requires a single argument, a TEXT variable containing a valid file 
specification.  It uses callable EDT to create/edit an ASCII text file.  In 
order to incorporate this function into the Datatrieve shareable image, we had 
to add a reference to the EDTSHR shareable image in the link command for DTRSHR.

            cluster=edtrtl,,,sys$common:[syslib]edtshr.exe/shareable

This UDF can be used in Datatrieve procedures to create and maintain ASCII 
files.  In this implementation, only one argument is used however the RTL 
function which is referenced will take a number of optional arguments as well 
(an EDT initialization file, for example).  The UDF could be restructured to 
accommodate these optional arguments as well.

One could achieve the same end result using an expression such as

                        DTR> FN$DCL("EDIT/EDT filespec")

but would incur the overhead involved with spawning a subprocess and activating 
the EDT.EXE image.  Using this function

                             DTR> WL$EDT(filespec)

will result in much less overhead and faster response time.


WL$GET_SYMBOL / WL$SET_SYMBOL

This pair of functions permit one to translate or define a symbol in the symbol 
table.  This can be particularly useful if Datatrieve is executing inside of a 
command or batch procedure.


WL$OCTAL

Modeled after DEC's FN$HEX function, WL$OCTAL permits the user to translate a 
decimal value into a string representing the octal equivalent.  This can be 
particularly useful when dealing with UIC's.

     DTR> PRINT WL$OCTAL(16)

     WL$OCTAL

           20


WL$POWER

This function simply raises a value to a power.  Two real number arguments are 
required, the base and the exponent.

DTR> PRINT WL$POWER(4.0,0.5), WL$POWER(5,3)

  WL$POWER	WL$POWER

  2.0000E+00	1.2500E+02


WL$RANDOM

This function returns a random number.  A single argument which is a longword 
"seed" value is required.  The RTL function MTH$RANDOM then computes a random 
value.  The function can be useful in statistical calculations requiring many 
iterations to compute probabilities.


WL$RENAME_FILE

As the name implies, this function is used to rename files.  It requires two 
arguments, both TEXT variables, which contain the old and new file 
specifications respectively.

               DTR> WL$RENAME_FILE(old_file_spec, new_file_spec)


WL$WAIT

This function takes a single argument, a floating value representing a 
specified number of seconds.  The function will then hibernate the process for 
the specified time.

                      DTR> WL$WAIT(5)     !Wait 5 seconds

This function can be used in applications where several reports or plots are 
created sequential and displayed on the screen.  If placed between report or 
plot statements, a pre-defined viewing time can be programmed into the 
procedure.


Generating Function Help

Digital supplies help text for all of the UDF's that are supplied with the 
installation kit.  By insuring that UDF's not supplied by Digital can be 
identified (via our naming convention), we are able to automatically generate 
help file source text for these functions.  The following procedure generates 
help file source text for our site-specific UDF's.

DEFINE PROCEDURE MAKE_FUNCTION_HELP
!
! This procedure generates help file source text for Warner Lambert
! UDF's.
!
! Written by:  Donald E. Stern, Jr.
!
READY DTR_FUNCTIONS SHARED
!
ON WL_FUNCTIONS.HLP
!
FOR DTR_FUNCTIONS WITH DTR_FUNCTION_NAME STARTING "WL"
BEGIN     ! Print the comments about the function
       PRINT "2  "|DTR_FUNCTION_NAME, SKIP 2,
       FUNCTION_DESCRIPTION (-),SKIP 2,
       OUT_ARG_DESCRIPTION (-), SKIP 2,"Arguments:", SKIP 1,
       ALL "     "|IN_ARG_DESCRIPTION (-), SKIP OF IN_ARGS, SKIP
END
END-PROCEDURE

The following is excerpted from the file WL_FUNCTIONS.HLP which was generated 
using this procedure.

       	    :
       	    :

2  WL$DELETE_FILE

Delete a file

No output

Arguments:
            Input is a filename to delete

       	    :
       	    :

Using the following command one can extract Digital function help from the 
Datatrieve help library SYS$HELP:DTRHELP.HLB.

            $ LIB/HELP/EXT=FUNCTIONS SYS$HELP:DTRHELP DEC_FUNCTIONS

Our help (WL_FUNCTIONS.HLP) can be concatenated with the Digital function help
(DEC_FUNCTIONS.HLP) into a single file (FUNCTIONS.HLP) using the following DCL 
command.

         $ COPY/CONC DEC_FUNCTIONS.HLP,WL_FUNCTIONS.HLP FUNCTIONS.HLP

This new help text is used to update the Datatrieve help library by the 
following command.

                 $ LIB/LOG/HELP/REP SYS$HELP:DTRHELP FUNCTIONS


Summary

User Defined Functions are one way in which the functionality of VAX 
Datatrieve can be greatly extended.  One need not be a MACRO programmer to 
implement UDFs.  The "cookbook" procedure described in the Datatrieve 
documentation can be followed or a system such as the one described here can 
be implemented.


Appendix I - Data Entry Routines


DEFINE PROCEDURE ADD_DTR_FUNCTIONS
!
! This procedures readies the necessary domains and calls
! the ADD_DTR_FUNCTION procedure 1 or more times to add new
! definitions for Datatrieve User Defined Functions.
!
!     Written by:    Donald E. Stern, Jr.
!                    Warner Lambert Company
!                    10 Webster Road
!                    Milford, CT  06460
!
!
READY DTR_FUNCTION_INFO SHARED WRITE
READY DTR_FUNCTION_INPUTS SHARED WRITE
DECLARE MORE PIC X.
!
! Shorthand for where we put User Defined DTR stuff.
FN$CREATE_LOG("SCHICK$DTR","SCHICK$DISK:[DTRLIB]")
MORE = "Y"
WHILE MORE="Y" BEGIN
        :ADD_DTR_FUNCTION
        MORE=FN$UPCASE(*.MORE)
END
END-PROCEDURE


DEFINE PROCEDURE ADD_DTR_FUNCTION
!
! This procedure is used to update the DTR_FUNCTIONS.DAT
! data file which all the necessary data to construct the
! DTRFUN.MAR file needed to add User Defined Functions
! (UDF's) to Datatrieve.
!
! NOTE:  The domains DTR_FUNCTION_INFO and
!        DTR_FUNCTION_INPUTS must be readed for WRITE
!        access before invoking this procedure.
!
!
!     Written by:    Donald E. Stern, Jr.
!                    Warner Lambert Company
!                    10 Webster Road
!                    Milford, CT  06460
!
!
!Create variables to contain data passed back from FMS
!
DECLARE FNAME PIC X(31).
DECLARE NARG  BYTE.
DECLARE ARGNM BYTE.
!
ARGNM=0
!
! Shorthand for where all our UDF stuff is.
!
FN$CREATE_LOG("SCHICK$DTR","SCHICK$DISK:[DTRLIB]")
!
!       Loop to update DTR_FUNCTION_INFO (1 record/UDF)
BEGIN
     STORE DTR_FUNCTION_INFO USING DISPLAY_FORM
           DTR_FUNCTION_ADD IN
           SCHICK$DTR:DTR_FUNCTIONS RETRIEVE USING
        BEGIN
          FNAME                        = GET_FORM NAME
          DTR_FUNCTION_NAME            = FNAME
          FUNCTION_DESCRIPTION         = GET_FORM FUN_DESC
          EXT_FUNCTION_NAME            = GET_FORM EXTERNAL
          OUT_ARG_TYPE                 = GET_FORM OUT_TYPE
          OUT_ARG_DTYPE                = GET_FORM OUT_DTYPE
          OUT_ARG_DESCRIPTION          = GET_FORM OUT_DESC
          EDIT_STR                     = GET_FORM EDT_STR
          QUERY_HDR                    = GET_FORM QRY_HDR
          NOVALUE                      = GET_FORM NOVAL
          NO_OPTIMIZE                  = GET_FORM NOOPT
          NARG                         = GET_FORM NARGS
          IN_COUNT                     = NARG
        END
     REPEAT NARG     !Loop to update DTR_FUNCTION_INPUTS
        BEGIN        !Contains 0-n records/UDF
          ARGNM = ARGNM + 1
          STORE DTR_FUNCTION_INPUTS USING DISPLAY_FORM
            DTR_FUNCTION_ADD_INARGS IN
                  SCHICK$DTR:DTR_FUNCTIONS USING
            BEGIN
               PUT_FORM NAME        = FNAME
               PUT_FORM ARGNUM      = ARGNM
            END RETRIEVE USING
            BEGIN
               DTR_FUNCTION_NAME    = FNAME
               IN_ARG_TYPE          = GET_FORM IN_TYPE
               IN_ARG_DESCRIPTION   = GET_FORM IN_DESC
               IN_ARG_DTYPE         = GET_FORM IN_DTYPE
               ORDER                = GET_FORM ARG_ORDER
               OUT_PUT              = GET_FORM OUTPUT
               ALL_LEN              = GET_FORM ALLLEN
            END
        END
END
END-PROCEDURE




Appendix II - Routines to Create DTRFND.MAR File


DEFINE PROCEDURE MAKE_DTRFND
!
! This procedure re-creates the MACRO file DTRFND.MAR
!
!       Supplied by:    Philip A. Naecker
!                       Consulting Engineer
!                       Altadena, CA
!
READY DTR_FUNCTIONS SHARED
SET COLUMNS_PAGE = 132
ON DTRFND.MAR
 BEGIN
  PRINT -
  ".TITLE  DTRFND  VAX-11 Datatrieve Function Definitions",
  SKIP,
  ";+++++++++++++++++++++++++++++++++++++++++++++++++++",
  SKIP, ";", SKIP,
  ";     F U N C T I O N    D E F I N I T I O N S", SKIP,
  ";", SKIP,
  ";---------------------------------------------------",
  SKIP 2,
  ".PSECT FND,NOWRT,SHR,PIC,2", SKIP 1,
  ".LIBRARY /DTR$LIBRARY:DTRFNLB/", SKIP 1,
  ".LIBRARY /SYS$LIBRARY:STARLET/", SKIP 1,
  ";.SHOW EXPANSIONS", SKIP 1,
  "$DSCDEF", SKIP 1,
  "$DTR$FUN_INIT", SKIP 4
!
!   Print all of the functions
!
  FOR DTR_FUNCTIONS  :PRINT_FUNCTION
!
!   Print the trailer
!
  PRINT "$DTR$FUN_FINI", SKIP 2, ".END"
 END;
END-PROCEDURE


DEFINE PROCEDURE PRINT_FUNCTION
!
! Print a single function definition in DTRFND.MAR
!
!       Supplied by:    Philip A. Naecker
!                       Consulting Engineer
!                       Altadena, CA
!
!     Modified by:     Donald E. Stern, Jr.
!                      Warner Lambert Company
!                      10 Webster Road
!                      Milford, CT  06460
!
BEGIN     ! Print the comments about the function
     PRINT "; "|DTR_FUNCTION_NAME|||"- "|
           FUNCTION_DESCRIPTION, SKIP, ";", SKIP,
           "; "|OUT_ARG_DESCRIPTION, SKIP,
           ALL "; "|IN_ARG_DESCRIPTION, SKIP OF IN_ARGS,
              SKIP
     ! The opening line
     PRINT "$DTR$FUN_DEF"|||DTR_FUNCTION_NAME||
          ", "|EXT_FUNCTION_NAME||", "|IN_COUNT
     ! The output argument
     PRINT "    $DTR$FUN_OUT_ARG  TYPE = "|
           OUT_ARG_TYPE VIA FUN_TYPE_TABLE||
           IF (OUT_ARG_TYPE EQ "STATUS","INPUT")
               THEN " "
           ELSE ", DTYPE = DSC$K_DTYPE_"|
               OUT_ARG_DTYPE VIA DTYPE_VALUE_TO_NAME
     ! If the function is a novalue function, say so.
     IF (NOVALUE EQ "Y") THEN
                PRINT "    $DTR$FUN_NOVALUE"
     ! If the function is a nooptimize function, say so
     IF (NO_OPTIMIZE EQ "Y") THEN
                PRINT "    $DTR$FUN_NOOPTIMIZE"
     ! Do the edit-string and query-header
     IF (EDIT_STR NOT MISSING) THEN
         PRINT "    $DTR$FUN_EDIT_STRING ^\"||
                EDIT_STR||"\"
     IF (HDR NOT MISSING) THEN
         PRINT "    $DTR$FUN_HEADER  HDR = <"||HDR||">"
     ! OK, now for the input arguments
     FOR A IN IN_ARGS
          CHOICE
            (IN_ARG_TYPE = "TEXT") THEN
               PRINT "    $DTR$FUN_IN_ARG  TYPE ="|||
               (IN_ARG_TYPE VIA FUN_TYPE_TABLE)||
               (IF (ALL_LEN EQ 0) THEN " "
                     ELSE ",ALL_LEN = "|ALL_LEN)|
               (CHOICE
                  (ORDER NE 0) THEN
                                ", ORDER = "|ORDER
                  (OUT_PUT EQ "Y") THEN
                                ", OUT_PUT = TRUE"
                          ELSE
                             ";;; illegal OUTPUT or ORDER"
                 END_CHOICE)
            (IN_ARG_TYPE = "VALUE") THEN
               PRINT "    $DTR$FUN_IN_ARG  TYPE ="|||
               (IN_ARG_TYPE VIA FUN_TYPE_TABLE)||
               ", DTYPE = DSC$K_DTYPE_"|
               IN_ARG_DTYPE VIA
                        DTYPE_VALUE_TO_NAME||", ORDER = "|
                        ORDER
            (IN_ARG_TYPE = "NULL") THEN
               PRINT "    $DTR$FUN_IN_ARG  TYPE ="|||
               (IN_ARG_TYPE VIA FUN_TYPE_TABLE)
            (IN_ARG_TYPE = "REF", "DESC") THEN
               PRINT "    $DTR$FUN_IN_ARG  TYPE ="|||
               (IN_ARG_TYPE VIA FUN_TYPE_TABLE)||
               ", DTYPE = DSC$K_DTYPE_"|
               IN_ARG_DTYPE VIA
                        DTYPE_VALUE_TO_NAME||
               (CHOICE
                  (ORDER NE 0) THEN ", ORDER = "|
                            ORDER
                  (OUT_PUT EQ "Y") THEN
                               ", OUT_PUT = TRUE"
                ELSE ";;; Illegal OUTPUT or ORDER"
               END_CHOICE)
              ELSE PRINT ";;; Illegal input type"
          END_CHOICE
     PRINT "$DTR$FUN_END_DEF", SKIP
END
END-PROCEDURE

DEFINE PROCEDURE MAKE_COMMAND_FILE
   ON CHECK.COM
   BEGIN
   PRINT "$MAC/LIS DTRFND"
   PRINT "$COPY DTRFND.MAR, DTRFND.LIS, DTRFND.OBJ -"
   PRINT "     SCHICK$DISK:[DTRLIB]*/LOG"
   PRINT "$LIBR/LOG/REP SCHICK$DISK:[SCHICK.DTRLIB]DTRFUN -"
   PRINT "     SCHICK$DISK:[DTRLIB]DTRFND"
   END
END-PROCEDURE




Appendix III - WL$x Function Definitions from DTRFND.MAR

The following was extracted from the file DTRFND.MAR.  It provides the precise 
definition for each of the site-specific UDF discussed above.

; WL$CHAR - convert an ASCII Code to an ASCII Character
;
; output is a one character string
;
; input is an unsigned byte ASCII code

$DTR$FUN_DEF WL$CHAR, LIB$CHAR, 2
    $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUS
    $DTR$FUN_IN_ARG  TYPE = FUN$K_TEXT, OUT_PUT = TRUE
    $DTR$FUN_IN_ARG  TYPE = FUN$K_REF,
    	 DTYPE = DSC$K_DTYPE_BU, ORDER = 1
$DTR$FUN_END_DEF

; WL$DAY - returns the number of days since the base date 17-Nov-1858
;
; output is a longword integer cont. the days since base date
;
; input is a binary quadword date

$DTR$FUN_DEF WL$DAY, LIB$DAY, 2
    $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUS
    $DTR$FUN_IN_ARG  TYPE = FUN$K_REF,
    	 DTYPE = DSC$K_DTYPE_L, OUT_PUT = TRUE
    $DTR$FUN_IN_ARG  TYPE = FUN$K_REF,
    	 DTYPE = DSC$K_DTYPE_ADT, ORDER = 1
$DTR$FUN_END_DEF

; WL$DAY_OF_WEEK - returns a numeric day of the week for a date/time
;
; output is an unsigned longword value between 1 and 7
; input is a 64-bit date/time
;

$DTR$FUN_DEF WL$DAY_OF_WEEK, LIB$DAY_OF_WEEK, 2
    $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUS
    $DTR$FUN_IN_ARG  TYPE = FUN$K_REF,
    	 DTYPE = DSC$K_DTYPE_ADT, ORDER = 1
    $DTR$FUN_IN_ARG  TYPE = FUN$K_REF, 
    	 DTYPE = DSC$K_DTYPE_L, OUT_PUT = TRUE
$DTR$FUN_END_DEF

; WL$DELETE_FILE - Delet a file
;
; No output
; Input is a filename to delete

$DTR$FUN_DEF WL$DELETE_FILE, LIB$DELETE_FILE, 1
    $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUS
    $DTR$FUN_NOVALUE
    $DTR$FUN_NOOPTIMIZE
    $DTR$FUN_IN_ARG  TYPE = FUN$K_DESC, 
    	 DTYPE = DSC$K_DTYPE_T, ORDER = 1
$DTR$FUN_END_DEF

; WL$DELETE_LOGICAL - deletes a supervisor-mode logical from a specified table
;
; no output
; argument 1 is a char. string containing the logical name
; arg. 2 is a char. string cont. the logical name table

$DTR$FUN_DEF WL$DELETE_LOGICAL, LIB$DELETE_LOGICAL, 2
    $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUS
    $DTR$FUN_NOVALUE
    $DTR$FUN_NOOPTIMIZE
    $DTR$FUN_IN_ARG  TYPE = FUN$K_DESC, 
    	 DTYPE = DSC$K_DTYPE_T, ORDER = 1
    $DTR$FUN_IN_ARG  TYPE = FUN$K_DESC, 
    	 DTYPE = DSC$K_DTYPE_T, ORDER = 2
$DTR$FUN_END_DEF

; WL$EDT - Edit an ASCII file
;
; No output
; input is a filename passed by descriptor

$DTR$FUN_DEF WL$EDT, EDT$EDIT, 1
    $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUS
    $DTR$FUN_NOVALUE
    $DTR$FUN_NOOPTIMIZE
    $DTR$FUN_IN_ARG  TYPE = FUN$K_DESC, 
    	 DTYPE = DSC$K_DTYPE_T, ORDER = 1
$DTR$FUN_END_DEF

; WL$GET_SYMBOL - returns the value of a CLI symbol as a string
;
; output is a character string passed by desc.
; arg. 1 is a char. string cont. the symbol name
;

$DTR$FUN_DEF WL$GET_SYMBOL, LIB$GET_SYMBOL, 2
    $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUS
    $DTR$FUN_IN_ARG  TYPE = FUN$K_DESC, 
    	 DTYPE = DSC$K_DTYPE_T, ORDER = 1
    $DTR$FUN_IN_ARG  TYPE = FUN$K_TEXT, OUT_PUT = TRUE
$DTR$FUN_END_DEF

; WL$OCTAL - convert an unsigned integer longword to an octal char. strg.
;
; output is a character string representing an octal value
; input is an unsigned integer longword passed by reference
;

$DTR$FUN_DEF WL$OCTAL, OTS$CVT_L_TO, 2
    $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUS
    $DTR$FUN_EDIT_STRING ^\X(8)\
    $DTR$FUN_IN_ARG  TYPE = FUN$K_REF, 
    	 DTYPE = DSC$K_DTYPE_L, ORDER = 1
    $DTR$FUN_IN_ARG  TYPE = FUN$K_TEXT,
    	 ALL_LEN = 8, OUT_PUT = TRUE
$DTR$FUN_END_DEF

; WL$POWER - computes the value of a number raised to a power
;
; output is a real number
; argument 1 is the base
; argument 2 is a real exponent

$DTR$FUN_DEF WL$POWER, OTS$POWRR, 2
    $DTR$FUN_OUT_ARG  TYPE = FUN$K_VALUE, 
    	 DTYPE = DSC$K_DTYPE_F
    $DTR$FUN_IN_ARG  TYPE = FUN$K_VALUE, 
    	 DTYPE = DSC$K_DTYPE_F, ORDER = 1
    $DTR$FUN_IN_ARG  TYPE = FUN$K_VALUE, 
    	 DTYPE = DSC$K_DTYPE_F, ORDER = 2
$DTR$FUN_END_DEF

; WL$RANDOM - a random number generator
;
; output is an F-floating random number
; input is an unsigned integer longword

$DTR$FUN_DEF WL$RANDOM, MTH$RANDOM, 1
    $DTR$FUN_OUT_ARG  TYPE = FUN$K_VALUE, 
    	 DTYPE = DSC$K_DTYPE_F
    $DTR$FUN_IN_ARG  TYPE = FUN$K_REF, 
    	 DTYPE = DSC$K_DTYPE_L, ORDER = 1
$DTR$FUN_END_DEF

; WL$RENAME_FILE - Renames a file
;
; No output
; Argument 1 is the source filename passed by descriptor
; Argument 2 is the new filename passed by descriptor

$DTR$FUN_DEF WL$RENAME_FILE, LIB$RENAME_FILE, 2
    $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUS
    $DTR$FUN_NOVALUE
    $DTR$FUN_NOOPTIMIZE
    $DTR$FUN_IN_ARG  TYPE = FUN$K_DESC, 
    	 DTYPE = DSC$K_DTYPE_T, ORDER = 1
    $DTR$FUN_IN_ARG  TYPE = FUN$K_DESC, 
    	 DTYPE = DSC$K_DTYPE_T, ORDER = 2
$DTR$FUN_END_DEF

; WL$SET_LOGICAL - (re)defines a supervisor mode logical in a specified table
;
; no output
; arg. 1 is a char. string containing the logical name
; arg. 2 is a char string containing the value to assign
; arg. 3 is a char. string cont. the name of the table

$DTR$FUN_DEF WL$SET_LOGICAL, LIB$SET_LOGICAL, 3
    $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUS
    $DTR$FUN_NOVALUE
    $DTR$FUN_NOOPTIMIZE
    $DTR$FUN_IN_ARG  TYPE = FUN$K_DESC, 
    	 DTYPE = DSC$K_DTYPE_T, ORDER = 1
    $DTR$FUN_IN_ARG  TYPE = FUN$K_DESC, 
    	 DTYPE = DSC$K_DTYPE_T, ORDER = 2
    $DTR$FUN_IN_ARG  TYPE = FUN$K_DESC, 
    	 DTYPE = DSC$K_DTYPE_T, ORDER = 3
$DTR$FUN_END_DEF

; WL$SET_SYMBOL - define or redefine a CLI symbol
;
; no output
; arg. 1 is a string descriptor containing the CLI symbol
; arg. 2 is a string descriptor cont. the CLI symbol value

$DTR$FUN_DEF WL$SET_SYMBOL, LIB$SET_SYMBOL, 2
    $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUS
    $DTR$FUN_NOVALUE
    $DTR$FUN_IN_ARG  TYPE = FUN$K_DESC, 
    	 DTYPE = DSC$K_DTYPE_T, ORDER = 1
    $DTR$FUN_IN_ARG  TYPE = FUN$K_DESC, 
    	 DTYPE = DSC$K_DTYPE_T, ORDER = 2
$DTR$FUN_END_DEF

; WL$WAIT - places current process in hibernation for specified time
;
; no output
; input is the number of seconds to wait - F-floating by ref.

$DTR$FUN_DEF WL$WAIT, LIB$WAIT, 1
    $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUS
    $DTR$FUN_NOVALUE
    $DTR$FUN_IN_ARG  TYPE = FUN$K_REF, 
    	 DTYPE = DSC$K_DTYPE_F, ORDER = 1
$DTR$FUN_END_DEF


Appendix IV - Database for Valid Datatypes

DEFINE TABLE DTYPE_NAME_TO_VALUE FROM DTYPS USING
	NAME : VALUE
END_TABLE

DEFINE TABLE DTYPE_VALUE_TO_NAME FROM DTYPS USING
	VALUE : NAME
END_TABLE

DEFINE DOMAIN DTYPS USING DTYP_REC ON
	SCHICK$DISK:[DTRLIB]DTYPE.DAT;

DEFINE RECORD DTYP_REC
01 DTYPE.
	03 VALUE	PIC 99.
	03 NAME 	PIC X(4).
	03 DESC 	PIC X(60).
;

Value   Name                Description

 00	 Z      unspecified
 01	 V      bit - an aligned bit string
 02	 BU      byte logical - 8-bit unsigned quantity
 03	 WU      word logical - 16-bit unsigned quantity
 04	 LU      longword logical - 32-bit unsigned quantity
 05	 QU      quadword logical - 64-bit unsigned quantity
 06	 B      byte integer - 8-bit signed 2's complement integer
 07	 W      word integer - 16-bit signed 2's-complement integer
 08	 L      longword integer - 32-bit signed 2's-complement integer
 09	 Q      quadword integer - 64-bit signed 2's-complement integer
 10	 F      F-floating - 32-bit single precision real number
 11	 D      D-floating - 64-bit double precision
 12	 FC      F-floating complex - low address real, high address imag
 13	 DC      D-floating complex- Pair of D-float. (low real, high imag.)
 14	 T      char. coded text - string data type
 15	 NU      numeric string, unsigned
 16	 NL      numeric string, left separate sign
 17	 NLO      numeric string, left overpunched sign
 18	 NR      numeric string, right separate sign
 19	 NRO      numeric string, right overpunched sign
 20	 NZ      numeric string, zoned sign
 21	 P      packed decimal string
 22	 ZI      sequence of instructions
 23	 ZEM      procedure entry mask
 24	 DSC      descriptor - levels of descriptors are allowed
 25	 OU      octaword logical - 128-bit unsigned quantity
 26	 O      octaword integer - 128-bit signed 2's complement integer
 27	 G      G-floating - 64-bit double precision number
 28	 H      H-floating - 128-bit quad precision real number
 29	 GC      G-floating complex- Pair of G-float. (low real, high imag.)
 30	 HC      H-floating complex- Pair of H-float. (low real, high imag.)
 31	 CIT      COBOL Interm. Temp. - 18-digit norm. dec. fract. 2-dig exp.
 32	 BPV      bound procedure value
 33	 BLV      bound label value
 34	 VU      bit unaligned - data are 0 to 2**16-1 contiguous bits
 35	 ADT      absolute date and time
 37	 VT      varying character-coded text


Appendix V - Table of Function/Argument Types

DEFINE TABLE FUN_TYPE_TABLE
	"STATUS"	:	"FUN$K_STATUS"
	"INPUT"		:	"FUN$K_INPUT"
	"VALUE"		:	"FUN$K_VALUE"
	"REF" 		:	"FUN$K_REF"
	"DESC"		:	"FUN$K_DESC"
	"TEXT"		:	"FUN$K_TEXT"
	"NULL"		:	"FUN$K_NULL"
END_TABLE

