FME Readers and Writers 2013 SP2 - Safe Softwaredocs.safe.com/fme/2013sp3/pdf/reader_writer_pdf/xlsx.pdf · MicrosoftExcel(XLSX)Reader/Writer Name Type Width Precision Theattribute

FME Readers and Writers 2013 SP2

Microsoft Excel (XLSX) Reader/Writer

Note: Licensing options for this format begin with FME Professional Edition.

The Microsoft Excel reader and writer modules provide FME with access to attributedata held in Microsoft Excel spreadsheets, also known as workbooks.

Several types of Excel files are supported including older .xls files, newer .xlsx files,as well as metadata .xlsm files. This module can only process a single file type at atime.

Overview

FME provides read and write access to Microsoft Excel spreadsheets. Excelspreadsheets may contain multiple worksheets and each worksheet may optionallycontain specifically named cell ranges called Named Ranges. FME treats worksheetsand named ranges as feature types and can read cell data and write cell data andformatting information to them. FME treats each column in a worksheet or namedrange as an attribute and each row as a feature.

Usage Notes

l This format supports formulas.

l Formatting (font, background colors, etc.) are supported on the writer only, andso will not be preserved from the reader to the writer. Formatting in a templatefile will be preserved but will not be used in modifications to it.

l This data may not necessarily have a spatial component to it but columns can beidentified as x,y, or z coordinates to create point geometries.

l FME currently does not support Pivot tables, charts, or graphs.

l The Microsoft Excel writer allows the specification of a template file to use as astarting point for creating a new dataset. If a template file name is specified, thewriter will make a copy of the template file in the location specified in theDATASET parameter. All write operations will be performed on the copy. Thetemplate file specified remains unchanged. This is particularly useful whenpopulating an area of the template with data such as an existing chart, graph orpivot table or when creating many spreadsheets from a single template. If thedestination dataset already exists, and a template file is specified, the destinationdataset will always be overwritten.

Terminology in this Chapter

l An Excel spreadsheet and an Excel workbook are synonymous.

l A worksheet is defined to be either a worksheet or a named range.

l An attribute is defined to be a column.

- 2503 -


l A feature is defined to be a row.

l A feature type is the FME representation of either a sheet or a named range.

Microsoft Excel (XLSX) Quick Facts

About Quick Facts Tables

Format Type Identifier XLSX

Reader/Writer Both

Licensing Level Professional

Dependencies None

Dataset Type File

Feature Type Worksheet Name or Named Range

Typical File Extensions .xlsx, .xlsm, .xls

Automated Translation Support Yes

User-Defined Attributes Yes

Coordinate System Support No

Generic Color Support No

Spatial Index Never

Schema Required Yes

Transaction Support No

Encoding Support Yes

Geometry Type xlsx_none

Geometry Support

Geometry Supported? Geometry Supported?

aggregate no point read-only

circles no polygon no

circular arc no raster no

donut polygon no solid no

elliptical arc no surface no

ellipses no text no

line no z values n/a

none yes

- 2504 -


Reader Overview

The XLSX reader supports reading multiple worksheets and named ranges from thesame file. Because of this, multiple files are not supported, so you will need to create aseparate reader for each Microsoft Excel spreadsheet.

The tables must be defined in the workspace before they can be read. In MicrosoftExcel, tables can be either worksheets or named ranges. FME always signifies namedranges using the notation <sheetName>/<namedRangeName>.

The Reader parameters dialog allows you to flag columns as one of [x_coordinate|y_coordinate|z_coordinate]. If both an x_coordinate and a y_coordinate attributeexist, features will be returned with Point geometries (when the values of thoseattributes are numbers). Z coordinates will be added to the points when they exist.

Mircosoft Excel Workbench Reader Parameters

Microsoft Excel Reader Parameters

Each dataset must be defined before it can be read. The definition contains theworksheet/named range name, followed by the names and types of the attributes.

The schema is determined either through choices in the workspace, or by scanning xfeatures of the feature type, where x is defined by

the Max Features to Read parameter in the Workbench Navigator (scan_max_features). The schema is only useful for defining the schema which may be useful forwriters, but it is ignored on read.

Therefore, features beyond the Max Features to Readmight return values that do NOTcomply with the schema. (If this is an issue, you can re-add a reader with a largervalue for Max Features to Read or manually edit the attribute types in the Attributessection of the parameters dialog).

View the Attribute Types

Field Type Description

char(<width>) Character fields store fixed length strings. The widthparameter controls the maximum number ofcharacters that can be stored by the field. No paddingis required for strings shorter than this width.

Notes:

Strings encountered that have length greater thanwidth will still be returned; they will not betruncated.

The width parameter is only valuable if the featureswill be passed to another format that requires thisinformation.

date Date fields store date as character string with the

- 2505 -



format

YYYYMMDDHHmmSS.mmm

(Year, Month, Day, Hour, Minute, Second,Milliseconds)

number(<width>,<decimals>)

Number fields store single and double precisionfloating point values. The width parameter is thetotal number of characters allocated to the field,including the decimal point. The decimals parametercontrols the precision of the data and is the numberof digits to the right of the decimal.

Notes:

Incoming numbers of greater width or precision willstill be returned and will not be modified to fit.Numbers will also not be padded to fit the specifieddecimal value.

The width and decimal parameters are only valuableif the features will be passed to another format thatrequires this information.

string String fields store variable length character data upto a length of 32767 characters. Values larger than32767 are truncated.

number Number fields store single and double precisionfloating point values.

x_coordinate

y_coordinate

z_coordinate

Coordinate fields store double precision floating pointvalues. There is no ability to specify the precisionand width of the field. If an x and a y coordinate arespecified on a feature type on read, features will usethem to try to create Point geometries.

boolean Bool fields store TRUE/FALSE data. Data read orwritten from and to such fields must always have avalue of either true or false.

FME represents Booleans as Yes and No for TRUE andFALSE respectively, so any logging within FME willreflect this. Round tripped values will be written asTRUE/FALSE as expected.

Sheets to Read

This area shows all of the sheets and named ranges in the Excel file. A named range isof the form sheetName/NamedRangeName.

- 2506 -


In this example, the selected area is a named range: the name of the named range isSecond_Table, and it is on the sheet NoSheetInfo.

The column Field Names Row allows you to select which row contains the headernames, and the column Cell Range allows you to restrict the information to read.

Preview

This area shows a preview of the data (100 rows) of the selected feature type (eitherfeature or named range). As shown in the example here, if you choose a header row,that row will be shown in boldface text.

Attributes

This area displays the attributes that were created for the feature type (schemascanned).

- 2507 -


Name Type Width Precision

The attributename that will beplaced onresultingfeatures.

The attribute type islisted in this column.You can change theattribute type byclicking on the fieldand selecting fromthe drop-down list.

This only affects theresulting features ifthere is an x_coordinate and ay_coordinate.

Controls themaximum numberof characters thatcan be stored bythe field. Nopadding is requiredfor strings shorterthan this width.

When scanning anumeric column, thiscolumn lists thelargest number ofdecimals found.

Filter

Filter a list of attributes by typing a key sequence into this field.

Read Formulas (.formula)

If this parameter is enabled, an <attrName>.formula attribute will be added to theworkspace for columns that contain a formula.

Writer Overview

The Microsoft Excel writer writes attribute records into a spreadsheet. The writerprovides the following capabilities:

Table Creation: The Microsoft Excel writer uses the information within the FMEworkspace (mapping file) to automatically create worksheets and named ranges asrequired. All worksheets and named ranges will be created with when the first inputfeature is processed. If no features are sent to a feature type, then the correspondingworksheet or named range will not be created. However, creating an empty worksheetor named range is still possible by sending a feature with no attributes to thecorresponding feature type.

- 2508 -


Multiple Worksheets and/or Named Ranges: One writer can have multipleworksheets and/or named ranges created in a new or existing spreadsheet, includingmultiple named ranges on a single sheet.

Writer Mode Specification: The Microsoft Excel writer allows you to specify what todo with incoming features.

l Insert_New_Rows causes them to be appended to the end of the sheet or writtento an exact row and column position. This mode also inserts a new row at thelocation specified, so if the row position has data following it, that data will beshifted down rather than overwritten.

l Insert_Overwriting_Cell_Contents causes them to be appended to the end of thesheet or written to an exact row and column position. Any data that already existsat that location will be overwritten.

l Update_Cell_Contents causes the row corresponding to the feature’s valuespecified in the xlsx_row_id_column to have its data changed to the values onthe incoming feature.

l Delete_Cell_Contents deletes the values in the row corresponding to that value.Only a number of columns equal to the amount of columns in a schema will beblanked out.

l Delete_Entire_Rows deletes the entire row corresponding to that value. Writermode can be specified at three levels: the writer level which sets the startingvalue for each of the feature types, feature type level, or on individual features.Any data following the deleted row will be shifted up.

Writer mode can be specified at three levels: the writer level that sets the startingvalue for each of the feature types, the feature type level, or on individual features.

Note: The individual feature writer mode only works when the feature type writermode is NOT set to Insert_New_Rows or Delete_Entire_Rows.

Microsoft Excel Workbench Writer Parameters

Microsoft Excel Writer Parameters

Writer Parameters

Overwrite Existing File

By default, this option is set to No, which means that features will be written to theoriginal file. Select Yes to delete an existing file before writing out any features.

Template File

If you specify a template file, the writer will make a copy of the template file in thelocation specified in the Destination Microsoft Excel File parameter. All operations willbe performed on the copy: the template file specified remains unchanged. When atemplate file is used, the destination file will always be overwritten, regardless of whatis chosen for the Overwrite Existing File parameter.

- 2509 -


Sheet/Named Range Parameters

One writer can have multiple worksheets and/or named ranges created in a new orexisting spreadsheet, including multiple named ranges on a single sheet.

Drop Existing Sheets/Named Ranges

The worksheet or named range will be deleted prior to writing.

Truncate Existing Sheets/Named Ranges

All data will be deleted (formatting will remain).

Note: Note that worksheet names must be less than 31 characters in length.

Output Field Names

This parameter specifies whether or not to write the headers of the attributes. Thisparameter has an effect only if the sheet is being created (which happens when it isnew or if it is being dropped).

Writer Mode

The MS Excel writer allows you to specify a writer mode, which determines how eachfeature received is treated. Valid writer modes are listed below:

Mode Description

Insert_New_Rows Appends features to the end of the sheet or writes them toan exact row and column position. This mode also inserts anew row at the location specified, so if the row position hasdata following it, that data will be shifted down rather thanoverwritten.

Note: Note: Individual feature writer mode specificationswill be ignored when the feature type is in this writermode.

Insert_Overwriting_Cell_Contents

Appends features to the end of the sheet or writes them toan exact row and column position. Any data that alreadyexists at that location will be overwritten.

Update_Cell_Contents Causes the row corresponding to the feature’s valuespecified in the xlsx_row_id_column to have its datachanged to the values on the incoming feature.

Delete_Cell_Contents Deletes the entire row corresponding to the feature’s valuespecified in the xlsx_row_id_column. Any data followingthe deleted row will be shifted up.

Note: Note: Individual feature writer mode specificationswill be ignored when the feature type is in this writermode.

- 2510 -


Mode Description

Delete_Entire_Rows Deletes the values in the row corresponding to the feature’svalue specified in the xlsx_row_id_column. Only a numberof columns equal to amount of columns in the schema willget blanked out.

For additional information, please see Writer Mode Specification.

Writer Mode Specification

The MS Excel writer allows the user to specify a writer mode, which determines theoperation to perform for each feature received. Valid writer modes areare Insert_New_Rows, Insert_Overwriting_Cell_Contents, Update_Cell_Contents, Delete_Cell_Contents, and Delete_Entire_Rows.

Writer Modes

In Insert_New_Rows mode, the attribute values of each received feature are written ina newly created row, inserted at the next row location.

In Insert_Overwriting_Cell_Contents mode, the attribute values of each receivedfeature are written at the next row in the sheet, overwriting any data that might existat that location.

In Update_Cell_Contents mode, the attribute values of each received feature are usedto update existing rows in the worksheet. The rows that are updated are determinedvia the xlsx_row_id_column DEF line parameter.

In Delete_Cell_Contents mode, the attribute values of each received feature are usedto blank out cell values corresponding to the amount of attributes in the schema. Therows that are changed are determined via the xlsx_row_id_column DEF lineparameter.

In Delete_Entire_Rows mode, the attribute values of each received feature are used toremove entire rows. The rows that are changed are determined via the xlsx_row_id_column DEF line parameter.

Writer Mode Constraints

In UPDATE1 and DELETE2 modes, the writer looks for the xlsx_row_id_column DEFline parameter and uses it to determine which records should be affected by thecommand. Please refer to the DEF section for more information about the xlsx_row_id_column DEF line parameter.

Writer Mode Selection

The writer mode can be specified at two unique levels: on the feature type, or onindividual features.

1maps to Update_Cell_Contents2maps to Delete_Cell_Contents

- 2511 -


At the writer level, the writer mode specified by the WRITER_MODE directive is inheritedas the starting writing mode by all of its feature types.

At the feature type level, the writer mode is specified by the xlsx_writer_mode DEFline parameter. It may be superseded on individual features by the fme_db_operationattribute. Please refer to the DEF line documentation for more information about thisparameter.

At the feature level, the writer mode is specified by the fme_db_operation attribute.The writer mode specified by this attribute always supersedes all other values.Accepted values for the fme_db_operation attribute are INSERT, UPDATE and DELETE.These values map to Insert_Overwriting_Cell_Contents, Update_Cell_Contents, andDelete_Cell_Contents, respectively.

Note: Please note that feature level specification will not be used if the feature typeWRITER_MODE directive is set to Insert_New_Rows or Delete_Entire_Rows.

Format Mapping File Directives

Note: FME translations were originally based entirely on Mapping Files. Mappingfiles still exist under the surface but the interface has been almost entirely replacedby Workbench's graphical interface. Information on mapping files is included in thismanual for technical reference purposes.

Mapping Files are ASCII text files that contain a series of rules that specify the FMEreaders, writers, and transformations (in Workbench, these are represented bytransformers).

A mapping file (.fme) is a series of commands for FME to perform. Mapping files usefunctions and factories to transform the data. They also contain the definition andparameters for the readers and writers. A mapping file can be run through the FMEQuick Translator. Before FME Workbench was designed and developed (about 2001),this was the only way to configure a translation process.

You can create a mapping file either by manually programming it or by using FMEWorkbench. In Workbench, there is still an Export as .fme tool on the toolbar. TheWorkbench file format itself (.fmw file) is partially a mapping file with an XML header.When FME runs a workspace it is converted into a mapping file.

Since mapping files are written in a plain ASCII format, so you can use any text editorto edit them. To see what a mapping file looks like: select one or more transformers inWorkbench, copy them, and then paste them in a text editor. The mapping fileequivalent of those transformers will be pasted.

Directives and Reader/Writer Keywords

Directives are processed by the reader or writer. Directives are prefixed by thecurrent <ReaderKeyword> or <WriterKeyword> in a mapping file. By default, the

- 2512 -


keywords for formats are the format shortname (viewable in the Formats Gallery, orin the Format Quick Facts tables.

Reader Directives

The suffixes listed are prefixed by the current <ReaderKeyword> in a mapping file. Bydefault, the <ReaderKeyword> for the MS Excel reader is XLSX.

These directives are exposed in Workbench as format settings through the ReaderParameters.

DATASET

Required/Optional: Required

This is the file name of the Microsoft Excel workbook.

Example:

XLSX_DATASET C:/data/citySource.xls

Workbench Parameter: Source Microsoft Excel File(s)

DEF


Each dataset must be defined before it can be read. The definition contains theworksheet/named range name, followed by the names and types of the attributes.

The schema is determined either through choices in the workspace, or by scanning xfeatures of the feature type, where x is defined by scan_max_features. The schema isonly useful for defining the schema which may be useful for writers, but it is ignoredon read. Therefore, features beyond the scan_max_features might return valuesTHAT do not comply with the schema. (If this is an issue, you can re-add a reader witha larger value for scan_max_features or manually edit the attribute types in theworkspace).

The syntax of an XLSX DEF line is:

XLSX_DEF <baseName> \[<attrName> <attrType>]+

The following table shows the attribute types supported:


char(<width>) Character fields store fixed length strings. The widthparameter controls the maximum number ofcharacters that can be stored by the field. No paddingis required for strings shorter than this width.

Notes:

Strings encountered that have length greater thanwidth will still be returned; they will not be

- 2513 -



truncated.

The width parameter is only valuable if the featureswill be passed to another format that requires thisinformation.

date Date fields store date as character string with theformat

YYYYMMDDHHmmSS.mmm

(Year, Month, Day, Hour, Minute, Second,Milliseconds)

number(<width>,<decimals>)

Number fields store single and double precisionfloating point values. The width parameter is thetotal number of characters allocated to the field,including the decimal point. The decimals parametercontrols the precision of the data and is the numberof digits to the right of the decimal.

Note:

l Incoming numbers of greater width or precisionwill still be returned and will not be modified to fit.

l Numbers will not be padded to fit the specifieddecimal value.

l The width and decimal parameters are onlyvaluable if the features will be passed to anotherformat that requires this information.

string String fields store variable length character data upto a length of 32767 characters. Values larger than32767 are truncated.

number Number fields store single and double precisionfloating point values.

x_coordinate

y_coordinate

z_coordinate

Coordinate fields store double precision floating pointvalues. There is no ability to specify the precisionand width of the field.

If an x and a y coordinate are specified on a featuretype on read, features will use them to try to createPoint geometries.

boolean Bool fields store TRUE/FALSE data. Data read orwritten from and to such fields must always have avalue of either true or false.

Note: FME represents Booleans as ‘Yes’ and ‘No’ for

- 2514 -



TRUE and FALSE respectively, so any logging withinFME will reflect this. Round tripped values will bewritten as TRUE/FALSE as expected

IDs

Required/Optional: Optional

This optional specification is used to limit the available and defined database tablesthat will be read. If no IDs are specified, then all worksheets and named ranges areread.

XLSX_IDs <featureType1> \<featureType2> … \<featureTypeN>

The feature types must match those used in DEF lines.

Note that named ranges will be prepended by the worksheet name they exist on and aforward slash. For example, <sheet1>/<myNamedRange>.

The example below selects only the HISTORY worksheet for input during a translation:

XLSX_IDs HISTORY

Workbench Parameter: Feature Types to Read

OUTPUT_FORMULAS


This directive controls whether the reader will attempt to read formulas from thesheet. It is also used to determine the schema.

If OUTPUT_FORMULAS is set to yes, and a formula is found, it will be added to thefeature as <attrName>.formula.

If OUTPUT_FORMULAS is set to no, formulas will not be read.

Default: NO

Values: <yes | no>

OUTPUT_COMMENTS


This directive controls whether the reader will attempt to read comments from thesheet. It is also used to determine the schema.

If OUTPUT_COMMENTS is set to yes, and a comment is found, it will be added to thefeature as <attrName>.comment.

If OUTPUT_COMMENTS is set to no, then comments will not be read.

Default: NO

- 2515 -


Values: <yes | no>

Note: Note: This option currently works for .xls files only.

Required/Optional

Optional

START_ROW


This directive can be used to specify a start row to begin reading from or to read theschema from. Use this to skip rows in a worksheet, such as headers. This directive canbe overruled at the feature type level. The row indices start at 1.

Values: <number>

END_ROW


This directive can be used to specify the last row to read from or to read the schemafrom. Use it to cut off the features and prevent it from reading foot notes or additionalworksheets that may be on the sheet. This directive can be overruled at the featuretype level. The row indices start at 1.

Values: <number>

START_COL


This directive can be used to specify a start column to begin reading from or to readthe schema from. Use this to skip attributes in a worksheet. The column indices startat 1.

Values: <number>

END_COL


This directive can be used to specify an end column for the read or read schema calls.The column indices start at 1.

Values: <number>

_SCHEMA


This field is used by the GUI to force the reader to a schema. It specifies the featuretypes, their attributes and attribute types, and the range to read.

SCAN_MAX_FEATURES


- 2516 -


This field can be used to indicate the maximum number of rows to scan to obtainattribute types in the resultant source feature type. This does not affect the preview inthe reader parameters which always scans a fixed amount of rows.

If set to a value of 0, the entire file will be read to determine the schema.

Values: <number of lines>

Default: 10000

Workbench Parameter: Maximum Lines to Scan (0 for no limit)

RETRIEVE_ALL_SCHEMAS


This specification is only applicable when generating a mapping file, generating aworkspace or when retrieving schemas in an FME Objects application.

When set to YES, tells the reader to return all the schemas of the tables in thedatabase.

If this specification is missing, it is assumed to be NO.

Values: <yes | no>

Default: NO

RETRIEVE_ALL_TABLE_NAMES


This specification is only applicable when generating a mapping file, generating aworkspace, or when retrieving schemas in an FME Objects application.

This directive is similar to RETRIEVE_ALL_SCHEMAS except when set to YES.

When set to YES, this directive tells the reader to only return the names of all of thetables in the database. However, if RETRIEVE_ALL_SCHEMAS is also set to YES, thenRETRIEVE_ALL_SCHEMAS takes precedence.

If this specification is missing, it is assumed to be NO.

Values: <yes | no>

Default: NO

EXPOSED_ATTRS

This directive allows the selection of format attributes to be explicitly added to thereader feature type.

This is similar to exposing format attributes on a reader feature type once it has beengenerated; however, it is even more powerful because it enables schema-drivenapplications other than Workbench to access and leverage these attributes as if theywere explicitly on the schema as user attributes.

- 2517 -


The result of picking a list of attributes is a comma-separated list of attribute namesand types that will be added to the schema features. Currently all reader feature typeswill receive the same set of additional schema attributes for a given instance of thereader.

Required/Optional

Optional

Mapping File Syntax

Not applicable. While it is possible for FME Objects applications to invoke thisdirective, the required format is not documented. This directive is intended for use inour GUI applications (for example, Workbench) only.

Workbench Parameter

Additional Attributes to Expose

Writer Directives

The directives processed by the Microsoft Excel writer are listed below. The suffixesshown are prefixed by the current <WriterKeyword> in a mapping file. By default, the<WriterKeyword> for the Microsoft Excel writer is XLSX.

These directives are exposed in Workbench as format settings through the WriterParameters.

DATASET


This is the name of the destination file.

For example:

XLSX_DATASET C:/data/states.xlsx

Workbench Parameter: Destination Microsoft Excel File

DEF


Each MS Excel table must be defined before it can be written. The general form of aMicrosoft Excel definition statement is:

XLSX <worksheetName> \[xlsx_drop_sheet (yes|no]] \[xlsx_trunc_sheet (yes|no)] \[xlsx_row_id_column <keyColumn>] \

[xlsx_table_writer_mode (Insert_New_Rows|Insert_Overwriting_Cell_Contents|

Update_Cell_Contents|Delete_Cell_Contents|Delete_Entire_Rows)] \[xlsx_field_names_out (yes|no)] \[xlsx_start_col <startCol>] \

- 2518 -


[xlsx_start_row <startRow>] \[xlsx_offset_col <offsetCol>] \[xlsx_offset_row <offsetRow>] \

[<fieldName> <fieldType(attributeStyle)>] +

The table definition allows control of the table that will be created. <fieldType> willbe used for worksheet creation, but will subsequently be ignored when writing valuesto the sheet. Fields that can contain NULL values do not need to be listed: these fieldswill be filled with NULL values.

The configuration parameters present on the definition line are described in thefollowing table:

Field Type Contents

worksheetName The name of the worksheet to be written. Namedranges can be specified by usage of a slash character(/); for example:

<sheetName>/<namedRangeName>

If xlsx_drop_sheet is set to YES, the worksheet ornamed range will be deleted prior to writing. If xlsx_trunc_sheet is set to YES then all the data will bedeleted (formatting will remain). Worksheet namesmust be less than 31 characters in length.

xlsx_table_writer_mode The default writer mode for the feature types beingwritten. Valid values are Insert_New_Rows, Insert_Overwriting_Cell_Contents, Update_Cell_Contents,Delete_Cell_Contents, and Delete_Entire_Rows.

Note that Insert_New_Rows and Delete_Entire_Rowsmodes cannot be overwritten at the feature levels.

The writer-level choice provides the initial value toall the feature type choices.

Default: Insert_New_Rows

xlsx_row_id_column This is the attribute whose value specifies which rowis to be updated or delete when the writer mode isUpdate_Cell_Contents, Delete_Cell_Contents, orDelete_Entire_Rows.

This attribute will not be written out. For example:xlsx_row_id_column ID would instruct the writer tomodify the row pointed to by the FME attribute ID.Row indices should be specified, starting from 1.

xlsx_field_names_out Specifies whether or not to write the headers of theattributes. This directive only matters if the sheet is

- 2519 -


Field Type Contents

being created (which happens when it is new or beingdropped).

fieldName The name of the field to be written. Valid values forfield name include any character string devoid ofinvalid SQL characters and less than 255 charactersin length.

fieldType Excel is not actually a database, so columns are notstrictly typed. Therefore, for the schema, FMEprovides only very generic types (string, date,number and bool). However, Excel does allow forformatting, which is captured in the attribute typeparameter.

There are two types of formatting:

Simple, where GUIs help select the font, font color,and fill color OR

Custom, where a custom format string must becreated.

The custom format string can be created using therules at the following link:

http://office.microsoft.com/en-ca/help/number-date-and-time-format-codes-HP005207595.aspx?CTT=5&origin=HP005227090

Please note that if you are creating a worksheet, thisformat will be applied to the entire column. If youare writing to an existing worksheet, or writing anamed range, then only those cells you write willhave this format. This means that column width isignored for any case except a brand new worksheet.

xlsx_start_row A numeric value that tells FME which row to create anamed range at (ignored for worksheets). Rowindices should be specified starting from 1.

xlsx_start_col A numeric value which tells FME which column tocreate the named range at (ignored for worksheets).

Column indices should be specified starting from 1.

xlsx_offset_row The start row (relative to the start of the worksheetor named range) to begin writing data.

For sheets, this is from the beginning of the sheet, soa value of 1 for a sheet would write at the very top of

- 2520 -

http://office.microsoft.com/en-ca/help/number-date-and-time-format-codes-HP005207595.aspx?CTT=5&origin=HP005227090


Field Type Contents

the sheet. For a named range, this is relative to thefirst row of the named range, so a value of 2 for anamed range beginning at row 4 would start writingat row 5.

Column indices should be specified starting from 1.

xlsx_offset_col This is the same concept as the xlsx_offset_row,but applied to columns instead of rows. See xlsx_offset_row for how this is affected by writing aworksheet versus a named range.

WRITER_MODE


This directive informs the Microsoft Excel writer which write operations will beperformed by default by this writer. This operation can be set to to Insert_New_Rows,Insert_Overwriting_Cell_Contents, Delete_Entire_Rows, Delete_Cell_Contents, orUpdate_Cell_Contents. The writer-level value chosen in the settings box gets passed tothe feature types (or worksheet) level. The corresponding feature type DEF parametername is called xlsx_table_writer_mode. It has the same valid options as the writerlevel mode.

The operation can be set specifically for individual feature as well when the the featuretype writer mode is not Insert_New_Rows or Delete_Entire_Rows.

If the XLSX_WRITER_MODE statement is not specified, then a value of Insert_New_Rowsis given.

Field Type Contents

<writer_mode> The type of operation that should be performed bythe writer. The valid list of values is below:

Insert_New_Rows

Insert_Overwriting_Cell_Contents

Update_Cell_Contents

Delete_Cell_Contents

Delete_Entire_Rows

Example:

XLSX_WRITER_MODE Insert_New_Rows

Workbench Parameter: Writer Mode

OVERWRITE_FILE

If set to YES, deletes the existing Excel spreadsheet file before writing.

- 2521 -



Workbench Parameter: Overwrite Existing File

TEMPLATEFILE

If specified will make a copy of the template file in the location specified in theDATASET parameter. All operations will be performed on the copy. The template filespecified remains unchanged.


Workbench Parameter: Template File

Feature Representation

Features read from an Excel spreadsheet consist of a series of attribute values. Bydefault, there is no geometry produced but points can be created by identifying x,y andoptionally z coordinate types for particular columns.

The attribute names are as defined in the workspace. If attribute names are notdefined, then default attribute names will be created which correspond to the columnindex. Features being returned may not respect their schema attribute types.

In addition, if the Read Formulas (.formula) parameter (OUTPUT_FORMULAS readerdirective) has been selected, then an <attrName>.formula attribute may also beadded.

Features written to the database have the destination table as their feature type, andattributes as defined on the DEF line.

In addition to the generic FME feature attributes that FME Workbench adds to allfeatures (see About Feature Attributes), this format adds the format-specific attributesdescribed in this section.

Attribute Name Contents

xlsx_type The type of geometric entity stored withinthe feature. The valid values are:

XLSX_NONE

XLSX_POINT

XLSX_NONE

Features with no coordinates are tagged with this value when reading from MicrosoftExcel.

XLSX_POINT

Features with valid x and y coordinates have a Point geometry added and are taggedwith this value. There is no support for multi-points or point collections in XLSX. Pointscan have a z-coordinate if one is specified as well in the schema.

- 2522 -


Note: Note: Geometry will be created only on the reader, and only if both an x_coordinate and a y_coordinate attribute exists. Geometry on features entering thewriter will be dropped.

Troubleshooting

There are some common problems that can occur when reading or writing a MicrosoftExcel file.

l Ensure the desired Microsoft Excel file is not open in Excel.

l Ensure the Microsoft Excel file is not password protected. This module does notcurrently support password-protected files.

- 2523 -

Documents

FME Readers and Writers 2013 SP2 - Safe Softwaredocs.safe.com/fme/2013sp3/pdf/reader_writer_pdf/xlsx.pdf · MicrosoftExcel(XLSX)Reader/Writer Name Type Width Precision Theattribute