Reference > Utilities

idresgen utility

The idresgen utility generates identifiers for XML elements with their associated identifiers. The XML files must have identifiers because the XML files map directly to the target database schema.

If the XML content already supplies identifiers, you do not have to run the idresgen utility.

The idresgen utility includes an error reporter that generates a log file if there is an error.

The following are examples of situations in which you might want to use the idresgen utility:

• Load new content in XML format when identifiers for the data are required

• Update content when identifiers already exist for an object in the database

The idresgen utility can supply actual identifiers, or identifiers can be resolved using the following techniques:

Internal-alias resolution

To use internal-alias resolution with the idresgen utility, an alias is placed in the primary-key attribute (identifier) in the XML file. The alias can then be used throughout the XML file to refer to that element. This process eliminates the need for a program to determine the unique indexes necessary to build the XML file.

Properties-file specification

The idresgen utility in the loading utilities can use a Java properties file to determine which columns of a primary table should be used as lookups for tables that require the identifier of a primary table. A table is primary if it is listed in the KEYS or SUBKEYS table.

Unique-index resolution

In the idresgen utility, unique-index resolution uses any specified unique indexes on a table as a means of determining an identifier. For example, MEMBER_ID plus IDENTIFIER is a unique index on the CATALOG table and can therefore be used as a resolution point to the primary key CATALOG_ID of the CATALOGDSC table.

The idresgen utility can analyze the database schema to determine whether there is a unique index that fulfills its requirements. The idresgen utility looks for a unique index only when there is no entry in the properties file for the table being analyzed or when there is no properties file. If these conditions are true, a unique-index check is performed. The unique index is considered valid if it exists and does not include the primary key for the table.

Before running this utility, ensure that you have complete the required configuration tasks:

1. Configure the loading utilities.

2. Configure tracing and logging for the loading utilities.

3. Configure the idresgen utility.

Filenames specified as parameters for this utility can be preceded by relative or absolute paths. Relative paths must be relative to the directory from which you run the idresgen utility.

Important: The wcs.dtd file must be in the same directory as the infile XML file.

In addition to the trace log and message log for the loading utilities, this utility produces the following log file:

• WC_INSTALL/logs/idresgen.db2.log

• WC_INSTALL/logs/idresgen.oracle.log

Run this utility as the non-root WebSphere Commerce user ID. Do not run this command as root.

Utility command

The idresgen utility has the following file name:

• idresgen.sh

• idresgen.cmd

Parameter values

-method

Required: Method to be used in processing the input file. The default method is load.

The following methods are supported:

load

The input file only contains records that do not exist in the database. The idresgen utility generates new identifiers for the records in the input files.

update

The input file only contains records that exist in the database. The idresgen utility locates the identifiers in the database. If a record does not exist in the database, the idresgen utility will not be able to resolve the identifier for this record and it will indicate that an error has occurred.

mixed

The input file contains both records that exist in the database and records that do not exist in the database. The idresgen utility creates new identifiers for records only if the records do not exist in the database. Otherwise, the existing identifier is obtained from the database.

-customizer

Name of the customizer property file to be used for the WebSphere Commerce database. When specifying the customizer property file with this parameter, omit the ".properties" file extension.

Specify one of the following customizer values:

• (Not required) Do not specify this parameter if you are using DB2 Universal Database on AIX, Linux, Solaris, or Windows operating systems.

• Required: Specify one of the following values:

  ISeries_RESWCSID_Customizer

  Specify this customizer value if you are using the native i5/OS JDBC driver.

  When you specify this value, the idresgen utility uses the values specified in the following file:

  WC_INSTALL/properties/ISeries_RESWCSID_Customizer.properties

  Toolbox_RESWCSID_Customizer

  Specify this customizer value if you are using the IBM Toolbox for Java JDBC driver.

  When you specify this value, the dtdgen utility uses the values specified in the following file:

  WC_INSTALL/properties/Toolbox_RESWCSID_Customizer.properties

  If you specify this customizer value, specify the hostname as the -dbname parameter. The following is an example of invoking the idresgen utility:

  ./idresgen.sh -method mixed -customizer Toolbox_RESWCSID_Customizer
  -infile ./myinfile.xml
  -outfile ./myoutfile.xml -dbname MY.HOSTNAME.COM -dbuser instance
  -dbpwd mypass
  

  Toolbox_RESWCSID_Customizer must be specified when using a remote iSeries database. If this is not specified, an error is thrown when running acpload.

• Required: OracleConnectionCustomizer

  When you specify this value, the idresgen utility uses the values specified in the following file:

  WC_INSTALL/properties/OracleConnectionCustomizer.properties.

-propfile

Optional: The full path to a text file containing Java properties in the form of name/value pairs. This file is used to define the look-aside column names for foreign-key identifier lookup and the select predicate for main table (such as CATEGORY and PRODUCT) queries. You can omit entries in this file for tables that have a unique index defined that does not include the identifier.

If you do not specify this parameter, the default file is used. The default file is WC_INSTALL/properties/IdResolveKeys.properties.

-infile

Name of the input XML document containing table records. The wcs.dtd file must be in the same directory as the XML file.

-inputDirectory

Full path of the directory containing only XML files that contain table records. The wcs.dtd file must also be in this directory. If the directory contains any files other than wcs.dtd file and files that contain table records, the idgresgen utility command will fail.

-infileList

The full path to a text file containing a comma-separated list of XML files that contain table records.

-outfile

Required: Name of the output XML file to be produced. This file can be used as input to the massload utility.

-dbname

• Name of the target database.

• The Oracle TNS name for the database.

• Depending on the JDBC driver you use to connect to the database, specify one of the following:

  Native i5/OS JDBC driver

  The database name as displayed in the relational database directory (WRKRDBDIRE).

  IBM Toolbox for Java JDBC driver

  The fully-qualified host name of the database system. If you are using the IBM Toolkit for Java JDBC driver, specify the -schemaname parameter.

  If the database is on a remote IASP and the database name is different than the hostname, the value of dbname that is passed to a utility is:

  -dbname "hostname/schemaName;database name=db_Name;cursor hold=false"
  

  For example,

  -dbname "TORASCAT.yourcompany.com/demo;database name=CATDB;cursor hold=false"
  

For DB2 UDB databases, the Type 2 database name is deprecated, where the database names do not contain a prefix.

That is, the DB2 Type 4 JDBC driver is used instead, where the Type 4 database name is prefixed with the database server and port. For example, db_server:db_port/db_name.

See How JDBC applications connect to a data source in the DB2 Information Center for more information.

-contentcontext

Optional: Tells the utility to use the base schema (production-ready data). This parameter cannot be specified with the -schemaname or the -workspcname parameters.

-schemaname

Optional: Name of the target database schema.

This parameter is required if there are multiple schemas in the database into which you are loading data.

If this parameter is not specified when running the utility, the utility looks for a name=value pair in the customizer property file that specifies the value of SchemaName. If this pair is present in the property file, the utility uses the value specified.

If neither a command-line nor a property-file specification for the -schemaname parameter exists, the utility defaults to the value of the -dbuser parameter.

-workspcname

Important: This parameter can only be used when loading data into a workspace on an authoring server. This parameter cannot be used when loading data on a staging server or a production server. Optional: The workgroup code which is the system generated identifier for the workspace, not the name assigned to the workspace by the Workspace Manager. Specify this parameter if you want the idresgen utility to resolve identifiers for a workspace.

If you specify the workspace parameter, specify the following optional parameters:

-taskgrp

Important: This parameter can only be used when loading data into a workspace on an authoring server. This parameter cannot be used when loading data on a staging server or a production server. The task group code which is the system generated identifier for the task groups, not the name assigned to the task group by the Workspace Manager.

-task

This parameter does not apply to WebSphere Commerce - Express.

Important: This parameter can only be used when loading data into a workspace on an authoring server. This parameter cannot be used when loading data on a staging server or a production server. The task code which the system generated identifier for the task, not the name assigned to the task by the Workspace Manager.

-dbuser

• Required: Name of the user connecting to the database.

• Required: The ID of the instance user.

• Oracle user ID connecting to the database.

-dbpwd

• Required: Password for the user connecting to the database.

• Required: Password for the user connecting to the database.

-poolsize

Optional: Number of identifiers to be reserved. If you do not specify this parameter, the idresgen utility reserves 50 identifiers.

-maxerror

Optional: Number of errors after which the idresgen utility terminates. If you do not specify this parameter, the idresgen utility terminates after one error.

-optimize

Optional: Specifies whether the idresgen utility will check for duplicate records before writing resolved records to the output file. If you do not specify this parameter, the idresgen utility checks for duplicate records.

yes

Check for duplicate records.

no

Do not check for duplicate records. Specify this value if you are using the XML file to delete records from the database.

Eliminating duplicate XML elements improves the performance of the massload utility when loading the XML file produced by the idgesgen utility.

When you use the update or mixed method with the idresgen utility, the idresgen utility automatically recognizes XML elements being resolved that are duplicates of records that already exist in the database. The duplicates are not written to the output file specified by the -outfile option, the idresgen utility logs them to trace.txt file. The duplicate entries in the trace.txt file are made without counting the duplicates as actual errors.

Each element is checked for duplication by comparing that element's attributes to the corresponding database table columns. An element must always contain all of the attributes required by the DTD. However, elements might also contain optional attributes. When checking for duplicates, the idresgen utility uses all of the attributes contained by each element. If any element is different, the element is not considered to be a duplicate.

When you use the mixed method with the idresgen utility, only elements already determined to be non-candidates for insertion are further processed to check for duplicates. This increases the efficiency of the process.

Duplicate-record checking is not performed by the idresgen utility when you use the load method because the loadable elements are not supposed to exist in the database when you use this method.

If you are deleting data from the database loading the loading utilities, you should set -optimize to no.

Relationship elements (such as cattogrp and catgrprel) might not be reported as duplicates.

Related concepts

Overview of the mass load utilities

Transforming, loading, and extracting data using the WebSphere Commerce loading utilities

Related tasks

Configure the loading utilities

Configure the idresgen utility

Resolve identifiers

Specify a properties file with the idresgen utility

Create an XML file to use internal-alias ID resolution

Related reference

Resolve identifiers for records that share identifiers with existing data

dtdgen utility

massextract utility

massload utility (Server environment)

txttransform utility

xmltransform utility

idresgen utility

+

Search Tips   |   Advanced Search