0 / 0

XML Composer step (DataStage)

Last updated: Mar 12, 2025
XML Composer step (Hierarchical Data stage)

Use a specified structure to compose XML content.

XML Target

Write to File
Enter the output directory and the file name prefix for the files that will be composed, or click Insert Parameter and then select the name of the parameter for the output directory and file name prefix. The parameters that are available are the parameters that you previously defined in the job and the built-in macros that are in IBM® InfoSphere® DataStage®.
Pass as String
Pass the composed XML string to a downstream step or stage for further processing.
Pass as Large Object
Pass the composed XML string as a large object. The final target stage – that is the last stage in the job – must be a LOB-aware stage, such as the Db2 connector, Oracle connector, ODBC connector, Teradata connector, or WebSphere MQ connector. These stages use the LOB locator string to obtain the XML data and then write it to the target database or message queue. The job can contain non-LOB-aware stages, but these stages must not modify the LOB locator string. If the last stage in the job is not LOB-aware, the LOB locator is written out as data, rather than being interpreted as a locator.

Document Root

Select the top-level element that describes the documents that you are composing. The types that display under the library's namespace are top-level element definitions. Following the XML schema standard, only top-level elements can describe documents. The name of the element that you select must match the top-level element name in the instance documents. For example, if you are composing Order documents, you select the Order element. When you select the element, you can view its structure and verify that the structure is correct for the documents that you want to compose.
Note: The elements from which you select the document root are from the resources that were previously imported into the schema libraries. If you need to import the resource that contains the document root for the XML Composer step, click the Open libraries tab and import the resource that you need. Then, return to the Assembly Editor and configure the document root.

Validation

By default, the XML Composer uses Minimal validation, and the job fails if a violation occurs. To customize validation, specify the action to perform when a violation occurs.

For more information about validation rules, see XML Composer validation rules (DataStage).

Mappings

Create a mapping to the document_collection item. How you map this item determines whether one document or multiple documents are created. To produce only one document, map the root of the Input (top) to document_collection. To produce multiple documents, map a list item to the document_collection item. Then, one file is created for each item in the list. For more information about mapping, see Working with the mapping table (DataStage).

Header

Specify more optional information to include at the beginning of the XML output.

Generate XML fragment
Do not include the XML declaration, comments, and processing instructions.
Include XML declaration
Include the XML declaration, for example, <?xml version="1.0" encoding="UTF-8">.
Include comments
Include the comments that you enter in the Comments field.
Include processing instructions
Include the processing instructions that you enter in the Processing Instructions field. Enclose each processing instruction in the <? and ?> tags.
Include schemaLocation
Include the schemaLocation attribute in the xml file with the value that you enter in the Schema Location field.
Include noNamespaceSchemaLocation
Include the noNamespaceSchemaLocation attribute in the xml file with the value that you enter in the No Namespace Schema Location field.

Format

Encoding type
Select the encoding to use for the document. The default encoding is UTF-8.
Format style
Check the box to apply the following format options to the XML output:
  • Spaces per indentation level – Select the number of characters to use for each indentation level in the XML output.
  • New line style – Select the type of new line. Choices are UNIX (LF), DOS(CRLF) or MAC(CR).
  • Time Zone – Specify the time zone value from +14:00 to -14:00. If the composer output data has any elements of date data type (time, dateTime, or gMonth), then the composer step converts the date data type according to the specified time zone and appends the converted data to the composer output data. If the composer output data does not contain any time zone information then the time zone that is specified in the text field is appended to the composer output data.

    You can select the Insert Parameter option to insert parameters containing time zone at run time instead of specifying them at design time.

  • Omit attributes with default value – For attributes that have default values and are in the data or for attributes that have fixed values, omit the values from the XML output.
  • Omit null elements – For nullable elements that are not in the data, omit the elements from the XML output.
  • Omit optional empty elements – If an XML node has an empty value, omit the elements from the XML output.