; ___________________________________________________________       1 User Defined Functions (UDF's) for VAX Datatrieve   5 Donald E. Stern, Jr. - Warner Lambert Co., Milford CT ; ___________________________________________________________        Introduction  L VAX Datatrieve provides a mechanism for easily extending the functionality  O provided in the "vanilla" product.  This additional functionality comes in the  P form of User Defined Functions or UDF's.  This article will deal with two major O topics.  A system for creating and maintaining UDF's will be discussed first.   P Following this discussion, several specific UDF's, which have been added at our & site, will be presented and discussed.     Creating and Maintaining UDF's  O User Defined Functions are linked into the Datatrieve shareable image, DTRSHR.  Q Several functions are already linked with DTRSHR when the product is installed.   K These functions include FN$ABS, FN$COS, FN$DAY, FN$LOG, FN$SHOW_TIMER, and  K FN$TRANS_LOG to name a few.  UDF's serve a wide variety of purposes.  Some  L functions are used in value expressions while others are used to modify the % execution environment of a process.     M The functions linked with the Datatrieve image are specified in a Macro file  M called DFNFND.MAR.  The code in this file provides information regarding the  O name Datatrieve will use for this function, the name of the routine which will  K be linked with the image and called when the function is used, information  H regarding input and output arguments, etc.  The VAX DATATRIEVE Guide to N Programming and Customization gives a fairly thorough explanation of what the P various components of this file are and how to modify this file in order to add 
 functions.  Q The specific routines called when the various functions are invoked can be a Run  J Time Library (RTL) routine, a System Service, or a user-written routine.  J Although extending Datatrieve by adding UDF's is a fairly straightforward Q procedure, many people are discouraged from doing so because of the need to deal  O with Macro, the linker, etc.  In a Wombat Magic presentation several years ago  P (Spring 1984) Phil Naecker described a process by which Datatrieve itself could O be used to maintain the file DTRFND.MAR.  In fact, it was pointed out that the  Q VAX Datatrieve development team uses a similar method to maintain the file which  P is ultimately shipped to customers.  We have implemented a system to create and P maintain Datatrieve UDF's based upon this concept.  This system is described in  the following paragraphs.      UDF Database Description  O There is a one-to-many relationship between a function's attributes (DTR name,  M external name, value, query header, etc.) and its arguments.  A function can  O have 0 to n arguments, each having its own set of attributes (datatype, order,  P etc.)  Two domains have been created to contain the information needed to fully P 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) 1        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)7        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 X5        VALID IF NOVALUE EQ "Y","N" MISSING VALUE "N". (    03  NO_OPTIMIZE                 PIC X5        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) 4            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 X9            VALID IF OUT_PUT EQ "Y","N" MISSING VALUE "N".    	03 ALL_LEN            WORD. ;   F The fields used in these records are described in the following table.  5      Field Name                           Description    Domain: DTR_FUNCTION_INFO   K DTR_FUNCTION_NAME	     The name of the UDF.  This is the name that is used  B                              to reference the UDF from Datatrieve.  G FUNCTION_DESCRIPTION	     This is a brief description of the functions  M                              intent.  The information is used to comment the  ;                              MACRO code which is generated.   G EXT_FUNCTION_NAME	     This is the name of the external function which  A                              will be called when the UDF is used.   E OUT_ARG_TYPE		     This describes the value of the function.  It can  M                              be a value (eg. FN$LOG10(x)) or it can return a  $                              status.  G OUT_ARG_DTYPE		     This is a code which specifies the datatype of the  F                              function.  A database of valid codes and J                              corresponding datatypes is maintained.  (See N                              Appendix IV for a listing of the domain, record, Q                              and table definitions, as well as, a listing of the  .                              valid datatypes.)  J OUT_ARG_DESCRIPTION	     This describes the output and is used to comment 6                              the generated MACRO code.  > EDIT_STR		     If a special edit-string is required, X(8) for O                              example, this field is used to specify it.  It is  L                              not required information and can be left blank.  ? QUERY_HDR		     If a query header, other than the UDF name, is  L                              required then this field is used to specify it.  > NOVALUE			     This field can contain a "Y" or an "N".  A "Y" J                              indicates that no value is returned from the G                              external function.  The UDFs FN$WIDTH and  J                              FN$CREATE_LOG are examples of such functions.  D NO_OPTIMIZE		     This field can contain a "Y" or an "N".  If a "Y" O                              is stored, then the UDF will not be optimized out  B                              of a loop.  The default value is "N".  C IN_COUNT		     This specifies the number of arguments to be passed  L                              to/from the external function.  It corresponds J                              exactly to the number of "member" records in 1                              DTR_FUNCTION_INPUTS.        Domain: DTR_FUNCTION_INPUTS   J DTR_FUNCTION_NAME	     The DTR function name.  It relates records in this D                              domain to records in DTR_FUNCTION_INFO.  C IN_ARG_TYPE		     This field describes how the argument is passed,  C                              eg. by reference, by description, etc.   I IN_ARG_DESCRIPTION	     This describes the argument.  The description is  F                              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.  B OUT_PUT			     Permitted values are "Y" and "N".  A "Y" indicates M                              that this is a value returned from the external  C                              function rather than one passed to it.   ? ALL_LEN			     If the output is of predetermined length, it is  J                              specified here.  See FN$HEX and WL$OCTAL for &                              examples.  A Every UDF has one, and only one, record occurrence in the domain  O DTR_FUNCTION_INFO.  Each UDF must be identified by a unique function name, ie.  N FN$LOG10, this name is stored in the field DTR_FUNCTION_NAME.  Records in the M domain DTR_FUNCTION_INPUTS contain information about a functions arguments.   N The field DTR_FUNCTION_NAME is used to relate records in this domain with the = corresponding "owner" record in the DTR_FUNCTION_INFO domain.s  O Using the view definition given below the two domains are logically combined.  sG Each record occurrence of this view contains sufficient information to o completely define a UDF.  1 DEFINE DOMAIN DTR_FUNCTIONS OF DTR_FUNCTION_INFO,g    DTR_FUNCTION_INPUTS USING- 01 DTR_FUNCTION OCCURS FOR DTR_FUNCTION_INFO.,*        03 FUNCTION FROM DTR_FUNCTION_INFO.5        03 IN_ARGS OCCURS FOR DTR_FUNCTION_INPUTS WITH #                 DTR_FUNCTION_NAME =r8        	    	       DTR_FUNCTION_INFO.DTR_FUNCTION_NAME./        	    05 INPUTS FROM DTR_FUNCTION_INPUTS.  ;k    O As previously pointed out, UDF's reference external functions which are called CI and to/from which arguments are passed.  In the case of the User Defined sK Function FN$LOG10 the external function is the RTL routine MTH$ALOG10. The sF following shows the data stored for the Digital-supplied UDF FN$LOG10.    DTR_FUNCTION_NAME	    : FN$LOG10+ FUNCTION_DESCRIPTION	    : Common logarithma" EXT_FUNCTION_NAME	    : MTH$ALOG10 OUT_ARG_TYPE		    : VALUEi OUT_ARG_DTYPE		    :   10 > OUT_ARG_DESCRIPTION	    : output is a floating value in R0, R1 EDIT_STR		    :  QUERY_HDR		    : NOVALUE			    : Nh NO_OPTIMIZE		    : N IN_COUNT		    :    1*    DTR_FUNCTION_NAME	           : FN$LOG10     IN_ARG_TYPE		           : REFP    IN_ARG_DESCRIPTION	           : input is a floating value passed by reference"    IN_ARG_DTYPE		           :   10    ORDER		           :    1     OUT_PUT		           : N    ALL_LEN		           :      0i  O The data shows us that the function FN$LOG10 uses the RTL function MTH$ALOG10; iE that the function returns a value which is a real number; no special nM EDIT_STRING or QUERY_HEADER are used; that the function can be optimized out oI of a loop (at Datatrieve compile time); and that the function requires a a3 single argument, a real number passed by reference.n     Maintaining the UDF Database  O The procedures ADD_DTR_FUNCTION and ADD_DTR_FUNCTIONS were created in order to  O add data to the database.  The code for each is given in Appendix I.  Separate mA forms were created to capture the data for DTR_FUNCTION_INFO and cQ DTR_FUNCTION_INPUTS.  While simplifying the data entry procedures, the existence aP of forms are not necessary; the procedures can be modified if the target system % does not have FMS or TDMS installed. s  O Two procedures, MAKE_DTRFND and PRINT_FUNCTION, are used to recreate the macro nJ source file DTRFND.MAR.  The source code is assembled and linked into the O Datatrieve shareable image. The code for these procedures is given in Appendix  O II.  MAKE_DTRFND, prints the Macro header information, executes PRINT_FUNCTION fM once for every record in DTR_FUNCTIONS, and prints the trailer information.   M PRINT_FUNCTION simply prints a DTR_FUNCTIONS record in the required format.   J Appendix II also contains the procedure MAKE_COMMAND which produces a DCL Q command file which, when executed, assembles DTRFND, copies the source, listing,  M and object files into a central location, and updates the library DTRFUN.OLB.F  O Since DTRFND.MAR is completely recreated by the use of these procedures, it is IO necessary to load data for Digital-supplied UDF's into the database as well as I any site-specific UDF's.       Site Specific UDF'sQ     Naming Convention   N We have developed a standard set of UDF's which are linked with the shareable G Datatrieve images on each of the nodes in our network.  Almost without OB exception, UDF's previously described by users, in this and other : publications, have followed the Digital naming convention.  +                                     FN$name.  E We have found it more convenient to name our UDF's using a different T; convention.  All of our site specific UDF's are named using5  +                                     WL$nameE  N as the convention.  By doing this, we can easily identify and separate Warner M Lambert functions from those supplied by Digital.  Additionally, we are able IM to avoid naming conflicts as new versions of Datatrieve (with new functions)  M are released.  This significantly reduces the maintenance effort needed when FN re-installing Datatrieve.  The following is a list of some of the UDF's which " have been implemented at our site.  1 Function Name                Function Description   9 WL$CHAR		     Convert an ASCII Code to an ASCII CharacterUG WL$DAY		     Returns the number of days since the base date 17-Nov-1858 E WL$DAY_OF_WEEK	     Returns a numeric day of the week for a date/timet! WL$DELETE_FILE	     Delete a fileMN 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 stringE 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 fileN WL$SET_LOGICAL	     (Re)defines a supervisor mode logical in a specified table2 WL$SET_SYMBOL	     Define or redefine a CLI symbolF WL$WAIT		     Places current process in hibernation for specified time     WL$CHARl  O We use this function primarily to generate non-printing ASCII characters, such  M as BELL (ASCII code 7) and ESCAPE (ASCII code 27), which tend to disrupt the  N printing of procedures when the character itself is embedded in the code.  In J the Fall 1986 Wombat Magic session held in San Francisco, Pat Scopelletti K demonstrated how the escape character could be programmed into a procedure p0 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  J 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, -n7 CON> "TODAY" USING DD-MMM-YYYY, WL$DAY_OF_WEEK("TODAY")i  	 			WL$DAY  			   OF 			 WEEK   Sunday	   8-Feb-1987		7$     WL$DELETE_FILE  M This function has a single argument, a TEXT variable, which contains a valid "K file specification.  Unlike the DCL DELETE command, the file specification eL provided to this function does not require version number information.  For  example:8                        DTR> WL$DELETE_FILE("YACHTS.DAT")  - will delete the latest version of YACHTS.DAT.t  G This function is very useful in procedures which contain a DEFINE FILE yN command.  The UDF can be used to clear out any older versions of the file and H thereby save disk space and the need to do this housekeeping outside of  Datatrieve.o    " WL$DELETE_LOGICAL / WL$SET_LOGICAL  J The Digital UDF FN$CREATE_LOG is used to create User Mode logical names.  I These functions are used to delete/create logical names in any specified  M logical name table (to which the user has write access of course.)  We found  K this particularly useful when spawning a subprocess from Datatrieve.  User  K mode logical names will not be defined for the subprocess but Process Mode c/ logical names will.  For example, the statement   9 	   DTR> WL$SET_LOGICAL("DTR$LOGICAL","My logical name",  $                 "LNM$PROCESS_TABLE")  P will create a logical name called DTR$LOGICAL in the process logical name table G and assign the value "My logical name" to it.  Similarly, the statementl  D            DTR> WL$DELETE_LOGICAL("DTR$LOGICAL","LNM$PROCESS_TABLE")  , will delete the logical name from the table.     WL$EDT  M This UDF requires a single argument, a TEXT variable containing a valid file oL specification.  It uses callable EDT to create/edit an ASCII text file.  In O order to incorporate this function into the Datatrieve shareable image, we had eP to add a reference to the EDTSHR shareable image in the link command for DTRSHR.  D             cluster=edtrtl,,,sys$common:[syslib]edtshr.exe/shareable  K This UDF can be used in Datatrieve procedures to create and maintain ASCII oJ files.  In this implementation, only one argument is used however the RTL N function which is referenced will take a number of optional arguments as well M (an EDT initialization file, for example).  The UDF could be restructured to s- accommodate these optional arguments as well.   A One could achieve the same end result using an expression such asD  8                         DTR> FN$DCL("EDIT/EDT filespec")  P but would incur the overhead involved with spawning a subprocess and activating ' the EDT.EXE image.  Using this functiona  2                              DTR> WL$EDT(filespec)  ; will result in much less overhead and faster response time.t     WL$GET_SYMBOL / WL$SET_SYMBOLf  P This pair of functions permit one to translate or define a symbol in the symbol O table.  This can be particularly useful if Datatrieve is executing inside of a D command or batch procedure.D     WL$OCTAL  N Modeled after DEC's FN$HEX function, WL$OCTAL permits the user to translate a L 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$OCTALR  
            20      WL$POWER  O This function simply raises a value to a power.  Two real number arguments are o$ required, the base and the exponent.  + DTR> PRINT WL$POWER(4.0,0.5), WL$POWER(5,3)1     WL$POWER	WL$POWER      2.0000E+00	1.2500E+021    	 WL$RANDOMw  N This function returns a random number.  A single argument which is a longword N "seed" value is required.  The RTL function MTH$RANDOM then computes a random N value.  The function can be useful in statistical calculations requiring many $ iterations to compute probabilities.     WL$RENAME_FILE  M As the name implies, this function is used to rename files.  It requires two  C arguments, both TEXT variables, which contain the old and new file I specifications respectively.  @                DTR> WL$RENAME_FILE(old_file_spec, new_file_spec)     WL$WAIT   G This function takes a single argument, a floating value representing a TO specified number of seconds.  The function will then hibernate the process for f the specified time.   9                       DTR> WL$WAIT(5)     !Wait 5 secondsa  M This function can be used in applications where several reports or plots are hM created sequential and displayed on the screen.  If placed between report or  G plot statements, a pre-defined viewing time can be programmed into the  
 procedure.     Generating Function Help  K Digital supplies help text for all of the UDF's that are supplied with the  I installation kit.  By insuring that UDF's not supplied by Digital can be iN identified (via our naming convention), we are able to automatically generate N help file source text for these functions.  The following procedure generates 2 help file source text for our site-specific UDF's.  # DEFINE PROCEDURE MAKE_FUNCTION_HELP  !sC ! This procedure generates help file source text for Warner Lambert  ! UDF's. !N# ! Written by:  Donald E. Stern, Jr.o !e READY DTR_FUNCTIONS SHARED !o ON WL_FUNCTIONS.HLPi !d6 FOR DTR_FUNCTIONS WITH DTR_FUNCTION_NAME STARTING "WL"1 BEGIN     ! Print the comments about the functionF-        PRINT "2  "|DTR_FUNCTION_NAME, SKIP 2,e'        FUNCTION_DESCRIPTION (-),SKIP 2, <        OUT_ARG_DESCRIPTION (-), SKIP 2,"Arguments:", SKIP 1,@        ALL "     "|IN_ARG_DESCRIPTION (-), SKIP OF IN_ARGS, SKIP END 
 END-PROCEDURE   N The following is excerpted from the file WL_FUNCTIONS.HLP which was generated  using this procedure.l  
        	    : 
        	    :t   2  WL$DELETE_FILEl  
 Delete a file   	 No output   
 Arguments:)             Input is a filename to deleteo  
        	    :d
        	    :t  K Using the following command one can extract Digital function help from the o- Datatrieve help library SYS$HELP:DTRHELP.HLB.D  C             $ LIB/HELP/EXT=FUNCTIONS SYS$HELP:DTRHELP DEC_FUNCTIONSe  N Our help (WL_FUNCTIONS.HLP) can be concatenated with the Digital function helpO (DEC_FUNCTIONS.HLP) into a single file (FUNCTIONS.HLP) using the following DCL i command.  E          $ COPY/CONC DEC_FUNCTIONS.HLP,WL_FUNCTIONS.HLP FUNCTIONS.HLPa  H This new help text is used to update the Datatrieve help library by the  following command.  >                  $ LIB/LOG/HELP/REP SYS$HELP:DTRHELP FUNCTIONS     Summarye  E User Defined Functions are one way in which the functionality of VAX mK Datatrieve can be greatly extended.  One need not be a MACRO programmer to WF implement UDFs.  The "cookbook" procedure described in the Datatrieve M documentation can be followed or a system such as the one described here can e be implemented.r      Appendix I - Data Entry Routines    " DEFINE PROCEDURE ADD_DTR_FUNCTIONS !i9 ! This procedures readies the necessary domains and callsh; ! the ADD_DTR_FUNCTION procedure 1 or more times to add newn4 ! definitions for Datatrieve User Defined Functions. ! ) !     Written by:    Donald E. Stern, Jr.e+ !                    Warner Lambert Companyi$ !                    10 Webster Road' !                    Milford, CT  06460e !e !o$ READY DTR_FUNCTION_INFO SHARED WRITE& READY DTR_FUNCTION_INPUTS SHARED WRITE DECLARE MORE PIC X.  !i4 ! Shorthand for where we put User Defined DTR stuff.2 FN$CREATE_LOG("SCHICK$DTR","SCHICK$DISK:[DTRLIB]")
 MORE = "Y" WHILE MORE="Y" BEGIN         :ADD_DTR_FUNCTIONe         MORE=FN$UPCASE(*.MORE) END 
 END-PROCEDUREs    ! DEFINE PROCEDURE ADD_DTR_FUNCTIONo ! 8 ! This procedure is used to update the DTR_FUNCTIONS.DAT9 ! data file which all the necessary data to construct theL6 ! DTRFUN.MAR file needed to add User Defined Functions ! (UDF's) to Datatrieve. !D* ! NOTE:  The domains DTR_FUNCTION_INFO and5 !        DTR_FUNCTION_INPUTS must be readed for WRITEi/ !        access before invoking this procedure.y !  !e) !     Written by:    Donald E. Stern, Jr. + !                    Warner Lambert Company $ !                    10 Webster Road' !                    Milford, CT  06460e !i !m6 !Create variables to contain data passed back from FMS !n DECLARE FNAME PIC X(31). DECLARE NARG  BYTE.s DECLARE ARGNM BYTE.  !r ARGNM=0l !e+ ! Shorthand for where all our UDF stuff is.n !o2 FN$CREATE_LOG("SCHICK$DTR","SCHICK$DISK:[DTRLIB]") !B7 !       Loop to update DTR_FUNCTION_INFO (1 record/UDF)! BEGIN /      STORE DTR_FUNCTION_INFO USING DISPLAY_FORMn            DTR_FUNCTION_ADD IN2            SCHICK$DTR:DTR_FUNCTIONS RETRIEVE USING
         BEGIN 6           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_DTYPEa:           OUT_ARG_DESCRIPTION          = GET_FORM OUT_DESC9           EDIT_STR                     = GET_FORM EDT_STRe9           QUERY_HDR                    = GET_FORM QRY_HDR 7           NOVALUE                      = GET_FORM NOVALr7           NO_OPTIMIZE                  = GET_FORM NOOPTr7           NARG                         = GET_FORM NARGS -           IN_COUNT                     = NARGt         END 8      REPEAT NARG     !Loop to update DTR_FUNCTION_INPUTS.         BEGIN        !Contains 0-n records/UDF           ARGNM = ARGNM + 1i6           STORE DTR_FUNCTION_INPUTS USING DISPLAY_FORM&             DTR_FUNCTION_ADD_INARGS IN0                   SCHICK$DTR:DTR_FUNCTIONS USING             BEGIN(+                PUT_FORM NAME        = FNAME)+                PUT_FORM ARGNUM      = ARGNMp             END RETRIEVE USING             BEGINl+                DTR_FUNCTION_NAME    = FNAMEr6                IN_ARG_TYPE          = GET_FORM IN_TYPE6                IN_ARG_DESCRIPTION   = GET_FORM IN_DESC7                IN_ARG_DTYPE         = GET_FORM IN_DTYPEB8                ORDER                = GET_FORM ARG_ORDER5                OUT_PUT              = GET_FORM OUTPUTy5                ALL_LEN              = GET_FORM ALLLEN              ENDL         ENDD ENDG
 END-PROCEDUREE        0 Appendix II - Routines to Create DTRFND.MAR File     DEFINE PROCEDURE MAKE_DTRFND !i5 ! This procedure re-creates the MACRO file DTRFND.MARo !p) !       Supplied by:    Philip A. Naeckere+ !                       Consulting Engineerr$ !                       Altadena, CA !s READY DTR_FUNCTIONS SHARED SET COLUMNS_PAGE = 132
 ON DTRFND.MARs  BEGIN	   PRINT -s;   ".TITLE  DTRFND  VAX-11 Datatrieve Function Definitions",    SKIP,)9   ";+++++++++++++++++++++++++++++++++++++++++++++++++++",u   SKIP, ";", SKIP,9   ";     F U N C T I O N    D E F I N I T I O N S", SKIP,    ";", SKIP,9   ";---------------------------------------------------",h	   SKIP 2,t'   ".PSECT FND,NOWRT,SHR,PIC,2", SKIP 1,L+   ".LIBRARY /DTR$LIBRARY:DTRFNLB/", SKIP 1, +   ".LIBRARY /SYS$LIBRARY:STARLET/", SKIP 1,m   ";.SHOW EXPANSIONS", SKIP 1,   "$DSCDEF", SKIP 1,   "$DTR$FUN_INIT", SKIP 4f !D !   Print all of the functions ! $   FOR DTR_FUNCTIONS  :PRINT_FUNCTION !n !   Print the trailer  ! '   PRINT "$DTR$FUN_FINI", SKIP 2, ".END"a  END; 
 END-PROCEDUREe     DEFINE PROCEDURE PRINT_FUNCTIONt !l2 ! Print a single function definition in DTRFND.MAR ! ) !       Supplied by:    Philip A. Naecker + !                       Consulting Engineeri$ !                       Altadena, CA !a+ !     Modified by:     Donald E. Stern, Jr.p- !                      Warner Lambert CompanyR& !                      10 Webster Road) !                      Milford, CT  06460f !t1 BEGIN     ! Print the comments about the functionc)      PRINT "; "|DTR_FUNCTION_NAME|||"- "| 1            FUNCTION_DESCRIPTION, SKIP, ";", SKIP, *            "; "|OUT_ARG_DESCRIPTION, SKIP,8            ALL "; "|IN_ARG_DESCRIPTION, SKIP OF IN_ARGS,               SKIP      ! The opening linee/      PRINT "$DTR$FUN_DEF"|||DTR_FUNCTION_NAME||l/           ", "|EXT_FUNCTION_NAME||", "|IN_COUNTa      ! The output argument+      PRINT "    $DTR$FUN_OUT_ARG  TYPE = "| ,            OUT_ARG_TYPE VIA FUN_TYPE_TABLE||0            IF (OUT_ARG_TYPE EQ "STATUS","INPUT")                THEN " ",)            ELSE ", DTYPE = DSC$K_DTYPE_"|e4                OUT_ARG_DTYPE VIA DTYPE_VALUE_TO_NAME5      ! If the function is a novalue function, say so.       IF (NOVALUE EQ "Y") THENW,                 PRINT "    $DTR$FUN_NOVALUE"7      ! If the function is a nooptimize function, say soe!      IF (NO_OPTIMIZE EQ "Y") THENc/                 PRINT "    $DTR$FUN_NOOPTIMIZE"e*      ! Do the edit-string and query-header#      IF (EDIT_STR NOT MISSING) THENe.          PRINT "    $DTR$FUN_EDIT_STRING ^\"||                 EDIT_STR||"\"e      IF (HDR NOT MISSING) THEN7          PRINT "    $DTR$FUN_HEADER  HDR = <"||HDR||">"a&      ! OK, now for the input arguments      FOR A IN IN_ARGSa           CHOICE'             (IN_ARG_TYPE = "TEXT") THENc5                PRINT "    $DTR$FUN_IN_ARG  TYPE ="|||o1                (IN_ARG_TYPE VIA FUN_TYPE_TABLE)||O*                (IF (ALL_LEN EQ 0) THEN " "1                      ELSE ",ALL_LEN = "|ALL_LEN)|b                (CHOICE#                   (ORDER NE 0) THEN 2                                 ", ORDER = "|ORDER'                   (OUT_PUT EQ "Y") THEN_2                                 ", OUT_PUT = TRUE"                           ELSE:                              ";;; illegal OUTPUT or ORDER"                  END_CHOICE)(             (IN_ARG_TYPE = "VALUE") THEN5                PRINT "    $DTR$FUN_IN_ARG  TYPE ="||| 1                (IN_ARG_TYPE VIA FUN_TYPE_TABLE)||w(                ", DTYPE = DSC$K_DTYPE_"|                IN_ARG_DTYPE VIA :                         DTYPE_VALUE_TO_NAME||", ORDER = "|                         ORDER '             (IN_ARG_TYPE = "NULL") THENn5                PRINT "    $DTR$FUN_IN_ARG  TYPE ="|||	/                (IN_ARG_TYPE VIA FUN_TYPE_TABLE)r.             (IN_ARG_TYPE = "REF", "DESC") THEN5                PRINT "    $DTR$FUN_IN_ARG  TYPE ="|||I1                (IN_ARG_TYPE VIA FUN_TYPE_TABLE)||e(                ", DTYPE = DSC$K_DTYPE_"|                IN_ARG_DTYPE VIAo-                         DTYPE_VALUE_TO_NAME||(                (CHOICE1                   (ORDER NE 0) THEN ", ORDER = "|D!                             ORDERU'                   (OUT_PUT EQ "Y") THENd1                                ", OUT_PUT = TRUE"l2                 ELSE ";;; Illegal OUTPUT or ORDER"                END_CHOICE)1               ELSE PRINT ";;; Illegal input type"y           END_CHOICE#      PRINT "$DTR$FUN_END_DEF", SKIPa ENDx
 END-PROCEDUREe  " DEFINE PROCEDURE MAKE_COMMAND_FILE    ON CHECK.COM"    BEGIN    PRINT "$MAC/LIS DTRFND"5    PRINT "$COPY DTRFND.MAR, DTRFND.LIS, DTRFND.OBJ -"u)    PRINT "     SCHICK$DISK:[DTRLIB]*/LOG"e<    PRINT "$LIBR/LOG/REP SCHICK$DISK:[SCHICK.DTRLIB]DTRFUN -"*    PRINT "     SCHICK$DISK:[DTRLIB]DTRFND"    END
 END-PROCEDUREr        8 Appendix III - WL$x Function Definitions from DTRFND.MAR  O The following was extracted from the file DTRFND.MAR.  It provides the precise r= definition for each of the site-specific UDF discussed above.   7 ; WL$CHAR - convert an ASCII Code to an ASCII Character  ; " ; output is a one character string ;o& ; input is an unsigned byte ASCII code  ! $DTR$FUN_DEF WL$CHAR, LIB$CHAR, 2E)     $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUS 6     $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 = 1D $DTR$FUN_END_DEF  E ; WL$DAY - returns the number of days since the base date 17-Nov-1858D ;R= ; output is a longword integer cont. the days since base dateT ;S! ; input is a binary quadword datee   $DTR$FUN_DEF WL$DAY, LIB$DAY, 2F)     $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUSt&     $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  D ; WL$DAY_OF_WEEK - returns a numeric day of the week for a date/time ;r6 ; output is an unsigned longword value between 1 and 7 ; input is a 64-bit date/timed ;T  / $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, C+     	 DTYPE = DSC$K_DTYPE_L, OUT_PUT = TRUE) $DTR$FUN_END_DEF   ; WL$DELETE_FILE - Delet a fileo ;U ; No output  ; Input is a filename to deleteG  / $DTR$FUN_DEF WL$DELETE_FILE, LIB$DELETE_FILE, 1 )     $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUSI     $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  N ; WL$DELETE_LOGICAL - deletes a supervisor-mode logical from a specified table ;  ; no output : ; argument 1 is a char. string containing the logical name7 ; arg. 2 is a char. string cont. the logical name table   5 $DTR$FUN_DEF WL$DELETE_LOGICAL, LIB$DELETE_LOGICAL, 2C)     $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUSG     $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 fileN ;U ; No output * ; input is a filename passed by descriptor    $DTR$FUN_DEF WL$EDT, EDT$EDIT, 1)     $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUSn     $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.0 ; arg. 1 is a char. string cont. the symbol name ;R  - $DTR$FUN_DEF WL$GET_SYMBOL, LIB$GET_SYMBOL, 2R)     $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUSI(     $DTR$FUN_IN_ARG  TYPE = FUN$K_DESC, &     	 DTYPE = DSC$K_DTYPE_T, ORDER = 16     $DTR$FUN_IN_ARG  TYPE = FUN$K_TEXT, OUT_PUT = TRUE $DTR$FUN_END_DEF  I ; WL$OCTAL - convert an unsigned integer longword to an octal char. strg.T ; : ; output is a character string representing an octal value; ; input is an unsigned integer longword passed by referenceG ;N  & $DTR$FUN_DEF WL$OCTAL, OTS$CVT_L_TO, 2)     $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUSO      $DTR$FUN_EDIT_STRING ^\X(8)\'     $DTR$FUN_IN_ARG  TYPE = FUN$K_REF, A&     	 DTYPE = DSC$K_DTYPE_L, ORDER = 1'     $DTR$FUN_IN_ARG  TYPE = FUN$K_TEXT,l!     	 ALL_LEN = 8, OUT_PUT = TRUE  $DTR$FUN_END_DEF  = ; WL$POWER - computes the value of a number raised to a power. ;s ; output is a real numberI ; argument 1 is the base ; argument 2 is a real exponentK  # $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 generatorY ;A' ; output is an F-floating random numberS' ; input is an unsigned integer longwordp  % $DTR$FUN_DEF WL$RANDOM, MTH$RANDOM, 1 *     $DTR$FUN_OUT_ARG  TYPE = FUN$K_VALUE,      	 DTYPE = DSC$K_DTYPE_FR'     $DTR$FUN_IN_ARG  TYPE = FUN$K_REF, V&     	 DTYPE = DSC$K_DTYPE_L, ORDER = 1 $DTR$FUN_END_DEF  ! ; WL$RENAME_FILE - Renames a file  ;$ ; No outputD8 ; Argument 1 is the source filename passed by descriptor5 ; Argument 2 is the new filename passed by descriptor   / $DTR$FUN_DEF WL$RENAME_FILE, LIB$RENAME_FILE, 2t)     $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUSs     $DTR$FUN_NOVALUE     $DTR$FUN_NOOPTIMIZED(     $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  M ; WL$SET_LOGICAL - (re)defines a supervisor mode logical in a specified tableM ;  ; no outputu6 ; arg. 1 is a char. string containing the logical name8 ; arg. 2 is a char string containing the value to assign6 ; 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  1 ; WL$SET_SYMBOL - define or redefine a CLI symbol_ ;C ; no output 9 ; arg. 1 is a string descriptor containing the CLI symbole: ; 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_STATUSP     $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  D ; WL$WAIT - places current process in hibernation for specified time ;u ; no outputo= ; input is the number of seconds to wait - F-floating by ref.   ! $DTR$FUN_DEF WL$WAIT, LIB$WAIT, 1O)     $DTR$FUN_OUT_ARG  TYPE = FUN$K_STATUSu     $DTR$FUN_NOVALUE'     $DTR$FUN_IN_ARG  TYPE = FUN$K_REF, T&     	 DTYPE = DSC$K_DTYPE_F, ORDER = 1 $DTR$FUN_END_DEF    * Appendix IV - Database for Valid Datatypes  1 DEFINE TABLE DTYPE_NAME_TO_VALUE FROM DTYPS USING 
 	NAME : VALUEt	 END_TABLEg  1 DEFINE TABLE DTYPE_VALUE_TO_NAME FROM DTYPS USING 
 	VALUE : NAME_	 END_TABLET  % DEFINE DOMAIN DTYPS USING DTYP_REC ONF 	SCHICK$DISK:[DTRLIB]DTYPE.DAT;    DEFINE RECORD DTYP_REC	 01 DTYPE.| 	03 VALUE	PIC 99.( 	03 NAME 	PIC X(4).N 	03 DESC 	PIC X(60). ;   ' Value   Name                Description     00	 Z      unspecified '  01	 V      bit - an aligned bit string 3  02	 BU      byte logical - 8-bit unsigned quantityT4  03	 WU      word logical - 16-bit unsigned quantity8  04	 LU      longword logical - 32-bit unsigned quantity8  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 C  08	 L      longword integer - 32-bit signed 2's-complement integer C  09	 Q      quadword integer - 64-bit signed 2's-complement integer <  10	 F      F-floating - 32-bit single precision real number0  11	 D      D-floating - 64-bit double precisionE  12	 FC      F-floating complex - low address real, high address imag H  13	 DC      D-floating complex- Pair of D-float. (low real, high imag.)/  14	 T      char. coded text - string data typeR%  15	 NU      numeric string, unsignedT/  16	 NL      numeric string, left separate signP3  17	 NLO      numeric string, left overpunched sign 0  18	 NR      numeric string, right separate sign4  19	 NRO      numeric string, right overpunched sign'  20	 NZ      numeric string, zoned sign !  21	 P      packed decimal stringT%  22	 ZI      sequence of instructions "  23	 ZEM      procedure entry mask<  24	 DSC      descriptor - levels of descriptors are allowed9  25	 OU      octaword logical - 128-bit unsigned quantityyD  26	 O      octaword integer - 128-bit signed 2's complement integer7  27	 G      G-floating - 64-bit double precision number ;  28	 H      H-floating - 128-bit quad precision real numberTH  29	 GC      G-floating complex- Pair of G-float. (low real, high imag.)H  30	 HC      H-floating complex- Pair of H-float. (low real, high imag.)I  31	 CIT      COBOL Interm. Temp. - 18-digit norm. dec. fract. 2-dig exp. #  32	 BPV      bound procedure valuef  33	 BLV      bound label valueoB  34	 VU      bit unaligned - data are 0 to 2**16-1 contiguous bits$  35	 ADT      absolute date and time)  37	 VT      varying character-coded textA    - Appendix V - Table of Function/Argument Types    DEFINE TABLE FUN_TYPE_TABLEt 	"STATUS"	:	"FUN$K_STATUS" 	"INPUT"		:	"FUN$K_INPUT"R 	"VALUE"		:	"FUN$K_VALUE"  	"REF" 		:	"FUN$K_REF" 	"DESC"		:	"FUN$K_DESC"  	"TEXT"		:	"FUN$K_TEXT"  	"NULL"		:	"FUN$K_NULL"E	 END_TABLEF  