DIRT Tags

Every development area within the system allows for the use of DIRT tags. These tags provide a method for the management of dynamic parameters within the run-time environment.

Each DIRT tag is identified as opening with "{{", closing with "}}" and uses "||" (Double Pipe) as a parameter delimiter.

A simple statement like:

{{variable||sysdata||42}}

will resolve to the value of the 42nd field of the "sysdata" variable at run time. If the value of sysdata<42> at run time equals "Hello, how are you", then the run time resolution for this tag will be "Hello, how are you". This text will replace the DIRT tag text.

Nested DIRT tags

DIRT tags can be nested. The following example could be placed within an HTML object:

{{convert||oconv||{{variable||sysdata||1}}||mcu}}
will resolve to upper case text extracted from sysdata<1>.

{{convert||oconv||{{variable||sysuser}}||mcu}}
This resolves to an upper case equivalent of the user name.

{{option||{{variable||sysbldval}}||=||1||First Label|| }}
This resolves to the text "First Label" if the variable sysbldval resolves to "1".

The "{{", "}}" and "||" are reserved words.

 

{{assign

This DIRT tag is used to assign a value to a common block variable. It is recommended that this tag be placed in the Header HTML section of the Page properties, although it can be used throughout a page.

Format

{{assign||CommonVarName||Field#.Value#||FieldValue}}

CommonVarName - Any named variable within the common block
Field# - The field position (attribute) to change (1-9999)
Value# - The value position to change
FieldValue - The new value to assign to the request variable

Examples

{{assign||syshidden||14||test}}
syshidden<14> will now contain the string "test"

{{assign||sysdata||1.4||1000}}
sysdata<1,4> will now equal 1000

 

 

{{convert

This DIRT tag is used to do simple string conversions.

Format

{{convert||ConversionType||DataToConvert||CnvParm}}

ConversionType - Any of the types defined below
DataToConvert - The string to convert
CnvParm - Conversion parameters

oconv - output conversion

The oconv function converts a string to a specified format. CnvParm contains the conversion code defined by the OCONV command in BASIC.

{{convert||oconv||Hello||mcu}}
Result - "HELLO"

iconv - input conversion

The iconv function converts a string to a specified format. CnvParm contains the conversion code defined by the ICONV command in BASIC.

{{convert||iconv||1200.00||md2}}
Result - "120000"

fmt

Format the text. CnvParm contains the format code defined by the FMT command in BASIC.

{{convert||fmt||12||r%6}}
Result - "000012"

change

Substring replacement. CnvParm contains the from/to strings. Equivalent to the CHANGE command in BASIC.

{{convert||change||This is a test||t||}}
Result - "This is a es"
{{convert||change||This is a test||t||p||1}}
Result - "This is a pest"

convert

Byte Replacement. CnvParm contains from/to strings. Equivalent to the CONVERT command in BASIC.

{{convert||convert||abcdefg||ac||xy}}
Result - "xbydefg"

trim

Removes extraneous spaces. CnvParm is not used. Equivalent to the TRIM command in BASIC.

{{convert||trim|| This Mess }}
Result - "This Mess"

trimf

Removes spaces from the front of the string. CnvParm is not used. Equivalent to the TRIMF command in BASIC.

trimb

Removes spaces from the back of the string. CnvParm is not used. Equivalent to the TRIMB command in BASIC.

field

Retrieve the required field from a string using a specified delimiter. CnvParm contains the delimiter character. Note that the field command only accepts a single character as a delimiter. If more than one character is specified as a delimiter, then the first character in the string is used as the delimiter. Equivalent to the FIELD command in BASIC.

{{convert||field||aa-bb-cc-dd||-||3}}
Result - "cc"

 

 

{{extract

This DIRT tag is used to extract data from a specific field in an item in a file.

Format

{{extract||FileName||ItemName||FieldNumber}}

FileName - The File name for the extraction
ItemName - The name of the record for extraction
FieldNumber - Field Position, Value Position

Examples

{{extract||syscontrols||parms||1}}
Result - "syslogon" (The first field of the parms record within the syscontrols file)

{{extract||UserFile||Guest||3.4}}
Result - The 4th value of the 3rd field of the guest record within UserFile

 

 

{{field

Retrieve the required field from a string using a specified delimiter. CnvParm contains the delimiter character. Note that the field command only accepts a single character as a delimiter. If more than one character is specified as a delimiter, then the first character in the string is used as the delimiter. Equivalent to the FIELD command in BASIC.

Format

{{field||ItemName||DelimiterName||FieldNumber}}

ItemName - The name of the dynamic array to perform the function on.
DelimiterName - The delimiter character
FieldNumber - Value Position

Example

{{field||aa-bb-cc-dd||-||3}}
Result - "cc"

 

 

{{include

You can use this to include any file on the file system directly into the HTML delivered to the web browser.

Format

{{include||path||filename}}

path - The absolute path to the file you widh to include.
filename - The name of the file

Example

{{include||c:\data||stdfooter.txt}}

 

 

{{lang

This DIRT tag is used to extract a string from the database that corresponds to the language defined for the current user.

Format

{{lang||Default Word/Phrase orUnique ID||Desired Language||Image Flag||Default Text}}

Default Word/Phrase or Unique ID - The text in the default language or an ID of a record in the syslanguage file when used in conjunction with the Default Text parameter.
Desired Language - (Optional) The numeric id, or textual reference to the language required in the Language definition.
Image Flag - (Optional) Set to "IMAGE" to indicate that the text contained is an image.
Default Text - (Optional) The text to display if no translation is available.

Place the standard text, which will be defined as the default text under the Language Translation section, in this field. The system will always default the resultant text to the value in this field if no other option is found.

You can optionally specify the language that should be used in the second parameter by either specifying the numeric index of the language, or the actual textual reference to that language. If the second parameter is not set, then the system will use the language specified in field 23 of the user's record in sysusers (as set up under User Settings).

If the Default Word/Phrase is in fact an image, and you would like the system to automatically insert the correct path to the correct image for each language, you can add the third parameter by setting it's value to IMAGE. The system will then insert the textual reference of that language into the path before the image name. All spaces in the language definition will be replaced with an underscore (_) character. The system will however use a translation if one is found in the translation definitions.

Examples

For the examples below we will assume the language definition has field 1 as French, and field 2 as German.

{{lang||UniqueID||||Hello World}}
Other Settings - none.
Result - Hello World

{{lang||Hello World}}
Other Settings - none.
Result - Hello World

{{lang||UniqueID||||Hello World}}
Other Settings - default user language set to French.
Result - Hello World

{{lang||Hello World}}
Other Settings - default user language set to French.
Result - Hello World

{{lang||UniqueID||||Hello World}}
Other Settings - translations set up for id "UniqueID" and default user language set to French.
Result - French translation of Hello World as defined in translation record

{{lang||Hello World}}
Other Settings - translations set up for phrase "Hello World" and default user language set to French.
Result - French translation of Hello World as defined in translation record

{{lang||Hello World||German}}
Other Settings - translations set up for phrase "Hello World" and default user language set to French.
Result - German translation of Hello World as defined in translation record

{{lang||Hello World||2}}
Other Settings - translations set up for phrase "Hello World" and default user language set to French.
Result - German translation of Hello World as defined in translation record

{{lang||/images/background.gif}}
Other Settings - translations set up for phrase "/images/background.gif" and default user language set to French.
Result - Path to French version of image as defined in translation record

{{lang||/images/background.gif||||IMAGE}}
Other Settings - translations set up for phrase "/images/background.gif" and default user language set to French.
Result - Path to French version of image as defined in translation record

{{lang||/images/background.gif||German||IMAGE}}
Other Settings - translations set up for phrase "/images/background.gif" and default user language set to French.
Result - Path to French version of image as defined in translation record

{{lang||/images/background.gif||||IMAGE}}
Other Settings - default user language set to French.
Result - /images/french/background.gif

{{lang||/images/background.gif||German||IMAGE}}
Other Settings - default user language set to French..
Result - /images/german/background.gif.

 

 

{{locate

This DIRT tag is used to locate an expression in the search field in a dynamic array. The value returned is the corresponding value in the return field on that dynamic array.

The dynamic array specified must be an dynamic array defined in the common block.

Format

{{locate||SearchText||VarName||SearchIn||ReturnFrom}}

VarName - Common block variable name
SearchText - The search text
SearchIn - The field in which to locate the SearchText
ReturnFrom - The field containing the associated result

Examples

{{locate||REMOTE_ADDR||syscgivars||1||2}}
or
{{locate||REMOTE_ADDR||syscgivars}}

Result

IP Address of the user. The REMOTE_ADDR item is searched within "syscgivars" field 1. The resultant IP address is returned from the associated value in field 2.

 

 

{{locatef

This DIRT tag is used to locate an expression in a field in a record in a file. The value returned is the corresponding value in the return field in the record in the file.

Format

{{locatef||SearchText||FileName||KeyName||SearchIn||ReturnFrom}}

SearchText - The search text
FileName - ID of the file to search in
KeyName - Record ID to search in
SearchIn - The field in which to locate the SearchText
ReturnFrom - The field containing the associated result

Examples

{{locatef||extract||syscontrols||parms||15||16}}

Result

"sysxtr" which is the routine that the system uses when the "extract" DIRT tag is run. The file "syscontrols" is opened and the "parms" record read from it. If "extract" is found in field 15 then the resultant value is returned from the associated value in field 16.

 

 

{{named

This DIRT tag is used to associate a value with a named variable.

Format

{{named||NamedItem}}

NamedItem - A valid name defined within the "sysnamed" settings within the system environment.

Examples

{{named||stdbg}}

Result - Possibly resolves to a URL pointing to the standard background image for a set of pages.

 

 

{{option

This DIRT tag is used to evaluate expressions.

Format

{{option||Value1||Oper||Value2||ThenClause||ElseClause}}

Value1 - The First Value
Value 2 - The Seconds Value
Oper - The operation between the two
ThenClause - Value for true result
ElseClause - Value for false result

Maths Operations

+
{{option||1||+||2}}
Result 3

-
{{option||5||-||1}}
Result 4

/
{{option||5||/||2}}
Result 2.5

*
{{option||8||*||2}}
Result 16

DIV
{{option||5||DIV||2}}
Result 2

MOD
{{option||5||MOD||2}}
Result 1

Conditional Operations

=
{{option||10||=||10||It is 10||It is not 10}}
Result "It is 10"

#
{{option||10||#||2||Not Equal||Equal}}
Result "Not Equal"

>
{{option||10||>||5||It is greater||It is less}}
Result "It is greater"

<
{{option||10||<||5||It is less||It is greater}}
Result "It is greater"

>=
{{option||10||>=||10||It is greater or equal||It is less}}
Result "It is greater or equal"

<=
{{option||10||<=||5||It is lessor equal||It is greater}}
Result "It is greater"

 

 

{{script

This DIRT tag is used to place a script, defined as a script object, on a page.

Format

{{script||ScriptName}}

ScriptName - A valid object of type "sysscript".

Examples

{{script||sysmonopen}}

Result - The script inclusions stored within the "sysmonopen" script record.

 

 

{{subroutine

This DIRT tag is used to call a subroutine. The return value of the subroutine is the return value of the DIRT tag.

Format

{{subroutine||SubName||SubParms}}

SubName - The name of the catalogued subroutine. The subroutine must have two parameters (parms,result).
SubParms - The parameter text that will be passed to the subroutine

Examples

{{subroutine||test||These are the parms}}

Subroutine Example
SUB test(parms,result)
*--- include the common block
INCLUDE sysbp syscommon
*--- generate the result
result = \"\:parms:\"\
*--- job well done
RETURN

Result - "These are the parms"

 

 

{{system

This DIRT tag is used to return the result of any valid @ command line command.

Format

{{system||SystemVariable||FldNumber}}

SystemVariable - Any valid "@" variable
FldNumber - A field and value identifier

Examples

{{system||@TIME}}
Result - The time at which this process was started
{{system||@record||4.x}}
Result - The attribute and (build) value within the @record system variable

 

 

{{table

This DIRT tag is used to return a table object (systabmain).

Format

{{table||TheTableName}}

TheTableName- Any systabmain object.

Examples

{{table||syslogonbdr}}
Result - The syslogonbdr systabmain object.

 

 

{{url

This DIRT tag returns a standard URL containing the system executable name (sysexename), the URL parameters needed to replicate security (sessioncopy,sequencecopy), and the parameters required to invoke a page or secure subroutine as specified. If a server PIN is assigned, this tag will use the more secure "linksession" URL parameter.

Format

{{url||page||pagename||parameters}}
OR
{{url||routine||secure subroutine name||parameters}}

pagename - the name of the page to be called
secure subroutine name - the name of the secure subroutine to be called
parameters - optional. Comma separated items which specify switching on or off of certain switched in the URL DIRT tag.
norand -Tells the system not to insert a random number on the URL. A random number is inserted by default to ensure an un-cached page.
nosession - tells the system that you do not want session replication turned on for this link
keepsession - instructs the system to use the current session

Examples

{{url||page||testpage||norand,nosession}}

Result -
/scripts/connector.dll?pagename=testpage

{{url||routine||testroutine}}

Result - /scripts/connector.dll?subrt=testroutine&sessioncopy=...&sequencecopy=...&rnd=...

{{url||page||testpage||keepsession}}

Result - /scripts/connector.dll?pagename=testpage&session=...&sequence=...&rnd=...

 

 

{{variable

This is the most commonly used DIRT tag. It is used to return the value of a data field of a dynamic array defined in the common block.

Format

{{variable||CommonVariableName||FieldNumber.ValueNumber}}

CommonVariableName - Any named variable within the common block
FieldNumber - The field position (attribute) to extract (1-9999)
ValueNumber - The value position to extract ("x" implies the current multi-value)

Examples

{{variable||sysuser}}
Result - User Name

{{variable||syshidden||14.x}}
Result - Multi Value "x" within syshidden<14>

{{variable||sysdata||1.4}}
Result - Multi Value 4 within sysdata<1>

 

 

{{regitem

This DIRT tag is used to return a value from the registry. This DIRT tag has also been incorporated into the UNIX system, but the examples below are specific to Windows.

Format

{{regitem||KeyName||VarName}}

KeyName - is a valid path to a key in the registry
VarName - The item in the registry to be read

There are four main groups in the registry:
HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS
HKEY_CURRENT_CONFIG

A registry path must always be prefixed by one of these and must be in uppercase. After that case is irrelevant.

Examples

{{regitem||HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment||Path}}

Result -
The default system path is returned.