Data Tags and Property Data Types

The data tags to access property values are different from other data tags. The basics of there use are the same as all data tags. However, data tags for properties include additional parameters to access the property values and those parameters depend upon the data type of the property they are referencing.

Boolean

A Boolean property will result in a Boolean data tag. Like their property counterparts, Boolean data tags are either true or false. When passed as an argument to a function tag, there are special syntactical rules that apply to Boolean data tags.

When data tag expansion occurs, a Boolean data tag will result in either the text “true” or “false.” Because of this fact, when a Boolean data tag is used as a parameter to a function tag, it should not be enclosed in markers (<< and >>). When a Boolean is not enclosed in these markers, the value of either true or false is passed to the function, rather than the text values of “true” or “false”. This is important since, if the text values are passed to a function that is expecting a Boolean value, it will always consider the value passed in to be true. Remember that true is a value and false is the absence of a value. The text “false” is a value and, thus, will be treated as true in the context of a Boolean parameter.

When a Boolean data tag is passed as an argument to a function, it is likely that the Boolean value of true or false is desired, not the text. In this case, you omit the markers around the tag. This will result in the Boolean value of the tag being passed as an argument to the function. So, in the following examples:
<<if <<object.BooleanProp>> ... >>



<<if object.BooleanProp ... >>
The first will result in the Boolean data tag being expanded to result in:
<<if “false” ... >>

This will result in the text value of “false” being passed to the function.

The second line will result in the Boolean value of true or false being passed to the <<if...>>, rather then the text “true” or “false.” Note that referencing a Boolean without the markers is only valid when the Boolean tag is passed as an argument to a function.

Strings

There are four property data types that will result in a string data tag. These property data types include:
  • String
  • Complex Table Selection
  • Data Table Selection
  • External Data (provides access to the file name and location, not the file data)
The value of the item the data tag provides access to will be placed in the script at expansion time. There is, however, a minor modification to the value that will occur for scripts used in SQL system connections. Any single quotes within the string will be escaped for the database, that is, a second single quote will be placed before the existing quote. This is the standard escape character in most database systems and is necessary as the single quote is used to denote the beginning and end of a string in a SQL statement. So, when expanded, if a string data tag contains the value:
The customer’s car has front end damage.
the value in the script when data tag expansion occurs will be:
The customer’’s car has front end damage.

Note the two single quotes in place of the previously single quote (used as an apostrophe here) within the word “customer’s”. As explained in the chapter on function tags, the <<dequote...>> function also provides this ability. However, for string data tags with a property as its data source, this behavior is automatic.

Another optional behavior in string property data tags is the ability to truncate the value, if needed. This is accomplished through the optional named parameter, length=. The syntax for this is as follows:
<<parent.stringDataTag length=n>>

Denoting this data tag in this manner, the value of the string will be truncated to the length of n. This truncation occurs before any quotes are escaped, so that the extra quotes added in that process are not affected by the truncation. As stated, length is an optional parameter and, if not provided, the entire value of the string will be placed in the script file during data tag expansion.

Another optional parameter to a property string data tag is raw. This parameter will return the value of the string without escaping the quotes it may contain. The syntax for this is:
<<object.stringDataTag.raw>>

Integral and Decimal Numbers

Integral data tags result from properties of the types Integral Number and Identifier. Decimal data tags result from properties of type Decimal Number. During data tag expansion, the value of these tags are placed in the script without modification. In this respect these two data types are treated the same. It is when these values are passed as arguments to functions where the difference between the two types becomes important.

Integral Number data tags will contain whole number values. These data tags can be used with the math function tags that accept integral numbers. Many of the function tags that can accept the use of numerical values have a type parameter. When using this type of data tag, the value to the type parameter of the function is Int.

Decimal Number data tags will contain numerical values that have a fractional portion, such as 2.4 or 3.00. These data tags can be used with math function tags that accept decimal numbers. Many of the function tags that accept the use of numerical data, math tags as well as others, can accept a type parameter. When using this type of data tag, the value for the type parameter is Float.

Date

Date data tags contain a calendar date value. During data tag expansion of a SQL script, date tags are expanded in such a way that the resulting text is enclosed in the conversion function of the target database system that converts string values to date values. So, if a date data tag, StatusDate, contains the value 01/25/2006, then the data tag
<<transaction.StatusDate>>
in an Oracle database will be expanded to the value
to_date(‘01/25/2006’, ‘MM/DD/YYYY’)
It is possible to get just the date value as a string by using the raw parameter, which is available to all date data tags. Continuing with the previous example, the data tag
<<transaction.StatusDate.raw>>
will be expanded to the value
01/25/2006

This can be useful if the date value is to be within some sort of string value within the database, such as a description. In this case, you do not want to convert the value to a database date format, but rather use it as a string.

Time

Time data tags contain a time of day value, in a 24 hour format. When data tag expansion occurs in a SQL script, the resulting value is enclosed in the conversion function for the target database system that is used to convert string values into times. So, if a data tag named EndTime contains the value 13:10:43, then the data tag
<<transaction.EndTime>>
in an Oracle database will be expanded to
to_date(‘13:10:43’, ‘HH24:MI:SS’)
It is possible to access the value as a string, without the conversion function, by using the parameter raw, which is available to all Time data tags. Using the previous example data tag
<<transaction.EndTime.raw>>
will expand to the value
13:10:43

This is used whenever you wish to access just the time string, without converting it to the database time format.

Date And Time

Date and Time data tags are, in essence, a combination of the Time data type and the Date data type. This data tag type contains the calendar date and time of day in a single value. When data tag expansion occurs in a SQL script, the resulting value is enclosed in the conversion function for the target database system that is used to convert string values into dates and times. If a data tag named InspectionDateTime contains the value 02/13/2005 13:20:35, then the data tag:
<<transaction.InspectionDateTime>>
in an Oracle database will be expanded to
to_date(‘02/13/2005 13:20:35’, ‘MM/DD/YYYY HH24:MI:SS’)
As with other data types, it is possible to access the string value without wrapping it in a conversion function, by using the parameter raw, which is available in all Date and Time data tags. Using the previous example data tag
<<transaction.InspectionDateTime.raw>>
will expand to
02/13/2005 13:20:35

This is used whenever just the date and time value is desired, without wishing to convert it before being processed by the enterprise system.

Formatting Dates and Times

These three data types that deal with dates and times support the use of the named parameter format=. This parameter accepts one or more of several date and time tokens. These tokens are combined to provide a picture of how the data should be placed in the file. When a date, time, or date and time data tag contains the format parameter, the default format is overridden, including the conversion function within which the values are normally contained.

Following is a list of the tokens supported by these data tag types. In each of the examples the date and time is 02/07/2001 10:09:03 AM. The Example column contains the value for the token listed. The Short Form contains the example of the value that results by preceding the token with a hyphen, as in: %-m
Token Description Example Short Form
%a The three letter abbreviation of the day. Wed We
%A The name of the day. Wednesday Wed
%b The three-letter abbreviation of the month. Feb n/a
%B The name of the month. February Feb
%d The date of the month. 07 7
%j The Julian date, with a leading 0. 038 38
%m The two digit month (01-12) 02 2
%w The numerical day of the week (0-6 Sunday = 0) 3 n/a
%y The two-digit year 01 1
%Y The four-digit year. 2001 n/a
%R or %r The raw format of the value 36543,37 n/a
%H The hour of the day, 24 hour format. 10 n/a
%h or %I The hour of the day, 12 hour format 10 n/a
%M The minutes of the hour. 09 9
%p AM or PM indicator. A a
%S Seconds of the minute. 03 3
%Z The time zone when the time was recorded. Central Standard Time n/a
non-token characters Any non-format token character, or any character not preceded by the % sign passed to the named parameter format will be returned unchanged at the position at which it was placed in the parameter value. n/a n/a

Signature

Signature data tags result from Signature property types. This data tag type is used with the signature capture functionality available in Agentry. This functionality allows for an application to capture and store a signature the user enters on the screen. The image is stored as a bitmap, and is also available in the raw pixels.

This data tag type supports the following parameters. The value returned for all of these parameters is a string, with the exception of bmp, row.n, and raw.
  • type - Will return either “image” or “none” during expansion. Image indicates that there is an image and the transaction was performed on a client device that supports this functionality. None indicates that the device does not support the signature capture functionality.
  • bmp - This parameter returns the signature, if it exists, in a bitmap format. This returns a string of hexadecimal values that may be used as an argument to another utility program that processes the data, e.g. stores it in a database.
  • height - This parameter returns the height, in pixels, of the signature image.
  • width - This parameter returns the width, in pixels, of the signature image.
  • row.n - This parameter returns the row of pixels, specified by n
  • signed - Returns either true or false. True is returned when a signature has been captured on the client, or, for devices that do not support this functionality, if the check box control that replaces it has been checked. These values are returned as text values of “true” or “false.”
  • raw - Returns the pixels that make up the image.
The syntax for these parameters is:
<<transaction.signatureProp.parameter>>

Of these parameters, only type and signed are always available. The others will return a data tag not found error if a signature was not captured on the client, i.e. signed returns false. Therefore, the return value of signed should be checked before attempting to access the other parameters.

Image

Image data tags result from Image property types. This data tag type is used with the image capture functionality available in Agentry. This functionality allows the application to interact with a device’s built in still camera, when present. A captured image is stored on the device as a file and referenced by the image property.

During synchronization this file data is sent to the server for processing as a part of the transaction data. To access this image data there are two options. The first is to use a file document management step. In this case, it is likely not necessary to reference the data tags for the image property, though they can be when necessary. For other step types access to the image data requires the use of SDML data tags. Data tags for the image property include two parameters in the format <<transaction.imageProperty.parameter>>.

The following list describes these parameters and their purpose:
  • data - This parameter returns the image data in ASCII-encoded hexadecimal values.
  • type - This parameter returns the image type as stored on the client device. The possible return values of this parameter are jpeg, bitmap, and unknown when the file type is not determined.