1 Functions A DEC DATATRIEVE function is a word you define and add to the DEC DATATRIEVE language. By adding functions, you extend the capability of DEC DATATRIEVE to efficiently perform specific tasks. To learn how to define functions for DEC DATATRIEVE, see the DEC DATATRIEVE Guide to Programming and Customizing. The DEC DATATRIEVE installation kit provides some functions. You can use them to form value expressions or to set parameters for a process. These functions can be modified by users at your site. If they do not work as indicated in the examples, consult the person at your site responsible for DEC DATATRIEVE for a list of the functions currently available. DEC DATATRIEVE functions have the following format: function-name [ (value-expression [,...] ) ] 2 FN$ABS Calculates the absolute value of input. 3 Input A signed decimal number. 3 Output An unsigned decimal number of type G-floating. 3 Example DTR> PRINT FN$ABS (-128) FN$ABS 1.2800E+02 DTR> 2 FN$ATAN Calculates the arctangent of input. 3 Input A signed decimal number (radians). 3 Output A signed decimal number of type G-floating. 3 Example DTR> PRINT 4 * (FN$ATAN (1)) 3.1416E+00 DTR> 2 FN$BIT_AND Returns the bitwise AND of two longwords. 3 Input This function takes two parameters as input. Two longwords, separated by a comma and enclosed in parentheses. 3 Output An integer number. 3 Example DTR> DECLARE OP1 PIC 99999999 LONG .; DTR> DECLARE OP2 PIC 99999999 LONG .; DTR> OP1 = 128+64+32 ; DTR> OP2 = 32+8+4+1 ; DTR> PRINT FN$BIT_AND(OP1,OP2); FN$BIT AND 32 DTR> 2 FN$BIT_EXTRACT Returns the bit field within a longword. 3 Input This function takes three parameters: the longword, the starting bit in the longword, and the length of the bit field in the longword. The three must be separated by a comma and enclosed in parentheses. 3 Output An integer number. 3 Example DTR> DECLARE SOURCE PIC 99999999 LONG .; DTR> DECLARE I LONG .; DTR> SOURCE = 7 ; DTR> I = 0; DTR> REPEAT 6 CON> BEGIN CON> PRINT FN$BIT_EXTRACT(SOURCE,I,1); CON> I = I+1; CON> END FN$BIT EXTRACT 1 1 1 0 0 0 DTR> 2 FN$BIT_NOT Returns the bitwise complement of a longword. 3 Input A longword. 3 Output An integer number. 3 Example DTR> DECLARE OP1 PIC 99999999 LONG .; DTR> OP1 = 128+64+32 ; DTR> PRINT FN$BIT_NOT(OP1); FN$BIT NOT -225 DTR> 2 FN$BIT_OR Returns the bitwise OR of two longwords. 3 Input This function takes two arguments: two longwords. The two must be separated by a comma and enclosed in parentheses. 3 Output An integer number. 3 Example DTR> DECLARE OP1 PIC 99999999 LONG .; DTR> DECLARE OP2 PIC 99999999 LONG .; DTR> OP1 = 128+64+32 ; DTR> OP2 = 32+8+4+1 ; DTR> PRINT FN$BIT_OR(OP1,OP2); FN$BIT OR 237 DTR> 2 FN$BIT_XOR Returns the bitwise exclusive OR of two longwords. 3 Input This function takes two arguments: two longwords. The two must be separated by a comma and enclosed in parentheses. 3 Output An integer number. 3 Example DTR> DECLARE OP1 PIC 99999999 LONG .; DTR> DECLARE OP2 PIC 99999999 LONG .; DTR> OP1 = 128+64+32 ; DTR> OP2 = 32+8+4+1 ; DTR> PRINT FN$BIT_XOR(OP1,OP2); FN$BIT XOR 205 DTR> 2 FN$COMMAND_KEYBOARD Returns the current value of the COMMAND_KEYBOARD field in the data access block (DAB). COMMAND_KEYBOARD is the keyboard used for command input. This function allows you to add other functions that access the features of the Screen Management Guidelines (SMG) of the Screen Management facility. This function is not available in a DECwindows Motif environment. 3 Input None. 3 Output A longword value of the COMMAND_KEYBOARD field. 3 Example DTR> DECLARE COMMAND_KEYBOARD LONG. DTR> COMMAND_KEYBOARD = FN$COMMAND_KEYBOARD 2 FN$COS Calculates the cosine of input. 3 Input A signed decimal number (radians). 3 Output A signed decimal number of type G-floating. 3 Example DTR> PRINT FN$COS (3.14159) using s9.999 FN$COS -1.000 DTR> 2 FN$CREATE_LOG Assigns a user mode logical name within the process logical name table as a synonym for a physical name. The logical name is deleted when you exit from DEC DATATRIEVE. 3 Input This function takes two parameters as input. The first is a logical name character string; the second is a physical name character string. Each string must be in quotation marks (unless you use variables previously declared). The two strings must be separated by a comma and enclosed in parentheses. 3 Output None. 3 Example DTR> FN$CREATE_LOG ("HANK", "DB0:[MORRISON.RW]LOG.RNO") DTR> 3 Usage_Note Logical names are defined at execution time (runtime) and not during the compilation phase. If you define a logical name within a statement, the logical name is not translated during the compilation phase, consequently it is executed without being defined, which will lead to an error. DTR> READY YACHTS DTR> BEGIN [Looking for statement] CON> FN$CREATE_LOG("FORM_DIR","DTR$LIBRARY:FORMS"); CON> FOR X IN YACHTS [Looking for statement] CON> WITH_FORM YACHT IN FORM_DIR [Looking for SEND or RECEIVE statement] CON> SEND FROM X TO BOAT; CON> END Error opening DECforms form file DISK:[DALFY]FORM_DIR.EXE; . 2 FN$DATE Converts a date string to a 64-bit data value. 3 Input A complete date string formatted as "dd-MMM-yyyy hh:mm:ss.cc". Unpredictable results may occur if you supply only a portion of a date string, such as "21-MAR-1990". The month must be specified in uppercase. 3 Output A date data value formatted as "dd-MMM-yyyy hh:mm:ss.cc". 3 Example DTR> DECLARE X USAGE DATE EDIT_STRING X(23). DTR> X = FN$DATE("30-AUG-1990 15:20:31.45") DTR> PRINT X X 30-Aug-1990 15:20:31.45 DTR> DTR> DECLARE Y USAGE DATE EDIT_STRING X(23). DTR> DECLARE Z PIC X(23). DTR> Z = "20-FEB-1990 14:54:29.83" DTR> Y = FN$DATE (Z) DTR> PRINT Y Y 20-Feb-1990 14:54:29.83 DTR> 2 FN$DAY Extracts the day part of input (dd in dd-MMM-yyyy hh:mm:ss.cc). 3 Input A date. 3 Output An unsigned integer from 1 to 31. 3 Example DTR> DECLARE CAL USAGE DATE EDIT_STRING X(23). DTR> CAL = "NOW"; PRINT CAL CAL 1-Feb-1990 08:51:11.55 DTR> PRINT FN$DAY (CAL) FN$DAY 1 DTR> 2 FN$DBKEY_LENGTH Returns the byte length of dbkeys for the relational domain or table specified as argument. 3 Input A string expression providing the name of the domain or table. The string expression must be placed inside quotation marks, and enclosed in parentheses. 3 Output The byte length of the dbkey. An error message is returned if the domain is unknown, or if the domain is not a relational one. 3 Example It is useful for example as an argument to the FN$STR_EXTRACT function, which extracts a substring from the input character string using a default edit string of 30 characters. In the following example FN$STR_EXTRACT extracts a substring from the 100-character long field D. D is the variable, 1 is the starting character, and FN$DBKEY_LENGTH is the length of the desired substring: DTR> DECLARE D PIC X(100).; DTR> VAR = 1234567890 DTR> PRINT FN$DBKEY_LENGTH("NULLS_1") FN$DBKEY LENGTH 8 DTR> PRINT FN$STR_EXTRACT (D,1,FN$DBKEY_LENGTH("NULLS_1")) FN$STR EXTRACT 12345678 3 Usage_Note This function has been implemented for Oracle Rdb dbkeys only. 2 FN$DCL Allows you to spawn directly from your main DEC DATATRIEVE process to execute a specified DCL command. 3 Input Type FN$DCL at the DEC DATATRIEVE prompt. On the same line, specify the DCL command argument you want to spawn to, such as the DCL print command. The DCL command argument can be any DCL command and must be placed inside quotation marks (unless you use variables previously declared), and enclosed in parentheses. 3 Output Your DEC DATATRIEVE process is suspended and the terminal is attached to the subprocess. The DCL command is executed. 3 Examples DTR> FN$DCL ("PRINT REPORTACCOUNTS.RPT") Job REPORTACCOUNTS (queue SYSTEMPRINT$QUEUE, entry 148) started on PRINTER$LPA0 DTR> In the above example the message appears indicating that the job has been added to the print queue. After the command has completed or you have exited from the program initiated by the command, you see the DTR> prompt. This shows that control has been returned to the original process in DEC DATATRIEVE. The following example shows how you can use variables with FN$DCL: DTR> DECLARE ALP PIC X(30). DTR> ALP = "DIR/COL=1" DTR> FN$DCL (ALP) Directory MY$DISK:[DALFY] TEST.OBJ;1 ZTEST.FOR;3 Note that the FN$DCL process inherits attributes from the caller (that is, the main DEC DATATRIEVE process from which it spawned). Refer to the OpenVMS documentation on OpenVMS Run-Time Library routines for more information. 2 FN$DEFINE_KEY Takes a key definition in DCL DEFINE/KEY syntax, then creates the defined key in DEC DATATRIEVE. This function is not available in a DECwindows Motif environment. 3 Input A quoted string containing the key definition in DCL DEFINE/KEY command syntax. You must use single quotation marks for the outer pair of quotation marks. The inner pair of quotation marks must be double. 3 Output None. 3 Example DTR> FN$KEYPAD_MODE ("APPLICATION") DTR> FN$DEFINE_KEY ('DEFINE/KEY/ECHO/NOTERMINATE KP7 "FIND" ') 3 Usage_Note The previous example will not work unless the device is set to APPLICATION. DEC DATATRIEVE ignores the the terminal characteristics of your device, for this reason you must execute the FN$KEYPAD_MODE function before executing the FN$DEFINE_KEY function. 2 FN$DELETE_KEY Deletes a key definition currently in effect. This function is not available in a DECwindows Motif environment. 3 Input This function takes two parameters. o The first parameter is the name of the key whose definition you want to delete. o The second parameter is the state string. You must specify the state name DEFAULT when there is no alternate state. Each parameter must be in matching quotation marks. The two parameters must be separated by a comma and enclosed in parentheses. 3 Output None. 3 Example DTR> FN$DELETE_KEY ("KP0","DEFAULT") DTR> FN$DELETE_KEY ("KP0","GOLD") 2 FN$DELETE_LOG Deletes the assignment of a logical name. 3 Input The logical name you want to delete. 3 Output None. 3 Example DTR> FN$DELETE_LOG ("HANK") DTR> PRINT FN$TRANS_LOG ("HANK") USING X(30) FN$TRANS LOG DTR> 2 FN$DELETE_LOGICAL Deletes a supervisor-mode process logical name. 3 Input This function takes two parameters as input. The first is the logical name to be deleted; the second is the name of the table from which the logical name is to be deleted. The two must be separated by a comma and enclosed in parentheses. 3 Output None. 3 Example DTR> FN$DELETE_LOGICAL("MY_LOGICAL", "LNM$PROCESS"); DTR> FN$DCL("SHOW LOGICAL MY_LOGICAL"); %SHOW-S-NOTRAN, no translation for logical name MY_LOGICAL DTR> 2 FN$DELETE_SYMBOL Deletes a CLI symbol. 3 Input The name of the symbol to be deleted. 3 Output None. 3 Example DTR> FN$DELETE_SYMBOL("MY_SYMBOL"); DTR> FN$DCL("SHOW SYMBOL MY_SYMBOL") ; %DCL-W-UNDSYM, undefined symbol - check validity and spelling DTR> 2 FN$DISABLE_DECFORMS Disables DECforms from managing forms. 3 Input None. The function has no arguments. 3 Output None. 3 Example DTR> SET DICTIONARY CDD$TOP.DTR$LIB.FORMS ; DTR> YACHTS uses an FMS/TDMS form, YACHTS_F uses a DECforms form DTR> SHOW YACHTS, YACHTS_F DOMAIN YACHTS USING CDD$TOP.DTR$LIB.DEMO.YACHT ON YACHT.DAT FORM IS YACHT IN DTR$LIBRARY:FORMS ; DOMAIN YACHTS_F USING CDD$TOP.DTR$LIB.DEMO.YACHT ON YACHT.DAT FORM IS YACHTS IN DTR$LIBRARY:YACHT.FORM ; DTR> FN$DISABLE_DECFORMS ; DTR> READY YACHTS ; DTR> SHOW FORMS ; Loaded forms: Form YACHT in SYS$COMMON:[DTR]FORMS.FLB; ( FMS ) DTR> FN$ENABLE_DECFORMS ; DTR> READY YACHTS_F ; DTR> SHOW FORMS ; Loaded forms: Form YACHTS in SYS$COMMON:[DTR]YACHT.FORM; ( DECforms ) Form YACHT in SYS$COMMON:[DTR]FORMS.FLB; ( FMS ) 2 FN$ENABLE_DECFORMS Enables DECforms to manage forms. 3 Input None. The function has no arguments. 3 Output None. 3 Example See the example for function FN$DISABLE_DECFORMS. 2 FN$EXP Calculates the value of e to a specified power. 3 Input A signed decimal number. 3 Output A signed decimal number of type G-floating. 3 Example DTR> PRINT FN$EXP (2) FN$EXP 7.3891E+00 DTR> 2 FN$FLOOR Truncates the decimal part of positive input or rounds negative input. 3 Input A signed decimal number. 3 Output A signed decimal number of type G-floating. 3 Example DTR> PRINT FN$FLOOR (59.99) FN$FLOOR 5.9000E+01 DTR> PRINT FN$FLOOR (-59.99) FN$FLOOR -6.0000E+01 2 FN$FORMAT_DBKEY Returns a character string containing the dbkey of the readied relational domain, table, or view. 3 Input A string containing the dbkey in its binary format. 3 Output The character string of the dbkey. This function assumes that the dbkey is internally structured as an array of elementary dbkeys and that each elementary dbkey is 8 bytes long. 3 Example In the following example the variable VAR prints the dbkey of each record in the relational view C in their string format. The length of the dbkeys in this view is 16 bytes (8 bytes by the number of tables in the view). DTR> DECLARE VAR PIC X(80).; DTR> FOR C BEGIN CON> VAR = FN$LASTREC_DBKEY("C"); CON> PRINT - CON> FN$FORMAT_DBKEY(FN$STR_EXTRACT(VAR,1,FN$DBKEY_LENGTH("C"))) CON> END; FN$FORMAT DBKEY 39:512:0 40:518:0 39:512:1 40:518:0 39:512:2 40:518:0 39:512:3 40:518:0 DTR> 3 Usage_Note This function has been implemented for Oracle Rdb dbkeys only. 2 FN$GET_SYMBOL Returns the value of a DCL symbol. 3 Input A character string that represents the symbol name. 3 Output The value of a DCL symbol. 3 Example DTR> PRINT FN$GET_SYMBOL("DTR$INVOKE") USING X(45) FN$GET SYMBOL RUN DTR$DISK:[DTR.TESTS]DTRV4.EXE DTR> 2 FN$HEX Calculates the hexadecimal equivalent of input. 3 Input A signed integer no larger than (2 ** 31) -1 (the maximum value that can be stored in a signed longword). 3 Output A hexadecimal character string. 3 Example DTR> PRINT FN$HEX(183) FN$HEX B7 DTR> 2 FN$HEX_TO_DEC Calculates the integer equivalent of a hexadecimal value. 3 Input A string expression containing the hexadecimal character string. The string expression must be placed inside quotation marks, and enclosed in parentheses. 3 Output A longword integer equivalent to the hexadecimal value. 3 Examples The following example returns the integer equivalent to the hexadecimal value FF. DTR> PRINT FN$HEX_TO_DEC ("FF") FN$HEX TO DEC 255 DTR> The following example shows how the FN$HEX_TO_DEC function can be used to calculate the numeric value of the address of the first free page at the end of the program region of the process. DTR> PRINT FN$HEX_TO_DEC (FN$PROCESS_INFO ("FREP0VA" VIA - CON> JPI_CODES)) FN$HEX TO DEC 7991296 DTR> 2 FN$HOUR Extracts the hour part of input (hh in dd-MMM-yyyy hh:mm:ss.cc). 3 Input A date. 3 Output An unsigned integer from 1 to 24. 3 Example DTR> DECLARE CAL USAGE DATE EDIT_STRING X(23). DTR> CAL = "NOW"; PRINT CAL CAL 1-Feb-1990 08:51:11.55 DTR> PRINT FN$HOUR (CAL) FN$HOUR 8 DTR> 2 FN$HUNDREDTH Extracts hundredth-of-a-second part of input (cc in dd-MMM-yyyy hh:mm:ss.cc). 3 Input A date. 3 Output An unsigned integer from 0 to 99. 3 Example DTR> DECLARE CAL USAGE DATE EDIT_STRING X(23). DTR> CAL = "NOW"; PRINT CAL CAL 1-Feb-1990 08:51:11.55 DTR> PRINT FN$HUNDREDTH (CAL) FN$HUNDREDTH 55 DTR> 2 FN$ICHAR It converts the first character of a string to an 8-bit ASCII integer extended to a longword. 3 Input The string expression. 3 Output The 8-bit ASCII integer. 3 Example DTR> DECLARE VAR PIC X(80) .; DTR> DECLARE CH PIC X . ; DTR> DECLARE I INTEGER .; DTR> VAR = "GRZ-ALE" ; DTR> i = 1 ; DTR> REPEAT FN$STR_LENGTH( VAR || "" ) CON> BEGIN CON> CH = FN$STR_EXTRACT(VAR, i, 1 ); CON> PRINT CH("CHARACTER"), FN$ICHAR(CH)("CODE"); CON> I = I+1 ; CON> END ; CHARACTER CODE G 71 R 82 Z 90 - 45 A 65 L 76 E 69 DTR> 2 FN$INIT_TIMER Initializes a timer and counter. 3 Input None. 3 Output None. 3 Example DTR> SHOW TIME_READY PROCEDURE TIME_READY FN$INIT_TIMER READY OWNERS FN$SHOW_TIMER END_PROCEDURE DTR> :TIME_READY ELAPSED: 0 00:00:04.24 CPU: 0:00:00.61 BUFIO: 1 DIRIO: 42 FAULTS: 64 DTR> 2 FN$JULIAN Calculates the Julian date of input. (A Julian date is based on days of the year being numbered beginning with January 1st. The Julian date of January 6th is 6. The Julian date of February 2nd is 33, and so on.) 3 Input A date. 3 Output An unsigned integer from 1 to 366. (There are 366 days in a leap year.) 3 Example DTR> DECLARE CAL USAGE DATE EDIT_STRING X(23). DTR> CAL = "NOW"; PRINT CAL CAL 1-Feb-1990 08:51:11.55 DTR> PRINT FN$JULIAN (CAL) FN$JULIAN 32 DTR> 2 FN$KEYPAD_MODE Lets you specify the terminal mode from within DEC DATATRIEVE. This function duplicates the ability of the SET [NO] APPLICATION_ KEYPAD command. The function form of FN$KEYPAD_MODE, however, allows you to change the keypad mode inside compound statements. This function is not available in a DECwindows Motif environment. 3 Input You must specify one of two parameters: o APPLICATION specifies application keypad mode. o NUMERIC specifies numeric keypad mode. This function is not case sensitive; you can type APPLICATION or NUMERIC in either uppercase or lowercase. The words must be in either single or double quotation marks, and the spelling must be exact. 3 Output None. 3 Example DTR> FN$KEYPAD_MODE ("APPLICATION") DTR> FN$KEYPAD_MODE ("NUMERIC") 2 FN$KEYTABLE_ID Returns the value of the KEYTABLE_ID field currently in the data access block (DAB). FN$KEYTABLE_ID allows you to add other functions that access other capabilities of the Screen Management Guidelines (SMG) of the Screen Management facility. This function is not available in a DECwindows Motif environment. 3 Input None. 3 Output A longword value of the KEYTABLE_ID field. 3 Example DTR> DECLARE KEYTABLE LONG. DTR> KEYTABLE = FN$KEYTABLE_ID 2 FN$LASTREC_DBKEY Returns the dbkey of the last record read in a currently readied relational domain or table. 3 Input A string expression providing the name of the domain or table. 3 Output The record dbkey as a byte string. 3 Example In the following example the FN$FORMAT_DBKEY function returns the dbkey of the last record read from CITY_CODE_TABLE in its string format. DTR> PRINT FN$FORMAT_DBKEY(FN$LASTREC_DBKEY("CITY_CODE_TABLE")) FN$FORMAT DBKEY 11:149:26 DTR> 2 FN$LN Calculates the natural log of input. 3 Input A signed number. 3 Output A signed number of type G-floating. 3 Example DTR> PRINT FN$LN (36) FN$LN 3.5835E+00 DTR> 2 FN$LOAD_KEYDEFS Lets you define multiple keypad keys from a file containing DCL DEFINE/KEY commands. This way you do not have to make multiple calls to the FN$DEFINE_KEY function. This function is not available in a DECwindows Motif environment. 3 Input A quoted string with a DCL file specification indicating the file containing the DCL DEFINE/KEY commands. 3 Output None. 3 Example DTR> FN$LOAD_KEYDEFS ("APPL1.KEYS") 2 FN$LOG10 Calculates the base 10 log of input. 3 Input A signed number. 3 Output A signed number of type G-floating. 3 Example DTR> PRINT FN$LOG10 (36) FN$LOG10 1.5563E+00 DTR> 2 FN$MINUTE Extracts the minute part of input (mm in dd-MMM-yyyy hh:mm:ss.cc). 3 Input A date. 3 Output An unsigned integer from 0 to 59. 3 Example DTR> DECLARE CAL USAGE DATE EDIT_STRING X(23). DTR> CAL = "NOW"; PRINT CAL CAL 1-Feb-1990 08:51:11.55 DTR> PRINT FN$MINUTE (CAL) FN$MINUTE 51 DTR> 2 FN$MOD Calculates the value of input according to a specified modulus, using double precision floating values. 3 Input This function takes two parameters: a signed number and a modulus. The two must be separated by a comma and enclosed in parentheses. 3 Output A real number of type G-floating. 3 Example DTR> PRINT FN$MOD (31,7) FN$MOD 3.0000E+00 DTR> 2 FN$MODI Calculates the value of input according to a specified modulus, using integer values. 3 Input This function takes two parameters: a signed number and a modulus. The two must be separated by a comma and enclosed in parentheses. 3 Output An integer number. 3 Example DTR> PRINT FN$MODI(13,4); FN$MODI 1 DTR> PRINT FN$MODI(-13,4); FN$MODI -1 DTR> 2 FN$MONTH Extracts the month part of input (MMM in dd-MMM-yyyy hh:mm:ss.cc). 3 Input A date. 3 Output An unsigned integer from 1 to 12. 3 Example DTR> DECLARE CAL USAGE DATE EDIT_STRING X(23). DTR> CAL = "NOW"; PRINT CAL CAL 1-Feb-1990 08:51:11.55 DTR> PRINT FN$MONTH (CAL) FN$MONTH 2 DTR> 2 FN$NINT Calculates the integer nearest to input. 3 Input A signed number. 3 Output A signed longword. 3 Example DTR> PRINT FN$NINT (59.99) FN$NINT 60 DTR> 2 FN$OPENS_LEFT Calculates the number of additional files you can open. 3 Input None. 3 Output An signed longword. 3 Example DTR> PRINT FN$OPENS_LEFT FN$OPENS LEFT 3 DTR> 2 FN$PROCESS_INFO Returns information on the current process. 3 Input An integer value specifying the item of information that the FN$PROCESS_INFO function is to return; the integer value is one of the values used by the $GETJPI system service. DEC DATATRIEVE supplies a table associating symbolic strings to values of the $GETJPI system service. The table is called JPI_ CODES, located in CDD$TOP.DTR$LIB. If you use the JPI_CODES table with this function, the syntax is: FN$PROCESS_INFO ("symbolic-string" VIA CDD$TOP.DTR$LIB.JPI_CODES) Where symbolic-string is a text string defined in JPI_CODES. The text string must be placed inside quotation marks. For a complete description of the item codes, see the $GETJPI service documented in the OpenVMS System Services Reference Manual. 3 Output A text string containing the information requested by the item- code. 3 Examples The following examples shows how the FN$PROCESS_INFO function returns information about the username; the first example uses an integer value, the second example uses the JPI_CODES table. DTR> PRINT FN$PROCESS_INFO (514) FN$PROCESS INFO DALFY DTR> DTR> PRINT - CON> FN$PROCESS_INFO ("USERNAME" VIA CDD$TOP.DTR$LIB.JPI_CODES) FN$PROCESS INFO DALFY DTR> 2 FN$PROMPT_KEYBOARD Returns the value of the PROMPT_KEYBOARD field currently in the data access block (DAB). PROMPT_KEYBOARD is the keyboard ID used for prompting. FN$PROMPT_KEYBOARD allows you to add other functions that access other capabilities of the Screen Management Guidelines (SMG) of the Screen Management facility. This function is not available in a DECwindows Motif environment. 3 Input None. 3 Output A longword value of the PROMPT_KEYBOARD field. 3 Example DTR> DECLARE PROMPT_KEYBOARD LONG. DTR> PROMPT_KEYBOARD = FN$PROMPT_KEYBOARD 2 FN$SECOND Extracts the second part of input (ss in dd-MMM-yyyy hh:mm:ss.cc). 3 Input A date. 3 Output An unsigned integer from 0 to 59. 3 Example DTR> DECLARE CAL USAGE DATE EDIT_STRING X(23). DTR> CAL = "NOW"; PRINT CAL CAL 1-Feb-1990 08:51:11.55 DTR> PRINT FN$SECOND (CAL) FN$SECOND 11 DTR> 2 FN$SETDEF Allows you to change the default disk directory for the process. 3 Input A string expression containing the new default disk directory. The string expression must be placed inside quotation marks, and enclosed in parentheses. 3 Output None. 3 Example The following example shows how to change the default directory from within your DEC DATATRIEVE process and how to restore the old default directory to its original status before exiting DEC DATATRIEVE. $ SHOW DEFAULT DISK:[SMITH] DTR> DECLARE OLDDIR PIC X(80). DTR> OLDDIR = FN$SHOWDEF DTR> PRINT OLDDIR OLDDIR [SMITH] DTR> FN$SETDEF ("[SMITH.WORK]") DTR> PRINT FN$SHOWDEF FN$SHOWDEF [SMITH.WORK] DTR> . . . DTR> FN$SETDEF (OLDDIR) DTR> PRINT FN$SHOWDEF FN$SHOWDEF [SMITH] DTR> EXIT $ SHOW DEFAULT DISK:[SMITH] $ 2 FN$SETDEFPROT Allows you to change the default file protection for the process. 3 Input A string expression containing the new default file protection specification. The format is the standard OpenVMS format (e.g. "SYSTEM:RWED,OWNER:RWED,GROUP:R,WORLD:R"). The string expression must be placed inside quotation marks, and enclosed in parentheses. 3 Output None. 3 Example The following example shows how to change the default file protection from within your DEC DATATRIEVE process and how to restore the old default file protection to its original status before exiting DEC DATATRIEVE. DTR> PRINT FORMAT FN$SHOWDEFPROT USING X(80) SYSTEM:RWED,OWNER:RWED,GROUP:RWED,WORLD: DTR> DECLARE OLDPROT PIC X(80). DTR> OLDPROT = FN$SHOWDEFPROT DTR> PRINT OLDPROT OLDPROT SYSTEM:RWED,OWNER:RWED,GROUP:RWED,WORLD: DTR> FN$SETDEFPROT ("S:RWED,O:RWED") DTR> PRINT FORMAT FN$SHOWDEFPROT USING X(80) SYSTEM:RWED,OWNER:RWED,GROUP:,WORLD: DTR> DEFINE DOMAIN H USING H_REC ON H.DAT; DTR> DEFINE RECORD H_REC USING DFN> 01 H_REC. DFN> 03 F1 PIC X(7). DFN> 03 F2 PIC X(10). ; DTR> DEFINE FILE FOR H; DTR> FN$DCL ("DIR/PROT *.DAT") Directory DISK:[DALFY.NEWUSER] EMPLOYEES.DAT;1 10-FEB-1993 11:06:03.39 (RWED,RWED,RWED,) FAMILY.DAT;108 25-MAR-1992 21:44:53.30 (RWED,RWED,RWED,) FAMS.DAT;1 6-AUG-1992 15:33:51.24 (RWED,RWED,RWED,) H.DAT;1 24-MAR-1993 09:47:39.31 (RWED,RWED,,) Total of 4 files. DTR> FN$SETDEFPROT (OLDPROT) DTR> PRINT FORMAT FN$SHOWDEFPROT USING X(80) SYSTEM:RWED,OWNER:RWED,GROUP:RWED,WORLD: DTR> EXIT $ SHOW PROTECTION SYSTEM=RWED, OWNER=RWED, GROUP=RWED, WORLD=NO ACCESS $ 2 FN$SET_FORM_TABLE_ADDR Notifies the DATATRIEVE interpreter that the DECforms forms to be used are linked with the application rather than being stored in external files (default case) and provides an address to get them. Alternatively, it can reset the default case. It is relevant only for applications calling the DATATRIEVE API. Syntax: FN$SET_FORM_TABLE_ADDR (form_table_addr, enable_flag). 3 Input This function takes two parameters as input. The first one (form_table_addr) is the address of FORMS$AR_FORM_TABLE, if linked forms are to be used (enable_flag is 1 ). The second one (enable_form) must be 1, if form files are to be ignored and linked forms (via FORMS$AR_FORM_TABLE) are to be used. It must be 0, if form files are to be used (default case). 3 Output None. 3 Example (C code) .... { #pragma nostandard globalref unsigned long FORMS$AR_FORM_TABLE ; #pragma standard unsigned long *ar_form_table_ptr ; char com[80]; ar_form_table_ptr = &FORMS$AR_FORM_TABLE ; /* DECforms Forms linked with the application must be used */ sprintf(com, "FN$SET_FORM_TABLE_ADDR(%1d,%1d)", ar_form_table_ptr, 1 ) ; tdesc.dsc$a_pointer = com ; tdesc.dsc$w_length = strlen(com) ; status = dtr$command(&dab, &tdesc ); } 2 FN$SET_LOGICAL Defines or redefines a supervisor-mode process logical name. 3 Input This function takes three parameters as input. The first is the logical name to be defined or redefined; the second is the value to be given to the logical name; the third is the name of the table in which to create the logical name. 3 Output None. 3 Example DTR> FN$SET_LOGICAL("MY_LOGICAL","ITS_EQUIVALENT","LNM$PROCESS"); DTR> PRINT FN$TRANS_LOG("MY_LOGICAL"); FN$TRANS LOG ITS_EQUIVALENT DTR> 2 FN$SET_SYMBOL Defines or redefines a CLI (Command Language Interpreter) symbol. 3 Input This function takes two parameters as input. The first is the symbol name; the second is the value to be given to the symbol. 3 Output None. 3 Example DTR> FN$SET_SYMBOL("MY_SYMBOL","ITS_VALUE") DTR> PRINT FN$GET_SYMBOL("MY_SYMBOL"); FN$GET SYMBOL ITS_VALUE DTR> 2 FN$SHOW_KEY Displays the definition of a keypad key. This function is not available in a DECwindows Motif environment. 3 Input This function takes two parameters: o The first parameter specifies the keypad key name. o The second parameter is the state string. You must specify the state name DEFAULT when there is no alternate state. Each parameter must be in matching quotation marks. The two quoted parameters must be separated by a comma and enclosed in parentheses. 3 Output The definition of the specified key. 3 Example DTR> FN$SHOW_KEY ("KP7","DEFAULT") KP7 = "SHOW ALL" (echo,terminate,noerase,nolock) 2 FN$SHOW_KEYDEFS Displays the key definitions in all of the states. This function duplicates the ability of the DEC DATATRIEVE SHOW KEYDEFS command. The function form of FN$SHOW_KEYDEFS lets you show all keypad definitions inside compound statements. This function is not available in a DECwindows Motif environment. 3 Input None. 3 Output The definitions of all the defined keys. 3 Example DTR> FN$SHOW_KEYDEFS BLUE state keypad definitions: KP1 = "SHOW KEYDEFS" (noecho,terminate,noerase,nolock) DEFAULT state keypad definitions: PF1 = " " (echo,noterminate,noerase,nolock,set_state=GOLD) PF4 = " " (echo,noterminate,noerase,nolock,set_state=BLUE) KP0 = "SHOW KEYDEFS" (echo,terminate,noerase,nolock) KP1 = "READY " (echo,noterminate,noerase,nolock) KP7 = "SHOW ALL" (echo,terminate,noerase,nolock) KP8 = "SHOW DOMAINS" (echo,terminate,noerase,nolock) KP9 = "SHOW RECORDS" (echo,terminate,noerase,nolock) ENTER = "SET APPLICATION_KEYPAD" (echo,terminate,noerase,nolock) GOLD state keypad definitions: ENTER = "SET NO APPLICATION_KEYPAD" (echo,terminate,noerase,nolock) KP1 = "SHOW KEYDEFS" (noecho,terminate,noerase,nolock) 2 FN$SHOW_TIMER Shows elapsed time since the timer was last initialized. Note that DEC DATATRIEVE does not include the information displayed by FN$SHOW_TIMER in a log file created with the OPEN command. 3 Input None. 3 Output Displays the elapsed time in this format: D HH:MM:SS.SS 3 Example DTR> SHOW TIME_READY PROCEDURE TIME_READY FN$INIT_TIMER READY OWNERS FN$SHOW_TIMER END_PROCEDURE DTR> :TIME_READY ELAPSED: 0 00:00:04.24 CPU: 0:00:00.61 BUFIO: 1 DIRIO: 42 FAULTS: 64 DTR> At the end of a 24-hour period, the timer begins displaying time in the number of days rather than the accumulated number of hours. 2 FN$SHOWDEF Displays the current disk directory for the process. 3 Input None. 3 Output A text string containing the name of the current disk directory. 3 Example The following example shows how to display the current working directory from DEC DATATRIEVE. $ SHOW DEFAULT DISK:[SMITH.WORK] $ DATATRIEVE DTR> PRINT FN$SHOWDEF USING X(80) FN$SHOWDEF [SMITH.WORK] DTR> 2 FN$SHOWDEFPROT Displays the current file protection for the process. 3 Input None. 3 Output A text string containing the current default file protection. 3 Example The following example shows how to display the current default file protection. DTR> PRINT FN$SHOWDEFPROT USING X(80) FN$SHOWDEFPROT SYSTEM:RWED,OWNER:RWED,GROUP:RWED,WORLD: DTR> 2 FN$SIGN Indicates the sign of a number. 3 Input A signed number. 3 Output 1, -1, or 0 (depending on the sign of the number). 3 Example DTR> PRINT FN$SIGN (-4) FN$SIGN -1 DTR> 2 FN$SIN Calculates the sine of input. 3 Input A signed decimal number (radians). 3 Output A signed decimal number of type G-floating. 3 Example DTR> PRINT FN$SIN (3.14159/2) FN$SIN 1.000 DTR> 2 FN$SPAWN Creates a subprocess by calling the OpenVMS Run-Time Library routine LIB$SPAWN. 3 Input Type FN$SPAWN at the DTR> prompt to create the subprocess. 3 Output Your default DCL prompt appears on the screen. You can then invoke utilities or enter commands. Type LOGOUT after the DCL prompt to return to your original process in DEC DATATRIEVE. A message is printed on the screen indicating that you have logged out of the subprocess. DEC DATATRIEVE generates the DTR> prompt, showing that control has been returned to the original process in DEC DATATRIEVE. 3 Example DTR> FN$SPAWN $ MAIL . . . MAIL> EXIT $ LOGOUT Process PROCESSNAME_1 logged out at 25-FEB-1990 09:47:09:27 DTR> 2 FN$SQRT Calculates the square root of the input number. 3 Input Zero or a positive decimal number. 3 Output Zero or a positive decimal number of type G-floating. 3 Example DTR> PRINT FN$SQRT (196) FN$SQRT 1.4000E+01 DTR> 2 FN$STR_CHARN It returns a string containing n duplicates of the input character. 3 Input This function takes two input arguments separated by a comma: a number and a character. 3 Output A string containing the selected number of input characters. 3 Example DTR> READY CDD$TOP.DTR$LIB.DEMO.YACHTS ; DTR> FOR FIRST 3 YACHTS SORTED BY PRICE ASCENDING CON> PRINT BUILDER, MODEL, FN$STR_CHARN(300,FN$ICHAR("_"))("NOTES") USING T(30) ; MANUFACTURER MODEL NOTES BUCCANEER 270 ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ PEARSON 26W ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ BUCCANEER 320 ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ ______________________________ DTR> 2 FN$STR_EXTRACT Extracts a substring from the input character string using a default edit string of 30 characters. 3 Input This function takes three parameters: o A character string o An ordinal number of starting character (numerical position within string) o The length of desired substring 3 Output A substring. 3 Example DTR> DECLARE WOMBAT PIC X(25). DTR> WOMBAT = "Wombats have sharp claws." DTR> PRINT FN$STR_EXTRACT (WOMBAT,9,4) FN$STR EXTRACT have DTR> 2 FN$STR_LENGTH Returns the length of a string.. 3 Input This functions takes a string expression. 3 Output The length of the string. 3 Example DTR> READY YACHTS DTR> FOR FIRST 1 YACHTS CON> BEGIN CON> PRINT "BUILDER is", FN$STR_LENGTH(BUILDER)," Characters long"; CON> PRINT "The record is", FN$STR_LENGTH(BOAT)," Characters long"; CON> END; FN$STR LENGTH BUILDER is 10 Characters long FN$STR LENGTH The record is 41 Characters long 2 FN$STR_LOC Calculates the starting position of the specified substring in the input character string. 3 Input This functions takes two parameters: a character string and a substring. 3 Output An unsigned integer. If the string is undefined, FN$STR_LOC returns the value 0. 3 Example DTR> DECLARE WOMBAT PIC X(25) DTR> WOMBAT = "Wombats have sharp claws." DTR> PRINT FN$STR_LOC (WOMBAT,"claws") FN$STR LOC 20 DTR> 2 FN$STR_TOKEN Searches a string for the next token delimited by user-specified delimiters. When the function is called for the first time for a given string the init_flag must be 1 and the first token delimited by characters in delimiters is returned. In the following calls to get the other tokens in the same string, the init_flag must be 0. The string argument is now ignored because an internal copy is now used. The delimiters string may be different from that used in the first call. When no more tokens exist, an empty string is returned. 3 Input This function takes three parameters as input, separated by commas: o The string expression to be searched. o The delimiters of the token. o The initial flag for a given string: 1 for the first call and 0 for the following calls to the same string. 3 Output The token within the delimiters. 3 Example The following example shows you how to split a sentence into lines (the separators are spaces, commas, or dots). DTR> SHOW D1 DOMAIN D1 USING R1 ON LOG_NAM ; DTR> FN$CREATE_LOG("LOG_NAM","FN_STR_TOKEN_01.DAT"); DTR> READY D1 ; DTR> DECLARE TOKEN PIC X(80) .; DTR> FOR D1 CON> BEGIN CON> TOKEN = FN$STR_TOKEN(F," ,.", 1) ; CON> WHILE TOKEN NOT EQ " " CON> BEGIN CON> PRINT TOKEN ; CON> TOKEN = FN$STR_TOKEN(F," ,.", 0); CON> END ; CON> END ; TOKEN DEC DATATRIEVE for OpenVMS AXP systems is a query report and data management tool for the OpenVMS Operating System DTR> 2 FN$TAN Calculates the tangent of the input number. 3 Input A signed decimal number (radians). 3 Output A signed decimal number of type G-floating. 3 Example DTR> PRINT FN$TAN (3.14159/4) FN$TAN 1.0000E+00 DTR> 2 FN$TIME Extracts the time part of input (hh:mm:ss.cc in dd-MMM-yyyy hh:mm:ss.cc). 3 Input A date. 3 Output The time in OpenVMS format. 3 Example DTR> DECLARE CAL USAGE DATE EDIT_STRING X(23). DTR> CAL = "NOW"; PRINT CAL CAL 1-Feb-1990 08:51:11.55 DTR> PRINT FN$TIME (CAL) FN$TIME 08:51:11.5 DTR> 2 FN$TRANS_LOG Translates a logical name. 3 Input A character string containing the logical name you want to translate. 3 Output A character string. 3 Example DTR> FN$CREATE_LOG ("HANK", "DB0:[MORRISON.RW]LOG.RNO") DTR> PRINT FN$TRANS_LOG ("HANK") USING X(30) FN$TRANS LOG DB0:[MORRISON.RW]LOG.RNO DTR> 2 FN$UPCASE Changes the characters in a string to uppercase. 3 Input A character string. 3 Output The input character string, all in uppercase. 3 Example DTR> DECLARE WOMBAT PIC X(25). DTR> WOMBAT = "Wombats have sharp claws." DTR> PRINT FN$UPCASE (WOMBAT) FN$UPCASE WOMBATS HAVE SHARP CLAWS. DTR> 2 FN$USERNAME Displays the text string of the username. 3 Input None. 3 Output The text string of the username passed by descriptor. 3 Example DTR> PRINT FN$USERNAME DALFY DTR> 2 FN$WAIT Places the current process into hibernation for the number of seconds specified in its argument. 3 Input The number of seconds to wait. You can also specify a prompting value expression. 3 Output A pause determined by the seconds specified in the argument. 3 Examples DTR> BEGIN CON> REPEAT 3 PRINT "HALLO", CON> FN$WAIT(2) CON> END FN$WAIT HALLO 0 HALLO 0 HALLO 0 DTR> The following example uses a prompting value expression. DTR> BEGIN CON> REPEAT 3 PRINT "HALLO", CON> FN$WAIT(**.'Seconds') CON> END FN$WAIT Enter Seconds: 3 HALLO 0 HALLO 0 HALLO 0 DTR> 2 FN$WEEK Calculates the week number for a date you enter. (The week number is an integer from 1 to 52. A week number is assigned sequentially to each week, beginning with the first week of the year. The first week of January is week number 1, the second week of January is week number 2, and so on.) 3 Input A date. 3 Output An unsigned integer from 1 to 52. 3 Example DTR> DECLARE CAL USAGE DATE EDIT_STRING X(23). DTR> CAL = "NOW"; PRINT CAL CAL 1-Feb-1983 08:51:11.55 DTR> PRINT FN$WEEK (CAL) FN$WEEK 5 DTR> 2 FN$WIDTH Changes the character width of the terminal. 3 Input An integer. 3 Output None. 3 Example DTR> SET COLUMNS_PAGE = 132 DTR> FN$WIDTH (132) FN$WIDTH (132) sets the terminal's width at 132 characters or columns. The SET COLUMNS_PAGE command ensures that any output produced by REPORT, PRINT, SUM, or LIST statements is spaced across the 132 columns. 2 FN$YEAR Extracts the year part of input (yyyy in dd-Mmm-yyyy hh:mm:ss.cc). 3 Input A date. 3 Output An unsigned integer for years 1858 to 9999. 3 Example DTR> DECLARE CAL USAGE DATE EDIT_STRING X(23). DTR> CAL = "NOW"; PRINT CAL CAL 1-Feb-1990 08:51:11.55 DTR> PRINT FN$YEAR (CAL) FN$YEAR 1990 DTR>