Library /sys$common/syshlp/helplib.hlb  —  CONV$ Routines
    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.
Close Help