Guide to OpenVMS File Applications
An interactive session is controlled by these Edit/FDL utility scripts.
You can invoke a script in two ways:
Example 4-1 shows a sample session with the Edit/FDL utility.
| Example 4-1 Sample Edit/FDL Utility
Session |
OpenVMS FDL Editor
Add to insert one or more lines into the FDL definition
Delete to delete one or more lines from the FDL definition
Exit to leave the FDL Editor after creating the FDL file
Help to obtain information about the FDL Editor
(1) Invoke to initiate a script of related questions
Modify to change existing line(s) in the FDL definition
Quit to abort the FDL Editor with no FDL file creation
Set to specify FDL Editor characteristics
View to display the current FDL Definition
(2) Main Editor Function (Keyword)[Help] : INVOKE
Script Title Selection
Add_Key modeling and addition of a new index's parameters
Delete_Key removal of the highest index's parameters
Indexed modeling of parameters for an entire Indexed file
(3) Optimize tuning of all indexes' parameters using file statistics
Relative selection of parameters for a Relative file
Sequential selection of parameters for a Sequential file
Touchup remodeling of parameters for a particular index
(4) Editing Script Title (Keyword)[-] : INDEXED
(5) Target disk volume Cluster Size (1-1Giga)[3] : 3
(6) Number of Keys to Define (1-255)[1] : 1
Line Bucket Size vs Index Depth as a 2 dimensional plot
Fill Bucket Size vs Load Fill Percent vs Index Depth
(7) Key Bucket Size vs Key Length vs Index Depth
Record Bucket Size vs Record Size vs Index Depth
Init Bucket Size vs Initial Load Record Count vs Index Depth
Add Bucket Size vs Additional Record Count vs Index Depth
(8) Graph type to display (Keyword)[Line] : LINE
(9) Number of Records that will be Initially Loaded
into the File (0-1Giga)[-] : 100000
(10) (Fast_Convert NoFast_Convert RMS_Puts)
Initial File Load Method (Keyword)[Fast] : FAST
(11) Number of Additional Records to be Added After
the Initial File Load (0-1Giga)[0] : 0
(12) Key 0 Load Fill Percent (50-100)[100] : 100
(13) (Fixed Variable)
Record Format (Keyword)[Var] : VARIABLE
(14) Mean Record Size (1-32229)[-] : 80
(15) Maximum Record Size (0,80-32229)[0] : 0
(16) (Bin2 Bin4 Bin8 Int2 Int4 Int8 Decimal String Collated
Dbin2 Dbin4 Dbin8 Dint2 Dint4 Dint8 Ddecimal Dstring Dcollated)
Key 0 Data Type (Keyword)[Str] : STRING
(17) Key 0 Segmentation desired (Yes/No)[No] : NO
(18) Key 0 Length (1-255)[-] : 9
(19) Key 0 Position (0-32220)[0] : 0
(20) Key 0 Duplicates allowed (Yes/No)[No] : NO
(21) File Prolog Version (0-3)[3] : 3
(22) Data Key Compression desired (Yes/No)[Yes] : YES
(23) Data Record Compression desired (Yes/No)[Yes] : YES
(24) Index Compression desired (Yes/No)[Yes] : YES
*|
9|
8|
Index 7|
6|
Depth 5|
4|
3| 3 3
2| 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2
1| 1 1 1 1 1 1 1 1
+- + - - - + - - - - + - - - - + - - - - + - - - - + - - - - + - +
(25) 1 5 10 15 20 25 30 32
Bucket Size (number of blocks)
PV-Prolog Version 3 KT-Key 0 Type String EM-Emphasis Flatter ( 3)
DK-Dup Key 0 Values No KL-Key 0 Length 9 KP-Key 0 Position 0
RC-Data Record Comp 0% KC-Data Key Comp 0% IC-Index Record Comp 0%
BF-Bucket Fill 100% RF-Record Format Variable RS-Mean Record Size 80
LM-Load Method Fast_Conv IL-Initial Load 100000 AR-Added Records 0
(Type "FD" to Finish Design)
(26) Which File Parameter (Mnemonic)[refresh] : FD
(27) Text for FDL Title Section (1-126 chars)[null]
: FDL_SESSION_EXAMPLE
(28) Data File file-spec (1-126 chars)[null]
: EXAMPLE.DAT
(29) (Carriage_Return Fortran None Print)
Carriage Control (Keyword)[Carr] : CARRIAGE_RETURN
Emphasis Used In Defining Default: ( Flatter_files )
Suggested Bucket Sizes: ( 3 3 27 )
(30) Number of Levels in Index: ( 2 2 1 )
Number of Buckets in Index: ( 72 72 1 )
Pages Required to Cache Index: ( 216 216 27 )
Processing Used to Search Index: ( 168 168 766 )
(31) Key 0 Bucket Size (1-63)[3] : 3
(32) Key 0 Name (1-32 chars)[null]
: SSNUM
(33) Global Buffers desired (Yes/No)[No] : NO
(34) The Depth of Key 0 is Estimated to be No Greater
than 2 Index levels, which is 3 Total levels.
(35) Press RETURN to continue (^Z for Main Menu)
OpenVMS FDL Editor
Add to insert one or more lines into the FDL definition
Delete to delete one or more lines from the FDL definition
Exit to leave the FDL Editor after creating the FDL file
(36) Help to obtain information about the FDL Editor
Invoke to initiate a script of related questions
Modify to change existing line(s) in the FDL definition
Quit to abort the FDL Editor with no FDL file creation
Set to specify FDL Editor characteristics
View to display the current FDL Definition
(37) Main Editor Function (Keyword)[Help] : EXIT
(38) DISK$:[FOX.RMS]FDL_SESSION_EXAMPLE.FDL;1 40 lines
|
- The Main Editor Function menu displays the
Edit/FDL utility commands.
- The INVOKE command displays the Script Title
Selection menu. Note that HELP is the default command so if you want
online help, just press the Return key.
- The Script Title Selection menu shows the
seven scripts you can choose to help you design your file. There is no
default so you must explicitly select one of the scripts.
- Choose the INDEXED script to design an indexed
data file.
- Choose a disk cluster size of three.
- Define only one key---the primary key.
- This menu provides a selection of graphic
display types.
- Select a line plot display.
- Select 100,000 records to be loaded initially.
- Select the CONVERT/FAST_LOAD method of
loading records into the data file.
- Opt for no additional records after the
initial load.
- Elect a fill level of 100 percent for the
primary index buckets.
- Choose the variable-length record format.
- Select an average record size of 80
characters.
- Select an unlimited maximum record size.
- Select the string data type for the primary
key.
Note
The string data-type keys include STRING, DSTRING, COLLATED and
DCOLLATED keys.
|
- Opt to disallow segmentation in the primary
key.
- Set the length of the primary key to 9 bytes.
- Define the initial position of the primary
key at column 0.
- Opt to disallow duplicates of the primary key.
- Choose the Prolog 3 version.
- Select data key compression.
- Select data record compression.
- Select index compression.
- This is a line plot showing bucket size
against index depth.
- Type "FD" to finish the design
session.
- Enter the title of your FDL file
specification.
- Enter the file specification of your data
file.
- Select the CARRIAGE_RETURN carriage control.
- This display shows the tuning emphasis you
chose to design your file. It also shows suggested bucket sizes for
various index level depths and other tuning information.
- Select the default bucket size for the
primary key.
- Enter the name of the primary key.
- Choose whether you want global buffers.
- This message shows the depth of the primary
key index and gives the total number of levels.
- Press the Return key to display the main menu.
- This is the main menu.
- Use the EXIT command to exit the editor and
to create the FDL file.
- This message shows the resulting FDL file
specification and the number of lines it contains.
Note that the example uses most of the suggested defaults. There are
three ways to accept defaults:
- Press the Return key without entering a value.
- Use the /RESPONSES=AUTOMATIC qualifier when you invoke the Edit/FDL
utility.
- Use the following sequence:
- Select the SET command from the main menu.
- Select RESPONSES from the SET menu.
- Accept the default (AUTO) when the Edit/FDL utility prompts for
"Default responses in script."
Key compression and index compression are not acceptable options when
you select a collated key data type.
When the Edit/FDL utility creates an FDL file, it groups the attributes
into major sections. The section headings are called primary
attributes, and the attributes within a primary section are called
secondary attributes. Certain secondary attributes contain a
third level of attributes called qualifiers.
The objective of using the Edit/FDL utility is to create an FDL file
with optimum values for the various attributes. An FDL file contains a
list of the primary and secondary attributes with related qualifiers.
If a primary or secondary attribute does not appear in the FDL file, it
is assigned its default value.
Example 4-2 shows an FDL file. IDENT, SYSTEM, FILE, RECORD, AREA n,
and KEY n are primary attributes; the others are secondary attributes.
| Example 4-2 Sample FDL File |
IDENT
" 1-MAR-1993 14:07:46 OpenVMS FDL Editor"
SYSTEM
SOURCE VMS
FILE
GLOBAL_BUFFER_COUNT 0
NAME DISK$RMS:[RMSTEST]INDEXED.DAT;3
ORGANIZATION indexed
OWNER [RMS1,TEST]
PROTECTION (system:RWED, owner:RWED, group:RE, world:)
RECORD
BLOCK_SPAN yes
CARRIAGE_CONTROL none
FORMAT variable
SIZE 2048
AREA 0
ALLOCATION 233
BEST_TRY_CONTIGUOUS yes
BUCKET_SIZE 5
EXTENSION 60
AREA 1
ALLOCATION 5
BEST_TRY_CONTIGUOUS yes
BUCKET_SIZE 5
EXTENSION 5
AREA 2
ALLOCATION 18
BEST_TRY_CONTIGUOUS yes
BUCKET_SIZE 3
EXTENSION 6
KEY 0
CHANGES no
DATA_AREA 0
DATA_FILL 100
DATA_KEY_COMPRESSION no
DATA_RECORD_COMPRESSION no
DUPLICATES no
INDEX_AREA 1
INDEX_COMPRESSION no
INDEX_FILL 100
LEVEL1_INDEX_AREA 1
NAME "NUM"
NULL_KEY no
PROLOG 3
SEG0_LENGTH 8
SEG0_POSITION 0
TYPE bin8
KEY 1
CHANGES yes
DATA_AREA 2
DATA_FILL 100
DATA_KEY_COMPRESSION yes
DUPLICATES yes
INDEX_AREA 2
INDEX_COMPRESSION yes
INDEX_FILL 100
LEVEL1_INDEX_AREA 2
NAME "NAME"
NULL_KEY yes
NULL_VALUE 0
SEG0_LENGTH 39
SEG0_POSITION 9
TYPE string
|
4.1.2.2 Designing an FDL File
When you want to create an FDL file, you invoke the Edit/FDL utility
with a DCL command in the following form:
EDIT/FDL/CREATE fdl-filespec
|
The /CREATE qualifier specifies that you want to create an FDL file
with the name entered in the fdl-filespec parameter.
When the Edit/FDL utility displays the main menu, select the INVOKE
command. In response to the INVOKE command, the Edit/FDL utility
prompts you for a script. The only appropriate scripts for creating a
file are INDEXED, RELATIVE, and SEQUENTIAL.
As discussed previously, you can enter a script directly by specifying
the /SCRIPT qualifier on the DCL command line. For example, enter the
following command to create an indexed FDL file:
$ EDIT/FDL/CREATE/SCRIPT=INDEXED MY_FDL_FILE
|
When you select the script, the Edit/FDL utility prompts you for
information about the data file. Each prompt consists of a short
question, a range of acceptable values (for example, 50-100) or the
value type (for example, Keyword, YES/NO, and so forth) in parentheses,
and the default answer in brackets. One of the questions in the INDEXED
script is shown as follows:
Number of Keys to Define (1-255)[1] :
|
In this example, the Edit/FDL utility prompts you for the number of
keys you want to define for an indexed data file. The Edit/FDL utility
accepts any number from 1 to 255. If you do not specify a value, it
assumes that you want to define one key only, the primary key. To
accept the default value, press the Return key.
If the Edit/FDL utility requires that you enter a value (that is, no
default value is specified for the response), it includes a dash within
brackets [-].
When you specify the SEQUENTIAL script or the RELATIVE script, the
Edit/FDL utility returns you to the main menu level after finishing the
dialog. When you specify the INDEXED script, one of the prompts
requests your choice of a design graphics display: a Line_Plot graph or
a Surface_Plot graph. After finishing the dialog, the Edit/FDL utility
displays the selected graph to help you make your final design choice.
The Line_Plot graph plots bucket size against index depth. All things
equal, the size of the buckets determines the number of levels in the
index, and the number of levels has a direct effect on the run-time
performance of an indexed file. Fewer levels generally reduce the
average number of keys searched when the index tree is traversed.
However, fewer levels imply more records per data bucket and may cause
longer data bucket search times. Thus, the Line_Plot graph helps you
decide on the best bucket size for your application. Figure 4-1
shows a Line_Plot graph.
Figure 4-1 Line_Plot Graph
As shown in Figure 4-1, a bucket size of 1 block results in an index
with five levels. Increasing the bucket size to 2 blocks reduces the
number of index levels to four, but an increase to 5 blocks does not
reduce the number of index levels at all. A bucket size of 7 blocks,
however, reduces the number of index levels to three.
When you choose the bucket size, remember that the graphs do not
display the data level. For example, if you want three levels in the
file, then you must limit the number of index levels to two.
The Surface_Plot graphics mode lets you choose a range of values to see
their effects. The Edit/FDL utility prompts you to enter a lower and
upper bound for one of the following values:
- Load fill percent
- Key length
- Record size
- Initial load record count
- Additional record count
The selected range is displayed along the graph's vertical axis.
The variable on the graph's horizontal axis is bucket size. The numbers
in the field portion of the graph show the number of levels at each
bucket size for each of the other values.
Figure 4-2 is a Surface_Plot graph that shows a range of values for
initial fill factors ranging from 100% to 40%.
Figure 4-2 Surface_Plot Graph
The area on the graph within the slash marks represents combinations
that RMS finds acceptable. In Figure 4-2, a fill factor of 70% and a
bucket size of 10 blocks is the optimum combination. A fill factor of
70% and a bucket size of 15 blocks is a relatively poor combination
because it falls outside of the slash boundaries.
If you are sure the information you supplied to the Edit/FDL utility is
valid, the best values are those that lie along the left-hand boundary
next to the slash marks. If you are not sure that your information is
valid, you should choose a value that lies more to the right of the
slash boundary.
When you complete the dialog and the Edit/FDL utility presents the
graph, you can make changes to certain attributes of the proposed data
file. The design is not complete until you specify "FD" for
"Finish Design," at which point the Edit/FDL utility asks a
few more questions. You then have the opportunity to return to the main
menu to view the file attributes that the Edit/FDL utility has created.
Figure 4-3 shows the attributes that you can alter when the Edit/FDL
utility displays the graph. Note that each attribute has a 2-letter
mnemonic. To alter an attribute, you specify the corresponding
mnemonic. To refresh the display, press the Return key. To begin the
final design phase, enter "FD."
Figure 4-3 Design Mnemonics
During the final design phase, the Edit/FDL utility gives you an
opportunity to supply values for such attributes as TITLE, an optional
primary that allows you to label the FDL file. (Most of these questions
are also applicable to designing sequential and relative files.) When
you have answered the questions, the Edit/FDL utility assigns the
values to the FDL attributes and returns you to the main menu level to
display the resulting FDL file.
At the main menu, you can select the ADD command to assign values to
any attribute the script omitted. Remember that if an attribute does
not appear in the FDL file, it assumes the default value. (For a list
of the default values for each attribute, see the OpenVMS Record Management Utilities Reference Manual.) To
modify an attribute, use the MODIFY command, and to delete an
attribute, use the DELETE command.
To create the displayed FDL file, select the EXIT command. To abort the
session without creating an FDL file, select the QUIT command.
You can also define file-creation characteristics with the FDL utility
routines. The FDL routines provide you with the functions of the File
Definition Language, and they allow you to set file creation
characteristics from within your application.
There are four FDL routines:
|
FDL$CREATE
|
Creates a file from an FDL specification, and then closes the file. See
Section 4.2.4 for more information.
|
|
FDL$GENERATE
|
Produces an FDL specification by interpreting a set of control blocks.
It then writes the FDL specification either to an FDL file or to a
character string.
|
|
FDL$PARSE
|
Parses an FDL specification, allocates control blocks, and then fills
in the relevant fields.
|
|
FDL$RELEASE
|
Deallocates the virtual memory used by the control blocks created by
FDL$PARSE. You must use FDL$PARSE to fill in (to populate) the control
blocks if you plan to release the memory with FDL$RELEASE later.
|
Because the FDL$GENERATE, FDL$PARSE, and FDL$RELEASE routines allow you
to use the run-time, as well as the creation-time, features of RMS, you
must call them from a language that can access the control block fields
that specify the CONNECT options. This may be difficult from a
high-level language.
Example 4-3 shows how to call the FDL$PARSE and FDL$GENERATE routines
from a Pascal program.
| Example 4-3 Using FDL Routines in a Pascal
Program |
[INHERIT ('SYS$LIBRARY:STARLET')]
PROGRAM example2 (input,output,order_master);
(* This program fills in its own FAB, RAB, and *)
(* XABs by calling FDL$PARSE and then generates *)
(* an FDL specification by calling FDL$GENERATE.*)
(* It requires an existing input FDL file *)
(* (TESTING.FDL) for FDL$PARSE to parse. *)
TYPE
(*+ *)
(* FDL CALL INTERFACE CONTROL FLAGS *)
(*- *)
$BIT1 = [BIT(1),UNSAFE] BOOLEAN;
FDL2$TYPE = RECORD CASE INTEGER OF
1: (FDL$_FDLDEF_BITS : [BYTE(1)] RECORD END;
);
2: (FDL$V_SIGNAL : [POS(0)] $BIT1;
(* Signal errors; don't return *)
FDL$V_FDL_STRING : [POS(1)] $BIT1;
(* Main FDL spec is a char string *)
FDL$V_DEFAULT_STRING : [POS(2)] $BIT1;
(* Default FDL spec is a char string *)
FDL$V_FULL_OUTPUT : [POS(3)] $BIT1;
(* Produce a complete FDL spec *)
)
END;
mail_order = RECORD
order_num : [KEY(0)] INTEGER;
name : PACKED ARRAY[1..20] OF CHAR;
address : PACKED ARRAY[1..20] OF CHAR;
city : PACKED ARRAY[1..19] OF CHAR;
state : PACKED ARRAY[1..2] OF CHAR;
zip_code : [KEY(1)] PACKED ARRAY[1..5]
OF CHAR;
item_num : [KEY(2)] INTEGER;
shipping : REAL;
END;
order_file = [UNSAFE] FILE OF mail_order;
ptr_to_FAB = ^FAB$TYPE;
ptr_to_RAB = ^RAB$TYPE;
byte = 0..255;
VAR
order_master : order_file;
flags : FDL2$TYPE;
order_rec : mail_order;
temp_FAB : ptr_to_FAB;
temp_RAB : ptr_to_RAB;
status : integer;
FUNCTION LIB$SIGNAL
(%REF cond_val: INTEGER;
%IMMED num: INTEGER := %immed 0;
%STDESCR s1: PACKED ARRAY[L1..U1: INTEGER] OF CHAR := %IMMED 0;
%STDESCR s2: PACKED ARRAY[L2..U2: INTEGER] OF CHAR := %IMMED 0): INTEGER;
EXTERN;
FUNCTION FDL$PARSE
(%STDESCR FDL_FILE : PACKED ARRAY [L1..U1:INTEGER]
OF CHAR;
VAR FAB_PTR : PTR_TO_FAB;
VAR RAB_PTR : PTR_TO_RAB) : INTEGER; EXTERN;
FUNCTION FDL$GENERATE
(%REF FLAGS : FDL2$TYPE;
FAB_PTR : PTR_TO_FAB;
RAB_PTR : PTR_TO_RAB;
%STDESCR FDL_FILE_DST : PACKED ARRAY [L1..U1:INTEGER]
OF CHAR) : INTEGER;
EXTERN;
BEGIN
status := FDL$PARSE ('TESTING',TEMP_FAB,TEMP_RAB);
if not odd (status) then LIB$SIGNAL(status);
flags::byte := 0;
status := FDL$GENERATE (flags,
temp_FAB,
temp_RAB,
'SYS$OUTPUT:');
if not odd (status) then LIB$SIGNAL(status);
END.
|
For more information about FDL routines, see the OpenVMS Utility Routines Manual.
|
