Document revision date: 30 March 2001

The Convert/Reclaim utility (CONVERT/RECLAIM) reclaims empty buckets in Prolog 3 indexed file on local and remote nodes. Using the /KEY qualifier, you can reclaim index buckets for specific keys. If you request statistics and specify a group of keys, the Convert/Reclaim utility returns statistics separately for each specified key.

Unlike the Convert utility, the Convert/Reclaim utility preserves the RFAs from the input file. In general, the Convert utility provides more efficient indexed files than the Convert/Reclaim utility.

You can use callable routines to perform Convert/Reclaim utility functions from within a program. For more information, refer to the CONVERT routines in the OpenVMS Utility Routines Manual.

3.1 Using the Convert/Reclaim Utility

The Convert/Reclaim utility reclaims empty buckets in an existing Prolog 3 indexed file. The organization, record format, and key order of the file are not changed.

When you delete all the records in a bucket, it still retains its position within the database because it has a specified range of primary key values associated with it. When you write new records to the file, the records with primary key in the specified range are written to the bucket.

If your application has buckets with records that do not use a primary key left over from a deleted record, empty buckets cannot be reused unless you reclaim them. To reclaim a bucket, the Convert/Reclaim utility deletes the old pointers to it and puts it on a list of free buckets. When an application adds records and needs a bucket, RMS goes to the free bucket list and sets up pointers to a bucket from the free bucket list. By reclaiming buckets, you may avoid extending the file, thereby optimizing processing efficiency.

Another benefit in using the Convert/Reclaim utility is that the utility preserves RFA (record file address) access to the file.

You cannot use the Convert/Reclaim utility on Prolog 1 or Prolog 2 indexed files. To reclaim empty buckets in a Prolog 1 or Prolog 2 indexed file, you must first reorganize the file by using the Convert utility. This reorganization creates a new version of the file. Note however, that the Convert utility establishes new RFAs for the file records.

To invoke the Convert/Reclaim utility from within a program, use the callable CONV$RECLAIM routine. For more information, refer to the OpenVMS Utility Routines Manual.

CONVERT/RECLAIM Usage Summary

The Convert/Reclaim utility (CONVERT/RECLAIM) reclaims empty buckets in Prolog 3 indexed files so that new records can be written into the reclaimed buckets. The output file retains the same record format, file organization, and key order as the input file.

Format

CONVERT/RECLAIM filespec

filespec

Specifies the Prolog 3 indexed file in which you want to reclaim buckets. When you use the CONVERT/RECLAIM command, the file cannot be opened for shared access.

If you want to execute CONVERT/RECLAIM commands over a network, you need NETMBX privilege.

Qualifiers

This section describes the CONVERT/RECLAIM command qualifiers. Using these qualifiers, you can reclaim index buckets by key and you can also request reclamation statistics.

/KEY

The /KEY qualifier lets you reclaim index buckets for specified keys.

Format

/KEY=key_number[,...] filename

Qualifier Values

key_number

Specifies the key number for the buckets to be reclaimed.

filename

Specifies the name of the index file containing the buckets to be reclaimed.

Description

If you request statistics and specify the /KEY qualifier, the utility reports the statistics for each key separately. If you do not use the /KEY qualifier, the default is to reclaim all index buckets and to provide a single report.

Determines whether statistics about the completed conversion and reclamation are displayed. If you do not specify reclamation of index buckets by key, all buckets are reclaimed and a single statistics report is generated. If you specify reclamation of index buckets by key, a separate set of statistics is returned for each specified key.

Format

/STATISTICS

/NOSTATISTICS (DEFAULT)

Description

The Convert/Reclaim utility provides the following statistics:

• Total buckets scanned
• Data buckets reclaimed
• Index buckets reclaimed
• Total buckets reclaimed
• Elapsed time
• Buffered I/O
• Direct I/O
• Page faults
• CPU time

The File Definition Language facility includes the File Definition Language (FDL), the Create/FDL utility (see Chapter 5), and the Edit/FDL utility (see Chapter 6). This chapter describes the File Definition Language.

4.1 Overview

The File Definition Language facility helps you design data files that can be processed efficiently by using a model file (FDL file) whose attributes (characteristics) are subsequently applied to the data file. This section provides an overview of an FDL file, briefly describing each of its primary attributes. Other sections expand on each of the primary attributes, presenting them in alphabetical order.

An FDL file is a collection of file sections, where each section describes a file attribute. The file sections appear in the following order:

• TITLE
• IDENT
• SYSTEM
• FILE
• DATE
• RECORD
• ACCESS
• NETWORK
• SHARING
• CONNECT
• AREA
• KEY
• ANALYSIS_OF_AREA
• ANALYSIS_OF_KEY

Each section may include a lower order of file characteristics called secondary attributes, and some secondary attributes have a third level of attributes called qualifiers. An FDL file consists of attribute keywords followed by their assigned values. Lowercase letters and uppercase letters are equivalent and can be used interchangeably. Secondary attributes can be either create-time attributes or run-time attributes. Create-time attribute values are established when the file is created. Run-time attributes are established just prior to an application's opening or connecting to an existing file by calling the FDL$PARSE routine and by passing the routine the applicable FDL file specification. See the OpenVMS Utility Routines Manual for details about using the FDL$PARSE routine.

Attributes take one of the following value types:

Switch	A logical value set to TRUE (YES) or FALSE (NO). TRUE or YES asserts the attribute; FALSE or NO negates it. You can abbreviate the logical values to T (TRUE), Y (YES), F (FALSE), and N (NO).
Keyword	One or more words that follow the attribute name. When you use multiple keywords with an attribute, you must enclose them in parentheses and separate them by commas. You can truncate a keyword to its unique leading character(s).
String value	A character string that follows the attribute name. You should enclose a string value in a pair of single or double quotation marks. The null string is a valid string value.
Number	A decimal number.

The following sections describe primary and secondary attributes and contain cross-references to corresponding fields (parameters) in RMS control blocks. The term DECnet for OpenVMS operations refers to remote file access between two OpenVMS operating systems and, unless stated otherwise, attributes are supported for DECnet for OpenVMS operations.

4.2 ACCESS Section

The ACCESS primary attribute allows you to specify file-processing operations by assigning appropriate values to the secondary attributes. The ACCESS keyword takes no values; it serves only to define this section.

The following table lists the ACCESS secondary attributes and their default values. Note that all of the ACCESS secondary attributes are run-time attributes.

Secondary Attribute	Default Value
BLOCK_IO	FALSE
DELETE	FALSE
GET	GET when performing an Open service
PUT	PUT when performing a Create service
RECORD_IO	FALSE
TRUNCATE	FALSE
UPDATE	FALSE

BLOCK_IO

This switch specifies block I/O operations involving either the Read or the Write RMS service, depending on whether you have specified the GET (Read service) or the PUT (Write service) ACCESS secondary attributes. If you specify BLOCK_IO, no record I/O operations (such as DELETE, GET, PUT, TRUNCATE, or UPDATE) can be performed. The BLOCK_IO secondary attribute also permits you to use the Space service.

The BLOCK_IO attribute corresponds to the BIO option in the FAB$B_FAC field.

DELETE

This switch enables Delete operations. The DELETE attribute corresponds to the DEL option in the FAB$B_FAC field.

GET

This switch specifies either the Get or the Find RMS service. GET is the default when you are opening the file and when one of the following conditions exists:

• No other ACCESS section secondary attribute is defined.
• The DELETE or UPDATE secondary attributes in the SHARING section have been specified.

If you also specify the BLOCK_IO attribute, you can perform Read services. The GET attribute corresponds to the GET option in the FAB$B_FAC field.

PUT

This switch specifies the Put service or the Extend service. PUT is the default when you create a file. If you specify the PUT attribute and the BLOCK_IO attribute, you can perform Write services.

The PUT attribute corresponds to the PUT option in the FAB$B_FAC field.

RECORD_IO

This switch allows mixed record I/O and block I/O operations under certain circumstances (see the OpenVMS Record Management Services Reference Manual for more information).

The RECORD_IO attribute corresponds to the BRO option in the FAB$B_FAC field.

TRUNCATE

This switch allows Truncate operations. The TRUNCATE attribute corresponds to the TRN option in the FAB$B_FAC field.

UPDATE

This switch selects either the Update service or the Extend service. The UPDATE attribute corresponds to the UPD option in the FAB$B_FAC field.

The Analyze/RMS_File utility (ANALYZE/RMS_FILE) creates the ANALYSIS_OF_AREA section and supplies it with values. The ANALYSIS_OF_AREA section appears only in FDL files that describe indexed files.

This primary section has only one secondary attribute: the run-time attribute RECLAIMED_SPACE.

RECLAIMED_SPACE

ANALYZE/RMS_FILE supplies a number value for the RECLAIMED_SPACE secondary attribute that represents the number of blocks in the area reclaimed by the Convert utility (CONVERT) using the /RECLAIM qualifier. For more information about using CONVERT/RECLAIM, see Chapter 3.

ANALYZE/RMS_FILE creates the ANALYSIS_OF_KEY section and supplies appropriate values. The Edit/FDL utility uses the ANALYSIS_OF_KEY section in its Optimize script for FDL files that define an indexed file.

The primary attribute ANALYSIS_OF_KEY has a numeric value that represents the key being analyzed (0 is the primary key).

The following table lists the ANALYSIS_OF_KEY secondary attributes. Note that all ANALYSIS_OF_KEY secondary attributes are run-time attributes. All values returned to the attributes are numerical.

Secondary Attribute	Default Value
DATA_FILL	None
DATA_KEY_COMPRESSION	None
DATA_RECORD_COMPRESSION	None
DATA_RECORD_COUNT	None
DATA_SPACE_OCCUPIED	None
DEPTH	None
DUPLICATES_PER_SIDR	None
INDEX_COMPRESSION	None
INDEX_FILL	None
INDEX_SPACE_OCCUPIED	None
LEVEL1_RECORD_COUNT	None
MEAN_DATA_LENGTH	None
MEAN_INDEX_LENGTH	None

DATA_FILL

This attribute shows the percentage of bytes per bucket in the data level that has been filled.

DATA_KEY_COMPRESSION

This attribute shows the percentage of compression achieved for the primary keys. For example, if the keys added up to 1000 bytes and compression reduced that figure to 600 bytes, the value shown in the DATA_KEY_COMPRESSION attribute would be 40 (representing 40 percent compression).

Negative compression might occur because of the overhead involved. If you see a negative value, you should disable that type of compression in the KEY section.

DATA_RECORD_COMPRESSION

This attribute shows the percentage of compression that has occurred in the level 0 data record. For example, if compression reduces the number of bytes in the data records added from 100,000 to 70,000, the value shown in the DATA_RECORD_COMPRESSION attribute would be 30 (representing 30 percent compression).

Negative compression might occur because of the overhead involved. If you see a negative value, you should disable that type of compression in the KEY section.

This attribute applies only to the primary key.

DATA_RECORD_COUNT

This attribute shows the number of data records in the file.

DATA_SPACE_OCCUPIED

This attribute shows the size, in blocks, of the level 0 of the index structure.

DEPTH

This attribute shows the number of index levels in the index structure. The value does not include the data level.

DUPLICATES_PER_SIDR

This attribute shows the average number of duplicate key values for the secondary index data records (SIDR); that is, the value is the total number of duplicates divided by the total number of SIDRs.

This attribute applies only to alternate keys.

INDEX_COMPRESSION

This attribute shows the percentage of compression that has occurred in the index records within the index levels. If the full indexes amounted to 10,000 bytes and compression reduced this value to 8000 bytes, the value shown in the INDEX_COMPRESSION attribute would be 20 (representing 20 percent).

INDEX_FILL

This attribute shows the percentage of bytes per bucket that have been filled in the index levels.

INDEX_SPACE_OCCUPIED

This attribute shows the size, in blocks, of the index levels (level 1 and greater).

LEVEL1_RECORD_COUNT

This attribute indicates the number of records in the level 1 index, which is the index level immediately above the data. When duplicate key values (for SIDRs) have been specified, even when SIDR overflow buckets exist, the tuning algorithm of EDIT/FDL is made more accurate.

Generally, every bucket on level 0 of an alternate key has a pointer record from level 1 of the alternate key. However, there are no pointers from level 1 to any overflow buckets. LEVEL1_RECORD_COUNT keeps track of how many records are in level 1, particularly when duplicate key values force overflow buckets to be created.

MEAN_DATA_LENGTH

This attribute shows the average length, in bytes, of the data records. This does not take compression into account.

MEAN_INDEX_LENGTH

This attribute shows the average length, in bytes, of the index records. This does not take compression into account.

The AREA section is an RMS-specific region of an indexed file that you cannot create or manipulate from a high-level programming language. RMS provides appropriate areas for you when you create an indexed file.

If you want to create or manipulate areas in an indexed file, you must include the AREA primary attribute in an FDL file. The AREA primary attribute acts as a header for a section in the FDL file that describes areas. It takes a numeric value in the range 0 to 254 that identifies the area. To define multiple areas for an indexed file, you must specify a separate AREA section for each area.

Most AREA secondary attributes (except for the EXACT_POSITIONING, POSITION, and VOLUME secondary attributes) have corresponding FILE secondary attributes. The values you specify for AREA secondary attributes override values you specify for corresponding secondary attributes in the FILE section.

The AREA primary attribute corresponds to the XAB$B_AID field in a XAB (extended attribute block).

The following table lists the AREA secondary attributes and their default values. Note that all AREA secondary attributes are create-time attributes.

Secondary Attribute	Default Value
ALLOCATION	0
ASYNCHRONOUS	FALSE
BEST_TRY_CONTIGUOUS	FALSE
BUCKET_SIZE	0
CONTIGUOUS	FALSE
EXACT_POSITIONING	FALSE
EXTENSION	0
POSITION	None
VOLUME	0

ALLOCATION

This numeric attribute establishes the initial number of blocks allocated to an area. Its value must be an integer in the range 0 to 4,294,967,295. If you take the default value of 0, the system allocates no space for the area.

The ALLOCATION attribute corresponds to the XAB$L_ALQ field in a XAB.

ASYNCHRONOUS

This switch specifies that the task is to be done asynchronously. This option is relevant only to file tasks that involve I/O operations. It is typically used with success/error ASTs, or in conjunction with the $WAIT service, to synchronize the program with task completion.

The ASYNCHRONOUS attribute corresponds to the FAB$V_ASY bit in the FAB$L_FOP field.

BEST_TRY_CONTIGUOUS

This switch controls whether an area is allocated contiguous space, assuming there is enough space for it. If you set the switch to YES and there is not enough space, the area is allocated noncontiguously.

If you take the default, NO, this attribute has no effect.

The BEST_TRY_CONTIGUOUS attribute corresponds to the CBT option in the XAB$B_AOP field.

BUCKET_SIZE

This numeric attribute establishes the number of blocks per bucket for this area. Its value must be an integer in the range 0 to 63. If you take the default value of 0, RMS calculates the smallest bucket size capable of holding the largest record. If RMS--11 is to process the file, the bucket size is limited to 32 blocks.

The BUCKET_SIZE attribute corresponds to the XAB$B_BKZ field.

CONTIGUOUS

This switch controls whether RMS allocates contiguous space for the file. If there is not enough contiguous space, RMS returns an error when you try to create the file.

When you take the default, NO, FDL ignores this attribute.

The CONTIGUOUS attribute corresponds to the CTG option in the XAB$B_AOP field.

EXACT_POSITIONING

This switch mandates that the area is allocated the precise location you specify with either the POSITION CYLINDER attribute or the POSITION LOGICAL attribute. If the location is not available, RMS returns an error. When you take the default (NO), RMS allocates the area nearest the specified location.

The EXACT_POSITIONING attribute corresponds to the HRD option in the XAB$B_AOP field.

EXTENSION

This numeric attribute establishes the area's default extension size, in blocks. The extension is the space added to the area when the allocated space is filled.

This value must be an integer in the range 0 to 65,535. If you take the default (0), the system determines the extension size.

The EXTENSION attribute corresponds to the XAB$W_DEQ field.

POSITION

This attribute establishes the location of the area and takes one of the following keyword values:

ANY_CYLINDER	This keyword begins the area on any cylinder boundary.
CYLINDER	This keyword begins the area on the specified cylinder boundary.
FILE_ID	This keyword positions the area as close to the specified file as possible. You must use a value for an existing file that includes the file identification number (FID), the file sequence number, and the relative volume number. The FILE_ID attribute uses the following syntax, including parentheses: (FID-num,FID-seq,RVN)
FILE_NAME	This keyword positions the area as close to the specified file as possible; you must specify an existing file. The FILE_NAME attribute is not supported for DECnet for OpenVMS operations; use the keyword NONE.
LOGICAL	This keyword positions the start of the area at the specified logical block.
NONE	This keyword is the default value; it means you do not want to control the placement of the area.
VIRTUAL	This keyword positions the start of the area at the specified virtual block.

The POSITION attribute corresponds to the XAB$B_ALN, XAB$L_LOC, and XAB$W_RFI fields in a XAB. This attribute is not supported for DECnet for OpenVMS operations; use the keyword NONE.

VOLUME

This attribute specifies the area location by using the relative volume number in a Files-11 disk volume set.

You must specify an integer in the range 0 to 255. If you take the default, 0, it means that you do not want to control the area's placement on the volume set.

The VOLUME attribute corresponds to the XAB$W_VOL field.

	privacy and legal statement
6027PRO_005.HTML