HP OpenVMS Systems Documentation

HP OpenVMS DCL Dictionary

Converts a CDA supported revisable input file to another revisable or final form output file.

Note You can use this command only if DECwindows Motif for OpenVMS is installed on your system.

Format

CONVERT/DOCUMENT input-filespec output-filespec

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.

Description

The CONVERT/DOCUMENT command lets you convert documents from one format to another. You specify the name and format of the input file (a file whose format is incompatible with the application that needs to read the file) and the output file (the file to be created in a new format).

You can convert a file from one format to another if an input converter exists for the input file format and an output converter exists for the output file format. 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.

DDIF input and output converters, in addition to several other converters, are installed with the CDA Base Services for DECwindows Motif for OpenVMS. Some of the converters support processing options, which ensure minimal changes when your input file is converted to a different output file format. Create an options file with the processing options you need before specifying the CONVERT/DOCUMENT command with the /OPTIONS qualifier.

Every converter supports a message log option, which is a file name you specify and to which informational and error messages are logged during the conversion.

Qualifiers

/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 for DECwindows Motif for OpenVMS and the default file type for the file formats they support are as follows:

Input Format	File Type
DDIF	.DDIF
DTIF	.DTIF
TEXT	.TXT

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

Output Format	File Type
DDIF	.DDIF
DTIF	.DTIF
TEXT	.TXT
PS	.PS
ANALYSIS	.CDA$ANALYSIS

The CDA Converter Library is a layered product that offers several other document, graphics, image, and data table input and output converters. Independent software vendors also write CDA conforming applications and converters for the operating system. Contact your system manager for a complete list of converters available on your system.

Analysis Output Converter

The Analysis output converter produces an analysis of the intermediate representation 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.

DDIF Input Converter

The DDIF input converter converts a DDIF input file to an intermediate representation that is subsequently converted to the specified output file format. The following list summarizes the data mapping, conversion restrictions, external file references, and document syntax errors relevant to the DDIF input converter:

• Data mapping
  The information in the DDIF input file maps directly to an intermediate representation.
• Conversion restrictions
  The DDIF input file does not lose any information when converted to the intermediate representation.
  However, 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.
• External file references
  Any external file references within the DDIF input file are converted to the intermediate representation.
  The DDIF input converter makes no attempt to resolve external references, although the converter kernel can if requested by the output converter.
• Document syntax errors
  A document syntax error in the DDIF input file causes a fatal input processing error. If the DDIF input converter encounters a document syntax error, the conversion stops and no further input processing occurs.

DDIF Output Converter

The DDIF output converter creates a DDIF output file from the intermediate representation of the input file. The following list summarizes the data mapping and conversion restrictions relevant to the DDIF output converter.

• Data mapping
  The information in the intermediate representation of the input file maps directly to the DDIF output file.
• Conversion restrictions
  The intermediate representation of the input file does not lose any information when converted to the DDIF output file.

DTIF Input Converter

The DTIF input converter converts a DTIF input file to an intermediate representation that is subsequently converted to the specified output file format. The following list summarizes the data mapping, conversion restrictions, external file references, and document syntax errors relevant to the DTIF input converter:

• Data mapping
  The information in the DTIF input file maps directly to an intermediate representation.
• Conversion restrictions
  The DTIF input file does not lose any information when converted to the intermediate representation.
  However, 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.
• External file references
  Any external file references within the DTIF input file are converted to the intermediate representation.
  The DTIF input converter makes no attempt to resolve external references.
• Document syntax errors
  A document syntax error in the DTIF input file causes a fatal input processing error. If the DTIF input converter encounters a document syntax error, the conversion stops and no further input processing occurs.

DTIF Output Converter

The DTIF output converter converts the intermediate representation of the input file to a DTIF output file. The following list summarizes the data mapping, conversion restrictions, and external file references relevant to the DTIF output converter:

• Data mapping
  The information in the intermediate representation of the input file maps directly to the DTIF output file.
• Conversion restrictions
  The intermediate representation of the input file does not lose any information when converted to the DTIF output file.
• External file references
  The DTIF output converter converts external file references stored in the intermediate representation of the input file but makes no attempt to resolve external references.

Text Input Converter

The Text input converter converts a Text (ISO Latin1) input file to an intermediate representation that is subsequently converted to the specified output file format. The following list summarizes the data mapping, conversion restrictions, external file references, and document syntax errors relevant to the Text input converter:

• Data mapping
  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 diaeresis	Capital Y with acute accent
  Small oe ligature	Division sign
  Small y with diaeresis	Y with acute accent

• Conversion restrictions
  The text input file does not lose any information 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.
• External file references
  Text files do not contain external file references.
• Document syntax errors
  Text files do not contain syntax, so syntax errors are not reported by the Text input converter.

Text Output Converter

The Text output converter converts the intermediate representation of the input file to a Text output file. The following list summarizes the data mapping and conversion restrictions relevant to the Text output converter:

• Data mapping
  All Latin1 text in the intermediate representation of the input file is converted to the text output file.
  When converting an input file to a text output file, you should be aware that text output files can contain only textual content and minimal formatting such as line feeds, page breaks, and tabs. The Text output converter preserves formatting information to the extent possible. Page coordinates convert to the nearest character cell (line,column) position.
• Conversion restrictions
  All graphics, images, and text attributes in the intermediate representation of the input file are lost when converted to the text output file.
  Because a monospace font is used, it is possible that some text may be lost due to overwriting to preserve the layout. It is also possible that 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.

PostScript Output Converter

The PostScript output converter converts the intermediate representation of the input file to a PostScript output file. The following list summarizes the data mapping and conversion restrictions relevant to the PostScript output converter.

• Data mapping
  The information in the intermediate representation of the input file maps directly to the PostScript output file.
• Conversion restrictions
  The intermediate representation of the input file does not lose any information when converted to the PostScript output 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.

/OPTIONS=options-filename

Specifies a text file that contains processing options applied to the input file and the output file during the conversion. The default file type for an options file is .CDA$OPTIONS.

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 type of .CDA$OPTIONS on the operating system.

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. However, you may require an options file if you need to use other than the default settings.

Use the following guidelines to create an options file:

• Begin each line of the options file with the keyword for the input or output format, followed by one or more spaces or tabs, or by a slash (/).
  For some file formats, such as DDIF and DTIF, there is an input converter and an output converter. You can restrict a processing option to only the input format or the output format by following the format keyword with _INPUT or _OUTPUT.
• Specify only one processing option on each line when there are several options for the same input or output 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 keyword because 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.

Processing Options for Analysis Output

The Analysis output converter supports the following options:

• COMMENT DEFAULT_VALUES
  Inserts a comment character (!) at the beginning of lines generated by default values. (The comment prefix is also included on associated aggregate brackets and array parentheses where they may apply.)

• COMMENT INHERITED_VALUES
  Inserts a comment character (!) at the beginning of lines generated by inherited values. (The comment prefix is also included on associated aggregate brackets and array parentheses where they may apply.)
• 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 can be overridden by supplying the TRANSLATE_BYTE_STRINGS option.
• 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.
• 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.

Processing Options for Text Output

The Text output converter supports the following options:

• 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.
• 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.
• 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.
• 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.
• SOFT_DIRECTIVES [ON,OFF]
  Causes the Text output converter to obey the soft directives contained in the document when creating your text output file. If this option is not specified, the default is OFF; if this option is specified without a value, the default is ON.
• 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.

PostScript Output Converter

The PostScript output converter supports the following options:

• PAPER_SIZE size
  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.
• PAPER_HEIGHT height
  Specifies a paper size other than one of the predefined values provided. The default paper height is 11 inches.
• PAPER_WIDTH width
  Specifies a paper size other than one of the predefined sizes provided. The default paper width is 8.5 inches.
• PAPER_TOP_MARGIN top-margin
  Specifies the width of the margin provided at the top of the page. The default value is 0.25 inch.
• PAPER_BOTTOM_MARGIN bottom-margin
  Specifies the width of the margin provided at the bottom of the page. The default value is 0.25 inch.
• PAPER_LEFT_MARGIN left-margin
  Specifies the width of the margin provided on the left-hand side of the page. The default value is 0.25 inch.
• PAPER_RIGHT_MARGIN right-margin
  Specifies the width of the margin provided on the right-hand side of the page. The default value is 0.25 inch.
• PAPER_ORIENTATION orientation
  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.
• EIGHT_BIT_OUTPUT [ON,OFF]
  Specifies whether the PostScript output converter should use 8-bit output. The default value is ON.
• LAYOUT [ON,OFF]
  Specifies whether the PostScript output converter processes the layout specified in the DDIF document. The default value is ON.
• OUTPUT_BUFFER_SIZE output-buffer-size
  Specifies the size of the output buffer. The value you specify must be within the range 64 to 256. The default value is 132.
• 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.
• 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.
• 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.

Domain Converter

You might 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 described in this section. 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.

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

The domain converter supports the following options:

• COLUMN_TITLE
  Displays the column titles as contained in the column attributes centered at the top of the column.
• 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.
• 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.
• 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.
• PAGE_NUMBER
  Displays the current page number in the top right corner of the page.
• PAPER_SIZE size
  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)
  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	13 x 254 millimeters (15600 x 10 inches)
  9x12_ENVELOPE	12 x 229 millimeters (14400 x 9 inches)
  BUSINESS_ENVELOPE	9.5 x 105 millimeters (11400 x 4.13 inches)
  EXECUTIVE	10 x 191 millimeters (12000 x 7.5 inches)
  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.
• PAPER_HEIGHT height
  Specifies a paper size other than one of the predefined values provided. The default paper height is 11 inches.
• PAPER_WIDTH width
  Specifies a paper size other than one of the predefined sizes provided. The default paper width is 8.5 inches.
• PAPER_TOP_MARGIN top-margin
  Specifies the width of the margin provided at the top of the page. The default value is 0.25 inch.
• PAPER_BOTTOM_MARGIN bottom-margin
  Specifies the width of the margin provided at the bottom of the page. The default value is 0.25 inch.
• PAPER_LEFT_MARGIN left-margin
  Specifies the width of the margin provided on the left side of the page. The default value is 0.25 inch.
• PAPER_RIGHT_MARGIN right-margin
  Specifies the width of the margin provided on the right side of the page. The default value is 0.25 inch.
• PAPER_ORIENTATION orientation
  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.

Example

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

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.