Syntax @TCL() @Tcl2() Arguments A Tool Command Language (Tcl) expression to execute on the feature. If the expression contains spaces or parentheses, it should be enclosed in quotation marks. Range: String @Tcl2 Configuration The @Tcl2 function accepts the following configuration lines: Tcl2 Tcl2 FME_Decode A Tcl expression to execute before the translation begins. Range: String Same as above, but the string is encoded in an internal FME format, as produced by Workbench's TEXT_EDIT_TCL transformer parameter type. Range: Encoded string Any number of Tool Command Language (Tcl) configuration lines may be present in the mapping file. They are executed by the Tcl interpreter in the order in which they appear before the translation begins. Tcl procedure definitions may be placed on these lines: Tcl2 proc toUpper {value} { return [string toUpper value] } Note: Since the Tcl interpreter compiles procedures, it is much more efficient to make small procedures and call them from @Tcl2 than it is to put the equivalent Tcl code inline in the @Tcl2 arguments directly. As an arbitrary Tcl expression may be placed on these configuration lines, this can be used to effect any action before a translation begins, such as deleting a file: Tcl2 unlink $(FME_MF_DIR)/status.txt The typical use of the configuration line is to source a file that defines procedures to be called later by the @Tcl2 function: Tcl2 source $(FME_MF_DIR)/tclProcs.tcl Note: An absolute path name is required to reliably source externally- defined Tcl procedures. Usually, the FME_HOME or FME_MF_DIR macros are placed before the file name to fully qualify the path name. If the file and path name contain spaces, enclose the path in parentheses: Tcl2 source {$(FME_MF_DIR)/tclProcs.tcl} Note: In some situations, it is useful to run an arbitrary Tcl script just before and/or just after a translation completes. In these scenarios, the FME_BEGIN_TCL and FME_END_TCL directives can be used. See the documentation on Translation Begin/End Hooks in the FME Configuration section of the FME Fundamentals manual (available in the Online Documentation area of Safe Software's website or through FME help menus). @Tcl2 Description Note: @Tcl2 (note the lowercase "cl") has better performance than @TCL because it does not make available the FME_Attributes global array variable, which is expensive to set up. Functions are provided to access feature attributes and should be used instead of the FME_Attributes array. @TCL is now deprecated as a function and its use is discouraged. This function evaluates an arbitrary Tcl 8.5.2 expression, and returns the result. Tcl, and its documentation, is copyrighted by the Regents of the University of California, Sun Microsystems, Inc., and other parties. However, the Tcl authors have granted permission to any party to reuse and modify the code and documentation, provided the original copyright holders are acknowledged. This function allows access to a complete procedural language with rich built-in primitives from within FME mapping files. Tcl procedures can be written to simplify tasks that are awkward to accomplish using standard mapping file syntax, and to allow users to extend FME to solve new problems. To effectively use this function, familiarity with the Tcl language is required. There are several sources of information available to assist in learning Tcl. The Internet has many Tcl sites - the official site is at http://www.scriptics.com. The book Tcl and the Tk Toolkit by John Ousterhout, published by Addison-Wesley, ISBN 0-201-63337-X provides a thorough introduction to Tcl. Note: The FME parser assumes that any words beginning with a % (percent) sign are transfer variables when found in a transfer specification. For this reason, it is not possible to pass a % as an argument to a call to @Tcl2 when the call is made in a correlation line. (It is okay to use a % when the call is made on a Factory input or output.) The work-around is to define a Tcl variable which holds the % sign on a Tcl2 configuration line, and then use it in the @Tcl2 call: Tcl2 set formatString %0.5d @Tcl2("format $formatString [FME_GetAttribute a])") Most of the Tcl functions and variables used in @Tcl2 are documented within the TclCaller transformer documentation. FME_StatMessage function (Not externally documented) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The FME_StatMessage function is used to output statistics to the FME log file. FME_StatMessage [ [ []]] =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- 2 2 ============================================================================== 4 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- can be a string or number, if number then it is assumed to be a message number that must exist in a message file. This will be used as the main heading for a given set of items. can be string or number, if number then it is assumed to be a message number that must exist in a message file. This will be used for the summary part of the string can have one of these values: fme_inform, fme_warn, fme_error, fme_fatal, fme_statistic, fme_statusreport. can be a string or number, if number then it is assumed to be a message number that must exist in a message file. This will be used as the sub heading for a given set of items. @TCL Configuration This function is deprecated. Use @Tcl2 instead. The @TCL function accepts the following configuration line: TCL A Tcl expression to execute before the translation begins. Range: String Any number of Tool Command Language (Tcl) configuration lines may be present in the mapping file. They are executed by the Tcl interpreter in the order in which they appear before the translation begins. Tcl procedure definitions may be placed on these lines: TCL proc toUpper {value} { return [string toUpper value] } As an arbitrary Tcl expression may be placed on these configuration lines, this can be used to effect any action before a translation begins, such as deleting a file: TCL unlink $(FME_MF_DIR)/status.txt The typical use of the configuration line is to source a file containing Tcl procedure definitions which defines procedures to be called later by the @TCL function: TCL source $(FME_MF_DIR)/tclProcs.tcl Note: An absolute path name is required to reliably source externally- defined Tcl procedures. Usually, the FME_HOME or FME_MF_DIR macros are placed before the file name to fully qualify the path name. If the file and path name contain spaces, enclose the path in parentheses: TCL source { $(FME_MF_DIR)/tclProcs.tcl } @TCL Description This function is deprecated. Use @Tcl2 instead. This function evaluates an arbitrary Tcl 8.4.12 expression, and returns the result. Tcl, and its documentation, is copyrighted by the Regents of the University of California, Sun Microsystems, Inc., and other parties. However, the Tcl authors have granted permission to any party to reuse and modify the code and documentation, provided the original copyright holders are acknowledged. This function allows access to a complete procedural language with rich built-in primitives from within FME mapping files. Tcl procedures can be written to simplify tasks that are awkward to accomplish using standard mapping file syntax, and to allow users to extend FME to solve new problems. To effectively use this function, familiarity with the Tcl language is required. There are several sources of information available to assist in learning Tcl. The Internet has many Tcl sites - the official site is at http://www.scriptics.com. The book Tcl and the Tk Toolkit by John Ousterhout, published by Addison-Wesley, ISBN 0-201-63337-X provides a thorough introduction to Tcl. Note: The FME parser assumes that any words beginning with a % (percent) sign are transfer variables when found in a transfer specification. For this reason, it is not possible to pass a % as an argument to a call to @TCL when the call is made in a correlation line. (It is okay to use a % when the call is made on a Factory input or output.) The workaround is to define a Tcl variable which holds the % sign on a TCL configuration line, and then use it in the @TCL call: TCL set formatString %0.5d @Tcl("format $formatString $FME_Attributes(a)") Global Variables ~~~~~~~~~~~~~~~~ Three Tcl global variables provide a gateway between an FME feature and the Tcl script: FME_Attributes, FME_FeatureType,FME_CoordSys, FME_AttrEncoding, and FME_AttrNameEncoding variables. In order to use these in a Tcl procedure, they must be declared as global; otherwise, the variables will be considered to be local and will not affect or interact with the FME feature upon which the function is run. To use them in a function, use a pattern like: proc doSomething { global FME_Attributes global FME_FeatureType global FME_CoordSys # rest of function goes here... } FME_Attributes Array ~~~~~~~~~~~~~~~~~~~~ Within any Tcl procedure called by @TCL, the Tcl global array variable FME_Attributes mirrors all attributes of the feature that @TCL was invoked upon. Note: The FME_Attributes variable is completely unrelated to the FME @GlobalVariable function. These may be read, written, or removed. For example, set FME_Attributes(attr1) 30 sets an attribute called attr1 in the current feature to have the value 30 in the same way that @SupplyAttributes(attr1,30)does. Similarly, puts $FME_Attributes(attr1) outputs the value of the current feature's attr1 attribute to standard output. As well, unset FME_Attributes(attr1) removes the attribute attr1 from the feature in the same way @RemoveAttribute(attr1)does. Finally, [array names FME_Attributes] returns a list of all the attributes of the current feature. Note: Because of the interaction between Tcl and FME, you should not use the Tcl command: [info exists FME_Attributes(someAttr)] to determine whether or not an attribute exists on a feature. The above command will always return true. Instead, use this idiom to check whether or not a feature has an attribute: set attrIndex [lsearch [array names FME_Attributes] someAttr] then check that attrIndex is not equal to -1. FME_FeatureType Variable ~~~~~~~~~~~~~~~~~~~~~~~~ This global variable is set up to mirror the feature type of the feature. As with the FME_Attributes array, it can be set, read, and unset: set FME_FeatureType "Roadster" puts $FME_FeatureType FME_CoordSys Variable ~~~~~~~~~~~~~~~~~~~~~ This global variable is set up to mirror the coordinate system of the feature. As with the FME_FeatureType variable, it can be set, read, and unset: set FME_CoordSys UTM10-83 puts $FME_CoordSys unset FME_CoordSys FME_AttrEncoding Variable ~~~~~~~~~~~~~~~~~~~~~~~~~ This global variable defines the name of the character encoding in which Tcl assumes a feature's attributes are specified when working with FME_Attributes. As Tcl works internally with UTF-8, this means that it will convert attribute values from the given encoding to UTF-8 when evaluating $FME_Attributes(attrName), and will convert values from UTF-8 to the given encoding when setting FME_Attributes(attrName). The default attribute encoding is the same as the default character encoding of the system on which FME is executing, and might be overridden by Tcl's built-in "encoding system" command. A complete list of supported encodings may be obtained by executing the command "encoding names". The variable may be set, read, or unset: set FME_AttrEncoding iso8859-2 puts $FME_AttrEncoding unset FME_AttrEncoding If FME_AttrEncoding is unset, or is set to be an empty string, it reverts to the default system encoding. FME_AttrNameEncoding Variable ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This global variable defines the name of the character encoding in which Tcl assumes a feature's attributes' names are specified when working with FME_Attributes. As Tcl works internally with UTF-8, this means that it will convert attribute names from UTF-8 to the given encoding system, and use the converted name when referring to the actual feature's attributes. The default attribute encoding is the same as the default character encoding of the system on which FME is executing, and might be overridden by Tcl's built-in "encoding system" command. A complete list of supported encodings may be obtained by executing the command "encoding names". The variable may be set, read, or unset: set FME_AttrNameEncoding iso8859-2 puts $FME_AttrNameEncoding unset FME_AttrNameEncoding If FME_AttrNameEncoding is unset, or is set to be an empty string, it reverts to the default system encoding. FME_Coordinates Function ~~~~~~~~~~~~~~~~~~~~~~~~ In any Tcl procedure invoked by @TCL, the FME_Coordinates function can be used to read and write the coordinates of the feature. It provides several options, as listed below: dimension (2|3) Sets the dimension of the feature - either 2 or 3. numCoords Returns the number of coordinates in the feature. resetCoords Removes all the current coordinates from the feature. Note: Calling resetCoords has no effect on the fme_geometry or fme_type attributes. These must be reset or readjusted explicitly by the script so the feature is not left in an inconsistent state. getCoord (x|y|z) [(true|false)] Returns the coordinate value for the specified axis at the specified - ranges from zero to one less than the number of coordinates. true/false - DEPRECATED addCoord [] Adds the coordinate specified to the end of the feature's geometry. geomType [] Returns the geometry type of the feature - it will be one of the values allowed for the fme_geometry attribute as documented in the FME Architecture chapter of the FME Foundation manual: fme_point fme_line fme_polygon fme_donut fme_aggregate fme_undefined geomType Sets the geometry type of the feature to the passed-in value. No sanity checking is done. It is important that this be done with care since setting an incorrect geometry type can later hinder the FME. FME_LogMessage Function ~~~~~~~~~~~~~~~~~~~~~~~ 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 [ ... ]+ or FME_LogMessage 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_Execute function ~~~~~~~~~~~~~~~~~~~~ This function is used to call any FME function from within a Tcl procedure. This allows standard FME functions to be called iteratively on the same feature. The syntax for FME_Execute is: FME_Execute [ ... ]+ is the name of any FME function, without the leading @ sign. Any remaining arguments are passed to the function. For example, the @Generalize function is invoked like this: FME_Execute Generalize Douglas 10 and this would accomplish the same effect as if @Generalize(Douglas,10) were invoked elsewhere in the mapping file. If the function that is invoked causes the feature to be deleted, the translation will be aborted. The @Generalize function may do this if the feature's total length is less than the tolerance value passed in. FME_StatMessage function (Not externally documented) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The FME_StatMessage function is used to output statistics to the FME log file. FME_StatMessage [ [ []]] =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- 2 2 ============================================================================== 4 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- can be a string or number, if number then it is assumed to be a message number that must exist in a message file. This will be used as the main heading for a given set of items. can be string or number, if number then it is assumed to be a message number that must exist in a message file. This will be used for the summary part of the string can have one of these values: fme_inform, fme_warn, fme_error, fme_fatal, fme_statistic, fme_statusreport. can be a string or number, if number then it is assumed to be a message number that must exist in a message file. This will be used as the sub heading for a given set of items.