Considerations for Batch Data Usage

Output can process XML files that contain one record or many records. These XML files are known as batch data files. When processing a batch XML data file, Output can generate a single output file that contains many documents (one output file for each record). Output can also generate a separate file for each document that is generated (one output file for each record)

The following XML data shows an example of a data file that contains three data records.

<?xml version="1.0" encoding="UTF-8"?> 
<batch> 
<LoanRecord> 
    <mortgageAmount>500000</mortgageAmount> 
    <lastName>Blue</lastName> 
    <firstName>Tony</firstName> 
    <SSN>555666777</SSN> 
    <Description>Buy a home</Description> 
</LoanRecord> 
<LoanRecord> 
    <mortgageAmount>300000</mortgageAmount> 
    <lastName>White</lastName> 
    <firstName>Sam</firstName> 
    <SSN>555666222</SSN> 
    <Description>Buy a home</Description> 
</LoanRecord> 
<LoanRecord> 
    <mortgageAmount>700000</mortgageAmount> 
    <lastName>Green</lastName> 
    <firstName>Steve</firstName> 
    <SSN>55566688</SSN> 
    <Description>Buy a home</Description> 
</LoanRecord> 
</batch>
Note: Notice that the XML element that starts and ends each data record is named LoanRecord. The application logic that generates each document references this XML element.

Incremental loading of multiple records in a batch

Output incrementally loads each record in a batch into memory, processes the record, and releases it before moving on to read the next record. Incremental loading is useful when merging a form design with a batch data set. The result is an improvement in the volume of records that can be processed. The reason is because not all the records are loaded and merged at once into memory.

To enable incremental loading, remove the <xfa:datasets> node from the form design in Designer. This restriction applies to the current version of Output. You can view and remove the <xfa:datasets> node in the XML Source tab.

The network printer administrator can confirm that incremental loading is enabled after processing the form using Output. The network printer administrator can check the server log file for the following message:

Unable to perform an incremental load. Performing a full data load.

This message is to inform you that Output examined the form design and discovered the presence of a data schema. It determines this fact by searching for the <dataset> node. If it discovers this node, it abandons the attempt to load the data incrementally (one record at a time). Instead, it merges the entire data stream with the form design.

Designing for multiple records

The sample batch XML above contains multiple instances of LoanRecord; however, the record starts at the Batch node. The network printer administrator uses the following run-time options:

Output Record Level
Indicates that the data file has multiple records

Record Name indicates where the record begins
The Record Level option specifies the level where Output creates a document for each node. For example, if you look at the sample XML, Batch is the root; therefore it is at level 1. The LoanRecord node is next; therefore it is level 2. In this example, the network printer administrator would enter 2 in the Record Level field to indicate that each record begins at the LoanRecord node.

The Record Level option is used when all the records in the XML data are of the same type. However, if the XML data has a mix of various record types, the network printer administrator can use the Record Name option. The Record Name option specifies the record type to use for generating output. For more information about these options, see Workbench Help.

Remember the Record Level and Record Name Output run-time options as you design your form and data binding in Designer. These options allow you to take advantage of incremental loading,

To ensure that the records are properly designed and the data binding functions properly, start with a schema that represents one record. Match the record to record level 2 or 3 in the Record Level Output run-time option. If the XML data contains various record types, create a representation for each record, matching each to the Record Name option.

Avoid using [*] at the record node because it causes Output to look to repeating the record rather than loading a new record.

After you test the form and are satisfied, you can base the remaining records on the ones used for testing.

Scripting methods for use when processing batch data sets

Several scripting methods that you can use in the Designer scripting environment are available.

Method

Description

documentCountInBatch

Determines the number of documents in the current batch

absPageCountInBatch

Determines the page count of the current batch

documentInBatch

Determines the ordinal number of the current document within the batch

sheetCountInBatch

Determines the sheet count of the current batch

absPageInBatch

Determines which page within the batch contains the form object

cancelBatch

Cancels a pending batch update

sheetInBatch

Determines which sheet within the batch contains the form object

updateBatch

Writes all pending batch updates to the data source

For the most up-to-date information about scripting objects, properties, and methods, see Designer Scripting Reference.

// Ethnio survey code removed