5.   Using KEYpak Command Line

This chapter provides detailed information on how to convert documents by using the KEYpak command line and its parameters.


The KEYpak command line consists of the command name kw followed by a number of parameters.  These parameters define the operations to be performed. 


In general, the syntax of the command line is as follows:

 

kw [-s<src-mnemonic>] -t<trg-mnemonic> [options] <src-file> <trg-file>

                      Notes               Parameters in square brackets are optional.  When entering command from the console, DO NOT type brackets of any kind.

                                               Unless otherwise indicated, all commands must be in lower case.  For example, the following two commands are not equivalent in KEYpak.

KW -SDX -TWO SRC TRG
kw -sdx -two src trg

Parameters passed to KEYpak must specify the following information:

 

       Target conversion mnemonic

       Source and target document file names

[options] in the KEYpak command line refer to the following optional parameters:

 

       -l <file-spec>                                                -nl

       -A                                                                  -nr

       -c<file-spec>                                                -q

       -d                                                                   -O

       -i                                                                     -bs

       -o<file-spec>                                                -bt

       -L<file-spec>                                                -bf=<name string>

       -r<file-spec>                                                 -bc=<name string>

       -p                                                           

 

 

<file-spec> is a standard UNIX file specification (wild card characters are not supported in file specifications in any context).

 

Each of the command line parameters is described in detail on the following pages.

Specify Source Translator

-s<src-mnemonic>

To specify a source translator, use the -s<src-mnemonic> parameter.  This parameter identifies the mnemonic name of the source document’s format and determines which source conversion module is to be used to interpret the source document file.  See Appendix A for a list of conversion modules and their corresponding mnemonics.

<src-mnemonic> must be a valid source conversion mnemonic name which actually exists in the conversion library.  A mnemonic must immediately follow the -s parameter specification.

If -s<src-mnemonic> appears more than once on the command line, only the last one will be accepted.  If the specified mnemonic is not found in the library, an error is reported and the application terminates.

This parameter is optional.  If it is not specified on the command line, KEYpak will call upon the auto-detect function to determine the format of the source document.  If the format is identified and the corresponding translator is available on your system, the conversion will be invoked.  The identified format will be listed in the log file.  If the format is not identified or the corresponding translator is not available on your system, the application will terminate with an error message.

                 Example        Specify Microsoft Word for Windows as the source.

The following command translates the Microsoft Word for Windows document src.doc to a WANG OIS/VS document called trg.doc.  The KEYpak mnemonic for Microsoft Word for Windows is mww and is designated on the command line as -smww.

kw -smww -twf src.doc trg.doc

                 Example        Use auto-detect to determine the format of the source document.

Use the following command to convert the document src.doc of unknown format to the Microsoft Word (PC) document trg.doc.

kw -tmw src.doc trg.doc

Specify Target Translator

-t<trg-mnemonic>

To specify a target translator, use the -t<trg-mnemonic> parameter.  This parameter identifies the target document’s format.

<trg-mnemonic> must be a valid target conversion mnemonic name which exists in the conversion library.  A mnemonic must immediately follow the -t parameter specification.

If -t<trg-mnemonic> appears more than once on the command line, only the last one will be accepted.  If the specified mnemonic is not found in the library, an error is reported and the application terminates.

                 Example        Specify Microsoft Word for Windows as the target.

The following command translates the src.doc document to the Microsoft Word for Windows document trg.doc.  MWW is the KEYpak mnemonic for Microsoft Word for Windows target conversion and is designated on the command line as -tmww.  The source mnemonic is not specified in this example.  KEYpak will call upon the auto-detect function to determine the format of the source document.

kw -tmww src.doc trg.doc

                        Note        The MWW target conversion will create an RTF document to be used with Microsoft Word for Windows.

Specify Source Document Name

<src-file>

A source file name must be specified for conversion operations.  KEYpak does not assume a default value for this parameter.

This parameter gives the file name of the document you want to convert.  It is the first parameter that is not preceded by a dash (-).  It must follow the optional parameters and precede the target file name.

                 Example        Specify source document name.

Use the following command to convert the MultiMate document test.doc to the Word Perfect document test.wo.

kw -smm -two test.doc test.wo

Specify Target Document Name

<trg-file>

A target file must also be specified for conversion operations.  KEYpak does not assume a default value for this parameter.

This parameter specifies the file name of the converted document.  It is the second parameter that is not preceded by a dash (-).  It must follow the source file name.

If the specified file name already exists and the -O parameter is not specified on the command line to overwrite the existing file, KEYpak will generate a message and terminate the conversion process.

                 Example        Specify target document name.

Use the following command to convert the Wang OIS/VS document wf.doc to the ASCII document af.doc.  The log file will be displayed on your terminal.

kw -swf -taf wf.doc af.doc

Optional Parameters

Specify Log File Name

-l<file-spec>

This parameter specifies the file name in which the conversion log file is to be created and stored.  A log file serves as an audit and summary of the conversion process.  It contains the following information:

       The conversion name

       Names of the source, target, and configuration files

       Warning messages

       Statistical information

In order to determine how and why a document is changed during the conversion process, you must use this option on the command line.

If the -l<file-spec> option is not specified on the command line, the log file will be displayed on your terminal.  If this parameter appears more than once on the command line, only the last one will be accepted. 

If the specified file name already exists and the -A parameter is not specified on the command line to append to the existing file, KEYpak will generate a message and terminate the conversion process.

                 Example        Create a log file.

Use the following command to convert the Microsoft Word (PC) document mwsrc.doc to the DECdx document dxtrg.doc and create the log file mwdx.log:

kw -smw -tdx  -lmwdx.log  /usr/src/mwsrc.doc  /usr/trg/dxtrg.doc

A sample log file is shown as follows.

KEYpak   -   TRANSLATION LOG   -   mwdx.log

KEYpak TRANSLATION UTILITY  -  ODX V5.0

January 8, 1998 - 9:59

Conversion is  MS Word to DECdx

Configuration file(s): 
                ‘/usr/lib/kw/dxstd.cfg’

Source document is /usr/src/mwsrc.doc

MS Word:  Merge file data; Ignored Pg.2 Ln.26

Target document is /usr/trg/dxtrg.doc

DECdx  Text beyond right margin; Text wrapped Pg.3 Ln.2



MAIN:  TRANSLATION SUCCESSFUL

STATISTICS:
Duration (secs):                  2

Characters processed:       2806

Messages logged:                2

Files created:                       1

In the above example, KEYpak uses the standard configuration file dxstd.cfg.  The Microsoft Word and DECdx translators each generate a single message during the conversion.  For detailed information on the messages generated in the log file, see chapter 6 of the KEYpak ODX Conversion Reference Guide.

Append Log to Existing File

-A

This option is used with -l<file-spec>.  This option appends warning messages and other log data generated during the conversion to an existing file.  If this parameter is not used in the command and the file specified by the -l parameter already exists, the conversion process will abort with a warning message.

                 Example        Append log to the existing file m1dc.log.

This example converts a MASS-11 document named m1.doc to an IBM DCA-RFT document named dc.doc.  To append log to the existing file m1dc.log, use the following command:

kw -sm1 -tdc -lm1dc.log -A m1.doc dc.doc

Specify Configuration File Name

-c<file-spec>

This parameter specifies the file names containing source, target and/or character set configurations.  You must specify the full name of the configuration file as KEYpak does not assume a default file extension for this file. 

                        Note        To create or modify a configuration file refer to chapter 5 of the KEYpak ODX Conversion Reference Guide.

KEYpak accepts a maximum of eight configuration files in one command line.  If this number is exceeded, only the first eight configuration files are processed.  Each configuration file name must immediately follow the -c parameter specification.  Configuration files are processed in the order in which they appear on the command line or in option files. 

When two configuration files contain values for the same configuration, only the last value encountered will be retained.

If a configuration file is not specified on the command line, KEYpak will search for the standard character set configuration file (xxstd.cfg, where xx is the KEYpak mnemonic for the target module) in the following order:

1.     Current directory

2.     On one of the search paths

3.     For the Environmental Variable KW

If the standard configuration file is not found in the above locations, KEYpak will default to internal settings.

                      Notes               The standard configuration file xxstd.cfg is generally the character set configuration file for the target conversion format.  This file defines how to translate source characters to the target document.  If any other configuration file is used on the command line, the standard configuration file will not be used.  In that case, only the standard printable characters will be passed to the target document.  All other characters will be replaced with the character specified by the target configuration “Place marker”.  Therefore, you must explicitly specify the standard configuration file (see the following example).

                                               The following target conversion formats do not require any character set configuration file:

       DEC WPS-PLUS (WPL)

       HTML Hypertext Markup Language (HTM)

       Lotus AMI Pro (AMI)

       Microsoft Rich Text Format (RTF)

       Microsoft Word for Mac (MWM)

       Microsoft Word for Windows (MWW)

       Picture Conversion (PIC)

       PostScript Formatter (PSF)

       WordPerfect 5.x for DOS/Windows (WO)

No standard configuration file (xxxstd.cfg) is available for the above formats.  For these formats, KEYpak will automatically load and map the character set files as required.

                 Example        Specify a configuration file on the command line.

The following command converts the CGM Vector format file picture.cgm to the WPG Vector format file picture.wpg.  The configuration file piccfg.cfg contains the configuration “Vector Format” defined as WPG.

kw -spic -tpic -cpiccfg.cfg picture.cgm picture.wpg

                        Note        When converting a picture file from one format to another, pic is used for both the source and the target conversion format.  You must specify a configuration file to define the format for the target file.  For detailed information on the Picture Conversion format, refer to the source/target reference files pic*.doc and chapter 7 of the KEYpak ODX Conversion Reference Guide.

                 Example        Specify two configuration files on the command line.

This example converts the Microsoft Word for Windows document mww.doc to the HP Word/PC document hw.doc.  The log file will be displayed on your terminal.  To specify the user created configuration file mwwhw.cfg and the standard HP Word/PC configuration file hwstd.cfg, use the following command.

kw -smww -thw -chwstd.cfg -cmwwhw.cfg mww.doc hw.doc

Ignore Configurations with Errors

-d

This option affects the handling of errors detected while parsing configuration files.  Normally, if an error is detected in a section (i.e. $SOURCE, $TARGET, or $CHRSET) of the configuration file, the whole section of configurations is ignored and error messages are logged.

If the -d option is specified, only the configuration with the error will be ignored.  KEYpak will log a message for the error and continue with the next configuration in that section.

                 Example        Ignore configurations with errors.

This example converts the Microsoft Word (PC) document mw.doc to the ASCII document af.doc and uses the user created configuration file mwaf.cfg and the standard ASCII configuration file afstd.cfg.  Use the following command to ignore configurations with errors:

kw -smw -taf -cafstd.cfg -cmwaf.cfg -d mw.doc af.doc

Ignore Standard Configuration File

-i

If you do not specify any configuration file on the command line, KEYpak will search and use the standard configuration file xxstd.cfg.  You can use the -i option to turn off the automatic use of this standard configuration file.

                 Example        Ignore the standard configuration file.

Use the following command to convert the MultiMate document mmsrc.doc to the IBM DCA-RFT document dctrg.doc.  KEYpak will not use the standard configuration file dcstd.cfg for this conversion.

kw -smm -tdc -i mmsrc.doc dctrg.doc

Specify Option File Name

-o<file-spec>

This parameter specifies a file containing other KEYpak parameters.  Each line of an option file is parsed and processed as though it is an extension to the application command line.

Option files are useful when the same type of conversion is executed many times.  In such cases the special configuration files and various optional parameters remain constant for all similar conversions. 

There is no limit to the number of lines or parameters which may appear in an option file.  Also there is no limit to the number of -o parameters which may appear in the command line of the conversion application (except that which is imposed by the maximum UNIX command line length). 

You must specify the full name of the option file as KEYpak does not assume a default file extension for this file.

Option files must not be nested; that is, an option file referenced on the command line must not reference any further option files.

                 Example        Specify KEYpak parameters using an option file.

This Example converts a WordPerfect document called src.doc to a MultiMate document called trg.doc, and it appends log to the existing file womm.log.  

Using any text editor, create the following sequence of commands in an option file named test.opt:

-swo
-tmm
-lwomm.log
-A

To pass the test.opt file to KEYpak for processing, use:

kw  -otest.opt src.doc trg.doc

Specify Language of Message Output

-L<file-spec>

This option allows you to select the language in which the KEYpak messages generated during the conversion process are to appear.  By default, KEYpak uses the English file default.msg, provided as part of the installation diskettes. 

                      Notes               Before using this option, you must create and compile messages in a language of your choice.  See Appendix C for detailed information on internationalizing the KEYpak messages.

                                               The message file must have the .msg extension, but do not specify this extension on the command line (see the following example).

                 Example        Specify French as the language of messages generated.

Use the following command to generate KEYpak messages in French by using the message file french.msg:

kw -saf -tmw -Lfrench src.doc trg.doc

Specify Statistics File Name

-r<file-spec>

This parameter specifies a file to which the statistical information at the end of a conversion is to be sent.  By default, the statistical information will be displayed on your terminal or in the log file.  In order to create an ASCII statistics file, it must be specified on the command line.

A statistics file provides the following information:

       The number of source characters processed

       The number of messages generated

       A measure of the duration of the conversion process

       A count of the number of target document files created

                        Note        If you do not specify the -r<file-spec> option, the statistics will still be displayed on your terminal or logged in the log file unless the -nr option is specified.

                 Example        Create a statistics file.

The following command converts the ASCII document src.doc to the WordStar document trg.doc and sends the statistical information to the stats file:

kw -saf -tws -rstats src.doc trg.doc

Prompt for Parameters

-p

If you specify the -p option on the command line, KEYpak will prompt you for the required command line parameters.

Defaults are enclosed in [ ] and any parameters specified on the command line will be used as defaults.

                 Example        Convert a document from MultiMate to MASS-11 and prompt for input.

To convert the MultiMate document src.doc to the MASS-11 document trg.doc and log all messages to the file mmm1.log, use the following command:

kw -p

The system will produce the following prompts one at a time.  Enter the desired information:

Enter source format [ ]: mm

Enter target format [ ]: m1

Enter source file name [NUL]: src.doc

Enter target file name [NUL]: trg.doc

Enter log file name [NUL]: mmm1log

Enter configuration file name [NUL]: m1std.cfg

 

Change options [n]:

If you want to change any of the information entered above, enter y for the last prompt (Change option). 

 

To add other optional parameters, you must use the command line.  For example, to include the option file test.opt and to get the prompt for KEYpak parameters, use the following command:

 

kw -p -otest.opt

Disable Log Messages

-nl

The -nl option is used to disable the creation of the log file.  This option may be used when an option file containing the -l<file-spec> parameter is used on the command line and you do not want to create the log file.  In this case, KEYpak will display the conversion log on your terminal. 

                 Example        Disable the creation of the log file.

This example converts the Microsoft Word document src.doc to the DECdx document trg.doc.  It uses an option file mwdx.opt containing the -s, -t, and -l<file-spec> parameters.  To disable the creation of the log file, use the following command.  The log will be displayed on your terminal.

kw -omwdx.opt -nl src.doc trg.doc

Disable Statistics

-nr

By default, statistical information is displayed on your terminal or included in the log file.  This option disables the creation of all statistical information.  No statistics will be displayed on your terminal, or stored in the log and statistics file. 

                 Example        Disable all statistical information.

This example converts the Microsoft Word document src.doc to the ASCII document trg.doc.  It uses an option file mwaf.opt containing the -s, -t, ‑r<file-spec> and -l<file-spec> parameters.  To disable the creation of the statistical information, use the following command:

kw -omwaf.opt -nr src.doc trg.doc

Inhibit Screen Output

-q

By default, all logged messages and statistical information is sent to your terminal.  These messages can be suppressed by:

 

       Re-routing them to files using the -l and -r options

       Specifying the -q option  (inhibits all screen output)

The -q option is useful if you want to run KEYpak as a background task.

                 Example        Inhibit screen output.

The following command converts the Microsoft Word document src.doc to the DECdx document trg.doc.  To disable all screen output, use the following command:

kw -smw -tdx -q src.doc trg.doc

Overwrite Existing Target Document

-O

This option allows you to overwrite the existing target document.  If the target document already exists and this option is not specified, KEYpak will generate a warning and terminate the conversion process.

                 Example        Overwrite the existing document.

This example converts a MultiMate document named srcdoc.mm to an IBM DCA-RFT document named trgdoc.dc.  If the document trgdoc.dc already exists, use the following command to overwrite the existing document and continue with the conversion process:

kw -smm -tdc -lmmdc.log -O srcdoc.mm trgdoc.dc

Specify MacBinary Format for Source Document

-bs

This option allows you to specify that the document you are going to convert is in the MacBinary format.

                 Example        Use the following command to convert the Microsoft Word (Mac) document ma.doc to the MultiMate document mm.doc:

kw -sma -tmm -bs ma.doc mm.doc

Specify MacBinary Format for Target Document

-bt

This parameter specifies that the target document is to be created in the MacBinary format.  This option uses default values for the MacBinary file type and MacBinary file creator.  If you want to create the target document in another MacBinary format, see the options -bf and -bc.

                 Example        Use the following command to convert the DECdx document test.dx to the Microsoft Word (Mac) document test.mwm:

kw -sdx -tmwm -bt test.dx test.mwm

In this example, -bt option will automatically set the MacBinary file type to WDBN and MacBinary file creator to MSWD for the document test.mwm.  When you use this document in the Macintosh environment, it will be invoked as the Microsoft Word document.

Specify MacBinary File Type

-bf=<name string>

Macintosh file type is one of the parameters the Macintosh operating system uses to associate data files with the application that created them.  By correctly setting these codes, documents created by KEYpak can be “double clicked” on the Macintosh to automatically invoke their associated application.

This parameter is specified in conjunction with the -bt (MacBinary target) option to over-ride the default MacBinary file type.

<name string> is a one to four character string of printable ASCII  characters.  Leading white space is not allowed.  Spaces, forward slashes (/), and commas (,) are not permitted in the name.

The default MacBinary file type varies with the word processor being used.  If the target system is:

Microsoft Word V6.0              default is                W6BN
Microsoft Word (Mac)           default is                WDBN
WordPerfect 4.2                       default is                WPPC
WordPerfect 5.x                        default is                .WP5
All others                                  default is                TEXT

                 Example        Use the following command to convert the MultiMate document test.mm to the ASCII document test.af in MacBinary format.  The converted document test.af will have TEXT as the file type and ???? as the file creator.

kw -smm-taf -bt -bf=TEXT test.mm test.af

Specify MacBinary File Creator

-bc=<name string>

Macintosh file creator is one of the parameters the Macintosh operating system uses to associate data files with the application that created them.  By correctly setting these codes, documents created by KEYpak can be “double clicked” on the Macintosh to automatically invoke their associated application.

This parameter is specified in conjunction with the -bt (MacBinary target) option to over-ride the default MacBinary file creator.

<name string> is a one to four character string of printable ASCII characters.  Leading white space is not allowed.  Spaces, forward slashes (/), and commas (,) are not permitted in the name.

The default MacBinary creator varies with the word processor being used. 

 

If the target system is:

Microsoft Word V6.0              default is                MSWD
Rich Text Format (RTF)           default is                MSWD

Microsoft Word (Mac)           default is                MSWD

WordPerfect 4.2                       default is                SSIW

WordPerfect 5.x                        default is                WPC2

All others                                  default is                ????

                 Example        Use the following command to convert the WordStar document test.ws to the WordPerfect document test.wo in the MacBinary format:

kw -sws -two -bt test.ws test.wo

The above command, by default will set the MacBinary file type to .WP5 and the MacBinary file creator to WPC2.  If you want to create the WordPerfect document test.wo with TEXT as the file type and MSWD as the file creator, use:

kw -sws -two -bt -bf=TEXT -bc=MSWD test.ws test.wo