HP OpenVMS Utility Routines Manual

CONV$PASS_FILES

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.

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.

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.

CONV$PASS_OPTIONS

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 ¹ 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 ²

20 CONV$L_IGNORE_PROLOGUE 0 Not applicable

21 CONV$L_SECONDARY 1 SECONDARY=1

**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 ¹	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 ²
20	CONV$L_IGNORE_PROLOGUE	0	Not applicable
21	CONV$L_SECONDARY	1	SECONDARY=1

¹Null character. To specify non-null pad character, insert ASCII value of desired pad character.
²System or process default setting.

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

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 the control flags (or a 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 supplied in the call to CONV$PASS_FILES as an FDL specification in string form. By default, this argument is interpreted as the file name of an FDL file.

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

Flag	Function
CONV$V_FDL_STRING	Interprets the fdl_filespec argument supplied in the call to CONV$PASS_FILES as an FDL specification in string form. By default, this argument is interpreted as the file name of an FDL file.
FDL$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

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.

CONV$RECLAIM

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.

**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

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.

Contents

Index

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

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

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.

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

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.

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

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.