Command-Line Interface

While FME's graphical user interface is well suited for most uses, FME also has
a powerful and flexible command-line interface that enables it to be used as a 
component of a batch processing environment.

    Starting FME from the Command Line

Type fme on the command line to start the FME command-line utility.

    Using Command-Line Options

The fme command supports the following options:

    Syntax
       Reference Section
    
    fme COMMAND_FILE <commandFile>
       Executing Batch Files (Multiple Runs Per Session)
    
    fme Generate ...
       Generating Mapping Files
    
    fme GENTRANS
       Performing Generic Translations
    
    fme LIST_TRANSFORMERS [VERBOSE]
    fme LIST_UNLICENSED_TRANSFORMERS
       Listing Transformers
    
    fme <mappingFile>
       Running Custom Mapping Files
    
    fme PARAMETER_FILE
       Generating Mapping Files
    
    fme PROTECT <sourceFile> <destFile>
       Reading Command-Line Parameters from a File
    
    fme <TclFile> ...
       Reading Command-Line Parameters from a File
    
    
    Executing Batch Files (Multiple Runs Per Session)
    
fme COMMAND_FILE <commandFile>

This option is used to execute an FME batch file, as follows:

    fme COMMAND_FILE <commandFile>

Normally, FME starts up and shuts down for each translation. In cases where 
users want to process a large number of files, the time taken to start and stop 
can become significant. In order to operate more efficiently in such situations, 
FME supports a mode where it runs several times in a single session without the 
resources required to restart.

To use FME in this way, a command file must be created that consists of multiple 
FME command lines. These command lines are executed in the order they are 
specified when FME is run.

A command file is invoked using the following syntax:

    fme COMMAND_FILE <cmdFile>

The command file must contain one command per line. Line continuation characters 
(\) can be used to split commands over several physical lines in the file. The 
commands that can be processed in this way are: mapping file generation, running 
a mapping file, and even executing another batch file. For example, the command 
file might contain lines like:

    c:\dxf2dgn.fme --SourceDataset c:\in1.dxf --DestDataset c:\out1.dgn 
    c:\dxf2dgn.fme --SourceDataset c:\in2.dxf --DestDataset c:\out2.dgn

Command lines that generate mapping files could also be present in the command 
file. Notice that the word "fme" is not present as the first word of each 
command, as it would be if this were a DOS Batch (.BAT) file.

Mapping files run in this way should contain LOG_FILENAME lines so that 
statistics on FME performance are gathered. Alternately, a LOG_FILENAME could be 
specified at the end of each command line:

    c:\dxf2dgn.fme --SourceDataset c:\in1.dxf --DestDataset c:\out1.dgn LOG_FILENAME 
    c:\fme.log
    c:\dxf2dgn.fme --SourceDataset c:\in2.dxf --DestDataset c:\out2.dgn LOG_FILENAME
    c:\fme.log
    
An example batch run might look like this:

    fme COMMAND_FILE c:\fmebatch.cmd

    CONTINUE_ON_FAIL

The CONTINUE_ON_FAIL optional keyword controls whether or not to continue 
running the translations in the command file. If its value is no, all the 
translations will fail if one translation fails.

    fme COMMAND_FILE fmebatch.cmd CONTINUE_ON_FAIL no

If the keyword is not used, then all the translations will run, and a summary of 
the failures is output at the end.

    Return Codes

When FME is run as a command-line utility, it produces informational messages on 
its standard error output stream. When the mapping file generation or 
translation has completed, FME will exit with a return code of 0 if there was no 
error, and with -1 if there was. In general, a calling script should test for 
zero as a successful return code and non-zero as a failure.

Note that it is possible for FME to exit with a zero return code, indicating 
success even if no output was produced. A variety of situations result in this 
condition; for example, if a query was issued to a spatial database that 
returned no features, the translation would succeed even though there was no 
output. Software calling FME to perform translations may wish to do additional 
checks on the output data to ensure that something was produced.


    Generating Mapping Files

    fme Generate

This option is used to generate a mapping file without performing a translation. 
It is equivalent to using File > Generate from the FME Universal Translator user 
interface, and is used as follows:

    fme Generate ...

Note: You can generate mapping files in this way; however, Safe Software 
recommends that you use Workbench to configure translations.

Here is some example syntax:

    fme Generate <readerType> <writerType> <sourceDataset> <mappingFile> \
     [+DATASET <additionalSourceDataset>]* \
     [+MERGE_SCHEMAS (yes|no)] \
     [+FME_DEBUG DUMP_SCHEMA] \
     [--APPEND_LINE <text>]* \
     [--<macroName> <value>]*
    
Note that pre-FME-2013, the line [--APPEND_LINE <text>]* was [--APPEND_LINE 
<text>]

Tip: It is usually easier to customize a mapping file generated by FME or 
Workbench than to build a mapping file from scratch. The generated mapping file 
may be edited and customized for the particular translation. See Running Custom 
Mapping Files.

The following example, which should appear as one continuous line,

    fme Generate SHAPE MIF /usr/shapedata/92b034 /tmp/s2m.fme

would generate a mapping file in /tmp/s2m.fme which could be used to translate 
all the Shape files in the /usr/shapedata/92b034 directory to MapInfo MID/MIF.

Additional source datasets of the same source format can be combined in the 
initial generate command to create a mapping file that will merge them all when 
run. The +DATASET directive is used to specify an additional dataset, and this 
can be repeated multiple times. In such a situation, the +MERGE_SCHEMAS 
directive controls whether or not all the specified datasets are examined for 
schema information. If MERGE_SCHEMAS is set to no, then only the <sourceDataset> 
has its schema extracted. This is used when it is known that all the input 
datasets have the same schema. If it is set to yes, then each of the source 
datasets specified have their schema extracted, and the union of these schemas 
is used to generate the mapping file. The default for MERGE_SCHEMAS is no.

The +FME_DEBUG DUMP_SCHEMA can be added to the generate command line to have the 
schema information from the source dataset logged to standard output when the 
generate is done. This can be used to determine why a generated mapping file 
does not seem to have the appropriate schema information in errant 
circumstances.

When the --APPEND_LINE option is used, the specified text is added at the end of 
the mapping file on a line by itself.


    Performing Generic Translations

This method of using the FME translation engine allows translations to be 
performed without requiring a workspace or mapping file to provide the 
translation rules. When used in this mode, the FME will make a "best guess" for 
a translation between two formats.

GENTRANS

FME's GENTRANS mode is a simple and easy way to perform a quick translation 
between two formats.

GENTRANS is useful when you need to perform quick translations between different 
formats, and don't need to perform any special operations that might require 
either Workbench or a mapping file. GENTRANS performs translations that are very 
similar to the Universal Translator's Generate/Translate functionality.

Command-Line Syntax

    Fme GENTRANS [OPTIONS] <param-file>
    Fme GENTRANS [OPTIONS] <param-file> <source-dataset> <dest-dataset>
    Fme GENTRANS [OPTIONS] < source -format> <source-dataset> <dest-format>
      <dest-dataset>
    Fme GENTRANS [OPTIONS] < source -format> <source-dataset> <source-directives> 
      <dest-format> <dest-dataset> <dest-directives>
    Fme GENTRANS [OPTIONS] <session-directives> < source -format> <source-dataset> 
      <source-directives> <dest-format> <dest-dataset> <dest-directives>

Description

The minimum amount of information that FME GENTRANS requires in order to 
function is:

-    Source/Destination Formats: The "Short Name" as listed in the Formats 
    Gallery.

-    Source/Destination Datasets: Where the data should be read from, and written 
    to.

In addition to the required configuration information, GENTRANS also allows 
directives to be passed directly to the FME translation session, as well as to 
the individual readers and writers.

The above configuration information can be passed to GENTRANS either via the 
command line, or via a parameter file.

As shown in the synopsis, there are are several different command line forms 
allowed.

Note: The Generic Translator is implemented using FME Objects - using some 
advanced functionality requires an understanding of FME Objects.

The components of the command line are:

<param-file>
   The location of the parameter file

<source-dataset>
   The location of an existing dataset.

<dest-dataset>
   The location where the data will be written to. Note: If the dataset exists, it 
   will be overwritten.

<source-format>
   The short name of the source format.

<dest-format>
   The short name of the destination format.

<session-directives>
   Any directives to pass to the FME session. 
   Note: See FME Objects documentation at
   www.safe.com/download/index.php#obj_documents

<source-directives>
   Any directives to pass to the FME reader. Note: See FME Objects documentation 
   www.safe.com/download/index.php#obj_documents.

<dest-directives>
   Any directives to pass to the FME writer. Note: See FME Objects documentation 
   www.safe.com/download/index.php#obj_documents.

Note: Directives are specified using a comma-separated list of strings. Where 
possible, it is recommended that directives not be specified on the command 
line, but are instead put in a parameter file.

    Options

The following options are currently supported. These options must be specified 
right after GENTRANS on the command line.

[LOG_STANDARDOUT <YES|NO>]
   If YES, the session will log to standard output as the translation executes.

[LOG_ TIMINGS <YES|NO>]
   If YES, the standard FME timings will be logged.

[LOG_FILENAME <filepath>]
   If specified, an FME translation log will be created at the specified location. 
   If not specified, no log file will be created.

[GUI]
   If specified, an FME dialog will pop up, allowing the source and destination 
   formats and data to be specified. The selected formats and data will override 
   any formats or data specified on the command-line or in a parameter file.

[GENERATE <param-file>]
   If specified, the translation will not run, and a parameter file will be 
   generated instead.

[GENERATE_CMDLINE]
   If specified, the translation will not run, and the command-line arguments will 
   be printed to standard output. When used with the GUI option, this option allows 
   users to determine which command-line options to use for a translation.

[PIPELINE <pipeline-file>]
   Specifies a file containing an FME factory pipeline. Features read from the 
   source will be processed using this pipeline before being written to the 
   destination.

    Wildcard Support

Instead of exactly specifying source datasets, it is possible to use the "*"
character to specify several files at once. This is especially useful for 
merging several files.

For example,

    GENTRANS SHAPE "*.shp" FFS out.ffs

Note: When using wildcards, the source dataset must be enclosed in quotation 
marks to prevent the shell's file globing mechanism from taking over.

    Parameter File Format

The GENTRANS parameter file uses a simple format that is very similar to older 
Window's INI files. Each parameter file is broken into sections. Within each 
section, there are multiple key-value pairs.

    Syntax

The syntax for the parameter file is very simple. Sections begin with the 
specification of a section header, and run until either another section header, 
or the end of the file, is reached.

Each section header occurs on its own line and are of the form:

    [ SectionName ]

Within each section, there are multiple key-value pairs of the form:

    Key = Value

    Sections

The following sections are currently supported:

SESSION

Specifies session-specific configuration options:

GENTRANS-specific keys:

    GENTRANS_PIPELINE: The name of a pipeline file.

Any other key-value pairs are assumed to be session directives and will used to 
initialize the session.

SOURCE

Specifies source-specific configuration options:

GENTRANS-specific keys:

    GENTRANS_FORMAT: The short name of the format

    GENTRANS_DATASET: The dataset that will be read

Any other key-value pairs are assumed to be reader directives and will be passed 
to the reader.

DESTINATION

Specifies destination-specific configuration options:

GENTRANS-specific keys:

    GENTRANS_FORMAT: The short name of the format

    GENTRANS_DATASET: The dataset that will be written

Any other key-value pairs are assumed to be writer directives and will be passed 
to the reader.

CONSTRAINTS

Constrain the reading to a certain subset of the dataset.

Note: Using constraints is an advanced functionality, and assumes familiarity 
with FME's FME Objects API.

This section's key-value pairs are used to construct a constraints feature that 
will be used with the reader's setConstraints method.

Either a bounding box, or a set of coordinates is required to construct the 
feature. To specify a list of coordinates, use the following keys: 
GENTRANS_X_COORDS, GENTRANS_Y_COORDS, GENTRANS_Z_COORDS. Each of these keys take 
a comma-separated list of floating point numbers as a value.

Note: If a 2 dimensional constraint is desired, the GENTRANS_Z_COORDS key does 
not need to be specified.

For example,

    GENTRANS_X_COORDS = 0.0, 1.5, 1.5, 0.0, 0.0
    GENTRANS_Y_COORDS = 0.0, 0.0, 2.5, 2.5, 0.0

A bounding box is specified with the GENTRANS_BOUNDING_BOX key name. The value 
must have the following format:

    <minx>, <maxx>, <miny>, <maxy>

where minx, maxx, miny, and maxy are floating point numbers.

For example,

    GENTRANS_BOUNDING_BOX = 0.0, 2.5, 0.0, 1.5

In addition to the geometric constraints, a search type must also be specified 
using the FME_SEARCH_TYPE key. Values for the search type can be found in the 
FME Objects documentation.

For example,

    FME_SEARCH_TYPE = FME_ENVELOPE_INTERSECTS

Certain search types require additional key-value pairs to be specified as 
parameters.

Any additional key-value pairs in this section will be passed as attributes on 
the constraints feature. See the FME Objects documentation for more details.

    Parameter File Generation

GENTRANS offers a GENERATE mode that provides a quick method of creating 
parameter files. This mode is especially useful for formats that require several 
directives.

To generate a parameter file, take any valid GENTRANS command-line, and add the 
GENERATE <parameter file> option. The translation will not run, and a new 
parameter file will be generated (even if another one was used).

Usage of the GUI option further increases the usefulness of this feature by 
allowing a user to specify format options in a dialog box.

For example,

    GENTRANS GUI GENERATE filename.param SHAPE foo.shp MIF foo.mif

    Examples

Using Coordinate System Reprojection
    
    FME GENTRANS LOG_FILENAME gentrans.log ACAD drainage_design_P001.dwg 
    COORDSYS,BritishNatGrid ACAD drainage_design2_P001.dxf COORDSYS,BritishNatGrid

Translating with a Parameter File

Generating a parameter file:
    
    FME GENTRANS GUI GENERATE key.param ACAD drainage_design_P001.dwg ACAD 
    drainage_design2_P001.dxf

Using a parameter file:

    FME GENTRANS LOG_FILENAME logfile.txt parameter_file.txt

Generating a GENTRANS Command from a GUI

This example opens a GUI which outputs a GENTRANS command line. To run it, 
prefix it with FME GENTRANS.

    FME GENTRANS GUI GENERATE_CMDLINE

Generating a GENTRANS Commmand from a Parameter File

    FME GENTRANS GENERATE_CMDLINE key.param

Translating with Reader and Writer Directives

    FME Gentrans ACAD "S:\key-systems\drainage_design_P001.dwg"
    "RUNTIME_MACROS,\ 
    "METAFILE,acadScan,_EXPAND_BLOCKS,no,_EXPAND_VISIBLE,no,_BULGES_AS_ARCS,no,_STORE_
    BULGE_INFO,yes,_READ_PAPER_SPACE,no,ACAD_IN_READ_GROUPS,no,_IGNORE_UCS,no,_MERGE_S
    CHEMAS,YES\",META_MACROS,\ 
    "Source_EXPAND_BLOCKS,no,Source_EXPAND_VISIBLE,no,Source_BULGES_AS_ARCS,no,Source_
    STORE_BULGE_INFO,yes,Source_READ_PAPER_SPACE,no,SourceACAD_IN_READ_GROUPS,no,Sourc
    e_IGNORE_UCS,no\
    ",METAFILE,acadScan,COORDSYS,BritishNatGrid,IDLIST," ACAD 
    "S:\key-systems\drainage_design_P001.dxf" "RUNTIME_MACROS,\ 
    "_ATTRKIND,external_attributes,_REL,Release2000,_TMPL,S:\key-systems\drainage_desi
    gn_P001.dwg\",META_MACROS,\ 
    "Dest_ATTRKIND,external_attributes,Dest_REL,Release2000,Dest_TMPL,S:\key-systems\d
    rainage_design_P001.dwg\",METAFILE,ACAD,COORDSYS,BritishNatGrid"
    
Using GENTRANS for Batch Processing

    for /R x: %%F in (*.shp) do fme gentrans LOG_FILENAME "y:\%%~pF%%~nF.log"PIPELINE
    ground2grid.fmi SHAPE "%%F" SHAPE "y:\%%~pF"

Listing Transformers

The following parameters, which are used almost exclusively for internal testing 
purposes, list licensed and unlicensed transformers. If the VERBOSE option is 
specified, all functions and factories used by each transformer will also be 
listed.

    fme LIST_TRANSFORMERS [VERBOSE]
    fme LIST_UNLICENSED_TRANSFORMERS

Running Custom Mapping Files

fme <mappingFile>

This option, the most common use of the FME command-line utility, is used to 
translate data from one format to another. It is equivalent to using File > Run 
from the graphical user interface and is used as follows:

    fme <mappingFile> [--<macroName> <value>]* [[-]<overrideKeyword> <value>]* 
    [+<addKeyword> <value>]*

When FME is invoked in this way, all parameters pertaining to the translation 
session are extracted from the mapping file specified. The additional optional 
arguments are used to override or supplement the contents of the mapping file.

For example,

    fme roadgen.fme

Running Custom Mapping Files

fme <mappingFile>

This option, the most common use of the FME command-line utility, is used to 
translate data from one format to another. It is equivalent to using File > Run 
from the graphical user interface and is used as follows:

    fme <mappingFile> [--<macroName> <value>]* [[-]<overrideKeyword> <value>]* 
    [+<addKeyword> <value>]*

When FME is invoked in this way, all parameters pertaining to the translation 
session are extracted from the mapping file specified. The additional optional 
arguments are used to override or supplement the contents of the mapping file.

For example,

    fme roadgen.fme

Defining Macros

Frequently, a mapping file intentionally references a macro that it does not 
define. It is assumed that when the mapping file is used, such macros will be 
given values on the command line.

Macros are defined on the command line by preceding the macro name with two 
dashes. The value that follows the macro name is assigned to it.

Note: Macros specified on the command line provide only an initial value for the 
macro. If the macro is defined anywhere in the mapping file, the mapping file's 
definition overrides that given on the command line.

In the following example, the roadgen.fme file contains the line:

    SAIF_DATASET $(saifFile)

However, the saifFile macro is not defined anywhere in this mapping file. A 
value for the macro must be provided on the command line:

    fme roadgen.fme --saifFile /usr/data/92j013.zip

Overriding Mapping File Settings

Any keyword settings in the mapping file may be overridden on the command line 
simply by listing the keyword, optionally preceded by a dash, followed by its 
new value.

Any values for the keyword that are already in the mapping file will be 
overridden by the new value.

The following example sets the READER_TYPE keyword value to SAIF and the 
WRITER_TYPE keyword value to SHAPE. The values provided for READER_TYPE and 
WRITER_TYPE in the mapping file are ignored.

    fme roadgen.fme -READER_TYPE SAIF -WRITER_TYPE SHAPE

Note that since the dashes are optional when keyword values are being 
overridden, the previous example is equivalent to:

    fme roadgen.fme READER_TYPE SAIF WRITER_TYPE SHAPE

Extending Mapping File Settings

The keyword settings in a mapping file may be extended on the command line by 
preceding the keyword with a plus sign (+), and listing the additional values 
for the keyword.

The result is the same as if the keyword and values were placed at the end of 
the mapping file. This is only useful for keywords accumulating their values and 
may be specified more than once in the mapping file. It is most commonly used to 
add to the _IDs being read by the reader module during an FME session.

The following example adds the Lanes ID to the other IDs that were requested for 
translation in the roadgen.fme mapping file. If this mapping file originally 
included a line stating SAIF_IDs Roads Railroads and the command line below was 
used, the SAIF Reader would process the features in the Roads, Railroads, and 
Lanes collections.

    fme roadgen.fme +SAIF_IDs Lanes

However, if the plus sign (+) was not used and the command line below was given 
instead, then the SAIF_IDs on the command line would override those in the 
mapping file, and only the Lanes collection would be processed.

    fme roadgen.fme -SAIF_IDs Lanes

Reading Command-Line Parameters from a File

fme PARAMETER_FILE ...

This option reads command-line parameters from a file. Although the number of 
macros or keywords that can be specified on the FME command line is unlimited, 
some operating systems place a limit on overall command-line length.

This option serves as a workaround when such a limit is reached - it tells FME 
to read the command-line parameters from a file as follows:

    fme PARAMETER_FILE ...

Note: Two additional FME command-line options can be used when FME is run in 
server mode. These options are documented in the FME Server Administrator's 
Guide (available at www.safe.com/support/onlinelearning/documentation.php).

Password Protecting a Mapping File

This option is used to permanently protect a mapping file. You do not require a 
password: once you protect a file using this option, you cannot remove the 
protection.

    fme.exe PROTECT <sourceFile> <destFile>

Using a password

If you want to protect a file but allow access with a password, you can follow 
the steps in the example below:

1    Create an .fmi file (for example, password.fmi) that includes the following 
    information:

MACRO password secretPass
MACRO username secretUser

2    In your main mapping file, include the following statement:

INCLUDE password.fmi

3    From the command line, protect password.fmi:

fme PROTECT password.fmi passwordp.fmi

4    In the main mapping file, change the INCLUDE line to:

INCLUDE passwordp.fmi


    Executing Tcl Programs

fme <TclFile>

FME can also be requested to execute Tcl (version 8.5.2) scripts, which in turn 
can run FME translations and perform shell commands through its command-line 
interface. A Tcl program is executed using the following syntax:

    fme <TclProgramName> [<argument>]*

where TclProgramName must have a .tcl extension. Any additional arguments will 
be passed to the Tcl program in the argv list, and argc will be set to the 
number of additional arguments. For example, if test.tcl contains these lines:
    
    puts "argc is: $argc"
    puts "argv is: $argv"
    foreach i $argv {
     puts $i 
     fme $i.fme --SourceDataset $i.e00
    }

the FME command-line utility is then invoked as follows:

    fme test.tc train railway

And as a result, FME executes the following commands:

    fme train.fme --SourceDataset train.e00
    fme railway.fme --SourceDataset railway.e00

    Tcl Functions

In a Tcl script, FME provides the following Tcl functions:

FME_CommonPrefix

Returns the longest common prefix shared by all input string arguments.

Syntax:

    FME_CommonPrefix <arg1> <arg2> . . .

-    All arguments are strings. Any number of strings may be passed in.

-    Returns a string.

Example:

    FME_CommonPrefix "c:/data1/bob.txt" "c:/data1/subdir2/joe.txt" returns "c:/data1/"

FME_RecursiveGlob

Expands all input arguments into a single list of filenames, according to the 
pattern matching rules described in Reader Datasets.

Syntax:

    FME_RecursiveGlob <arg1> <arg2> . . .

-    All arguments are strings. Any number of strings may be passed in.

-    Returns the files as a list of strings.

FME_TempFilename

Generates a temporary filename in FME temporary directory. The filename is 
guaranteed to be a new file. The returned filename will have no extension.

Note that FME will create an empty file with the given name; you must delete it 
when you are done.

Syntax:

    FME_TempFilename

Example:

    FME_TempFilename

     returns "c:/Temp/FME_a02724"