Script wrapper nickname options

You can specify options when you create a nickname for a script. Only the root nickname can include input columns.

Nickname options

The following list describes the nickname options:

DATASOURCE: The name of the script that will be invoked. The script must be listed in the script daemon configuration file. This option is required for data sources in the parent nickname. This option applies only to the root nickname.
NAMESPACES: A comma-separated list of name=value pairs that the wrapper uses to resolve namespace prefixes in the nickname XPath expression.
TIMEOUT: The maximum time, in minutes, that the script wrapper waits for results from the script daemon. The default value is 60 minutes. This option applies only to the root nickname.
VALIDATE: Specifies whether the XML source document must be validated before the XML data is extracted. If this option is set to YES, the DB2® database system verifies that the structure of the source document conforms to an XML schema or to a document type definition (DTD). This option is accepted only for columns of the root nickname (the nickname that identifies the elements at the top level of the XML document). The default value is NO.; The XML source document is not validated if the script wrapper cannot locate the XML schema file or DTD file (.xsd or .dtd). The DB2 database system does not issue an error message if the validation does not occur. Ensure that the XML schema file or DTD file is in the location that is specified in the XML source document. Do not set the VALIDATE parameter to YES if you set the STREAMING parameter to YES.
STREAMING: Specifies whether the XML source document is separated into logical fragments that correspond to the node that matches the XPath expression of the nickname. The script wrapper then processes the XML source data fragment by fragment, reducing total memory use. This option is accepted only for columns of the root nickname (the nickname that identifies the elements at the top level of the XML document). The default streaming value is NO. Do not set the STREAMING parameter to YES if you set the VALIDATE parameter to YES.
XPATH: An XPath expression that identifies the XML element that represents individual tuples in the data source. The wrapper evaluates the XPATH nickname option for a child nickname in the context of the path that is specified by the XPATH nickname option of the parent nickname. This XPath expression is used as a context for evaluating column values that are identified by the XPATH nickname column options.

Nickname column options

The nickname column options are described in the following:

DEFAULT

The default value for an input column. This option applies only to input columns.

The default value is used if no value is provided by the SQL query. This option is not required.

FOREIGN_KEY

Indicates that this nickname is a child nickname and specifies the corresponding parent nickname.

A nickname can have at most one FOREIGN_KEY column option. The value for this option is case-sensitive. The column that is designated by the FOREIGN_KEY option contains a key that is generated by the wrapper. The value of the column cannot be retrieved in a SELECT query, and the XPATH option must not be specified. The column can only be used to join parent nicknames and child nicknames. A CREATE NICKNAME statement with a FOREIGN_KEY option fails if the parent nickname has a different schema name. Unless the nickname that is referred to in a FOREIGN_KEY clause is explicitly defined to be lowercase or mixed case by enclosing it in quotation marks under the corresponding CREATE NICKNAME statement, then you must specify the nickname in uppercase when you refer to this nickname in the FOREIGN_KEY clause.

Foreign key columns must be designated as FOR BIT DATA and NOT NULL.

INPUT_MODE

Specifies the input mode for a column. Valid values are CONFIG or FILE_INPUT. The wrapper passes the specified value to the script daemon.

CONFIG: The value is treated as a configurable parameter.
FILE_INPUT: A file is created that stores the value and the file name is passed as the command line argument.

POSITION

An integer value for positional parameters. The position sequence order starts at 1. This option applies only to input columns.

If the positional value is set to an integer, then this input must be in this position in the command line. If this option is set, the switch is inserted into the appropriate location when the query is run. If POSITION is set to -1, the option is added as the last command line option. For example, if a column value must be at the end of the command line and there is no SWITCH option, setting the value of POSITION to -1 adds the value at the end of the command line. POSITION integer values cannot be duplicated in a nickname. This option is not required.

PRIMARY_KEY

Indicates that this nickname is a parent nickname. The column data type must be VARCHAR(16). A nickname can have at most one PRIMARY_KEY column option. The only valid value is Y.

The column that is designated as PRIMARY_KEY contains a key that is generated by the wrapper. The value of the column cannot be retrieved in a SELECT query, and the XPATH option must not be specified. The column can only be used to join parent nicknames and child nicknames. Primary key columns must be designated as FOR BIT DATA and NOT NULL.

SWITCH

A character string to specify a parameter for the script on the command line. This option applies only to input columns.

On the command line, the value of this option precedes the column value that is supplied by WSSCRIPT.ARGS or the default value, if any. If the value for the switch is an empty string and a default value exists for the column, the default value is added without any SWITCH information when the command line is generated. If no default value is provided and no value for the column is provided by the SQL query, then this input column is ignored when the command line is generated. This option is required for an input column.

SWITCH_ONLY

Enables the use of switches without a command line argument.

If the SWITCH_ONLY option is specified with a value of Y, then valid input values are Y or N. For an input value of Y, only the switch is added to the command line. For an input value of N, no value is added to the command line.

VALID_VALUES

A semicolon-separated set of valid values for a column.

XPATH

Specifies the XPath expression in the XML document that contains the data that corresponds to this column. The script wrapper evaluates the XPath expression after the CREATE NICKNAME statement applies this XPath expression from this XPATH nickname option. If you run a query on a column name that has an incorrectly configured XPATH tag reference such as incorrect case, your query returns null values in this column for all returned rows.