Marc's Place

1  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).


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

   Digital's 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 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 DEC 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 DEC CDA Base Services
      converters.

   Format

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

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

3  Qualifiers
 

/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 DEC 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 DEC 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
 

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

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

3  DEC_CDA_Base_Service_Converters
   Converters installed with the DEC CDA Base Services are described
   below.
 

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

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

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

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

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.
 

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

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

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

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

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

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

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

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

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

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.
 

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

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

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

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

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

4  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 Digital 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.
 

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

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

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

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

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

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.
 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3  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 Digital's 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 DEC
   CDA Base Services converters.
 

3  CDA$_Facility_Messages
   The CDA$ facility messages that can be returned during the
   conversion of your document are described here. A brief
   explanation and recommended user action follows each message,
   unless a user action is not required. The messages are listed in
   alphabetical order, by message name.
 

4  AGGCNT
 

aggregate type: !AD Agg count: !ZL

   Level: Informational

   Explanation: Aggregate type: 'string' Agg count: 'integer'
   This is information on the aggregate name, and the count of the
   aggregate type.
 

4  ALLOCFAIL
 

memory allocation failure

   Level: Error

   Explanation: The standard memory allocation procedure failed to
   allocate dynamic memory.
 

4  CLOSEFAIL
 

close failure

   Level: Error

   Explanation: The standard close function has failed.
 

4  DCVNOTFND
 

domain converter not found

   Level: Error

   Explanation: The required domain converter could not be found.
 

4  DEFAULT
 

item present by default

   Level: Success

   Explanation: The application called CDA$LOCATE_ITEM, which
   determined that the item was present by default in the input
   stream.
 

4  DEFNOTFOU
 

definition not found

   Level: Error

   Explanation: The application called CDA$FIND_DEFINITION
   referencing an entity that is not defined.
 

4  EMPTY
 

empty item

   Level: Error

   Explanation: The application called a CDA access procedure
   referencing an item that is empty.
 

4  ENDOFDOC
 

end of document

   Level: Error

   Explanation: The application called CDA$GET_AGGREGATE, which
   determined that no more aggregates exist in the document.
 

4  ENDOFSEQ
 

end of sequence

   Level: Error

   Explanation: The application called CDA$NEXT_AGGREGATE
   referencing an aggregate that was at the end of a sequence.
 

4  ERRINPLOG
 

error messages produced during input conversion, see error log

   Level: Error

   Explanation: The input conversion did not complete and some error
   messages were produced.

   User Action: Refer to the error log for more details.
 

4  ERROUTLOG
 

error messages produced during output conversion, see error log

   Level: Error

   Explanation: The output conversion did not complete and some
   error messages were produced.

   User Action: Refer to the error log for more details.
 

4  FILESPEC
 

missing filespec

   Level: Informational

   Explanation: Missing filespec: 'filespec' This is the name of the
   missing filespec.
 

4  FLTTRN
 

floating-point truncation

   Level: Error

   Explanation: During CDA$LOCATE_ITEM for a general floating-point
   value, floating truncation occurred.
 

4  ICVNOTFND
 

input converter not found

   Level: Error

   Explanation: The specified input converter could not be found.
 

4  INDEX
 

index out of range

   Level: Error

   Explanation: The application called CDA$LOCATE_ITEM, CDA$STORE_
   ITEM, or CDA$ERASE_ITEM referencing an array-valued item, but the
   index is out of range.
 

4  INFINPLOG
 

informational messages produced during input conversion, see error log

   Level: Informational

   Explanation: The input conversion completed but some
   informational messages were produced.

   User Action: Refer to the error log for more details.
 

4  INFOUTLOG
 

informational messages produced during output conversion, see error log

   Level: Informational

   Explanation: The output conversion completed but some
   informational messages were produced.

   User Action: Refer to the error log for more details.
 

4  INHERIT
 

item present by inheritance

   Level: Success

   Explanation: The application called CDA$LOCATE_ITEM, which
   determined that the item was present by inheritance in the input
   stream.
 

4  INTERR
 

internal error

   Level: Fatal

   Explanation: The CDA Toolkit detected an internal error.
 

4  INVADDINF
 

invalid additional information

   Level: Error

   Explanation: The add-info parameter in a call to CDA$LOCATE_ITEM
   or CDA$STORE_ITEM is invalid.
 

4  INVAGGCTX
 

invalid aggregate context

   Level: Error

   Explanation: The user called PUT AGGREGATE, PUT DOCUMENT, or
   ENTER SCOPE with an aggregate that is invalid in its context in
   the document
 

4  INVAGGTYP
 

invalid aggregate type

   Level: Error

   Explanation: The application called a CDA access procedure
   referencing an aggregate type code that is undefined, or an
   aggregate that has an undefined type code.
 

4  INVBUFLEN
 

invalid buffer length

   Level: Error

   Explanation: The application called CDA$_STORE_ITEM referencing
   an item that is required to have a specified buffer length. The
   value of the buffer length parameter is not the required value.
 

4  INVDATLEN
 

invalid data length

   Level: Error

   Explanation: The length of the value data exceeded the specified
   length for the data type.
 

4  INVDOC
 

invalid document syntax

   Level: Error

   Explanation: The CDA access procedures determined that the
   document contains invalid syntax.
 

4  INVFLTVAL
 

invalid floating-point value

   Level: Error

   Explanation: A floating-point datum has a reserved value.
 

4  INVFUNCOD
 

invalid function code

   Level: Error

   Explanation: The application called CDA$CONVERT with an invalid
   function code.
 

4  INVINPDMN
 

invalid input domain

   Level: Error

   Explanation: An invalid input domain was specified for the front
   end. Only DDIF and DTIF are supported as domains.
 

4  INVINSERT
 

invalid insert

   Level: Error

   Explanation: The application called CDA$INSERT_AGGREGATE or
   CDA$STORE_ITEM referencing an aggregate that was already part
   of a sequence, but was not the first aggregate of the sequence.
 

4  INVITMCOD
 

invalid item code

   Level: Error

   Explanation: The application called a CDA access procedure
   referencing an aggregate item code that is not defined.
 

4  INVITMLST
 

invalid item list

   Level: Error

   Explanation: The application called CDA$OPEN_FILE or CDA$CREATE_
   ROOT_AGGREGATE with a processing options item list that contained
   an invalid item.
 

4  INVOPTION
 

invalid converter option

   Level: Error

   Explanation: An invalid option was specified for the converter.

   User Action: Refer to the documentation for this converter to see
   the valid options.
 

4  INVOUTDMN
 

invalid output domain

   Level: Error

   Explanation: An invalid output domain was specified for the back
   end. Only DDIF and DTIF are supported as domains.
 

4  INVSCOCOD
 

invalid scope code

   Level: Error

   Explanation: The application called CDA$ENTER_SCOPE or CDA$LEAVE_
   SCOPE referencing a scope code that is not defined or invalid in
   following correct document scoping rules.
 

4  INVSCOTRAN
 

invalid scope transition

   Level: Error

   Explanation: The application made a call to CDA$ENTER_SCOPE or
   CDA$LEAVE_SCOPE that did not follow correct scoping rules.
 

4  INVSTSCOD
 

invalid status code

   Level: Error

   Explanation: The specified status code's associated message could
   not be found.
 

4  INVTAGCOD
 

invalid tag code

   Level: Error

   Explanation: The application called CDA$_STORE_ITEM referencing
   an item that has a special tag encoding, but the value of the
   add-info parameter is not defined for the item.
 

4  ITMAGGCNT
 

aggregate item code: !ZL Aggregate type: !AD Agg count: !ZL

   Level: Informational

   Explanation: Aggregate item code: 'integer' Aggregate type:
   'string' Agg count: 'integer' This is info on an item missing,
   aggregate name, and the count of the aggregate type.
 

4  MISEXTREF
 

external reference file missing or could not be read

   Level: Warning

   Explanation: An external reference file is missing or could not
   be read. A document's external reference could not be found,
   read, or processed.
 

4  MISSTYGDE
 

style guide file missing or could not be read

   Level: Warning

   Explanation: Style guide file missing or could not be read. A
   document's external style guide could not be found, read, or
   processed.
 

4  NORMAL
 

normal successful completion

   Level: Success

   Explanation: The specified action has been successfully
   completed.
 

4  OCVNOTFND
 

output converter not found

   Level: Error

   Explanation: The specified output converter could not be found.
 

4  OPENFAIL
 

open failure

   Level: Error

   Explanation: The standard open function has failed.
 

4  READFAIL
 

read failure

   Level: Error

   Explanation: The standard read function has failed.
 

4  READONLY
 

aggregate is read-only

   Level: Error

   Explanation: The application requested input processing options
   that require an aggregate to be read-only. The application
   attempted to write or delete the aggregate.
 

4  REQITMMIS
 

required item missing

   Level: Error

   Explanation: The user called PUT AGGREGATE, PUT DOCUMENT, or
   ENTER SCOPE with an aggregate that contains an item which is
   required, but empty.
 

4  SUSPEND
 

converter is suspended

   Level: Success

   Explanation: The application called CDA$CONVERT, which determined
   that the back end suspended conversion. This message can only be
   returned by the CDA viewer.
 

4  TYPEREF
 

reference to undefined type name

   Level: Informational

   Explanation: The definition of type typeref was not found.
 

4  UNRECENC
 

Unrecognized encodings skipped

   Level: Success, Informational

   Explanation: This success status is returned by the GET AGGREGATE
   and GET DOCUMENT routines if unrecognized data in the input
   encoding is skipped. This informational status is logged to the
   common message log by the bundled DDIF and DTIF converter front
   ends if data is skipped during the reading within the front-end
   conversion.
 

4  UNSUPCNV
 

unsupported document conversion

   Level: Error

   Explanation: The input and output document formats are
   incompatible for conversion.
 

4  UNSUPFMT
 

unsupported document format

   Level: Error

   Explanation: The application called CDA$CONVERT with an
   unsupported document format name. The document format name may
   be misspelled, or the required conversion module may not be
   installed.
 

4  VAREMPTY
 

empty variant item (OBSOLETE)

   Level: Error

   Explanation: The application called CDA$LOCATE_ITEM, CDA$STORE_
   ITEM, or CDA$ERASE_ITEM referencing an item that has a variable
   data type. The item that specifies the data type is empty.
 

4  VARINDEX
 

variant index out of range (OBSOLETE)

   Level: Error

   Explanation: The application called CDA$LOCATE_ITEM, CDA$STORE_
   ITEM, or CDA$ERASE_ITEM referencing an array-valued item that has
   a variable data type, but the index is out of range for the item
   that specifies the data type.
 

4  VARVALUE
 

variant value out of range

   Level: Error

   Explanation: The application called CDA$LOCATE_ITEM, CDA$STORE_
   ITEM, or CDA$ERASE_ITEM referencing an item that has a variable
   data type, but the item that specifies the data type has an
   invalid value.
 

4  VERSKEW
 

major version skew between input file and CDA Toolkit

   Level: Error

   Explanation: The file's major version is different from the
   Toolkit's. Thus, the Toolkit cannot properly process the file.
 

4  WRITFAIL
 

write failure

   Level: Error

   Explanation: The standard write function has failed.
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 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
  
3  Parameters
input-filespec [,...]

   Specifies the file or files to be converted. You may specify
   up to 10 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.
 

3  Qualifiers
 

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

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

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

/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)
 

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

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

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

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

/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).
 

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

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

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

/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)
 

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

/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  (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.
 

/STATISTICS

   Determines whether a set of statistics about the completed
   conversion is to be displayed.

   Format

     /STATISTICS
     /NOSTATISTICS  (DEFAULT)

   The statistics produced by the Convert utility 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
 

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

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

/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.$ CONVERT/NOCREATE/TRUNCATE/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.
2  /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  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  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  Qualifiers
 

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

/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
Software development, photography, jokes, ....

Sites by me

Hosting Favorites

Blogroll

Marc's Place

1 CONVERT
