VMS Help CONV$ Routines, CONV$CONVERT  *Conan The Librarian (sorry for the slow response - running on an old VAX)

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