The CONVERT routines perform the functions of both the Convert
and Convert/Reclaim utilities.
1 – CONV$CONVERT
The CONV$CONVERT routine uses the Convert utility to
perform the actual conversion begun with CONV$PASS_FILES and
CONV$PASS_OPTIONS. Optionally, the routine can return statistics
about the conversion.
Note that the CONV$CONVERT routine may return appropriate File
Definition Language (FDL) error messages to the calling program,
where applicable.
Format
CONV$CONVERT [status_block_address] [,flags]
[,callback_routine]
1.1 – 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.
1.2 – Arguments
status_block_address
OpenVMS usage:vector_longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
The conversion statistics. The status_block_address argument is
the address of a variable-length array of longwords that receives
statistics about the conversion.
You can request conversion statistics using zero-based, symbolic
offsets (CONV$K_) into the variable-length array of longwords
that contains the statistics. The array is defined as a structure
(CONV$STATISTICS) of named longwords (CONV$L_) to support access
by high-level progamming languages.
Conversion Statistics Array lists the array elements by number
and by symbol. The first element specifies the number of
statistics to return by array order. For example, if you assign
the symbol CONV$L_STATISTICS_COUNT the value 2, the routine
returns the statistics from the first two statistics elements:
o Number of files converted
o Number of records converted
Table 4-1 Conversion Statistics Array
Array
ElementField Name Description
0 CONV$L_STATISTICS_COUNT Number of statistics specified
1 CONV$L_FILE_COUNT Number of files
2 CONV$L_RECORD_COUNT Number of records
3 CONV$L_EXCEPT_COUNT Number of exception record
4 CONV$L_VALID_COUNT Number of valid records
5 CONV$L_KEY_NUMBER Most recent key processed
6 CONV$L_REC_OUT Number of records sorted
7 CONV$L_NODES Nodes in sort tree
8 CONV$L_WRK_ALQ Work file allocation
9 CONV$L_INI_RUNS Initial dispersion runs
10 CONV$L_MRG_ORDER Maximum merge order
11 CONV$L_MRG_PASSES Number of merge passes
12 CONV$L_SORT_DIO_COUNT Sort direct IO
13 CONV$L_SORT_BIO_COUNT Sort buffered IO
14 CONV$Q_SORT_ELAPSED_TIME Sort elapsed time
15 CONV$Q_SORT_CPU_TIME Sort CPU time
16 CONV$L_SORT_PF_COUNT Number of page faults for sort
17 CONV$L_LOAD_DIO_COUNT Load direct IO
18 CONV$L_LOAD_BIO_COUNT Load buffered IO
19 CONV$Q_LOAD_ELAPSED_TIME Load elapsed time
20 CONV$Q_LOAD_CPU_TIME Load CPU time
21 CONV$L_LOAD_PF_COUNT Number of page faults for load
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Flags (or masks) that control how the CONV$PASS_FILES fdl_
filespec argument 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 flags and their meanings are
described in the following table:
Flag Function
CONV$V_FDL_ Interprets the fdl_filespec argument supplied
STRING 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.
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.
callback_routine
OpenVMS usage:procedure
type: procedure value
access: read only
mechanism: by reference
Name of a user-supplied routine to process the statistics
information. The callback_routine argument is the address of
the procedure value of a user-supplied routine to call at the
completion of each key load.
1.3 – Condition Values Returned
SS$_NORMAL Normal successful completion.
CONV$_BADBLK Invalid option block.
CONV$_BADLOGIC Internal logic error detected.
CONV$_BADSORT Error trying to sort input file.
CONV$_CLOSEIN Error closing file specification as input.
CONV$_CLOSEOUT Error closing file specification as output.
CONV$_CONFQUAL Conflicting qualifiers.
CONV$_CREA_ERR Error creating output file.
CONV$_CREATEDSTM File specification has been created in stream
format.
CONV$_DELPRI Cannot delete primary key.
CONV$_DUP Duplicate key encountered.
CONV$_EXTN_ERR Unable to extend output file.
CONV$_FATALEXC Fatal exception encountered.
CONV$_FILLIM Exceeded open file limit.
CONV$_IDX_LIM Exceeded maximum index level.
CONV$_ILL_KEY Illegal key or value out of range.
CONV$_ILL_VALUE Illegal parameter value.
CONV$_INP_FILES Too many input files.
CONV$_INSVIRMEM Insufficient virtual memory.
CONV$_KEY Invalid record key.
CONV$_LOADIDX Error loading secondary index n.
CONV$_NARG Wrong number of arguments.
CONV$_NOKEY No such key.
CONV$_NOTIDX File is not an indexed file.
CONV$_NOTSEQ Output file is not a sequential file.
CONV$_NOWILD No wildcard permitted.
CONV$_OPENEXC Error opening exception file specification.
CONV$_OPENIN Error opening file specification as input.
CONV$_OPENOUT Error opening file specification as output.
CONV$_ORDER Routine called out of order.
CONV$_PAD Packet Assembly/Disassembly (PAD) option
ignored; output record format not fixed.
CONV$_PLV Unsupported prolog version.
CONV$_PROERR Error reading prolog.
CONV$_PROL_WRT Prolog write error.
CONV$_READERR Error reading file specification.
CONV$_REX Record already exists.
CONV$_RMS Record caused RMS severe error.
CONV$_RSK Record shorter than primary key.
CONV$_RSZ Record does not fit in block/bucket.
CONV$_RTL Record longer than maximum record length.
CONV$_RTS Record too short for fixed record format file.
CONV$_SEQ Record not in order.
CONV$_UDF_BKS Cannot convert UDF records into spanned file.
CONV$_UDF_BLK Cannot fit UDF records into single block
bucket.
CONV$_VALERR Specified value is out of legal range.
CONV$_VFC Record too short to fill fixed part of VFC
record.
CONV$_WRITEERR Error writing file specification.
2 – 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]
2.1 – 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.
2.2 – 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_ Interprets the fdl_filespec argument as an FDL
STRING 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.
2.3 – 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.
2.4 – 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.
3 – 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]
3.1 – 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.
3.2 – 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:
o As an array of named longwords using zero-based symbols
(CONV$L_ . . . )
o 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 CONVERT
Qualifiers. 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:
o /CREATE
o /SHARE
o /FAST_LOAD
The remaining qualifiers take the default values depicted in
CONVERT Qualifiers.
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 CONVERT Qualifiers.
Table 4-2 CONVERT Qualifiers
Longword
Element Default
Qualifier
Number Symbolic Value Value 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_ 0 Not applicable
PROLOGUE
21 CONV$L_SECONDARY 1 SECONDARY=1
Footnotes:
1. Default is a null pad character. To specify a non-null
pad character, insert the ASCII value of the desired pad
character.
2. Specify a 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:
o The value 0 (default) specifies the system or process prolog
type.
o 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.
o 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_ Interprets the fdl_filespec argument supplied
STRING 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.
3.3 – 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}
3.4 – 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.
4 – CONV$RECLAIM
The CONV$RECLAIM routine invokes the functions of the
Convert/Reclaim utility.
Format
CONV$RECLAIM input_filespec [,statistics_blk] [,flags]
[key_number]
4.1 – 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.
4.2 – 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.
Bucket Reclamation Statistics Array 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:
o Data buckets scanned
o Data buckets reclaimed
o Index buckets reclaimed
Table 4-3 Bucket Reclamation Statistics Array
Array
ElementField Name Description
0 RECL$L_STATISTICS_ Number of statistics specified
COUNT
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.
4.3 – 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.