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