Read from Named Range

Operation Name

Function Overview

Read Excel data from a named range.

Data Model

Table model type.

Properties

For details on use of variables, refer to “Variables”.

Basic settings

Item name	Required/Optional	Use of variables	Description	Remarks
Name	Required	Not available	Enter the name to show on the script canvas.

Required settings

Item name	Required/Optional	Use of variables	Description	Remarks
File	Required	Available	Enter the Excel file path. You can click [Browse] button to launch file chooser and find the file.	A file with ".xlsx" or ".xlsm" extension is processed as an Excel workbook, and a file with other extension is processed as an Excel 2003 workbook. Specify the file path as an absolute path of DataSpider File System. Except for the path separator “/”, restricted characters of DataSpider File System cannot be used.
Range name	Required	Available	Select or enter the named range of the Excel file specified in [File].	Case-sensitive.
Column list	Optional	-	Specify columns. Each column can be operated with the following buttons. [Add]: Add a column. [Up]: Move the selected column upwards by one row. [Down]: Move the selected column downwards by one row. [Delete]: Delete the column.	Column names set in [Column list] will be displayed in Mapper schema.
Column list/Column name	Required	Available	Enter the column name. The first row of the file specified in [File] can be set as column names using [Update column list] property action.
Column list/Type	Required	Not available	Select the type of [Column name]. [General]: (default) [Text]: [Number]: [Date]:

Property actions

Item name	Description	Remarks
Update column list	Get column names and types from the first row values of the file specified in [File] and set them in [Column list].	Disabled when the specified file does not exist or a variable is set in [File]. When the value of a cell is empty, a type different from the cell's one might be set to [Column list/Type].

Read settings

Item name	Required/Optional	Use of variables	Description	Remarks
Do not get first row as value	Optional	Not available	Select whether or not to handle the first row of the specified file as data. [Checked]: Do not handle as data. [Not checked]: (default) Handle as data.
Read cell formula	Optional	Not available	Select whether or not to read cell formula as data. [Checked]: Read formula as data. [Not checked]: (default) Do not read formula as data.	Disabled when an Excel workbook is specified in [File].

Data processing method

Item name	Required/Optional	Use of variables	Description	Remarks
Data processing method	Required	Not available	Select data processing method. [Apply script settings]: (default) Apply the mass data processing settings of the script property to the adapter. [Do not perform mass data processing]: Mass data processing will not be performed. [Perform mass data processing]: Mass data processing will be performed.

Comment

Item name	Required/Optional	Use of variables	Description	Remarks
Comment	Optional	Not available	You can write a short description of this adapter. The description will be reflected in the specifications.

Schema

Input schema

None.

Output schema

The number of columns varies depending on the [Column list] settings.

Refer to “Schema of table model type” for more details.

Loading schema in Mapper

Schema is loaded automatically.

Refer to “Edit Schema” for more details.

Mass Data Processing

Mass Data Processing is supported.

When the file specified in [File] is an Excel workbook, mass data processing cannot be performed.

PSP Usage

PSP is supported.

Refer to “Parallel Stream Processing” for more details.

Available Component Variables

Component variable name	Description	Remarks
count	The number of read data is stored.	Default value is null. Value is not stored in PSP.
filePath	The file path is stored.	Default value is null. Value is not stored in PSP.
message_category	When an error occurs, the corresponding message code's category is stored.	Default value is null.
message_code	When an error occurs, the corresponding message code is stored.	Default value is null.
message_level	When an error occurs, the corresponding message code's severity is stored.	Default value is null.
error_type	When an error occurs, the error type is stored.	Default value is null. The error type will be in the following format. Example: “java.io.FileNotFoundException” The contents that will be stored may vary depending on DataSpider Servista versions.
error_message	When an error occurs, the error message is stored.	Default value is null. The contents that will be stored may vary depending on DataSpider Servista versions.
error_trace	When an error occurs, the error's trace information is stored.	Default value is null. The contents that will be stored may vary depending on DataSpider Servista versions and client applications.

Null and Empty Strings

When the target cell value is empty, the read data will be null.

Specification Limits

Reading values of cells with formulas

The result value of a formula in a cell whose format is "Number" will be read up to the number of decimal places set in the format in range within the limit of 15 significant digits as Excel specifications.

Digits that exceed the significant digits will be rounded off.
Digits under the specified number of decimal places will be rounded off.

Example:

Result value of formula (Number of decimal places)	Read value	Read method
1234567890123456.123 (2 digits)	1234567890123460	Round off the digits that exceed the number of significant digits
1234567890.1234567 (10 digits)	1234567890.12346	Round off the digits that exceed the number of significant digits
12345.123 (2 digits)	12345.12	Round off the digits that exceed the specified number of decimal places

The result value of a formula in a cell whose format is "General" will be read up to 9 decimal places in range within the limit of 15 significant digits as Excel specifications.

Digits that exceed the significant digits will be rounded off.
A value whose integer part is not 0 will be rounded off to 9 decimal places.
For a value whose integer part is 0, the 9 digits from the first non-zero digit will be counted as significant digits, and the 10th digit will be rounded off.

Example:

Result value of formula	Read value	Read method
1234567890123456.123	1234567890123460	Round off the digits that exceed the number of significant digits
1234567890.1234567	1234567890.12346	Round off the digits that exceed the number of significant digits
1.12345678944	1.123456789	Round off the decimal places to 9 digits.
0.0001234567894444	0.000123456789	The 9 digits from the first non-zero digit will be counted as significant digits, and the value will be rounded off to 9 decimal places

Date
- The oldest date that can be handled as date is 1900/01/01.
- The latest date that can be handled as date is 9999/12/31.
- Date type data will be read according to the cell format as follows.
  - If date is alone set as format, only date will be read. The data will be output in yyyy-MM-dd, the format of ISO8601 without timezone.
  - If time is set in addition to date as format, date and time will be read. The data will be output in date-time (yyyy-MM-dd HH:mm:ss) format, similar to ISO8601 without timezone.
For the following settings, reading is not supported.
- Settings of rows and columns / phonetic guides / comments / newlines / graphs / clip arts / shapes / pictures / macros / attachments / hyperlinks
- Cell formats other than General / Number / Date / Text (Custom format, etc.)
Named range set with multiple ranges
- When multiple ranges are set for one named range, only the range that initially appeared will be read.
Print area (Print_Area)
- When print area (Print_Area) is defined in multiple sheets, you will get the print range of the last sheet in the workbook.
File encrypted with a password
- You cannot read data from an Excel file that is encrypted with a password.
[Read cell formula]
- You cannot read formulas from an Excel workbook.
Handling large Excel files
- When a large Excel file is specified in [File], OutOfMemoryError may occur, or it might take some time to analyze the file contents and operations in the screen may be delayed.
  In that case, you can prevent this issue by specifying a variable such as script variable in [File].

Major Exceptions

Exception name	Cause	Solution
InvalidPropertyConfigurationException <property name> is not specified.	[<property name>] is not specified.	Specify [<property name>].
FileIsDirectoryException	The path entered in [File] is directory.	Enter a file path in [File].
NoDefinitionAreaException	[Range name] is not specified or does not exist.	Check [Range name].
java.io.FileNotFoundException	The file specified in [File] does not exist.	Check [File].
jxl.read.biff.PasswordException	Password to open is set in the Excel 2003 workbook specified in [File].	Enter an Excel 2003 workbook in which a password to open is not set in [File].
jxl.read.biff.BiffException Unable to recognize OLE stream	The Excel 2003 workbook specified in [File] is in an invalid state.	Check the following. Whether the file specified in [File] is an Excel 2003 workbook included in Supported Versions Whether a file that is not Excel 2003 workbook is specified with ".xls" extension in [File] Whether the file is corrupted
jxl.read.biff.BiffException The file format is corrupt	The Excel 2003 workbook specified in [File] might be corrupted.	Check the following. Check whether the file specified in [File] is corrupted.
ZipEntryBrokenException: The entry of the operating ZIP file is broken.	The Excel workbook specified in [File] is in an invalid state.	Check the following. Whether the file specified in [File] is an Excel workbook Whether a file that is not Excel workbook is specified with ".xlsx" / ".xlsm" extension in [File] Whether the file is corrupted
ZipEntryNotFoundException: Entry of the specified name does not exist in the zip file	The Excel workbook specified in [File] is protected with password to open or is in an invalid state.	Check whether password to open is set to the Excel workbook specified in [File], and whether the file is corrupted.