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 [,...] ) ]
1 – FN$ABS
Calculates the absolute value of input.
1.1 – Input
A signed decimal number.
1.2 – Output
An unsigned decimal number of type G-floating.
1.3 – Example
DTR> PRINT FN$ABS (-128)
FN$ABS
1.2800E+02
DTR>
2 – FN$ATAN
Calculates the arctangent of input.
2.1 – Input
A signed decimal number (radians).
2.2 – Output
A signed decimal number of type G-floating.
2.3 – Example
DTR> PRINT 4 * (FN$ATAN (1))
3.1416E+00
DTR>
3 – FN$BIT_AND
Returns the bitwise AND of two longwords.
3.1 – Input
This function takes two parameters as input. Two longwords,
separated by a comma and enclosed in parentheses.
3.2 – Output
An integer number.
3.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>
4 – FN$BIT_EXTRACT
Returns the bit field within a longword.
4.1 – 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.
4.2 – Output
An integer number.
4.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>
5 – FN$BIT_NOT
Returns the bitwise complement of a longword.
5.1 – Input
A longword.
5.2 – Output
An integer number.
5.3 – Example
DTR> DECLARE OP1 PIC 99999999 LONG .;
DTR> OP1 = 128+64+32 ;
DTR> PRINT FN$BIT_NOT(OP1);
FN$BIT
NOT
-225
DTR>
6 – FN$BIT_OR
Returns the bitwise OR of two longwords.
6.1 – Input
This function takes two arguments: two longwords. The two must be
separated by a comma and enclosed in parentheses.
6.2 – Output
An integer number.
6.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>
7 – FN$BIT_XOR
Returns the bitwise exclusive OR of two longwords.
7.1 – Input
This function takes two arguments: two longwords. The two must be
separated by a comma and enclosed in parentheses.
7.2 – Output
An integer number.
7.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>
8 – 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.
8.1 – Input
None.
8.2 – Output
A longword value of the COMMAND_KEYBOARD field.
8.3 – Example
DTR> DECLARE COMMAND_KEYBOARD LONG.
DTR> COMMAND_KEYBOARD = FN$COMMAND_KEYBOARD
9 – FN$COS
Calculates the cosine of input.
9.1 – Input
A signed decimal number (radians).
9.2 – Output
A signed decimal number of type G-floating.
9.3 – Example
DTR> PRINT FN$COS (3.14159) using s9.999
FN$COS
-1.000
DTR>
10 – 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.
10.1 – 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.
10.2 – Output
None.
10.3 – Example
DTR> FN$CREATE_LOG ("HANK", "DB0:[MORRISON.RW]LOG.RNO")
DTR>
10.4 – 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; .
11 – FN$DATE
Converts a date string to a 64-bit data value.
11.1 – 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.
11.2 – Output
A date data value formatted as "dd-MMM-yyyy hh:mm:ss.cc".
11.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>
12 – FN$DAY
Extracts the day part of input (dd in dd-MMM-yyyy hh:mm:ss.cc).
12.1 – Input
A date.
12.2 – Output
An unsigned integer from 1 to 31.
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$DAY (CAL)
FN$DAY
1
DTR>
13 – FN$DBKEY_LENGTH
Returns the byte length of dbkeys for the relational domain or
table specified as argument.
13.1 – 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.
13.2 – 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.
13.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
13.4 – Usage Note
This function has been implemented for Oracle Rdb dbkeys only.
14 – FN$DCL
Allows you to spawn directly from your main DEC DATATRIEVE
process to execute a specified DCL command.
14.1 – 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.
14.2 – Output
Your DEC DATATRIEVE process is suspended and the terminal is
attached to the subprocess. The DCL command is executed.
14.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.
15 – 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.
15.1 – 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.
15.2 – Output
None.
15.3 – Example
DTR> FN$KEYPAD_MODE ("APPLICATION")
DTR> FN$DEFINE_KEY ('DEFINE/KEY/ECHO/NOTERMINATE KP7 "FIND" ')
15.4 – 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.
16 – FN$DELETE_KEY
Deletes a key definition currently in effect.
This function is not available in a DECwindows Motif environment.
16.1 – 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.
16.2 – Output
None.
16.3 – Example
DTR> FN$DELETE_KEY ("KP0","DEFAULT")
DTR> FN$DELETE_KEY ("KP0","GOLD")
17 – FN$DELETE_LOG
Deletes the assignment of a logical name.
17.1 – Input
The logical name you want to delete.
17.2 – Output
None.
17.3 – Example
DTR> FN$DELETE_LOG ("HANK")
DTR> PRINT FN$TRANS_LOG ("HANK") USING X(30)
FN$TRANS
LOG
DTR>
18 – FN$DELETE_LOGICAL
Deletes a supervisor-mode process logical name.
18.1 – 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.
18.2 – Output
None.
18.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>
19 – FN$DELETE_SYMBOL
Deletes a CLI symbol.
19.1 – Input
The name of the symbol to be deleted.
19.2 – Output
None.
19.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>
20 – FN$DISABLE_DECFORMS
Disables DECforms from managing forms.
20.1 – Input
None. The function has no arguments.
20.2 – Output
None.
20.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 )
21 – FN$ENABLE_DECFORMS
Enables DECforms to manage forms.
21.1 – Input
None. The function has no arguments.
21.2 – Output
None.
21.3 – Example
See the example for function FN$DISABLE_DECFORMS.
22 – FN$EXP
Calculates the value of e to a specified power.
22.1 – Input
A signed decimal number.
22.2 – Output
A signed decimal number of type G-floating.
22.3 – Example
DTR> PRINT FN$EXP (2)
FN$EXP
7.3891E+00
DTR>
23 – FN$FLOOR
Truncates the decimal part of positive input or rounds negative
input.
23.1 – Input
A signed decimal number.
23.2 – Output
A signed decimal number of type G-floating.
23.3 – Example
DTR> PRINT FN$FLOOR (59.99)
FN$FLOOR
5.9000E+01
DTR> PRINT FN$FLOOR (-59.99)
FN$FLOOR
-6.0000E+01
24 – FN$FORMAT_DBKEY
Returns a character string containing the dbkey of the readied
relational domain, table, or view.
24.1 – Input
A string containing the dbkey in its binary format.
24.2 – 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.
24.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>
24.4 – Usage Note
This function has been implemented for Oracle Rdb dbkeys only.
25 – FN$GET_SYMBOL
Returns the value of a DCL symbol.
25.1 – Input
A character string that represents the symbol name.
25.2 – Output
The value of a DCL symbol.
25.3 – Example
DTR> PRINT FN$GET_SYMBOL("DTR$INVOKE") USING X(45)
FN$GET
SYMBOL
RUN DTR$DISK:[DTR.TESTS]DTRV4.EXE
DTR>
26 – FN$HEX
Calculates the hexadecimal equivalent of input.
26.1 – Input
A signed integer no larger than (2 ** 31) -1 (the maximum value
that can be stored in a signed longword).
26.2 – Output
A hexadecimal character string.
26.3 – Example
DTR> PRINT FN$HEX(183)
FN$HEX
B7
DTR>
27 – FN$HEX_TO_DEC
Calculates the integer equivalent of a hexadecimal value.
27.1 – Input
A string expression containing the hexadecimal character string.
The string expression must be placed inside quotation marks, and
enclosed in parentheses.
27.2 – Output
A longword integer equivalent to the hexadecimal value.
27.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>
28 – FN$HOUR
Extracts the hour part of input (hh in dd-MMM-yyyy hh:mm:ss.cc).
28.1 – Input
A date.
28.2 – Output
An unsigned integer from 1 to 24.
28.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>
29 – FN$HUNDREDTH
Extracts hundredth-of-a-second part of input (cc in dd-MMM-yyyy
hh:mm:ss.cc).
29.1 – Input
A date.
29.2 – Output
An unsigned integer from 0 to 99.
29.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>
30 – FN$ICHAR
It converts the first character of a string to an 8-bit ASCII
integer extended to a longword.
30.1 – Input
The string expression.
30.2 – Output
The 8-bit ASCII integer.
30.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>
31 – FN$INIT_TIMER
Initializes a timer and counter.
31.1 – Input
None.
31.2 – Output
None.
31.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>
32 – 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.)
32.1 – Input
A date.
32.2 – Output
An unsigned integer from 1 to 366. (There are 366 days in a leap
year.)
32.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>
33 – 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.
33.1 – 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.
33.2 – Output
None.
33.3 – Example
DTR> FN$KEYPAD_MODE ("APPLICATION")
DTR> FN$KEYPAD_MODE ("NUMERIC")
34 – 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.
34.1 – Input
None.
34.2 – Output
A longword value of the KEYTABLE_ID field.
34.3 – Example
DTR> DECLARE KEYTABLE LONG.
DTR> KEYTABLE = FN$KEYTABLE_ID
35 – FN$LASTREC_DBKEY
Returns the dbkey of the last record read in a currently readied
relational domain or table.
35.1 – Input
A string expression providing the name of the domain or table.
35.2 – Output
The record dbkey as a byte string.
35.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>
36 – FN$LN
Calculates the natural log of input.
36.1 – Input
A signed number.
36.2 – Output
A signed number of type G-floating.
36.3 – Example
DTR> PRINT FN$LN (36)
FN$LN
3.5835E+00
DTR>
37 – 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.
37.1 – Input
A quoted string with a DCL file specification indicating the file
containing the DCL DEFINE/KEY commands.
37.2 – Output
None.
37.3 – Example
DTR> FN$LOAD_KEYDEFS ("APPL1.KEYS")
38 – FN$LOG10
Calculates the base 10 log of input.
38.1 – Input
A signed number.
38.2 – Output
A signed number of type G-floating.
38.3 – Example
DTR> PRINT FN$LOG10 (36)
FN$LOG10
1.5563E+00
DTR>
39 – FN$MINUTE
Extracts the minute part of input (mm in dd-MMM-yyyy
hh:mm:ss.cc).
39.1 – Input
A date.
39.2 – Output
An unsigned integer from 0 to 59.
39.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>
40 – FN$MOD
Calculates the value of input according to a specified modulus,
using double precision floating values.
40.1 – Input
This function takes two parameters: a signed number and a
modulus. The two must be separated by a comma and enclosed in
parentheses.
40.2 – Output
A real number of type G-floating.
40.3 – Example
DTR> PRINT FN$MOD (31,7)
FN$MOD
3.0000E+00
DTR>
41 – FN$MODI
Calculates the value of input according to a specified modulus,
using integer values.
41.1 – Input
This function takes two parameters: a signed number and a
modulus. The two must be separated by a comma and enclosed in
parentheses.
41.2 – Output
An integer number.
41.3 – Example
DTR> PRINT FN$MODI(13,4);
FN$MODI
1
DTR> PRINT FN$MODI(-13,4);
FN$MODI
-1
DTR>
42 – FN$MONTH
Extracts the month part of input (MMM in dd-MMM-yyyy
hh:mm:ss.cc).
42.1 – Input
A date.
42.2 – Output
An unsigned integer from 1 to 12.
42.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>
43 – FN$NINT
Calculates the integer nearest to input.
43.1 – Input
A signed number.
43.2 – Output
A signed longword.
43.3 – Example
DTR> PRINT FN$NINT (59.99)
FN$NINT
60
DTR>
44 – FN$OPENS_LEFT
Calculates the number of additional files you can open.
44.1 – Input
None.
44.2 – Output
An signed longword.
44.3 – Example
DTR> PRINT FN$OPENS_LEFT
FN$OPENS
LEFT
3
DTR>
45 – FN$PROCESS_INFO
Returns information on the current process.
45.1 – 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.
45.2 – Output
A text string containing the information requested by the item-
code.
45.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>
46 – 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.
46.1 – Input
None.
46.2 – Output
A longword value of the PROMPT_KEYBOARD field.
46.3 – Example
DTR> DECLARE PROMPT_KEYBOARD LONG.
DTR> PROMPT_KEYBOARD = FN$PROMPT_KEYBOARD
47 – FN$SECOND
Extracts the second part of input (ss in dd-MMM-yyyy
hh:mm:ss.cc).
47.1 – Input
A date.
47.2 – Output
An unsigned integer from 0 to 59.
47.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>
48 – FN$SETDEF
Allows you to change the default disk directory for the process.
48.1 – Input
A string expression containing the new default disk directory.
The string expression must be placed inside quotation marks, and
enclosed in parentheses.
48.2 – Output
None.
48.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]
$
49 – FN$SETDEFPROT
Allows you to change the default file protection for the process.
49.1 – 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.
49.2 – Output
None.
49.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
$
50 – 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).
50.1 – 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).
50.2 – Output
None.
50.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 );
}
51 – FN$SET_LOGICAL
Defines or redefines a supervisor-mode process logical name.
51.1 – 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.
51.2 – Output
None.
51.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>
52 – FN$SET_SYMBOL
Defines or redefines a CLI (Command Language Interpreter) symbol.
52.1 – 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.
52.2 – Output
None.
52.3 – Example
DTR> FN$SET_SYMBOL("MY_SYMBOL","ITS_VALUE")
DTR> PRINT FN$GET_SYMBOL("MY_SYMBOL");
FN$GET
SYMBOL
ITS_VALUE
DTR>
53 – FN$SHOW_KEY
Displays the definition of a keypad key.
This function is not available in a DECwindows Motif environment.
53.1 – 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.
53.2 – Output
The definition of the specified key.
53.3 – Example
DTR> FN$SHOW_KEY ("KP7","DEFAULT")
KP7 = "SHOW ALL"
(echo,terminate,noerase,nolock)
54 – 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.
54.1 – Input
None.
54.2 – Output
The definitions of all the defined keys.
54.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)
55 – 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.
55.1 – Input
None.
55.2 – Output
Displays the elapsed time in this format:
D HH:MM:SS.SS
55.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.
56 – FN$SHOWDEF
Displays the current disk directory for the process.
56.1 – Input
None.
56.2 – Output
A text string containing the name of the current disk directory.
56.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>
57 – FN$SHOWDEFPROT
Displays the current file protection for the process.
57.1 – Input
None.
57.2 – Output
A text string containing the current default file protection.
57.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>
58 – FN$SIGN
Indicates the sign of a number.
58.1 – Input
A signed number.
58.2 – Output
1, -1, or 0 (depending on the sign of the number).
58.3 – Example
DTR> PRINT FN$SIGN (-4)
FN$SIGN
-1
DTR>
59 – FN$SIN
Calculates the sine of input.
59.1 – Input
A signed decimal number (radians).
59.2 – Output
A signed decimal number of type G-floating.
59.3 – Example
DTR> PRINT FN$SIN (3.14159/2)
FN$SIN
1.000
DTR>
60 – FN$SPAWN
Creates a subprocess by calling the OpenVMS Run-Time Library
routine LIB$SPAWN.
60.1 – Input
Type FN$SPAWN at the DTR> prompt to create the subprocess.
60.2 – 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.
60.3 – Example
DTR> FN$SPAWN
$ MAIL
.
.
.
MAIL> EXIT
$ LOGOUT
Process PROCESSNAME_1 logged out at 25-FEB-1990 09:47:09:27
DTR>
61 – FN$SQRT
Calculates the square root of the input number.
61.1 – Input
Zero or a positive decimal number.
61.2 – Output
Zero or a positive decimal number of type G-floating.
61.3 – Example
DTR> PRINT FN$SQRT (196)
FN$SQRT
1.4000E+01
DTR>
62 – FN$STR_CHARN
It returns a string containing n duplicates of the input
character.
62.1 – Input
This function takes two input arguments separated by a comma: a
number and a character.
62.2 – Output
A string containing the selected number of input characters.
62.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>
63 – FN$STR_EXTRACT
Extracts a substring from the input character string using a
default edit string of 30 characters.
63.1 – 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
63.2 – Output
A substring.
63.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>
64 – FN$STR_LENGTH
Returns the length of a string..
64.1 – Input
This functions takes a string expression.
64.2 – Output
The length of the string.
64.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
65 – FN$STR_LOC
Calculates the starting position of the specified substring in
the input character string.
65.1 – Input
This functions takes two parameters: a character string and a
substring.
65.2 – Output
An unsigned integer. If the string is undefined, FN$STR_LOC
returns the value 0.
65.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>
66 – 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.
66.1 – 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.
66.2 – Output
The token within the delimiters.
66.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>
67 – FN$TAN
Calculates the tangent of the input number.
67.1 – Input
A signed decimal number (radians).
67.2 – Output
A signed decimal number of type G-floating.
67.3 – Example
DTR> PRINT FN$TAN (3.14159/4)
FN$TAN
1.0000E+00
DTR>
68 – FN$TIME
Extracts the time part of input (hh:mm:ss.cc in dd-MMM-yyyy
hh:mm:ss.cc).
68.1 – Input
A date.
68.2 – Output
The time in OpenVMS format.
68.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>
69 – FN$TRANS_LOG
Translates a logical name.
69.1 – Input
A character string containing the logical name you want to
translate.
69.2 – Output
A character string.
69.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>
70 – FN$UPCASE
Changes the characters in a string to uppercase.
70.1 – Input
A character string.
70.2 – Output
The input character string, all in uppercase.
70.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>
71 – FN$USERNAME
Displays the text string of the username.
71.1 – Input
None.
71.2 – Output
The text string of the username passed by descriptor.
71.3 – Example
DTR> PRINT FN$USERNAME
DALFY
DTR>
72 – FN$WAIT
Places the current process into hibernation for the number of
seconds specified in its argument.
72.1 – Input
The number of seconds to wait. You can also specify a prompting
value expression.
72.2 – Output
A pause determined by the seconds specified in the argument.
72.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>
73 – 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.)
73.1 – Input
A date.
73.2 – Output
An unsigned integer from 1 to 52.
73.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>
74 – FN$WIDTH
Changes the character width of the terminal.
74.1 – Input
An integer.
74.2 – Output
None.
74.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.
75 – FN$YEAR
Extracts the year part of input (yyyy in dd-Mmm-yyyy
hh:mm:ss.cc).
75.1 – Input
A date.
75.2 – Output
An unsigned integer for years 1858 to 9999.
75.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>