IBM Datacap

Version 9 Release 0

Datacap Objects (DCO) API Guide



SC27-6376-00
IBM Datacap
Version 9 Release 0

Datacap Objects (DCO) API Guide



SC27-6376-00
 Note
Before using this information and the product it supports, read the information in “Notices” on page 93.

This edition applies to Version 8 Release 1 of Datacap (product number 5725-C15) and to all subsequent releases
and modifications until otherwise indicated in new editions.
© Copyright IBM Corporation 2014.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
ibm.com and related resources. . . . . v IsValid method . . . . . . . . . . . 37
How to send your comments . . . . . . . . . v MoveChild method . . . . . . . . . . 37
Contacting IBM . . . . . . . . . . . . . vi MoveIn method . . . . . . . . . . . 38
NumOfChildren method . . . . . . . . 39
Datacap object API . . . . . . . . . . 1 NumOfVars method . . . . . . . . . 39
ObjectType method . . . . . . . . . . 40
Relationship between runtime batch and document
Parent . . . . . . . . . . . . . . 41
hierarchy . . . . . . . . . . . . . . . 2
Read method . . . . . . . . . . . . 41
Creating a document hierarchy with Datacap object
ReadSetup method . . . . . . . . . . 42
APIs . . . . . . . . . . . . . . . . . 3
SetPosition method . . . . . . . . . . 43
DCO APIs . . . . . . . . . . . . . . . 4
SetupNode method . . . . . . . . . . 44
DCO properties . . . . . . . . . . . . 6
SetupObject method . . . . . . . . . 45
AltConfidenceString property. . . . . . . 6
set_AltConfidenceString . . . . . . . . 45
AltText property . . . . . . . . . . . 7
set_AltText method . . . . . . . . . . 46
CharConfidence property . . . . . . . . 8
set_CharConfidence method . . . . . . . 47
CharValue property . . . . . . . . . . 8
set_CharValue method. . . . . . . . . 48
ConfidenceString property . . . . . . . . 9
set_OMRValue . . . . . . . . . . . 49
ID property . . . . . . . . . . . . 10
set_Variable method . . . . . . . . . 49
ImageName property . . . . . . . . . 10
Write method. . . . . . . . . . . . 50
Status property . . . . . . . . . . . 11
WriteSetup method . . . . . . . . . . 51
Text property . . . . . . . . . . . . 11
DCOSetup API . . . . . . . . . . . . . 51
Type property . . . . . . . . . . . 12
DCOSetup properties . . . . . . . . . . 54
Variable property . . . . . . . . . . 12
DictionaryName property . . . . . . . 54
XML property . . . . . . . . . . . 13
Path property. . . . . . . . . . . . 54
DCO methods . . . . . . . . . . . . 14
Value property . . . . . . . . . . . 55
AddChild method . . . . . . . . . . 14
Word property . . . . . . . . . . . 55
AddValue method . . . . . . . . . . 15
DCOSetup methods . . . . . . . . . . 56
AddVariable method . . . . . . . . . 16
AddNode method . . . . . . . . . . 56
AddVariableFloat method . . . . . . . 17
DeleteNode method . . . . . . . . . 57
AddVariableInt method . . . . . . . . 17
DeleteNodeByName Method . . . . . . 58
AddVariableString method . . . . . . . 18
get_DictionaryName method . . . . . . 59
CheckIntegrity method . . . . . . . . 18
get_Value method . . . . . . . . . . 59
Clear method . . . . . . . . . . . . 19
get_Word method . . . . . . . . . . 60
CreateDocuments method . . . . . . . 20
GetNode method . . . . . . . . . . 60
CreateFields method . . . . . . . . . 21
GetNodeByName method . . . . . . . 61
DeleteChild method . . . . . . . . . 21
NumOfDictionaries method . . . . . . . 62
DeleteValue method . . . . . . . . . 22
NumOfNodes method . . . . . . . . . 62
DeleteVariable method. . . . . . . . . 23
NumOfWords . . . . . . . . . . . 63
FindChild method . . . . . . . . . . 23
ReadLock . . . . . . . . . . . . . 64
FindChildIndex method . . . . . . . . 24
ReadSetup . . . . . . . . . . . . . 64
FindRouteChild method . . . . . . . . 25
set_DictionaryName method. . . . . . . 64
FindVariable method . . . . . . . . . 25
set_Value method . . . . . . . . . . 65
get_AltConfidenceString method . . . . . 26
set_Word method . . . . . . . . . . 66
get_AltText method. . . . . . . . . . 27
ShowSetupDialog . . . . . . . . . . 66
get_CharConfidence method. . . . . . . 28
UnlockIt . . . . . . . . . . . . . 66
get_CharValue method . . . . . . . . 29
WriteSetup method . . . . . . . . . . 67
get_OMRValue method . . . . . . . . 30
DCOSetupNode APIs . . . . . . . . . . . 67
get_Variable method . . . . . . . . . 30
DCOSetupNode properties . . . . . . . . 68
GetChild method . . . . . . . . . . 31
Name property . . . . . . . . . . . 68
GetLastError method . . . . . . . . . 32
ObjectType property . . . . . . . . . 69
GetPosition method . . . . . . . . . 32
RuleChildName . . . . . . . . . . . 70
GetRoute method . . . . . . . . . . 33
RuleMaxNum . . . . . . . . . . . 70
GetVariableName method . . . . . . . 34
RuleMinNum. . . . . . . . . . . . 71
GetVariableValue method . . . . . . . . 35
RuleObjectType . . . . . . . . . . . 72
IsError method . . . . . . . . . . . 36
RulePosition . . . . . . . . . . . . 72
IsRoute method . . . . . . . . . . . 36
Variable . . . . . . . . . . . . . 73

© Copyright IBM Corp. 2014 iii

 VariableName . . . . . . . . . . . 73 NumOfRules method . . . . . . . . . 86
VariableValue . . . . . . . . . . . . 74 NumOfVariables Method . . . . . . . . 87
DCOSetupNode methods . . . . . . . . . 75 set_RuleChildName . . . . . . . . . 87
AddRule method . . . . . . . . . . 75 set_RuleMaxNumber . . . . . . . . . 88
AddVariable method . . . . . . . . . 76 set_RuleMinNumber . . . . . . . . . 88
DeleteRule method . . . . . . . . . . 77 set_RuleObjectType . . . . . . . . . . 88
DeleteVariable method. . . . . . . . . 77 set_RulePosition . . . . . . . . . . . 89
DeleteVariableByName method . . . . . . 78 set_Variable . . . . . . . . . . . . 90
FindRule method . . . . . . . . . . 78 set_VariableName . . . . . . . . . . 90
get_RuleChildName method. . . . . . . 79 set_VariableValue . . . . . . . . . . 91
get_RuleMaxNumber Method . . . . . . 80
get_RuleMinNumber method . . . . . . 80 Notices . . . . . . . . . . . . . . 93
get_RuleObjectType method . . . . . . . 81 Trademarks . . . . . . . . . . . . . . 95
get_RulePosition method . . . . . . . . 82 Privacy policy considerations . . . . . . . . 95
get_Variable method . . . . . . . . . 83
get_VariableName method . . . . . . . 83
Index . . . . . . . . . . . . . . . 97
get_VariableValue Method . . . . . . . 84
GetRule method . . . . . . . . . . . 85

iv IBM Datacap: DCO API Guide

ibm.com and related resources
Product support and documentation are available from ibm.com®.

Support and assistance

Product support is available on the Web. Click Support from the product Web site
at:
Datacap
http://www.ibm.com/support/entry/portal/Software/
Enterprise_Content_Management/Datacap_Taskmaster_Capture

Knowledge Center

You can view the product documentation on ibm.com. See Knowledge Center at
http://www.ibm.com/support/knowledgecenter/SSZRWV_9.0.0/.

PDF publications

You can view the PDF files online using the Adobe Acrobat Reader for your
operating system. If you do not have the Acrobat Reader installed, you can
download it from the Adobe Web site at http://www.adobe.com.

See the following PDF publications Web site:

Product Web site

Datacap http://www.ibm.com/support/
docview.wss?uid=swg27035774

How to send your comments

Your feedback is important in helping to provide the most accurate and highest
quality information.

You can use any of the following methods to provide comments:

v Add comments by using the Comments pane at the bottom of every topic in
Knowledge Center.
v Send your comments by clicking the Feedback link at the bottom of any topic in
Knowledge Center.
v Send your comments by using the online readers' comment form at
http://www.ibm.com/software/data/rcf/.
v Send your comments by e-mail to [email protected]. Include the name of
the product, the version number of the product, and the name and publication
number of the information (if applicable). If you are commenting on specific
text, please include the location of the text (for example, a title, a table number,
or a page number).

© Copyright IBM Corp. 2014 v

 Consumability survey

Tell us how you feel about the value of quality content by taking the Importance of
High Quality Technical Information survey at the following link:
http://www.ibm.com/survey/oid/wsb.dll/s/ag2c1. If you want to help IBM
make this product easier to install and use, take the Consumability Survey at the
following link: http://www.ibm.com/software/data/info/consumability-survey/.

Contacting IBM
To contact IBM customer service in the United States or Canada, call
1-800-IBM-SERV (1-800-426-7378).

To learn about available service options, call one of the following numbers:
v In the United States: 1-888-426-4343
v In Canada: 1-800-465-9600

For more information about how to contact IBM, see the Contact IBM Web site at
http://www.ibm.com/contact/us/.

vi IBM Datacap: DCO API Guide

Datacap object API
You can use Datacap object APIs to create or modify runtime batches and
document hierarchies, and to obtain or modify recognition confidence levels, field
values, text values, and object types. To use Datacap object APIs, you reference
TDCO.DLL in your development environment, such as Microsoft Visual Studio.

Datacap contains three separate classes or APIs that you can use to complete
actions on different parts of a Datacap object (DCO), which can be a batch,
document, page, field, or character. You use the three sets of Datacap API to
modify the document hierarchy (setup DCO) and the runtime batch hierarchy
(runtime DCO).

Datacap requires an XML file to process a batch. When you use Datacap Studio to
create an application, Datacap saves the setup DCO as an XML file, for example,
C:\Datacap\application name\dco_application name\application name.xml.
Similarly, if you create a document hierarchy outside of Datacap Studio, you use
an API to save the setup DCO as an XML file. Each Datacap object is represented
as a node in the XML file. The setup DCO defines the expected structure of a
batch, including valid documents, pages in documents, the fields on each page,
and other predefined information.

Datacap creates the runtime DCO when a workflow is started. When a task
completes, Datacap writes the batch to a batch folder, for example,
C:\Datacap\APT\batches\batch number. The runtime information comprises a root
file that is named after the completed task, for example, C:\Datacap\APT\batches\
batch number\Verify.xml and defines the documents and pages in the batch.
Datacap also writes a data file for each page, for example, C:\Datacap\APT\
batches\batch number\tm000001.xml. The runtime DCO indicates the current
composition of the batch, including documents, pages, fields, and characters.

The three sets of APIs are DCO, DCOSetup, and DCOSetupNode. You can use the
APIs to search or browse through a DCO object, starting from the root node
(batch) to a child node, which includes documents, pages, fields, and characters.
Using the APIs, you can find and select a child node, and modify or populate a
value. You use the DCO APIs with a runtime DCO, the DCOSetup APIs with the
setup DCO, and the DCOSetupNode APIs with individual nodes in the setup
DCO. The following tasks represent a sample of how you can use some of the
APIs:
v Create a document hierarchy
v Modify a batch by creating documents, reorganizing pages, or deleting
documents
v Determine the page types that contain confidential information and, with the
implementation of custom verification panels, display only those pages to an
operator who has appropriate security clearance
v Create, modify, or populate fields and characters
v Access and modify a dictionary that can be used to present a list of valid field
values to an operator during a verification task
v Use XML files to load a batch, or save a batch to a disk

© Copyright IBM Corp. 2014 1

Relationship between runtime batch and document hierarchy
To know which APIs to use for specific objects, you need to understand how a
runtime batch and a document hierarchy are related. For example, when the page
types are identified in a runtime batch, you can insert document objects into the
batch by referencing the DCO setup object.

At the beginning of a workflow, Datacap scans a collection of pages. Because the

page types are initially unknown, Datacap assigns the type Other to the pages
when it adds them to the runtime batch hierarchy. The following diagram shows
that the document hierarchy includes four pages. At run time, the four pages are
initially assigned the type Other when Datacap adds the pages to a batch.

DCO object
( Batch )

Runtime batch hierarchy

DCO object DCO object DCO object DCO object DCO Setup object
( TYPE=Other ) ( TYPE=Other ) ( TYPE=Other ) ( TYPE=Other ) ( Batch )

Pages
Document 1 Document 2

Page 1 Page 2 Page 3 Page 4

Document hierarchy

Datacap identifies each page type by referencing the types that are defined in the
document hierarchy, and assigns the appropriate TYPE attribute to each page object.
For example, the four pages in the runtime batch hierarchy are identified as P1, P2,
P3, and P4, as shown in the following diagram:

DCO object
( Batch )

Runtime batch hierarchy

DCO object DCO object DCO object DCO object DCO Setup object
( TYPE=P1 ) ( TYPE=P2) ( TYPE=P3 ) ( TYPE=P4 ) ( Batch )

Pages
Document 1 Document 2

Page 1 Page 2 Page 3 Page 4

Document hierarchy

2 IBM Datacap: DCO API Guide

 Datacap gets the document type that is associated with each page type and inserts
the appropriate document objects into the runtime hierarchy. Previously, the batch
included the four pages without the associated document type. The following
diagram shows that P1 and P2 are associated with D1, and P3 and P4 are
associated with D2. The page and document type association is based on the
document hierarchy that is defined in the DCO Setup object:

DCO object
( Batch )

Documents
DCO object DCO object DCO Setup object
( Type=D1 ) ( Type=D2 ) ( Batch )

DCO object DCO object Document 1 Document 2

( TYPE=P1 ) ( TYPE=P3 )

DCO object DCO object Page 1 Page 2 Page 3 Page 4

( TYPE=P2) ( TYPE=P4 )
Document hierarchy
Pages

Creating a document hierarchy with Datacap object APIs

You can use the Datacap object APIs to create a document hierarchy. For example,
you can use these APIs to read a setup DCO XML file and add child objects,
including documents, pages, and fields.

This task also assumes that you successfully exported a batch of documents from a
database to an XML file.

Because the use of Datacap object APIs is limited to runtime batches and document
hierarchies, the task does not include steps for data recognition and initial
calculation of confidence levels.

To create a document hierarchy by using Datacap object APIs, complete the

following steps:
1. Use the ReadSetup method read a document hierarchy that you exported:
m_oDCO.ReadSetup("C:\\temp_location\\exported_application.XML");
2. Use the WriteSetup method to populate your new setup object and save the
document hierarchy as an XML file:
m_oDCO.WriteSetup("C:\\Datacap\\NEW\\dco_NEW\\NEW.XML")
3. Optional: Use the AddNode method to add child objects (documents, pages, or
fields) to the setup object.
TheAddNode method uses two arguments: nType lpszNodeName. The nType value
(1) specifies that the new node is a document object. The lpszNodeName value
specifies that the document object name is NewNode, as shown in the following
example:
m_oDCOSetup.AddNode(1, "NewNode");

Datacap object API 3

 The resulting node in the DCO Setup XML file is <D type="NewNode">.

Tip: You can similarly add pages, fields, or characters by setting the nType
value to 2 (for pages), 3 (for fields), or 4 (for characters).
4. Use the AddRule method to specify the structure of a document. This step gets
the SetupNode object for the NewNode document in the Setup DCO. The step
then adds a rule that requires one instance of the page NewPage to exist for the
document structure to be valid. If a page node for NewPage does not exist, the
method creates NewPage automatically.
TDCOLib.DCOSetup m_oDCOSetup = m_oDCO.SetupObject();
TDCOLib.DCOSetupNode m_oDCOSetupNode =
m_oDCOSetup.GetNodeByName(1, "NewNode");
m_oDCOSetupNode.AddRule(2, "NewPage", 0, 1, 1);
After the execution of the code, the following line is added to the Setup DCO
beneath the NewNode document type.
<D type="NewNode">
.
.
.
<P type="NewPage" pos="0" min="1" max="1"/> <!-- New line added -->
Additionally, if NewPage does not exist, the following page node is created in
the Setup DCO:
<P type="NewPage">
<V n="ID">0</V>
<V n="TYPE">Page</V>
<V n="STATUS">0</V>
<V n="IMAGEFILE"></V>
<V n="DATAFILE"></V>
<V n="TEMPLATE IMAGE"></V>
<V n="MIN_TYPES">0</V>
<V n="MAX_TYPES">0</V>
</P>
5. Use the Read method, Write method, and the XML property to export the
document hierarchy to an external location, which can be a content repository,
a database, or a web server. This example exports the document hierarchy to a
temporary location on a local server:
m_oDCO.Read("C:\\C:\\Datacap\\NEW\\dco_NEW\\NEW.XML");
strDCOXml = m_oDCO.XML;
m_oDCO.Write ("c:\\temp_location\\new_application.xml")

The Read method stores the document hierarchy in a setup object. The XML
property assigns the XML file to a variable, and the Write method writes the
document hierarchy (setup DCO) to a new location.

DCO APIs
The DCO APIs include properties and methods that you can use to modify the
runtime batch hierarchy, which is also known as the runtime DCO. For example,
when your business requirements change, you can use these APIs to add or
remove documents and pages, or change the names or values of object types.

When you create a runtime DCO object (m_oDCO in this example), a corresponding
DCOSetup object is created automatically. The DCOSetup object is a child of the
DCO object.
TDCOLib.IDCO m_oDCO = new TDCOLib.DCOClass();
//Creating a runtime DCO object

4 IBM Datacap: DCO API Guide

 DCO object
( Batch )

DCOSetup object
( Batch )

Because the DCOSetup object is empty, you need to populate the DCOSetup object
from the Setup DCO file of the application.
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");
//Reading a Setup DCO file

DCO object
( Batch )

DCOSetup object
( Batch )

Document 1 Document 2

Page 1 Page 2 Page 3 Page 4

Runtime batch hierarchy
Created during workflow processing Document hierarchy

As workflow tasks process scanned pages, Datacap creates a hierarchy of child

objects beneath the runtime DCO object. Each child object in the runtime batch
hierarchy corresponds to an object in the Setup DCO:

Datacap object API 5

 DCO object
( Batch )

Runtime objects Setup DCO

DCO object DCOSetup object

( Document ) ( Batch )

DCO object DCOSetupNode

( Page ) ( Document )

DCO object DCOSetupNode

( Field ) ( Page )

DCO object DCOSetupNode

( Character ) ( Field )

You use the DCO API properties to change the names of object types, and you can
use methods to add or remove child objects.

DCO properties
You can use DCO properties to access or modify the names and values of DCO
objects, including documents, pages, fields, and characters. You can also use DCO
properties to modify metadata, which includes confidence levels, IDs, types,
statuses, and variables. Generally, you use the properties to pass values to methods
that complete actions on the associated objects.

AltConfidenceString property
The AltConfidenceString property sets or gets the confidence level of characters in
the field value.

VBScript restriction: Because extended properties are not supported through the
C# .NET Interop interface, you must instead use the “set_AltConfidenceString” on
page 45 method or the “get_AltConfidenceString method” on page 26 method.

Syntax
VBScript
oDCO.AltConfidenceString (nIndex as Long) as String.

Applies to

Field objects only.

Type

Read and write.

Arguments
nIndex
0 specifies the primary value. Where the field contains multiple recognition,

6 IBM Datacap: DCO API Guide

 voting, or multi-pass data entry values, 1 specifies the first alternative, 2
specifies the second alternative, and so on.

Return value

String that contains the confidence level of each character.

VBScript example

The following example sets the confidence string for the first alternative in the
Total field:
objTotalField.AltConfidenceString(1) = "987999"

In the example, the Total field consists of 6 characters, and the confidence level of
each character is 9, 8, 7, 9, 9, and 9.

AltText property
The AltText property sets or gets the alternative character data that is associated
with a field. You use this property with multiple-pass verification tasks and when
you need to display alternative text options to an operator.

VBScript restriction: Because extended properties are not supported through the
C# .NET Interop interface, you must instead use the “set_AltText method” on page
46 or the “get_AltText method” on page 27.

Syntax
VBScript
oDCO.AltText (nIndex as Long) as String

Applies to

Field objects only.

Type

Read and write.

Arguments
nIndex
0 specifies the primary value. When the field contains multiple recognition,
voting, or multiple-pass data entry values, 1 specifies the first alternative, 2
specifies the second alternative, and so on.

Returns

String containing the alternative text. The string is stored in the page XML file in
ASCII format.

VBScript example

This example shows the first alternative value (231.77) for the Total field that an
operator entered during a multiple-pass verification task.
objTotalField.AltText(1) = "231.77"

Datacap object API 7

 CharConfidence property
The CharConfidence property sets or gets the confidence level of the value of a
character.

VBScript restriction: Because extended properties are not supported through the
C# .NET Interop interface, you must instead use the “set_CharConfidence method”
on page 47 or the “get_CharConfidence method” on page 28.

The confidence level of each character is a digit from 0 (lowest confidence) to 9

(highest confidence). If the confidence level for a four-character field is 9999, each
of the 4 characters has a confidence level of 9.

Syntax
VBScript
oDCO.CharConfidence (nIndex as Long) as Long

Applies to

Character objects only.

Type

Read and write.

Arguments
nIndex
0 specifies the primary value. When the field contains multiple recognition,
voting, or multiple-pass data entry values, 1 specifies the first alternative, 2
specifies the second alternative, and so on.

VBScript example

This example sets the confidence level of the primary character to 9, or the highest
confidence level.
oDCO.CharConfidence(0)=9 ' high confidence
conf = oDCO.CharConfidence(0)

CharValue property
The CharValue property sets or gets the data value of a character, which can be a
digit in a multiple-digit number or a single character in a string. You can use this
property to search for or assign a value to a character in a field.

VBScript restriction: Because extended properties are not supported through the
C# .NET Interop interface, you must instead use the“set_CharValue method” on
page 48 or the “get_CharValue method” on page 29.

Syntax
VBScript
oDCO.CharValue (nIndex as Long) as String.

Applies to

Character objects only.

8 IBM Datacap: DCO API Guide

Type

Read and write.

Arguments
nIndex
0 specifies the primary value. When the field contains multiple recognition,
voting, or multiple-pass data entry values, 1 specifies the first alternative, 2
specifies the second alternative, and so on.

ConfidenceString property
The ConfidenceString property sets or gets the confidence values for the primary
character data in a field object.

The value of each character can be 0 - 9 and corresponds to integer confidence

levels of 0 to 9. After Datacap scans a page and applies recognition rules, Datacap
generates an XML file that contains confidence levels for characters in each field on
a page. The XML code adds a value of 1 to the confidence level so that the range
in XML is 1 - 10.

In this XML sample for the Vendor field, the fourth character contains a confidence
level of 6 for the primary character value. The first alternative character value has
confidence level of 8, and the second alternative character value has a confidence
level of 4.
<F id="Vendor">
<V n="TYPE">Vendor</V>
<V n="Position">0,0,0,0</V>
<V n="Status">1</V>
<C cn="6,8,10" cr="0,0,0,0>83,49,53</C>
<C cn="6,8,10" cr="0,0,0,0>116,50,54</C>
<C cn="6,8,10" cr="0,0,0,0>105,51,55</C>
<C cn="6,8,4" cr="0,0,0,0>110,52,56</C>

Syntax
VBScript
oDCO.ConfidenceString as String
C#
string ConfidenceString { set; get; }

Applies to

Field objects only.

Type

Read and write.

C# example

This example sets and gets the confidence string that is associated with the
primary character data in the Vendor field. The root of the search in this case is the
page object.
m_oDCOPage.FindChild("Vendor").ConfidenceString = "7777";
string strReturn = m_oDCOPage.FindChild("Vendor").ConfidenceString;

Datacap object API 9

 v The confidence levels that you specify are the internal confidence levels (0 - 9).
When you write them to the page XML file, field object and parent page object
confidence values are raised by 1 because the XML values range 1 - 10.
v If the field contains more characters than specified when you are setting the
confidence string, the last specified character is used for all remaining characters.
For example, if you specify 1234 but the field has 10 characters, the remaining 6
characters are assigned a confidence value of 4.

ID property
The ID property sets or gets the unique identifier of an object, which can be a
batch, document, or page.

This property provides access to the id attribute of an object. For example, the id
attribute for a batch, document, page, and field can be <B id="20100096">, <D
id="20100096.001.01">, <P id="TM000001">, and <F id="Vendor">. You can pass
the value of the id attribute to a variable or custom action.

Syntax
VBScript
oDCO.ID as String
C#
string ID { set; get; }

Applies to

All objects. The ID property typically has a value for a batch and for all child
nodes, including documents, pages, and fields, but not for characters.

Type

Read and write.

ImageName property
The ImageName property sets or gets the full path and the file name of the image
file that is associated with a page object. You can use this property when you are
modifying the order of pages in a batch.

This property provides access to the variable IMAGEFILE.

Syntax
VBScript
oDCO.ImageName as String
C#
string ImageName { set; get; }

Applies to

Page objects only.

Type

Read and write.

10 IBM Datacap: DCO API Guide

C# example

The following example sets and gets the full path and the file name for the image
file that is associated with the page object with ID "TM000001":
m_oDCO.FindChild("TM000001").ImageName = "C:\\Datacap\\APT\\batches
\\20100096.001\\tm000001.tif";
strImageName = m_oDCO.FindChild("TM000001").ImageName;

Status property
The Status property sets or gets the status of an object. The status is a numerical
value that indicates success, failure, error, problem, or other status that depends on
the type of object. For example, you can use this property to locate pages with a
status of 1, which indicates that there was a problem during the page identification
task.

This property provides access to the STATUS variable, which is one of the standard
variables that are installed with Datacap.

Syntax
VBScript
oDCO.Status as Long
C#
int Status { set; get; }

Applies to

All object types.

Type

Read and write.

Text property
The Text property sets or gets the primary character data that is associated with a
field.

The characters of a field are stored as ASCII values in the page data XML file. In
this sample XML node for the Vendor field, the fourth character contains a
primary text value of 97. The first alternative text value is 52, and the second
alternative text value is 97.
<F id="Vendor">
<V n="TYPE">Vendor</V>
<V n="Position">0,0,0,0</V>
<V n="STATUS">1</V>
<C cn="10,8,10" cr="0,0,0,0>68,49,68</C>
<C cn="10,8,10" cr="0,0,0,0>97,50,97</C>
<C cn="10,8,10" cr="0,0,0,0>116,51,116</C>
<C cn="10,8,10" cr="0,0,0,0>97,52,97</C>
</F>

Syntax
VBScript
Text as String
C#
string Text { set; get; }

Datacap object API 11

 Applies to

Field objects only.

Type

Read and write.

C# example

This example sets the primary character data in the Vendor field to IBM. The
confidence values (cn attribute) are automatically set to high (9 in the code; 10 in
the page XML file).
m_oDCOPage.FindChild("Vendor").Text = "IBM";
v The text is the value that a task, such as Profiler, adds to a runtime field object.
v If you use this property to replace existing data, all characters are assigned high
confidence, unless you specify otherwise by using the ConfidenceString
property.

Type property
The Type property sets or gets the object name. You can use this property to search
for document types or page types in a batch and change the name of the object.

This property provides access to the TYPE variable, which is one of the standard
variables that are installed with Datacap.

Syntax
VBScript
objRT.Type as String
C#
string Type { set; get; }

Applies to

Any object, but it is used primarily for documents and pages.

Type

Read and write.

Example

This example sets the name of the document object to 1040ez:

oDCO.Type = "1040ez"

Variable property
The Variable property sets or gets the value of a named variable. You can use this
property when you first need to obtain a value that you pass afterward to another
variable or object, such as a field.

VBScript restriction: Because extended properties are not supported through the
C# .NET Interop interface, you must instead use set_Variable or get_Variable.

12 IBM Datacap: DCO API Guide

Syntax
VBScript
oDCO.Variable(lpszName as String) As Variant.

Arguments
lpszName
The name of the variable of which you need to set or get the value.

Applies to

All objects.

Type

Read and write.

VBScript example

This example checks the value of the Handwriting variable. If Handwriting is greater
than 0, then the code sets the value of the Checked variable to 1 to indicate that a
check box is selected.
If oDCO.Variable("HandWriting") > 0 Then
WriteLog("HandWriting is TRUE")
End If
oDCO.Variable("Checked") = 1

XML property
The XML property sets or gets the XML file that is associated with an object. You
can use this property to populate a run time object from the Setup DCO file and
assign the XML file to a variable.

Syntax
C#
string XML { set; get; }

Arguments

None.

Returns

String containing the XML file name.

Applies to

All object types.

C# example

This example populates the runtime batch object from the DCO Setup file, and
then assigns the XML file to the variable strDCOXml.
m_oDCO.Read("C:\\Datacap\\APT\\batches\\20100096.001\\Verify.xml");
strDCOXml = m_oDCO.XML;

Datacap object API 13

 DCO methods
You can use DCO methods to complete actions on DCO objects, such as adding
documents to batches, pages to documents, or fields to pages. You can also use the
DCO methods to search for and change metadata values, including confidence
levels, indexes, variables, and alternative text for verification.

AddChild method
The AddChild method adds a child object to the parent runtime DCO object. You
can use the AddChild method to add a field to a page or add a page to a
document. You can add only a child that is at the same or a lower level than this
object in the hierarchy.

Syntax
VBScript
oDCO.AddChild (ObjectType as Long, ID as String,
Placement as Long) as Object
C#
TDCOLib.DCO AddChild(int nType, string lpszID, int nIndex)

Applies to

All objects.

Arguments
nType
The type of the child object:
0=Batch
1=Document
2=Page
3=Field
4=Character
lpszID
A string with the ID of the new object. Use an empty string for character
objects.
nIndex
The index of the child object relative to other child objects of the same parent.
If necessary, existing child objects are moved down to accommodate a new
child object.
-1: Adds the new child object to the end of the list.
0: Adds the new child object to the beginning of the list.

Returns

The child object of the specified type.

C# examples

The first example creates a field object under the parent page object. The field is
added to the page data file as the last field in the list by using a value of -1.
m_oDCOField = m_oDCOPage.AddChild(3, "NewField", -1);

14 IBM Datacap: DCO API Guide

The second example adds a character object to the parent field object. The new
character is added at the beginning of the list (0) and all existing character fields
move down one position.
m_oDCOChar = m_oDCOField.AddChild(4, "", 0);
v You cannot add a parent to a child. For example, you cannot add a page object
to a field object.
v You cannot assign an ID that is already used by another child of the same
parent.

AddValue method
The AddValue method adds a character data value (ASCII code) and the associated
confidence level to the character object. You can use this method to correct optical
character recognition (OCR) errors.

In addition to the primary data value, each character in a field can have multiple
alternative data values. Each of the alternative data values has an associated
confidence level (0 - 9 internally and 1 - 10 in the page XML file). Each time that
you add a value by using the AddValue method, the new value is appended to the
list of existing values. Also, a new confidence level is appended to the list of
existing confidence levels.

In the following example, the fourth character contains a primary confidence level
value of 6, a first alternative confidence level of 8, and a second alternative
confidence level of 10. The fourth character also contains a primary character value
of 110, a first alternative character value of 52, and a second alternative character
value of 56.
<F id="Vendor">
<V n="TYPE">Vendor</V>
<V n="Position">0,0,0,0</V>
<V n="STATUS">1</V>
<C n="6,8,10" cr="0,0,0,0">83,49,53</C>
<C n="6,8,10" cr="0,0,0,0">116,50,54</C>
<C n="6,8,10" cr="0,0,0,0">105,51,55/C>
<C n="6,8,10" cr="0,0,0,0">110,52,56</C>
</F>

Syntax
VBScript
oDCO.AddValue (Value as Long, Confidence as Long) as Boolean
C#
int AddValue(int nValue, int nConfidence)

Applies to

Character objects only.

Arguments
nValue
The ASCII code of the character.
nConfidence
A number between 0 (low) and 9 (high) representing the confidence level.

Datacap object API 15

 Returns
VBScript
Returns true if successful; returns false if unsuccessful.
C# Returns 1 if successful; returns 0 if unsuccessful.

C# example

This example adds the ASCII character 50 with a confidence level of 3 to the
character object:
m_oDCOChar.AddValue(50,3);

AddVariable method
The AddVariable method adds a variable and its value to an object, such as a
batch, document, page, or field. You can use this method when you need to pass
values to a custom action. For example, your organization might introduce a new
security regulation that requires a new field for identification on certain page
types.

Syntax
VBScript
oDCO.AddVariable (strName as String, newValue as Variant) as Boolean
C#
bool m_oDCO.AddVariable (string strName, object newValue)

Arguments
strName
The variable name.
newValue
The value of the variable.

Returns

Returns true if successful; returns false if unsuccessful.

Applies to

All objects.

Examples
VBScript
This example adds the Company variable with a value of IBM to the page
object.
Dim page
Call objField.AddVariable ("Company", IBM)
factor = objField.Variable("Company")
C# This example adds the variable Company and the value IBM to page
TM000001 in the runtime batch.
TDCOLib.IDCO m_oChild = m_oDCO.FindChild("TM000001");
if (m_oChild != null
)
{
m_oChild.AddVariable("Company", "IBM");
}

16 IBM Datacap: DCO API Guide

 The resulting XML code is shown in the following example:
<?xml-stylesheet type="text/xsl" href="..\..\dco.xsl"?>
<B id="20100096.001">
<V n="TYPE">APT</V>
<V n="STATUS">0</V>
<D id="20100096.001.01">
<V n="TYPE">Invoice</V>
<V n="STATUS">0</V>
<P id="TM000001">
<V n="TYPE">Main_Page</V>
<V n="STATUS">0</V>
<V n="Company">IBM</V>

AddVariableFloat method
The AddVariableFloat method adds a variable of type double and its value to an
object.

Syntax
VBScript
oDCO.AddVariableFloat (strName as String, fValue as Double) as Boolean
C#
bool AddVariableFloat(string strName, double fValue)

Applies to

All object types.

Arguments
strName
The variable name.
fValue
The value of the variable as a double.

Returns

Returns true if successful; returns false if unsuccessful.

Example

See AddVariable method.

AddVariableInt method
The AddVariableInt method adds an integer variable and its value to an object.
You can use this method when you need to pass values to custom actions.

Syntax
VBScript
oDCO.AddVariableInt (strName as String, nValue as Integer) as Boolean.
C#
bool AddVariableInt(string strName, int nValue)

Applies to

All object types.

Datacap object API 17

 Arguments
strName
The variable name
nValue
The value of the variable as an integer. This method also accepts a double, but
rounds the double to the nearest integer before the method assigns the value to
the object.

Returns

Returns true if successful; returns false if unsuccessful.

Example

See AddVariable method.

AddVariableString method
The AddVariableString method adds a string variable and its value to an object.
You can use this method when you need to pass values to custom actions.

Syntax
C#
bool AddVariableString(string strName, string strValue)
VBScript
oDCO.AddVariableString (strName as String, strValue as String) as Boolean

Applies to

All objects types.

Arguments
strName
The variable name.
strValue
The value of the variable as a string.

Returns

Returns true if successful; returns false if unsuccessful.

Example

See AddVariable method.

CheckIntegrity method
The CheckIntegrity method determines whether a batch conforms to the
document integrity rules that are specified in the Setup DCO file.

This method is typically used after the “CreateDocuments method” on page 20.

Syntax
VBScript
oDCO CheckIntegrity (pLastChecked as Object ) as Long.

18 IBM Datacap: DCO API Guide

C#
int CheckIntegrity(out object pLastChecked)

Arguments
pLastChecked
Variable to contain the last object that is checked in case of an error.

Returns

One of the following values:

0 Passed
1 Has more child objects than allowed by the max attribute.
2 Has fewer child objects than required by the min attribute.
3 Invalid member. A child object is not of a type that is supported by the
parent.
4 A child object is in the wrong position relative to other child objects as
specified by the pos attribute.

Applies to

All object types except character objects. When applied to a batch or document, the
method checks to the page level but not lower to a field or character object. When
applied to a page, the method checks fields on that page.

VBScript example

This example creates documents in a batch and applies integrity rules. If an error is
encountered, the code opens a message box that displays the type of error (1-4).
The message box also displays the object and the ID that are the source of the
error.
Dim DocInt
Dim LastChecked
Call oDCO.CreateDocuments
DocInt = oDCO.CheckIntegrity(LastChecked)
If DocInt > 0 Then
msgbox "Document Integrity problem = " & DocInt
msgbox "Detected at " & LastChecked.ObjectType & " type object ID " & LastChecked.ID
End If

C# example

This example populates the runtime and setup DCO objects, and checks the
integrity of the runtime batch.
m_oDCO.Read("C:\\Datacap\\APT\\batches\\20100096.001\\Verify.xml");
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");
Object pLastChecked = null;
int nRetVal = m_oDCO.CheckIntegrity(out pLastChecked);

Clear method
The Clear method removes all of the child objects of a runtime object, but does not
remove the object itself. For example, you can use this method when a document
contains corrupted or incorrect pages.

Datacap object API 19

 Syntax
VBScript
oDCO.Clear ( ) as Boolean.
C#
bool Clear()

Arguments

None.

Returns

Returns true if successful; returns false if unsuccessful.

Applies to

All object types.

VBScript example

This example instantiates a field-level object, uses Clear( ) to remove any child
objects, and then assigns a value to the ID property of the object.
Dim objFldTwo
Set objFldTwo = DCOSetup.GetNode(3,8)
objFldTwo.Clear
objFldTwo.ID = Tax2

CreateDocuments method
The CreateDocuments method uses the Setup DCO file to determine the document
type that is associated with each page in a batch and creates the required
document objects.

This method is normally called after the page identification task to assign pages to
documents within the runtime hierarchy.

Syntax
VBScript
oDCO.CreateDocuments ( ) as Boolean.
C#
bool CreateDocuments()

Applies to

Batch objects only.

Arguments

None.

Returns

Returns true if successful; returns false if unsuccessful.

20 IBM Datacap: DCO API Guide

 VBScript example

This example reads the Setup DCO file (BDOcs.xml), creates the document objects,
and confirms that the batch conforms to the document integrity rules.
Call oDCO.ReadSetup ("c:\Datacap\BDOcs\dco_APT\BDOcs.xml")
Call objBatch.CreateDocuments
Call objBatch.CheckIntegrity

CreateFields method
The CreateFields method creates a runtime field object for each field that is
specified within the corresponding page (or field) node in the document hierarchy.

For example, the 1040EZ page node in the following document hierarchy has rules
for three field objects. So, CreateFields( ) creates three field objects (Tax Year,
SSN, Spouse SSN).
<P type="1040EZ">
( <V n="ID">0</V>
<V n="TYPE">Page</V>
<V n="STATUS">0</V>
<V n="IMAGEFILE"></V>
<V n="DATAFILE"></V>
<V n="TEMPLATE IMAGE"></V>
<V n="MIN_TYPES">1</V>
<V n="MAX_TYPES">0</V>
<V n="rules"><in><r id="3" rs="4" /><r id="1" rs="5" /><r id="2" rs="6" /></in></V>
<F type="Tax Year" pos="0" min="0" max="0"/> <!-- Rule 0 -->
<F type="SSN" pos="0" min="0" max="0"/> <!-- Rule 1 -->
<F type="Spouse SSN" pos="0" min="0" max="0"/> <!-- Rule 2 -->
</P>

The child objects are used to hold the field data that is generated during the field
recognition process. This method ensures that a data file is created for the current
page when a batch is saved.

Syntax
VBScript
oDCO.CreateFields( ) as Boolean.
C#
bool CreateFields()

Arguments

None.

Returns

Returns true if successful; returns false if unsuccessful.

Applies to

Page objects or field objects.

DeleteChild method
The DeleteChild method removes the specified child object from the runtime DCO
object.

Datacap object API 21

 Syntax
VBScript
oDCO.DeleteChild (nIndex subscript as Long ) as Boolean
C#
bool DeleteChild(int nIndex)

Applies to

Any object

Arguments
nIndex
Index of the child to delete, where 0 is the first child.

Returns

Returns true if successful; returns false if unsuccessful.

C# example

This example removes the first field object of the runtime page object.
m_oDCOPage.DeleteChild(0);

DeleteValue method
The DeleteValue method deletes a data value and the corresponding confidence
level value of a character object.

In the following example, the fourth character contains a primary confidence level
value of 6, a first alternative confidence level of 8, and a second alternative
confidence level of 10. The fourth character also contains a primary character value
of 110, a first alternative character value of 52, and a second alternative character
value of 56.
<F id="Vendor">
<V n="TYPE">Vendor</V>
<V n="Position">0,0,0,0</V>
<V n="STATUS">1</V>
<C n="6,8,10" cr="0,0,0,0">83,49,53</C>
<C n="6,8,10" cr="0,0,0,0">116,50,54</C>
<C n="6,8,10" cr="0,0,0,0">105,51,55/C>
<C n="6,8,10" cr="0,0,0,0">110,52,56</C>
</F>

Syntax
VBScript
oDCO.DeleteValue (nIndexValue as Long) as Boolean
C#
bool DeleteValue(int nIndexValue)

Applies to

Character objects only.

22 IBM Datacap: DCO API Guide

Arguments
nIndexValue
The index of the value to be deleted, where 0 is the primary value, 1 is the first
alternative value, and so on.

Returns

Returns true if successful; returns false if unsuccessful.

C# example

This example deletes the first alternative character value and the first alternative
confidence level value.
m_oDCOChar.DeleteValue(1);

Character XML before: "\t<C cn=\"10,9\" cr=\"0,0,0,0\">83,99</C>\n"

Character XML after: "\t<C cn=\"10\" cr=\"0,0,0,0\">83</C>\n"

DeleteVariable method
The DeleteVariable method removes a variable, including variables such as TYPE
or STATUS that are installed with Datacap, and its value from a runtime DCO
object.

Syntax
VBScript
oDCO.DeleteVariable (lpszName as String ) as Boolean
C#
bool DeleteVariable(string lpszName)

Applies to

All objects.

Arguments
lpszName
The name of the variable to delete (case sensitive).

Returns

Returns true if successful; returns false if unsuccessful.

FindChild method
The FindChild method gets an interface to a child object that is referenced by ID
(name). You can use this method when you need to get the interface to a child
object for which you only know the name.

If the method references a field and the same ID is used within multiple page
objects, the method returns the first matching field.

Syntax
VBScript
oDCO FindChild (lpszName as String ) as Boolean.

Datacap object API 23

 C#
TDCOLib.DCO FindChild(string lpszName)

Arguments
lpszName
The ID (name) of the child object.

Returns

Returns an interface to the child object if successful; returns nothing if

unsuccessful.

Applies to

All objects.

VBScript example

This example returns the interface to the Client_ID field, and displays the interface
in a message box.
Dim objRTClFld
Set objRTClFld=oDCO.FindChild("Client_ID")
msgbox objRTClFld.ID

To retrieve a child object by index instead of ID, use “GetChild method” on page
31

C# example

This example returns an interface to the Vendor field:

m_oDCOField = m_oDCOPage.FindChild("Vendor");

FindChildIndex method
The FindChildIndex method returns the index of the specified child object that is
contained within a runtime DCO object. You can use this method when you know
the name of the child object, and you need to pass the position of the child object
to a variable.

Syntax
VBScript
oDCO FindChildIndex (lpszName as String ) as Long
C#
int FindChildIndex(string lpszName)

Applies to

All objects except batch.

Arguments
lpszName
The ID (name) of the child object.

24 IBM Datacap: DCO API Guide

Returns

Returns the index of the specified child object, where 0 is the first child; returns –1
if the specified child is not found.

VBScript example

This example returns the index of the Client_ID field, and passes the index to the
GetChild method.
Dim ClientFldVal
ClientFldVal = objRTSurvey.FindChildIndex("Client_ID")
Call objRTSurvey.GetChild(ClientFldVal)

C# example

This example returns the index of the Vendor field:

int nVendorIndex = m_oDCOPage.FindChildIndex("Vendor");

FindRouteChild method
The FindRouteChild method returns the interface to an object that is specified by
using the path through the document hierarchy. You use this method to save or
restore execution points during an action process.

The use of the path through a document hierarchy is shown in this example:
B/D(20100028.002.01)/P(TM000001)/F(Vendor)

Syntax
C#
TDCOLib.DCO FindRouteChild(string bszRoute)

Arguments
bszRoute
The route through the document hierarchy. (See the C# example.)

Returns

Returns an interface to the specified object; returns null if the route is invalid.

C# example

This example gets an interface to the Vendor field object on page TM000001:
m_oDCOField = m_oDCO.FindRouteChild("B/D(20100028.002.01)/P(TM000001)/F(Vendor)");

FindVariable method
The FindVariable method returns the index of a variable by using the ID (name)
of the variable. You can use this method when you need to pass the value of a
variable to another variable or action.

Syntax
VBScript
oDCO FindVariable (lpszName as String ) Variables Index subscript as Long
C#
int FindVariable(string lpszName)

Datacap object API 25

 Arguments
lpszName
The variable ID (name).

Returns

Returns the index of the specified variable, where 0 is the first variable; Returns –1
if the specified variable is not found.

Applies to

All objects.

VBScript example

This example returns the index of the Length variable, and displays the index in a
message box:
Dim VarLength
varLength = oDCO.FindVariable("Length")
if varLength > 0 then
msgbox oDCO.Variable(varLength)
end if

get_AltConfidenceString method
The get_AltConfidenceString method gets the confidence level of each character
in the referenced field. You can use this method when you need to pass the
confidence level of a string to a variable or action.

.NET only: For VBScript, use the“AltConfidenceString property” on page 6

instead.

The confidence level of each character is a digit from 0 (lowest confidence) to 9

(highest confidence). If the confidence level for a four-character field is 9999, each
of the 4 characters has a confidence level of 9. The XML code adds a value of 1 to
the confidence level so that the range in XML is 1-10. In the following example
XML setup node for the field, Vendor, the confidence level for the primary
character is 6. The confidence level for the first alternative character is 8, and the
confidence level for the second alternative is 10.
<F id="Vendor">
<V n="TYPE">Vendor</V>
<V n="Position">0,0,0,0</V>
<V n="STATUS">1</V>
<C cn="6,8,10" cr="0,0,0,0">83,49,53</C>
<C cn="6,8,10" cr="0,0,0,0">116,50,54</C>
<C cn="6,8,10" cr="0,0,0,0">105,51,55/C>
<C cn="6,8,10" cr="0,0,0,0">110,52,56</C>
</F>

Syntax
C#
string get_AltConfidenceString(int nIndex)

Applies to

Field objects only.

26 IBM Datacap: DCO API Guide

Arguments
nIndex
0 specifies the primary value. Where the field contains multiple recognition,
voting, or multiple-pass data entry values, 1 specifies the first alternative, 2
specifies the second alternative, and so on. (See the C# example.)

Returns

String containing the confidence level of each character. The returned digits are
always one less than the digits that are stored in the page XML file. (See the C#
example.)

C# example

The following example gets the confidence string for the second alternative.
string strAltConf = m_oVendorField.get_AltConfidenceString(2)

Referencing the XML code example for the Vendor field, the return value in this
case is 9999, because the returned value is always the stored value minus 1.

get_AltText method
The get_AltText method gets the primary or alternative character data that is
associated with a field.

.NET only: For VBScript, use “AltText property” on page 7 instead.

Primary and alternative values are stored in ASCII format in the page XML file, as
shown in the following example:
<F id="Vendor">
<V n="TYPE">Vendor</V>
<V n="Position">0,0,0,0</V>
<V n="STATUS">1</V>
<C n="6,8,10" cr="0,0,0,0">83,49,68</C>
<C n="6,8,10" cr="0,0,0,0">116,50,97</C>
<C n="6,8,10" cr="0,0,0,0">105,51,116/C>
<C n="6,8,10" cr="0,0,0,0">110,52,97</C>
</F>

For the fourth character, the primary text value is 110. The first alternative text
value is 52, and the second alternative text value is 97.

Syntax
C#
string get_AltText(int nIndex)

Applies to

Field objects only.

Arguments
nIndex
0 specifies the primary value. When the field contains multiple recognition,
voting, or multiple-pass data entry values, 1 specifies the first alternative, 2
specifies the second alternative, and so on.

Datacap object API 27

 Returns

String containing the alternative text.

Example

This example gets the second alternative text value from the Vendor field. Using
the page XML example, the returned string is 68,97,116,97. The root of the search
in this case is the page DCO.
string sAltText = m_oDCOPage.FindChild("Vendor").get_AltText(2);

get_CharConfidence method
The get_CharConfidence method gets the primary or alternative character data that
is associated with a field. You can use this method when you need to pass the
character data value to a variable or action.

.NET only: For VBScript, use “CharConfidence property” on page 8 instead.

This method gets the confidence level (cn) of the primary character value or
alternative value. Within the XML file, the confidence level is a digit from 1 (lowest
confidence) to 10 (highest confidence). In the following example XML setup node
for the field, Vendor, the character primary confidence level is 6. The first
alternative confidence level is 8, and the second alternative confidence level is 10.
<F id="Vendor">
<V n="TYPE">Vendor</V>
<V n="Position">0,0,0,0</V>
<V n="STATUS">1</V>
<C cn="6,8,10" cr="0,0,0,0">83,49,53</C>
<C cn="6,8,10" cr="0,0,0,0">116,50,54</C>
<C cn="6,8,10" cr="0,0,0,0">105,51,55/C>
<C cn="6,8,4" cr="0,0,0,0">110,52,56</C>
</F>

Syntax
C#
int get_CharConfidence(int nIndex)

Applies to

Character objects only,

Arguments
nIndex
0 specifies the primary value. When the field contains multiple recognition,
voting, or multiple-pass data entry values, 1 specifies the first alternative, 2
specifies the second alternative, and so on.

Returns

Integer representing the confidence level.

v get_CharConfidence returns the value as it is stored in the XML file. The
field-level functions, such as “get_AltConfidenceString method” on page 26,
return the internal representation, which is the stored value minus 1.

28 IBM Datacap: DCO API Guide

C# example

This example gets the confidence level of second alternative value of the fourth
character (index = 3) in the Vendor field. By using the example XML setup node,
the returned value is 4. The root of the search in this case is the page DCO.
nConfLevel = m_oDCOPage.FindChild("Vendor").GetChild(3).get_CharConfidence(2);

get_CharValue method
The get_CharValue method gets the ASCII data value of the primary character or
alternative character. You can use this method when you need to pass the character
data value to a variable or action.

.NET only: For VBScript, use “CharValue property” on page 8 instead.

In the following example XML setup node for the field, Vendor, the fourth
character has an ASCII data value of 110 for the primary character. Also, the ASCII
data value is 52 for the first alternative character and 56 for the second alternative
character.
<F id="Vendor">
<V n="TYPE">Vendor</V>
<V n="Position">0,0,0,0</V>
<V n="STATUS">1</V>
<C cn="6,8,10" cr="0,0,0,0">83,49,53</C>
<C cn="6,8,10" cr="0,0,0,0">116,50,54</C>
<C cn="6,8,10" cr="0,0,0,0">105,51,55/C>
<C cn="6,8,10" cr="0,0,0,0">110,52,56</C>
</F>

Syntax
C#
int get_CharValue(int nIndex)

Applies to

Character objects only.

Arguments
nIndex
0 specifies the primary value. Where the field contains multiple recognition,
voting, or multi-pass data entry values, 1 specifies the first alternative, 2
specifies the second alternative, and so on.

Returns

Integer representing the ASCII character value.

v To get the converted text of the entire field, use “get_AltText method” on page
27.

C# example

This example gets the second alternative value of the fourth character (index = 3)
in the Vendor field. By using the example XML setup node, the returned value is
56. The root of the search in this case is the page DCO.
nCharValue = m_oDCOPage.FindChild("Vendor").GetChild(3).get_CharValue(2);

Datacap object API 29

 get_OMRValue method
The get_OMRValue method gets the positions within the optical mark recognition
(OMR) field of the check boxes that are selected. You can use this method to pass
the positions to variables or actions, such as those that are used in verification
functions to confirm that check boxes are selected.

Each character in an OMR field is assigned the value 0 (ASCII 48 = not selected) or
1 (ASCII 49 = selected), and the resulting binary string is expressed as a decimal.
The following XML example is 000100, which equals 4 in decimal. So, the return
value is 4.
<F id="1a">
<V n="TYPE">1a</V>
<V n="Position">120,1025,853,1169</V>
<V n="STATUS">0</V>
<V n="DensityString">BAAVAA</V>
<C cn="10" cr="519,1132,559,1170">48</C> <!--48 indicates option not selected-->
<C cn="10" cr="563,1132,603,1170">48</C>
<C cn="10" cr="607,1132,647,1170">48</C>
<C cn="10" cr="652,1132,692,1170">49</C> <!--49 indicates option selected-->
<C cn="10" cr="697,1132,737,1170">48</C>
<C cn="10" cr="763,1132,803,1170">48</C>
</F>

Syntax
C#
int get_OMRValue(int nIndex)

Arguments
nIndex
0 specifies the primary value. When the field contains multiple recognition,
voting, or multi-pass data entry values, 1 specifies the first alternative, 2
specifies the second alternative, and so on.

Returns

The positions of the selected OMR check boxes (See the XML example.)

Applies to

OMR fields only.

get_Variable method
The get_Variable method gets the value of a referenced variable by using the ID
(name) of the variable. You can use this method to pass the value of a named
variable to an action for further processing.

.NET only: For VBScript, use “Variable property” on page 12 instead.

If the specified variable does not exist in the runtime object, but does exist in the
associated setup node object, the get_Variable method returns the value from the
setup node.

A number of variables are defined and installed with Datacap. For a listing of
these variables, see the Standard Variable Reference in IBM® Knowledge Center for
Datacap.

30 IBM Datacap: DCO API Guide

Syntax
C#
string get_Variable(string lpszName)

Arguments
lpszName
The name of the variable of which you need the value.

Applies to

All objects.

C# example

This example gets the value of the Company variable.

string CompanyName = m_oDCO.get_Variable("Company")

GetChild method
The GetChild method gets a referenced child object by using the index of the child
object. You can use this method to retrieve a field on a page when you know the
position, but not the name.

Syntax
VBScript
oDCO GetChild (nIndex as Long ) as Object
C#
TDCOLib.DCO GetChild(int nIndex)

Arguments
nIndex
The index of the child, where 0 is the first child

Returns

Returns the child object if successful; returns nothing otherwise.

Applies to

All objects.

VBScript example

This example gets the name of the first four fields on a page, and displays each
name in a message box.
Dim objViewField(4)
Dim I
i = 0
Do While i < 4
Set objViewField(i) = oDCO.GetChild(i)
msgbox objViewField(i).Text
i = i + 1
Loop

Datacap object API 31

 C# example

This example returns the first field object on the page:

m_oDCOField = m_oDCOPage.FindChild(0);
v You can retrieve a child object by ID instead of by index by using the
“FindChild method” on page 23.
v You can create a loop by using the GetChild method with the “NumOfChildren
method” on page 39 to get all of the child objects that are associated with an
object.

GetLastError method
The GetLastError method retrieves the text of the last error that is encountered
during a DCO read operation or write operation, and clears the error.

Before you call the GetLastError method, you can check whether an error string
exists by calling the “IsError method” on page 36.

Syntax
VBScript
objRTBatch.GetLastError as Boolean
C#
string GetLastError()

Arguments

None.

Returns

Returns true if successful; returns false if unsuccessful.

Applies to

Batch objects only.

VBScript example

This example
objBatch.BatchDir = c:\Datacap\MQSW\Batches
bStatus = objBatch.Write rulerunner.xml
If bStatus <> True Then
msgbox objBatch.GetLastError
End if

GetPosition method
The GetPosition method gets the position of a field or character on a page. You
can use this method for fields or characters that are located at identical positions
on multiple pages in a batch.
v For field objects, the position is defined by the Position variable of the field.
<V n="Position">0,0,0,0</V>
v For character objects, the position is defined by the cr attribute of the character.
<C cn="10" cr="0,0,0,0">83</C>

32 IBM Datacap: DCO API Guide

 Syntax
VBScript
oDCO.GetPosition(pnLeft as Long, pnTop as Long, nRight as Long, pnBottom as Long) as Boolean
C#
bool GetPosition(out object pnLeft, out object pnTop, out object pnRight, out object pnBottom)

Arguments
Argument Description
pnLeft Variable for the distance from the left side of
the page to the left edge of the object (in
pixels)
pnTop Variable for the distance from the top of the
page to top edge of the object (in pixels)
pnRight Variable for the distance from the left side of
the page to right edge of the object (in
pixels)
pnBottom Variable for the distance from the top of the
page to bottom edge of the object (in pixels)

Returns

Returns true if successful; returns false if unsuccessful.

Applies to

Field and character objects only.

VBScript example

This example gets a field's distance in pixels from the left, top, right, and bottom of
a page, and displays the values in a message box.
Dim L,T,R,B
oDCO.GetPosition "L,T,R,B"
msgbox "The field’s position is " L & "," & T & "," & R & "," & B

C# example

This example finds the Vendor field on a page, and gets the field's distance in
pixels from the left, top, right, and bottom of a page.
m_oDCOField = m_oDCOPage.FindChild("Vendor");
object pLeft, pTop, pRight, pBottom;
m_oDCOField.GetPosition(out pLeft, out pTop, out pRight, out pBottom);

GetRoute method
The GetRoute method gets the path through the document hierarchy to an object.

Use the argument to specify whether you want the path through the Runtime DCO
(True) or the Setup DCO (False).

Syntax
C#
string GetRoute(bool bRuntime)

Datacap object API 33

 Arguments
bRuntime
True for the Runtime DCO path; False for the Setup DCO path

Returns

String with the path.

Applies to

Any object type.

C# example

In the first example, GetRoute( ) returns the path through the Runtime DCO to the
Vendor field on page TM000001.
m_oDCO.Read("C:\\Datacap\\APT\\batches\\20100096.001\\Verify.xml");
m_oDCOPage = m_oDCO.FindChild("TM000001");
m_oDCOField = m_oDCOPage.FindChild("Vendor");
string strRoute = m_oDCOField.GetRoute(true);

The returned string has the following format: B/D(20100096.001.01)/P(TM000001)/

F(Vendor).

In the next example, GetRoute( ) returns the path through the Setup DCO to the
Details field.
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");
m_oDCOField = m_oDCO.FindChild("Details");
string returnString = m_oDCOField.GetRoute(false);

The returned string has the following format: B/D[Invoice]/P[Main_Page]/

F[Details].

GetVariableName method
The GetVariableName method gets the name (ID) of a variable from the index of the
variable. You can use this method when you know the position of a variable
within an object, but you do not know the name of the variable.

Syntax
VBScript
oDCO.VariableName(nIndex subscript as Long) as String
C#
string GetVariableName(int nIndex)

Applies to

All objects.

Arguments
nIndex
The index of the variable.

34 IBM Datacap: DCO API Guide

Returns

Returns the name of the variable; returns an empty string if a variable with the
specified index does not exist.

VBScript example

This example returns the name of the third variable in a field object.
Dim VarID
VarID = objField.VariableName(2)

GetVariableValue method
The GetVariableValue method gets the value of a referenced variable by using the
index of the variable.

Syntax
VBScript
oDCO.VariableName(nIndex subscript as Long) as Variant
C#
object GetVariableValue(int nIndex)

Applies to

All objects.

Arguments
nIndex
The index of the variable, the value of which you want to get, where 0 is the
first variable.

Returns

Returns an object that contains the value of the variable; returns nothing if there is
an error.

VBScript example

This example gets the value of the third variable in a field object, and displays the
value of the variable in a message box.
Dim VarVal
VarVal = objField.VariableValue(2)
msgbox VarVal

Tip: To get the value of a referenced variable by using the ID (name) of the
variable, use the “Variable property” on page 12 property.

C# example

This example gets the value of the 10th variable that is defined on page 1 of the
runtime batch.
object oVarValue = m_oDCO.FindChild("TM000001").GetVariableValue(9);

Tip: To get the value of a referenced variable by using the ID (name) of the
variable, use the “get_Variable method” on page 30 method.

Datacap object API 35

 IsError method
The IsError method indicates whether an error occurred during a prior Read
operation or Write operation.

If IsError returns true, use the “GetLastError method” on page 32 to get the
associated error message. The IsError flag is cleared upon calling GetLastError.

Syntax
VBScript
oDCO.IsError as Boolean
C#
bool IsError()

Applies to

Batch object only.

Arguments

None.

Returns

Returns true if the IsError flag is set; Returns false if the IsError flag is not set.

VBScript example

This example checks if there are any errors for the Rulerunner task. If an error is
found, it displays the error to a message box.
objBatch.BatchDir = "c:\Datacap\MQSW\Batches"
’ clear any old errors
sOldError = objBatch.GetLastError
Call objBatch.Write ("rulerunner.xml")
If objBatch.IsError <> 0 Then
msgbox objBatch.GetLastError
End if

IsRoute method
The IsRoute method indicates whether the specified path is the valid path through
the runtime hierarchy for an object.

Syntax
C#
bool IsRoute(string lpszRoute)

Arguments
lpszRoute
The path through the runtime hierarchy. (See the C# example.)

Returns

Returns true if the specified path matches the path for this object; returns false if
the specified path does not match the path for this object.

36 IBM Datacap: DCO API Guide

C# example

The following example gets an interface to the Vendor field and then uses
GetRoute to confirm the path.
m_oDCOField = m_oDCO.FindChild("TM000001").FindChild("Vendor");
bool bRouteOK = m_oDCOField.IsRoute("B/D(20100028.002.01)/P(TM000001)/F(Vendor)");

IsValid method
The IsValid method confirms that the interface of a DCO object is valid and is
connected to an actual object.

Syntax
VBScript
oDCO.IsValid as Boolean
C#
bool IsValid()

Arguments

None.

Returns

Returns true if the interface is valid; returns false if the interface is invalid.

Applies to

Field objects only.

C# example

The following call returns False:

TDCOLib.IDCO m_oNullDCOObject = new TDCOLib.DCOClass();
bResult = m_oNullDCOObject.IsValid();

MoveChild method
The MoveChild method moves a child of a runtime DCO object to a different index
location. You can use this method to reorganize or correct batches, documents,
pages, or fields.

Description

For example, MoveChild(0,2) moves the object at position 0 to position 2. When

you use this method, MoveChild reindexes the other child objects, as needed.
Table 1. Example implementation of MoveChild method
Index Value Index Value
0 One 0 Two
MoveChild(0, 2)
1 Two 1 Three
2 Three 2 One
Before After

Datacap object API 37

 Syntax
VBScript
oDCO.MoveChild(nOldIndex as Long,nNewIndex as Long) as Boolean
C#
bool MoveChild(int nOldIndex, int nNewIndex)

Arguments
nOldIndex
Index value of the current position, of the child object, where 0 is the first child
nNewIndex
Index value of the new position of the child object

Returns

True if successful; False otherwise

Applies to

All objects

C# Example

This example moves the first field on page TM000001 to the third position.
m_oDCO.FindChild("TM000001").MoveChild(0, 2);

See also

“FindChild method” on page 23, “MoveIn method”

MoveIn method
The MoveIn method moves the specified runtime DCO object from the current
parent to a different parent.

Syntax
VBScript
oDCO.MoveIn(pNewParent as Object, nIndex as Long) as Boolean.
C#
bool MoveIn(object pNewParent, int nIndex)

Applies to

All objects

Arguments
pNewParent
A valid runtime DCO object as the new parent
nIndex
The index value for the child in the new parent. An index value of -1 places
the child at the end.

38 IBM Datacap: DCO API Guide

Returns

True if successful; False otherwise

C# Example

The following example moves the Vendor field from page TM000002 to the end of
page TM000001.
m_oDCOField = m_oDCO.FindChild("TM000002").FindChild("Vendor");
m_oDCOPage = m_oDCO.FindChild("TM000001");
m_oDCOField.MoveIn(m_oDCOPage, -1);

See also

“MoveChild method” on page 37

NumOfChildren method
The NumOfChildren method returns the number of child objects that is associated
with the runtime DCO object.

Syntax
VBScript
oDCO.NumOfChildren as Long
C#
int NumOfChildren()

Arguments

None

Returns

The number of child objects that is associated with this object.

Applies to

All objects

VBScript Example
Dim CntPgChildren
CntPgChildren = oDCO.NumOfChildren
msgbox "Page 1 has " & CntPgChildren & " children"

C# Example

This example returns the number of fields on page TM000001.

int nNumFields = m_oDCO.FindChild("TM000001").NumOfChildren();

See also

“GetChild method” on page 31

NumOfVars method
The NumOfVars method returns the number of variables that is associated with the
runtime DCO object.

Datacap object API 39

 Syntax
VBScript
oDCO.NumOfVars as Long
C#
int NumOfVars()

Arguments

None

Returns

A count of the variables of the object

Applies to

All objects

Example

This example returns the number of variables that is associated with the Vendor
field.
int nNumVars = m_oDCO.FindChild("TM000001").FindChild("Vendor").NumOfChildren();

See also

“GetVariableValue method” on page 35, “GetVariableName method” on page 34

ObjectType method
The ObjectType method returns a numeric value that indicates the object type.

Syntax
VBScript
oDCO.ObjectType as Long
C#
int ObjectType()

Arguments

None.

Returns

A value that indicates the object type (0=batch, 1=document, 2=page, 3=field,
4=character).

Applies to

All objects

40 IBM Datacap: DCO API Guide

Example
VBScript
If oDCO.ObjectType <> 2 Then
msgbox "The object is not a page!"
End if

Parent
The Parent method returns the parent of the runtime DCO object.

Syntax
VBScript
oDCO.Parent as oDCO Object
C#
TDCOLib.DCO Parent()

Arguments

None

Returns

The parent object, or nothing (null) if the method is applied to a batch object.

Applies to

All objects except batch

Example
VBScript
If oField.Parent = Nothing Then
msgbox "Cannot access the page!"
End if

Read method
The Read method reads the runtime information from a Runtime DCO file or a
page data file, and writes the information into the DCO object.

This method can read a Runtime DCO file (for example, Verify.xml), or a page
data file (for example, tm000001.xml) of an application. Because new DCO objects
are created as batch objects by default, you must first create a child object of type
page before using the Read method to directly read the page data file. Runtime
information files are located in the batches folder of an application, and include
the data that are denoted by the following properties:
|--m_oDCO
|--BatchDir(string)
|--BatchPriority(int)
|--ConfidenceString(string
|--ID(string)
|--ImageName(string)
|--Options(string)
|--Status(int)
|--Text(string)
|--Type(string)
|--XML(string)
|--AltConfidenceString(string)*
|--AltText(string)*

Datacap object API 41

 |--CharConfidence(int)*
|--CharValue(int)*
|--OMRValue(int)*
|--Variable(string)*

* These extended properties are accessible directly from VBScript or through the
corresponding get method or set method in .NET.

Syntax
VBScript
oDCO.Read (FilePath as String) as Boolean
C#
bool Read(string lpszFileName)

Applies to

Batch or page objects only.

Arguments
lpszFileName
The full path and name of the file to read.

Returns

Returns true if successful; returns false if unsuccessful.

Example

The first example reads the Runtime DCO file into an existing batch level DCO
object:
m_oDCOBatch.Read("C:\\Datacap\\APT\\batches\\20100096.001\\Verify.xml");

The second example creates a runtime DCO object with a page data file only:
TDCOLib.DCO m_oDCO = new TDCOLib.DCO();
TDCOLib.DCO m_oDCOPage = new TDCOLib.DCO();
m_oDCOPage = m_oDCO.AddChild(2, "NewChildPage", -1);
m_oDCOPage.Read("C:\\Datacap\\APT\\batches\\20100096.001\\tm000001.xml");

If there is an error, the “IsError method” on page 36 returns true and the
“GetLastError method” on page 32 returns the last error message.

ReadSetup method
The ReadSetup method reads the document hierarchy setup information from the
specified Setup DCO file and writes the information into the Setup object and
SetupNode object.

This sample file shows properties that the ReadSetup method can process.
|--Setup
|--Path(string)
|--DictionaryName*
|--Value*
|--Word*

|--SetupNode
|--MaxNumOfChildren(int)
|--MinNumOfChildren(int)
|--Name(string)

42 IBM Datacap: DCO API Guide

 |--ObjectType(int)
|--RuleChildName*
|--RuleMaxNumber*
|--RuleMinNumber*
|--RuleObjectType*
|--RulePosition*
|--Variable*
|--VariableName*
|--VariableValue*

* Extended properties that are accessible directly from VBScript or through the
corresponding get method or set method in .NET.

Syntax
VBScript
oDCO.ReadSetup (FileName as String) as Boolean
C#
bool IDCO.ReadSetup(string lpszFileName)

Arguments
lpszFileName
Full path and name for the Setup DCO XML file. (See the following example.)

Returns

Returns true if successful; returns false if unsuccessful.

C# example

This example populates the Setup object and SetupNode object from APT.XML,
changes the name of the first dictionary to Datacap, and writes the objects back to
the Setup DCO.
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");
m_oDCO.SetupObject().set_DictionaryName(0, "Datacap");
m_oDCO.WriteSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");

SetPosition method
The SetPosition method sets the position of the runtime field or character object
on the page. This method is useful for making corrections to zonal recognition on a
page.
v For field objects, the position is defined by the Position variable of the field.
<V n="Position">0,0,0,0</V>
v For character objects, the position is defined by the cr attribute of the character.
<C cn="10" cr="0,0,0,0">83</C>

Syntax
VBScript
oDCO.SetPosition (nLeft as Long, nTop as Long, nRight as Long,
nBottom as Long) as Boolean
C#
bool SetPosition(int nLeft, int nTop, int nRight, int nBottom)

Applies to

Field or character objects.

Datacap object API 43

 Arguments
nLeft
Distance from the left side of the page to the left edge of the object (in pixels)
nTop
Distance from the top of the page to the top edge of the object (in pixels)
nRight
Distance from the left side of the page to the right edge of the object (in pixels)
nBottom
Distance from the top of the page to the bottom edge of the object (in pixels)

Returns

Returns true if successful; returns false if unsuccessful.

Example
VBScript
Call oDCO.SetPosition (115, 450, 138, 400)

SetupNode method
The SetupNode method accesses the SetupNode object that is associated with the
current object. You can use this method to get the name of the object in the
document hierarchy that corresponds to the object in the runtime batch hierarchy.

Syntax
VBScript
oDCO.SetupNode as Object
C#
TDCOLib.DCOSetupNode SetupNode()

Arguments

None.

Returns

The setup object that corresponds to this runtime object. If you created this object
dynamically at run time, and the object is not based on a SetupNode, then the
method returns nothing (null).

Applies to

All objects.

C# example

This example populates the batch level Setup object and SetupNode object from
the Setup DCO file and points m_oDCOSetupNode to the SetupNode object of the
Vendor field.
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");
TDCOLib.DCOSetupNode m_oDCOSetupNode = m_oDCO.FindChild("TM000001").FindChild("Vendor").SetupNode();

44 IBM Datacap: DCO API Guide

SetupObject method
The SetupObject method returns the Setup object that is associated with the
current batch-level runtime DCO object. You can use this method when a batch
contains unidentified pages and you need to modify the runtime batch hierarchy.

Syntax
VBScript
oDCO.SetupObject as Object
C#
TDCOLib.DCOSetup SetupObject()

Applies to

Batch objects only.

Arguments

None.

Returns

The setup object.

C# example

This example populates the batch level Setup and SetupNode objects from the
Setup DCO file and points m_oDCOSetup to the Setup object:
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");
TDCOLib.DCOSetup m_oDCOSetup = m_oDCO.SetupObject();

For a complete example, see ReadSetup.

set_AltConfidenceString
The set_AltConfidenceString method sets the confidence level of each character in
the referenced field.

Description

Important: .NET only. For VBScript, use the AltConfidenceString property instead.

The confidence level of each character is a digit from 0 (lowest confidence) to 9

(highest confidence). For example, if the confidence level for a four-character field
is 9999, each of the 4 characters has a confidence level of 9.
<F id="Vendor">
<V n="TYPE">Vendor</V>
<V n="Position">0,0,0,0</V>
<V n="STATUS">1</V>
<C cn="6,8,10" cr=0,0,0,0">83,49,53</C>
<C cn="6,8,10" cr=0,0,0,0">116,50,54</C>
<C cn="6,8,10" cr=0,0,0,0">105,51,55</C>
<C cn="6,8,10" cr=0,0,0,0">110,52,56</C>
</F>

In the sample XML file, the primary confidence level is 6. The first alternative
confidence level is 8, and the second alternative confidence level is 10. The value
that is stored is always the value set + 1.

Datacap object API 45

 Syntax
C#
void set_AltConfidenceString(int nIndex, string pVal)

Applies to

Field objects only

Arguments
nIndex
0 specifies the primary value. Where the field contains multiple recognition,
voting, or multipass data entry values, 1 specifies the first alternative, 2
specifies the second alternative, and son on. (See the following example).
pVal
A string that contains containing the confidence level of each character (for
example, "9999"). The digits that are stored in the page XML file are always
one greater than the digits you specify in pVal (See the following example).

Comments
v To set or get the primary confidence level, you can also use the ConfidenceString
property.
v To set or get the confidence level on individual characters, use
set_CharConfidence or get_CharConfidence.

Example
C#
The following example sets the confidence string for the second alternative.
m_oVendorField.set_AltConfidenceString(2, "9999")

The value 9999 is stored as 10,10,10,10 because the value that is stored is
always the value set + 1.

See also

get_AltConfidenceString, set_AltText

set_AltText method
The set_AltText method sets the primary character data or alternative character
data that is associated with a field. You can use this method for multi-pass
verification tasks and double-blind data entry tasks.

.NET restriction: For VBScript, use the AltText property instead.

The set_AltText method sets primary and alternative values that are stored in the
page XML file in ASCII format, as shown in the following example:
F id="Vendor">
<V n="TYPE">Vendor</V>
<V n="Position">0,0,0,0</V>
<V n="STATUS">1</V>
<C cn="6,8,10" cr="0,0,0,0">83,49,68</C>
<C cn="6,8,10" cr="0,0,0,0">116,50,97</C>
<C cn="6,8,10" cr="0,0,0,0">105,51,116</C>
<C cn="6,8,10" cr="0,0,0,0">110,52,97</C>
</F>

46 IBM Datacap: DCO API Guide

In the sample XML file, the primary text value for the fourth character is 110. The
first alternative text value is 52, and the second alternative text value is 97.

Syntax
C#
void set_AltText(int nIndex, string pVal)

Applies to

Field objects only.

Arguments
nIndex
0 specifies the primary value. Where the field contains multiple recognition,
voting, or multi-pass data entry values, 1 specifies the first alternative, 2
specifies the second alternative, and so on.
pVal
String containing the alternative text.

C# example

This example sets the alternative value 1 in the field object.

m_oField.set_AltText(1, "Hello");
v Use the set_AltConfidenceString method to specify a confidence level other
than the default value of 9 (high confidence).
v Use the Text property to set the primary field value.
v Use the set_CharValue method to set individual characters.

set_CharConfidence method
The set_CharConfidence method sets the confidence level for the primary value or
of the alternative value of a character in a field.

.NET Restriction: For VBScript, use the CharConfidence property instead.

The confidence level is determined by the cn attribute. Within the page XML file,
the confidence level is a digit from 1 (lowest confidence) to 10 (highest confidence).
In the following XML sample, the primary confidence level of the fourth character
is 6. The first alternative confidence level is 8, and the second alternative
confidence level is 4.
F id="Vendor">
<V n="TYPE">Vendor</V>
<V n="Position">0,0,0,0</V>
<V n="STATUS">1</V>
<C cn="6,8,10" cr="0,0,0,0">83,49,53</C>
<C cn="6,8,10" cr="0,0,0,0">116,50,54</C>
<C cn="6,8,10" cr="0,0,0,0">105,51,55</C>
<C cn="6,8,4" cr="0,0,0,0">110,52,56</C>
</F>

Syntax
C#
void set_CharConfidence(int nIndex, int pVal)

Datacap object API 47

 Arguments
nIndex
0 specifies the primary value. Where the field contains multiple recognition,
voting, or multipass data entry values, 1 specifies the first alternative, 2
specifies the second alternative, and so on.
pVal
The confidence value (1-10), as stored in the XML file.

This method sets the value as it is stored in the XML file (1-10). For field-level
functions such as set_AltConfidenceString, you specify the internal representation,
which is the stored value minus 1.

C# example

This example sets the confidence level of second alternative value of the fourth
character (index = 3) in the Vendor field. The root of the search in this case is the
page DCO.
m_oDCOPage.FindChild("Vendor").GetChild(3).set_CharConfidence(2, 4);

set_CharValue method
The set_CharValue method sets the ASCII data value of the primary character or
alternative character.

.NET Restriction: For VBScript, use the CharValue instead.

To set the text of the entire field, use the set_AltText. In the following sample XML
file, the primary value for the fourth character is 110. The first alternative value is
52, and the second alternative value is 56.
F id="Vendor">
<V n="TYPE">Vendor</V>
<V n="Position">0,0,0,0</V>
<V n="STATUS">1</V>
<C cn="6,8,10" cr="0,0,0,0">83,49,53</C>
<C cn="6,8,10" cr="0,0,0,0">116,50,54</C>
<C cn="6,8,10" cr="0,0,0,0">105,51,55</C>
<C cn="6,8,10" cr="0,0,0,0">110,52,56</C>
</F>

Syntax
C#
void set_CharValue(int nIndex, int pVal)

Applies to

Character objects only.

Arguments
nIndex
0 specifies the primary value. Where the field contains multiple recognition,
voting, or multipass data entry values, 1 specifies the first alternative, 2
specifies the second alternative, and so on.

Returns

Nothing.

48 IBM Datacap: DCO API Guide

C# example

This example sets the second alternative value of the fourth character (index = 3)
in the Vendor field. The root of the search in this case is the page DCO.
m_oDCOPage.FindChild("Vendor").GetChild(3).set_CharValue(2, 56);

set_OMRValue
The set_OMRValue method sets the character values within the OMR field to
indicate whether a check box is selected.

Description

Each character is assigned the value 0 (ASCII 48; not selected) or 1 (ASCII 49;
selected) and the resulting binary string is expressed as a decimal. The following
XML example represents a row of six check boxes and the binary string is 001000,
which equals 8 in decimal. So, the required value is 8.
<F id="1a">
<V n="TYPE">1a</V>
<V n="Position">120,1025,853,1169</V>
<V n="STATUS">0</V>
<V n="DensityString">BAAVAA</V>
<C cn="10" cr="519,1132,559,1170">48</C>
<-- 48 indicates option not selected
<C cn="10" cr="563,1132,603,1170">48</C>
<C cn="10" cr="607,1132,647,1170">48</C>
<C cn="10" cr="652,1132,692,1170">49</C>
<-- 49 indicates option selected
<C cn="10" cr="697,1132,737,1170">48</C>
<C cn="10" cr="763,1132,803,1170">48</C>
</F>

Syntax
C#
void set_OMRValue(int nIndex, int pVal)

Arguments
nIndex
0 specifies the primary value. Where the field contains multiple recognition,
voting, or multi-pass data entry values, 1 specifies the first alternative, 2
specifies the second alternative, and so on.
pVal
A number that reflects the state of each OMR check box. (See the XML
example.)

See also

get_OMRValue, get_CharValue

set_Variable method
The set_Variable method sets the value of a referenced variable by using the
name of the variable.

Description

.NET restriction: For VBScript, use the Variable instead.

If you set a variable that does not exist in the runtime object, this method
automatically creates the variable.

Datacap object API 49

 Datacap uses a number of standard variables. For a listing of these variables, see
the Standard Variable Reference in this IBM Knowledge Center.

Syntax
C#
string set_Variable(string lpszName, string pVal)

Arguments
lpszName
The name of the variable, the value of which you want to set.
pVal
The value.

Applies to

All objects.

C# example

The following example assigns the value IBM to the variable Company.
m_oDCO.set_Variable("Company", "IBM")

The method either sets the value if the variable exists, or creates a new variable
with the specified value. The following sample XML node shows the resulting
variable and the value:
<V n="Company">IBM</V>

Write method
The Write method saves the runtime batch object to a batch file, or a page object to
a page file. When it writes a batch object, this method also writes all of the child
objects, including documents, pages, and fields.

When you create a batch with an application that you developed in Datacap
Studio, Datacap saves the batch as an XML file. The file is named after the last
completed task in the workflow of the application. When you create a batch with
an application that you developed outside of Datacap Studio, you can use the
Write method to save the batch object to a file.

Syntax
VBScript
oDCO.Write(lpszFileName as String) as Boolean
C#
bool Write(string lpszFileName)

Applies to

Batch or page objects.

Arguments
lpszFileName
The full path and name of the output file.

50 IBM Datacap: DCO API Guide

 Returns

Returns true if successful; returns false if unsuccessful.

C# example

This example writes the 20030086.003 batch object and the page objects of the
batch to Verify.xml file.
bStatus = objBatch.Write ("c:\Datacap\MQSW\Batches\20030085.003\Verify.xml")
objPage.CreateFields
bStatus = objPage.Write ("c:\Datacap\BDOcs\Batches\20030085.003" & objPage.ID)

WriteSetup method
The WriteSetup method writes the Setup object and SetupNode objects to the
Setup DCO file. You use this method after you read a setup DCO file from an
external location.

Syntax
VBScript
oDCO.WriteSetup(FileName as String) as Boolean
C#
bool WriteSetup(string lpszFileName)

Applies to

Batch objects only.

Arguments
lpszFileName
Full path and name for the Setup DCO file (for example, C:\Datacap\APT\
dco_APT\APT.xml).

Returns

Returns true if successful; Returns false if unsuccessful.

Example

See ReadSetup for an example.

DCOSetup API
The DCOSetup APIs include properties and methods that you can use to create or
modify the document hierarchy. Datacap saves the document hierarchy as the
setup DCO file in XML format, for example, C:\Datacap\application
name\dco_application name\application name.xml.

In the setup DCO file, each document, page, and field type is defined as a separate
node, as shown in this sample XML code:
<?xml-stylesheet type="text/xsl" href="..\..\dco.xsl"?>
<S>
<B type="batch_name">
1

[Variables and rules associated with this batch]

</B>

Datacap object API 51

 <D type="document_name">
2

[Variables and rules associated with this document]

</D>

[more document types]

<P type="page_name">
3

[Variables and rules associated with this page]

</P>

[more page types]

<F type="field_name">
4

[Variables and rules associated with this field]

</F>

[more field types]

<DICT n="dict_name">
5

[Terms (words and values) in this dictionary]

</DICT>

[more document types]

1 Setup node for the batch

2 Setup node for the document

3 Setup node for the page

4 Setup node for the field

5 Setup node for the dictionary

When you use an API to populate the DCOSetup object with child nodes from the
Setup DCO file, each node becomes a separate DCOSetupNode object.

You use the DCOSetup APIs to modify the DCOSetup object and use the
DCOSetupNode APIs to modify the child DCOSetupNode objects.

52 IBM Datacap: DCO API Guide

 DCO object

\dco_<app_name> DCOSetup
object Custom
<B> application
<D>
DCOSetup API
<P>
<F>
Setup DCO
DCOSetupNode DCOSetupNode
object object

DCOSetupNode API DCOSetupNode API

When you create a runtime DCO object (m_oDCO in this example), Datacap
automatically creates a corresponding DCOSetup object and updates the setup
DCO file.
TDCOLib.IDCO m_oDCO = new TDCOLib.DCOClass();

Runtime DCO
object

DCO API

DCOSetup
object

DCOSetup API
You can use the SetupObject method to access the DCOSetup object either directly
or by first obtaining an interface to the DCOSetup object:
Accessing the DCOSetup Object Directly
m_oDCO.SetupObject().AddNode(1,"NewDoc1");
Accessing the DCOSetup object through an interface
TDCOLib.DCOSetup m_oDCOSetup = m_oDCO.SetupObject();
//Obtaining an interface

m_oDCOSetup.AddNode(1,"NewDoc2");
//Accessing the DCOSetup object through the interface

The DCOSetup object is initially null. You populate the DCOSetup object and the
child objects in one of the following ways:
Use the ReadSetup method from an existing Setup DCO file
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");

The ReadSetup method parses the XML file and creates all of the child
DCOSetupNode objects, such as documents, pages, and fields, that are
defined for the document hierarchy.
Use the AddNode method
m_oDCO.SetupObject().AddNode(1,"NewDoc1");

Datacap object API 53

 If you are creating a Setup DCO or modifying an existing Setup DCO, you can
write the memory resident object hierarchy to disk by using the WriteSetup
method:
m_oDCO.WriteSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");

DCOSetup properties
You can use DCOSetup properties to access DCOSetup objects and modify
metadata, including dictionary paths, terms, names, and key values that are used
in verification tasks.

DictionaryName property
The DictionaryName property sets or gets the name of a dictionary in the Setup
DCO.

VBScript only: Because extended properties are not supported through the C#
.NET Interop interface, you must instead use the “set_DictionaryName method” on
page 64 or the “get_DictionaryName method” on page 59.

Syntax
VBScript
oSO.DictionaryName(DictIndex as Long) as String

Arguments
DictIndex
The number that indicates the location of the dictionary in the setup DCO,
with 0 being the first dictionary, 1 being the second, and so on.

Type

Read and write.

VBScript example

This example sets the name of the first dictionary in the setup DCO file to Vendors
and the name of the second dictionary to Customers.
oSO.DictionaryName(0) = "Vendors"
oSO.DictionaryName(1) = "Customers"

Path property
The Path property sets or gets the path to the setup DCO file.

Syntax
VBScript
oSO.Path as String
C#
string Path { set; get; }

Type

Read and write.

54 IBM Datacap: DCO API Guide

VBScript example

This example sets the path to the BDCcs.xml setup DCO file:
oSO.Path = "c:\Datacap\BDOcs\dco_BDOcs\BDOcs.xml"

Value property
The Value property sets or gets the key value of a dictionary term in the Setup
DCO file. You can use this property when you need to pass a value to a variable.

VBScript restriction: Because extended properties are not supported through the
C# .NET Interop interface, you must instead use the “set_Value method” on page
65 or the “get_Value method” on page 59.

The following example defines one dictionary with four words, where
RoutingInstructions is the dictionary name. The text in each set of quotation
marks is the key value that is associated with the word that follows it. Datacap
uses the key value to identify words in the dictionary that are displayed to an
operator during a verification task. Datacap populates the associated field with the
word that the operator selects.
<DICT n="RoutingInstructions">
<W v="None">None</W>
<W v="Delete">Delete</W>
<W v="Rescan">Rescan</W>
<W v="Review">Review</W>
</DICT>

Syntax
VBScript
oSO.Value(nDictionary subsript as Long, nIndex subscript as Long) as String

Type

Read and write.

Arguments
nDictionary
The index of the dictionary in the setup object, where 0 is the first dictionary.
nIndex
The index of the entry in the dictionary, where 0 is the first entry.

VBScript example

This example sets the key value of the seventh entry in the first dictionary to 123.
oSO.Value(0,6) = "123"

Word property
The Word property sets or gets the word value in a dictionary term in the setup
DCO file. You can use this property to pass a value to a variable.

VBScript restriction: Because extended properties are not supported through the
C# .NET Interop interface, you must instead use set_Word or get_Word.

The following sample setup DCO XML file defines one dictionary with four words,
where RoutingInstructions is the dictionary name. The text in each set of
quotation marks is the key value that is associated with the word that follows it.

Datacap object API 55

 <DICT n="RoutingInstructions">
<W v="None">None</W>
<W v="Delete">Delete</W>
<W v="Rescan">Rescan</W>
<W v="Review">Review</W>
</DICT>

Datacap uses the key value to identify words in the dictionary that are displayed
to an operator during a verification task. Datacap populates the associated field
with the word that the operator selects.

Syntax
VBScript
oSO.Word(nDictionary as Long, nIndex as Long) as String

Type

Read and write.

Arguments
nDictionary
The index of the dictionary within the Setup object, where 0 is the first
dictionary.
nIndex
The index of the entry within the dictionary, where 0 is the first entry.

VBScript example

This example compares the value of the VendorName field to the seventh entry in
the first dictionary in the Setup DCO file:
oSO.Word(0,6) = "FreightLiners"
If VendorName = oSO.Word(0,6) then...

DCOSetup methods
DCOSetup methods enable access to DCO nodes and dictionaries. You can use
DCOSetup methods to obtain and modify metadata, including names, values,
terms, and quantities. You can also use these methods to create or delete nodes.

AddNode method
The AddNode method adds a node to the Setup DCO object at the end of the section
for the type specified (batch, document, page, field, character).

Syntax
VBScript
oSO.AddNode (Type as Long, Name as String) as Boolean
C#
bool AddNode(int nType, string lpszNodeName)

Arguments
nType
Specify one of the following number values to indicate the type of node to
add:
0 = Batch

56 IBM Datacap: DCO API Guide

 1 = Document
2 = Page
3 = Field
4 = Character
lpszNodeName
The name of the new node. This name is referenced as the node's type
attribute in the Setup DCO file, as shown in this example:
<D type="NewDocNode">

Returns

Returns true if successful; returns false if unsuccessful.

C# example

The following example adds a document node to the Setup DCO:

m_oDCOSetup.AddNode(1, "NewDocNode");

The new node inherits its attributes and variables from the object template in the
file C:\Datacap\dcshared\dcotemp.xml. The resulting Setup object is shown in this
sample:
<D type="NewDocNode">
<V n="ID">0</V>
<V n="TYPE">Document</V>
<V n="STATUS">0</V>
<V n="DOC DATA">0</V>
<V n="MIN_TYPES">0</V>
<V n="MAX_TYPES">0</V>
</D>

DeleteNode method
The DeleteNode method reads the value of the nIndex argument and deletes the
corresponding node from the Setup DCO.

Syntax
VBScript
oSO.DeleteNode(nType as Long, nIndex subscript as Long) as Boolean
C#
bool DeleteNode(int nType, int nIndex)

Arguments
nType
The type of the node to delete:
0 = Batch
1 = Document
2 = Page
3 = Field
4 = Character
nIndex
The index of the node to delete, where 0 is the first node of the specified type.

Datacap object API 57

 Returns

Returns true if successful; returns false if unsuccessful.

C# example

The following example deletes the third document node (type = 1, index = 2) from
the Setup DCO:
m_oDCOSetup.DeleteNode(1, 2);

DeleteNodeByName Method
The DeleteNodeByName method deletes a node from the Setup DCO by referencing
the node's name.

Description

DeleteNodeByName references a node through the node's name, and deletes the
node.

Syntax
VBScript
oSO.DeleteNode(nType as Long, lpszName as String) as Boolean
C#
bool DeleteNodeByName(int nType, string lpszName)

Arguments
nType
The type of the node to delete:
0 = Batch
1 = Document
2 = Page
3 = Field
4 = Character
lpszName
The name of the node to delete, as referenced in the node's type attribute:
<D type="NewDocNode">

Returns

True if successful; False otherwise.

VBScript Example
Dim OK
OK = oSO.DeleteNodeByName(3, "Total")
msgbox OK
msgbox "The number of fields remaining is " & oSO.NumOfNodes(3)

C# Example

The following example deletes the document node, "NewDocNode," from the
Setup DCO:
m_oDCOSetup.DeleteNode(1, "NewDocNode");

58 IBM Datacap: DCO API Guide

See Also

“DeleteNode method” on page 57, “AddNode method” on page 56

get_DictionaryName method
The get_DictionaryName method gets the name of a dictionary from the Setup
DCO.

.NET restriction: For VBScript, use the “DictionaryName property” on page 54

instead.

Syntax
C#
string get_DictionaryName(int nDictionary)

Arguments
nDictionary
The index of the dictionary within the Setup DCO, where 0 is the first
dictionary.

Returns

The name of the dictionary.

C# example

This example gets the name of the first dictionary from the Setup DCO file,
APT.XML:
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");
string strDictName = m_oDCO.SetupObject().get_DictionaryName(0);

get_Value method
The get_Value method gets the key value of a term in a dictionary from the Setup
DCO.

.NET restriction: For VBScript, use the “Value property” on page 55 instead.

In this sample XML code, RoutingInstructions is the name of the dictionary,

which is followed by the key value and word pairs ("None",None, and so on).
<DICT n="RoutingInstructions">
<W v="None">None</W>
<W v="Delete">Delete</W>
<W v="Rescan">Rescan</W>
<W v="Review">Review</W>
</Dict>

Syntax
C#
string get_Value(int nDictionary, int nIndex)

Arguments
nDictionary
The index of the dictionary within the Setup object, where 0 is the first
dictionary.

Datacap object API 59

 nIndex
The index of the term within the dictionary, where 0 is the first term.

C# example

This example gets the key value on the second term in the first dictionary:
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");
string strDictValue = m_oDCO.SetupObject().get_Value(0, 1);

get_Word method
The get_Word method gets the word value from a dictionary term.

.NET restriction: For VBScript, use the “Word property” on page 55 instead.

In the following XML sample, RoutingInstructions is the name of the dictionary,

which is followed by the key value and word value pairs ("None", None, and so
on):
<DICT n="RoutingInstructions">
<W v="None">None</W>
<W v="Delete">Delete</W>
<W v="Rescan">Rescan</W>
<W v="Review">Review</W>
</Dict>

Syntax
C#
string get_Word(int nDictionary, int nIndex)

Arguments
nDictionary
The index of the dictionary within the Setup object, where 0 is the first
dictionary
nIndex
The index of the term within the dictionary, where 0 is the first term

C# example

This example gets the word value on the second term in the first dictionary:
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");
string strDictWord = m_oDCO.SetupObject().get_Word(0, 1);

GetNode method
The GetNode method gets an interface to a SetupNode object in the Setup DCO by
using an index value. You can use this method when you know the position of the
object but not the name.

Syntax
VBScript
oSO.GetNode(nType as Long, nIndex as Long) child node as node object
C#
TDCOLib.DCOSetupNode GetNode(int nType, int nIndex)

60 IBM Datacap: DCO API Guide

 Arguments
nType
Value indicating the component type:
0 = Batch
1 = Document
2 = Page
3 = Field
nIndex
Value of the node's index, where 0 is the first node of the specified type in the
Setup DCO

Returns

The SetupNode object on success; nothing (null) on failure.

C# example

The following example gets an interface to the first node of type page from the
Setup DCO:
m_oDCOSetupNode = m_oDCOSetup.GetNode(2, 0);

GetNodeByName method
The GetNodeByName method accesses a SetupNode object from the Setup DCO by
using the object name.

Syntax
VBScript
oSO.GetNodeByName(nType as Long, lpszName as String) as child node as node object
C#
TDCOLib.DCOSetupNode GetNodeByName(int nType, string lpszName)

Arguments
nType
Value indicating the component type:
0 = Batch
1 = Document
2 = Page
3 = Field
lpszName
The node's name, as referenced in the node's type attribute:
<P type="Main_Page">

Returns

The SetupNode object on success; nothing (null) on failure.

Datacap object API 61

 C# Example

The following example gets an interface to the node "Main_Page" of type "page"
from the Setup DCO:
m_oDCOSetupNode = m_oDCOSetup.GetNodeByName(2, "Main_Page");

See also

“GetNode method” on page 60

NumOfDictionaries method
The NumOfDictionaries method returns the number of dictionaries that are defined
in the Setup DCO.
<DICT n="RoutingInstructions">
<W v="None">None</W>
<W v="Delete">Delete</W>
<W v="Rescan">Rescan</W>
<W v="Review">Review</W>
</Dict>

In the sample XML code, there is one dictionary that is called

RoutingInstructions.

Syntax
VBScript
oSO.NumOfDictionaries( ) as Long
C#
int NumOfDictionaries()

Arguments

None

Returns

The number of dictionaries defined in this Setup DCO.

See also

“NumOfWords” on page 63, “DictionaryName property” on page 54

NumOfNodes method
The NumOfNodes method gets the number of documents, pages, fields, or character
nodes in the Setup DCO.

Syntax
VBScript
oSO.NumOfNodes(nType as Long) as Long
C#
int NumOfNodes(int nType)

Arguments
nType
Value indicating the object type:

62 IBM Datacap: DCO API Guide

 0 = Batch
1 = Document
2 = Page
3 = Field
4 = Character

Returns

Value specifying the number of nodes of the specified type.

VBScript Example

This example reads the Setup DCO and gets the number of field nodes:
Dim Flds
Call oSO.ReadSetup("C:\Datacap\APT\dco_APT\APT.xml")
nFlds = oSO.NumOfNodes(3)
msgbox nFlds

C#

This example reads the Setup DCO and gets the number of field nodes:
m_oDCO.ReadSetup("C:\Datacap\APT\dco_APT\APT.xml");
TDCOLib.DCOSetup m_oDCOSetup = m_oDCO.SetupObject();
int numNodes = m_oDCOSetup.NumOfNodes(3);

See also

“AddNode method” on page 56, “get_DictionaryName method” on page 59,

“GetNodeByName method” on page 61, “DeleteNode method” on page 57

NumOfWords
The NumOfWords method returns the number of words that are defined in the
dictionary in the Setup DCO.

Description

The following example defines one dictionary with four words, where
RoutingInstructions is the dictionary name, and the text in each set of quotation
marks is the key value that is associated with the word that follows it.
<DICT n="RoutingInstructions">
<W v="None">None</W>
<W v="Delete">Delete</W>
<W v="Rescan">Rescan</W>
<W v="Review">Review</W>
</DICT>

Syntax

VBScript
oSO.NumOfWords (nDictionary subscript as Long) as Long

C#
int NumOfWords(int nDictionary)

Datacap object API 63

 Arguments
nDictionary
The index of the dictionary, where 0 is the first dictionary in the Setup DCO.

Returns

The number of words in the dictionary.

See also

NumOfDictionaries

ReadLock
The ReadLock method locks, and prevents other applications from writing to, the
specified Setup DCO file.

Description

ReadLock attempts to obtain the lock every 50 milliseconds. After 300 unsuccessful
attempts, ReadLock stops the attempt and returns False. The attempt fails when
another process locked the file.

Syntax

C#
bool ReadLock(string lpszPath)

Arguments
lpszPath
Full path and file name to the Setup DCO file.

Returns

True if successful; False otherwise.

See also

UnlockIt

ReadSetup
This method is identical to DCO.ReadSetup, except that you call it from a
DCOSetup object.

See DCO.ReadSetup for details.

set_DictionaryName method
The set_DictionaryName method sets the name of a dictionary within the Setup
DCO.

Syntax
C#
void set_DictionaryName(int nDictionary, string pVal)

64 IBM Datacap: DCO API Guide

Arguments
nDictionary
The index of the dictionary within the Setup DCO, where 0 is the first
dictionary.
pVal
The new dictionary name.

Returns

Nothing.

C# example

This C# example sets the name of the first dictionary in the Setup DCO file
APT.XML:
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");
string strDictName = m_oDCO.SetupObject().set_DictionaryName(0, "Datacap");
m_oDCO.WriteSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");

set_Value method
The set_Value method sets the key value in a dictionary term.

.NET restriction: For VBScript, use the Value instead.

The following example defines one dictionary with four words, where
RoutingInstructions is the dictionary name. The text in each set of quotation
marks is the key value that is associated with the word that follows it.
<DICT n="RoutingInstructions">
<W v="None">None</W>
<W v="Delete">Delete</W>
<W v="Rescan">Rescan</W>
<W v="Review">Review</W>
</DICT>

Syntax
C#
void set_Value(int nDictionary, int nIndex, string pVal)

Arguments
nDictionary
The index of the dictionary within the Setup object, where 0 is the first
dictionary.
nIndex
The index of the term within the dictionary, where 0 is the first term.
pVal
The key value.

Returns

Nothing

Datacap object API 65

 C# example

This example sets the key value on the second term in the first dictionary to
Delete:
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");
m_oDCO.SetupObject().set_Value(0, 1, "Delete");
m_oDCO.WriteSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");

set_Word method
The set_Word method sets the word value in a dictionary term.

.NET restriction: For VBScript, use the Word instead.

The following example defines one dictionary with four words, where
RoutingInstructions is the dictionary name. The text in each set of quotation
marks is the key value that is associated with the word that follows it.
<DICT n="RoutingInstructions">
<W v="None">None</W>
<W v="Delete">Delete</W>
<W v="Rescan">Rescan</W>
<W v="Review">Review</W>
</DICT>

Syntax
C#
void set_Word(int nDictionary, int nIndex, string pVal)

Arguments
nDictionary
The index of the dictionary within the Setup object, where 0 is the first
dictionary.
nIndex
The index of the term within the dictionary, where 0 is the first term.
pVal
The key value.

C# example

This example sets the word value on the second term in the first dictionary to
Delete:
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");
m_oDCO.SetupObject().set_Word(0, 1, "Delete");
m_oDCO.WriteSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");

ShowSetupDialog
The ShowSetupDialog method is identical to DCO.ShowSetupDialog, except that
you call it from a DCOSetup object.

UnlockIt
The Unlockit method unlocks the Setup DCO file that was locked previously with
the ReadLock method.

66 IBM Datacap: DCO API Guide

 Syntax

C#
bool UnlockIt()

Arguments

None

Returns

True if successful; False otherwise.

See also

ReadLock

WriteSetup method
The WriteSetup method is identical to DCO.WriteSetup, except that you call it from
a DCOSetup object.

For more information, see DCO.WriteSetup.

DCOSetupNode APIs
You can use the DCOSetupNode API properties and methods to access and modify
Setup DCO child objects, including rules and variables.

Each runtime DCO object inherits attributes and variables from the corresponding
DCOSetupNode object. For example, as demonstrated in the following setup node
sample, all documents that are identified as Invoice documents include the TYPE,
STATUS, DOC DATA, MIN_TYPES, MAX_TYPES, and rules variables. The Invoice
document object must also contain at least one Main_Page page object. Similarly, all
runtime objects that are identified as Main_Page types must be in the first position
of the Invoice document.
<D type="Invoice">
1
<V n="ID">0</V>
<V n="TYPE">Document</V>
<V n="STATUS">0</V>
<V n="DOC DATA">0</V>
<V n="MIN_TYPES">0</V>
2
<V n="MAX_TYPES">0</V>
<V n="rules"><in&gt;<r id=&quot;1&quot; rs=&quot;11&quot;
/&gt;<r id=&quot;5&quot; rs=&quot;7&quot; /&gt;<r
id=&quot;4&quot; rs=&quot;16&quot; /&gt;</in&gt;</V>

<P type="Main_Page" pos="1" min="1" max="1"/>

<P type="Trailing_Page" pos="0" min="0" max="0"/>
3
<P type="Attachment" pos="0" min="0" max="0"/>

</D>

1 Setup node for the document type Invoice

2 Variables

3 Parameters

Datacap object API 67

 DCOSetupNode objects are created and accessed through the parent DCOSetup
object.

The SetupNode object also defines the document integrity rules for that object type.
The following example specifies that a Tax Return document must have at least
one (min="1") and at most one (max="1") page of type 1040EZ. The relative position
attribute (pos="2") specifies that the 1040EZ page must come after the TaxSep page
(if present) and before the Attachment page (if present):
<D type="Tax Return">
<V n="ID">0</V>
<V n="ID">0</V>
<V n="TYPE">Document</V>
<V n="STATUS">0</V>
<V n="DOC DATA">0</V>
<V n="MIN_TYPES">2</V>
<V n="MAX_TYPES">0</V>
<V n="rules"></V>
<P type="TaxSep" pos="1" min="0" max="1"/>
<P type="1040EZ" pos="2" min="1" max="1"/> <--- Rule for page 1040EZ
<P type="Attachment" pos="3" min="0" max="0"/>
</D>

The max="0" value means unlimited. In the example, there can be any number of
attachment pages. The MIN_TYPES and MAX_TYPES variables define the minimum and
maximum number of child object types that must be present at run time to
constitute a valid document. The MIN_TYPES value (2) specifies that each runtime
document must have at least two different page types.

After you obtain an interface to the DCOSetup object, you can obtain an interface
to any DCOSetupNode object by using the “GetNode method” on page 60 or the
“GetNodeByName method” on page 61, as shown in the following example:
TDCOLib.DCOSetupNode m_oDCOSetupNode = m_oDCOSetup.GetNodeByName(2, "Main_Page");

Through the DCOSetup object interface, you can access all of the DCOSetupNode
object properties and methods.

DCOSetupNode properties
You can use DCOSetupNode properties to access DCOSetup objects and modify
metadata, including names, types, and values. You can also use these properties to
modify rules, variables, and child objects.

Name property
The Name property sets or gets the name of the SetupNode object.

The SetupNode object name is saved as the type attribute in the Setup DCO XML
file:
<D type="NodeName">

The name is the identifier that is used to refer to child objects within the Setup
DCO, as shown in this example:
<P type="Main_Page">
.
.
.
<F type="Vendor" pos="0" min="0" max="0"/> <--Referencing the Vendor node by name

68 IBM Datacap: DCO API Guide

Syntax
VBScript
oSNO.Name as String
C#
string Name { set; get; }

Type

Read and write.

VBScript example

In the following example, the code populates a setup object from the BDOcs.xml
setup DCO file. The code then uses the Name property to update the name of the
second node of type Page to Invoice in the Setup object. The example also writes
the updated Setup DCO file to disk.
Call oSO.ReadSetup("c:\Datacap\BDOcs\dco_BDOcs\BDOcs.xml")
Dim objInvPage
Set objInvPage = oSO.GetNode(2,1)
objInvPage.Name = "Invoice"
Call oSO.WriteSetup("c:\Datacap\BDOcs\dco_BDOcs\BDOcs.xml")

C# example

In the following example, after the code populates a setup object from the APT.XML
setup DCO file, the code uses the Name property to update the name of the
TM000001 node to Invoice in the Setup object. The example also writes the updated
Setup DCO file to disk.
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");
TDCOLib.DCOSetupNode m_oDCOSetupNode = m_oDCO.FindChild("TM000001").SetupNode();
m_oDCOSetupNode.Name = "Invoice";
m_oDCO.WriteSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");

ObjectType property
The ObjectType property sets or gets the SetupNode object type, such as a batch,
document, page, field, or character.

Use one of these number values to determine the SetupNode object type:
Object type
0 = Batch.
1 = Document.
2 = Page.
3 = Field.
4 = Character.

Syntax
VBScript
oSNO.ObjectType as Long
C#
int ObjectType { set; get; }

Datacap object API 69

 Type

Read and write.

VBScript example

This example gets a SetupNode object for the Total field and sends the type (3 =
Field) to a script debugger:
Dim objTotal
Set objTotal = oSO.GetNodeByName(3, "Total")
Debug.write objTotal.ObjectType

RuleChildName
The RuleChildName property sets or gets the name of a rule that is referenced by an
index.

Description

Important: VBScript only. Extended properties are not supported through the C#
.NET Interop interface. Instead, use set_RuleChildName or get_RuleChildName.

For more information, see get_RuleChildName.

Syntax
VBScript
oSNO.RuleChildName(nIndex as Long) as String

Arguments
nIndex
The index of the rule, where 0 is the first rule.

Type

Read and write

Example
VBScript
Dim objDoc
Set objDoc = MQDCO.GetNodebyName(1, "Doc")
Call objDoc.AddRule (2,"Page1",1,1,3)
msgbox "The name of Rule 1 is " & objDoc.RuleChildName(0)

See also

AddRule

RuleMaxNum
The RuleMaxNum property sets or gets the max attribute for a rule.

Description

Important: VBScript only. Extended properties are not supported through the C#
.NET Interop interface. Instead, use set_RuleMaxNumber or get_RuleMaxNumber.

For more information, seeget_RuleMaxNumber.

70 IBM Datacap: DCO API Guide

Syntax
VBScript
oSNO.RuleMaxNum(RuleIndex as Long)

Arguments
RuleIndex
The index of the rule, where 0 is the first rule under this SetupNode object.

Type

Read and write

Example
VBScript
Dim MaxTotal
MaxTotal = objInv.RuleMaxNum(3)
msgbox MaxTotal

See also

RuleMinNum

RuleMinNum
The RuleMinNum property sets or gets the min attribute for a rule.

Description

Important: VBScript only. Extended properties are not supported through the C#
.NET Interop interface. Instead, use set_RuleMinNumber or get_RuleMinNumber.

For more information, see get_RuleMinNumber.

Syntax
VBScript
oSNO.RuleMinNum (RuleIndex as Long) as Long

Arguments
RuleIndex
The index of the rule, where 0 is the first rule under this SetupNode object.

Type

Read and write

Example
VBScript
Dim MinSSN
MinSSN = objPageTwo.RuleMinNum(0)
msgbox MinSSN

See also

RuleMaxNum

Datacap object API 71

 RuleObjectType
The RuleObjectType property sets or gets the type of an object.

Description

Important: VBScript only. Extended properties are not supported through the C#
.NET Interop interface. Instead, use set_RuleObjectType or get_ RuleObjectType.

The object type is determined by a value 0-3.

0 = Batch

1 = Document

2 = Page

3 = Field

Syntax
VBScript
oSNO.RuleObjectType (Index as Long) as Long

Arguments
Index
The index of the rule, where 0 is the first rule under this SetupNode object.

Type

Read and write

Example
VBScript
Dim TypeSSN
TypeSSN = objPageTwo.RuleObjType(0)
msgbox TypeSSN

See also

get_ RuleObjectType

RulePosition
The RulePosition property determines the order of rules, and optionally restricts
the order of child objects within a parent object at run time.

Description

Important: VBScript only. Extended properties are not supported through the C#
.NET Interop interface. Instead, use set_RulePosition or get_ RulePosition.

All child objects with rules that specify Position=1 must appear before any child
objects with higher position values (greater than 1). A Position=0 means that the
child item can appear in any order.

72 IBM Datacap: DCO API Guide

Syntax
VBScript
oSNO.RulePosition (Index as Long) as Long

Type

Read and write

Arguments
Index
The index of the rule, where 0 is the first rule under this SetupNode object.

Variable
The Variable property sets or gets the value that is associated with a variable in
the SetupNode object. You can use this property to identify objects (for example,
pages) that require special processing when a variable contains a specific value.

Description

Important: VBScript only. Extended properties are not supported through the C#
.NET Interop interface. Instead, use set_Variable or get_ Variable.

Syntax
VBScript
oSNO.Variable (VarName as String) as Variant

Type

Read and write

Arguments
VarName
Name of the variable (case sensitive)

Example
VBScript
Call objTotal.AddVariable ("Length", "10")
msgbox objTotal.Variable("Length")

See also

get_ Variable

VariableName
The VariableName property sets or gets the name of a variable that is accessed by
an index in the DCOSetupNode object. You can use this property to identify
objects (for example, pages) that require special processing when a variable
contains a specific value. This property is useful when a node contains many child
objects and variables.

Description

Important: VBScript only. Extended properties are not supported through the C#
.NET Interop interface. Instead, use set_VariableName or get_ VariableName.

Datacap object API 73

 Syntax
VBScript
oSNO.VariableName (Node as Long) as String

Type

Read and write.

Arguments
Node
The index of the variable, where 0 is the first variable that is defined in the
DCOSetupNode object.

See also

get_ VariableName

VariableValue
The VariableValue property sets or gets the value of an indexed variable from the
DCOSetupNode object. You can use this property to identify objects (for example,
pages) when a node contains many child objects and variables.

Description

Important: VBScript only. Extended properties are not supported through the C#
.NET Interop interface. Instead, use set_RuleObjectType or get_ RuleObjectType.

Syntax
VBScript
oSNO.VariableValue (Node as Long) as Variant

Arguments
Node
The index of the variable, where 0 is the first variable that is defined in the
DCOSetupNode object.

Data type

Variant

Example
VBScript
This example displays the current value that is assigned to the third
variable that is linked to the objTotal node:
msgbox objTotal.VariableValue(2)

read/write

Read and write

See also

get_ RuleObjectType

74 IBM Datacap: DCO API Guide

DCOSetupNode methods
You can use DCOSetupNode methods to add or delete rules and variables. You can
also use these methods to obtain and modify metadata, including names, number
attributes, object types, and values. You might use these methods when the
business requirements of your organization change and require different rules and
variables.

AddRule method
The AddRule method adds a document integrity rule to a SetupNode object. For
example, you can use this method to add a rule that specifies that a document type
must contain a specific page type.

Document integrity rules specify the required structure of the document. For
example, a rule for the document type Invoice might specify that documents of
this type must have a page of type Main_Page. A rule for the page type Main_Page
might specify that pages of this type must have a field of type Invoice_Total.

If a SetupNode object for the specified child object does not exist, this method
creates the SetupNode object.

Syntax
VBScript
AddRule(ObjectType as Long, lpszChildName as String,
nPosition as Long, MinNumber as Long, MaxNumber as Long)
as Boolean
C#
int AddRule(int nObjectType, string lpszChildName,
short nPosition, short nMinNumber, short nMaxNumber)

Arguments
nObjectType
Use one of the following number values to determine the object type of the
child node:
0 = Batch
1 = Document
2 = Page
3 = Field
lpszChildName
The name of the child object, which is stored as the type attribute of the rule.
nPosition
The position that child objects of this type must be relative to other child
items at run time. In the DCO Setup window, this value is the Order property
of the child node.
nMinNumber
The minimum number of instances of this child object that must exist for the
document structure to be valid.
nMaxNumber
The maximum number of instances of this child object that can exist for the
document structure to be valid.

Datacap object API 75

 Returns

Returns true if successful; returns false if unsuccessful.

C# example

This example gets the SetupNode object for the Invoice document in the Setup
DCO. The example then adds a rule that requires one instance of the page NewPage
to exist for the document structure to be valid. If a page node for NewPage does not
exist, the method creates NewPage automatically.
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");
TDCOLib.DCOSetup m_oDCOSetup = m_oDCO.SetupObject();
TDCOLib.DCOSetupNode m_oDCOSetupNode =
m_oDCOSetup.GetNodeByName(1, "Invoice");
m_oDCOSetupNode.AddRule(2, "NewPage", 0, 1, 1);

The following line is added to the Setup DCO:

<D type="Invoice">
.
.
.
<P type="NewPage" pos="0" min="1" max="1"/> <!-- New line added -->

Additionally, if NewPage does not exist, the following page node is created:
<P type="NewPage">
<V n="ID">0</V>
<V n="TYPE">Page</V>
<V n="STATUS">0</V>
<V n="IMAGEFILE"></V>
<V n="DATAFILE"></V>
<V n="TEMPLATE IMAGE"></V>
<V n="MIN_TYPES">0</V>
<V n="MAX_TYPES">0</V>
</P>

AddVariable method
The AddVariable method adds a variable to a SetupNode object and assigns a
default value.

By default, all SetupNode objects include the standard variables that are installed
with Datacap. For more information, see the Standard Variable Reference section in
IBM Knowledge Center for Datacap.

Syntax
VBScript
oSNO.AddVariable(lpszName as String, lpszValue as String) as Boolean
C#
bool AddVariable(string lpszName, string lpszValue)

Applies to

All node types.

Arguments
lpszName
Name of the new variable.

76 IBM Datacap: DCO API Guide

lpszValue
Default value (always a string)

Returns

Returns true if successful; returns false if unsuccessful.

C# example

This example gets the SetupNode object for the Invoice document in the APT.XML
Setup DCO file and adds a variable NewVar with a default value True:
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");
TDCOLib.DCOSetup m_oDCOSetup = m_oDCO.SetupObject();
TDCOLib.DCOSetupNode m_oDCOSetupNode =
m_oDCOSetup.GetNodeByName(1, "Invoice");
m_oDCOSetupNode.AddVariable("NewVar", "True");

The following line is added to the Setup DCO:

<D type="Invoice">
.
.
.
<V n="NewVar">True</V> <!-- New line added -->

DeleteRule method
The DeleteRule method deletes the specified document integrity rule from a
SetupNode object.

Description

For a description of document integrity rules, see “AddRule method” on page 75.

Syntax
VBScript
oSNO.DeleteRule(nIndex as Long) as Boolean
C#
bool DeleteRule(int nIndex)

Arguments
nIndex
The index of the rule to delete, where 0 is the first rule that is specified under
this SetupNode object.

Returns

True if successful; False otherwise.

See also

“AddRule method” on page 75

DeleteVariable method
The DeleteVariable method deletes the specified variable that is referenced by an
index, from a setup node.

Datacap object API 77

 Syntax
VBScript
oSNO. DeleteVariable(VarIndex as Long) as Boolean
C#
bool DeleteVariable(int nIndex)

Applies to

All node types.

Arguments
VarIndex
The index of the variable to delete, where 0 is the first variable.

Returns

True if successful; False otherwise.

See also

“AddVariable method” on page 76, “DeleteVariableByName method”

DeleteVariableByName method
The DeleteVariableByName method deletes the specified variable that is referenced
by name from a setup node.

Syntax
VBScript
oSNO.DeleteVariableByName(lpszName as String) as Boolean
C#
bool DeleteVariableByName(string lpszName)

Applies to

All node types

Arguments
lpszName
The variable name

Returns

True if successful; False otherwise.

See also

“AddVariable method” on page 76, “DeleteVariable method” on page 23

FindRule method
The FindRule method uses a specified name to search for a SetupNode child object.

78 IBM Datacap: DCO API Guide

Syntax
VBScript
oSNO.FindRule(lpszName as String) child node as node object
C#
TDCOLib.DCOSetupNode FindRule(string lpszName)

Arguments
lpszName
The name of the rule.

Returns

The child node if successful; or nothing (null) otherwise.

Applies to

Any SetupNode object

See also

“GetRule method” on page 85

get_RuleChildName method
The get_RuleChildName method gets the name of the rule under the current
SetupNode object.

Attention: .NET only. For VBScript, use the “RuleChildName” on page 70

property instead.

Description

The name of the rule is the type attribute in the Setup DCO XML file, and is the
same name as the child node to which the rule applies. In the following rule for
documents of type Invoice, the name of the rule is Main_Page.
<D type="Invoice">
.
.
<P type="Main_Page" pos="0" min="1" max="1"/> <!--Rule-->

Syntax
C#
string get_RuleChildName(int nIndex)

Arguments
nIndex
The index of the rule, where 0 is the first rule under this SetupNode object.

C# Example

This example gets the name of the first rule under the current SetupNode object:
string strRuleName = m_oDCOSetupNode.get_RuleChildName(0);

Datacap object API 79

 See also

“set_RuleChildName” on page 87

get_RuleMaxNumber Method
The get_RuleMaxNumber method gets the maximum number of child objects of the
specified type that can be associated with the parent object without violating a
document integrity rule.

Attention: .NET only. For VBScript, use the “RuleMaxNum” on page 70 property
instead.

Description

The maximum number is the max attribute in the Setup DCO XML file. In the
following rule, the maximum number of pages of type Main_Page that a document
of type Invoice can have is 1.
<D type="Invoice">
.
.
<P type="Main_Page" pos="0" min="1" max="1"/> <!--Rule-->

Syntax
C#
int get_RuleMaxNumber(int nIndex)

Arguments
nIndex
The index of the rule, where 0 is the first rule under the current SetupNode
object.

C# Example

This example gets the max attribute of the first rule under the current SetupNode
object:
int nMaxNum = m_oDCOSetupNode.get_RuleMaxNumber(0);

See also

“set_RuleMaxNumber” on page 88

get_RuleMinNumber method
The get_RuleMinNumber method gets the minimum number of child objects of the
specified type that must be associated with the parent object to avoid violating a
document integrity rule.

Attention: .NET only. For VBScript, use the “RuleMinNum” on page 71 property
instead.

Description

The minimum number is the min attribute in the Setup DCO XML file. In the
following rule, the minimum number of pages of type Main_Page that a document
of type Invoice must have is 1.

80 IBM Datacap: DCO API Guide

<D type="Invoice">
.
.
<P type="Main_Page" pos="0" min="1" max="1"/> <!--Rule-->

Syntax
C#
int get_RuleMinNumber(int nIndex)

Arguments
nIndex
The index of the rule index, where 0 is the first rule under the current
SetupNode object.

C# example

This example gets the min attribute of the first rule under the current SetupNode
object.
int nMinNum = m_oDCOSetupNode.get_RuleMinNumber(0);

See also

“set_RuleMinNumber” on page 88

get_RuleObjectType method
The get_RuleObjectType method gets the type of an object.

Attention: .NET only. For VBScript, use the “RuleObjectType” on page 72

property instead.

Description

The type of an object is defined by a value range of 0-3.

0 = Batch

1 = Document

2 = Page

3 = Field

In the following rule for documents of type Invoice, the object type is 2 (Page).
<D type="Invoice">
.
.
<P type="Main_Page" pos="0" min="1" max="1"/> <!--Rule-->

Syntax
C#
int get_RuleObjectType(int nIndex)

Datacap object API 81

 Arguments
nIndex
The index of the rule index, where 0 is the first rule under the current
SetupNode object.

C# Example

This example gets the object type for the first rule under the current SetupNode
object.
int nRuleType = m_oDCOSetupNode.get_RuleObjectType(0);

See also

“set_RuleObjectType” on page 88

get_RulePosition method
The get_RulePosition method gets the pos attribute of a specified rule within a
SetupNode object. The pos attribute determines the position of an object type
relative to other objects of the same type within the parent node. You can use this
method to verify the order of pages in a document and ensure document integrity.

Attention: .NET only. For VBScript, use the “RulePosition” on page 72 property
instead.

Description

The following rules specify position requirements for documents of type Tax
Return.
v A TaxSep page must come before the 1040EZ page and any Attachment pages.
v The 1040EZ page must come before any Attachment pages.
<D type="Tax Return">
.
.
<P type="TaxSep" pos="1" min="0" max="1"/> <!--Rule 0-->
<P type="1040EZ" pos="2" min="1" max="1"/> <!--Rule 1-->
<P type="Attachment" pos="3" min="0" max="0"/> <!--Rule 2-->

If a rule has pos="0", then the corresponding object type is not included in the
process that confirms document integrity. For details about document integrity, see
“DCOSetupNode APIs” on page 67.

Syntax
C#
int get_RulePosition(int nIndex)

Arguments
nIndex
The index of the rule, where 0 is the first rule under the current SetupNode
object.

C# Example

This example gets the position attribute for the first rule under the current
SetupNode object.

82 IBM Datacap: DCO API Guide

int nPosValue = m_oDCOSetupNode.get_RulePosition(0);

See also

“set_RulePosition” on page 89

get_Variable method
The get_Variable method gets the value of a variable from the SetupNode object.
You can use this method to identify objects (for example, pages) that require
special processing when a variable contains a specific value.

Attention: .NET only. For VBScript, use the“Variable property” on page 12

property instead.

Description

The following example shows three variables that are associated with the page
node Main_Page in the Setup DCO file.
<P type="Main_Page">
<V n="ID">0</V>
0
<V n="TYPE">Page</V>
1
<V n="STATUS">0</V>
2

0 Variable 0 (name = ID, value = 0)

1 Variable 1 (name = TYPE, value = Page)

2 Variable 2 (name = STATUS, value = 0)

Syntax
C#
string get_Variable(string lpszName)

Arguments
lpszName
The variable name (case sensitive)

C# Example

The following example gets the value of the variable TYPE from the page node
Main_Page in the Setup DCO.
TDCOLib.DCOSetupNode m_oDCOSetupNode = m_oDCOSetup.GetNodeByName(2, "Main_Page");
string strValue = m_oDCOSetupNode.get_Variable("TYPE");

See also

“get_VariableName method,” “get_VariableValue Method” on page 84,

“set_Variable” on page 90

get_VariableName method
The get_VariableName method gets the name of an indexed variable from the
SetupNode object. You can use this method to identify objects (for example, pages)
that require special processing when a variable contains a specific value. This
method is useful when a node contains many child objects and variables.

Datacap object API 83

 Attention: .NET only. For VBScript, use the “VariableName” on page 73 property
instead.

Description

The following example shows three variables that are associated with the page
node Main_Page in the Setup DCO file:
<P type="Main_Page">
<V n="ID">0</V>
0
<V n="TYPE">Page</V>
1
<V n="STATUS">0</V>
2

0 Variable 0 (name = ID, value = 0)

1 Variable 1 (name = TYPE, value = Page)

2 Variable 2 (name = STATUS, value = 0)

Syntax
C#
string get_VariableName(int nIndex)

Arguments
nIndex
The index of the variable, where 0 is the first variable that is defined in the
SetupNode object

C# Example

The following example gets the name of the first variable that is defined within the
page node, Main_Page, in the Setup DCO.
TDCOLib.DCOSetupNode m_oDCOSetupNode = m_oDCOSetup.GetNodeByName(2, "Main_Page");
string varName = m_oDCOSetupNode.get_VariableName(0);

See also

“ReadSetup method” on page 42, “GetNodeByName method” on page 61,

“get_Variable method” on page 83, “get_VariableValue Method,”
“set_VariableName” on page 90

get_VariableValue Method
The get_VariableValue method gets the value of an indexed variable from the
SetupNode object. You can use this method to identify objects (for example, pages)
that require special processing when a variable contains a specific value. This
method is useful when a node contains many child objects and variables.

Attention: .NET only. For VBScript, use the “VariableValue” on page 74 property
instead.

Description

The following example shows three variables that are associated with the page
node, Main_Page, in the Setup DCO file:

84 IBM Datacap: DCO API Guide

 <P type="Main_Page">
<V n="ID">0</V>
0
<V n="TYPE">Page</V>
1
<V n="STATUS">0</V>
2

0 Variable 0 (name = ID, value = 0)

1 Variable 1 (name = TYPE, value = Page)

2 Variable 2 (name = STATUS, value = 0)

Syntax
C#
string get_VariableValue(int nIndex)

Arguments
nIndex
The index of the variable, where 0 is the first variable defined in the
SetupNode object

C# Example

The following example gets the value of the first variable defined with the page
node, Main_Page, in the Setup DCO:
TDCOLib.DCOSetupNode m_oDCOSetupNode = m_oDCOSetup.GetNodeByName(2, "Main_Page");
string varValue = m_oDCOSetupNode.get_VariableValue(0);

See also

“get_Variable method” on page 83, “get_VariableName method” on page 83,

“set_VariableValue” on page 91

GetRule method
The GetRule method gets the SetupNode object that is referenced by a specified
rule. You can use this method to identify objects (for example, pages) that require
special processing when a node contains many child objects and rules.

Description

For example, the following rule references a page of type Main_Page. So, GetRule
returns the Main_Page SetupNode object.
<D type="Invoice">
.
.
<P type="Main_Page" pos="0" min="1" max="1"/> <!--Rule referencing page "Main_Page" -->

Syntax
VBScript
oSNO.GetRule(nIndex as Long) child node as node object
C#
TDCOLib.DCOSetupNode GetRule(int nIndex)

Arguments
nIndex
The index of the rule, where 0 is the first rule under this SetupNode object.

Datacap object API 85

 Applies to

All node types

Returns

Child node object if successful; otherwise nothing (null).

C# Example

This example gets the SetupNode object for the Invoice document in the Setup
DCO and then gets the first rule under this node. It then gets the SetupNode object
for the child object that is referenced by this rule.
m_oDCO.ReadSetup("C:\\Datacap\\APT\\dco_APT\\APT.XML");
TDCOLib.DCOSetup m_oDCOSetup = m_oDCO.SetupObject();
TDCOLib.DCOSetupNode m_oDCOSetupNode = m_oDCOSetup.GetNodeByName(1, "Invoice");
TDCOLib.DCOSetupNode m_oDCOSetupNode2 = m_oDCOSetupNode.GetRule(0);

See also

“AddRule method” on page 75

NumOfRules method
The NumOfRules method returns the number of rules that is within a SetupNode
object.

Syntax
VBScript
oSNO.NumOfRules( ) as Long
C#
int NumOfRules()

Arguments

None

Returns

The number of rules in this SetupNode object.

Applies to

All node types

C# Example

This example returns the number of rules that is contained in the current
SetupNode object.
int nNumRules = m_oDCOSetupNode.NumOfRules();

See also

“AddRule method” on page 75

86 IBM Datacap: DCO API Guide

NumOfVariables Method
The NumOfVariables method returns the number of variables that is within a
SetupNode object.

Description

This method returns user-defined variables and standard variables. (For more
information, see the Standard Variable Reference).

Syntax
VBScript
oSNO.NumOfVariables ( ) as Long
C#
int NumOfVariables()

Arguments

None

Returns

The number of variables in this SetupNode object.

C# Example

The following example returns the number of rules within the current SetupNode
object:
int nNumVars = m_oDCOSetupNode.NumOfVariables();

set_RuleChildName
The set_RuleChildName method sets the name of the rule under the current
SetupNode object.

Description

Important: .NET only. For VBScript, use the RuleChildName property instead.

For more information, see get_RuleChildName.

Syntax
C#
void set_RuleChildName(int nIndex, string pVal)

Arguments
nIndex
The index of the rule, where 0 is the first rule under this SetupNode object.

See also

get_RuleChildName

Datacap object API 87

 set_RuleMaxNumber
The set_RuleMaxNumber method sets the maximum number of child objects of the
specified type that can be associated with the parent object without violating a
document integrity rule.

Description

Important: .NET only. For VBScript, use the RuleMaxNum property instead.

For more information, see get_RuleMaxNumber.

Syntax
C#
void set_RuleMaxNumber(int nIndex, int pVal)

Arguments
nIndex
The index of the rule, where 0 is the first rule under this SetupNode object.
pVal
The maximum number of child objects.

See also

get_RuleMaxNumber

set_RuleMinNumber
The set_RuleMinNumber method sets the minimum number of child objects of the
specified type that must be associated with the parent object to avoid violating a
document integrity rule.

Description

Important: .NET only. For VBScript, use the RuleMinNum property instead.

For more information, see get_RuleMinNumber.

Syntax
C#
void set_RuleMinNumber(int nIndex, int pVal)

Arguments
nIndex
The index of the rule, where 0 is the first rule under the current SetupNode
object.
pVal
The minimum number of child objects.

See also

get_RuleMinNumber

set_RuleObjectType
The set_RuleObjectType method sets the type of an object.

88 IBM Datacap: DCO API Guide

Description

Important: .NET only. For VBScript, use the RuleObjectType property instead.

For more information, see get_RuleObjectType.

Syntax
C#
void set_RuleObjectType(int nIndex, int pVal)

Arguments
nIndex
The index of the rule, where 0 is the first rule under this SetupNode object.
pVal
The object type:
0 = Batch
1 = Document
2 = Page
3 = Field

See also

get_RuleObjectType

set_RulePosition
The set_RulePosition method sets the pos attribute of a specified rule within a
SetupNode object. The pos attribute determines the position of an object type
relative to other objects of the same type within the parent node. You can use this
method to determine the order of pages in a document and ensure document
integrity.

Description

Important: .NET only. For VBScript, use the RulePosition property instead.

For more information, see get_RulePosition.

Syntax
C#
void set_RulePosition(int nIndex, int pVal)

Arguments
nIndex
The index of the rule, where 0 is the first rule under this SetupNode object.
pVal
The position of the rule.

See also

get_RulePosition

Datacap object API 89

 set_Variable
The set_Variable method sets the value of a variable from the SetupNode object.
You can use this method to determine which objects (for example, pages) require
special processing when a variable contains a specific value.

Description

Important: .NET only. For VBScript, use the Variable property instead.

For more information, see get_Variable.

Syntax

C#
void set_Variable(string lpszName, string pVal)

Arguments
lpszName
The variable name (case sensitive).
pVal
The value (always a string).

See also

get_Variable

set_VariableName
The set_VariableName method sets the name of an indexed variable within a
SetupNode object. You can use this method to identify variables within a node that
contains many child objects.

Description

Important: .NET only. For VBScript, use the VariableName property instead.

Syntax
C#
void set_VariableName(int nIndex, string pVal)

Arguments
nIndex
The index of the variable, where 0 is the first variable that is defined in the
SetupNode object.
pVal
The variable name.

See also

get_VariableName

90 IBM Datacap: DCO API Guide

set_VariableValue
The set_VariableValue method sets the value of an indexed variable from the
SetupNode object. You can use this method to identify objects (for example, pages)
when a node contains many child objects and variables.

Description

Important: .NET only. For VBScript, use the VariableValue property instead.

Syntax
C#
void set_VariableValue(int nIndex, string pVal)

Arguments
nIndex
The index of the variable, where 0 is the first variable that is defined in the
SetupNode object.
pVal
The variable value (always a string).

See also

get_VariableValue

Datacap object API 91

92 IBM Datacap: DCO API Guide
Notices
This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing

Legal and Intellectual Property Law
IBM Japan Ltd.
1623-14, Shimotsuruma, Yamato-shi
Kanagawa 242-8502 Japan

The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply
to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.

© Copyright IBM Corp. 2014 93

 IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:

IBM Corporation
J46A/G4
555 Bailey Avenue
San Jose, CA 95141-1003
U.S.A.

Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.

The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.

This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.

Any performance data contained herein was determined in a controlled

environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.

All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which

illustrate programming techniques on various operating platforms. You may copy,

94 IBM Datacap: DCO API Guide

 modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs.

Trademarks
The following terms are trademarks of the International Business Machines
Corporation in the United States, other countries, or both: http://www.ibm.com/
legal/copytrade.shtml

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Oracle and/or its affiliates.

Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered
trademarks or trademarks of Adobe Systems Incorporated in the United States,
and/or other countries.

Linux is a registered trademark of Linus Torvalds in the United States, other

countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other
countries.

Other product and service names might be trademarks of IBM or other companies.

Privacy policy considerations

IBM Software products, including software as a service solutions, (“Software
Offerings”) may use cookies or other technologies to collect product usage
information, to help improve the end user experience, to tailor interactions with
the end user or for other purposes. In many cases no personally identifiable
information is collected by the Software Offerings. Some of our Software Offerings
can help enable you to collect personally identifiable information. If this Software
Offering uses cookies to collect personally identifiable information, specific
information about this offering’s use of cookies is set forth below.

The Software Offering uses session and persistent cookies that collect each user's
user name, for purposes of session management, enhanced user usability, single
sign-on configuration. Session cookies cannot be disabled. Persistent cookies can be
disabled, but disabling them will also eliminate the functionality they enable.

If the configurations deployed for this Software Offering provide you as customer
the ability to collect personally identifiable information from end users via cookies
and other technologies, you should seek your own legal advice about any laws
applicable to such data collection, including any requirements for notice and
consent.

For more information about the use of various technologies, including cookies, for
these purposes, See IBM’s Privacy Policy at http://www.ibm.com/privacy and
IBM’s Online Privacy Statement at http://www.ibm.com/privacy/details the

Notices 95
 section entitled “Cookies, Web Beacons and Other Technologies” and the “IBM
Software Products and Software-as-a-Service Privacy Statement” at
http://www.ibm.com/software/info/product-privacy.

96 IBM Datacap: DCO API Guide

Index
A CreateDocuments
DCO methods 20, 21
DCO (continued)
getting OMR field positions
Accessing SetupNode object creating field objects (continued)
DCO methods 44 CreateFields 21 get_OMRValue 30
AddChild DCO methods 21 getting variable values
DCO methods 14 DCO methods 30
adding character data values get_Variable 30
AddValue 15
DCO methods 15 D identifying object type
DCO methods 40
adding child objects Datacap
ObjectType 40
AddChild 14 creating document hierarchies 3
identifying parent
DCO methods 14 Datacap objects
DCO methods 41
adding variables API 1
Parent 41
AddVariable 16 DCO
moving child objects
DCO methods 16 adding integer variables
DCO methods 37, 38
AddNode AddVariableInt 17
MoveChild 37
DCOSetup methods 56 DCO methods 17
MoveIn 38
AddRule adding string variables
OMR character values
DCOSetupNode methods 75 AddVariableString 18
DCO methods 49
AddValue DCO methods 18
set_OMRValue 49
DCO methods 15 adding variables of type double
organizing child objects
AddVariable AddVariableFloat 17
DCO methods 37
DCO methods 16 DCO methods 17
MoveChild 37
DCOSetupNode methods 76 check boxes
setting confidence level of characters
AddVariableFloat DCO methods 30
DCO methods 45
DCO methods 17 get_OMRValue 30
set_AltConfidenceString 45
AddVariableInt checking document integrity
setting OMR character values
DCO methods 17 CheckIntegrity 18
check boxes 49
AddVariableString DCO methods 18
DCO methods 49
DCO methods 18 child object number
set_OMRValue 49
AltConfidenceString DCO methods 39
setting variables
DCO properties 6 NumOfChildren 39
DCO methods 49
AltText confidence levels
set_Variable 49
DCO properties 7 DCO methods 47
variable count
API set_CharConfidence 47
DCO methods 40
creating document hierarchies 3 creating document objects
NumOfVars 40
DCO 1 CreateDocuments 20
variable values
Document hierarchy 1 DCO methods 20
DCO methods 49
Runtime batch hierarchy 1 deleting character data values
set_Variable 49
Setup DCO 1 DCO methods 22
writingfiles
DeleteValue 22
DCO methods 50
deleting child objects
Write 50
C Clear 20
DCO methods 20, 22
DCO API
character position creating document hierarchies 3
DeleteChild 22
DCO methods 32, 43 Datacap objects 1
deleting confidence level values
GetPosition 32 DCO methods
DCO methods 22
SetPosition 43 AddChild 14
DeleteValue 22
character values AddValue 15
deleting variable values
DCO methods 48 AddVariable 16
DCO methods 23
set_CharValue 48 AddVariableFloat 17
DeleteVariable 23
CharConfidence AddVariableInt 17
deleting variables
DCO properties 8 AddVariableString 18
DCO methods 23
CharValue CheckIntegrity 18
DeleteVariable 23
DCO properties 8 Clear 20
getting child objects
CheckIntegrity CreateDocuments 20
DCO methods 31
DCO methods 18 CreateFields 21
GetChild 31
Clear DeleteChild 22
getting object paths
DCO methods 20 DeleteValue 22
DCO methods 33
clearing last error 32 DeleteVariable 23
GetRoute 33
ConfidenceString FindChild 23
getting OMR field positions
DCO properties 9 FindChildIndex 24
DCO methods 30

© Copyright IBM Corp. 2014 97

DCO API (continued) DCOSetup API (continued) DeleteNode
DCO methods (continued) DCOSetup methods (continued) DCOSetup methods 57
FindRouteChild 25 get_Word 60 DeleteNodeByName
FindVariable 25 GetNode 60 DCOSetup methods 58
get_AltConfidenceString 26 GetNodeByName 61 DeleteRule
get_AltText 27 NumOfDictionaries 62 DCOSetupNode methods 77
get_CharConfidence 28 NumOfNodes 62 DeleteValue
get_CharValue 29 NumOfWords 63 DCO methods 22
get_OMRValue 30 ReadLock 64 DeleteVariable
get_Variable 30 ReadSetup 64 DCO methods 23
GetChild 31 set_DictionaryName 64 DCOSetupNode methods 78
GetLastError 32 set_Value 65 DeleteVariableByName
GetPosition 32 set_Word 66 DCOSetupNode methods 78
GetRoute 33 ShowSetupDialog 66 Dictionary name
GetVariableName 34 Unlockit 67 setting 64
GetVariableValue 35 WriteSetup 67 DictionaryName
IsError 36 DCOSetup properties DCOSetup properties 54
IsRoute 36 DictionaryName 54 discovering errors
IsValid 37 Path 54 DCO methods 36
MoveChild 37 Value 55 IsError 36
MoveIn 38 Word 55 Document hierarchy
NumOfChildren 39 Document hierarchy 51 API 1
NumOfVars 40 methods 56
ObjectType 40 properties 54
Parent 41
Read 41
Setup DCO 51
DCOSetupNode API
F
field position
ReadSetup 42 DCOSetupNode methods
DCO methods 32, 43
set_AltConfidenceString 45 AddRule 75
GetPosition 32
set_AltTex 46 AddVariable 76
SetPosition 43
set_CharConfidence 47 DeleteRule 77
FindChild
set_CharValue 48 DeleteVariable 78
DCO methods 23
set_OMRValue 49 DeleteVariableByName 78
FindChildIndex
SetPosition 43 FindRule 79
DCO methods 24
SetupObject 45 get_RuleChildName 79
finding child object index
Variable 49 get_RuleMaxNumber 80
DCO methods 24
Write 50 get_RuleMinNumber 80
FindChildIndex 24
WriteSetup 51 get_RuleObjectType 81
finding child objects
DCO properties get_RulePosition 82
DCO methods 23
AltConfidenceString 6 get_Variable 83
FindChild 23
AltText 7 get_VariableName 84
finding object interface
CharConfidence 8 get_VariableValue 84
DCO methods 25
CharValue 8 GetRule 85
FindRouteChild 25
ConfidenceString 9 NumOfRules 86
finding variable index
ID 10 NumOfVariables 87
DCO methods 25
ImageName 10 set_RuleChildName 87
FindVariable 25
Status 11 set_RuleMaxNumber 88
FindRouteChild
Text 11 set_RuleMinNumber 88
DCO methods 25
Type 12 set_RuleObjectType 89
FindRule
Variable 12 set_RulePosition 89
DCOSetupNode methods 79
XML 13 set_Variable 90
FindVariable
DCOSetupNode 67 set_VariableName 90
DCO methods 25
definition 1 set_VariableValue 91
document assembly 2 DCOSetupNode properties
methods 14 Name 68
Properties 6 ObjectType 69 G
Runtime batch hierarchy 4 RuleChildName 70 get_AltConfidenceString
Runtime DCO 4 RuleMaxNum 70 DCO methods 26
Setup DCO child objects 67 RuleMinNum 71 get_AltText
DCO methods RuleObjectType 72 DCO methods 27
SetupNode 44 RulePosition 72 get_CharConfidence
DCOSetup API Variable 73 DCO methods 28
DCOSetup methods VariableName 73 get_CharValue
AddNode 56 VariableValue 74 DCO methods 29
DeleteNode 57 methods 75 get_DictionaryName
DeleteNodeByName 58 properties 68 DCOSetup methods 59
get_DictionaryName 59 DeleteChild get_OMRValue
get_Value 59 DCO methods 22 DCO methods 30

98 IBM Datacap: DCO API Guide

get_RuleChildName getting last error NumOfVars
DCOSetupNode methods 79 DCO methods 32 DCO methods 40
get_RuleMaxNumber GetLastError 32 NumOfWords
DCOSetupNode methods 80 getting object name DCOSetup methods 63
get_RuleMinNumber DCO properties 12
DCOSetupNode methods 80 Type 12
get_RuleObjectType
DCOSetupNode methods 81
getting object unique identifier
DCO properties 10
O
object interface
get_RulePosition ID 10
DCO methods 25
DCOSetupNode methods 82 getting Status property
document hierarchy path 25
get_Value DCO properties 11
FindRouteChild 25
DCOSetup methods 59 Status 11
ObjectType
get_Variable getting variable
DCO methods 40
DCO methods 30 DCO properties 12
DCOSetupNode properties 69
DCOSetupNode methods 83 Variable 12
get_VariableName getting variable names
DCOSetupNode methods 84 DCO methods 34
get_VariableValue GetVariableName 34 P
DCOSetupNode methods 84 getting variable values Parent
get_Word DCO methods 35 DCO methods 41
DCOSetup methods 60 GetVariableValue 35 Path
GetChild getting XML file name DCOSetup properties 54
DCO methods 31 DCO properties 13 Populating setup objects
GetLastError XML 13 DCO methods 45
DCO methods 32 GetVariableName SetupObject 45
GetNode DCO methods 34
DCOSetup methods 60 GetVariableValue
GetNodeByName
DCOSetup methods 61
DCO methods 35 R
Read
GetPosition
DCO methods 41
DCO methods 32
GetRoute
I reading files
ID DCO methods 41
DCO methods 33
DCO properties 10 Read 41
GetRule
ImageName reading Setup DCO files
DCOSetupNode methods 85
DCO properties 10 DCO methods 42
getting alternative character field data
interface validity ReadSetup 42
AltText 7
DCO methods 37 Readlock
DCO properties 7
IsValid 37 DCOSetup methods 64
getting character ASCII data values
IsError ReadSetup
DCO methods 29
DCO methods 36 DCO methods 42
get_CharValue 29
IsRoute DCOSetup methods 64
getting character data
DCO methods 36 returning child object index
DCO methods 27, 28
IsValid DCO methods 24
DCO properties 11
DCO methods 37 FindChildIndex 24
get_AltText 27
returning variable index
get_CharConfidence 28
DCO methods 25
Text 11
getting character data confidence value M FindVariable 25
RuleChildName
ConfidenceString 9 MoveChild
DCOSetupNode properties 70
DCO properties 9 DCO methods 37
RuleMaxNum
getting character data value MoveIn
DCOSetupNode properties 70
CharValue 8 DCO methods 38
RuleMinNum
DCO properties 8
DCOSetupNode properties 71
getting character value confidence level
RuleObjectType
CharConfidence 8
DCO properties 8
N DCOSetupNode properties 72
Name RulePosition
getting child object interface
DCOSetupNode properties 68 DCOSetupNode properties 72
DCO methods 23
NumOfChildren Runtime batch hierarchy
FindChild 23
DCO methods 39 API 1
getting confidence level of characters
NumOfDictionaries
AltConfidenceString 6
DCOSetup methods 62
DCO methods 26
DCO properties 6
NumOfNodes
DCOSetup methods 62
S
get_AltConfidenceString 26 set_AltConfidenceString
NumOfRules
getting image file name DCO methods 45
DCOSetupNode methods 86
DCO properties 10 set_AltTex
NumOfVariables
ImageName 10 DCO methods 46
DCOSetupNode methods 87

Index 99
set_CharConfidence setting primary character data Setup DCO (continued)
DCO methods 47 DCO properties 11 getting number of variables
set_CharValue Text 11 DCOSetupNode methods 87
DCO methods 48 setting runtime field position NumOfVariables 87
set_DictionaryName DCO methods 43 getting number of words
DCOSetup methods 64 SetPosition 43 DCOSetup methods 63
set_OMRValue setting Status property NumOfWords 63
DCO methods 49 DCO properties 11 getting object types
set_RuleChildName Status 11 DCOSetupNode methods 81
DCOSetupNode methods 87 setting variable get_RuleObjectType 81
set_RuleMaxNumber DCO properties 12 getting path
DCOSetupNode methods 88 Variable 12 DCOSetup properties 54
set_RuleMinNumber setting XML file name Path 54
DCOSetupNode methods 88 DCO properties 13 getting rule name
set_RuleObjectType XML 13 DCOSetupNode methods 79
DCOSetupNode methods 89 Setup DCO get_RuleChildName 79
set_RulePosition adding nodes getting rule pos attribute
DCOSetupNode methods 89 AddNode 56 DCOSetupNode methods 82
set_Value DCOSetup methods 56 document integrity 82
DCOSetup methods 65 adding rules get_RuleObjectType 82
set_Variable AddRule 75 verifying page order in
DCO methods 49 DCOSetupNode methods 75 documents 82
DCOSetupNode methods 90 adding variables getting SetupNode objects
set_VariableName AddVariable 76 DCOSetupNode methods 85
DCOSetupNode methods 90 DCOSetupNode methods 76 GetRule 85
set_VariableValue deleting rules identifying objects by rules 85
DCOSetupNode methods 91 DCOSetupNode methods 77 getting variable names
set_Word DeleteRule 77 DCOSetupNode properties 73
DCOSetup methods 66 deleting variables identifying objects through index
SetPosition DCOSetupNode methods 78 values 73
DCO methods 43 DeleteVariable 78 VariableName 73
setting alternative character field data DeleteVariableByName 78 getting variable values
AltText 7 getting dictionary name DCOSetupNode methods 83, 84
DCO properties 7 DCOSetup methods 59 DCOSetupNode properties 73
setting character data DCOSetup properties 54 get_Variable 83
DCO methods 46 DictionaryName 54 get_VariableName 84
set_AltTex 46 get_DictionaryName 59 get_VariableValue 84
setting character data confidence value getting dictionary term key value identifying objects through
ConfidenceString 9 DCOSetup properties 55 variable values 73, 83, 84
DCO properties 9 Value 55 Variable 73
setting character data value getting dictionary term key values getting word value
CharValue 8 DCOSetup methods 59 DCOSetup properties 55
DCO properties 8 get_Value 59 Word 55
setting character object position getting dictionary word values searching for child object
DCO methods 43 DCOSetup methods 60 DCOSetupNode methods 79
SetPosition 43 get_Word 60 FindRule 79
setting character value confidence level getting max attribute for child objects setting dictionary key values
CharConfidence 8 DCOSetupNode methods 80 DCOSetup methods 65
DCO properties 8 get_RuleMaxNumber 80 set_Value 65
setting character values getting min attribute for child objects setting dictionary name
DCO methods 48 DCOSetupNode methods 80 DCOSetup methods 64
set_CharValue 48 get_RuleMinNumber 80 set_DictionaryName 64
setting confidence level of characters Getting nodes setting dictionary term key value
AltConfidenceString 6 DCOSetup methods 60 DCOSetup properties 55
DCO properties 6 GetNode 60 Value 55
setting confidence levels Getting nodes by using names setting dictionary word values
DCO methods 47 DCOSetup methods 61 DCOSetup methods 66
set_CharConfidence 47 GetNodeByName 61 set_Word 66
setting image file name getting number of dictionaries setting max attribute for child objects
DCO properties 10 DCOSetup methods 62 DCOSetupNode methods 88
ImageName 10 NumOfDictionaries 62 set_RuleMaxNumber 88
setting object name getting number of nodes setting min attribute for child objects
DCO properties 12 DCOSetup methods 62 DCOSetupNode methods 88
Type 12 NumOfNodes 62 set_RuleMinNumber 88
setting object unique identifier getting number of rules setting object types
DCO properties 10 DCOSetupNode methods 86 DCOSetupNode methods 89
ID 10 NumOfRules 86 set_RuleObjectType 89

100 IBM Datacap: DCO API Guide

Setup DCO (continued) SetupUpNode DCO (continued) WriteSetup
setting path getting rule max attribute DCO methods 51
DCOSetup properties 54 DCOSetupNode properties 70 DCOSetup methods 67
Path 54 RuleMaxNum 70 writing Setup objects
setting rule name getting rule min attribute DCO methods 51
DCOSetupNode methods 87 DCOSetupNode properties 71 WriteSetup 51
set_RuleChildName 87 RuleMinNum 71
setting rule pos attribute getting rule name
DCOSetupNode methods 89
determining page order in
DCOSetupNode properties
RuleChildName 70
70 X
XML
documents 89 Setting object name
DCO properties 13
document integrity 89 DCOSetupNode properties 68
set_RuleObjectType 89 Name 68
setting variable names Setting object type
DCOSetupNode methods 90 DCOSetupNode properties 69, 72
identifying variables through index ObjectType 69
values 90 RuleObjectType 72
set_VariableName 90 Setting rule max attribute
setting variable values DCOSetupNode properties 70
DCOSetupNode methods 90, 91 RuleMaxNum 70
DCOSetupNode properties 74 Setting rule min attribute
identifying objects through DCOSetupNode properties 71
variable values 74, 90, 91 RuleMinNum 71
set_Variable 90 Setting rule name
set_VariableValue 91 DCOSetupNode properties 70
VariableValue 74 RuleChildName 70
setting word value ShowSetupDialog
DCOSetup properties 55 DCOSetup methods 66
Word 55 Status
showing the setup dialog DCO properties 11
DCOSetup methods 66
ShowSetupDialog 66
Setup DCO file
Deleting nodes
T
Text
DCOSetup methods 57
DCO properties 11
DeleteNode 57
Type
Deleting nodes by name
DCO properties 12
DCOSetup methods 58
DeleteNodeByName 58
locking
DCOSetup methods 64 U
ReadLock 64 Unlockit
reading DCOSetup methods 67
DCOSetup methods 64
ReadSetup 64
unlocking
DCOSetup methods 67
V
validating object paths
Unlockit 67
DCO methods 36
SetupNode
IsRoute 36
DCO methods 44
Value
SetupObject
DCOSetup properties 55
DCO methods 45
Variable
SetupUpNode DCO
DCO properties 12
determining child object order
DCOSetupNode properties 73
DCOSetupNode properties 72
VariableName
RulePosition 72
DCOSetupNode properties 73
determining rule order
VariableValue
DCOSetupNode properties 72
DCOSetupNode properties 74
RulePosition 72
getting object name
DCOSetupNode properties 68
Name 68 W
getting object type Word
DCOSetupNode properties 69, 72 DCOSetup properties 55
ObjectType 69 Write
RuleObjectType 72 DCO methods 50

Index 101
102 IBM Datacap: DCO API Guide



Product Number: 5725-C15

SC27-6376-00