Chapter Seven

Working With Variables

How to Use Variables

Variables are placeholders that you can assign a value to; they are created and assigned values using the Assign action or the <@ASSIGN> meta tag.

Every variable belongs to a scope, which tells Tango if the variable is to be used only for the particular application file execution, for a user, or for a particular domain being served with Tango.

Arrays are a special variable type that allow you to create a structured data table with multiple values, as opposed to standard variables which only store one value.

One important set of variables determines the behavior of certain Tango options. These are called configuration variables.

This chapter covers the following topics:

• introduction to variables--standard and array--including variable scope and its effects
• how to assign values to variables
• configuration variables
• changing a special user variable option: the user key.

[back to top]

About Variables

Variables are defined and given values with an Assign action in a Tango application file.

For more information, see "Where You Can Use Meta Tags".

Variables can also be assigned values by using the <@ASSIGN> meta tag.

You can assign any combination of literal values and meta tag values to a variable. For example, to assign a full phone number using values from area code and phone number form fields, you could use "(<@POSTARG area>) <@POSTARG phone>" as the variable value.

Naming Variables

All variable names:

• must start with a letter
• may contain numbers, letters, and the underscore ("_") character.
• may be no longer than 31 characters.

Variable names are case insensitive; for example, myVar is the same variable as MYVAR and MyVaR.

Understanding Scope

Every variable belongs to a scope. There are several scopes that are used for different purposes within Tango. The following diagram shows the different scopes and their relationships.

Variables that are assigned values in more restrictive scopes override variables with the same name that are assigned values in more general scopes.

Local scope is the most restrictive; variables that belong to this scope are used only for the execution of a particular application file. Cookie scope refers to variables that are sent to and kept by Web browsers. User scope refers to variables that are set for particular users within Tango. Domain scope refers to variables that are used in a particular World Wide Web domain. System scope is the most general, applying to the entire Tango Server. This scope is restricted to configuration variables.

You can find more details on these scopes in the following sections.

Local

Local scope is used for variables that expire after an application file is executed. That is, after the application file (and its branches, if any) have finished executing, the variable is purged from memory.

Local variables could be used for a counter within a loop. The counter is not needed outside the application file that it is in, so using a local variable would be appropriate.

For another example, a user might enter a choice during the execution of an application file to have full explanations returned during the execution of an application file (for a beginning user), or rather terse commands (for an experienced user). At the beginning of the application file, a local variable is set, and that variable is used in the rest of the application file to determine what HTML is returned to the user.

User

Variables that have user scope let you store and access values associated with a particular user. Once an assignment has been made to a user variable, its value is available in subsequent actions within the same application file execution and in any application files executed afterward.

For example, user variables would be necessary in an application file that logs users in to a private area of your Web site, displaying a Web page that prompts for a user's name and password. You might want to save the entered name so you can display it on personalized pages in subsequent queries. Or you may need to use the name to restrict database queries performed by that user. Both of these actions would be performed with a user variable.

For more information, see "variableTimeout" in the Meta Tags and Configuration Variables manual.

User variables expire 30 minutes after the user associated with them last accesses Tango. You can change the timeout by changing the value of the Tango configuration variable variableTimeout.

Cookie

Cookie scope is used for variables that are sent to the user's browser as cookies (that is, saved in a small text file and kept by the browser for a specified amount of time).

Cookies are saved by the browser and then are sent to the site by the browser when it returns to the site that generated the cookie in the first place. Cookie variables can be used to save state information between browser sessions or in a single browser session.

For more information, see "Cookie Properties".

There are a variety of cookie options that can be set for cookie variables, such as when the cookies expire.

Domain

Domain scope is used for variables that are relevant to a particular domain. Domain variables, like system variables, are persistent across application files and users.

For more information, see "variableTimeout" in the Meta Tags and Configuration Variables manual.

Domain scope variables, by default, expire after the time period specified by variableTimeout (system scope). To change the expiry timeout period for domain variables, assign the desired value to variableTimeout in domain scope.

Domains are different base URLs; for example, one Web server could be hosting several different domains (www.my_company.com, www.your_company.com, www.a_non_profit.org). Tango uses an encrypted form of the domain used to access the file as the domain key, and any variable set with scope=DOMAIN is set for the particular domain where the application file is executed.

Caution: You can add your own password to the encrypted domainScopeKey if you want to ensure that application files created by others and run on your server cannot change your domain variables.

For more information, see "domainScopeKey" in the Meta Tags and Configuration Variables manual.

For example, a variable called organization with domain scope could be assigned a value in two different domains hosted on the same Web server (values are "My Company, Inc." and "My Non-Profit"). When an application file returns the value of organization SCOPE=domain (say, in a standard footer), a different value is returned depending on the URL that is being accessed, even though the variable name is the same.

Domain scope for variables lets you easily store values that are shared by all users of a particular domain. By default, the domain key (that is, the piece of information Tango uses to determine which domain a user belongs to) is based on the SERVER_NAME CGI parameter. The value of the SERVER_NAME parameter comes from the URL used to initiate each request by a user. For example, if a user requests

http://www.yourserver.com/foo.taf

the domain variable is keyed on "www.yourserver.com". Everyone using "www.yourserver.com" to access a Tango application file gets the same values for domain variables.

However, if a user accesses the exact same application files with the IP address of the server (http://206.186.95.106/foo.taf), the domain scope variable is different because the key value is now the server's IP address not the server's name. The same applies if you access the Web site locally with:

http://localhost/foo.taf

This behavior is not usually a problem because most users access your site with the server name, not its IP address. If, however, you need to be sure domain variables are being shared by users hitting your site with its IP address and also using its domain name, consider the following options:

• If your Tango Server is hosting just one domain, you can set the domain scope key to the name of that domain (for example, "www.myserver.com" or any constant value). That way, the value of the key is the same for everyone using your server, regardless of the URL used to access it. Use the configuration application file (config.taf) to set the value of the domainScopeKey variable to the desired value.

For more information, see "httpHeader" in the Meta Tags and Configuration Variables manual.

For more information, see "<@CRLF>" in the Meta Tags and Configuration Variables manual.

• At the main entry points of your site, redirect the user to your site using the domain name. You can use a Tango application file to do this by setting the httpHeader variable (local scope) to:

  HTTP/1.1 302 Temporarily Moved<@CRLF>Location: http://www.yourserver.com/foo.taf<@CRLF><@CRLF>

• Use absolute URLs in links to Tango application files. For example, instead of <A HREF="/mydoc.taf">mydoc</A> use
  <A HREF="http://www.myserver.com/mydoc.taf">mydoc
  </A>

System

System scope is used for variables that are set at the system level, that is, only configuration variables. Many configuration variables that affect the behavior of Tango are set with system scope. For example, the variable dateFormat sets the way the date is displayed when it is returned by Tango with a meta tag such as <@CURRENTDATE>. If this variable is set with system scope, then all dates returned by Tango are in that format.

For more details on different scopes for configuration variables, see "Understanding Scope".

Certain configuration variables can be set for different scopes. This means that the value changes in one particular scope (and all scopes that scope dominates) while maintaining its default value elsewhere.

For example, dateFormat can be set with scope=LOCAL, which changes the format of the date for the current application file; scope=USER, which would change the format of the date for all application files executed by a particular user; or scope=DOMAIN, which would change the format of the date for all application files and users that use a particular URL containing a domain to access Tango.

To set system configuration variables

For more information, see "Configuring Tango Server".

You can set system configuration variables with the config.taf application file. This application file prompts you for a password and then presents groups of related configuration variables on different screens, allowing you to easily set system configuration variables.

To set configuration variables without using the config.taf application file (that is, in an application file), you must know the correct password. This password is stored in the t3server.ini configuration file and a configuration variable called configPasswd.

When you attempt to set a system configuration variable, Tango checks to see if there is a variable called configPasswd with scope=USER that matches configPasswd with scope=SYSTEM. If there is, Tango lets you change configuration variables. If not, Tango returns an error message.

Setting configPasswd scope=USER can interact with user keying mechanisms; see "Changing the User Key".

That is, you must assign the value of an entered string (for example, <@POSTARG NAME="Password">) to the configuration variable configPasswd with scope=USER using the Assign action or the <@ASSIGN> meta tag.

Returning Variable Values

To have Tango return the value of a particular variable, use the <@VAR> meta tag. This tag is replaced with the variable value at the time that the application file is executed. For example, to return the value of the variable named fred in user scope:

<@VAR NAME="fred" SCOPE="user">

Default Scoping Rules

If you do not specify a scope parameter, Tango checks for matching variables in different scopes, from the most restrictive to the most general:

<@VAR NAME="fred">

Tango checks for matching variables in local, user, cookie, domain, and system scope, returning the value for the first matching variable that it finds.

Note: Cookie scope is a special scope, and Tango does not check for matching variables with this scope when returning unscoped variable values with <@VAR>.

Shortcut Syntax for Returning Variables (@@foo)

There is a shortcut syntax for returning variables as well, with or without scope: use a double "@" and the name of the variable. The following two notations are equivalent:

<@VAR NAME="fred"> --> @@fred

To use a scope parameter with this shortcut, place it in front of the variable being accessed, with a dollar sign ("$") in between. The following two notations are equivalent:

<@VAR NAME="fred" SCOPE="user"> --> @@user$fred

If you are creating complicated meta tag syntax, using this shortcut may help to make things clearer.

The 31-character length limit on variable names is exclusive of any scope specifier; for example, in local$longvariablename, the length limit applies to the variable name portion.

Arrays

Arrays are a special type of variable that allow you to store many different values in a structured format. This is distinct from the standard variable, which only stores one value.

Arrays are structured as a table with rows and columns; values are saved at each row and column intersection. This is similar to the way values are saved in a database table: as rows and columns.

For example, a three-row by four-column array with the values of the first twelve integers would look like this:

1 2 3 4
5 6 7 8
9 10 11 12

Setting Arrays

For more information, see "<@ARRAY>" in the Meta Tags and Configuration Variables manual.

To create an array--for example, the one in the previous paragraph--use the <@ARRAY> tag within the Assign action or the <@ASSIGN> and <@ARRAY> meta tags together:

You can use the <@ARRAY> tag to create arrays by using only rows and columns (ROW attribute and COLS attribute), which creates an array with the specified dimensions, all of whose elements are empty, or by using the VALUE attribute to create and initialize the array with values. If ROWS, COLS, and VALUE are specified, they must match in terms of the number of rows and columns specified.

The meta tag assignment of an array to a variable looks as follows:

For more information, see "<@ASSIGN>" in the Meta Tags and Configuration Variables manual.

<@ASSIGN NAME="arrayVar" VALUE=<@ARRAY ROWS="3" COLS="4" VALUE="1,2,3,4;5,6,7,8;9,10,11,12">>

When using an Assign action to create an array and assign it to a variable, the Value field would contain an <@ARRAY> meta tag.

For more information, "cDelim" and "rDelim" in the Meta Tags and Configuration Variables manual.

(The row and column delimiters for VALUE are set with the configuration variables rDelim and cDelim, or with the <@ARRAY> tag's optional attributes RDELIM and CDELIM. By default, they are set to ";" and "," respectively.)

Array cells can contain single values only. They cannot contain other arrays.

Array Formats

How arrays are returned depends on context, that is, where an array-returning meta tag such as <@VAR> is used.

Arrays are returned as array variables (with their special internal structure) when used in assignments to other variables, for example:

<@ASSIGN NAME="fred" VALUE="<@VAR NAME=
'array_variable'>">

When referred to anywhere else (for example, returned in Results HTML using the <@VAR> meta tag), arrays are converted to a text representation using the supplied <@VAR> attributes for prefixes and suffixes, or the configuration variable defaults, if no attributes are specified.

Returning the Values of Arrays

Remember an array is not just a list of values; it has two-dimensional structure. For example, if you set up and gave values to the variable fred as above and then asked Tango to return the value of the array in HTML only, Tango would return the structured string of values, using delimiters to separate rows and columns.

Along with many other uses for programming and database work, arrays offer a quick method of returning a table or ordered list of values in HTML. The <@VAR> meta tag has attributes that can be used with arrays:

APrefix: the array prefix string
ASuffix: the array suffix string
RPrefix: the row prefix string
RSuffix: the row suffix string
CPrefix: the column prefix string
CSuffix: the column suffix string

For detailed information on all configuration variables, see the Meta Tags and Configuration Variables manual.

The defaults of these parameters are set with configuration variables. If the above array variable is returned using <@VAR> with the default parameters:

APrefix='<TABLE BORDER=1>'
ASuffix='</TABLE>'
RPrefix='<TR>'
RSuffix='</TR>'
CPrefix='<TD>'
CSuffix='</TD>'>

the following simple table is returned when <@VAR NAME="fred"> is retrieved in Results HTML:

For more information on arrays, see "<@ARRAY>", "<@VAR>", and other meta tags that return arrays in the Meta Tags and Configuration Variables manual.

<TABLE BORDER=1><TR><TD>1</TD><TD>2</TD><TD>3</TD>
<TD>4</TD></TR><TR><TD>5</TD><TD>6</TD><TD>7</TD>
<TD>8</TD></TR><TR><TD>9</TD><TD>10</TD>
<TD>11</TD><TD>12</TD></TR></TABLE>

Using different suffixes and prefixes could create different kinds of HTML code, such as various kinds of lists.

You can retrieve one single value from an array by specifying row and column co-ordinates:

<@VAR NAME="FRED[2,3]">
--> Tango returns 7

You can return one column or one row from an array by specifying only one of the co-ordinates, and setting the other to *:

<@VAR NAME="FRED[2,*]">
--> Tango returns a one-column array with the values 5 6 7 8
<@VAR NAME="FRED[*,3]">
--> Tango returns a one-row array with the values 3 7 11

Special Array: resultSet

Whenever an action returns a result rowset in Tango (for example, a Search action), that rowset is assigned, in array format, to the local variable resultSet. This variable could be used in Result HTML to return your search result, for example:

Your search returned the following results:
<@VAR NAME="resultSet" SCOPE="local">.

As with any array variable, you can use the prefix and suffix attribute name/value pairs to change how the array is formatted in HTML.

resultSet Named Columns

A special property of resultSet is that when it returns the results of a Search action or Direct DBMS query, its columns are named. This means that you can refer to the names of columns (instead of the column number) when returning the value of the resultSet array. For example, if you selected these columns in the order shown (as the result of a Search action):

The following expressions in Results HTML evaluate as shown:

<@VAR NAME="resultSet[3,2]">
--> Tango returns 1234

Using named columns, you could return the same values using the following syntax:

<@VAR NAME="resultSet[3,customer_ID]"> --> Tango returns 1234

You can use a combination of asterisks and named columns:

<@VAR NAME="resultSet[*,customer_Name]">
--> Tango returns Smith Jones Johnson (a one-column array).

[back to top]

Assigning Variables With the Assign Action

To assign a variable

Drag the Assign action from the Action bar into the application file window.

The Assign action is inserted into the application file and the Assign editing window appears.

The Assign editing window consists of a three-column list. Each row of the list shows the variable scope, name and value, along with a field that changes to a pull-down menu when active. This field allows you to change the scope. The scope can be one of Local, Cookie, User, Domain, or System.

You can add one or more variable assignments to each Assign action.

To add a new variable assignment to this window

Do one of the following:

• From the Edit menu, choose Insert.
• On the main toolbar, click the Insert icon.

  

• Right click the Assign window and choose Insert Assignment from the context-sensitive menu that appears.

To select an assignment

Click the row.

To move an assignment

Click an assignment and drag it to the desired position.

To delete an assignment

You can also use the right mouse menu in the Assignment window. See "Editing Variable Assignments".

1. Click the assignment you want to delete.
2. Do one of the following:
   • From the Edit menu, choose Delete.
   • On the main toolbar, click the Delete icon.

     

   • Press the Delete key.
3. When the dialog box appears asking you to confirm the deletion, click OK.

Editing Variable Assignments

You can type text in the Name and Value fields, and assign scope in the Scope field.

For more information, see "defaultScope" in the Meta Tags and Configuration Variables manual.

The Scope field contains a pop-up menu which allows you to change the scope. The scope can be Default, Local, Cookie, User, Domain or System.

Using the context sensitive menu, you can fill in names from previously assigned variables.

The Document Variables submenu contains an alphabetical list of all variables assigned (via Assign actions) in the current application file. Selecting an item from this list sets both the scope and name for the variable assignment.

Context Sensitive Menu

The content area of the Assignment rows within the Assign window supports a context-sensitive menu, as seen above.

The menu contains Document Variable, Insert Assignment, Delete Assignment, and Properties items. All of these are active when you invoke the menu on an assignment. If you click a selected row, then the right click menu contains just Delete Assignment and Properties items.

Editing Properties

Selecting the Properties command when an assignment is selected (either the whole line or while editing any part of it), or selecting an assignment when the properties window is already open shows the assignment's properties.

The Assign Properties window consists of two tabs: General and Cookie. The General tab allows editing of the name, value and scope.

The Cookie tab appears only if the scope for the current assignment is "Cookie".

Cookie Properties

The Cookie section contains controls for editing attributes of cookie variables. (Each group of settings corresponds to an element of the Set-Cookie HTTP header line.)

The default values for new cookies are as shown.

• Expiry

  When user quits browser is the default cookie behavior as described in the cookie specifications. When this option is chosen, the Expires value is omitted from Set-Cookie line in the cookie header.

  After __ [time units]. The drop-down list for time units has minutes, hours, days, and years options. The text entry field holds up to 31 characters and a meta tag can be specified there.

• Domain

  Current server omits the Domain value from the Set-Cookie line, causing the cookie to be valid for the current server.

  Other allows specification of any domain string up to 31 characters. ".pervasive.com", for example, would cause the cookie to be sent back to www.pervasive.com, demo.pervasive.com, sales.pervasive.com, and so on.

• Path

  Server root (/) specifies that the cookie be sent for all paths within the specified domain.

  Other allows specification of a path string up to 31 characters. For example, /tango/ would cause the cookie to be sent back only for URLs below the tango folder.

• Require secure connection for client send

  True (enabled) or False (disabled). This option sets the Secure value of the Set-Cookie line. If the value is set to true, then the cookie is sent back by the browser only if a secure connection is being made.

How Tango Determines Default Scope in Variable Assignments

When you assign a value to a variable but do not specify a scope, Tango performs these steps to determine which scope to use:

• Tango looks for an existing variable with that name. The search starts in the local scope, and continues up through user, cookie, domain, and finally to system scope. If Tango finds the variable, it assigns the value to it and stops looking.
• If no variable with the specified name is found, Tango creates the variable in the user scope. (This default scope for new variables can be changed using the defaultScope configuration variable).

Here are some examples. Assume these variables are already defined:

<@ASSIGN NAME="foo" VALUE="myVal"> assigns myVal to the existing local variable foo.

<@ASSIGN NAME="doh" VALUE="myVal"> creates a new user variable called doh and assigns myVal to it.

<@ASSIGN NAME="ipsum" VALUE="myVal" SCOPE="local">
creates a new local variable called ipsum and assigns myVal to it.

<@ASSIGN NAME="lorem" VALUE="myVal"> assigns myVal to the domain variable lorem.

[back to top]

Using Configuration Variables

Configuration variables are special values that control basic Tango behaviors. For example, there are configuration variables for controlling such settings as:

• the type of information written to Tango Server's log file (loggingLevel)
• the default date format used by Tango Server (dateFormat)
• how long user variables last before expiring (variableTimeout).

For a complete and detailed list of configuration variables, see the Meta Tags and Configuration Variables manual.

Some configuration variables can be set in all scopes (except cookie scope), some in particular scopes, and some only in system scope. For those configuration variables that can be set in all scopes, the different scopes have the following effects:

For more information, see "Configuring Tango Server".

For more information on how to use config.taf, see Chapter 20.

• scope=SYSTEM affects all application files executed by Tango Server. Assignments made to these configuration variables remain in effect until you change them again (even after stopping and starting Tango Server). The values of these variables are saved in the t3server.ini configuration file.

  The config.taf application file provided with Tango (in the admin folder) makes it easy to change the values of these configuration variables from your Web browser application. You need to know the password set by configPasswd in order to set configuration variables for the system.

  For example, the configuration variable dateFormat scope=SYSTEM would set the format of the date returned by such meta tags as <@CURRENTDATE>.

• scope=DOMAIN affects the configuration variables in a particular World Wide Web domain.

  For example, there are situations where it is useful to have a different dateFormat in a different domain. A company that does business in French and one that does business in English are being hosted on the same Web server. Because of the different conventions for date formats in the different languages, they would want the date to look quite different in each domain.

  The configuration variable dateFormat with scope=DOMAIN would be set to different values within each domain, and from then on, dates returned by Tango (with a meta tag such as <@CURRENTDATE>) would have different formats in the different domains.

For more information, see "userKey, altUserKey" in the Meta Tags and Configuration Variables manual.

For more information, see "Changing the User Key".

• scope=USER affects application files executed by a particular user. As with normal user variables, these depend on the setting of a reliable user key in order to work as expected, and they expire 30 minutes after that user last accesses Tango.

  For example, you could offer the user the chance to set the dateFormat scope=USER variable, and, for that particular user from that point on, dates would be formatted the way that user wants.

• scope=LOCAL affects a particular Tango application file execution, to override the system, domain, or user settings in a particular case. The change is effective from the action in which you make the assignment until the end of the application file's execution (including all its branches if it branches to another application file). You could change the dateFormat for a particular application file, for example.

For more information, see "Assigning Variables With the Assign Action".

You assign values to configuration variables in the same way as assignments to other kinds of variables: by using Tango Editor's Assign action or by using the <@ASSIGN> meta tag to set configuration variables in HTML processed by Tango.

Caution: Users cannot set system-level configuration variables unless they know the administrative password.

As with Tango's meta tags, letter case is not important when referencing configuration variables. For example, to Tango, cacheSize, cachesize, and CACHESIZE all represent the same configuration variable.

[back to top]

Shortcuts to Configuration Variable Assignments: Snippets

The Workspace contains configuration variable snippets which create assignments for configuration variables. The configuration variable snippets are organized alphabetically by category (Arrays, Data Format, Debugging, and so on) and by Scope (Domain, Local, System, and User). This provides you with a quick way of creating assignments to configuration variables by dragging these snippets into an Assign action window or an HTML editing field.

For more information, see "Using Snippets".

To use the configuration variable assignment snippets

1. Open the Snippets Workspace by showing the Workspace and clicking the Snippets tab.
2. Expand the Configuration Variables folder.

   A tooltip appears if you place your cursor over the snippet, giving the content of the snippet.

3. Choose the configuration variable to which you want an assignment created and drag in into the HTML or Assign action window.

For more information, see "Using Snippets".

Dragging a configuration variable snippet into the HTML window creates an assignment using meta tags, for example, <@ASSIGN NAME="currencyChar" SCOPE="Local" Value="¥">. Tango puts your cursor at the special ¥ symbol, so you can just start typing the value of the configuration variable.

When you drag a snippet into an Assign action window, the configuration variable assignment is automatically created for you.

The Value field becomes active, ready for you to type a value in:

If you choose a snippet without a defined scope (that is, from the category section of the configuration variable snippet), the scope is set to Default.

[back to top]

Using User Keys

To associate a user variable with a particular user, Tango must have a piece of information that it can use to uniquely identify that user.

Tango refers to the unique identifier used for tracking a user's variables as the user key (formerly known as the global key). Tango has several settings allowing you to control what information is used as the user key. Tango default behavior is to use a special meta tag called <@USERREFERENCE> as the value of userKey.

Under this scheme, when users execute their first Tango application file, Tango generates a unique user reference number and uses it as the user key. In the results sent back to the user, Tango includes the user reference number as an HTTP cookie. This cookie is remembered by the browser and is sent automatically with every subsequent request to your server. Tango checks for the existence of the cookie whenever it accesses a user variable. If it was sent, the cookie value is used as the user key.

To help understand how user variable tracking works, imagine that two users, John and Simone, have each executed an application file that assigns a value to a user variable called favorite_color. Tango generates a unique user reference number for each user and sends it in a cookie back to their browsers. The user reference number is a 24-digit hexadecimal string. Inside Tango Server, the user variable information is organized in a manner similar to this:

When, in another application file, the user variable favorite_color is referenced, Tango first checks to see what the value of the user key is for the current user. It then uses that key value in combination with the user variable name to determine the value to return. If the user is John, the user key value, sent to John's browser as a cookie, is 4DC3156644A9B130344B6BCC, and the user variable reference returns "blue"; if the user is Simone, the user key value is 54A497684AD25940014FDD13 and it returns "red".

Note: User variables may always be used to store information within the span of a single Tango application file execution (that is, from action to action). If you are assigning and referring to a user variable within the same execution, your user variable values will be correct. You may, however, want to use a local variable in that case, which is purged at the end of the execution of the application file. It is only across executions that the user key becomes critical.

User Keys Specific to Transactions

In the results sent back to the user, Tango includes the user reference number as an HTTP cookie. This cookie is remembered by the browser and is sent automatically with every subsequent request to your server. Cookies are common to the browser application, not specific to a browser window. If a user opens two windows in a browser application, both windows share the same cookies and, therefore, the same user variables. Usually, this is what you want.

Sometimes, however, you want the user variables to be specific to a particular transaction. In this case, you should store the needed values not as user variables but as hidden form fields or search arguments.

Not all browser applications support cookies. Currently, the two major cookie-capable browsers are Netscape Navigator and Microsoft Internet Explorer. If you need to support user reference-based user variables with browsers that do not support cookies, Tango allows the user reference number to be passed via a special search argument, _userReference. The search argument must be passed with every URL.

For example:

<A HREF="<@CGI>/purchase_item.qry?item_num=
<@COLUMN item_num>&_userReference=
<@USERREFERENCE>">Process Order</A>

There is also a shortcut meta tag for including the entire search argument, <@USERREFERENCEARGUMENT>.

Using this tag, the URL above can be rewritten as:

<A HREF="<@CGI>/purchase_item?item_num=
<@COLUMN item_num>&<@USERREFERENCEARGUMENT>">
Process Order</A>

When using user variables keyed on the user reference number (the default), it is important that all application files have this search argument passed in. If it is missing, and the browser does not support cookies, Tango generates a new user reference and uses it as the user key. The old user reference number cannot be retrieved. This means that previously assigned user variables are "orphaned" and references to them evaluated as empty; new user variables are keyed on the newly generated user reference value.

[back to top]

Changing the User Key

Tango gives you full control over what information is used as the user variable key. It does this via two configuration variables: userKey and altUserKey.

The contents of userKey determines the default key used for tracking user variables. The contents of altUserKey with SCOPE=system or domain determines what key is used when the value of the key specified by userKey with SCOPE=system or domain evaluates to empty. The maximum length of userKey and altUserKey is 32 characters. As stated above, the default value for userKey is <@USERREFERENCE>. The default value for altUserKey is empty.

Note: The userKey and altUserKey specified in the system scope are the default keys. If the domain scope userKey and altUserKey have been set, their values override the system settings and determine the user key for users in that domain, because of the way that variables are evaluated in Tango.

Assigning Values to userKey and altUserKey

When you assign a value to userKey and altUserKey, you must tell Tango Server not to evaluate meta tags in the VALUE attribute, but instead to evaluate the meta tag when user variables need to be keyed. This is done with the <@LITERAL> meta tag.

For more information, see "<@LITERAL>" in the Meta Tags and Configuration Variables manual.

For more information, see "<@USERREFERENCE> in the Meta Tags and Configuration Variables manual.

The syntax of the assignment to userKey of its default value would be as follows:

<@ASSIGN NAME="userKey" VALUE="<@LITERAL VALUE='<@USERREFERENCE>'">

Alternate User Keys

Here are some alternate possibilities for userKey (and altUserKey). You must use the <@LITERAL> tag when assigning to these configuration variables:

For more information, see "<@CGIPARAM>" in the Meta Tags and Configuration Variables manual.

• <@CGIPARAM username>

If you are using HTTP authentication for your site or for a particular set of Tango application files, and have each user logging in with a unique user name, this user name can be used to identify users and their user variables.

• <@CGIPARAM client_ip>

Tango can use the client's IP address as a user key. This user keying mechanism is useful when you know that the users hitting your site are guaranteed to have a one-to-one user/IP address mapping

Unfortunately, in many situations, the IP address is not an accurate method of identifying a particular user. For instance, some corporate networks are set up so that all HTTP requests are routed through a single server. In this case, requests from different users may all have the same IP address. When user variables are keyed on IP address, and an address may represent several users, user variables do not serve their purpose of providing a way to keep user-specific data.

Returning the Value of userKey and altUserKey

When the userKey and altUserKey configuration variables are used in Results HTML, they evaluate to the text of the tags, not the tag values. To see the current value of the user key, use the ENCODING=METAHTML parameter to the <@VAR> tag. For example, if the following text is typed in a Results HTML field:

For more information, see "Encoding Attribute" in the Meta Tags and Configuration Variables manual.

Variables are now being keyed on:
<@VAR NAME="userKey" scope=SYSTEM>.
--> Tango returns <@USERREFERENCE>

The value of the key in the current execution is:
<@VAR NAME="userKey" scope="SYSTEM"
ENCODING="METAHTML">
--> Tango returns 4DC3156644A9B130344B6BCC

Using Application File User Keys

You can override the default user key on an application file basis by setting userKey and altUserKey with scope=LOCAL. These work just like their system-wide counterparts, but apply only until the end of the application file execution. Use local user keys when you want to temporarily use a user key different than the system user key.