HELP CONVERT — VMS 4.6
The CONVERT commands perform the following functions:
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).
Additional information available:
File
Invokes the VAX/VMS 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 VAX/VMS Convert Utility, including more information about the
CONVERT command and its qualifiers, see the VAX/VMS Convert and
Convert/Reclaim Utility Reference Manual.
Format:
CONVERT input-file-spec[,...] output-file-spec
Additional information available:
ParametersCommand QualifiersExamples
Parameters
input-file-spec[,...] Specifies the name of one or more files to be converted. If you specify more than one file, separate them with commas. You may specify up to 10 input files. Multiple input files are concatenated into a single output file. No wildcard characters are allowed in the file specification. output-file-spec Specifies the name of the output file into which the converted records are to be written. If you omit the file type, the file type of the first input file is assumed. No wildcard characters are allowed in the file specification.
Command Qualifiers
Additional information available:
/APPEND/CREATE/EXCEPTIONS_FILE/EXIT/FAST_LOAD
/FDL/FILL_BUCKETS/FIXED_CONTROL/KEY/MERGE
/PAD/PROLOG/READ_CHECK/SHARE/SORT
/APPEND
/APPEND /NOAPPEND Controls whether the output records are appended to an existing sequential file. If both /APPEND and /CREATE are specified, /APPEND overrides the /CREATE qualifier. The default is /NOAPPEND. This qualifier is ignored when the output file's organization is relative or indexed.
/CREATE
/CREATE /NOCREATE Controls whether CONVERT creates an output file or uses 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. To create a file with the same characteristics as the input file, omit the /FDL qualifier. By default, /CREATE is assumed.
/EXCEPTIONS_FILE
/EXCEPTIONS_FILE[=file-spec] /NOEXCEPTIONS_FILE Controls whether an exceptions record file is generated during the conversion. An exceptions file is a sequential file that contains a copy of any input records that cause an exception. These records are not written to the output file because of a format error. If you omit the file specification, the records are written to the current SYS$OUTPUT device. By default, no exception record file is produced.
/EXIT
/EXIT /NOEXIT Controls whether the Convert Utility exits when an exception record is encountered. If you specify /NOEXIT or omit the qualifier, the operation will continue processing records even though an exception record was encountered.
/FAST_LOAD
/FAST_LOAD /NOFAST_LOAD Controls whether a fast-loading algorithm is used for indexed files. The loading algorithm requires multiple scratch disk files. By default, a fast-loading algorithm is used.
/FDL
/FDL=file-spec Specifies the FDL file to use in creating the output file. The newly created output file will have the same name specified by the output file specification. This name overrides the name specified in the FDL file. The default file type for the FDL file is FDL.
/FILL_BUCKETS
/FILL_BUCKETS /NOFILL_BUCKETS Controls whether to override the bucket fill percentage parameter associated with the output file, and to direct CONVERT to fill the buckets with as many records as possible. By default, /NOFILL_BUCKETS is assumed. This qualifier is valid only for indexed output files.
/FIXED_CONTROL
/FIXED_CONTROL
/NOFIXED_CONTROL
Controls the behavior of CONVERT in conversions between VFC records
and other types of records (FIXED or VARIABLE).
If you specify /NOFIXED_CONTROL with VFC input records, the fixed
portion of the record is not copied to the output record.
If /NOFIXED_CONTROL is specified for VFC output records, the fixed
portion of the output record is set to 0.
If /FIXED_CONTROL is specified for VFC input records, the fixed
control portion of the record will be written as the first part of
the output record.
If /FIXED_CONTROL is specified for VFC output records, the fixed
control portion of the output record is taken from the first part of
the input record.
NOTE
When you use this qualifier, you must account for
the size of the fixed control area when calculating
the maximum size of the output record.
/KEY
/KEY[=n] Specifies the key of reference by which records are accessed from an indexed file. The /KEY option is valid only for indexed input files. If you specify an indexed output file, you must also specify /NOFAST and /NOSORT. The default is /KEY=0 (the primary key).
/MERGE
/MERGE Specifies that records are to be inserted into their proper position in an existing indexed file. If both /MERGE and /CREATE are specified, /MERGE overrides the /CREATE qualifier. When loading records into an empty indexed file or when creating a new indexed file, omit the /MERGE qualifier. This option is valid only for indexed output files.
/PAD
/PAD[=[%b]x]
/NOPAD
Controls whether short records are padded. A record is too short
when it does not contain as many bytes as the record length for
fixed-length record format.
The /PAD qualifier specifies which pad character will be used. Pad
characters are specified as follows:
Option Character
PAD NULL (00 Decimal)
PAD=x x is ASCII A-Z, a-z, or 0-9
PAD=%bx x is a number representing
an ASCII character
b represents the base of the number. Values
for b are:
D = decimal
O = octal
X = hexadecimal
The default operation is /NOPAD, which causes an exception when a
short record is encountered.
The /PAD option is valid only for fixed output record formats.
/PROLOG
/PROLOG=n Specifies the prolog version number (n) of the output indexed file. If you specify a value of 2, the output file will be either a Prolog 1 or Prolog 2 file. If you specify 3, CONVERT will attempt to create a Prolog 3 file for output. If the output file cannot fit the criteria for Prolog 3, you will receive a fatal error and the conversion will not occur. If you do not specify the /PROLOG qualifier, then CONVERT uses the VAX-11 RMS default. To see what this is on your system, use the command SHOW RMS_DEFAULT. Using the /PROLOG qualifier overrides the value given with the FDL attribute KEY PROLOG.
/READ_CHECK
/READ_CHECK /NOREAD_CHECK Controls whether each input record is read from the file a second time and compared to the record originally read. By default, no read check is performed.
/SHARE
/SHARE /NOSHARE Controls whether the input file is to be opened for sharing with other processes. If /SHARE is specified, there is a chance that another process will alter the records at the same time CONVERT is operating. Thus, the consistency of the output data file cannot be guaranteed.
/SORT
/SORT /NOSORT Controls whether the input file is sorted before loading it into an indexed file. The sort is performed on the primary key of the output file. The /SORT qualifier is valid only with an indexed output file.
/SPREADSHEET
/SPREADSHEET
Invokes Xway, a program which translates data and models among many
popular spreadsheet programs. Xway also handles generic ASCII data
stored in tabular or field format, providing compatibility with
application programs and databases.
Xway is available as an interactive, menu-driven package with
extensive on-line, context-dependent help. Experienced users of the
interactive version can streamline operations with type-ahead. Xway
can be invoked on a DCL command line and also has a callable
interface.
This optional software product is available under separate license.
Format:
CONVERT/SPREADSHEET [input-file-spec] [output-file-spec]
For more information, invoke Xway and use the <HELP> key to see
Xway's on-line help, or refer to:
o VAX Xway User's Guide -- for information about running
Xway interactively.
o VAX Xway Programmer's Guide -- for information about
Xway's callable interface.
Additional information available:
FormatsCommand qualifiersParameter qualifiersOutput options
Release Notes
Formats
Xway exchanges information to and from the following formats:
DECalc command files
DECalc grids (binary)
Lotus 1-2-3 WKS (binary)
Lotus 1-2-3 WK1 (binary)
Lotus Symphony WRK (binary)
Multiplan SYLK
DIF (Data Interchange Format)
Generic ASCII tabular files
Generic ASCII field files
Model context information can be translated for model-to-model
exchanges.
Command qualifiers
Command qualifiers are used at DCL level and can appear anywhere on
the command line. Command qualifiers are optional.
Format:
$ CONVERT/SPREADSHEET [command_qualifiers]-
[input_filename] [parameter_qualifiers]-
[output_filename][parameter_qualifiers]
For more information, see the VAX Xway User's Guide.
/DEFINITION
/DEFINITION=filename
/NODEFINITION (default)
Allows you to restore a definition file containing Xway
parameters. This file can contain all information needed to
specify an exchange. Xway performs the exchange using the
information in the specified file instead of using information
entered at the terminal.
/INTERACTIVE
/INTERACTIVE (default)
/NOINTERACTIVE
Controls whether Xway invokes the menu interface. When in
INTERACTIVE mode, a Main Menu is displayed after you invoke Xway.
The /NOINTERACTIVE qualifier lets you use Xway without using the
menu interface; there is no user interaction. This qualifier is
useful when using Xway in a batch procedure or if you want to
suppress the menus.
When in /NOINTERACTIVE mode, you must supply all necessary
information on the command line for Xway to successfully perform
the exchange. You can specify a definition file which should
contain all the information Xway requires for the exchange.
/LOG
/LOG[=filename] (default)
/NOLOG
Indicates whether Xway displays status and error messages. You
can specify a file in which Xway records the log information. If
you do not specify a file with the /LOG qualifier, Xway displays
status and error messages on the terminal screen.
Additional information available:
Examples
1. $ CONVERT/SPREADSHEET/DEFINITION=WEEKLY_SPREADSHEET/NOINTERACTIVE
In this example, Xway uses the file, WEEKLY_SPREADSHEET.XWAY, as
the definition file. The definition file contains all the
information needed to perform the exchange. The /NOINTERACTIVE
qualifier suppresses the Xway menus and prompts.
2. $ CONVERT/SPREADSHEET/LOG=FOOBAR.LOG
In this example, all Xway status and error messages are recorded
in the file, FOOBAR.LOG.
Parameter qualifiers
Parameter qualifiers are used at DCL level and provide additional
information regarding the file immediately proceeding the qualifier.
Parameter qualifiers are optional.
Format:
$ CONVERT/SPREADSHEET [command_qualifiers]-
[input_filename] [parameter_qualifiers]-
[output_filename][parameter_qualifiers]
/DATE_EDIT_STRING
/DATE_EDIT_STRING="date edit string"
Specifies the format for the date in input or output files. Valid
characters for the date edit string are:
D represents a digit of the day of the month, 1 through 31
M represents a letter in the name of the month
N represents a digit in the number of the month, 1 through 12
Y represents a digit in the year
J represents a digit of the day in a year, 1 through 365
W represents a letter in the day of the week
B represents a blank (a space)
/ represents a slash
- represents a hyphen
. represents a period
(n) repeats the previous date edit string character 'n' times.
The 'n' must be a positive integer and cannot appear at the
beginning of the date edit string. If the value of 'n' is
zero (0), the previous character in the string is ignored.
/DISCARD
/DISCARD
/NODISCARD (default)
Specifies whether Xway should keep model context information (for
example, formatting and formulas). Using the /DISCARD qualifier
causes Xway to discard model formats and to produce a file
containing only data.
Since Xway translates information that cannot be exchanged
(formulas for which no equivalent exists in the target
spreadsheet) as labels, you may want to use the /DISCARD qualifier
to translate calculated data as constants during an exchange,
rather than labels.
/FORMAT
/FORMAT=type
Specifies the type of file Xway is processing. Input and output
filenames require a format specification. The format can be the
same for both files.
The types are as follows:
DECALC[=(option,...)]
LOTUS[=option]
DIF Data Interchange Format file
SYLK SYmbolic LinK file
FIELD ASCII field file
TABULAR ASCII tabular file
Use one of the following options for DECalc type files:
V22 DECalc V2.2 files
V30 DECalc V3.0 files [default]
COMMAND DECalc command files [default]
GRID DECalc grid files
Use one of the following options for LOTUS type files:
WKS LOTUS 1-2-3 V1.A binary worksheets
WK1 LOTUS 1-2-3 V2.0 binary worksheets
WRK LOTUS Symphony V1.0 binary worksheets
/RELOCATE
/RELOCATE[=(option[,option])]
/NORELOCATE (default)
Allows you to move an entire spreadsheet to the right or left and
up or down. The maximum number of rows or columns by which a
spreadsheet can be located is 65,535 in each direction.
You can use one or both of the following options.
ROW:n Moves the spreadsheet a specified number of rows.
COLUMN:n Moves the spreadsheet a specified number of columns.
Integers specified in an option can be positive or negative.
Negative integers move the grid up or to the left, omitting data
in the upper rows and right-hand columns of the grid. Positive
integers move the spreadsheet down or to the right, adding blank
rows and/or columns to the spreadsheet.
You should specify one option when using the /RELOCATE qualifier.
You are limited to specifying two options. Options should be
enclosed in parentheses; if using more than one option, separate
the options with a comma.
/SEPARATOR
/SEPARATOR="quoted string"
where:
"quoted string" is a string using up to 80 alphanumeric
characters. Some examples of valid separators
used in a "quoted string" are:
"*" asterisk
" " <space> character
" " <tab> character
"," comma (this is the default)
"" white space (this is only valid
for input files)
Defines the separator for an input or output tabular format file.
If used as a qualifier for an input file, Xway searches for the
specified separator when reading the file. If used for an output
file, Xway inserts the separator between data cells.
The separator is only used for tabular format files.
/TRAILING_SEPARATOR_COUNT
/TRAILING_SEPARATOR_COUNT=n
Indicates the number of separators appearing at the end of each
line in an output tabular format file. Use a positive integer
with this qualifier. The default value is zero (0).
SUPERCOMP-TWENTY requires two separators.
/TRANSPOSE
/TRANSPOSE
/NOTRANSPOSE (default)
Reverses the position of the rows and columns in a grid. Rows
become columns in a transposed grid (as if the grid is rotated
around a diagonal axis, from upper left to lower right corner).
The first row becomes the first column, and the left-to-right
sequence becomes a top-to-bottom sequence.
Additional information available:
Examples
1. CONVERT/SPREADSHEET BUDGET/FORMAT=FIELD -
/DATE_EDIT_STRING="DD/MMM/YYYY"
In this example, the input file, BUDGET.FLD uses DD/MMM/YYYY as
the format for dates where:
DD = the first two digits of the day in the month, 01 through 31
MMM = the first three letters of the month
YYYY = the four digits in the year
2. CONVERT/SPREADSHEET PAYROLL/FORMAT=(LOTUS:WKS) -
SALARY/FORMAT=(DECALC:V22COMMAND)
In this example, a Lotus 1-2-3 file, PAYROLL.WKS, is being
translated to a DECalc dump file, SALARY.DMP . All other
information required for the exchange would be entered by using
the Xway menus.
3. CONVERT/SPREADSHEET PAYROLL.WKS NEWPAYROLL.WKS/RELOCATE=(ROW:10,COL:10)
In this example, the file, PAYROLL.WKS, is relocated down ten
rows and moved ten rows to the right; blank rows and columns are
added to the model.
4. CONVERT/SPREADHSEET SALES/FORMAT=TABULAR/SEPARATOR="*" -
COST/FORMAT=(DECALC:V22COMMAND)
In this example, a tabular input file. SALES.TAB is being
translated to a DECalc dump file, COST.DMP. The separator used
in the tabular file is "*" .
5. CONVERT/SPREADSHEET STAFF/FORMAT=TABULAR -
/SEPARATOR="*"/TRAILING_SEPARATOR_COUNT=2
In this example, the input file, STAFF.TAB is a SUPERCOMP-TWENTY
file; therefore, the TRAILING_SEPARATOR_COUNT qualifier is used
to indicate that two separators appear at the end of every line
in the input file.
Output options
You can rearrange and manipulate output files with Xway options.
For more information, see the VAX Xway User's Guide.
The valid output options are:
RELOCATE Moves an entire grid (or file) up or down a number
of rows, and right or left a number of columns.
TRANSPOSE Reverses the row/column orientation. The columns
become rows and the rows become columns.
DISCARD Removes the model formatting information (such as
windows, titles, formulas, and cell formats).
Release Notes
A copy of the Xway release notes is contained in the file:
SYS$HELP:XWAY011.RELEASE_NOTES
The release notes include information regarding enhancements,
restrictions, and general notes. You can type or print this file to
read the release note information.
Additional information available:
Guidelines
DECalc output uses algebraic math mode.
Xway automatically sets the math mode to "algebraic" for DECalc
format output.
DECalc comments are omitted.
Any comments you have entered during a DECalc session are stripped
out of DECalc input files.
DECalc only reads dates in the format DD-MMM-YYYY.
Xway can output DECalc files containing dates that have been
formatted according to different date edit strings, but DECalc
does not read them. This restriction applies to DECalc version
2.2 and earlier.
No recursion checking is performed for DECalc exchanges.
Xway does not check whether the model you are translating into a
DECalc output format contains recursive references. DECalc does
not handle recursive references.
Xway does not handle the DECalc continuation character from table
files.
Long lines from tabular files (which are split into smaller
logical lines with the DECalc continuation character) are
exchanged as two or more separate lines by Xway.
Xway handles larger and smaller numbers (numbers with a greater
precision) than can DECalc.
Xway reports an overflow or underflow condition when it processes
a number that is too large or too small for the precision DECalc
can handle. Numbers that overflow or underflow are translated
into labels. DECalc's largest signed number is: + or -1.7E+38
and its smallest signed number is: + or -.29E-38.
Xway does not handle redundant cell referencing for SYLK input
files.
Xway does not parse "non-concise" (redundant) cell references from
Multiplan SYLK, such as: (R3:4 C1:61 C R3). Use only one "R" or
"C" per reference. For example,
SUM(R3:4 C1:61 C) should be written as SUM(R3:4 C)
ABS(R3:4 C[-1] R3) should be written as ABS(R3 C[-1])
Xway skips cells containing redundant cell references, and reports
an "invalid cell" message to the log.
You cannot specify a lowercase separator for tabular files when you
use the interactive, menu-driven version of Xway.
If you want a lowercase separator, specify it on the DCL command
line or edit the Definition file.
Lotus 1-2-3 version 1.0 does not allow cells to reference other
cells containing text.
1-2-3 changes to zero any cells that reference other cells
containing text. In the example below, cell B1 will contain zero.
A B C
1 "text" A1
Since Multiplan and DECalc do allow cells to reference other cells
containing text, models translated with Xway and read into Lotus
1-2-3 Version 1.0 may differ from the original.
/STATISTICS
/STATISTICS /NOSTATISTICS Controls whether CONVERT displays statistics about the conversion. The statistics displayed are: o Number of files processed o Total number of exception records encountered o Total number of valid records o Elapsed time o Buffered I/O count o Direct I/O count o Number of page faults o CPU time used o Name of the output file By default, no statistics are displayed.
Additional information available:
/TRUNCATE/WORK_FILES/WRITE_CHECK
/TRUNCATE
/TRUNCATE /NOTRUNCATE Controls whether long records are truncated. A record is too long when it exceeds either the maximum record length of the file or the record length for fixed record format. If a long record is encountered and /NOTRUNCATE is specified, the record is not written to the output file. If you specify the /EXCEPTIONS_FILE qualifier, the record itself is written untruncated to the exception file.
/WORK_FILES
/WORK_FILES=n Specifies the number of temporary work files to be used during the sort process. You may specify 0 or any value from 2 through 10. A value of 0 indicates that no work files are necessary because of sufficient physical memory. By default, two work files are used during a sort. This option is unnecessary if /NOSORT is specified.
/WRITE_CHECK
/WRITE_CHECK /NOWRITE_CHECK Controls whether all writes are checked by reading the new record and comparing it to the original. By default, no write check is performed.
Examples
1. $ CONVERT/FDL=INDEXFILE CUSTSEQ.DAT CUSTIND.DAT
This command processes the file CUSTSEQ.DAT according to the
specifications in the FDL file INDEXFILE.FDL and creates the new
file CUSTIND.DAT.
2. $ CONVERT/NOCREATE/TRUNCATE/EXCEPTIONS_FILE=EXFILE -
$_VARFILE.DAT FIXFILE.DAT
This command copies records from a file with variable-length records
(VARFILE.DAT) to a file with fixed-length records (FIXFILE.DAT). It
truncates variable-length records that are longer than the
fixed-length records in FIXFILE.DAT, and copies short records to the
exceptions file EXFILE.EXC.
3. $ 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; bucket splits and RRVs
(record reference vectors) disappear, and pointers to deleted
records are reclaimed. CONVERT also establishes new RFAs (record's
file addresses) during such reorganizations.
4. $ CONVERT/APPEND SALES.TMP KANSAS::[200,2]SALES.CMD
This CONVERT 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.
/RECLAIM
Invokes the VAX/VMS 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 CONVERT/RECLAIM makes it
available. Unlike CONVERT, CONVERT/RECLAIM maintains record file
addresses (RFAs). The /RECLAIM qualifier is required. For a
complete description of the Convert/Reclaim Utility, including more
information about the CONVERT/RECLAIM command and its qualifier, see
the VAX/VMS Convert Utility in the VAX/VMS Convert and
Convert/Reclaim Utility Reference Manual.
Format:
CONVERT/RECLAIM file-spec
Additional information available:
ParametersCommand QualifiersExamples
Parameters
file-spec Specifies the Prolog 3 indexed file in which you want to reclaim buckets. This file cannot be opened for shared access during bucket reclamation.
Command Qualifiers
Additional information available:
/STATISTICS
/STATISTICS /NOSTATISTICS Controls whether statistics are displayed about the conversion when it is completed. The statistics displayed are: o Total buckets scanned o Data buckets reclaimed o Index buckets reclaimed o Total buckets reclaimed o Elapsed time o CPU time By default, no statistics are displayed.
Examples
1. $ CONVERT/RECLAIM CUSTDATA.IDX This command causes the Convert/Reclaim Utility to reclaim buckets in the indexed file CUSTDATA.IDX.