Smart Parameter Actions for IBM Datacap Taskmaster Capture

Answer

Overview
Certain actions can accept Smart Parameters to set or retrieve the value of an object in the Document Hierarchy – typically a Variable or a Field value.  Values can be compared with or set from other Document Hierarchy values, text strings (constants), or other special values as described below.  Only actions that specifically accept Smart Parameters understand and work with them.
Smart Parameters follow a special syntax. Words starting with an at sign (@) are special variables or expressions as described below.  Words that begin with two periods (..) or backslash (\) are navigation expressions as described below.  Words separated by a plus sign (+) are concatenated together.  Words that don’t start with (@ or ..\) are treated as string value constants.  For example: Batch+@BATCHID evaluates as “Batch” followed by the current Batch ID; @F.DICT is the value of the DICT Variable of the current Field, etc.
The main actions in rrunner.rrx that accept Smart Parameters are:

• rr_Get(from): assigns a value to the “calling” object of the Document Hierarchy.
• rrSet(from, to): copies data from one place to another.
• rrCompare(from, to): compares the values specified by two Smart Parameters.
• rrCompare_Not(from, to): compares the values specified by Smart Parameters.
• rrCopy(from, to); Copies values from one field node to another, including zones & character confidence.
• rrAppend(from,to): Appends the value to the target.
• rrPrepend(from,to): Prepends the value to the target.

For versions 7.6 and earlier, these actions are:

• rr_Get(from): assigns a value to the “calling” object of the Document Hierarchy.
• rr_Set(from, to): copies data from one place to another.
• rr_Compare(from, to): compares the values specified by two Smart Parameters.
• rr_Compare_Not(from, to): compares the values specified by Smart Parameters.
• rr_Copy(from, to); Copies values from one field node to another, including zones & character confidence.
• rr_Append(from,to): Appends the value to the target.
• rr_Prepend(from,to): Prepends the value to the target.

This document describes behavior of 8.0 actions and newer. Check the Information for the action in older versions for the exact behavior.

Many other actions accept Smart Parameters. Consult the action help and other documentation for details.

Smart Parameters Concepts and Terminology
The information and tables below show how Smart Parameter actions might be used.
A rule containing a Smart Parameter action is “bound” to an object of the Document Hierarchy. Important! - In Smart Parameter terminology, this is the calling object.

• By default, a Smart Parameter returns a value to the Text property of the calling object.
• An action that retrieves the value of a TaskID and adds it to the “text” variable of the Document Hierarchy’s Batch object might look like this: rr_Get(@TASKID)…as long as the rule is bound to the Batch object.
• In contrast, for an action to assign the string “ThisTask” to the Task_ID variable of the Batch object, the following action would do the trick: rrSet(ThisTask,@B.Task_ID)
• An action to set a page’s variable METRIC to “100,100” would be:
  rrSet(100+@CHR(44)+100,@P.METRIC)
• To compare two values, use the rrCompare action: rrCompare(@TASKID,@B.Task_ID)

Individual Smart Parameters
A Smart Parameter action returns String values when using any of the following ParameterString arguments:

Smart Parameter	Description	Example(s)	Version(s)
@BATCHID	Returns the processing ID of the current batch.	rr_Get(@BATCHID) This assigns the Batch ID of the batch being processed, to the calling object.	6.5, 7.1, 7.5, 7.6, 8.0
@Id	Returns the processing ID of the bound object of the Document Hierarchy…the “calling” object.” For example, if the rule is bound to a Document object, this Smart Parameter retrieves the current document’s value.	rrSet(@Id,@B.Doc_ID) During processing, this example assigns the ID value of the bound object – presumably a Document object – to the Batch object’s Doc_ID variable.  If the Batch object does not have a Doc_ID variable this action will create it. Prior to 8.0.1 Fix Pack 4, all upper case ID could be used. As of Fix Pack 4, all upper case ID can not be used if there is a prefix (i.e. @B.Id, not @B.ID)	6.5, 7.1, 7.5, 7.6, 8.0
@STATUS	Returns the value of a calling object’s STATUS value. Important! STATUS is both a setup property and a runtime variable. As a property, it indicates an object’s nature: -1 specifies an “Anchor Field” or hidden field. During processing, a change in Status may designate a problem (“1” = Problem, “0” = OK).	rrCompare(@STATUS,@B.STATUS) If a rule with this action is bound to the Page object of the source page – Invoice_Page, for example – this very helpful example will compare each page’s processing status to the Batch object’s setup Status. If the values are different, the action will return False, and a follow-up action will probably halt processing (for details, see Page 11).	6.5, 7.1, 7.5, 7.6, 8.0
@TYPE	Indicates an object’s role and specifies its level on the Document Hierarchy: Batch, Document, Page or Field. This is a setup property with values that rarely change.	rr_Get(@TYPE+@Id)	6.5, 7.1, 7.5, 7.6, 8.0
@DATE (format)	Returns the current system Date value. Important! This is the current Date, unless another action has assigned a Date value to a different variable, and an rrSet action is placing that value in this location (Page 11). The parameter can include a format specification (see the examples).	rrSet(@DATE(),@P.Date) This action assigns the current Date to the Date variable of Page associated with the calling object.  rr_Get(@DATE(mm.dd.yyyy) This action formats the date to resemble “12.31.2006” and assigns it to the calling object. The default format is MM/DD/YYYY.	6.5, 7.1, 7.5, 7.6, 8.0
@TIME(format)	Returns the current system Time value. Important! This is the current Time unless another action has assigned the Time to a different variable, and an rr_Set action is placing that value in this location (Page 11). The parameter can include a format specification (see the examples).	rrSet(@TIME(),@P.Time) This action assigns the current Time to the Time variable of the Page associated with the calling object. rr_Get(@TIME(HH:MM) This action formats the Time value to resemble 12:33 and assigns to the calling object.  The default format is HH:MM:SS.	6.5, 7.1, 7.5, 7.6, 8.0
@VALUE	Returns the text value of the bound object…usually a Field object in a source page.	rrSet(@VALUE,..\<FieldName>.Text) If bound to a field, copies the value of that field to the Text property of another field named <FieldName> on the same page.	6.5, 7.1, 7.5, 7.6, 8.0
@CHR(ASCII value)	Returns a character that is a member of the ASCII character set. The advantage of this Smart Parameter is that it allows a character to be accessed and placed that would not otherwise be available – a comma, for example. See the examples for the action’s format.	rr_Get(..\Vendor_Name+@CHR(44)+ ..\Invoice_No) In this case, the rr_Get action constructs a value with three components:  the vendor’s name, a comma, and an Invoice Number.	6.5, 7.1, 7.5, 7.6, 8.0
@JOBID	Returns the value of the current Job ID. Important! The Job ID originates in the Job ID field of the Taskmaster Administrator’s Workflow tab. The Job Name (below) is in the Description field.	rr_Get(@JOBID) If a rule is bound with this action to the Batch object, the rule will update the Batch-level Text variable with the Job ID. rrSet(@JOBID+@JOBNAME) This action assigns the Job ID and the Job Name (below) to the calling object	6.5, 7.1, 7.5, 7.6, 8.0
@JOBNAME	Returns the value of the current Job Name. The Job Name originates in the Description field of the Taskmaster Administrator’s Workflow tab.	rr_Get(@JOBNAME) Sets the current Job Name – its description - to the Text property of the calling object.	7.1, 7.5, 7.6, 8.0
@OPERATOR	Returns the ID of the operator who is running the current task and places this value in the calling object’s Text property – or in a variable of another object designated by the rrSet action. An Operator ID originates in the User ID field of the Taskmaster Administrator’s Users tab. The value of a specific Operator ID is established when the operator signs on and launches the current Job/Task Combination.	rr_Get(@OPERATOR) This action retrieves the ID of the operator responsible for the current task, and places the value in the Text property of the calling object. rr_Get(@BATCHID+@OPERATOR) This very simple Smart Parameter action could be used to connect an operator to a batch, and assign their ID values to a calling object’s Text property.	6.5, 7.1, 7.5, 7.6, 8.0
@STATION	Returns the ID of the workstation which running the current task and places this value in the calling object’s Text property – or in a variable of another object designated by the rrSet action. A Station ID originates in the Station ID field of the Taskmaster Administrator’s Users tab.	rr_Get(@STATION) Station ID along with Operator ID provides useful information about the batch.	6.5, 7.1, 7.5, 7.6, 8.0
@TASKID	Returns the value of the current Task ID. The Task ID originates in the Task ID field of the Taskmaster Administrator’s Workflow tab; the Task Name (below) is in the Description field.	rr_Get(@TASKID) If a rule is bound with this action to the Batch object, the rule will update the object’s Text variable with the Task ID whenever a task runs. rrSet(@JOBID+@TASKID) This action assigns the Job ID and the Task ID to the calling object’s Text property.)	6.5, 7.1, 7.5, 7.6, 8.0
@TASKNAME	Returns the value of the current task name.  (see the example.) The Task Name originates in the Description field of the Taskmaster Administrator’s Workflow tab.	rr_Get(@TASKNAME) Assigns the current Task Name – its description -  to the Text property of the calling object – unless the action indicates a different location (see the examples.)	6.5, 7.1, 7.5, 7.6, 8.0
@EMPTY	Represents an empty string	rrSet(@EMPTY) This action assigns the calling objects Text property to an empty string, does not affect any other calling object values.	7.1, 7.5, 7.6, 8.0
@VAR(variable name)	Returns the value of the calling objects variable variablename. This is the same as using @F.variablename	rr_Get(@VAR(ID)) This action retrieves the unique Taskmaster "ID" of the calling object, and sets the calling object Text value to this ID.	7.5, 7.6, 8.0
@DCO(property name)	Returns the value of the calling object’s DCO property as specified in the property name argument. 8.0 Supported Properties: ID, TYPE, STATUS, BATCHDIR, BATCHPRIORITY, IMAGENAME, TEXT, CONFIDENCESTRING, XML.	rr_Get(@DCO(ImageName)) This action sets the calling object's Text value to the DCO ImageName property of the calling object.	7.5, 7.6, 8.0
@PILOT(property name)	Returns the value of the PILOT object property specified in the property name argument. 8.0 Supported Properties: BATCHID, BATCHDIR, OPERATOR, STATION, CHILDRENQUANTITY, PRIORITY, CAPTION, PROJECTPATH, PAGESINBATCH, DOCSINBATCH, EXPECTEDPAGES, EXPECTEDDOCS, ADJUSTEDPAGES, ADJUSTEDDOCS, JOBNAME, TASKNAME, FORMPATH, DCOFILE, JOBID, TASKID.	rr_Get(@PILOT(ProjectPath)) This action sets the calling objects Text property to the value of the Pilot.Projectpath property.	7.5, 7.6, 8.0
@STRING(string value)	Returns a string of the argument passed.	rr_Get(@STRING(..\HI+2)) This action sets the calling objects Text property to  “..\+2”	7.5, 7.6, 8.0
@PATH(key)	Returns the full path to a file that is defined in the configuration file “paths.ini” located in the application project folder.  For example, in the 1040EZ sample application, if c:\…\1040ez\process\paths.ini contains: [Paths] ExportDir=..\Export Then @PATH(ExportDir) would return c:\…\1040ez\Export	rr_Get(@PATH(Images)) This action assigns/sets the calling objects Text property to the value returned from the key ‘Images’ in the calling application files ‘Paths.ini’. The value of the entry is treated as a relative path., such that a paths.ini entry of ‘..\Images’ would result in a file path with the images directory being a sibling folder of the folder containing the paths.ini file and SetupDCO.xml.	7.5, 7.5SP1, 7.6, 8.0
@APPVAR(key)	Returns the value defined in the configuration file “paths.ini” located in the application project folder.  For example, in the 1040EZ sample application, if c:\…\1040ez\process\paths.ini contains: [Variables] LookupDSN=.PROVIDER=XYZ Then @APPVAR(LookupDSN) would assign PROVIDER=XYZ to the calling object's value. 8.0+: @AppVar smart parameter changed to look in the App Service for the current application for the passed argument/variable. If it cannot connect to the App Service or if it cannot find the requested variable, it logs that fact and then looks in the [Variables] section of current applications paths.ini in the process (or dco_appname) folder.	rr_Get(@APPVAR(LookupDSN))	7.5, 7.5SP1, 7.6, 8.0
@APPPATH(key)	Returns a full path value from the Application service.		8.0
@DICT_VALUE(smart parameter path)	Returns the DCO dictionary VALUE of  the OMR field specified in the parameter, which is a smart parameter path.	rrSet(@DICT_VALUE(..\SEX)) This action sets the calling objects Text property to the Dictionary VALUE of the OMR field ‘SEX’ which is a sibling field to the calling object.	7.1, 7.5, 7.6, 8.0
@DICT_WORD(smart parameter path)	Returns the DCO dictionary WORD of the OMR field specified in the parameter, which is a smart parameter path.	rr_Get(@DICT_WORD(..\SEX)) This action sets the calling objects Text property to the Dictionary WORD of the OMR field ‘SEX’ which is a sibling field to the calling object.	7.1, 7.5, 7.6, 8.0
@DICT_WINDEX(csv string)	The argument is a csv string of the dictionary word to match. Returns a zero filled string where matched indexes are represented by the '1' character.		8.0
@DICT_VINDEX(csv string)	The argument is a csv string of the dictionary value to match. Returns a zero filled string where matched indexes are represented by the '1' character.		8.0
@PROJECTDIR	Returns the directory path to the PILOT application settings file.	rr_Get(@PROJECTDIR+\+myfile.ini) This action sets the calling object's Text property with a path to a file named myfile.ini located in the same directory as the current task’s settings file (bpp).	7.5, 7.6, 8.0
@PROCESSDIR	Returns path to the process folder.  Process folder is defined as the directory containing the task’s setup dco.		8.0

Smart Parameter Navigation Syntax
An action with a Smart Parameter typically delivers a value directly to the calling object…to the object of the Document Hierarchy to which the action’s rule is bound. However, an action’s syntax can be modified so that the rule locates values in variables of objects at various levels of the Document Hierarchy and, if appropriate, assigns the values to the variables of objects at different levels.   
The following syntax parameters can be used to help Smart Parameter actions access and deliver data to and from objects of the Document Hierarchy, from level to level.
The descriptions in the table below use a simplified structure. In addition, the descriptions assume that values are returned to the calling object.
Batch: Invoice

   Document: Document
Page: Main_Page
Field:  Vendor_Name
Field:  Invoice_No

Navigation	Description
<object>.	The period (“.”) introduces a variable name – @D.Doc_ID, for example. rr_Get(@D.Doc_ID) retrieves the Document object’s Doc_ID variable value and assigns it to the calling object’s Text property. rrSet(13,@P.b_tp) sets the Page variable named b_tp to the value 13.  For a Bar Code field, this sets the bar code symbology to Code 39.
@B, @D, @P, @F	References the parent Batch, Document, Page and Field of the calling object.  For example: @P.Type refers to the Type variable of the current page. @P\Type refers to a field called Type for the current page.
..\	Designates a parent and child object, and returns the value of the child as long as it is one or more levels below the calling parent. For example, if the calling object is Document, the rr_Get action can return the value of the Invoice_No field because Invoice_No is a child of the Main_Page object.       rr_Get(\Main_Page\Invoice_No) In the example below, the calling object might be the Invoice batch object which would have the Text property of the Invoice_No field returned.      rr_Get(\MyDoc\Main_Page\Invoice_No)  Vendor_Name and Invoice_No are both siblings at lower levels. This action would copy the value of Vendor_Name to sibling Invoice_No.  Note that this process only copies the value and does not copy field confidence or captured zone info to Invoice_No.    rrSet(..\Vendor_Name,..\Invoice_No) The following action would return the text value of the object PagesPerDoc, which is a child of the calling object.    rr_Get(\PagesPerDoc)
+ (Concatenation)	Returns the concatenation of Smart Parameter values (one appended to the other) Here, the action appends Job ID and Task ID together and puts the resulting value in Batch variable JTInfo.    rrSet(@JOBID+@TASKID,@B.JTInfo)

Smart Parameter Actions
The following tables describe the rrunner.rrx Smart Parameter actions.

rr_Get

Actions Library	rrunner.rrx
Description	Uses the inserted Smart Parameter as a parameter to locate the value of an object variable, and assigns it to the Text property of the calling object.
Parameters	String Smart Parameter that identifies the target object and its variable.
Level	All levels.
Returns	False if the calling object and the target object are identical – or if the action cannot locate the target object. Otherwise, True.
Example	rr_Get(@D.Tot_Pages) This action locates the value in the Tot_Pages variable of the parent document, and assigns it to the Text property of the calling object.

rrSet

Actions Library	rrunner.rrx
Description	Uses the two Smart Parameters elements - The value of the variable for the first object is assigned to a variable of the second object.
Parameters	For 7.6 and earlier, a comma-separated String consisting of two Smart Parameters. For 8.0 and newer, two separate Stringvalues. Parameter 1 - A reference to the variable of an object that will be the value’s source. Parameter 2 - The identity of a target object, i.e. the variable or field where the value will be placed. For both elements, the action defaults to the Text property of the calling object.
Level	All levels.
Returns	False if the calling object and the target object are identical – or if the action cannot locate the target object. Otherwise, True.
Example	rrSet(@D.Tot_Pages,@B.Tot_Pages) This variation on the example for the rr_Get action locates the value in the parent document’s Tot_Pages variable and assigns it to the Tot_Pages variable of the Batch object.

rrCompare

Actions Library	rrunner.rrx
Description	Uses the inserted Smart Parameters as the parameter to locate and compare the values of two objects' variables. If the values do not match, the action returns False.
Parameters	For 7.6 and earlier, a comma-separated String consisting of two Smart Parameters. For 8.0 and newer, two separate Stringvalues. Parameter 1 - A reference to the variable of an object that is the first value’s source. Parameter 2 - A reference to the variable of an object that is the second value’s source.
Level	All levels.
Returns	False if the calling object and the target object are identical – or if values do not match. Otherwise, True.
Example	rrCompare(@D.Tot_Pages,@B.Tot_Pages) This variation on the examples for the previous action shows how a value is solicited from a comparable variable of two objects – the parent batch and document. The two values are then compared: the action returns False if the values are not the same.

rrCompare_Not

Actions Library	rrunner.rrx
Description	Uses the inserted Smart Parameters as the parameter to locate and compare the values of two objects’ variables. If the values do not match, the action returns True.
Parameters	For 7.6 and earlier, a comma-separated String consisting of two Smart Parameters. For 8.0 and newer, two separate Stringvalues. Parameter 1 - A reference to the variable of an object that is the first value’s source. Parameter 2 - A reference to the variable of an object that is the second value’s source.
Level	All levels.
Returns	True if the calling object and the target object are identical – or if values do not match. Otherwise, False.
Example	rrCompare_Not(@D.Tot_Pages,@B.Tot_Pages) This variation on the examples for the previous action shows how a value is solicited from a comparable variable of two objects – the parent batch and document. The two values are then compared: the action returns True if the values are not the same.

rrCopy

Actions Library	rrunner.rrx
Description	Copies values from one field node to another, including zones & character confidence.
Parameters	For 7.6 and earlier, a comma-separated String consisting of two Smart Parameters. For 8.0 and newer, two separate Stringvalues. Parameter 1 - A reference to the field object that is the first value’s source. Parameter 2 - A reference to the field object that is the second value’s source.
Level	All levels.
Returns	True if the calling object and the source and target objects exist, otherwise False.
Example	rrCopy(@P\SubTotal,@P\Total)

rrAppend

Actions Library	rrunner.rrx
Description	Uses the two Smart Parameters elements - The value of the variable for the first object is appended to a variable of the second object.
Parameters	For 7.6 and earlier, a comma-separated String consisting of two Smart Parameters. For 8.0 and newer, two separate Stringvalues. Parameter 1 - A reference to the variable of an object that will be the value’s source. Parameter 2 - The identity of a target object, i.e. the variable or field where the value will be appended. For both elements, the action defaults to the Text property of the calling object.
Level	All levels.
Returns	False if the calling object and the target object are identical – or if the action cannot locate the target object. Otherwise, True.
Example	rrAppend(@D.Tot_Pages,@B.Tot_Pages) This variation on the example for the rr_Get action locates the value in the parent document’s Tot_Pages variable and appends it to the Tot_Pages variable of the Batch object.

rrPrepend

Actions Library	rrunner.rrx
Description	Uses two Smart Parameters elements – The value of the variable for the first object is prepended to the value of the variable for the second object.
Parameters	For 7.6 and earlier, a comma-separated String consisting of two Smart Parameters. For 8.0 and newer, two separate Stringvalues. Parameter 1 - A reference to the variable of an object that will be the value’s source. Parameter 2 - The identity of a target object, i.e. the variable or field where the value will be appended. For both elements, the action defaults to the Text property of the calling object.
Level	All levels.
Returns	False if the calling object and the target object are identical – or if the action cannot locate the target object. Otherwise, True.
Example	rrPrepend(@D.Tot_Pages,@B.Tot_Pages) This variation on the example for the rr_Get action locates the value in the parent document’s Tot_Pages variable and prepends it to the Tot_Pages variable of the Batch object.