HELPLIB.HLB  —  CONVERT
     The CONVERT commands perform the following functions:

     o  Converts a revisable  format  file to another revisable or final
        form file from the DCL command line. (see /DOCUMENT).

     o  Copy records from one file to another, changing the  organization
        and  format  of  the  input  file to that of the output file (see
        File).

     o  Make empty buckets in Prologue 3 indexed files available so  that
        new records can be written in them (see /RECLAIM).

1    /DOCUMENT

    Converts documents from one format to another for the purpose
    of sharing information among different applications. Specify the
    input file name and format and the output file name and format as
    shown below.

    The default input and output file format is DDIF (Digital
    Document Interchange Format). DDIF is a standard format for the
    storage and interchange of compound documents, which can include
    text, graphics, and images.

    The CDA Converter Library, a layered product that offers
    conversion among other popular file formats, is separately
    installed and documented. If you have the CDA Converter Library
    Version 2.2 or later installed on your system, see HELP for
    CDA_Converters for more information.

    An /OPTIONS qualifier specifies a file containing options that
    are applied to the input and output file to ensure that minimal
    changes in format and content occur during the conversion.

    A /MESSAGE_FILE qualifier creates a file to which informational
    and error messages are logged during the conversion.

                                   NOTE

       The CDA Base Services for OpenVMS DECwindows Motif or
       later must be installed in order to use the /MESSAGE_FILE
       qualifier and new versions of the CDA Base Services
       converters.

    Format

    CONVERT/DOCUMENT input-filespec/FORMAT=input-format -
      output-filespec/FORMAT=output-format

1.1  –  Parameters

 input-filespec

    Specifies the name of the input file to be converted. The default
    file type is .DDIF.

 output-filespec

    Specifies the name of the output file. The default file type is
    .DDIF.

1.2  –  Qualifiers

1.2.1    /FORMAT

       /FORMAT=format-name

    Specifies the encoding format of the input or output file. The
    default input and output format is DDIF.

    Input converters bundled with the CDA Base Services and the
    default file extensions for the file formats they support are as
    follows:

    Input Format   File Extension

    DDIF           .DDIF
    DTIF           .DTIF
    TEXT           .TXT

    Output converters bundled with the CDA Base Services for
    OpenVMS DECwindows Motif and the default file extensions for the
    file formats they support are as follows:

    Output
    Format         File Extension

    DDIF           .DDIF
    DTIF           .DTIF
    TEXT           .TXT
    PS             .PS
    ANALYSIS       .CDA$ANALYSIS

1.2.2    /OPTIONS

       /OPTIONS=options-filename

    Specifies a file that contains processing option for both input
    and output. An options file is a text file with a default file
    extension of .CDA$OPTIONS on OpenVMS systems.

    An options file is not required. Default processing options are
    applied automatically when you convert a file. You may, however,
    require settings other than the default. Processing options can
    help ensure minimal changes when your input file is converted to
    a different output file format.

1.2.3    /MESSAGE_FILE

       /MESSAGE_FILE=filespec
       /NOMESSAGE_FILE (default)

    Turns on message logging for document conversion. Messages output
    by the input and output converters are directed to the file
    specified with filespec. If filespec is not specified, messages
    are output to SYS$ERROR. The default is /NOMESSAGE_FILE.

1.3  –  CDA Base Service Converters

    Converters installed with the CDA Base Services are described
    below.

1.3.1  –  Analysis Output Converter

    The Analysis output converter produces formatted text output of
    the in-memory DDIF or DTIF format of the input file. The analysis
    output file shows the named objects and values stored in the
    input file. Application programmers use an analysis output file
    for debugging purposes.

    Application end users use an analysis output file to determine
    whether an input file contains references or links to multiple
    subfiles. Each subfile must be copied separately across a network
    because subfiles are not automatically included when an input
    file is transferred across the network.

    You can search the analysis output file for all occurrences of
    the string "ERF_". The following example shows that the image
    file "griffin.img" is linked to the DDIF compound document that
    is the input file:

    ERF_LABEL ISO LATIN1 "griffin.img" ! Char. string.
    ERF_LABEL TYPE RMS_LABEL TYPE "$RMS"
    ERF_CONTROL COPY_REFERENCE ! Integer = 1

    Note that an analysis output file is intended as a programmer's
    tool. The coded information in the file is not intended for
    modification but rather to examine the content of a file. The
    previous example shows how you can search analysis output for
    references to linked files.

1.3.1.1  –  Analysis Converter Options

    The Analysis output converter supports the following options:

    o  TRANSLATE_BYTE_STRINGS

       Overrides the default. For data of type BYTE STRING, the
       analysis output no longer displays the hexadecimal translation
       if all the characters in the byte string are printable
       characters (hex values 20 through 7E). This feature may be
       overridden by supplying the TRANSLATE_BYTE_STRINGS option.

    o  IMAGE_DATA

       Overrides the default. For the special case of byte string
       data for item DDIF$_IDU_PLANE_DATA (a bitmapped image), the
       analysis output previously included both a hexadecimal and an
       ASCII translation display, neither of which were of particular
       value to most users. With the new version, both displays will
       be replaced with the following comment:

       ! *** Bit-mapped data not displayed here ***

       To retain the hexadecimal display, supply the IMAGE_DATA
       option. Even with this option turned on, there will be no
       translation into ASCII.

    o  INHERITANCE

       Specifies that the analysis is shown with attribute
       inheritance enabled. Inherited attributes are marked as
       "[Inherited value.]" in the output. This option also causes
       external references to be imported into the main document.

1.3.2  –  DDIF Input Converter

    The DDIF input converter converts a compound document DDIF input
    file to an intermediate format that is then converted to the
    specified output file format. If the DDIF input file is a newer
    version of the DDIF grammar than that understood by the DDIF
    input converter, data represented by the new grammar elements is
    lost.

    The DDIF input converter does not resolve external references,
    although the converter kernel can if requested by the output
    converter. A document syntax error in the DDIF input file causes
    a fatal input processing error and conversion stops.

1.3.3  –  DDIF Output Converter

    The DDIF output converter creates a compound document DDIF output
    file from the intermediate format of the input file.

1.3.4  –  Domain Converter

    You may want to convert tabular input files to document output
    files so that you can include textual representations of data
    tables or spreadsheets in reports and other documents. You will,
    however, lose cell borders, headers, grid lines, all formulas,
    and font types when converting a tabular input file to a document
    output file.

    When you convert a tabular input file (for example, a DTIF file)
    to a document output file, the file format first undergoes an
    automatic domain conversion from a table format to a document
    format. The output is then converted to the document format you
    specified.

    You can create an options file containing processing options that
    apply to any CDA supported tabular file format for which there is
    an input converter. Data tables and spreadsheets are examples of
    tabular file formats.

    To convert tabular input files to document output files, use
    the DTIF_TO_DDIF format name, followed by the processing options
    listed below. Specify the DTIF_TO_DDIF processing options in
    addition to the processing options for a particular tabular input
    file format and a particular document output file format.

1.3.4.1  –  COLUMN_TITLE

    COLUMN_TITLE displays the column titles as contained in the
    column attributes centered at the top of the column.

1.3.4.2  –  CURRENT_DATE

    CURRENT_DATE displays the current date and time in the bottom
    left corner of the page. The value is formatted according to the
    document's specification for a default date and time.

1.3.4.3  –  DOCUMENT_DATE

    DOCUMENT_DATE displays the document date and time as contained
    in the document header in the top left corner of the page. The
    value is formatted according to the document's specification for
    a default date and time.

1.3.4.4  –  DOCUMENT_TITLE

    DOCUMENT_TITLE displays the document title or titles as contained
    in the document header centered at the top of the page, one
    string per line.

1.3.4.5  –  PAGE_NUMBER

    PAGE_NUMBER displays the current page number in the top right
    corner of the page.

1.3.4.6  –  PAPER_SIZE

    PAPER_SIZE keyword specifies the size of the paper to be used
    when formatting the file. Valid values for the size argument are
    as follows:

    Keyword            Size

    A0                 841 x 1189 millimeters (33.13 x 46.85 inches)
    A1                 594 x 841 millimeters (23.40 x 33.13 inches)
    A2                 420 x 594 millimeters (16.55 x 23.40 inches)
    A3                 297 x 420 millimeters (11.70 x 16.55 inches)
    A4                 210 x 297 millimeters (8.27 x 11.70 inches)
    A5                 148 x 210 millimeters (5.83 x 8.27 inches)
    A                  8.5 x 11 inches (216 x 279 millimeters)
    B                  11 x 17 inches (279 x 432 millimeters)
    B4                 250 x 353 millimeters (9.84 x 13.90 inches)
    B5                 176 x 250 millimeters (6.93 x 9.84 inches)
    C                  17 x 22 inches (432 x 559 millimeters)
    C4                 229 x 324 millimeters (9.01 x 12.76 inches)
    C5                 162 x 229 millimeters (6.38 x 9.02 inches)
    D                  22 x 34 inches (559 x 864 millimeters)
    DL                 110 x 220 millimeters (4.33 x 8.66 inches)
    E                  34 x 44 inches (864 x 1118 millimeters)
    10x13_ENVELOPE     10 x 13 inches (254 x 330 millimeters)
    9x12_ENVELOPE      9 x 12 inches (229 x 305 millimeters)
    BUSINESS_ENVELOPE  4.13 x 9.5 inches (105 x 241 millimeters)
    EXECUTIVE          7.5 x 10 inches (191 x 254 millimeters)
    LEDGER             11 x 17 inches (279 x 432 millimeters)
    LEGAL              8.5 x 14 inches (216 x 356 millimeters)
    LETTER             8.5 x 11 inches (216 x 279 millimeters)
    LP                 13.7 x 11 inches (348 x 279 millimeters)
    VT                 8 x 5 inches (203 x 127 millimeters)

    The A paper size (8.5 x 11 inches) is the default.

1.3.4.7  –  PAPER_HEIGHT

    PAPER_HEIGHT value specifies a paper size other than one of
    the predefined values provided. The default paper height is 11
    inches.

1.3.4.8  –  PAPER_WIDTH

    PAPER_WIDTH value specifies a paper size other than one of the
    predefined sizes provided. The default paper width is 8.5 inches.

1.3.4.9  –  PAPER_TOP_MARGIN

    PAPER_TOP_MARGIN value specifies the width of the margin provided
    at the top of the page. The default value is 0.25 inch.

1.3.4.10  –  PAPER_BOTTOM_MARGIN

    PAPER_BOTTOM_MARGIN value specifies the width of the margin
    provided at the bottom of the page. The default value is 0.25
    inch.

1.3.4.11  –  PAPER_LEFT_MARGIN

    PAPER_LEFT_MARGIN value specifies the width of the margin
    provided on the left-hand side of the page. The default value
    is 0.25 inch.

1.3.4.12  –  PAPER_RIGHT_MARGIN

    PAPER_RIGHT_MARGIN value specifies the width of the margin
    provided on the right-hand side of the page. The default value
    is 0.25 inch.

1.3.4.13  –  PAPER_ORIENTATION

    PAPER_ORIENTATION keyword specifies the paper orientation to be
    used in the output file. The valid values for the orientation
    argument are as follows:

    Keyword         Meaning

    PORTRAIT        The page is oriented so that the larger dimension
                    is parallel to the vertical axis.
    LANDSCAPE       The page is oriented so that the larger dimension
                    is parallel to the horizontal axis.

    The default is PORTRAIT.

1.3.5  –  DTIF Input Converter

    The DTIF input converter converts a DTIF input file to an
    intermediate format that is then converted to the specified
    output file format. DTIF (Digital Table Interchange Format) is
    a standard format for the storage and interchange of tabular
    data files, such as those created by spreadsheet and database
    applications.

    If the DTIF input file is a newer version of the DTIF grammar
    than that understood by the DTIF front end, data represented by
    the new grammar elements is lost.

    The DTIF input converter does not resolve external references. A
    document syntax error in the DTIF input file causes a fatal input
    processing error. A document syntax error in the DTIF input file
    causes a fatal input processing error and conversion stops.

1.3.6  –  DTIF Output Converter

    The DTIF output converter converts the intermediate format of the
    input file to a DTIF output file. DTIF (Digital Table Interchange
    Format) is a standard format for the storage and interchange
    of tabular data files, such as those created by spreadsheet and
    database applications.

    The DTIF output converter converts external file references
    stored in the intermediate representation of the input file but
    does not resolve external references.

1.3.7  –  Text Input Converter

    The Text input converter converts a Text (ISO Latin1) input file
    to an intermediate format that is then converted to the specified
    output file format. The information in the text input file maps
    directly to an intermediate representation. Line breaks and form
    feeds are mapped to DDIF directives. One or more contiguous blank
    lines are interpreted as end-of-paragraph markers.

    If the text input file was entered as a DEC Multinational
    Character Set file on a character-cell terminal or terminal
    emulator, the following conversions occur:

    Original Character      Converted Character

    Concurrency sign        Diaeresis
    Capital OE ligature     Multiplication sign
    Capital Y with          Capital Y with acute accent
    diaeresis
    Small oe ligature       Division sign
    Small y with diaeresis  Y with acute accent

    The text input file does not lose any text when converted
    to the intermediate representation because no structure
    information is contained in a text file. All nonprinting
    characters are converted to space characters. For example,
    characters introducing ANSI escape characters are converted to
    space characters. There is no attempt to interpret ANSI escape
    sequences.

1.3.8  –  Text Output Converter

    The Text output converter converts the intermediate format of
    the input file to a Text output file. Text output files contain
    only textual content and minimal formatting such as line feeds,
    page breaks, and tabs. The output converter preserves formatting
    information to the extent possible. Page coordinates convert to
    the nearest character cell (line,column) position.

    All graphics, images, and text attributes in the input file
    are lost when converted to the text output file. Because a
    monospace font is used, it is possible some text may be lost due
    to overwriting to preserve the layout. Lines can be truncated if
    the specified page width is smaller than the page width specified
    in the document's format information. Neither of these cases
    occur when you use the OVERRIDE_FORMAT processing option because,
    in that case, the document's format information is ignored.

    The Text output converter supports the processing options listed
    below.

1.3.8.1  –  ASCII_FALLBACK

    ASCII_FALLBACK [ON,OFF] causes the Text output converter to
    output text in 7-bit ASCII. The fallback representation of the
    characters is described in the ASCII standard. If this option is
    not specified, the default is OFF; if this option is specified
    without a value, the default is ON.

1.3.8.2  –  CONTENT_MESSAGES

    CONTENT_MESSAGES [ON,OFF] causes the Text output converter to
    put a message in the output file each time a nontext element is
    encountered in the intermediate representation of the input file.
    If this option is not specified, the default is OFF; if this
    option is specified without a value, the default is ON.

1.3.8.3  –  HEIGHT

    HEIGHT value specifies the maximum number of lines per page
    in your text output file. If you specify zero, the number of
    lines per page will correspond to the height specified in your
    document. If you also specify OVERRIDE_FORMAT, or if the document
    has no inherent page size, the document is formatted to the
    height value specified by this option. The default height is
    66 lines.

1.3.8.4  –  OVERRIDE_FORMAT

    OVERRIDE_FORMAT [ON,OFF] causes the Text output converter to
    ignore the document formatting information included in your
    document, so that the text is formatted in a single large galley
    per page that corresponds to the size of the page as specified
    by the HEIGHT and WIDTH processing options. If this option is
    not specified, the default is OFF; if this option is specified
    without a value, the default is ON.

1.3.8.5  –  SOFT_DIRECTIVES

    SOFT_DIRECTIVES [ON,OFF] causes the Text output converter to
    obey the soft directives contained in the document when creating
    your text output file. (Soft directives specify such formatting
    commands as new line, new page, and tab.) If this option is
    not specified, the default is OFF; if this option is specified
    without a value, the default is ON.

1.3.8.6  –  WIDTH

    WIDTH value specifies the maximum number of columns of characters
    per page in your text output file. If you specify zero, the
    number of columns per page will correspond to the width specified
    in your document. If you also specify OVERRIDE_FORMAT, or if the
    document has no inherent page size, the document is formatted
    to the value specified by this processing option. If any lines
    of text exceed this width value, the additional columns are
    truncated. The default width is 80 characters.

1.3.9  –  PostScript Output Converter

    The PostScript output converter converts the intermediate format
    of the input file to a PostScript output file. The PostScript
    output converter supports the processing options listed below.

1.3.9.1  –  PAPER_SIZE

    PAPER_SIZE keyword specifies the size of the paper to be used
    when formatting the resulting PostScript output file. Valid
    values for the size argument are as follows:

    Keyword     Size

    A0          841 x 1189 millimeters (33.13 x 46.85 inches)
    A1          594 x 841 millimeters (23.40 x 33.13 inches)
    A2          420 x 594 millimeters (16.55 x 23.40 inches)
    A3          297 x 420 millimeters (11.70 x 16.55 inches)
    A4          210 x 297 millimeters (8.27 x 11.70 inches)
    A           8.5 x 11 inches (216 x 279 millimeters)
    B           11 x 17 inches (279 x 432 millimeters)
    C           17 x 22 inches (432 x 559 millimeters)
    D           22 x 34 inches (559 x 864 millimeters)
    E           34 x 44 inches (864 x 1118 millimeters)
    LEDGER      11 x 17 inches (279 x 432 millimeters)
    LEGAL       8.5 x 14 inches (216 x 356 millimeters)
    LETTER      8.5 x 11 inches (216 x 279 millimeters)
    LP          13.7 x 11 inches (348 x 279 millimeters)
    VT          8 x 5 inches (203 x 127 millimeters)

    The A paper size (8.5 x 11 inches) is the default.

1.3.9.2  –  PAPER_HEIGHT

    PAPER_HEIGHT value specifies a paper size other than one of the
    predefined values provided. The default paper height is 11 inches
    (in). Other valid units of measurement are: centimeters (cm),
    millimeters (mm), and points (pt or po).

1.3.9.3  –  PAPER_WIDTH

    PAPER_WIDTH value specifies a paper size other than one of the
    predefined sizes provided. The default paper width is 8.5 inches
    (in). Other valid units of measurement are: centimeters (cm),
    millimeters (mm), and points (pt or po).

1.3.9.4  –  PAPER_TOP_MARGIN

    PAPER_TOP_MARGIn value specifies the width of the margin
    provided at the top of the page. The default value is 0.25 inch
    (in). Other valid units of measurement are: centimeters (cm),
    millimeters (mm), and points (pt or po).

1.3.9.5  –  PAPER_BOTTOM_MARGIN

    PAPER_BOTTOM_MARGIN value specifies the width of the margin
    provided at the bottom of the page. The default value is 0.25
    inch (in). Other valid units of measurement are: centimeters
    (cm), millimeters (mm), and points (pt or po).

1.3.9.6  –  PAPER_LEFT_MARGIN

    PAPER_LEFT_MARGIN value specifies the width of the margin
    provided on the left-hand side of the page. The default value is
    0.25 inch (in). Other valid units of measurement are: centimeters
    (cm), millimeters (mm), and points (pt or po).

1.3.9.7  –  PAPER_RIGHT_MARGIN

    PAPER_RIGHT_MARGIN value specifies the width of the margin
    provided on the right-hand side of the page. The default value is
    0.25 inch (in). Other valid units of measurement are: centimeters
    (cm), millimeters (mm), and points (pt or po).

1.3.9.8  –  PAPER_ORIENTATION

    PAPER_ORIENTATION keyword specifies the paper orientation to
    be used in the output PostScript file. The valid values for the
    orientation argument are as follows:

    Keyword         Meaning

    PORTRAIT        The page is oriented so that the larger dimension
                    is parallel to the vertical axis.
    LANDSCAPE       The page is oriented so that the larger dimension
                    is parallel to the horizontal axis.

    The default is PORTRAIT.

1.3.9.9  –  EIGHT_BIT_OUTPUT

    EIGHT_BIT_OUTPUT [ON,OFF] specifies whether the PostScript output
    converter should use 8-bit output. The default value is ON.

1.3.9.10  –  LAYOUT

    LAYOUT [ON,OFF] specifies whether the PostScript output converter
    processes the layout specified in the DDIF document. The default
    value is ON.

1.3.9.11  –  OUTPUT BUFFER SIZE value

    OUTPUT_BUFFER_SIZE value specifies the size of the output buffer.
    The value you specify must be within the range 64 to 256. The
    default value is 132.

1.3.9.12  –  PAGE_WRAP

    PAGE_WRAP [ON,OFF] specifies whether the PostScript output
    converter performs page wrapping of any text that would exceed
    the bottom margin. The default value is ON.

1.3.9.13  –  SOFT_DIRECTIVES

    SOFT_DIRECTIVES [ON,OFF] specifies whether the PostScript output
    converter processes soft directives in the DDIF file in order
    to format output. (Soft directives specify such formatting
    commands as new line, new page, and tab.) If the PostScript
    output converter processes soft directives, the output file will
    look more like you intended. The default value is ON.

1.3.9.14  –  WORD_WRAP

    WORD_WRAP [ON,OFF] specifies whether the PostScript output
    converter performs word wrapping of any text that would exceed
    the right margin. The default value is ON. If you specify OFF,
    the PostScript output converter allows text to exceed the right
    margin.

1.4  –  Creating the Options File

    You can create an options file prior to specifying the CONVERT
    /DOCUMENT command with the /OPTIONS qualifier. An options file
    is a text file with a default file extension of .CDA$OPTIONS on
    OpenVMS systems.

    The options file contains all the processing options for your
    input file format and your output file format. Processing options
    help ensure minimal changes when your input file is converted to
    a different output file format.

    An options file is not required. Default processing options are
    applied automatically when you convert a file. You may, however,
    require settings other than the default.

    Enter options in the options file using these formats, where
    format is the name of the file format to which the option applies
    and option is the option:

    format_INPUT option         applies only to an input file of the
    [value]                     specified format
    format_OUTPUT option        applies only to an output file of the
    [value]                     specified format
    format option [value]       applies to either an input file or an
                                output file of the specified format

    Use uppercase and lowercase alphabetic characters, digits (0-9),
    dollar signs ($), and underscores (_) to specify the processing
    options.

    Use one or more spaces or tabs to precede values specified for a
    processing option.

    The following example is a typical entry in an options file:

    PS PAPER_HEIGHT 10

    In this example, the extension _OUTPUT is not required for the
    format, since PostScript is available only as an output format.
    The value specified for PAPER_HEIGHT is in inches by default.

    If the options file includes options that do not apply to
    the converters for a particular conversion, those options are
    ignored.

    If you specify an invalid option for an input or output format or
    an invalid value for an option, you receive an error message. The
    processing options described in the following sections document
    any restrictions.

1.4.1  –  Example

    $ CONVERT/DOCUMENT /OPTIONS=MY_OPTIONS.CDA$OPTIONS -
    _$ MY_INPUT.DTIF/FORMAT=DTIF MY_OUTPUT.DDIF/FORMAT=DDIF -
    _$ /MESSAGE_FILE=MY_MSGS.MSG

    This command converts an input file named MY_INPUT.DTIF, which
    has the DTIF format, to an output file named MY_OUTPUT.DDIF,
    which has the DDIF format. The specified options file is named
    MY_OPTIONS.CDA$OPTIONS, and the message file is named /MESSAGE_
    FILE=MY_MSGS.MSG.

1.5  –  Valid Conversions

    You can convert an input file to an output file that is of the
    same type: document, tabular, graphics, or image. The DDIF and
    Text converters support conversion between document file formats.
    The DTIF converters support conversion between tabular file
    formats.

    The Analysis output converter is a special type of document
    converter that produces formatted text output of the objects and
    values stored in the in-memory DDIF or DTIF format of an input
    file.

    The PostScript output converter also is a special type of
    document converter that supports conversion between all revisable
    file formats and final-form PostScript output.

    You can convert a tabular input file format to a document output
    file format. The domain converter provides this capability.

    You can convert a graphics or image input file to a compound
    document output file format that supports graphics and image
    elements.

    You can convert a compound document input file containing
    graphics or images to a graphics or image output file,
    respectively, but any text in the file is lost.

    If the CDA Converter Library or other third-party
    converters are installed, you can convert files among other
    popular file formats in addition to those supported by the
    CDA Base Services converters.

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

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

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

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

3    /RECLAIM

    Invokes the Convert/Reclaim utility (CONVERT/RECLAIM) to make
    empty buckets in Prolog 3 indexed files available so that new
    records can be written in them. If all the records in a bucket
    have been deleted, that bucket is locked until the Convert
    /Reclaim utility makes it available. Unlike the CONVERT utility,
    the Convert/Reclaim utility maintains record file addresses
    (RFAs). The /RECLAIM qualifier is required. For a complete
    description of the Convert/Reclaim utility, including more inform-
    ation about the CONVERT/RECLAIM command and its qualifier, see
    the OpenVMS Record Management Utilities Reference Manual.

    Format

      CONVERT/RECLAIM  filespec

3.1  –  Parameter

 filespec

    Specifies the Prolog 3 indexed file in which you want to reclaim
    buckets. When you use the CONVERT/RECLAIM command, the file
    cannot be opened for shared access.

3.2  –  Usage Summary

    Invoke the Convert/Reclaim utility by entering the CONVERT
    /RECLAIM command at the DCL level. Exit the Convert/Reclaim
    utility by letting the utility run to successful completion.
    The Convert/Reclaim utility produces an output file only if you
    specify the /STATISTICS command qualifier.

    If you want to execute CONVERT/RECLAIM commands over a network,
    you need NETMBX privilege.

3.3  –  Qualifiers

3.3.1    /KEY

    The /KEY qualifier lets you reclaim index buckets for specified
    keys.

    Format

      /KEY=key_number[,...]  filename

    If you request statistics and specify the /KEY qualifier, the
    utility reports the statistics for each key separately. If you do
    not use the /KEY qualifier, the default is to reclaim all index
    buckets and to provide a single report.

3.3.2    /STATISTICS

    Determines whether statistics about the completed conversion and
    reclamation are displayed. If you specify reclamation of index
    buckets by key, a separate set of statistics is returned for each
    specified key.

    Format

      /STATISTICS

      /NOSTATISTICS  (DEFAULT)

    The Convert/Reclaim utility provides the following statistics:

    o  Total buckets scanned

    o  Data buckets reclaimed

    o  Index buckets reclaimed

    o  Total buckets reclaimed

    o  Elapsed time

    o  Buffered I/O

    o  Direct I/O

    o  Page faults

    o  CPU time
Close Help