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 – 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 – 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.
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.