FME® Fundamentals

This manual is a technical reference that outlines fundamental

operating and configuration principles of FME.

[email protected] • www.safe.com
Safe Software Inc. makes no warranty either expressed or implied, including, but not limited to, any implied warranties of
merchantability or fitness for a particular purpose regarding these materials, and makes such materials available solely on an “as-is”
basis.

In no event shall Safe Software Inc. be liable to anyone for special, collateral, incidental, or consequential damages in connection with
or arising out of purchase or use of these materials. The sole and exclusive liability of Safe Software Inc., regardless of the form or action,
shall not exceed the purchase price of the materials described herein.

This manual describes the functionality and use of the software at the time of publication. The software described herein and the
descriptions themselves, are subject to change without notice.

Copyright

© 1994-2009 Safe Software Inc. All rights are reserved.

Revisions

Every effort has been made to ensure the accuracy of this document. Safe Software Inc. regrets any errors and omissions that may occur
and would appreciate being informed of any errors found. Safe Software Inc. will correct any such errors and omissions in a subsequent
version, as feasible. Please contact us at:

Safe Software Inc.

Fax: 604-501-9965
www.safe.com

Safe Software Inc. assumes no responsibility for any errors in this document or their consequences, and reserves the right to make
improvements and changes to this document without notice.

Trademarks

FME is a registered trademark of Safe Software Inc. All brand or product names mentioned in this document may be trademarks or
registered trademarks of their respective companies or organizations.

Document Information

Document Name: FME Fundamentals

Version: FME 2010
Date: December 2009
Contents FME Fundamentals

Chapter 1 FME Foundation . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

FME Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Supported File Types and Systems . . . . . . . . . . . . . . . . . . . . . . . 1
Functions, Factories and Transformers . . . . . . . . . . . . . . . . . . . . 2
Geometric Restructuring . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Filtering and Simplification . . . . . . . . . . . . . . . . . . . . . . . . . 3
Area and Length Calculation . . . . . . . . . . . . . . . . . . . . . . . . 3
2D and 3D Elevation Transfer . . . . . . . . . . . . . . . . . . . . . . . 4
File Aggregation and Data Integration . . . . . . . . . . . . . . . 4
Schema Redefinition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Data Source Merging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Topology Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Geometric Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Attribute Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Coordinate System Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Chapter 2 FME Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . 9

FME Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
fme_geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
fme_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Feature Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Optional Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
fme_color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
fme_feature_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
fme_dataset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
fme_basename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
FME 3D Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Formats With 3D Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Surfaces and Solids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
IFMESurfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
IFMEFace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
IFMEMesh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
IFMETriangleStrip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
IFMETriangleFan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
IFMERectangleFace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
IFMECompositeSurface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
IFMEMultiSurface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
IFMESolids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
IFMEBRepSolid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
IFMEExtrusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
IFMEBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
IFMECSGSolid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
IFMECompositeSolid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
IFMEMultiSolid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Vertex Normals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Texture Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Reader Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Feature Factory Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Transformation Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Writer Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Safe Software Inc. i

FME Fundamentals Contents

Mapping Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Chapter 3 FME Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

About FME Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Function Inverses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Function Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Transfer Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Attribute Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Attribute Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Composites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Function Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
User-Defined Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Chapter 4 FME Feature Factories . . . . . . . . . . . . . . . . . . . . . . 29

About FME Feature Factories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Factory Activation Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Factory Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
FACTORY_DEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
FACTORY_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
INPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Factory-Specific Directives . . . . . . . . . . . . . . . . . . . . . . . . . 33
GROUP_BY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Factory Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Factory Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Chapter 5 Command-Line Interface . . . . . . . . . . . . . . . . . . . . 37

Starting FME from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Using Command-Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Executing Batch Files (Multiple Runs Per Session) . . . . . . . . . . . . . . . 37
fme COMMAND_FILE <commandFile> . . . . . . . . . . . . . . . . . . . . 37
CONTINUE_ON_FAIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Generating Mapping Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
fme Generate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Performing Generic Translations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
GENTRANS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Command-Line Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Wildcard Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Parameter File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Parameter File Generation . . . . . . . . . . . . . . . . . . . . . . . . . 44
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Using Coordinate System Reprojection . . . . . . . . . . . . . . 44
Translating with a Parameter File . . . . . . . . . . . . . . . . . . . 44
Generating a GENTRANS Command from a GUI . . . . . . 44
Generating a GENTRANS Commmand from a
Parameter File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Translating with Reader and Writer Directives . . . . . . . . 44
Using GENTRANS for Batch Processing . . . . . . . . . . . . . . 45

ii Safe Software Inc.

Contents FME Fundamentals

Listing Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Running Custom Mapping Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
fme <mappingFile> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Defining Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Overriding Mapping File Settings . . . . . . . . . . . . . . . . . . . . . . . . . 46
Extending Mapping File Settings . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Reading Command-Line Parameters from a File . . . . . . . . . . . . . . . . . . . 47
fme PARAMETER_FILE ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Password Protecting a Mapping File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Using a password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Executing Tcl Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
fme <TclFile> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Tcl Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
FME User Interface Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Coordinate System Name Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Directory Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Dividers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
File Name Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Floating Point Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Informational Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Integer Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Multiple Selection List Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Password Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Single-Selection List Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Text Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Chapter 6 FME Transformation Process . . . . . . . . . . . . . . . . . 57

Transformation Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Transformation Specification Example . . . . . . . . . . . . . . . . . . . . . 59
Matching Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Transfer Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Translation Process Including Transfer Variable . . . . . . . . . . . . 61
Default Attribute Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Chapter 7 Mapping File Syntax . . . . . . . . . . . . . . . . . . . . . . . . 65

Working with Mapping Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Writer Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Dynamic Feature Type Definitions (Advanced FME) . . . . . . . . . 65
Line Continuation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Quoted Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Escaping Commas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Single-Line Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Block Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
MACRO Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Substituting Strings in Mapping Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Character Subsitutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
International Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Predefined Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
FME_ASC_xxx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
FME_BASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
FME_BUILD_DATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
FME_BUILD_NUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Safe Software Inc. iii

FME Fundamentals Contents

FME_HOME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
FME_HOME_UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
FME_HOME_DOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
FME_MF_DIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
FME_MF_DIR_UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
FME_MF_DIR_DOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
FME_MF_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
FME_MF_NAME_MASTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
FME_MF_DIR_MASTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
FME_MF_DIR_DOS_MASTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
FME_MF_DIR_UNIX_MASTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
FME_PRODUCT_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
File Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
DEFAULT_MACRO Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
INCLUDE Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Dynamic Mapping File Creation . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Dynamic Mapping File Creation Example 1 . . . . . . . . . . 76
Dynamic Mapping File Creation Example 2 . . . . . . . . . . 76
Environment Variable Expansion . . . . . . . . . . . . . . . . . . . . . . . . . 77
Static Function Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Example: Reprojecting Coordinates . . . . . . . . . . . . . . . . . 78

Chapter 8 FME Configuration . . . . . . . . . . . . . . . . . . . . . . . . . 81

Reader and Writer Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Reader and Writer Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Reader Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Dataset Wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Reader Pipelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Reader Start/End Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Reader Feature Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Log File Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
LOG_FILENAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
LOG_APPEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
LOG_STANDARDOUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
LOG_MAX_FEATURES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
LOG_MAX_RECORDED_FEATURES . . . . . . . . . . . . . . . . . . . . . . 87
LOG_MESSAGE_NUMBERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
FME_BEGIN_PYTHON and FME_END_PYTHON . . . . . . . . . . . . . . . . . . 87
FME_BEGIN_PYTHON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
FME_END_PYTHON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
FME_BEGIN_TCL and FME_END_TCL . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Translation Begin/End Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
FME_BEGIN_TCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
FME_END_TCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
FME_JVM_MIN_HEAP_SIZE and FME_JVM_MAX_HEAP_SIZE . . . . . . 102
FME_SHARED_RESOURCE_DIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Linux/UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
FME_STROKE_MAX_DEVIATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Geometry Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
FME_GEOMETRY_HANDLING . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Temporary Directory Determination . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Java VM Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

iv Safe Software Inc.

Contents FME Fundamentals

Mapping File Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Mapping File Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Minimum Build Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Safe Software Inc. v

FME Fundamentals Contents

vi Safe Software Inc.

 1
FME Foundation
Chapter 1

FME Principles
The topics in this section describe the fundamental operating and configuration principles of the
FME translation engine: the general, generic way that FME deals with geometry, attributes, display
characteristics and coordinate systems. This information provides the necessary foundation for
detailed understanding of the entire FME product family, and is relevant to anyone using FME
mapping files, FME Workbench, FME Universal Viewer, FME Objects, and the FME Plug-in
Software Development Kit (SDK).
The FME translator itself is driven by a set of rules held in a mapping file. This manual also
describes the syntax of these rules, and how they interact with mapping files, the external run-time
environment, and the various readers, writers, and processing facilities of FME. Armed with a
general understanding of FME, mapping file authors will find the necessary specific detailed
information on individual readers and writers in the FME Readers and Writers manual, and on
functions and factories in the FME Functions and Factories manual.
Although it is possible to create mapping files from scratch, it is almost always more efficient to
use FME Workbench to create translation configurations. FME Workbench workspaces are FME
mapping files with special embedded comments that allow Workbench to interpret and recreate a
graphical display.
Workspaces can be run from the FME command line and parameters can be passed from the
command line into both workspaces and mapping files, allowing easy batch translations to be run.
FME provides a fully configurable geo-object-relational data processing environment with many
capabilities. FME’s processing abilities provide the building blocks for solving difficult processing
tasks quickly and easily. The result is that FME can solve both simple and complex translation and
processing problems.
In the past, new software was written for each translation situation. Over time, this introduced a
maintenance problem because it resulted in a large number of incompatible and inflexible
translator programs. FME solves this issue by allowing the same translator program to be used to
solve a variety of translation problems.

Supported File Types and Systems

FME supports many file types and systems. The FME Readers and Writers manual available on
the FME CD or from the Downloads page on Safe Software’s website, provides detailed
information on each of these formats. Note that different editions of FME may not support all
available formats.

Safe Software Inc. 1

FME Fundamentals FME Foundation

Functions, Factories and Transformers

As data flows through FME, a series of transforming operations can be performed. The FME
provides a host of data processing options. FME functions operate on an individual feature at
a time, changing that feature or calculating some new values from it. FME factories operate on
one or more features, working with them to potentially produce new groups of features that
combine or alter the features in some way. These functions and factories are used in FME
mapping files. Workbench Transformers provide a simplified view of functions and factories
for FME Workbench. The details of all three are given in the FME Functions and Factories
manual available on the FME CD, in the on-line help, or from the Downloads page at
www.safe.com.
The paragraphs below give examples of how these facilities can be used by FME to produce
results not normally associated with simple data translation.

Geometric Restructuring

Function/Factory
Example
(Transformer)

Create an arbitrary point inside an area. For example, an @GeneratePoint

ESRI shape file may contain polygons. When these are con- (LabelPointReplacer)
verted to another format, this method may be called to create
a "centroid" or more accurately, simply an inside point; this
may be desirable by a user of that file with an IGDS system.

Create an area from explicit bounding arcs. In British Co- @Close

lumbia's 1:20 000 topographic mapping program, for exam- (LineCloser)
ple, a lake is actually a segment of a lakeshore. These
bounding segments can be assembled to produce a lake with
areal geometry.

Create an area from an explicit inside point and explicit PolygonFactory

bounding arcs. Where an area is indicated by an inside point (AreaGeneralizer)
and explicit bounding arcs, another notion of an area in SAIF
or a proprietary format may be created if required. A text node DonutFactory
and a series of lines in IGDS may thus be used to create a (DonutBuilder)
shape file polygon, with or without holes, as appropriate.

Create an area from an explicit inside point and implicit CloseFactory

bounding arcs for a coverage. In some cases, an area may (not available as a Workbench
be indicated directly only by an inside point; a coverage be- transformer)
comes a combination of a set of inside points and a set of lines
(which may be of the same or different types). This model can
be transformed such that for each area both an inside point
and the bounding arcs are specified directly.

Disaggregate the arcs defined or implied by areal ge- PIPComponentsFactory

ometry and remove any arcs that are positional dupli- (LabelPointReplacer)
cates. It may be of interest to take a series of polygons in ArcFactory
shape format, produce inside points (as described above), (LineJoiner)
with the non-graphic attributes now attached to these points,
and with one set of unique bounding arcs resulting. All dupli-
cates have been removed.

2 Safe Software Inc.

FME Foundation FME Fundamentals

Filtering and Simplification

Function/Factory
Example
(Transformer), Reader

Line simplification following the Douglas-Poikera algo- @Generalize

rithm. This algorithm leaves the end points alone, and elimi- (AreaGeneralizer)
nates a number of the intermediate points. The amount of
thinning is controlled by a single parameter.

Line simplification following the Deveau algorithm. @Generalize

This algorithm is similar to the one above; however, the posi- (AreaGeneralizer)
tion of remaining intermediate points may be altered. Three
parameters control how the simplification proceeds.

Sampling. For every n features as input, only one is output. SamplingFactory

(Sampler)

Deletion or amalgamation of features based on specific CorrelationFactory

attribute values. This capability can be accomplished with- (not available as a Workbench
out the use of functions or factories. It is inherent in the basic transformer)
correlation table. For example, many different types of roads
could be output simply as roads, or only gravel roads might be
output, or all roads might be output but only with some of a
number of attributes retained.

Creation of single features from component parts. Consider an PolygonFactory

areal feature broken into a number of parts by virtue of map- (AreaGeneralizer, Polygon-
sheet boundaries. If the different mapsheets are all used as Builder)
input, and if the neat-line segments are ignored, the true ar- MULTI-READER
eas can be automatically defined.
a. David H. Douglas and Thomas K. Peucker (Poiker), Algorithms for the Reduction of the Number of Points Re-
quired to Represent a Digitized Line or Its Caricature, CANADIAN CARTOGRAPHER, Vol. 10, No. 2, Decem-
ber, 1973, pp. 112-122.

Area and Length Calculation

Function/Factory
Example
(Transformer)

Calculate length, in either two or three dimensions, as- @Length

suming a rectilinear coordinate system. If a third spatial (LengthCalculator)
coordinate is available, lengths may be calculated in three di-
mensions, if desired. The length may be multiplied by a factor
to convert units from one measurement to another (for exam-
ple, meters to feet). A length attribute is added to the data by
this function.

Calculate area in two dimensions. Only the first two coor- @Area
dinates are considered. The area calculation takes holes into (AreaCalculator)
account. The area may be multiplied by a factor to convert
units from one measurement to another (for example, square
meters to hectares). An area attribute is added to the data by
this function.

Safe Software Inc. 3

FME Fundamentals FME Foundation

2D and 3D Elevation Transfer

Function/Factory
Example
(Transformer)

Convert the third spatial coordinate to an elevation at- @Zvalue

tribute. This is practical when translating from a format that (3DForcer, 3DPointAdder,
supports three-dimensional coordinates to one that supports 3DPointReplacer,
two-dimensional coordinates. It is appropriate when all parts ElevationExtractor)
of an object have the same elevation value, as would be true
with a point or a contour line.

Convert an elevation value to a third spatial coordinate. @Zvalue

This is applicable when translating from a 2D coordinate sys- (3DForcer, 3DPointAdder,
tem, with elevation held as a non-graphic attribute, to a 3D 3DPointReplacer,
coordinate system. In this case, the elevation attribute disap- ElevationExtractor)
pears as a non-graphic attribute in the output dataset (if de-
sired).

File Aggregation and Data Integration

Example Reader

From input of a series of files, create a single file as output. It Multi-Reader

may be of interest, for example, to take a number of topo-
graphic files (or any other type of geographic data files of in-
terest) as input and produce a single file on output. This can
aid data management.

Support file amalgamation with input files having different for- Multi-Reader
mats. It is possible to take data from different sources in dif-
ferent formats as input and produce a single file as output.

With either of the cases above, take files containing different Multi-Reader
types of data as input and produce a single file containing all
or a subset of the original data on output. For example, a for-
est cover map and a topographic map could be input; output
might consist of hydrographic features, transportation fea-
tures, and forest stands.

All of the processes described above will alter the schema (i.e., the model) of the data.
However, there are also other methods for redefining or extending the schema:

Schema Redefinition
• A series of table lookup procedures are available. For example, feature codes can be
converted to types of features, each with a series of attributes, and vice versa. With the B.C.
topographic data, 22 features codes for roads can be redefined as of being of type Road with
five attributes (number_of_lanes, surface_material, etc.). As another example, two
categorical attributes can be converted to one (and vice-versa) (@Lookup, @Split,
@Concatenate). Consider one attribute with values of left, middle, and right and another
with values of up, middle and down; these could be combined into a new attribute on output
with values of n, ne, e, se, s, sw, w, nw and center.
• Using TeeFactory (or multiple outgoing connections, in Workbench), features may be
cloned (duplicated), allowing for different processing for the two resulting streams of

4 Safe Software Inc.

FME Foundation FME Fundamentals

features. For example, if contours are input, the output might consist of the original contours,
as well as a second set of contours which have been smoothed or filtered, and perhaps
limited to only index contours or every nth contour. A user could then compare the two
versions in a browser or GIS.
• Linkages between different types of data may be changed. With the IGDS format, attribute
linkages based on graphic groups, on MS-links, or on user-defined attributes may be
changed from one to another. Fields used to link attribute files together may be changed as
well. With shape format, the link between the shape and corresponding dbf files is based
solely on position within the file. If such data is brought into IGDS + dbf (or ASCII
delimited or column-aligned text files), an explicit link can be defined and any of the options
mentioned above can be used in the graphics file.

With the kinds of sophisticated capabilities described above, data translation can be considered
as a transformation or manipulation exercise, operating on all features within a given dataset,
or on only some types of features, at the user's discretion. Efficient use of FME can
significantly streamline a number of practical problems.

Data Source Merging

Through the use of the FME’s Multi-Reader, data from several different sources – possibly of
varied formats – can be read, processed, and output to a single dataset. This can be used to:
• Combine several 1:50,000 maps together, generalize them, and create a single 1:250,000
map.
• Produce derived products for an area by combining input data from diverse sources.
• Bulk load data into seamless spatial database products.
For more information, see the Multi-Reader chapter in the FME Readers and Writers manual.
FME Workbench provides a graphical interface to the Multi-Reader, and makes it very simple
to merge datasets from different formats. To merge datasets of the same format, multiple
datasets can be specified for a single reader.

Topology Operations
The FME is capable of performing sophisticated topological operations during data translation.
These topology operations can be used in the following ways:
• Form polygons, possibly with holes, from input linear geometry.
• Merge points with the polygon or donut polygon containing them. The attributes associated
with the point are then associated with the enclosing area feature.
• Remove duplicate line segments from an input data set. This is useful when the input data
set is a collection of polygons that share common boundaries and the desired output is the
set of arcs which define the polygon boundaries.
• Connect line segments together. This is used to reduce the number of features by combining
their geometry. Line breaks occur only when the attribute values of the line pieces change
or when a topologically significant node is encountered.

Safe Software Inc. 5

FME Fundamentals FME Foundation

• Generate interior points for polygons. This is used when the destination format requires an
inside point for the polygonal data.

For more information, see @GeneratePoint, PolygonFactory, ArcFactory, and DonutFactory

in the FME Functions and Factories manual.

Geometric Operations
In addition to the topological operations, FME also provides a number of geometric operations
that can be used to achieve the following results:
• Generalize features by removing points from lines, converting small polygons and short
lines to points, and converting small polygons to lines. Two different line thinning
algorithms are available and each of the generalization operations is fully configurable on a
feature-by-feature basis.
• Calculate feature area and length. These calculated values can then be stored in the
destination format or used to control other aspects of the translation process.
For more information, see @ConvertToLine, @ConvertToPoint, @Generalize, @Length and
@Area in the FME Functions and Factories manual.

Attribute Operations
While FME is primarily a spatial data translation system, it also provides an extensive suite of
attribute manipulation operations. In fact, FME does not require the data it handles to have any
spatial component and it can be used to translate between relational or object-relational
attribute databases.
The attribute operations enable FME to:
• convert data between a relational model and an object-oriented model (this capability eases
migration to systems with an object-oriented data model)
• read or write feature attributes from or to external tables during translation (several different
types of attribute files are supported)
• join multiple relational tables together to extract or output data related to a single feature

Coordinate System Conversion

All FME features know the coordinate system of their geometry. When a coordinate system
change is requested, the FME completely transforms the feature, possibly changing its type of
geometry as it moves it to the new coordinate system.
The FME automatically extracts coordinate system information from those formats that store
this information. If a source format does not contain spatial referencing information, then the
user may specify it.
In any case, the coordinate system of the output format may also be specified. If the output
coordinate system is different than the input one, then the FME will automatically convert the
feature data. To ensure that the reprojection is accurate, the FME automatically vectorizes arcs,
ellipses, rectangles, and rounded rectangle objects before doing the coordinate system change.

6 Safe Software Inc.

FME Foundation FME Fundamentals

In addition, text rotation angles and sizes are adjusted during the change. The output system or
format stores the coordinate system of the data if it has the facilities to do this.
For complete information on FME’s coordinate system support, see the FME on-line help files.

Safe Software Inc. 7

FME Fundamentals FME Foundation

8 Safe Software Inc.

 2
FME Architecture
Chapter 2

The FME translation processor consists of software modules that operate on a collection of
features. The reader modules read features from external sources. The factory modules in the
factory pipeline join features together or split them apart in a variety of ways. The transformation
module converts the feature from one format’s representation into another’s. Writer modules
output the features in a supported format. All processing aspects performed by the FME are
specified through a mapping file or workspace.
All modules in the FME output statistics, progress information, warnings, and errors to a
translation log file.

FME Features
To transport features from one format to another, FME considers features to be collections of
attribute names and values associated with two-dimensional (2D) or three-dimensional (3D)
geometry. Arbitrary dimensions will be supported in a future release. FME places no restrictions
on the values or types of attributes. Attribute names consist of one or more ASCII characters.

fme_geometry
The coordinates of an FME feature may contain any of the types of geometry shown in the
following table. All FME features have an attribute called fme_geometry that indicates their
geometry type. If the feature has no coordinates, its geometry type is set to fme_undefined.

Geometry FME Geometry

Example Description
Type Value

Point A single x, y, and possibly z set

fme_point of values representing a single
point on the earth’s surface.
A line of two or more x, y, and
Line fme_line optionally z values. Spaghetti
lines which cross themselves
are allowed, but the FME always
removes any adjacent duplicat-
ed points it finds in lines as they
are read.
A closed ring of 2- or 3-dimen-
Polygon fme_polygon sional vertices that represent an
area. The first and last points
are identical. The polygon may
follow either the right-hand or
left-hand rule.

Safe Software Inc. 9

FME Fundamentals FME Architecture

Geometry FME Geometry

Example Description
Type Value

A set of closed rings or poly-

Donut Polygon fme_donut gons. The first ring defines the
outer boundary of the area. The
remaining rings must be com-
pletely inside the outer bound-
ary and define the “holes” in the
area. No orientation rule is en-
forced.
A collection of distinct geometric
Aggregate fme_aggregate entities, treated as a single unit.
These may or may not be ho-
mogenous.

fme_type
In addition to the fme_geometry attribute which indicates what the coordinates of an FME
feature are, each FME feature also has an fme_type attribute which controls the interpretation
of those coordinates. For example, a feature with fme_geometry of fme_point may be used to
represent a point, a text object, an arc, or an ellipse. The value of the fme_type attribute is used
to indicate which interpretation should be made.
The fme_type attribute can have one of a set number of values. Depending on the value of
fme_type, there may be additional attributes required to fully interpret the geometry. The

10 Safe Software Inc.

FME Architecture FME Fundamentals

following table lists the allowed values for fme_type, the associated fme_geometry, and its
additional attributes.
fme_type fme_geometry Additional Attributes
fme_arc fme_point fme_rotation: The rotation of the primary axis in degrees
counterclockwise from the primary axis. If not set, then 0 is
assumed.
primary axis
sweep 45°
slant 45°

rotator 45°

fme_primary_axis: The length of the primary semi-axis of

the defining ellipse measured in ground units.
fme_secondary_axis: The length of the secondary semi-
axis of the defining ellipse measured in ground units. For cir-
cular arcs this value will be equal to the fme_primary_axis.
fme_start_angle:
Refer to the @Arc (function) in the FME Functions and Facto-
ries manual for a detailed definition of start_angle.
fme_sweep_angle:
Refer to the @Arc (function) in the FME Functions and Facto-
ries manual for a detailed definition of sweep_angle.
fme_area fme_polygon or None
fme_donut or
fme_aggregate

fme_collection fme_aggregate None

fme_ellipse fme_point fme_rotation: The rotation of the primary axis in degrees

counterclockwise from horizontal. If not set, then 0 is as-
sumed.
fme_primary_axis: The length of the primary semi-axis of
the ellipse measured in ground units.
fme_secondary_axis: The length of the secondary semi-
axis of the ellipse measured in ground units. For circles this
value will be equal to the fme_primary_axis.
fme_line fme_line or None
fme_aggregate
fme_no_geom fme_undefined None

fme_point fme_point or None

fme_aggregate
fme_raster fme_aggregate None

Safe Software Inc. 11

FME Fundamentals FME Architecture

fme_type fme_geometry Additional Attributes

fme_solid fme_aggregate None.
Note: fme_solid is the fme_type for the following geometries:
IFMEExtrusion, IFMEBox, IFMEBRepSolid, IFMECSGSolid, and
IFMECompositeSolid. For a description of FME Surfaces and
Solids, see FME 3D Support.
fme_surface fme_aggregate None.
Note: fme_surface is the fme_type for the following geome-
tries: IFMEFace, IFMERectangleFace, IFMETriangleStrip, IF-
METriangleFan and IFMECompositeSurface. For a description
of FME Surfaces and Solids, see FME 3D Support.
fme_text fme_point fme_rotation: The rotation of the text in degrees counter-
clockwise from horizontal. If not set, then 0 is assumed.
fme_text_string: The actual annotation string.
fme_text_size: The height of the text measured in ground
units.

Note Any features with an fme_geometry value of fme_aggregate, and an fme_type other than
fme_collection must be homogeneous aggregates. An fme_type of fme_collection allows
the feature to have heterogeneous aggregate geometry.

Feature Type
In addition to attributes and geometry, each FME feature has a feature type. Reader and writer
modules interpret the feature type in ways specific to their own formats. For example, the
Design File reader and writer uses the feature type to store the Design File level of the feature,
while the Spatial Archive and Interchange Format (SAIF) reader and writer use it to store the
SAIF class of the object. Feature types are also used in FME mapping files as the foundation
for defining the transformation specifications.

Attributes
Feature attributes are usually a primitive type: integers, floats, characters. Internally, FME
stores all attributes as character strings and automatically converts between a string
representation and a numeric representation as needed.
Collections of attributes may also be stored in a single FME feature using an attribute list.
Attribute lists behave like primitive attributes except that they contain an index enclosed in
braces ({}) to identify an element of the list. Attribute list elements may contain primitives or
other attribute lists. Attribute lists may be used by feature factories, feature functions, and the
reader and writer modules.
The following snapshot shows a portion of a multi-line text feature produced by the Design
File reader. This feature contains an attribute list named igds_text_elements which holds
both of the text elements contained in the Design File feature.
Feature Type: 35
Attribute Name Value
igds_type igds_multi_text
igds_text_elements{0}.igds_text Hello
igds_text_elements{0}.x 477556

12 Safe Software Inc.

FME Architecture FME Fundamentals

igds_text_elements{0}.y 5360183
igds_text_elements{1}.igds_text World
igds_text_elements{1}.x 477556
igds_text_elements{1}.y 5359177
Coordinates: (477553,5360181,20)

Optional Attributes
fme_color
For readers and writers that support color, an fme_color attribute holds the “pen” color of the
feature. The format of this attribute is r,g,b, where each of r,g, and b is a number between 0 and
1.
If a feature within a writer contains a format-specific color specification, then that supersedes
fme_color.

Filled polygons or ellipses are given an attribute called fme_fill_color by the reader, and
writers will check for a fme_fill_color if no format-specific fill color was present.

fme_feature_type
This attribute holds the feature type of the feature. This attribute has value only when coming
from the reader. Setting it to a specific value when it goes into a writer will have no effect.
Some attributes are not present on features by default, but can be requested via the
READER_META_ATTRIBUTES directive:

READER_META_ATTRIBUTES <requested attribute>

For example:
READER_META_ATTRIBUTES fme_feature_type

adds fme_feature_type, and

READER_META_ATTRIBUTES fme_feature_type fme_dataset fme_basename

adds fme_feature_type, fme_dataset and fme_basename.

fme_dataset
This is the source dataset of a feature stored as an attribute. This attribute has value only when
coming from the reader. Setting it to a specific value when it goes into a writer will have no
effect.
This attribute won’t be added to any features by default, so you must add this directive to the
mapping file:
READER_META_ATTRIBUTES

For example:
READER_META_ATTRIBUTES fme_dataset

Safe Software Inc. 13

FME Fundamentals FME Architecture

adds fme_dataset, and

READER_META_ATTRIBUTES fme_feature_type fme_dataset fme_basename

adds fme_feature_type, fme_dataset and fme_basename.

fme_basename
This is the root (or base) part of the filename of the source dataset of a feature. This attribute
has value only when coming from the reader. Setting it to a specific value when it goes into a
writer will have no effect.
This attribute won’t be added to any features by default, so you must add this directive to the
mapping file:
READER_META_ATTRIBUTE

For example:
READER_META_ATTRIBUTES fme_basename

adds fme_basename, and

READER_META_ATTRIBUTES fme_feature_type fme_dataset fme_basename

adds fme_feature_type, fme_dataset and fme_basename.

FME 3D Support
FME supports translation of 3D geometry from one format to another, provided that each
format itself supports 3D. The extent of 3D support is limited by the level of each format’s own
3D support. If one format supports solids and another supports only faces, the solids may be
converted to faces during the translation. Because of this, each combination of reader and
writer will have its own unique characteristics and should be tested. It is also important not to
assume a particular transformer will support 3D until you have verified it first.
As with other enhancements to FME, the first step is the extension of core infrastructure and
new geometry model, in this case to handle 3D constructs. Over time, this enhanced 3D support
will be implemented throughout FME transformers and formats where this provides the most
value.

Formats With 3D Support

Refer to specific formats in the FME Readers and Writers manual for information on which
formats support 3D. Format Quick Facts tables contain fields named solid and surface.

Appearances
The appearance provides rendering information about a 3D surface to a format viewer.
Appearances may detail the color of the surface, the reaction of the surface to lighting, or
provide a texture, which is applied in conjunction with the texture coordinates. Appearances
may be shared between surfaces, including across features. Each surface has one appearance
reference per side. An appearance reference of 0 represents a part with no appearance. The

14 Safe Software Inc.

FME Architecture FME Fundamentals

appearance reference references a common appearance that may be shared between many
surfaces.
A collection of surfaces, such as IFMEMultiSurface, IFMECompositeSurface or IFMEMesh,
may store a default appearance at the parent level for each side, this value is inherited by all
children with no appearance set. In the case of multiple inheritance, the child surface inherits
the appearance of the nearest parent who contains an appearance.
FME supports translation of surfaces with appearances from one format to another, provided
each format itself supports appearances. The extent of appearance support is limited by the
level of support within each format for appearances.

Surfaces and Solids

IFMESurfaces
IFMEFace
A face is a planar area in 3D space. The planar structure can be a polygon, an ellipse, or a donut
(IFMEArea).
The planar area has a concept of a surface normal, a vector that points outwards perpendicular
from the area. The direction of the surface normal in an IFMEFace is determined by using the
right-hand rule - if the fingers of your right hand curl along the order of the vertices, the
direction that the thumb points to is the direction of the surface normal.
Contains: IFMEArea (1)
Contained by: IFMECompositeSurface, IFMEMultiSurface

IFMEMesh
A mesh is a special collection of simple single-sided facets or parts. These parts need not have
any spatial or topological relationship between each other. A mesh is referenced geometry
containing a common vertex pool, vertex normal pool, and texture coordinate pool. The
individual parts of the mesh represent single sided faces with planar polygon structure. The
orientation of each mesh part is determined using the same rule as for faces. The parts of a mesh
are defined by indices into the common pool. By allowing reuse of shared vertices, the physical
representation size of a mesh can be smaller than an equivalent collection of surfaces.

Safe Software Inc. 15

FME Fundamentals FME Architecture

In the example, P0 to P4 are represented as mesh parts, and vertices v0 to v8 are stored in a
common vertex pool. The definition of a part is given by a list of vertex indices that reference
the common vertex pool. For example, P2 is defined by the vertex index list containing the
indices 6, 7, 4, 3, and 6.
Contained by: IFMECompositeSurface, IFMEMultiSurface

IFMETriangleStrip
A triangle strip is a series of connected triangular faces. These faces are defined by three
consecutive points in a point list. The first three vertices (denoted below by v1, v2, and v3),
define the first triangular face. A new triangle is formed by connecting the next point with its
two immediate predecessors. That is, every additional point vi defines a new triangular face
with vertices vi–2, vi–1, and vi.
For example, the second triangle is defined by v2, v3, v4, the third by v3, v4, v5, etc. The
following diagram illustrates a typical IFMETriangleStrip.

v6
v2 v4

v1

v3 v5
v7

IFMETriangleFan
A triangular fan is a series of connected triangular faces. The fan differs from a
IFMETriangleStrip in the way how vertices define faces. The first three vertices (denoted
below by v1, v2, and v3), define the first triangular face. A new triangle is formed by
connecting the next point with its immediate predecessor and the first point of the triangle fan.
That is, every additional point vi defines a new triangular face with vertices v1, vi-1, and vi.
For example, the second triangle is defined by v1, v3, v4, the third by v1, v4, v5, etc. The
following diagram illustrates a typical IFMETriangleFan.

16 Safe Software Inc.

FME Architecture FME Fundamentals

v2

v3

v4

v1
v5

v6

v7

Contains: None
Contained by: IFMECompositeSurface, IFMEMultiSurface

IFMERectangleFace
A rectangular face is an optimized face representation that represents a face that is rectangular
and that lies parallel on a coordinate plane (either xy-, xz-, or yz-plane).
This face specifies its position by using two points, the minimum corner and maximum corner.
Because the face must lie parallel to a coordinate plane, the corner points share a common
coordinate value. For example, if the rectangular face lies on the xy-plane, the corner points
share a common z-value.
The surface normal of this rectangular face depends on the order of the specification of the min
and max points, as described in the following table.

Plane to Which Rectangle is Order of Specification of Direction of the

Parallel (Coordinates of) the Corners Surface Normal

XY Min-corner, max-corner Positive Z-axis

YZ Min-corner, max-corner Positive X-axis

XZ Min-corner, max-corner Positive Y-axis

XY Max-corner, min-corner Negative Z-axis

YZ Max-corner, min-corner Negative X-axis

XZ Max-corner, min-corner Negative Y-axis

With conjunction of a 4×4 transformation matrix, an IFMERectangleFace can be used to

represent rectangular faces that are not parallel to the coordinate planes. This matrix can store
affine transformations.
Contains: None

Safe Software Inc. 17

FME Fundamentals FME Architecture

Contained by: IFMECompositeSurface, IFMEMultiSurface

IFMECompositeSurface
A composite surface is a collection of connected surfaces. The components can be simple
surfaces (faces, rectangular face, and triangular strip/fans), or other composite surfaces.
The topological requirement of a composite surface is that the collection must represent a
contiguous surface.
Contains: IFMESurface (0..n)
Contained by: IFMEBRepSolid, IFMECompositeSurface, IFMEMultiSurface

IFMEMultiSurface
A multi-surface is a collection of surfaces. These surfaces need not have any spatial or
topological relationship between each other.
Contains: IFMESurface (0..n)
Contained by: None

IFMESolids
IFMEBRepSolid
A solid is a solid volume in 3D space, defined by a collection of connected surfaces. The
exterior surface is represented by an IFMECompositeSurface, with the additional requirement
that this composite surface must be closed, in order to form a volume.
An IFMEBRepSolid can contain spatial voids. Each spatial void is represented by an
IFMECompositeSurface, representing an interior surface. This definition is analogous to the
inner boundaries that define donut holes.
In general, an IFMEBRepSolid must contain one exterior surface and zero or more interior
surfaces.
Contains: IFMECompositeSurface (0..n)
Contained by: IFMECompositeSolid, IFMEMultiSolid, IFMECSGSolid

IFMEExtrusion
An extrusion is a solid volume in 3D space, defined by a planar face (IFMEFace) and an
extrusion vector. This solid is defined by the prism generated by extruding the face in the
direction and magnitude described by the extrusion vector.
For example, a triangular face, extruded in the direction of the surface normal of that face,
yields an IFMEExtrusion that represents a triangular prism.
Contains: IFMEFace (1)
Contained by: IFMECompositeSolid, IFMEMultiSolid, IFMECSGSolid

18 Safe Software Inc.

FME Architecture FME Fundamentals

IFMEBox
A box is a rectangular prism in 3D space. An IFMEBox is defined by a minimum corner and a
maximum corner, but unlike IFMERectangularFace, these two coordinates must not share
identical x-, y-, or z-values. The two corner points unambiguously represent a unique
rectangular prism, in which all faces are parallel to the coordinate planes.
With conjunction of a 4×4 transformation matrix, an IFMEBox can be used to represent boxes
that are not parallel to the coordinate planes. This matrix can store affine transformations.
Contains: None
Contained by: IFMECompositeSolid, IFMEMultiSolid, IFMECSGSolid

IFMECSGSolid
A constructive solid geometry (CSG) solid is a solid volume in 3D space. These solids are
defined by the resultant volume constructed by two operand solids, and a Boolean operator.
The supported Boolean operators include union, intersection, and difference.
The following diagram shows a solid defined by the Boolean difference of a cube with a sphere.

Source: http://en.wikipedia.org/wiki/Constructive_solid_geometry

An IFMECSGSolid supports multiple operations, such that a solid can be constructed from a
tree of operators and operands. A example of such a tree is shown in the following diagram.

Safe Software Inc. 19

FME Fundamentals FME Architecture

difference
intersection
union

Source: http://en.wikipedia.org/wiki/Constructive_solid_geometry

Contains: IFMESimpleSurface (n), IFMECSGSolid (n)

Contained by: IFMECompositeSolid, IFMEMultiSolid, IFMECSGSolid

IFMECompositeSolid
A composite surface is a collection of connected solids. The components can be simple solids
(boxes, boundary-representation solids, and extrusion solids), constructive solid geometry
(CSG) solids, or other composite solids.
The topological requirement of a composite surface is that the collection must share faces, so
that the collection can represent a contiguous solid.
Contains: IFMESolid (0..n)
Contained by: IFMECompositeSolid, IFMEMultiSolid

IFMEMultiSolid
A multi-solid is a collection of solids. These solids need not have any spatial or topological
relationship between each other.
Contains: IFMESolid (0..n)
Contained by: None

20 Safe Software Inc.

FME Architecture FME Fundamentals

Vertex Normals
A vertex normal at a vertex of a polyhedron is the normalized average of the surface normals
of the faces that contain that vertex
fme_vertex_normal_x
fme_vertex_normal_y
fme_vertex_normal_z

Additional Reference:
• http://www.flipcode.com/archives/Vertex_Normals.shtml

Set on the (enhanced) geometry using named measures called fme_vertex_normal_[x|y|z]

• Domain: (0.0, 1.0)

Texture Coordinates
Texture coordinates define how an image (or portion of an image) gets mapped to a geometry.
A texture coordinate is associated with each vertex on the geometry, and it indicates what point
within the texture image should be mapped to that vertex.
fme_texture_coordinate_x
fme_texture_coordinate_y
fme_texture_coordinate_z

Additional Reference:
• http://www.gamedev.net/reference/articles/article947.asp
Set on the (enhanced) geometry using named measures called fme_texture_coordinate_[x|y|z]
• Domain: each coordinate within the texture image is between (0.0, 1.0), but coordinates
outside the texture can be specified so effectively the domain is all real numbers
• 0,0 is the lower left

Reader Modules
Reader modules are responsible for retrieving data from a data source. The data source may be
either a static file or another software system. For example, the Design File reader module
extracts features from Intergraph Design Files, while the Spatial Database Engine (SDE) reader
module connects to an SDE server to retrieve its features.
The Multi-Reader, described in the FME Readers and Writers manual, allows many reader
modules to be used in a single FME session thereby enabling data from several different data
stores to be processed.
The CAT, CSV, DBF, and ASCII reading modules can also be used to retrieve feature
attributes from sources external to the primary spatial data storage. For more information, see
the @Relate Function section in the FME Functions, Factories and Transformers manual.

Safe Software Inc. 21

FME Fundamentals FME Architecture

The parameters used to control each of these modules are discussed in the specific data format
sections in the FME Readers and Writers manual.

Functions
FME functions may be called at any time to set attribute values or change a feature’s geometry.
For example, the @Generalize function can be called on a feature to thin its coordinates, and
the @Log function may be called to output the entire feature to the translation session log file
for later inspection. The current library of predefined functions is described in the FME
Functions and Factories manual.

TIP: The FME Plug-in Builder enables users to write their own feature functions as well as
readers, writers, and factories.

The @Relate function is particularly interesting because it allows attribute data to be extracted
from or added to auxiliary attribute databases. The FME supports both file-based attribute
databases in the dBASE, comma-separated value (CSV), column-aligned text (CAT), and
ASCII formats, as well as live databases such as Oracle through an Open DataBase
Connectivity (ODBC) link.

Note Functions operate on only one feature at a time.

Feature Factory Pipeline

Just as real factories take in raw materials, process them, and turn out products, the FME
factory modules called feature factories accept “raw” features as input, perform processing on
them as a group, and output “processed” features. Feature factories are able to combine input
features together into one output feature or split them apart into numerous output features. For
example, the polygon formation feature factory combines line segments that have identical
attributes and forms them into closed polygons. In Workbench, FME factories and functions
are interpreted as Transformers.

Transformation Module
The transformation module is responsible for transforming features from a source format to a
destination format. The first step in the transformation process is the matching of a feature with
the transformation specification that specifies how the feature is to be transformed. Matching
is done based on feature type and attribute values. When a match is found, the feature is
transformed into its destination form by adding, dropping, and modifying its attributes. For
example, when translating features from an Intergraph Design File to ESRI’s SDE, linear
features from level 12 with color 8 and style 0 could be correlated to features on the SDE layer
containing roads, with the attribute NUMLANES set to 2 and the attribute PAVED set to false.

TIP: The Transformation Module may be bypassed in a mapping file. In such a case, all
transformation work is done in the factory pipeline. This often results in simpler mapping
files.

22 Safe Software Inc.

FME Architecture FME Fundamentals

Writer Modules
The writer modules are responsible for exporting features from FME to some destination that
may be either a static file or another software system. For example, the Design File writer
module exports features to Intergraph Design Files, while the SDE writer module connects to
an SDE server to export its features.

TIP: The CAT, CSV, DBF, ASCII, and Database writing modules can also be used to output
feature attributes to sources external to the primary spatial data storage. See the @Relate
function in the FME Functions, Factories, and Transformers manual.

The parameters used to control each of these modules are discussed in the specific data format
chapters in the FME Readers and Writers manual.
The schema of the output data can be defined on Writer Definition lines in the mapping file.

Mapping Files
An FME translation is controlled by a series of rules specifying the guidelines and
transformations of a data translation. The mapping file drives the operation of all FME modules
during a data translation.
The typical format of the FME mapping file:

Reader and Writer Configuration

Feature Factory Pipeline Configuration

Feature Factory 1

Feature Factory 2
•
•
•
Feature Factory n

Transformation Module Configuration

Feature Definition Statements

Feature Correlation Rules

Although the order of the major sections of a mapping file is not significant, typically the
configuration of readers and writers is placed at the top. Next, the factory definitions, if any,
are presented. Finally, the definitions of the features in the input and output systems are given
with the rules for transforming them from one system to the other.

Safe Software Inc. 23

FME Fundamentals FME Architecture

FME Workbench can be thought of as a graphical editor for mapping files, and almost
everything that can be done in a mapping file can also be done in FME Workbench. It is usually
quicker to create a mapping file by using FME Workbench rather than typing it manually.

Note FME Workbench cannot work with an existing mapping file: it only works with
workspaces which can be treated as mapping files, or exported as a mapping file for further
manual refinement.

Note that Workbench workspaces can be run directly by the FME translation processor, so
there is no need to export them as .fme files.

24 Safe Software Inc.

 3
FME Functions
Chapter 3

About FME Functions

Functions provide a flexible means of applying specific algorithmic operations to features as they
are being transformed, thereby supplementing the transformation capabilities of FME.

TIP: FME functions differ from feature factories in that FME functions work on exactly one
feature at a time, whereas feature factories may work on many features at once.

FME functions are named with an “at” sign (@) as their first character. Arguments to the functions
are enclosed in parentheses. The format of a function is as follows:
@FuncName([<parameter>[,<parameter>]])

There are two kinds of transformation functions. Attribute functions are used to compute the value
for an attribute, whereas feature functions operate on the complete feature. The following table
contrasts the two kinds of transformation functions.

TIP: Attribute functions may also be used to provide values to FME mapping file directives.
For details, see the Static Function Evaluation section.

In FME Workbench, functions are wrapped into transformers and presented to users in a graphical
form.

Safe Software Inc. 25

FME Fundamentals FME Functions

Transformation Function Types

Attribute Functions Feature Functions

Compute and return a value. Do not return a value.

Cannot directly modify features. Can modify both feature attributes and geome-
try.

Leave no side effects to the feature. Leave lasting side effects on the feature.

Do not affect the feature, the environ- Can modify feature attributes and geometry, and
ment or the external data stores. can read or write to external data stores.

Must be placed to the right of a feature at- Placed after all attribute name or value pairs on
tribute name on a transformation specifi- a transformation specification line.
cation line.

Function Inverses
In the past, the same mapping file was often used to translate in either direction between two
systems or formats. Therefore, each function implements its inverse operation if it makes sense
to do so. Functions that cannot be reversed implement a null operation as their inverse or
perform the same operation when run in reverse as in the forward direction.
Transformation functions on the destination line of a transformation specification are run in
the forward direction.
Transformation functions on the source line of a transformation specification are run in the
inverse direction.
FME Workbench-created mapping files cannot be run in the reverse direction, and in general
this functionality is not recommended.

Transfer
Variable

Source Transformation Destination

Feature Module Feature

Transformation Transformation
Function (Inverse) Function

Function Parameters
Five kinds of parameters may be passed to transformation functions.

26 Safe Software Inc.

FME Functions FME Fundamentals

Constants
Constants are passed to the function untouched. If a constant contains a space, the constant
must be enclosed in quotation marks. All parameters are considered to be constants unless they
are transfer variables, attribute values or function calls.
In this example, all parameters are constant so each time the function is invoked on a feature,
it will be passed the same parameters.
@Generalize(Deveau,20,4,100)

Transfer Variables
Transfer variables are used to carry values across from a source transformation specification
line to a destination transformation specification line. All transfer variables have a % as their
first character. When a transfer variable is encountered in a function parameter list, its value is
passed to the function. If the function is running in the inverse direction, it will set the first
transfer variable in its parameter list to the result of its computation. See Forward Function
Example and Inverse Function Example for further information.
FME Workbench-created mapping files do not use transfer variables and their usage is now
discouraged.

Attribute Values
There are times when the value of an existing attribute should be used as a function argument.
In such cases, the value-of operator (an ampersand [&]) is used to tell FME to substitute the
value of the attribute as the argument to the function. If the function is run in the inverse
direction and there are no transfer variables in its argument list, it will set the first attribute to
its result.
The example below counts all of the different values encountered for the numberOfLanes
attribute. The totals are logged in the log file. This can be used to produce a histogram of a
particular attribute’s range of values.
@Count(&numberOfLanes)

If the attribute value itself contains an ampersand (&), it is recursively substituted. If this is not
desired, then use the @Value function to retrieve the attribute value. For example, instead of
&attr

you should use

@Value(attr)

Attribute Functions
Any attribute function may be used as the value for a parameter and this nesting may be
arbitrarily deep. At run-time, FME invokes the deepest nested function, uses its result as the
argument for the next function, and so on. Only functions that will return a value should be
nested. All nested functions must be enclosed in quotation marks.

Safe Software Inc. 27

FME Fundamentals FME Functions

The example below produces a histogram of the feature types encountered:

@Count(“@FeatureType()”)

Composites
Function parameters may be composed of the previous four types by enclosing them in a single
set of quotation marks. All substitutions are made before the resulting string is passed to the
function.
The example below returns three times the current @Count value and can be used as a counter
that goes up by three each time:
@Evaluate(“@Count() * 3”)

In this example, the string contains a function call. Each time this @Log function is invoked, the
@Count() is replaced in the log message by the value it returns:

@Log(“Feature # @Count()”)

Function Configuration
Some sophisticated functions require configuration before they can be invoked. To
accommodate this, these functions accept configuration lines in the mapping file. Such
configuration lines always begin with the name of the function, without the @ sign. If a function
accepts configuration, its documentation states the format of the configuration lines.

User-Defined Functions
End users may define their own functions in a mapping file. These functions are written in Tool
Command Language (Tcl), and are invoked via the @Tcl2 function. As well, the FME
Developer Kit API provides a mechanism for developers to write plug-in functions in C++ or
Java. These functions are then dynamically loaded into the FME core at runtime.
See the FME Functions and Factories manual for a detailed reference of all currently available
FME functions, as well as a description of @Tcl2.

28 Safe Software Inc.

 4
FME Feature Factories
Chapter 4

About FME Feature Factories

Feature factories enable FME to perform operations on collections of features. Factories are the
second major feature processing facility available in FME and supplement the function facility
introduced in the previous chapter. There are several differences between FME functions and FME
factories:
• Feature factories have no inverse. To ensure that a single correlation table can be used in both
directions, feature factory definitions are associated with a <ReaderKeyword>. If the active
<ReaderKeyword> does not match, then the feature factory definition is not activated.
• All feature and attribute value functions on feature factory definition lines run in the forward
direction.
• Feature factories are able to operate on more than one feature at a time. In addition, they may
output more than one feature. Feature functions are only able to make changes to the single
feature they are operating on, although they may delete it.
• Factories allow FME to perform sophisticated processing tasks. Because factories may be
combined with feature and attribute value functions, and chained together into a factory
pipeline, problems which traditionally required custom software can be solved by a single FME
mapping file.

Safe Software Inc. 29

FME Fundamentals FME Feature Factories

Factory Architecture
All feature factories have the same architecture. They each define an input interface used to
control the features entering the factory, invoking feature and attribute functions on them as
they enter. The core of every factory is its feature processing unit, which operates on the
features that have entered the factory. The processing unit may merge features together, split
them apart, delete them, generate new features based on the input features, and/or alter their
geometry and attributes in order to accomplish its task. The output interface controls how
features leaving the factory appear to the rest of the system. It allows the feature type and
attribute values to be reset and further feature and attribute functions to be invoked on the
feature as it leaves the factory.

Input Output
Features Features

Input Feature Output

Interface Processing Unit Interface

Factory Activation Sequence

When FME is launched, it initializes all of the factories first. The factory activation sequence
occurs in several steps as the mapping file is scanned from top to bottom:
When a feature factory definition is encountered, the FME determines if it matches the current
<ReaderKeyword>.

If the feature factory definition matches the <ReaderKeyword>, the feature factory is activated.
Otherwise, the factory definition is ignored.
When defining mapping files it is important to remember that features flow from the first
factory down through to the last one. It is impossible for a feature to exit one factory and enter
a factory defined earlier in the mapping file.

30 Safe Software Inc.

FME Feature Factories FME Fundamentals

Factory Pipeline
Feature factories add a flexible processing model to the FME. The real power of feature
factories is realized when they are chained together to form a factory pipeline.
A factory pipeline is formed when a feature leaves one factory and is immediately sent by the
FME to another factory. This chaining of factories is referred to as factory pipelining. An FME
factory pipeline is a directed acyclic graph.

Feature Feature Feature

Factory Factory Factory

Factory Definitions
Feature factory definitions control all aspects of the feature factories. Each factory definition
has the following form:
FACTORY_DEF <ReaderKeyword> <factory type> \
[FACTORY_NAME <factory name>] \
[INPUT [<tag>] FEATURE_TYPE <feature type> \
<attribute name> <attribute value>]* \
[<feature function>]* \
]* \
[<factory specific directives>]* \
[GROUP_BY [<attribute name>]+]* \
[OUTPUT <tag> FEATURE_TYPE <feature type> \
[<attribute name> <attribute value>]* \
[<feature function>]* \
]*

FACTORY_DEF
The FACTORY_DEF clause is always the first clause of a factory specification. It consists of two
parameters: <ReaderKeyword> and <factory type>.

Parameter Content
<ReaderKeyword> The reader module with which this factory is associated.
The wildcard reader (*) can also be used in place of the
<Reader-Keyword> to cause the factory to always be acti-
vated.
<factory type> The name of the factory used by this factory definition.

Safe Software Inc. 31

FME Fundamentals FME Feature Factories

The example FACTORY_DEF clause below specifies that the ArcFactory is to be activated when
the <ReaderKeyword> is IGDS.
FACTORY_DEF IGDS ArcFactory...

FACTORY_NAME
This clause allows each factory in a mapping file to be given a unique identifier.
This identifier is prefixed to any messages the factory logs and is useful to distinguish between
separate instances of the same factory in a mapping file. The name can also be used as the target
for the BranchingFactory.
This clause of a factory definition:
FACTORY_NAME Joiner

causes all messages produced by the factory to be prefixed with “Joiner”.

INPUT
Factory INPUT clauses acts as a guard, allowing only features that satisfy one of the input
clauses to enter the factory. Features that do not satisfy any of a feature factory’s INPUT
clauses skip that factory and are routed to the next factory downstream in the factory pipeline.

TIP: If a factory has no INPUT clause, it accepts every feature. This is an

easy way to create a factory that processes every feature. Using the
@Count() function on the input line of the feature will count the features
input to the factory.

Parameter Content
<tag> The tag is used to categorize input features for the facto-
ry. Some factories, such as the ReferenceFactory, require
that features be divided into classifications as they are ac-
cepted by the factory. See the FME Functions, Factories
and Transformers manual for descriptions of the individual
factories and for the tags they support. Most factories do
not support tags in their INPUT clauses as there is no dis-
tinction between types of features which enter the factory.

<feature type> The feature type of input features that match the input
clause.

<attribute name> The attribute name being referenced in the input specifi-
cation.

<attribute value> If the attribute value is a constant, it is used for matching.

Once the feature has successfully been matched, any at-
tribute values that were attribute functions are evaluated.
The result is assigned to the attribute before the feature
gets passed into the feature processing unit.

32 Safe Software Inc.

FME Feature Factories FME Fundamentals

Parameter Content
<feature function> If the feature is successfully matched, any feature func-
tions specified are executed in the forward direction be-
fore the feature is passed into the factory.

The following example specifies that all features with a feature type of ForestCoverPolygon
will be accepted by the factory. In addition, the output of the Area() command is assigned to
the feature’s area1 attribute before the feature is passed into the feature factory.
INPUT FEATURE_TYPE ForestCoverPolygon area1 @Area()

Factory-Specific Directives
Many of the factories require specific directives. The form of these directives varies from
factory to factory and is described in the factory reference system for each one.
For example, the ArcFactory requires that a directive of either END_NODED or VERTEX_NODED be
specified, while the SamplingFactory requires a SAMPLE_RATE directive be specified.

GROUP_BY
This clause identifies how features passed into the factory are partitioned. The clause specifies
the attribute names used to partition the input feature set. One partition is created for each
unique combination of the values of the named attributes.
Each partition is processed independently from every other partition. Features output from such
a factory are supplied values for each <attribute name> specified in the GROUP_BY clause.

Parameter Content
<attribute name> The name of the attribute used to define the group of fea-
tures.

TIP: Clever use of the GROUP_BY clause often reduces the number of
feature factories that need to be specified. However, not every factory
supports a GROUP_BY clause.

Factory Example 1
The example below uses the GROUP_BY statement with the ArcFactory to apply its functionality
to independent groups of features. This is equivalent to having a separate ArcFactory
specification for every combination of the specified attributes. This results in all Road::TRIM
features having the same numberOfLanes and abutting one another to be connected together.
It will not connect Road::TRIM features that have a different number of lanes.
FACTORY_DEF SAIF ArcFactory \
INPUT FEATURE_TYPE Road::TRIM \
GROUP_BY numberOfLanes \
END_NODED \

Safe Software Inc. 33

FME Fundamentals FME Feature Factories

OUTPUT LINE FEATURE_TYPE JoinedRoad::TRIM

Note Note the use of the factory-specific directive END_NODED on the

ArcFactory definition.

If we assume that the numberOfLanes a feature can have is only 1, 2, or 3, then the above
statement is equivalent to the following three factory definitions. Notice the extra work
required when the GROUP_BY clause is not specified.
FACTORY_DEF SAIF ArcFactory \
INPUT FEATURE_TYPE Road::TRIM numberOfLanes 1 \
END_NODED \
OUTPUT LINE FEATURE_TYPE JoinedRoad::TRIM numberOfLanes 1

FACTORY_DEF SAIF ArcFactory \

INPUT FEATURE_TYPE Road::TRIM numberOfLanes 2 \
END_NODED \
OUTPUT LINE FEATURE_TYPE JoinedRoad::TRIM numberOfLanes 2

FACTORY_DEF SAIF ArcFactory \

INPUT FEATURE_TYPE Road::TRIM numberOfLanes 3 \
END_NODED \
OUTPUT LINE FEATURE_TYPE JoinedRoad::TRIM numberOfLanes 3

Factory Example 2
The following mapping file fragment describes a feature pipeline that combines a
PolygonFactory, a DonutFactory, and a PIPComponentsFactory.
FACTORY_DEF IGDS PolygonFactory \
FACTORY_NAME “Poly Number” \
INPUT FEATURE_TYPE 9 igds_type igds_line igds_color 56 \
igds_style 1 igds_class 2 \
INPUT FEATURE_TYPE 9 igds_type igds_line igds_color 61 \
igds_style 1 igds_class 0 \
OUTPUT LINE FEATURE_TYPE PolygonFactory_Line \
lineNum @Count(LineNum) \
OUTPUT POLYGON FEATURE_TYPE ForestCoverPolygon polyNum\
@Count(PolyNum)

FACTORY_DEF IGDS DonutFactory \

FACTORY_NAME “Donut Maker” \
INPUT FEATURE_TYPE ForestCoverPolygon area1 @Area() \
INPUT FEATURE_TYPE 10 igds_type igds_text_node \
igds_graphic_group0 @Count(Nodes) \
INPUT FEATURE_TYPE 10 igds_type igds_multi_text \
igds_graphic_group 0 @Count(Multis) \
OUTPUT POLYGON FEATURE_TYPE ForestCoverPolygon \
OUTPUT DONUT FEATURE_TYPE ForestCoverPolygonDonut area2 \
@Area() donutNum @Count(DonutNum) \
OUTPUT POINT FEATURE_TYPE ForestCoverPolygonPoint \
OUTPUT PIP FEATURE_TYPE ForestCoverPIP

FACTORY_DEF IGDS PIPComponentsFactory \

FACTORY_NAME “Point Splitter” \
INPUT FEATURE_TYPE ForestCoverPIP \
OUTPUT POINT FEATURE_TYPE tiedpnt \

34 Safe Software Inc.

FME Feature Factories FME Fundamentals

OUTPUT POLYGON FEATURE_TYPE tiedpoly

The first factory in the example is the PolygonFactory. This factory is activated when the
<Readerkeyword> is IGDS. The factory accepts features from level 9 of the Design file and
outputs two types of features: PolygonFactory_Line features and ForestCoverPolygon
features. The PolygonFactory_Line features leave the factory pipeline and are processed by the
remainder of the FME.

TIP: Notice the use of the @Count() function to count the number of
features that exit the factory. This is used to assign unique numbers to
each feature leaving the factories.

The next factory in the pipeline is the DonutFactory. This factory takes the polygons from the
first factory along with text nodes and multi-text elements from the Design file. The factory
performs the DonutFactory operation and outputs four different types of features from the
factory. One of these types of features – ForestCoverPIP – is sent on to the last factory. The
other features flow on to be processed by the remainder of the FME.

TIP: Features output from factories that are not desired by any
downstream factories get moved on to the transformation process.

The final factory in the pipeline is the PIPComponentsFactory. This factory takes
ForestCoverPIP features from the earlier factory and outputs two types of features: tiedpnt and
tiedpoly. These two types of features are then processed by the rest of the system.

Safe Software Inc. 35

FME Fundamentals FME Feature Factories

36 Safe Software Inc.

 5
Command-Line Interface
Chapter 5

While the 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)
on page 37

fme Generate ... Generating Mapping Files on page 39

fme GENTRANS Performing Generic Translations on page 40

fme LIST_TRANSFORMERS [VERBOSE] Listing Transformers on page 45

fme LIST_UNLICENSED_TRANSFORMERS

fme <mappingFile> Running Custom Mapping Files on page 45

fme PARAMETER_FILE Generating Mapping Files on page 39

fme PROTECT <sourceFile> <destFile> Reading Command-Line Parameters from a File

on page 47

fme <TclFile> ... Reading Command-Line Parameters from a File

on page 47

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, the 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, the FME supports a mode where it runs several times
in a single session without the resources required to restart.

Safe Software Inc. 37

FME Fundamentals Command-Line Interface

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 the 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 an error. 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

38 Safe Software Inc.

Command-Line Interface FME Fundamentals

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>]*

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 on page 45.
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.

Safe Software Inc. 39

FME Fundamentals Command-Line Interface

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

40 Safe Software Inc.

Command-Line Interface FME Fundamentals

<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/in-
dex.php#obj_documents.

<dest-directives> Any directives to pass to the FME writer. Note: See FME
Objects documentation www.safe.com/download/in-
dex.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 trans-
lation 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 cre-
ated.

[GUI] If specified, an FME dialog will pop up, allowing the source
and destination formats and data to be specified. The se-
lected 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 com-
mand-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. Fea-

tures read from the source will be processed using this
pipeline before being written to the destination.

Safe Software Inc. 41

FME Fundamentals Command-Line Interface

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.

42 Safe Software Inc.

Command-Line Interface FME Fundamentals

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.

Safe Software Inc. 43

FME Fundamentals Command-Line Interface

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_U
CS,no,_MERGE_SCHEMAS,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_G
ROUPS,no,Source_IGNORE_UCS,no\

44 Safe Software Inc.

Command-Line Interface FME Fundamentals

",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_design_P001.dwg\",META_MACROS,\
"Dest_ATTRKIND,external_attributes,Dest_REL,Release2000,Dest_TMPL,S:\key-
systems\drainage_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

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:

Safe Software Inc. 45

FME Fundamentals Command-Line Interface

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

46 Safe Software Inc.

Command-Line Interface FME Fundamentals

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>]*

Safe Software Inc. 47

FME Fundamentals Command-Line Interface

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.

Example:
FME_RecursiveGlob "c:/files/*.shp" "c:/morefiles/file.txt" returns "c:/
files/bob.shp" "c:/files/joe.shp" "c:/files/john.shp" "c:/morefiles/

48 Safe Software Inc.

Command-Line Interface FME Fundamentals

file.txt"

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"

FME User Interface Directives

FME can be used to create graphical user interfaces that greatly simplify the task of operational
data translation by allowing the user to control translation parameters at run-time. This section
describes the statements used to configure the FME user interface.
All FME user interface statements start with the GUI (Graphical User Interface) keyword. FME
uses all the GUI statements in a mapping file to create a single dialog box that is displayed to
the user. Translation begins once the user clicks OK from this dialog.
The syntax and usage of the remaining FME GUI statements are described later in this section:
• Coordinate System Name Parameters
• Directory Parameters
• Dividers
• File Name Parameters
• Floating Point Parameters
• Informational Messages
• Integer Parameters
• Multiple-Selection List Parameters
• Password Parameters
• Single-Selection List Parameters
• Text Parameters
Each GUI statement in the mapping file corresponds to one dialog element. The sequence in
which the GUI statements appear within the mapping file determines the sequence in which the
corresponding dialog elements are ordered on the translation dialog.

Safe Software Inc. 49

FME Fundamentals Command-Line Interface

Specialized text boxes are available for restricting input to numeric values and for hiding text
as it is entered. Specialized text boxes with browse buttons are available to assist users with
selection of files, directories, and coordinate systems.

Note GUI statements that appear in external files referenced using the INCLUDE
directive are not used by FME.

All GUI statements require the user to supply a value. If a parameter is truly optional, that is, a
blank value is acceptable, then the GUI statement can be flagged as such by placing the
keyword OPTIONAL as the second word on the line. For example:
GUI OPTIONAL FLOAT Tolerance Surface Tolerance (Optional):

The DEFAULT_MACRO directive can be used to supply default values to dialog elements. For
example, the following lines:
GUI TITLE Line Generalization Parameters
DEFAULT_MACRO SourceDir C:\Data
GUI DIRNAME SourceDir Source directory:

DEFAULT_MACRO InputFile line.dat

GUI FILENAME Input Line_Files(*.dat)|*.dat Input file:

DEFAULT_MACRO MinVertex 3
GUI INTEGER MinVertex Minimum number of vertices:

DEFAULT_MACRO MaxLengthThreshold 5.5

GUI FLOAT MaxLengthThreshold Maximum length threshold:

DEFAULT_MACRO Algorithm Douglas

GUI CHOICE Algorithm Douglas%Deveau Algorithm:

DEFAULT_MACRO CoordinateSystem LL
GUI COORDSYS CoordinateSystem Destination Coordinate System:

DEFAULT_MACRO Classes class 1 class 5

GUI LISTBOX Classes class1%class2%class3%class4%class5 Classes:

50 Safe Software Inc.

Command-Line Interface FME Fundamentals

cause FME to display this dialog:

The title of the dialog box typically describes the type of processing performed by the mapping
file and is specified using the following syntax:
GUI TITLE <dialogTitle>

The GUI TITLE statement differs from all the other GUI statements because its position in the
file relative to the other GUI statements has no relevance. In other words, dialogTitle will be
used as the title for the translation dialog whether the GUI TITLE statement appears as the first
line in the file, the last line in the file, or anywhere in-between.

TIP: When FME runs a mapping file that has been run before, in the same session or in
a previous session, the last values specified for the dialog elements take precedence over
those supplied in the mapping file using the DEFAULT_MACRO directive.

Coordinate System Name Parameters

A parameter whose value must be chosen from the list of allowed coordinate system names is
requested using the following syntax:
GUI COORDSYS <macroName> <label>

This causes the FME user interface to interact with the user to get a coordinate system name
and use it to define the macro macroName. For example,
DEFAULT_MACRO CoordinateSystem LL
GUI COORDSYS CoordinateSystem Destination Coordinate System:

requests a text box labelled Destination Coordinate System with a default value of LL. A
browse button is used to display the FME Coordinate System Gallery.
After the user dismisses the Coordinate System Gallery dialog, the macro CoordinateSystem is
set to their choice, which is constrained to the list of valid coordinate system names.

Safe Software Inc. 51

FME Fundamentals Command-Line Interface

Directory Parameters
Directory paths are requested using the following syntax:
GUI DIRNAME <macroName> <label>

This causes the FME user interface to interact with the user to get a directory path and use it to
define the macro named by macroName. For example:
DEFAULT_MACRO SourceDir C:\Data
GUI DIRNAME SourceDir Source directory:

requests a text box with a field labelled Source Directory, that has a value of C:\Data.
A browse button is used to display the directory browse window.
After the directory selection dialog is dismissed, the macro SourceDir is set to the directory
that was input.

TIP: Use Settings > Classic File Dialogs to choose the style of directory selection dialog
boxes you want to see. Choosing Classic File Dialogs (which is the default setting) can be
faster in some network environments.

Dividers
When a dialog has a large number of entries, it is useful to separate the parameters into groups.
A horizontal line will be placed in the dialog when a divider is requested:
GUI DIVIDER

File Name Parameters

File names are requested using the following syntax:
GUI FILENAME <macroName> <filter> <label>

This causes the FME user interface to interact with the user to get a file name and use it to
define the macro named by macroName.
The filter is a standard MS-Windows filter, which follows the syntax:
<description>|<filter>[|<description>|<filter>]*

For example:
DEFAULT_MACRO InputFile line.dat
GUI FILENAME InputFile Line_Files(*.dat)|*.dat Input file:

requests a dialog box with a field labelled Input File that has a default value of line.dat.
A browse button displays the file browse dialog.
After the file selection dialog is dismissed, the macro InputFile is set to the file name that was
input.

52 Safe Software Inc.

Command-Line Interface FME Fundamentals

Floating Point Parameters

Floating point numbers are requested using the following syntax:
GUI FLOAT <macroName> <label>

For example:
DEFAULT_MACRO MaxLengthThreshold 5.5
GUI FLOAT MaxLengthThreshold Maximum length threshold:

requests a text box labelled Maximum Length Threshold that accepts only floating point
values. After the user dismisses the dialog box, the macro MaxLengthThreshold is set to the
floating point value that was input.
There is no ability to restrict the range of the floating point number.

Informational Messages
Messages may be added to the dialog to provide additional information to the end user.
Messages are specified using the following syntax:
GUI MESSAGE <message text>

For example:
GUI MESSAGE Enter Information for the Second Autocad Input Dataset

Integer Parameters
Integers are requested using the following syntax:
GUI INTEGER <macroName> <label>

For example:
DEFAULT_MACRO MinVertex 3
GUI INTEGER MinVertex Minimum number of vertices:

requests a text box labelled Minimum number of vertices that accepts only integers.
After the user dismisses the dialog box, the macro MinVertex is set to the integer value that
was input.
There is no ability to restrict the range of the integer.

Multiple Selection List Parameters

Multiple text or numeric parameters whose values must be chosen from a list of values are
requested using either of the following syntaxes:
GUI LISTBOX <macroName> <listItem>[%<listItem>]* <label>
GUI CLASSICLISTBOX <macroName> <listItem>[%<listItem>]* <label>

For example:

Safe Software Inc. 53

FME Fundamentals Command-Line Interface

DEFAULT_MACRO Types type1 type5

GUI LISTBOX Types type1%type2%type3%type4%type5 Types:

requests a text box labelled Types with a default value of type1 type5. A browse button displays
the multiple-selection list box dialog.
After you dismiss the multiple-selection list box dialog, the macro Types is set to the selected
items, separated by spaces.
In older FME versions, multiple-selection list boxes were displayed on the main dialog. This
effect can still be achieved by using CLASSICLISTBOX instead of LISTBOX.
For example:
DEFAULT_MACRO Classes class2 class3
GUI CLASSICLISTBOX Classes class1%class2%class3%class4%class5 Classes:

requests a list box that displays a list of selectable items.

After a user dismisses the dialog box, the macro Classes is set to the selected items, separated
by spaces.

TIP: If you choose not to select anything from a multiple-selection list box, it will result
in an empty parameter.

Password Parameters
Secure text parameters, such as passwords that must be obfuscated as they are typed, are
requested using the following syntax:
GUI PASSWORD <macroName> <label>

For example:
GUI PASSWORD passw Password:

requests a text box labelled Password that accepts text characters. As each character is entered,
the PASSWORD field displays an asterisk (*) to keep the contents of the field from displaying.
After the user dismisses the dialog box, the macro passw is set to their input.

Single-Selection List Parameters

Text or numeric parameters whose value must be chosen from a list of values are requested
using the following syntax:
GUI CHOICE <macroName> <value>[%<value>]* <label>
GUI INT_OR_CHOICE <macroName> <value>[%<value>]* <label>
GUI FLOAT_OR_CHOICE <macroName> <value>[%<value>]* <label>
GUI STRING_OR_CHOICE <macroName> <value>[%<value>]* <label>

For example:
DEFAULT_MACRO Algorithm Douglas
GUI CHOICE Algorithm Douglas%Deveau Algorithm:

54 Safe Software Inc.

Command-Line Interface FME Fundamentals

requests a text box labelled Algorithm with a pulldown list box and the entries Douglas and
Deveau. After the user dismisses the dialog, the macro Algorithm is set to the value of their
choice, which is constrained to a set of allowed values. Note that if an OPTIONAL CHOICE
is requested, then the pulldown list will automatically have a blank entry added to it.
<TYPE>_OR_CHOICE

allows a value of <TYPE> to be entered from the keyboard.

Text Parameters
Text parameters are requested using the following syntax:
GUI TEXT <macroName> <label>

For example:
GUI TEXT mapid Mapsheet Identifier

requests a text box labelled Mapsheet Identifier that accepts only text parameters.
After the user dismisses the dialog box, the macro mapid is set to the text that was input.

Safe Software Inc. 55

FME Fundamentals Command-Line Interface

56 Safe Software Inc.

 6
FME Transformation Process
Chapter 6

Note The functionality described in this section is not used in mapping files generated by FME
Workbench, and usage of this functionality is discouraged. This section is useful only to users who
may be maintaining older mapping files.

As features flow through FME, they are transformed from their original state to a destination state
according to the rules read from the mapping file. These rules are called transformation
specifications and are used to:
• identify a feature for transformation
• change the feature’s attribute names, values, and feature type

Source Transformation Destination

Feature Module Feature

Transformation Specification
The transformation specification determines the mapping between source features and destination
features. Each transformation specification consists of a pair of lines: one line associated with the
source format and one line associated with the destination format. The source line is used as a filter
to determine which source features match the transformation specification. If a feature matches a
source specification line, then the destination line instructs the FME how the feature is to be written
to the destination format. Each feature is matched to a single specification line. If a feature could
potentially match several different transformation specifications, then the first one defined in a
mapping file is used.
The mapping file fragment below is used to direct translations between IGDS Design File and
ESRI’s SDE. It illustrates the use of the mapping file in directing the transformation between
formats.
# -------------------------------------------------
# Handle Roads
IGDS 12 igds_type igds_line igds_
10 igds_style 3
SDE ROAD NUMLANES 2 PAVED false

Note These two lines control transformation in both directions – from IGDS to the
SDE, as well as from the SDE to IGDS.

Safe Software Inc. 57

FME Fundamentals FME Transformation Process

This pair of lines in the preceding example instructs FME to convert a linear IGDS source
feature with a color value of 10 and a style of 3 residing on level 12 of the Design file into an
SDE feature on the ROAD layer, with the number of lanes set to 2 and the paved flag set to false.
If the specifications were to change whereby all two-lane, unpaved roads were found to reside
on level 13 of the Design File, the operator need only alter this portion of the mapping file to
handle the schema change:
# -------------------------------------------------
# Handle Roads
IGDS 13 igds_type igds_line igds_color 10 igds_style 3
SDE ROAD NUMLANES 2 PAVED false

The portion of a mapping file that specifies how features are transformed consists of a series of
transformation specifications. These lines specify how features are transformed from some
source to some destination. Each transformation specification consists of a pair of two lines: a
source line and a destination line.

Note Transformation specifications are bidirectional. The same transformation specification

is used to control transformation from format A to format B, as well as back to format A from
format B.

In general, transformation specifications follow this pattern:

<ReaderKeyword> <Source Feature Type> \
[<attribute name> <attribute value>]* \
[<feature function>]*

<WriterKeyword> <Destination Feature Type> \

[<attribute name> <attribute value>]* \
[<feature function>]*

The feature type is the type of feature to match if on the source line or the new feature type if
on the destination line. The wildcard feature type, the asterisk (*) character, matches any
feature type when found on a source line. On a destination line, it does not alter the existing
feature type of the feature. In addition, when the wildcard feature type is used on a destination
line, it also carries across all attributes of the source feature. This is useful when the FME is
used to translate from one format back to itself.
The attribute value may be one of the following:
Constant: An explicit value assigned to the associated attribute name. When on the source line,
constant values are the only attribute values used to match features. On the destination line, the
constant values are used to set feature attribute values.
Transfer Variable: A variable used to transfer an attribute value from the source line to the
destination line. All transfer variables start with a percent (%) character.
Attribute Function: A function whose return value is used to set attribute values.
The portion of a mapping file that specifies how features are transformed consists of a series of
transformation specifications. These lines specify how features are transformed from some
source to some destination. Each transformation specification consists of a pair of two lines: a
destination line and a source line.

58 Safe Software Inc.

FME Transformation Process FME Fundamentals

Destination Line

The destination line portion of a transformation specification is the pattern used to create an
output feature once a match has been made. It is applied when a feature matches a source line
and all transformation variables have been loaded. The feature type of the output feature is set
to the feature type listed on the destination line, and any constant attribute values are set.
Attribute values may also be set to the value of transfer variables loaded on the source line.
Finally, all feature or attribute functions are executed in the forward direction, proceeding from
left to right across the line.

Source Line

The source line of a transformation specification is used as a pattern to be matched against

features. Source lines begin with the current <ReaderKeyword>, which by default is the same
as the name of the reader module being used. For a feature to match the source line, it must
have the same feature type as the source line. In addition, the feature’s attribute values must
have the same values as any attribute constants listed on the source line. Source lines also
identify attribute values to be transferred across to the destination line. Finally, the inverse
operation of all feature functions and attribute functions on the source line are executed from
right to left.

TIP: Use the @SupplyAttributes function to supply constant values to attributes when you
do not want the attribute values to be used for specification matching. See the FME
Functions and Factories manual for details.

Feature functions are functions that perform operations on a feature as a whole. They may be
used to change a feature’s geometry or operate on groups of attributes at a single time. See the
Functions and Factories manual for a full description of FME feature and attribute functions.

Transformation Specification Example

The following transformation specification translates road features between IGDS and SAIF:
# -------------------------------------------------
# Handle Roads
IGDS 12 igds_type igds_line igds_color 10 igds_style 3
SAIF Road::TRIM position.geometry.Class arc \
numberOfLanes 2 paved false

The first word of each line specifies the source or destination system involved in the
transformation. The same pair of lines is used to go in either direction between systems. In this
example, the two lines are used to translate from IGDS to the SAIF or from the SAIF to IGDS.
The direction of the transformation determines which keyword is used to identify candidate
source features and which keyword is used to identify destination features.

Matching Process
For each feature read from the source system, the FME logically scans the mapping file from
top to bottom looking for the first matching source specification. Then it transforms the feature
according to the corresponding destination specification. Expanding on the above example,
consider a mapping file containing these lines:

Safe Software Inc. 59

FME Fundamentals FME Transformation Process

# -------------------------------------------------
# Handle Two Lane Roads
IGDS 12 igds_type igds_line igds_color 10 igds_style 3
SAIF Road::TRIM position.geometry.Class arc \
numberOfLanes 2 paved false
# -------------------------------------------------
# Handle Four Lane Roads
IGDS 12 igds_type igds_line igds_color 4 igds_style 3
SAIF Road::TRIM position.geometry.Class arc \
numberOfLanes 4 paved false
# -------------------------------------------------
# Handle Single Lane Roads
IGDS 12 igds_type igds_line igds_color 4
SAIF Road::TRIM position.geometry.Class arc \
numberOfLanes 1 paved false

Note Recall that the second word on a transformation specification line is the
feature type, which for IGDS is the feature’s level and for SAIF is the feature’s
class.

Suppose a transformation from IGDS to SAIF is being performed, and a linear feature from
IGDS level 12 with color 10 and style 3 has been read. The FME scans down the mapping file,
examines all IGDS specifications, and looks for a match. Since the second specification
matches, the feature is transformed into a SAIF Road::TRIM, with the numberOfLanes and
paved attributes to 4 and false respectively. Then the feature is sent to the SAIF writer.

Note The order of the transformation specifications is very important.

Specifications should be listed from the most specific to the most general.

Suppose the next IGDS feature read is a linear feature from IGDS level 12 with color 10 and
style 2. The first two IGDS specifications are tested and found not to match. However, the third
IGDS specification does not refer to the style attribute so it is matched. The feature is
transformed into a single lane SAIF Road::TRIM. Note that if the third IGDS specification were
moved to the top of the file, it would match any linear IGDS feature from level 12 with color
4. The result would be that no two or four lane roads would be output. Instead, all roads
encountered would be output as single lane. For this reason, feature specifications should be
listed from the most specific to the most general.
If a feature does not match any source specification, it will not be translated. Statistics on the
number and types of features dropped, as well as those transformed, are gathered by the FME
and output to the FME log file.

Transfer Variables
In the previous examples, no attribute values were transferred between the source feature and
the destination feature. The attribute values of the destination feature were based entirely on
the matching source feature. This situation occurs often when one of the two systems involved
in the transformation is based on feature codes. For example, certain combinations of level, line
style, and color may be used to represent certain types of features in an IGDS file.

60 Safe Software Inc.

FME Transformation Process FME Fundamentals

Translation Process Including Transfer Variable

Transfer
Variable

Source Transformation Destination

Feature Module Feature

More commonly, however, attribute values must be transferred from an attribute of the source
feature to an attribute of the destination feature.
To accomplish this, a transfer variable is created to move the value from one system to another.
Transfer variables are identified with a first character of % and have the following syntax:
%<variable name>[:<default value>]

TIP: FME ensures that any transfer variables defined on a source line are
referenced on a destination line and, conversely, that any transfer variables
referenced on a destination line are defined on a source line.

When a transfer variable is encountered on a source line, it is assigned the value of the feature’s
attribute it is paired with. If the feature had no value for the attribute, then the transfer variable
is set to its default value if one was specified.
When a transfer variable is encountered on a destination line, the attribute to which it is
associated is assigned the variable’s value. If the variable’s value was the same as the default
value providing one was specified, then the attribute is not set.
Transfer variables may also be used as arguments to feature or attribute value functions.
The net effect of the transfer variable is to move an attribute value from the source feature to
the destination feature. For example:
# -------------------------------------------------
# Handle Bridges
IGDS 14 igds_type igds_line igds_graphic_group %var1
SDE BRIDGE width %var1

TIP: Using descriptive transfer variable names eases maintaining and

understanding the mapping file.

In this example, all linear features on level 14 represent bridges and the width of the bridges is
encoded in the IGDS graphic group field. The transfer variable var1 is used to transfer this
width value between the IGDS encoding and the SDE width attribute. Note that transfer

Safe Software Inc. 61

FME Fundamentals FME Transformation Process

variables may have any name as long as they are unique within a single transformation
specification and start with a percent character (%).

Default Attribute Values

In some formats, the absence of a value implies a predefined value. In other words, there is a
default value for an attribute which will not be explicitly stored in the format. To accommodate
transformations supporting such formats, the transfer variable syntax provides a means of
specifying a default value. The default value is listed immediately after the transfer variable
name and is separated from the variable name by a colon (:).
For example:
# -------------------------------------------------
# Handle Bridges
SAIF Bridge::TRIM bridgeType %bt:footBridge
SDE BRIDGE bridgeType %bt

In this example, bridge features stored in the SAIF format will not have a bridgeType attribute
when the value of the bridgeType is footBridge. The absence of the attribute implies this
value. When a transformation from SAIF to the SDE is performed, the %bt transfer variable is
assigned the value of footBridge if no bridgeType attribute was present in the feature. If a
bridgeType attribute were present, then its value would be used. In either case, the SDE
bridgeType attribute would have its value set.

If a translation from the SDE into SAIF is performed using the same transformation
specification, the value stored in the SDE bridgeType attribute would initially be assigned to
the %bt variable to be transferred to SAIF. However, when the feature was transformed into a
SAIF feature, a test would be done to ensure that the %bt variable was not equal to the default
value of footBridge before it was transferred. If it was equal to footBridge, it would not be
transferred.

Note If there are no transfer variables, there will be no attributes on the output
side.

In another example (using any format):

IN_FORMAT Bridge type %t:foot
OUT_FORMAT br outType %t

There are two possible scenarios:

If the original Bridge feature had a type attribute, its value is carried over to the outType
attribute.
If it did NOT have a type attribute, OR the attribute was blank (0 length string), then the
outType attribute will be set to foot. So, if the Bridge in IN_FORMAT has NO type attribute,
assume it really has a type attribute whose value was foot.
In another case, the opposite applies:
IN_FORMAT br outType %t
OUT_FORMAT Bridge type %t:foot

62 Safe Software Inc.

FME Transformation Process FME Fundamentals

However, if the outType attribute in the input format has a value of foot, DO NOT create a
type attribute in the OUT_FORMAT.This is because the default value for type is foot anyway,
so not creating an explicit attribute will have the same effect as if you created one. The outType
value is transferred to the type attribute, but then if the value is the same as the default (in this
case, foot), the type attribute is removed.

Safe Software Inc. 63

FME Fundamentals FME Transformation Process

64 Safe Software Inc.

 7
Mapping File Syntax
Chapter 7

Working with Mapping Files

The translation of features from a source system to a destination system is completely controlled
by rules specified in the mapping file. This ASCII text file consists of a series of translation
specifications.
FME Workbench workspaces are mapping files with special comments in them that Workbench
uses to recreate as a graphical representation.
The mapping file consists of free-form ASCII text organized into a series of lines. To expedite
maintenance, a mapping file may contain both line and block comments which can be nested, may
contain text expansion macros, and may include other text files. Each non-comment line in the
correlation file starts with a keyword recognized by some component of the translation engine.
A syntax highlighting editor such as UltraEdit, Textpad, or VIM can greatly improve productivity
when working with mapping files. FME ships with syntax files for these editors, as well as
templates for the FME functions and factories that greatly speed their entry.

Writer Definitions
Most writers in the FME require the schema for the output data to be defined before translation
begins. This is done through DEF lines, which take this syntax:
<WriterKeyword>_DEF <FeatureType>
<AttributeName> <AttributeType>
<AttributeName> <AttributeType>
.
.
.

For example, for the ESRI Shape format, the feature type defines the file name for the output
Shapefile. An ESRI Shapefile named ROADS.shp with attributes LENGTH and NUMLANES can be
defined like this:
SHAPE_DEF ROADS \
LENGTH char(30) \
NUMLANES char(30)

The details of what feature type names, attribute names, and types are allowed depends on the
individual format. Consult each format's writer documentation for more details.

Dynamic Feature Type Definitions (Advanced FME)

When writing out a large number of feature types, it can be tedious to create definitions for every
single feature type you may want to write out. In addition, the output feature types may depend on
the input data, and may not be known before translation begins. In this situation, FME can create

Safe Software Inc. 65

FME Fundamentals Mapping File Syntax

feature types dynamically, so that DEF lines don't need to be written in a mapping file. Many,
but not all, FME writers support dynamic feature type creation.
In order to use this feature, a single DEF line must be given in order to provide a template for
the dynamic feature types. Each feature type that is dynamically created will be a copy of the
template feature type. The fme_template_feature_type attribute is used to define these
dynamic feature types. When a feature is written with a feature type not defined on any DEF
line, the writer checks if the fme_template_feature_type attribute is defined on that feature.
If it is, the value of that attribute is used as the feature type name for the template that this
feature should use.
In the example shown below, we are writing to the GML2 writer, and use the
CreationFactory to simulate reading a large number of feature types. Normally we would
have to have a GML2_DEF section for every feature type from 1 to 100, but in this case we have
only a single definition (Template), which is used as a template for every dynamic feature type
that will be created. Every one of the 100 layers that will be created in the GML2 file will have
a schema identical to that of the Template definition, with a different feature type.
READER_TYPE NULL
NULL_DATASET null
WRITER_TYPE GML2
GML2_DATASET "c:/out.gml"
GML2_SCHEMA_MODE CREATE
# ---------------------------------------------------------------------
# Create 100 features, with the count attribute increasing for each one.
FACTORY_DEF * CreationFactory \
2D_GEOMETRY 0 0 \
CREATE_AT_END no \
NUMBER_TO_CREATE 100 \
OUTPUT FEATURE_TYPE 2DCREATOR_CREATED \
count @Count(counter,0)
# ---------------------------------------------------------------------
# Set each feature's feature type to the count attribute, and set
# the fme_template_feature_type.
FACTORY_DEF * TeeFactory \
FACTORY_NAME "2DCREATOR_CREATED -> Template Correlator" \
INPUT FEATURE_TYPE * \
OUTPUT FEATURE_TYPE * \
@Transform(FME_GENERIC,GML2) \
@FeatureType(&count) \
@SupplyAttributes(fme_template_feature_type,Template)
# ---------------------------------------------------------------------
NULL *
GML2 *
# ---------------------------------------------------------------------

GML2_DEF Template \
gml2_type gml2_point \
attr1 gml2_char(10) \
attr2 gml2_char(10)

Line Continuation
Long mapping file lines may logically continue to the next line by using a backslash (\) as the
last character. For example, the following two lines:
IGDS 45 igds_color 8 \
igds_style 3

66 Safe Software Inc.

Mapping File Syntax FME Fundamentals

are equivalent to this line:

IGDS 45 igds_color 8 igds_style 3

There is no limit to the number of consecutive lines that may be joined together using
continuation characters.

TIP: Breaking long lines into several smaller parts makes your mapping files
easier to read and maintain. The continued parts of lines are usually indented to
aid readability.

Quoted Text
Parameters or string literals containing spaces or tabs must be enclosed in quotation marks. The
quotation marks are stripped off by the FME when the mapping file is processed and the string
they contain is treated as a single token.
The example below assigns the text Hello There to the text.textString attribute of a SAIF
object.
SAIF Text::TRIM text.textString "Hello there"

If a parameter or string literal contains a quotation mark, the quotation mark is preceded by a
backslash, as shown in the example below:
SAIF Text::TRIM text.textString "Some \" label"

Escaping Commas
Function parameters that contain commas must have the commas escaped; otherwise, they will
be considered parameter separators. This is done by placing a backslash before the comma. The
example below passes the string “Hi, There” to @Log as the message it should output.
@Log("Hi\, there")

Single-Line Comments
Mapping files are mini-programs interpreted by the FME. In keeping with good programming
practice, the mapping file should be documented. The FME ignores any line that starts with a
hash (#) character. Blank lines are also ignored. For example, the line below would be ignored
during processing:
# This line is a comment

Note that the hash character must be the first character in the line to be considered a comment,
so it is not possible to place a comment on the same line as a control line. For example, the line
below would not be recognized as one containing a comment:
IGDS 45 igds_color 8 # This is a road

Safe Software Inc. 67

FME Fundamentals Mapping File Syntax

and would be reported by the IGDS module as invalid.

TIP: A mapping file is easier to read if groups of logically related lines are
separated by white space and a solid comment line.

Block Comments
Sometimes a larger discussion of the mapping file contents is desired. To accomplish this
without the inconvenience of starting each line of the comment with a special character, a block
comment may be used. Block comments start with slash-asterisk (/*) at the beginning of the
line, and end with an asterisk-slash (*/) at the end of the line.
The following examples illustrate the use of block comments in a mapping file:
/* This is a one-line block comment */
/*
This is a multi-line comment.
Any text in here will be ignored
/* This is a nested comment */
*/

TIP: Because block comments may be nested, they are often useful for disabling
large sections of a mapping file during testing.

MACRO Directives
To avoid duplicating portions of correlation lines repeatedly throughout a mapping file and to
allow creating symbolic constants to avoid hardcoding numbers, the mapping file provides a
simple textual substitution mechanism. Macros are defined by lines starting with the keyword
MACRO which must be in uppercase letters. The word following the MACRO keyword is the name
of the macro, which will be replaced by the contents of the rest of the line when it is expanded
on other lines. A macro expansion is requested by enclosing the macro name with $( and ). The
lines below:
MACRO blue 8
IGDS 32 igds_color $(blue) igds_style 3

will be expanded to:

IGDS 32 igds_color 8 igds_style 3

TIP: Using macros as symbolic constants for color numbers and line styles eases
the maintenance of mapping files.

Macro definitions may themselves refer to other macros which will be expanded recursively at
the time the outermost macro is expanded. Macros may be redefined at any time in the file. A
macro definition remains in effect from the point of definition until the end of the file, or until
it is redefined. Macro definitions may, of course, be spread over several lines using the
continuation character (\) to join consecutive physical lines. A macro may not, directly or
indirectly, refer to itself.
FME flags any reference to an undefined macro and stops the translation if one is encountered.

68 Safe Software Inc.

Mapping File Syntax FME Fundamentals

The next example illustrates a more complex use of macros to define a large, commonly used
correlation block. Note that the first macro itself references another macro to set the color of
the text. Once the two macros are defined, they are then used in the specification of the
translation from IGDS to SAIF.
MACRO IGDSTextSpec \
igds_color $(blue) \
igds_type igds_text \
igds_style 0 igds_class 0 igds_weight 1 \
igds_text_size %size \
igds_text %string \
igds_font %font \
igds_rotation %orientation
MACRO SAIFTextSpec \
textOrSymbol.characterHeight %size \
textOrSymbol.text %string \
textOrSymbol.fontName %font \
textOrSymbol.orientation @SAIFAngle(%orientation)
#-----------------------------------------------------
# Feature KB14250000 -- Text (Hydrographic)
IGDS 44 igds_color 2 $(IGDSTextSpec)
SAIF OtherText::TRIM \
textType hydrographic $(SAIFTextSpec)

Substituting Strings in Mapping Files

Occasionally, a character can cause a conflict in the mapping file parser. If this occurs, you can
substitute safe character strings in many formats, functions and factories, including:
• Geodatabase writer (Attribute Definitions > subtypes, Attribute Definitions > domains)
• @Lookup
• PythonFactory
• @SearchList
• @SupplyAttributes
• @Tcl2

Character Subsitutions
The encoding method is inspired by XML character entities.

Note Substitutions are made only in attribute type definitions.

Symbol Replaced with

< <lt>

> <gt>

" <quote>

& <amp>

\ <backslash>

Safe Software Inc. 69

FME Fundamentals Mapping File Syntax

Symbol Replaced with

/ <solidus>

' <apos>

$ <dollar>

@ <at>

<space>

, <comma>

( <openparen>

) <closeparen>

[ <openbracket>

] <closebracket>

{ <opencurly>

} <closecurly>

; <semicolon>

\r <cr>

\n <lf>

\t <tab>

\a <bell>

\b <backspace>

\v <verttab>

\f <formfeed>

International Characters

International Character Support Replaced with

<specialCharacter> <uABCD>
(where ABCD is the 4-digit hex value
for the equivalent UTF-16 character)

Example
According to the encoding method, the attribute type
coded_domain(TextDom:char(50):a:"the letter a":b:"the
letter b")

would be represented as
coded_domain(TextDom:char<openparen>50<closeparen>:a:
<quote>the<space>letter<space>a<quote>:b:<quote>the<space>
letter<space>b<quote>)

70 Safe Software Inc.

Mapping File Syntax FME Fundamentals

within a mapping file. Notice that the encoding is only applied to the body of the coded_domain
type, i.e. coded_domain(<body>). Similarly, it would only be applied to the body of
range_domain(<body>), subtype(<body>), and subtype_codes(<body>) which are
Geodatabase attribute types and to enum(<body>) and set(<body>) which are both MySQL
attribute types.

Predefined Macros
Most mapping files contain external references to the source and destination datasets for the
translation. Some mapping files include external references to other mapping files, for
example, mapinfoMacros.fmi. Advanced mapping files may reference external Tcl scripts
used to perform sophisticated operations. In all of these cases, you can simplify the portability
of the mapping file by using one of the macros automatically defined by FME.

FME_ASC_xxx
This set of macros each expands to the corresponding ASCII character. The xxx in
FME_ASC_xxx is a character set index number, and the macro value is the character at that index
in the ASCII character set.
For example, FME_ASC_2 expands to the ASCII character whose index value is 2.

FME_BASE
This macro expands to yes if the FME that is running is licensed only for FME Base Edition
capabilities. If the FME is licensed at the Professional level or greater, then this macro has the
value no.
This macro could be used to selectively include factories by using (as a single, continuous line):
INCLUDE base_factories_$(FME_BASE).fmi

in a mapping file, and then having base_factories_yes.fmi and base_factories_no.fmi in the

mapping file directory.

Note The deprecated FME_DESKTOP macro has the same value. The
FME_DESKTOP macro will still function in older mapping files.

FME_BUILD_DATE
This macro expands to the date that the FME executable processing the mapping file was built,
in YYYYMMDD format.

FME_BUILD_NUM
This macro expands to the build number of the FME executable processing the mapping file.

Safe Software Inc. 71

FME Fundamentals Mapping File Syntax

FME_HOME
This macro expands to the directory where the FME executable resides. On UNIX it uses the
slash (/) character as directory separator, and on Windows it uses the backslash (\). It includes
a trailing slash, independent of the platform.

FME_HOME_UNIX
This macro expands to the directory where the FME executable resides. It always uses the slash
directory separator, independent of the platform, and does not have a trailing separator (either
slash or backslash).

FME_HOME_DOS
This macro expands to the directory where the FME executable resides. It always uses the
backslash directory separator, independent of the platform, and does not have a trailing
separator (either slash or backslash).

FME_MF_DIR
This macro expands to the directory where the mapping file resides. On UNIX it uses the slash
(/) character as directory separator, and on Windows it uses the backslash (\) character. It
includes a trailing slash, independent of the platform.

Note In older versions of FME, FME_MF_DIR was called FME_CF_DIR. Although FME still
accepts FME_CF_DIR in place of FME_MF_DIR to accommodate backwards compatibility, its
use is not recommended.

FME_MF_DIR_UNIX
This macro expands to the directory where the mapping file resides. It always uses the slash
separator, independent of the platform, and does not have a trailing separator (either slash or
backslash).

FME_MF_DIR_DOS
This macro expands to the directory where the mapping file resides. It always uses the
backslash separator, independent of the platform, and does not have a trailing separator (either
slash or backslash).

FME_MF_NAME
This macro expands to the name of the mapping file including the extension, but not including
the directory specification.

FME_MF_NAME_MASTER
Similar to FME_MF_NAME, this macro expands to the name of the outermost original mapping
file except if the mapping file names ends with .tmp. Unlike FME_MF_DIR, it does not change
value within any INCLUDEd mapping file fragments.

72 Safe Software Inc.

Mapping File Syntax FME Fundamentals

FME_MF_DIR_MASTER
Similar to FME_MF_DIR, this macro expands to the directory of the outermost original mapping
file except if the mapping file names ends with .tmp.. Unlike FME_MF_DIR, it does not change
value within any INCLUDEd mapping file fragments.

FME_MF_DIR_DOS_MASTER
This macro is like FME_MF_DIR_MASTER, but all directory separators are the backslash, and it
does not include a trailing separator.

FME_MF_DIR_UNIX_MASTER
This macro is like FME_MF_DIR_MASTER, but all directory separators are the forward slash, and
it does not include a trailing separator.

FME_PRODUCT_NAME
This macro expands to the version name of the FME product that is processing the mapping
file.
For example: FME 2007

File Locations
It is recommended that any files referenced by your mapping file be located in the same
directory as mapping file or in a directory that can be expressed relative to the mapping file
directory. This allows you to identify the location of these files using the FME_MF_DIR macro
(or one of its variants) in the place of using hard coded directory specifications. By avoiding
hard coded directories, you can make your mapping files inherently portable across
installations. For example:
DEFAULT_MACRO SourceDataset "$(FME_MF_DIR)/../maps/082e.dgn"

Include files provided as part of the FME can be referenced using the FME_HOME macro as
follows:
INCLUDE "$(FME_HOME)/metafile/mapinfoMacros.fmi"

Note Although FME treats both slash and backslash as a legal directory
separators, independent of the platform, slash is the preferred separator because
it avoids ambiguity with the escape character.

Where Tcl is involved, all paths should be enclosed by braces. For example:
INCLUDE [source {$(FME_MF_DIR)/gen.tcl}; \
genLines {$(FME_MF_DIR)} ]

In most situations, the FME_MF_DIR and FME_HOME macros will suffice. However, if you
encounter a platform-specific issues where the standard macros do not give the desired result,

Safe Software Inc. 73

FME Fundamentals Mapping File Syntax

the _UNIX and _DOS variants can be used in their place. As an example, consider the
following line that duplicates a file using the DOS copy command:
@System("copy \"$(FME_MF_DIR_DOS)\MSFORMS.DBF\" \
"$(DestDirectory)\"")

For this command to be interpreted correctly, it is necessary to use the backslash separator.
The following simple mapping file example can be used to troubleshoot the use of these macros
on any platform:
#----------------------------------------------------------
# Specify a Null Reader and Writer
READER_TYPE NULL
WRITER_TYPE NULL
NULL_DATASET NULL
#----------------------------------------------------------
# Print the values of all predefined macros
TCL puts {FME_MF_DIR= $(FME_MF_DIR)}
TCL puts {FME_MF_DIR_UNIX= $(FME_MF_DIR_UNIX)}
TCL puts {FME_MF_DIR_DOS= $(FME_MF_DIR_DOS)}
TCL puts {FME_HOME= $(FME_HOME)}
TCL puts {FME_HOME_UNIX= $(FME_HOME_UNIX)}
TCL puts {FME_HOME_DOS= $(FME_HOME_DOS)}
TCL puts {FME_MF_NAME= $(FME_MF_NAME)}
TCL puts {FME_BUILD_NUM= $(FME_BUILD_NUM)}
TCL puts {FME_BUILD_DATE= $(FME_BUILD_DATE)}
TCL puts {FME_PRODUCT_NAME= $(FME_PRODUCT_NAME)}

Note All of the examples shown in this topic should appear as a single continuous
line.

DEFAULT_MACRO Directive
Default macros are used to supply a value to a macro name only if the macro was undefined.
If the macro was already defined, the DEFAULT_MACRO line is equivalent to that of the MACRO
directive.
DEFAULT_MACRO CELL_LIB “DEFAULT.LIB”

INCLUDE Directive
To allow for modularity and reuse of portions of mapping files, a facility exists to allow
mapping files to include other mapping files. The net effect is that the entire contents of the
included file are processed as though they were pasted into the mapping file containing them.
Breaking mapping files into smaller pieces allows reuse of mapping file portions, which makes
maintenance easier.

TIP: GUI directives should only appear in the main mapping file. GUI directives
that appear in files included by the main mapping file, either directly or indirectly,
will be ignored.

74 Safe Software Inc.

Mapping File Syntax FME Fundamentals

The INCLUDE keyword is followed by the name of the file to include. If the file name given is
not an absolute path, then the file name is assumed to be relative to the location of the
containing file. For example, the control fragment below:
INCLUDE colors.fmi

causes the contents of the colors.fmi file to be read before the rest of the file is processed.
The colors.fmi file must be in the same directory as the mapping file that included it. Of
course, absolute path names may also be specified in an INCLUDE statement.

Note Mapping files are named with an .fme extension. Included files are usually
named with an .fmi extension.

INCLUDE files are often used to define macros that are used by many mapping files. In this way,
a mapping file change may be made in just one place and affect all mapping files that include
the changed file.

TIP: The file name to be included may be composed of macros. For example,
INCLUDE $(_COLOR_SETTINGS).

TIP: There is no limit on the nesting of INCLUDE files; however, circular includes
are not allowed.

The INCLUDE directive is also used for Dynamic Mapping File Creation.

Dynamic Mapping File Creation

To further assist in keeping mapping files modular and maintainable, mapping file fragments
can be generated programmatically. This is accomplished through two extensions to the
INCLUDE syntax.

If the INCLUDE target begins with a pipe (|) character, then FME assumes that the INCLUDE
target is a program which should be executed. The standard output of the program is then
included into the mapping file. This allows arbitrary shell scripts to be executed to produce
FME mapping file code. In this way, portions of the mapping file can be created from tables
which are more easily maintained than large repetitive blocks of mapping file code.
If the INCLUDE target is enclosed in square brackets ([ ]), then FME assumes the INCLUDE target
is a Tool Command Language (Tcl) script that should be executed. Any output written by the
script using the puts Tcl command is then included in the mapping file. Because the Tcl
interpreter is part of FME, this approach is more portable than using the pipe method of
dynamic mapping file creation. It is also more efficient, because no new process needs to be
started to do the generation. For more information on Tcl, see @Tcl2 in the FME Functions
and Factories manual. FME uses Tcl version 8.5.2.

TIP: FME renames the Tcl puts command to puts_real. If the script needs to
output to other files, then puts_real should be called.

In both methods of dynamic mapping file creation, the program or script is executed with the
mapping file directory as the current working directory. This allows any configuration tables
used to drive the script or program to be located in the same directory as the mapping file and,
therefore, be easily found.

Safe Software Inc. 75

FME Fundamentals Mapping File Syntax

Dynamic Mapping File Creation Example 1

The awk script resides in the file create.awk which contains this line:
{print “DWG_DEF”,$1,“autocad_color”,$2,“autocad_linetype”,$3}

A table listing the names of AutoCAD layers, their colors, and their linetypes is found in a file
called layers.lst and contains these three lines:
ROADS 13 CONTINUOUS
RIVERS 4 DASHED
RAILWAYS 7 CONTINUOUS

This INCLUDE line:

INCLUDE |awk -f create.awk < layers.lst

causes these lines to be generated into the mapping file:

DWG_DEF ROADS autocad_color 13 autocad_linetype CONTINUOUS
DWG_DEF RIVERS autocad_color 4 autocad_linetype DASHED
DWG_DEF RAILWAYS autocad_color 7 autocad_linetype CONTINUOUS

This example shows how the text processing language awk is used to generate mapping file
fragments to be included in a mapping file. In this example, an awk script located in the same
directory as the mapping file is executed and its results are included in the mapping file.

Dynamic Mapping File Creation Example 2

In this example, a Tcl script located in the same directory as the mapping file is executed and
its results are included in the mapping file. The Tcl script resides in the file create.tcl which
contains these lines:
proc makeDefs {filename} {
set file [open $filename r]
while {[gets $file line] >= 0} {
set layer [lindex $line 0]
set col [lindex $line 1]
set lt [lindex $line 1]
puts "DWG_DEF $layer autocad_color $col autocad_linetype $lt"
}
close $file
}

A table listing names of AutoCAD layers, their colors, and linetypes is found in a file called
layers.lst and contains these three lines:

ROADS 13 CONTINUOUS
RIVERS 4 DASHED
RAILWAYS 7 CONTINUOUS

This INCLUDE line:

INCLUDE [source create.tcl ; makeDefs layers.lst]

will cause these lines to be generated and parsed into the mapping file:

76 Safe Software Inc.

Mapping File Syntax FME Fundamentals

DWG_DEF ROADS autocad_color 13 autocad_linetype CONTINUOUS

DWG_DEF RIVERS autocad_color 4 autocad_linetype DASHED
DWG_DEF RAILWAYS autocad_color 7 autocad_linetype CONTINUOUS

These techniques can be extended to more sophisticated input files and output requirements.
For example, transfer specifications as well as _DEF lines can be generated this way from
comma-separated value files which are easily edited using spreadsheet tools.
This example shows how the same problem is solved using the Tcl scripting language. This has
the advantage of being slightly more efficient and portable since no external program is started
to process the table.

Environment Variable Expansion

Sometimes it is useful to pick up the value of an environment variable within a mapping file.
This allows session settings to be part of a user’s environment rather than requiring them to be
specified each time a mapping file is run. An environment variable expansion is requested by
enclosing the environment variable name with ${ and }.

TIP: Each operating system defines its own mechanism for setting environment
variables. On UNIX, they are most often set in .login or .cshrc scripts that run when
a user logs on. On Windows, they may be set in an AUTOEXEC.BAT file or by using
the Control Panel.

Assuming that the environment variable FME_CONTROL_DIR has been set to

/usr/control_files

then this line:

INCLUDE ${FME_CONTROL_DIR}/mappings.fme

will be expanded to:

INCLUDE /usr/control_files/mappings.fme

Environment variable values may themselves refer to other environment variables, which are
expanded recursively when the outermost environment variable is substituted. An environment
variable may not, directly or indirectly, refer to itself.
FME flags any reference to an undefined environment variable, and stops the translation if one
is encountered.

Static Function Evaluation

In certain situations it is convenient to execute an FME attribute function while the mapping
file is parsed. The value returned from the function is then used as if it was part of the original
mapping file. In this way, certain settings are determined dynamically rather than by prompting
the user.
An FME function may be invoked at mapping file parse time by enclosing it with $[ and ]. The
function may take any type of arguments, including macros which are expanded prior to its
evaluation.

Safe Software Inc. 77

FME Fundamentals Mapping File Syntax

Only functions returning a value are legal in this context.

For example, if the mapping file contains the output shape file line:
SHAPE road creationTime $[@TimeStamp(“^Y^m^d^H^M^S”)]

then all road objects created will have the same value for their timestamp attribute. The
timestamp is the parse time of the mapping file. However, if the mapping file contained the
line:
SHAPE road creationTime @TimeStamp(“^Y^m^d^H^M^S”)

all road objects created would have different time stamps, reflecting the time this object was
created.
Other FME functions that are often useful in this context are @Lookup, @TCL, and @Evaluate.

Example: Reprojecting Coordinates

The following example shows how to use static function evaluation to reproject coordinates
from LL83 to UTM, and specify the bounding coordinates for the search envelope in the
destination coordinate system (UTM).
READER_TYPE NULL
NULL_DATASET null
WRITER_TYPE NULL

# Dump out the mapping file after it is parsed -- this way we can see
# if our procedures worked.

FME_DEBUG MAPPING_FILE

# Set up some macros for testing purposes

MACRO _SDE3MINX 490000

MACRO _SDE3MINY 5000000
MACRO _SDE3MAXX 510000
MACRO _SDE3MAXY 5300000

# Define two TCL procedures, which will reproject a coordinate and

# return either the X or the Y. To do this, we make use of the
# TCL "FME_Execute" to do @Reproject on attributes of a feature.
# We "fake out" attributes with the X and Y we want by setting them
# in the "FME_Attributes" array. Then we just return the reprojected
# value.

TCL proc pointReprojectX {sourceCsys destCsys sourceX sourceY} { \

global FME_Attributes; \
set FME_Attributes(x) $sourceX; \
set FME_Attributes(y) $sourceY; \
FME_Execute Reproject $sourceCsys $destCsys x y; \
return $FME_Attributes(x); \
}

TCL proc pointReprojectY {sourceCsys destCsys sourceX sourceY} { \

global FME_Attributes; \
set FME_Attributes(x) $sourceX; \
set FME_Attributes(y) $sourceY; \
FME_Execute Reproject $sourceCsys $destCsys x y; \
return $FME_Attributes(y); \
}

78 Safe Software Inc.

Mapping File Syntax FME Fundamentals

# Now, use "static function evaluation" ($[ ]) to actually call the TCL
# procedures defined above, which will do the conversion and return the
# correct values.

SDE30_SEARCH_ENVELOPE $[@TCL("pointReprojectX UTM27-15 LL83 $(_SDE3MINX) $(_SDE3MINY)")]\

$[@TCL("pointReprojectY UTM27-15 LL83 $(_SDE3MINX) $(_SDE3MINY)")] \
$[@TCL("pointReprojectX UTM27-15 LL83 $(_SDE3MAXX) $(_SDE3MAXY)")] \
$[@TCL("pointReprojectY UTM27-15 LL83 $(_SDE3MAXX) $(_SDE3MAXY)")]

# This is just used to give the mapping file something to do...

FACTORY_DEF * CreationFactory \
OUTPUT FEATURE_TYPE junk @Log()

The example illustrates a technique, but does not perform any translation.

Safe Software Inc. 79

FME Fundamentals Mapping File Syntax

80 Safe Software Inc.

 8
FME Configuration
Chapter 8

Reader and Writer Selection

The two most important FME keywords specify the reader and writer modules to be used during
an FME session. The syntax of these keywords are:
READER_TYPE <readerType>
WRITER_TYPE <writerType>

Any valid reader or writer module may be named following these keywords. When the FME
session is started, the mapping file is scanned for these two keywords and the appropriate reader
and writer are created.
The mapping file fragment below creates a SAIF reader and a Shape writer:
READER_TYPE SAIF
WRITER_TYPE SHAPE

Reader and Writer Keywords

When a reader and writer are created, they scan the mapping file for additional parameters to
configure their operation.
All reader and writer parameters are labeled with a two-part keyword. The prefix of the keyword
is the current keyword associated with the reader or writer. The suffix identifies the configuration
option. The general form of these parameters is:
<ReaderKeyword>_<ReaderOption> <parameter value>
<WriterKeyword>_<WriterOption> <parameter value>

Note The above examples should appear as a single continuous line.

By default, the <ReaderKeyword> is the same as the READER_TYPE setting, and the
<WriterKeyword> is the same as the WRITER_TYPE setting. For example, if the READER_TYPE and
WRITER_TYPE are configured as:

READER_TYPE SAIF
WRITER_TYPE SHAPE

then by default the <ReaderKeyword> is SAIF and the <WriterKeyword> is SHAPE. When the SAIF
reader is created, it searches the mapping file for parameters prefixed with SAIF_ and the Shape
writer searches for parameters prefixed with SHAPE_.
Transformation specifications determine the mapping between source features and destination
features. The <ReaderKeyword> starts every source line of a transformation specification and the
<WriterKeyword> starts every destination line. In the example above, the transformation module

Safe Software Inc. 81

FME Fundamentals FME Configuration

scans the file for pairs of lines starting with SAIF and SHAPE, with the SAIF lines being the
source portion of the transformation specification and the SHAPE lines being the destination
portion.
The default values for the <ReaderKeyword> and <WriterKeyword> may be overridden by
specifying values for READER_KEYWORD and WRITER_KEYWORD in the mapping file or on the
command line. The syntax of these directives is:
READER_KEYWORD <newReaderKeyword>
WRITER_KEYWORD <newWriterKeyword>

These directives are used most often when the READER_TYPE and WRITER_TYPE are the same.
For example, if FME is to read an Design file, alter the geometry of some of the features, then
output a new Design file, a mechanism is needed to identify the source and destination portions
of the transformation specifications, as well as the source and destination data sets. The
following mapping file fragment shows how to configure FME to do such a translation:
READER_TYPE IGDS
WRITER_TYPE IGDS
WRITER_KEYWORD I_OUT

# Name the input IGDS file. Note that since no

# <ReaderKeyword> was specified, the default of IGDS
# is used
IGDS_DATASET original.dgn

# Provide the name for the output IGDS file

I_OUT_DATASET newone.dgn

# Identify the seed file for the output IGDS file

I_OUT_SEED_FILE seed.dgn

# Now write a transformation specification. The

# source line will be labeled with the
# <ReaderKeyword> (IGDS), and the destination line
# will be labeled with the <WriterKeyword> (I_OUT)

IGDS 40 igds_color 3 igds_style %s

I_OUT 40 igds_color 4 igds_style %s \
@Generalize(Douglas,10

When a <ReaderKeyword> or <WriterKeyword> is specified, the reader or writer module first

scans the file for its configuration options using this keyword as a prefix. If any of its required
options are not found, then the configuration file is rescanned to search for the option prefixed
by the default prefix which is the same as the reader or writer type. In the example above, if the
line:
I_OUT_SEED_FILE seed.dgn

was given as:

IGDS_SEED_FILE seed.dgn

the end result would be the same. The Design file writer module first scans the mapping file for
I_OUT_SEED_FILE, because I_OUT is the <WriterKeyword>. However, it will not find this

82 Safe Software Inc.

FME Configuration FME Fundamentals

keyword. It then rescans the file using IGDS as the <WriterKeyword> and finds a value for
IGDS_SEED_FILE.

Reader Datasets
The dataset a reader will extract data from is specified via the <ReaderKeyword>_DATASET
directive.
The syntax for this directive is:
<ReaderKeyword>_DATASET [<datasetSpecification>]+

One or more datasets can be specified, separated by spaces. If a dataset specification contains
spaces, it must be enclosed in quotes.
When more than one dataset is listed, then the FME will create a reader for each of the datasets
listed, one after the other. The features read will appear to the rest of FME to have come from
a single reader however. The FME's MULTI_READER is used internally to do this merging.
Therefore, when multiple datasets are listed, the features read will have the MULTI_READER
attributes added to them so that their true original source can be determined if necessary. See
the Multi Reader chapter in the FME Readers and Writers manual.
If one of the datasets cannot be read, then it is skipped and a warning is logged. If none of the
datasets can be read, an error is generated.
A <datasetSpecification> can also contain wildcards which FME will expand into a list of
files or directories. If the dataset contains any of the metacharacters supported by C-shell glob
style syntax, then the dataset is taken as a pattern and expanded to include all files that match.
See Dataset Wildcards, below.

Dataset Wildcards
The special characters supported are:

? Matches any single character.

* Matches any sequence of zero or more charac-

ters.

** Matches the current directory and recursively

all subdirectories

[chars] Matches any single character in chars. If chars

contains a sequence of the form a-b then any
character between a and b (inclusive) will
match.

{ab, cd,e,...} Matches any of the strings ab, cd, e, etc.

Examples:

C:\data\*.dgn expands to all files in the c:\data directory

that end with a .dgn extension

Safe Software Inc. 83

FME Fundamentals FME Configuration

C:\data\**\*.dgn expands to all files in the c:\data directory

and any subdirectory below it that ends with a
.dgn extension

C:\**\*.dgn expands to all files on the entire C: drive that

end with a .dgn extension

C:\{data,archive}\*.dgn expands to all files in the c:\data and c:\ar-

chive directories that end with a .dgn exten-
sion

C:\{data,archive}\92*.dgn expands to all files in the c:\data and c:\ar-

chive directories that start with 92 and end
with a .dgn extension

C:\data\92?034.dgn expands to all files in the c:\data directory

that start with 92, have any letter or number
next, and end with 034.dgn

C:\data\92[a-z]034.dgn expands to all files in the c:\data directory

that start with 92, have any lowercase letter
next, and end with 034.dgn

Reader Pipelines
Certain readers employ a set of factories to "massage" the features they produce into something
easier to work with in a mapping file. In such cases, the factories are stored externally to the
mapping file and referenced via the <ReaderKeyword>_PIPELINE directive.
The syntax for this directive is:
<ReaderKeyword>_PIPELINE <pipeline file>

Note This directive is usually used by FME reader developers (but not normally
used by mapping file authors). When this directive is present in a generated
mapping file, it should not be altered or adjusted.

Reader Start/End Feature

To limit the number of features returned, you can optionally use one or both of these keywords:
<ReaderKeyword>_START_FEATURE_NUM <startnum>
<ReaderKeyword>_MAX_FEATURES <maxfeatures>

For example, if you have a dataset with 10 features:

• If neither keyword is specified, all 10 features will be read. This is the default behavior.
• If START_FEATURE_NUM is specified and is greater than zero, then all features starting from
feature number specified in the keyword will be read. For example,
• If START_FEATURE_NUM is 5, all features from 5 to 10 inclusive will be read.
• If START_FEATURE_NUM is less than or equal to zero it will always be treated as 1.
• If MAX_FEATURES is specified and is greater then zero then features starting from feature
number 1 will be read up to a maximum of MAX_FEATURES. If MAX_FEATURES is less than or
equal to zero then all features will be read. For example,

84 Safe Software Inc.

FME Configuration FME Fundamentals

• If MAX_FEATURES is 5, feature numbers 1 to 5 will be read.

• If MAX_FEATURES is 100, features from 1 to 10 will be read (since the dataset only has 10
features).
• If both START_FEATURE_NUM and MAX_FEATURES are specified and are greater than zero, then
the number of features read will depend on their values and number of features in the dataset.
Here are some examples, considering the same example 10-feature dataset:
START_FEATURE_NUM = 1 will read only the first feature
MAX_FEATURES = 1
START_FEATURE_NUM = 1 all features will be read
MAX_FEATURES = -1
START_FEATURE_NUM = 1 features from 1 to 10 inclusive will be read
MAX_FEATURES = 10
START_FEATURE_NUM = 10 only the 10th feature will be read
MAX_FEATURES = 1
START_FEATURE_NUM = 10 only the 10th feature will be read
MAX_FEATURES = 100
START_FEATURE_NUM = 100 no features will be read since dataset has only
MAX_FEATURES = 2 10 features
START_FEATURE_NUM = 6 features from 6 to 7 inclusive will be read
MAX_FEATURES = 2
START_FEATURE_NUM = 6 features from 6 to 10 inclusive will be read
MAX_FEATURES = 100
START_FEATURE_NUM = 1 all features will be read
MAX_FEATURES = 0

Reader Feature Types

To limit the type of features returned, you can optionally use this keyword:
<ReaderKeyword>_FEATURE_TYPES <ftname> .. <ftname>

where ft1 through n lists the feature type names that the reader will read. Some readers will use
this list and efficiently read only those feature types specified while other readers will read
everything and but only output the specified feature types.
The feature types themselves are specified with any special characters encoded as per the table
<special characters>. This allows easy specification of feature types that contain spaces, for
example.
For example, if you have a dataset with 10 features:

Log File Configuration

FME logs its configuration, progress, performance, statistics, warnings, and error messages to
a log file as it executes.
If features are logged by FME they will be described in the log file, but they will also be
recorded in an FFS file. This FFS file uses the same path and basename as the log file name,

Safe Software Inc. 85

FME Fundamentals FME Configuration

but it has an “.ffs” extension. This file can be opened in the FME Universal Viewer to visually
inspect any features that were logged by FME.

Note The number of features written really means the number of features that were
passed to the writer, which is not necessarily equal to the number of features that can be
viewed in the FME Universal Viewer or in the destination format. What the writer does with
the features (whether it splits them, or even rejects them, etc.) is dependent on the
individual format. There is no reliable way of relaying that information back to the FME
core, which outputs the statistics information.

LOG_FILENAME
The file name of the log file is set in the mapping file or on the command line by supplying a
value for the LOG_FILENAME keyword. The example below sets the log file’s name:
LOG_FILENAME /tmp/fme.log

If the named log file already exists, then FME appends to it by default. If no LOG_FILENAME
keyword is found in the mapping file, no session logging is performed.

TIP: After a translation, the log file should be scanned for warning messages and
the statistics examined to ensure that the translation was successful. When an
error occurs during translation, the log file contains detailed messages describing
what happened and possibly a list of the features that caused the problem.

LOG_APPEND
The flag LOG_APPEND directs FME to either append to the log file if it existed previously or to
delete it. Valid choices for this keyword are YES or NO. The default is YES.

LOG_STANDARDOUT
To assist in building customized interfaces to FME, log information may be routed to the
standard output stream. This stream may be redirected to a graphical user interface or a network
connection. To configure FME to log to standard output, the LOG_STANDARDOUT keyword must
be given a value of YES:
LOG_STANDARDOUT YES

LOG_MAX_FEATURES
To prevent the accidental creation of extremely large log files, you can control the number of
FME features that may be logged during an FME session. The FME logs features found to be
invalid during translation and the mapping file may request features be logged with the @Log
function. If a bad input data file is encountered, or a mapping file inadvertently specifies
logging the entire dataset, a log file several megabytes in size may result.
The value of the LOG_MAX_FEATURES keyword sets a limit on the number of features that can
be logged during a translation, which by default is 20. This prevents excessively large log files
from being inadvertently generated.
To remove the limit on the maximum number of loggable features, set LOG_MAX_FEATURES to
-1. The line below sets the maximum loggable features to 50:

86 Safe Software Inc.

FME Configuration FME Fundamentals

LOG_MAX_FEATURES 50

LOG_MAX_RECORDED_FEATURES
To prevent the accidental creation of extremely large FFS log files that may be created by
logging of features, you can control the number of FME features that may be logged during an
FME session. The FME logs features found to be invalid during translation and the mapping
file may request that features be logged with the @Log function. If a bad input data file is
encountered, or a mapping file inadvertently specifies logging the entire dataset, a log file
several megabytes in size may result.
The value of the LOG_MAX_RECORDED_FEATURES keyword sets a limit on the number of features
that can be recorded to an FFS file by logging during a translation, which by default is 20. This
prevents excessively large FFS log files from being inadvertently generated.
To remove the limit on the maximum number of loggable features, set
LOG_MAX_RECORDED_FEATURES to -1. The line below sets the maximum loggable features to
50:
LOG_MAX_RECORDED_FEATURES 50

LOG_MESSAGE_NUMBERS
The value of LOG_MESSAGE_NUMBERS indicates whether or not to output the message numbers
for the logged messages. The allowed values are YES or NO.
An example output with the keyword set to YES looks like this:
INFORM|(#231040) Mapping File Identifier is: SHAPE TO NULL
INFORM|(#231001) FME Configuration: Reader Keyword is `SHAPE'

And if the keyword set to NO, the messages will look like this:
INFORM|Mapping File Identifier is: SHAPE TO NULL FME Configuration:
INFORM|Reader Keyword is `SHAPE'

FME_BEGIN_PYTHON and FME_END_PYTHON

Note FME does not ship with an Python interpreter; use of FME_BEGIN_PYTHON and
FME_END_PYTHON requires either Python 2.3 or Python 2.4 to be installed on the same
computer as FME, and be in the system path. Python may be obtained from either http://
www.python.org or http://www.activestate.com. By default, FME will attempt to load Python
2.4 first, and then Python 2.3. If you wish, you can use the FME_PYTHON_VERSION directive
to specify a preference. For example:

Use FME_PYTHON_VERSION 2.3 to load Python 2.3

Use FME_PYTHON_VERSION 2.4 to load Python 2.4

Note For examples, see http://www.fmepedia.com/index.php Startup_and_Shutdown_Script_Examples

Safe Software Inc. 87

FME Fundamentals FME Configuration

FME_BEGIN_PYTHON
The FME_BEGIN_PYTHON directive specifies a Python script file to execute just prior to the start
of translation. The script is executed after the mapping file has been completely parsed, and
after the log file has been opened, but before any of the readers or writers have begun to do their
processing.
Note: FME will abort the translation if the execution of FME_BEGIN_PYTHON scripts fails. If, for
some reason, this behavior is undesirable and you want to continue a translation even if the
execution fails, you can use Python's exception handling to trap errors, allowing FME to
continue with the translation.
The syntax is:
FME_BEGIN_PYTHON <python script>

where the <python script> is any valid Python script file to execute.
The script may access the following global Python variables:

Global Variable Contents

FME_LogFileName Allows you to write custom (user-defined) messages to the

log file. For example:
from pyfme import *
log=FMELogfile()
log.log("hello")

Note Writing custom (user-defined) messages to the log

file varies depending on whether it is during the start-up
or shutdown phase. In a start-up script (because FME
already has the log file open, and it is dangerous to open
it more than once) you should use FME_LogMessage.

88 Safe Software Inc.

FME Configuration FME Fundamentals

Global Variable Contents

FME_LogMessage The FME_LogMessage function is used to write messages

to the FME log file. It may be invoked in one of two ways:
FME_LogMessage <severity> <messageNumber>
[<arg1> ... <argN>]+
or
FME_LogMessage <severity> <message>
<severity> can have one of these values: fme_inform,
fme_warn, fme_error, fme_fatal,
fme_statistic, and fme_statusreport
When the first form is used, the message number must be
present in a file in the messages subdirectory under the FME
installation directory. The remaining parameters are used to
fill in any %0, %1, ... %n parameter holders in the message.
For example, if the message was:
3011, Opening file %0 for mode %1
then FME_LogMessage could be called like this:
FME_LogMessage fme_inform 3011 /tmp/
cacher.txt read
In the second form, the message is output directly to the log
file.
FME_MappingFileId The value of the MAPPING_FILE_ID directive specified in
the mapping file
FME_MacroValues A Python dictionary, indexed by macro name, which holds
the value of each macro known within the workspace or
mapping file at the end of parsing.

FME_END_PYTHON
The FME_END_PYTHON directive specifies a Python script file to execute just after translation has
completed, either successfully or prematurely due to an error being encountered.
If the translation ended due to an error, the script is executed after all cleanup is done, all reader
and writers are shut down, and the log file has been closed. If the translation was successful,
the script is executed after all the the readers and writers have finished their work, and the log
file has been closed.
The script has access to a number of Python global variables that contain statistics and other
information about the translation.

Safe Software Inc. 89

FME Fundamentals FME Configuration

The script may access the following global Python variables, as well as any global variables set
up in the FME_END_PYTHON. Note that if the translation failed, only the FME_Status and
FME_FailureMessage will contain valid values.

Global Variable Contents

FME_CPUTime The total CPU time from just before the

FME_BEGIN_PYTHON was called until just before the
FME_END_PYTHON was called.
The amount of user CPU time used from just before the
FME_CPUUserTime FME_BEGIN_ PYTHON was called until just before the
FME_END_ PYTHON was called.
The amount of system CPU time used from just before the
FME_CPUSysTime FME_BEGIN_ PYTHON was called until just before the
FME_END_ PYTHON was called.
The actual elapsed time used from just before the
FME_ElapsedRunTime FME_BEGIN_ PYTHON was called until just before the
FME_END_ PYTHON was called.
FME_ElapsedTime The elapsed time from just before the
FME_BEGIN_PYTHON script was called until just before
the FME_END_PYTHON was called.
FME_FailureMessage The failure message if the translation failed, blank if the
translation succeeded
FME_FeaturesRead A Python dictionary, indexed by feature type, which holds
the number of features read for that feature type
FME_FeaturesWritten A Python dictionary, indexed by feature type, which holds
the number of features written for that feature type
FME_LogFileName Note Writing custom (user-defined) messages to the log
file varies depending on whether it is during the start-up
or shutdown phase. In a start-up script (because FME
already has the log file open, and it is dangerous to open
it more than once) you should use FME_LogMessage.

Allows you to write custom (user-defined) messages to the

log file. For example:
from pyfme import *
log=FMELogfile()
log.log("hello")

90 Safe Software Inc.

FME Configuration FME Fundamentals

Global Variable Contents

FME_LogMessage The FME_LogMessage function is used to write messages

to the FME log file. It may be invoked in one of two ways:
FME_LogMessage <severity> <messageNumber>
[<arg1> ... <argN>]+
or
FME_LogMessage <severity> <message>
<severity> can have one of these values: fme_inform,
fme_warn, fme_error, fme_fatal,
fme_statistic, and fme_statusreport
When the first form is used, the message number must be
present in a file in the messages subdirectory under the FME
installation directory. The remaining parameters are used to
fill in any %0, %1, ... %n parameter holders in the message.
For example, if the message was:
3011, Opening file %0 for mode %1
then FME_LogMessage could be called like this:
FME_LogMessage fme_inform 3011 /tmp/
cacher.txt read
In the second form, the message is output directly to the log
file.
FME_MacroValues A python dictionary, indexed by macro name, which holds
the value of each macro known within the workspace or
mapping file at the end of parsing.
FME_MappingFileId The value of MAPPING_FILE_ID keyword if specified in
the mapping file
FME_NumFeaturesLogged This variable records the total number of requests for fea-
tures to be logged. This can be helpful to detect features that
a writer may have rejected.
Note that to avoid accumulating hundreds of features in the
log, FME by default suppresses all log attempts after the
first 20. Therefore, the actual number of features logged
may be fewer than the number requested.
FME_Status 0 if the translation failed and 1 if it was successful
FME_TotalFeaturesRead The total number of features read
FME_TotalFeaturesWritten The total number of features written
FME_TotalCoordinates The total number of coordinates output

Safe Software Inc. 91

FME Fundamentals FME Configuration

FME_BEGIN_TCL and FME_END_TCL

Translation Begin/End Hooks
When the FME translation engine is incorporated into larger systems, it may be useful to have
the FME perform some additional site-specific custom processing either before or after each
translation.
Users can specify multiple FME_BEGIN_TCL and FME_END_TCL directives. Errors encountered
during the execution of the begin/end Tcl scripts will fail the translation.
The FME_BEGIN_TCL and FME_END_TCL mapping file directives specify Tcl scripts to be run
either before or after (respectively) the actual translation. The FME_END_TCL script has access
to a number of variables which contain the statistics and status of the translation, and as such
can be used to write customized logs or insert records into a database (perhaps using the
TclODBC or Oratcl Tcl extensions – see examples 6 and 7, respectively) to make a record of
the translation’s activity.
The FME_END_TCL script can also read through the log file produced by the FME to extract
certain messages and record those results as well.
The FME_BEGIN_TCL and FME_END_TCL scripts will share a Tcl interpreter, which means that
the FME_BEGIN_TCL script can set up some Tcl global variables that will later be available to
the FME_END_TCL script. However, in most scenarios it is likely that only an FME_END_TCL
script will be needed. Lastly, the FME_BEGIN_TCL and FME_END_TCL interpreter is completely
separate from any other Tcl interpreters used in FME; for example, the @TCL and @Tcl2 FME
functions do not share this interpreter.
The scripts to be executed for FME_BEGIN_TCL or FME_END_TCL can be specified right in the
mapping file, or they can be “source’d” in from an external file. If they are specified in the
mapping file, then any quotation marks must be escaped with a \ and continuation characters
must be used to join all the lines in the script together into one logical FME mapping file line.
This also then requires that the ; statement separator be used in the Tcl code.
Alternately, if the Tcl script is placed in an external file and source’d in, then native Tcl quoting
and formatting may be used. For example:
FME_END_TCL proc finalize {} { \
... Tcl code here ... \
}; \
finalize;
or

FME_END_TCL source $(FME_MF_DIR_UNIX)/finalization.tcl

Note that if the script contains a procedure definition, the script must call the procedure it
defined, otherwise the procedure itself will not be executed and no processing will occur.
If any errors are encountered during the processing of either the FME_BEGIN_TCL or
FME_END_TCL script, the errors are written into the log file. If there is no log file, the errors will
not be reported. Any errors raised by the Tcl script will be up propagated to the FME translator

92 Safe Software Inc.

FME Configuration FME Fundamentals

and will cause the translation to terminate with an error code, so that external callers of the
FME translator can take appropriate action.
These hooks are not available within the definition of a custom format. They can, of course, be
used in a mapping file or workspace that itself employs a custom format.
The FME Objects Tcl interface may not be used within the either of the FME_BEGIN_TCL or
FME_END_TCL scripts. This is because using FME Objects at the translation start/end times
would cause a configuration conflict within the FME translation system. However, the
FME_BEGIN_TCL/FME_END_TCL scripts can themselves start new processes via the “exec” Tcl
command, and these new processes could involve FME Objects Tcl without any conflict.

Note For examples, see http://www.fmepedia.com/index.php Startup_and_Shutdown_Script_Examples

FME_BEGIN_TCL
The FME_BEGIN_TCL directive specifies a Tcl script to execute just prior to the start of
translation. The script is executed after the mapping file has been completely parsed, and after
the log file has been opened, but before any of the readers or writers have begun to do their
processing.

Note FME will abort the translation if the execution of FME_BEGIN_TCL scripts
fails. If, for some reason, this behavior is undesirable and you want to continue a
translation even if the execution fails, you can add a Tcl catch command in your
Tcl script – this will catch any errors and FME will continue with the translation.

The syntax is:

FME_BEGIN_TCL <Tcl script>

where the <Tcl script> is any valid Tcl script to execute, or

FME_BEGIN_TCL FME_Decode <encoded Tcl script>

which allows for the script to be encoded in an internal FME format produced by Workbench.
The script may access the following global Tcl variable:

Global Variable Contents

FME_LogFileName Note Writing custom (user-defined) messages to the log

file varies depending on whether it is during the start-up
or shutdown phase. In a start-up script (because FME
already has the log file open, and it is dangerous to open
it more than once) you should use FME_LogMessage.

Allows you to write custom (user-defined) messages to the

log file.

Safe Software Inc. 93

FME Fundamentals FME Configuration

Global Variable Contents

FME_LogMessage The FME_LogMessage function is used to write messages

to the FME log file. It may be invoked in one of two ways:
FME_LogMessage <severity> <messageNumber>
[<arg1> ... <argN>]+
or
FME_LogMessage <severity> <message>
<severity> can have one of these values: fme_inform,
fme_warn, fme_error, fme_fatal,
fme_statistic, and fme_statusreport
When the first form is used, the message number must be
present in a file in the messages subdirectory under the
FME installation directory. The remaining parameters are
used to fill in any %0, %1, ... %n parameter holders in the
message. For example, if the message was:
3011, Opening file %0 for mode %1
then FME_LogMessage could be called like this:
FME_LogMessage fme_inform 3011 /tmp/
cacher.txt read
In the second form, the message is output directly to the log
file.
FME_MacroValues(<macroname>) Each element in this array, indexed by macro name, holds
the number of each macro known to the workspace or map-
ping file at the end of parsing.
FME_MappingFileId The value of the MAPPING_FILE_ID directive specified
in the mapping file

FME_END_TCL
The FME_END_TCL directive specifies a Tcl script to execute just after translation has
completed, either successfully or prematurely due to an error being encountered.
If FME_END_TCL is followed by the FME_Decode token, the script is encoded in an internal FME
format, as mentioned above for FME_BEGIN_TCL.
If the translation ended due to an error, the script is executed after all cleanup is done, all reader
and writers are shut down, and the log file has been closed. If the translation was successful,
the script is executed after all the the readers and writers have finished their work, and the log
file has been closed.

94 Safe Software Inc.

FME Configuration FME Fundamentals

The script may access the following global Tcl variables, as well as any global variables set up
in the FME_BEGIN_TCL. Note that if the translation failed, only the FME_Status and
FME_FailureMessage will hold any values.

Global Variable Contents

FME_CPUTime The total CPU time from just before the

FME_BEGIN_TCL was called until just before the
FME_END_TCL was called.

FME_CPUUserTime The amount of user CPU time used from just before
the FME_BEGIN_TCL was called until just before the
FME_END_TCL was called.

The amount of system CPU time used from just be-

FME_CPUSysTime fore the FME_BEGIN_TCL was called until just before
the FME_END_TCL was called.

The actual elapsed time used from just before the

FME_ElapsedRunTime FME_BEGIN_TCL was called until just before the
FME_END_TCL was called.

FME_ElapsedTime The elapsed time from just before the

FME_BEGIN_TCL script was called until just before
the FME_END_TCL was called.

FME_EndingSeconds The seconds since epoch when the translation ended

(as returned by [clock seconds])

FME_EndingTimeStamp The ending time of the translation, formatted as

YYYY-MM-DD HH:MM:SS

FME_FailureMessage The failure message if the translation failed, blank if

the translation succeeded

FME_FeaturesRead(<featureType>) Each element in this array, indexed by feature type,

holds the number of features read for that feature
type.

FME_FeaturesWritten(<featureType>) Each element in this array, indexed by feature type,

holds the number of features written for that feature
type.

FME_LogFileName Allows you to write custom (user-defined) messages

to the log file. For example:
FME_END_TCL set outputFile [open $FME_LogFileName a] ;\
puts $outputFile {}; \
puts $outputFile {Writing some stuff at the end}; \
puts $outputFile {}; \
close $outputFile;

FME_MacroValues(<macroname>) Each element in this array, indexed by macro name,

holds the number of each macro known to the work-
space or mapping file at the end of parsing.

FME_MappingFileId The value of MAPPING_FILE_ID keyword if specified

in the mapping file.

Safe Software Inc. 95

FME Fundamentals FME Configuration

Global Variable Contents

FME_NumFeaturesLogged This variable records the total number of requests

for features to be logged. This can be helpful to de-
tect features that a writer may have rejected.
Note that to avoid accumulating hundreds of fea-
tures in the log, FME by default suppresses all log at-
tempts after the first 20. Therefore, the actual
number of features logged may be fewer than the
number requested.

FME_StartingSeconds The seconds since epoch when the translation was

started (as returned by [clock seconds])

FME_StartingTimeStamp The starting time of the translation, formatted as

YYYY-MM-DD HH:MM:SS

FME_Status 0 if the translation failed and 1 if it was successful

FME_TotalCoordinates The total number of coordinates output

FME_TotalFeaturesRead The total number of features read

FME_TotalFeaturesWritten The total number of features written

Example 1:

When placed into a complete mapping file, this mapping file fragment uses the translation
begin/end hooks to cause the translation start and end times to be written to standard output.
FME_BEGIN_TCL set gTranslationStartTime [clock format [clock seconds]]
FME_END_TCL puts \”Translation started time: $gTranslationStartTime \
nTranslation end time: [clock format [clock seconds]]\”

Example 2:

When placed into a complete mapping file, this mapping file fragment uses the translation end
hook and the global FME_Status variable to output a translation success or failure message.
Notice that it first defines a procedure which will do this testing and output, and then it actually
calls the procedure to do the work.
FME_END_TCL proc finally {} { \
global FME_Status; \
if {$FME_Status == "1"} { \
puts \"Translation was successful\"; \
} else { \
puts \"Translation was NOT successful\"; \
}; \
}; \
finally

This same example could also be written without using a procedure:

FME_END_TCL if {$FME_Status == "1"} { \
puts \"Translation was successful\"; \
} else { \
puts \"Translation was NOT successful\"; \
}

96 Safe Software Inc.

FME Configuration FME Fundamentals

Example 3:

This example shows how macros used by the mapping file can be passed into a beginning or
ending script as an argument to a procedure. This could be used to move, copy, e-mail, backup
or otherwise post/pre-process the destination datasets. In this example, the destination dataset
is backed up prior to the start of translation to save any existing output file that would normally
be overwritten.
The mapping file fragment is:
# The macro being used in this mapping file to set the destination
# dataset directory is DestDataset.
DWG_DATASET "$(DestDataset)"
# Source in the Tcl script to run at the conclusion of this
# translation. The script is stored in the same directory as
# this mapping file.
FME_BEGIN_TCL source {$(FME_MF_DIR_UNIX)/backup.tcl}; backup {$(DestDataset)}

The contents of the “backup.tcl” file are:

proc backup {filename} {
if {[file exists $filename]} {
file copy -force $filename $filename.bak
}
}

Example 4:

This example shows how the FME_END_TCL could be used to chain together translations,
based on the results of a particular translation. In this example, if the original translation fails,
then another fme session will be initiated.
Note that in the Tcl file, the 2> NUL: routes any log and error messages to the null device,
which effectively causes them to be ignored.
The mapping file fragment is:
# Source in the Tcl script to run at the conclusion of this
# translation. The script is stored in the same directory as
# this mapping file.
FME_END_TCL source {$(FME_MF_DIR_UNIX)/tryAnother.tcl}

The contents of the “tryAnother.tcl” file are:

set outputFile [open c:/temp/status.txt w+]
if { $FME_Status == "1" } {
puts $outputFile "Translation was successful"
} else {
puts $outputFile "Translation failed -- running alternate translation"
exec fme.exe alternateTranslation.fme 2> NUL:
}
close $outputFile

Example 5:

This example uses an external script to output a complete set of translation statistics to a
summary file at the end of translation.

Safe Software Inc. 97

FME Fundamentals FME Configuration

The mapping file fragment is:

# Set a mapping file id so that the Tcl finalization procedure "knows" which
# mapping file was being run
MAPPING_FILE_ID Shape to AutoCAD
# Log all the message numbers so that we can later pull out only those
# we are interested in.
LOG_MESSAGE_NUMBERS yes
# Source in the Tcl script to run at the conclusion of this
# translation. The script is stored in the same directory as
# this mapping file.
FME_END_TCL source {$(FME_MF_DIR_UNIX)/tclFinalization.tcl}

The contents of the “tclFinalization.tcl” file are:

# Open a file for writing out the translation stats
set outputFile [open c:/temp/stats_out.txt w+]
# Check for the translation status and output the desired message
if { $FME_Status == "1" } {
puts $outputFile "Translation was successful"
} else {
puts $outputFile "Translation failed"
puts $outputFile "Error message was: $FME_FailureMessage"
};
puts $outputFile ""
# Output the unique Mapping file identifier set in the mapping file using MAPPING_FILE_ID
puts $outputFile "Translation summary for $FME_MappingFileId"
# Output the number of features read\written per feature type.
puts $outputFile "---------------------------------------------------------------------------"
puts $outputFile " Features read summary
"
puts $outputFile "---------------------------------------------------------------------------"
# Loop through a sorted listed of the feature types that were read, and output the
# count for each one
set formatSpec "%-65s: %12s"
foreach featType [lsort [array names FME_FeaturesRead]] {
puts $outputFile [format $formatSpec $featType $FME_FeaturesRead($featType)]
}
puts $outputFile "---------------------------------------------------------------------------"
puts $outputFile [format $formatSpec "Total Features Read" $FME_TotalFeaturesRead];
puts $outputFile "---------------------------------------------------------------------------"

puts $outputFile ""

puts $outputFile "---------------------------------------------------------------------------"
puts $outputFile " Features Written summary
"
puts $outputFile "---------------------------------------------------------------------------"
# Loop through a sorted listed of the feature types that were written, and output the
# count for each one
foreach featType [lsort [array names FME_FeaturesWritten]] {
puts $outputFile [format $formatSpec $featType $FME_FeaturesWritten($featType)]
}
puts $outputFile ""
puts $outputFile "---------------------------------------------------------------------------"
puts $outputFile [format $formatSpec "Total Features Written" $FME_TotalFeaturesWritten]
puts $outputFile [format $formatSpec "Total Coordinates Written" $FME_TotalCoordinates]
puts $outputFile "---------------------------------------------------------------------------"
puts $outputFile ""
# Look for any lines in the logfile that were warnings, and output a count of them to
# the summary file. Also, check if there was any "unexpected input remover"
# statistics line and report a non-zero count if there was (this may happen
# when workbench generated mapping files are run against input datasets
# with different feature types than those that were expected)
# And also fish out the system status log message (which is #246014) and copy
# it into the output file
set logFileExists [file exists $FME_LogFileName]
set warnings 0

98 Safe Software Inc.

FME Configuration FME Fundamentals

if {$logFileExists} {
set logFile [open $FME_LogFileName r]
while {[gets $logFile line] >= 0} {
if {[regexp {WARN} $line]} {
incr warnings
} elseif {[regexp {#246014} $line]} {
puts $outputFile "-------------------------------------------------------------------
"
puts $outputFile $line
puts $outputFile "-------------------------------------------------------------------
"
puts $outputFile ""
} elseif {[regexp {Unexpected Input Remover} $line]} {
set totalFeatures 0
set acceptedFeatures 0
set rejectedFeatures 0
set line [regsub {^.*Unexpected} $line {Unexpected}]
catch {scan $line "Unexpected Input Remover(TestFactory): Tested %d input features -
- %d features passed, %d features failed." totalFeatures acceptedFeatures
rejectedFeatures}
if {$rejectedFeatures > 0} {
puts $outputFile "---------------------------------------------------------------
"
puts $outputFile [format $formatSpec "Features with Unexpected Feature Types"
$rejectedFeatures]
puts $outputFile "---------------------------------------------------------------
"
puts $outputFile ""
}
}
}
close $logFile
}
puts $outputFile "---------------------------------------------------------------------------
"
puts $outputFile [format $formatSpec "Logfile $FME_LogFileName Warnings" $warnings]
puts $outputFile "---------------------------------------------------------------------------
"
puts $outputFile ""
puts $outputFile "---------------------------------------------------------------------------
"
puts $outputFile [format $formatSpec "Total Elapsed Time (seconds)" $FME_ElapsedTime]
puts $outputFile [format $formatSpec "Total CPU Time (seconds)" $FME_CPUTime]
puts $outputFile "---------------------------------------------------------------------------
"
puts $outputFile ""
# And close the file
close $outputFile

Example 6: Installing TclODBC

This example uses an external script to insert a record of the translation’s activity into a
database using the TclODBC package. In this example, an Access database is created (if
necessary) and populated with a row for each translation that completes.
To use TclODBC within the FME environment, follow these steps:
1 Read about the TclODBC package at http://wiki.tcl.tk/2151
2 Download the TclODBC package from http://sourceforge.net/projects/tclodbc
3 Unzip the result
4 Edit the supplied setup.tcl to change:

Safe Software Inc. 99

FME Fundamentals FME Configuration

if [string match *lib $i] {

to
if [string match *lib* $i] {
5 In a command prompt in the directory holding setup.tcl, run “fme setup.tcl”. This will
install the TclODBC package in the FME’s Tcl environment.
6 Ensure any scripts that require the TclODBC package start with:
package require tclodbc

7 To invoke the sample script below which does the database insertion, the mapping file
contains this line:
FME_END_TCL source {$(FME_MF_DIR_UNIX)/recordTranslationODBC.tcl}

The contents of the “recordTranslationODBC.tcl” file are:

# =========================================================================
#
# recordTranslationODBC.tcl
#
# This script records the execution of a translation using
# the TclODBC package. This example includes the creation of the
# Access database and table for storing the translation results.
# One row for each translation run is inserted into the table.
# Note that for an acutal production system the "puts" statements
# would be removed.
package require tclodbc
# =========================================================================
#
# Set up some variables that are used within to create and connect
# to the database via ODBC
set driver "Microsoft Access Driver (*.mdb)"
set dbfile c:/translations.mdb
set dsn XLATION
# =========================================================================
# Create the database if it isn't already there. We wouldn't do this if the
# database was a server-based one, but for this example we're just using Access.
if {![file exists $dbfile]} {
puts "Creating database $dbfile"
database configure config_dsn $driver [list "CREATE_DB=\"$dbfile\" General"]
} else {
puts "Using existing database $dbfile"
}
# =========================================================================
# Make an ODBC datasource for this database, and connect to it
# First always remove the DSN if it was there already. If we were
# using ODBC to connect to a "real" database, then we'd just assume
# the DSN is already valid
catch {database configure remove_dsn $driver "DSN=$dsn"}
database configure add_dsn $driver [list "DSN=$dsn" "DBQ=$dbfile"]
database db $dsn
# =========================================================================
# Create the table we want to insert into if it wasn't there already
if {[llength [db tables XLATION_RESULTS]] == 0} {
puts "Creating XLATION_RESULTS table in database $dbfile"
db "CREATE TABLE XLATION_RESULTS (
MappingFileID VARCHAR(50),
StartTime TIMESTAMP,
EndTime TIMESTAMP,
CpuTime DOUBLE,
Successful CHAR(3),
NumFeatures INTEGER)"
} else {
puts "XLATION_RESULTS table present in database $dbfile"
}
# =========================================================================

100 Safe Software Inc.

FME Configuration FME Fundamentals

# All of that was just setup, now we actually can insert our row,
# commit it, and disconnect from the datasource
set Success yes
if {$FME_Status == 0} {set Success no}
db "INSERT INTO XLATION_RESULTS
(MappingFileID, StartTime, EndTime, CpuTime, Successful, NumFeatures)
VALUES ('$FME_MappingFileId', \{ts '$FME_StartingTimeStamp'\},
\{ts '$FME_EndingTimeStamp'\},
$FME_CPUTime, '$Success', $FME_TotalFeaturesWritten)"

db commit
db disconnect
# =========================================================================
# If you were connecting to a server-based database, you probably
# would NOT remove the ODBC DSN at the end. But since we were file based
# we will remove it
database configure remove_dsn $driver "DSN=$dsn"

Example 7: Installing Oratcl

This example uses an external script to insert a record of the translation’s activity into an Oracle
database using the Oratcl package.
To use Oratcl within the FME environment, follow these steps:
1 Install and configure Oracle client software on your computer. Verify you can access your
database using sqlPlus.
2 Read about and download the Oratcl package at http://oratcl.sourceforge.net.
3 Unzip the result into $FME_HOME/tcl_library/oratcl4.1 (you will have to create this
directory, and the 4.1 may need to change to match version of Oratcl you’ve downloaded).
After unzipping, move the msvcr70.dll and oratcl41.dll to $FME_HOME/tcl_library
(up one level).
4 Ensure any scripts which require the Oratcl package start with:
package require Oratcl

(It is important that the “O” in Oratcl is uppercase.)

5 To invoke the sample script below script which does the database insertion, the mapping
file contains this line:
FME_END_TCL source {$(FME_MF_DIR_UNIX)/recordTranslationOracle.tcl}

The contents of the "recordTranslationOracle.tcl" file are:

# =========================================================================
#
# recordTranslationOracle.tcl
#
# This script records the execution of a translation using
# the Oratcl package. This example includes the creation of the
# XLATION_RESULTS table for storing the translation results.
# One row for each translation run is inserted into the table.
package require Oratcl
# =========================================================================
# Login to the Oracle service
set username scott
set password tiger
set service amidala
set loginHandle [oralogon $username/$password@$service]

Safe Software Inc. 101

FME Fundamentals FME Configuration

# =========================================================================
# Determine if the xlation_results table we wish to record results to exists
set tableExists no
set statementHandle [oraopen $loginHandle]
orasql $statementHandle "select * from user_tables where table_name = 'XLATION_RESULTS'"
while {[orafetch $statementHandle -datavariable row] == 0} {
set tableExists yes
}
# =========================================================================
# Create the xlation_results table if we need to
if {$tableExists == "no"} {
orasql $statementHandle "CREATE TABLE XLATION_RESULTS (
MappingFileID VARCHAR(50),
StartTime TIMESTAMP,
EndTime TIMESTAMP,
CpuTime FLOAT,
XlationSuccessful CHAR(3),
NumFeatures INTEGER)"
}
# =========================================================================
# Insert the translation results into the table
set Success yes
if {$FME_Status == 0} {set Success no}
orasql $statementHandle "INSERT INTO XLATION_RESULTS
(MappingFileID, StartTime, EndTime,
CpuTime, XlationSuccessful, NumFeatures)
VALUES ('$FME_MappingFileId',
timestamp '$FME_StartingTimeStamp',
timestamp '$FME_EndingTimeStamp',
$FME_CPUTime, '$Success',
$FME_TotalFeaturesWritten)" -commit
# =========================================================================
# Shut down the statement handle
oraclose $statementHandle
# =========================================================================
# Logout of our oracle service
oralogoff $loginHandle

FME_JVM_MIN_HEAP_SIZE and
FME_JVM_MAX_HEAP_SIZE
Through the environment variables FME_JVM_MIN_HEAP_SIZE and FME_JVM_MAX_HEAP_SIZE,
users can customize the initial and maximum heap size for initializing Java VM. These settings
are for FME Plug-ins written in Java.
By default, the initial heap size is 1024K and the maximum is 16384K. JVM will take the
default values if these two variables are not set.
The values of these two variables must be multiples of 1024K (for example, 4M and 64M or
4096K and 32768K).

FME_SHARED_RESOURCE_DIR
Through the environment variable FME_SHARED_RESOURCE_DIR, FME can share resource
directories that contain the following subdirectories: Transformers, Formats, Coordinate
Systems, and Transformer Categories.

102 Safe Software Inc.

FME Configuration FME Fundamentals

Windows
• FME_SHARED_RESOURCE_DIR can point to a shared resource directory. For example,
FME_SHARED_RESOURCE_DIR=c:\temp\fred;c:\temp\wilma
• The Registry entry HKEY_CURRENT_USER/Software/Safe Software Inc./Feature
Manipulation Engine/Shared Resource Directory can also point to a shared resource
directory.

Linux/UNIX
• FME_SHARED_RESOURCE_DIR must be set to run workspaces that reference custom
transformers, custom formats, and custom coordinate systems. For example,
export FME_SHARED_RESOURCE_DIR=~/fred;~/wilma

FME_STROKE_MAX_DEVIATION
The stroking of arcs can be controlled by this directive, which defines the maximum distance
between the arc feature and its stroked linear feature. If this directive exists, an arc feature will
be stroked into a linear feature with the smallest number of points, such that the maximum
distance between the arc and the stroked line is less than or equal to the value of this directive.
This directive defaults to 0 if not specified. If the value of this directive is smaller than or equal
to 0, arc features will be stroked into linear features such that the degree per edge is roughly the
value of FME_ARC_DEGREES_PER_EDGE which defaults to 5. (See the @Arc function in the FME
Functions and Factories manual for more information on FME_ARC_DEGREES_PER_EDGE.) If
the value is greater than one of the primary or secondary radius, arc features will be stroked
into linear features containing 4 points or less.

Geometry Handling
FME_GEOMETRY_HANDLING
Notes:

• Before the release of FME 2009, this directive was called FME_USE_RICH_GEOMETRY. It has
been renamed to more accurately reflect its function in FME.
• It is important to understand that, for the most part, the addition of the enhanced geometry
model will be transparent to users. You will not have to change the way you use FME or set up
a mapping file. The only visible difference should be improved output (if there was room for
improvement).

Enhanced geometry provides FME with the capability to handle very complex geometry types,
such as polygon features whose boundaries include arc features. It also provides the ability to
truly hold measures.
The FME_GEOMETRY_HANDLING global directive is used by FME to signal whether to produce
improved geometric results, where possible.
The directive only sets the enhanced geometry mode in readers and factories/functions/
transformers that were built before the inception of the enhanced geometry model in FME
2006. Most readers, factories, functions and transformers developed after FME 2006 were built

Safe Software Inc. 103

FME Fundamentals FME Configuration

using the enhanced geometry model and hence are not affected by this global directive. In
addition, the directive does not guarantee that all features output by a reader/function/factory/
transformer will be enhanced; only where it is beneficial. For example, the Shape Reader will
only output enhanced geometries if the source shapefile contains measures.
Writing of enhanced geometry is handled automatically by all writers. Those writers with
native enhanced geometry support will take advantage of the more complex geometries that
can be represented, and will maintain, within the constraints of the format, the geometry passed
to it. Writers that support only classic geometry will automatically convert any enhanced
geometry into classic geometry. This means any geometry (i.e., enhanced or classic) can be
sent to any writer. To fully take advantage of writers with enhanced geometry support, features
with enhanced geometry must be passed to them. The simplest way to accomplish this is to use
a reader developed after FME 2006 and/or set the FME_GEOMETRY_HANDLING directive to YES.
The default for this directive is NO. To use the enhanced geometry mode, set the directive to
YES.For example:
FME_GEOMETRY_HANDLING YES

If the directive is set to NO or is missing, the mapping file/workspace/FME Objects application

will use classic geometry mode. This means existing workspaces/mapping files/FME Objects
applications will produce the same results as they did before the introduction of the enhanced
geometry mode.
In Workbench and the Viewer, the FME_GEOMETRY_HANDLING option is called Geometry
Handling, and valid values for this parameter are Enhanced and Classic. To set this in
Workbench, go to the Navigator pane, choose Advanced Settings > Geometry Handling. In the
Viewer, select View > Options > Geometry Handling. The default mode is Classic in
Workbench and Enhanced in the Viewer.
See the documentation of applicable readers, factories, functions and transformers to find more
details on how their behavior will change when the geometry mode is set to Enhanced.
For more information on the differences between enhanced geometry and classic geometry
handling, visit www.fmepedia.com and search Geometry Model.

Temporary Directory Determination

FME puts many temporary files in the system temporary directory, which on some Windows
versions defaults to C:\temp. If there is not enough room in this directory due to space
limitations on the C drive, you can override this default and send the FME temporary files to a
different directory using the FME_TEMP environment variable. (In Windows, look under
Control Panel | System | Advanced | Environment Variables).
FME searches for a temp directory using the following tests in order:
1 If the user environment variable FME_TEMP exists, use its value as the temporary directory
path.
2 If the user environment variable TEMP exists, use its value as the temporary directory path.
3 If a directory called \temp exists on the drive on which FME is running, use that directory.

104 Safe Software Inc.

FME Configuration FME Fundamentals

4 If a directory called \tmp exists on the drive on which FME is running, use that directory.

If all of these tests fail to locate an existing temporary directory, FME aborts with an error
message indicating that it couldn't open a temporary file. To remedy this situation, either:
Create an <FMEdrive>:\temp or <FMEdrive>:\tmp directory (where <FMEdrive> is the drive
on which FME is running).
OR
Define the FME_TEMP or TEMP user environment variable, either system-wide or for the user
account on which FME is running. For example, if the temporary files are to be placed into the
directory j:\scratch, then the environment variable FME_TEMP would be set to j:\scratch
before FME is run.

Java VM Loading
These settings are for FME Plug-ins written in Java.
These environment variables allow you to specify memory available to Java Plug-ins:
FME_JVM_MIN_HEAP_SIZE: customize the initial heap size for initializing Java VM.

FME_JVM_MAX_HEAP_SIZE: customize the maximum heap size for initializing Java VM.

By default, the initial heap size is 1024K and the maximum is 16384K. JVM will take the
default values if these two variables are not set.
The values of these two variables must be multiplies of 1024K, for example, they can be 4M
and 64M or 4096K and 32768K.

Mapping File Debugging

FME provides several facilities that may be enabled to assist in debugging mapping files. These
debugging facilities are useful for finding either errors in a custom mapping file being
developed, or errors in input data. Each debugging option causes diagnostic information to be
output to the log file.
The debug options are enabled by listing the desired debug facilities on one or more FME_DEBUG
lines in a mapping file. The syntax of these lines is:
FME_DEBUG <option1> [<optionN>]*

The valid debugging options and their actions are listed below.

Safe Software Inc. 105

FME Fundamentals FME Configuration

Valid Debugging Options and Related Actions

Option Action

BADNEWS This is a debugging option useful only to Safe Software devel-

opers. When this is activated, FME will log the location and
message of any internal software exception.

DonutFactory This activates warning output from the DonutFactory. Points

and polygons contained by more than one polygon are logged,
as are polygons containing more than one point. This is used to
track down problems with extra points or overlapping polygons
in the original source data set.

DUMP_SCHEMA This option is usually only used on the mapping file generation
command line, and is used to cause FME to log the schema in-
formation it reads from the source dataset(s). This can be used
to determine why a mapping file is not being generated in the
expected way, usually to troubleshoot problems with the gen-
eration parameters or the source reader. It is also often used
by developers using the plug-in SDK to check if their readSche-
ma implementation is correct.

FACTORY Each factory definition line is logged as the factory is activated.

This can be used to ensure that the factories intended to oper-
ate are correctly created and configured.

FACTORY_TRACE This debugging option causes each feature to have the attribute
fme_factory_trace added to it. This attribute contains an or-
dered list of all factories the feature passed through. The
@Log() function may be used in conjunction with this option
causing this attribute’s value to be logged to allow inspection.

FME_END_TCL This debugging option will log additional diagnostic messages

in case, for some reason, the FME_END_TCL directive fails.

FME_STACK_TRACE This is a debugging option useful to Safe Software developers

only. It provides additional information for developers, but
works only in conjunction with the BADNEWS option.

MAPPING_FILE Every line of the mapping file is logged to the log file after all
blanks and comments have been removed, continuation char-
acters have been taken into account, and macros have been
expanded. A histogram of the keywords encountered in the
mapping file is also listed and used to view the mapping file as
FME actually sees it. The keyword histogram can also be used
to discover missing continuation characters if it reports extra
incorrect keywords.

PolygonDissolveFactory This activates additional statistical output from the PolygonDis-

solveFactory. When a GROUP_BY clause is used with this facto-
ry, setting this debug option causes the number of features
input and output from each group to be logged.

ReferenceFactory This activates additional statistical output information for the

ReferenceFactory. A table showing the number of features pro-
cessed by the ReferenceFactory is output when this is activat-
ed.

Relate This option causes each row read by an @Relate query to be

logged to the log file.

106 Safe Software Inc.

FME Configuration FME Fundamentals

Option Action

TRANSFER_PROCESS This is a very expensive debugging option that examines the

transformation process. It reports any attributes of source fea-
tures that were ignored or referenced but not defined during
the transformation process. Because it is done on each feature
and may produce a great deal of output in the log file, it should
only be done while testing mapping files on small input
datasets.

TRANSFER_SPECS Each transfer specification source and destination line is logged

to the log file as it is processed. This is useful when tracking
down an unmatched transfer specification pair or to ensure that
the transfer specifications are expanded appropriately.

UNCORRELATED One feature of each feature type is logged if it was not matched
by any source line of a transformation specification. This assists
in determining exactly which features were not correlated, so
transformation specifications may be written for them.

UNGROUPED One feature of each feature type is logged if it was correlated

and transformed but had no output destination. For example, if
a Shape feature of the type road was created but there was no
SHAPE_DEF for the road type, the feature would be logged.

Mapping File Identification

To assist in supporting mapping files that may be distributed widely, FME supports a directive
that allows the exact version of a mapping file to be echoed in the FME log file. This gives
quick confirmation that the correct mapping file version was used when browsing the log file.
The MAPPING_FILE_ID directive is used for this purpose. The syntax is:
MAPPING_FILE_ID <identification string>

For example, if a mapping file contained the following line (which should appear as a single,
continuous line):
MAPPING_FILE_ID TRIM to Shape Release 2.0 Oct 1 ‘02

then the string “TRIM to Shape Release 2.0 Oct 1 ‘02” would be echoed to the FME log file
each time the mapping file is run.

Minimum Build Requirement

To ensure that a mapping file is not used with an older version of FME which may not have all
the facilities used in mapping file, the mapping file may specify the minimum FME build
number that can run it. The FME_MINIMUM_BUILD directive is used for this purpose. The syntax
is:
FME_MINIMUM_BUILD <build number>

For example, if a mapping file contained the line:

FME_MINIMUM_BUILD 5600

Safe Software Inc. 107

FME Fundamentals FME Configuration

then no FME with a build earlier than 5600 would be permitted to run the mapping file.

108 Safe Software Inc.