HELPLIB.HLB  —  CONVERT  file
    Invokes the Convert utility (CONVERT) to copy records from
    one file to another, changing the organization and format of
    the input file to those of the output file. For a complete
    description of the Convert utility, including more
    information about the CONVERT command and its qualifiers, see
    the OpenVMS Record Management Utilities Reference Manual.

    Format

      CONVERT input-filespec[,...]  output-filespec

1  –  Parameters

 input-filespec [,...]

    Specifies the file or files to be converted. You may specify
    multiple input files but wildcard characters are not allowed.
    Multiple input files are concatenated to form a single output
    file.

 output-filespec

    Specifies the output file for the converted records. If you omit
    the file type, the Convert utility assigns the output file the
    file type of the first input file. No wildcard characters are
    allowed.

2  –  Qualifiers

2.1    /APPEND

    Controls whether converted records from an input file are
    appended to an existing sequential file.

    Format

      /APPEND

      /NOAPPEND  (DEFAULT)

    The /APPEND qualifier is useful when you want to convert an
    existing file to the format of an existing output file and append
    the converted records to the existing output file.

    If you specify the /APPEND qualifier and the /CREATE qualifier,
    /APPEND overrides the /CREATE.

    You should use this option when you are loading records into
    a sequential file that already contains records, or when you
    are creating a new sequential file. When the output file is a
    direct access file (relative or indexed), the /APPEND qualifier
    is ignored.

2.2    /CREATE

    Determines whether the Convert utility creates a file or uses an
    existing file for output.

    Format

      /CREATE  (DEFAULT)

      /NOCREATE

    The /CREATE qualifier causes the Convert utility to create an
    output file instead of using an existing file for output.

    If the output file is to have different characteristics from the
    input file, you must also specify the /FDL qualifier.

2.3    /EXCEPTIONS_FILE

    Specifies whether an exceptions file (file type .EXC) is to be
    generated during the conversion.

    Format

      /EXCEPTIONS_FILE  [=filespec]

      /NOEXCEPTIONS_FILE  (DEFAULT)

    Specifies the file in which the exception records are returned.
    If you specify /EXCEPTIONS_FILE but omit the filespec parameter,
    the exception records are displayed on the SYS$OUTPUT device.

2.4    /EXIT

    Controls whether the Convert utility exits when it encounters
    an exception record. By default, the Convert utility continues
    processing records when it encounters an exception record.

    Format

      /EXIT

      /NOEXIT  (DEFAULT)

2.5    /FAST_LOAD

    Specifies whether the Convert utility uses a fast-loading
    algorithm for indexed files.

    Format

      /FAST_LOAD  (DEFAULT)

      /NOFAST_LOAD

    By default, the Convert utility uses the fast-loading algorithm,
    but if CONVERT/FAST_LOAD is executed across a network, the
    Convert utility automatically changes from /FAST_LOAD to
    /NOFAST_LOAD.

2.6    /FDL

    Indicates that an FDL file is to be used in creating the output
    file.

    Format

      /FDL=fdl-filespec

    Specifies the FDL file to be used in creating the output file.
    The newly created output file will have the name specified by the
    fdl-filespec command parameter; this name overrides any file name
    specified in the FDL file.

    The default file type for the FDL file is .FDL.

2.7    /FILL_BUCKETS

    Controls whether to override the bucket fill percentage parameter
    associated with the output file.

    Format

      /FILL_BUCKETS

      /NOFILL_BUCKETS  (DEFAULT)

    If you specify /FILL_BUCKETS, the Convert utility fills the
    output file buckets with as many records as possible. This option
    is valid only for indexed output files.

2.8    /FIXED_CONTROL

    Controls file conversions between files having variable-length
    with fixed-length control field (VFC) records and files having
    other record formats.

    Format

      /FIXED_CONTROL

      /NOFIXED_CONTROL  (DEFAULT)

    This qualifier applies only to conversions where either the input
    or the output file, but not both, uses VFC records. This option
    is applicable only to sequential files.

    o  If you specify /FIXED_CONTROL and the input file uses VFC
       records but the output file does not, the fixed-length control
       field from the input record is inserted into the output record
       as data.

    o  If you specify /FIXED_CONTROL and the output file has VFC
       records but the input file does not, the leading part of the
       input record is used to fill the fixed-length control part of
       the output record.

    o  If you specify /NOFIXED_CONTROL and the input file uses VFC
       records but the output file does not, the fixed-length control
       field from the input record is not included as data in the
       output record.

    o  If you specify /NOFIXED_CONTROL and the output file has
       VFC records but the input file does not, the control field
       attached to the output record is set to null.

2.9    /KEY

    Directs the Convert utility to read records from an indexed file
    using a specified key of reference, such as the primary key, the
    first alternate key, or the second alternate key.

    Format

      /KEY=n

    A numeric value that specifies the key of reference that the
    Convert utility uses for reading records from the input indexed
    file. For example, you can specify the primary key as the key of
    reference by using the value 0 (/KEY=0), which is the default, or
    you can specify the first alternate key as the key of reference
    by using the value 1 (/KEY=1). The /KEY qualifier is valid for
    indexed input files only. If you use the /KEY qualifier, you
    must specify a key value (/KEY=0, /KEY=1, and so on). If you do
    not specify the /KEY qualifier, the default is the primary key
    (/KEY=0).

2.10    /MERGE

    Specifies that records are to be inserted into their proper
    position in an existing indexed file.

    Format

      /MERGE

      /NOMERGE  (DEFAULT)

    The /MERGE qualifier is useful when your input records are not
    sorted and you do not want them to be sorted as they are loaded
    into an output file.

    If you specify both /MERGE and /CREATE, /MERGE overrides the
    /CREATE qualifier.

2.11    /PAD

    Determines whether short records are to be padded.

    Format

      /PAD  [=[%b]x]

      /NOPAD  (DEFAULT)

    Specifies that the short records are to be padded with either
    ASCII characters (A through Z, a through z, or 0 through 9) or
    numeric values.

    To specify x as a numeric value, you must specify the numeric
    base using the percent symbol (%)  followed by one of the
    following characters:

    D    Indicates that x is a decimal number.
    O    Indicates that x is an octal number.
    X    Indicates that x is a hexadecimal number.

    The numeric value can be any number from 0 to 255.

2.12    /PROLOG

    Specifies the prolog version number of the output indexed file.

    Format

      /PROLOG=n

    Specifies the prolog number 1, 2, or 3.

    If you specify 2 for n, the output file will be either a Prolog 1
    or a Prolog 2 file.

    If you specify 3, the Convert utility creates a Prolog 3 file
    for output. Prolog 3 files accept multiple keys (or alternate
    keys), all data types, and segmented keys. The only restriction
    to using a Prolog 3 file applies to files containing overlapping
    key segments for the primary key. In this case, you would have to
    use a Prolog 2 file. If you do not specify the /PROLOG qualifier,
    the Convert utility uses the prolog version of the first input
    file. If the input file is not indexed, the utility uses the RMS
    default. To see what this default is on your system, enter the
    DCL command SHOW RMS_DEFAULT.

    The /PROLOG qualifier overrides the value given with the FDL
    attribute KEY PROLOG.

2.13    /READ_CHECK

    Specifies whether each input record is to be read from the file a
    second time and compared to the record originally read.

    Format

      /READ_CHECK

      /NOREAD_CHECK  (DEFAULT)

2.14    /SECONDARY

    Increases the Convert utility's performance by reducing the
    number of required passes through the input data. This is
    accomplished by placing alternate key information into the
    CONVWORK file.

    Format

    /SECONDARY=n

    Qualifier Value
    n
    Specifies the number of alternate keys that will be loaded to
    the CONVWORK file with each pass through the input data.

    This qualifier is valid when you are fast-loading a file with
    more than one alternate key. This option allows CONVERT to use
    more disk space for its work file than would be used by default.

    The default number of alternate keys written to the CONVWORK
    file is 1.

2.15    /SHARE

    Specifies whether the input file is to be opened for sharing with
    other processes during the conversion.

    Format

      /SHARE

      /NOSHARE  (DEFAULT)

    You can use the /SHARE option to generate a rough backup of a
    file that is always opened for sharing by some applications.
    However, another process can alter the records during the Convert
    utility operations. As a result, the consistency of the output
    file cannot be guaranteed.

2.16    /SORT

    Specifies whether the input file is to be sorted before being
    loaded into an indexed file. The sort is done according to the
    primary key of the output file.

    Format

      /SORT [=FORCE]  (DEFAULT)

      /NOSORT

    Two procedures can improve the sort performance:

    o  Increasing the size of the working set for the duration of the
       sort.

    o  Placing the input file, the output file, and the temporary
       work files on separate disk devices.

    By default, when there is a single indexed input file with
    the same primary key definition as the output file, CONVERT
    does not perform a sort of the primary key. If you specify the
    keyword FORCE, it forces a sorting operation for the primary key.

    If you specify /NOSORT with /FAST_LOAD, only the SORT of the
    primary key is disabled. Alternate or secondary keys are
    always sorted. The /NOSORT qualifier is useful when you know
    the input file is already in primary key order.

2.17    /STATISTICS

    Determines whether statistics about the file conversion are to
    be displayed.

    Format

      /STATISTICS[=keyword]

      /NOSTATISTICS  (DEFAULT)

    Keyword     Meaning

    BRIEF       Displays a summary of the file conversion at the
                completion of the operation.
    FULL        Displays summary information at the completion of
                each key load containing Sort and Load statistics
                for the key. A summary of the file conversion is
                also displayed at the completion of the operation.

    If you specify the /STATISTICS qualifier without specifying a
    keyword, CONVERT defaults to /STATISTICS=BRIEF.

    The statistics produced by the Convert utility upon completion
    are as follows:

    o  Number of files processed

    o  Total records processed

    o  Total exception records

    o  Total valid records

    o  Elapsed time

    o  Buffered I/O count

    o  Direct I/O count

    o  Page faults

    o  CPU time

2.18    /TRUNCATE

    Specifies whether records that exceed the maximum record length
    for variable-length records, or records that exceed the specified
    record length for fixed-length records, are to be truncated.

    Format

      /TRUNCATE

      /NOTRUNCATE  (DEFAULT)

    If you specify /NOTRUNCATE and a long record is encountered, the
    record is not written to the output file. If you specify the
    /EXCEPTIONS_FILE qualifier, the entire record is written to the
    exceptions file.

2.19    /WORK_FILES

    Specifies the number of temporary work files to be used during
    the sort process.

    Format

      /WORK_FILES=n

    Specifies the number of work files you want. You can specify 0 or
    any value from 1 through 10.

    The default number of work files used during a sort is 2.
    This qualifier is valid when you are fast-loading a file with
    multiple keys or when you specify the /SORT qualifier. For more
    information about sorting, see both the /SORT and the /FAST_LOAD
    qualifiers.

2.20    /WRITE_CHECK

    Specifies whether all writes are to be checked by comparing the
    new disk records with the original records in memory.

    Format

      /WRITE_CHECK

      /NOWRITE_CHECK  (DEFAULT)

    If you use this switch, each new record on the disk is read and
    then compared with the original record in memory.

3  –  Examples

 1.$ CONV/NOCREAT/TRUNC/EXCEPTIONS_FILE=EXFILE VARFILE.DAT FIXFILE.DAT

    This command causes the Convert utility to copy records from a
    file with variable-length records (VARFILE.DAT) to a file with
    fixed-length records (FIXFILE.DAT). Records longer than the
    fixed length are truncated, and short records are copied to the
    exceptions file EXFILE.EXC.

 2.$ CONVERT FILE.IDX FILE.IDX

    This command creates the output file FILE.IDX with a version
    number one higher than that of the input file. The output file is
    a copy of the input file, but it is a clean copy without bucket
    splits, RRVs (record reference vectors), or pointers to deleted
    records. The performance of the output file is also improved.

    Note that the Convert utility establishes new record file
    addresses (RFAs) during such reorganizations.

 3.$ CONVERT/FDL=TEST.FDL TRNTO::DBA1:[EXP]SUB.DAT OUT.DAT

    This command creates a new sequential file OUT.DAT with stream
    record format at the local node, according to the specification
    in the previously created FDL file TEST.FDL. The input file
    SUB.DAT at remote node TRNTO is sequential with variable-length
    record format. The Convert utility copies records from SUB.DAT to
    OUT.DAT, changing the format of the records.

    The contents of the FDL file TEST.FDL are as follows:

        SYSTEM
               SOURCE            VAX/VMS

        FILE
               ORGANIZATION      SEQUENTIAL

        RECORD
               BLOCK_SPAN        YES
               CARRIAGE_CONTROL  CARRIAGE_RETURN
               FORMAT            STREAM
               SIZE              0

 4.$ CONVERT MASTER.DAT DENVER::DB1:[PROD]MASTER.SAV

    This command creates a new file called MASTER.SAV at remote
    node DENVER from the file MASTER.DAT at the local node. Because
    the /FDL qualifier is not used, the new file has the same file
    organization and record format as the original file. The action
    of this CONVERT command is similar to that performed by the COPY
    command. However, CONVERT transfers the file record by record and
    thus does not use block I/O.

 5.$ CONVERT/APPEND SALES.TMP KANSAS::[200,2]SALES.CMD

    This command causes records from the file SALES.TMP at the local
    node to be added sequentially to the end of the output file
    SALES.CMD at remote node KANSAS. The file SALES.TMP is sequential
    with variable-length record format, and the file SALES.CMD is
    sequential with stream record format. When the Convert utility
    loads records from the input file to the output file, it changes
    the record format.

 6.$ CONVERT/FDL=FIXED/PAD=0/TRUNCATE INFILE.VAR OUTFILE.FIX

    This command creates the fixed format file OUTFILE.FIX and then
    loads it with records from the variable input file INFILE.VAR.
    Before they are loaded, any short records from the input file
    are padded with an ASCII 0 character, and any long records are
    truncated.

 7.$ CONVERT/FDL=SYS$INPUT FORT.DAT STREAM.DAT
      FILE
              ORGANIZATION            SEQUENTIAL

      RECORD
              CARRIAGE_CONTROL        CARRIAGE_RETURN
              FORMAT                  STREAM
 <Ctrl/Z>

    This command converts the FORTRAN carriage control file FORT.DAT
    to a stream file that prints or types identically. The number of
    records may differ, and the FORTRAN carriage control information
    is removed from the records.

 8.$ CONVERT/FDL=SYS$INPUT FORT.DAT VAR.DAT
      FILE
              ORGANIZATION            SEQUENTIAL

      RECORD
              CARRIAGE_CONTROL        CARRIAGE_RETURN
              FORMAT                  VARIABLE
 <Ctrl/Z>

    This command converts the FORTRAN carriage control file FORT.DAT
    to a variable-length record file. The FORTRAN carriage control
    information is preserved as the first data byte, and the number
    of records in the output and input files is the same.
Close Help