HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

The CONV$PASS_FILES routine specifies a file to be converted using the CONV$CONVERT routine.

Format

CONV$PASS_FILES input_filespec ,output_filespec [,fdl_filespec] [,exception_filespec] [,flags]

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

input_filespec

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor---fixed-length string descriptor

The name of the file to be converted. The input_filespec argument is the address of a string descriptor pointing to the name of the file to be converted.

output_filespec

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor---fixed-length string descriptor

The name of the file that receives the records from the input file. The output_filespec argument is the address of a string descriptor pointing to the name of the file that receives the records from the input file.

fdl_filespec

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor---fixed-length string descriptor

The name of the FDL file that defines the output file. The fdl_filespec argument is the address of a string descriptor pointing to the name of the FDL file.

exception_filespec

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor---fixed-length string descriptor

The name of the file that receives copies of records that cannot be written to the output file. The exception_filespec argument is the address of a string descriptor pointing to this name.

flags

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Flags (or masks) that control how the fdl_filespec argument is interpreted and how errors are signaled. The flags argument is the address of a longword containing the control flags (or mask). If you omit this argument or specify it as zero, no flags are set. If you specify a flag, it remains in effect until you explicitly reset it in a subsequent call to a CONVERT routine.

The flags and their meanings are described in the following table:

Flag	Function
CONV$V_FDL_STRING	Interprets the fdl_filespec argument as an FDL specification in string form. By default, this argument is interpreted as a file name of an FDL file.
CONV$V_SIGNAL	Signals any error. By default, the status code is returned to the calling image.

By default, an error status is returned rather than signaled.

Description

The CONV$PASS_FILES routine specifies a file to be converted using the CONV$CONVERT routine. A single call to CONV$PASS_FILES allows you to specify an input file, an output file, an FDL file, and an exception file. If you have multiple input files, you must call CONV$PASS_FILES once for each file. You need to specify only the input_filespec argument for the additional files, as follows:

status = CONV$PASS_FILES (input_filespec)

The additional calls must immediately follow the original call that specified the output file specification.

Wildcard characters are not allowed in the file specifications passed to the CONVERT routines.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
CONV$_INP_FILES	Too many input files.
CONV$_INSVIRMEM	Insufficient virtual memory.
CONV$_NARG	Wrong number of arguments.
CONV$_ORDER	Routine called out of order.

The CONV$PASS_OPTIONS routine specifies which qualifiers are to be used by the Convert utility (CONVERT).

Format

CONV$PASS_OPTIONS [parameter_list_address] [,flags]

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

parameter_list_address

OpenVMS usage:	vector_longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Address of a variable-length array of longwords used to specify the CONVERT qualifiers. The array is symbolically defined as a structure (CONV$OPTIONS) that you can access in one of the following ways:

• As an array of named longwords using zero-based symbols (CONV$L_...)
• As an array using zero-based offsets (CONV$K_...)

The first longword in the array (CONV$L_OPTIONS_COUNT) specifies the number of elements in the array, and each remaining element is associated with a CONVERT qualifier, as shown in Table 6-2. You can use the first element to assign values to the first n CONVERT qualifiers---where n is the value of CONV$L_OPTIONS_COUNT---and take default values for the remaining qualifiers. For example, to assign values to only the first three qualifiers and to take the default value for the remaining qualifiers, specify CONV$L_OPTIONS_COUNT=3. This effectively changes the size of the array to include only the first three elements, as follows, which have values you specify:

• /CREATE
• /SHARE
• /FAST_LOAD

The remaining qualifiers take the default values depicted in Table 6-2.

To assign individual values to the CONVERT qualifiers, access the array and specify the desired value (1 or 0). See the OpenVMS Record Management Utilities Reference Manual for detailed descriptions of the CONVERT qualifiers.

If you do not specify parameter_list_address, your program effectively sends the routine all of the default values listed in Table 6-2.

Table 6-2 CONVERT Qualifiers

Element Number	Symbolic Value	Longword Default Value	Qualifier Default Value
0	CONV$L_OPTIONS_COUNT	None	Not applicable
1	CONV$L_CREATE	1	/CREATE
2	CONV$L_SHARE	0	/NOSHARE
3	CONV$L_FAST	1	/FAST_LOAD
4	CONV$L_MERGE	0	/NOMERGE
5	CONV$L_APPEND	0	/NOAPPEND
6	CONV$L_SORT	1	/SORT
7	CONV$L_WORK_FILES	2	/WORK_FILES=2
8	CONV$L_KEY	0	/KEY=0
9	CONV$L_PAD	0	/NOPAD
10	CONV$L_PAD_CHARACTER	0 1	Pad character=0
11	CONV$L_TRUNCATE	0	/NOTRUNCATE
12	CONV$L_EXIT	0	/NOEXIT
13	CONV$L_FIXED_CONTROL	0	/NOFIXED_CONTROL
14	CONV$L_FILL_BUCKETS	0	/NOFILL_BUCKETS
15	CONV$L_READ_CHECK	0	/NOREAD_CHECK
16	CONV$L_WRITE_CHECK	0	/NOWRITE_CHECK
17	CONV$L_FDL	0	/NOFDL
18	CONV$L_EXCEPTION	0	/NOEXCEPTION
19	CONV$L_PROLOGUE	None	/PROLOGUE= n 2
20	CONV$L_IGNORE_PROLOGUE	0	Not applicable
21	CONV$L_SECONDARY	1	SECONDARY=1

If you specify /EXIT and the utility encounters an exception record, CONVERT returns with a fatal exception status.

If you specify an FDL file specification in the CONV$PASS_FILES routine, you must place a 1 in the FDL longword. If you also specify an exceptions file specification in the CONV$PASS_FILES routine, you must place a 1 in the EXCEPTION longword. You may specify either, both, or neither of these files, but the values in the CONV$PASS_FILES call must match the values in the parameter list. If they do not, the routine returns an error.

The PROLOG longword overrides the KEY PROLOG attribute supplied by the FDL file. If you use the PROLOG longword, enter one of the following values:

• The value 0 (default) specifies the system or process prolog type.
• The value 2 specifies a Prolog 1 or 2 file in all instances, even when circumstances would allow you to create a Prolog 3 file.
• The value 3 specifies a Prolog 3 file. If a Prolog 3 file is not allowed, you want the conversion to fail.

If the size of the options block that you pass to CONV$PASS_OPTIONS includes the SECONDARY longword value, then you must specify a value for the IGNORE_PROLOGUE field.

This field is used in conjunction with the PROLOGUE offset to determine if the prologue version of the output file is to be taken from a passed FDL, the input file, the process default or system default, or from the options block itself.

A value of 0 (zero) for the IGNORE_PROLOGUE field indicates that the prologue version of the output file is to be taken from the PROLOGUE value specified in the options block.

If the PROLOGUE value in the options block contains a 0 (zero), the process default or system default prologue version will be used. This will override the prologue version specified in an FDL file or in the input file's characteristics.

A value of 1 (one) for the IGNORE_PROLOGUE field implies that the prologue version of the output file will come from the FDL file (if specified) or from the input file's characteristics.

flags

The flags and their meanings are described in the following table:

By default, an error status is returned rather than signaled.

Description

You can use an options array to generate programmatic CONVERT commands. For example, you can generate the following programmatic CONVERT command by configuring the options array described by the pseudocode that follows the example command line:

$ CONVERT/FAST_LOAD/SORT/WORK_FILES=6/EXIT

OPTIONS ARRAY [12] {Allocate a 13-cell array} OPTIONS[0] = 12 {Number of options] OPTIONS[1] = 1 {Specifies the /CREATE option} OPTIONS[2] = 0 {Specifies the /NOSHARE option} OPTIONS[3] = 1 {Specifies the /FAST_LOAD option} OPTIONS[4] = 0 {Specifies the /NOMERGE option} OPTIONS[5] = 0 {Specifies the /NOAPPEND option} OPTIONS[6] = 1 {Specifies the /SORT option} OPTIONS[7] = 6 {Specifies the /WORK_FILES=6 option} OPTIONS[8] = 0 {Specifies the /KEY=0 option} OPTIONS[9] = 0 {Specifies the /NOPAD option} OPTIONS[10] = 0 {Specifies the null pad character} OPTIONS[11] = 0 {Specifies the /NOTRUNCATE option} OPTIONS[12] = 1 {Specifies the /EXIT option}

Condition Values Returned

SS$_NORMAL	Normal successful completion.
CONV$_BADBLK	Invalid option block.
CONV$_CONFQUAL	Conflicting qualifiers.
CONV$_INSVIRMEM	Insufficient virtual memory.
CONV$_NARG	Wrong number of arguments.
CONV$_OPENEXC	Error opening exception file file specification.
CONV$_ORDER	Routine called out of order.

The CONV$RECLAIM routine invokes the functions of the Convert/Reclaim utility.

Format

CONV$RECLAIM input_filespec [,statistics_blk] [,flags] [key_number]

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

input_filespec

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor---fixed-length string descriptor

Name of the Prolog 3 indexed file to be reclaimed. The input_filespec argument is the address of a string descriptor pointing to the name of the Prolog 3 indexed file.

statistics_blk

OpenVMS usage:	vector_longword_unsigned
type:	longword (unsigned)
access:	modify
mechanism:	by reference

Bucket reclamation statistics. The statistics_blk argument is the address of a variable-length array of longwords that receives statistics on the bucket reclamation. You can choose which statistics you want returned by specifying a number in the first element of the array. This number determines how many of the four possible statistics the routine returns.

You can request bucket reclamation statistics using symbolic names or numeric offsets into the variable-length array of longwords that contains the statistics. The array is defined as a structure of named longwords (RECL$STATISTICS) to support access by high-level progamming languages.

Table 6-3 lists the array elements by number and by symbol. The first element specifies one or more statistics by array order. For example, if you assign the symbol RECL$L_STATISTICS_COUNT the value 3, the routine returns the statistics from the first three statistics elements:

• Data buckets scanned
• Data buckets reclaimed
• Index buckets reclaimed

Table 6-3 Bucket Reclamation Statistics Array

Array Element	Field Name	Description
0	RECL$L_STATISTICS_COUNT	Number of statistics specified
1	RECL$L_SCAN_COUNT	Data buckets scanned
2	RECL$L_DATA_COUNT	Data buckets reclaimed
3	RECL$L_INDEX_COUNT	Index buckets reclaimed
4	RECL$L_TOTAL_COUNT	Total buckets reclaimed

flags

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Flags (or masks) that control how the fdl_filespec argument, used in calls to the CONV$PASS_FILES routine, is interpreted and how errors are signaled. The flags argument is the address of a longword containing control flags (or a mask). If you omit the flags argument or specify it as zero, no flags are set. The flag is defined as follows:

CONV$V_SIGNAL

Signals any error. By default, the status code is returned to the calling image.

By default, an error status is returned rather than signaled.

key_number

OpenVMS usage:	address
type:	longword (unsigned)
access:	read only
mechanism:	by reference

The optional key_number argument permits the calling program to selectively reclaim buckets by key number. If the calling program omits this argument or passes a NULL value in the argument, all buckets are reclaimed, without regard to key designation. If the calling program passes a valid key number as the value for this argument, the routine reclaims only the buckets for the specified key.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
CONV$_BADLOGIC	Internal logic error detected.
CONV$_INSVIRMEM	Insufficient virtual memory.
CONV$_INVBKT	Invalid bucket at VBN n.
CONV$_NOTIDX	File is not an indexed file.
CONV$_NOWILD	No wildcard permitted.
CONV$_OPENIN	Error opening file specification as input.
CONV$_PLV	Unsupported prolog version.
CONV$_PROERR	Error reading prolog.
CONV$_PROL_WRT	Prolog write error.
CONV$_READERR	Error reading file specification.
CONV$_WRITEERR	Error writing output file.