STATIC Variables

STATIC variable objects store up to 5 values for one or more named keys. You can set the values manually, with a script element or with a condition action.

You define and enter the values for static variables in two pages. On the Variables main page you can set up to five values for the variable. On the Attributes page you define the variable itself, that is, you determine its format and settings as well as what will happen if the variable value is not found.

This topic provides information on the following:

Variables Page

Here you can enter as many keys as you need and specify up to 5 values for each, for example:

You set static variable objects' values:

The following script elements are available for STATIC and XML variables:

Manually Entering Static Values

Each table line entry is composed of a key plus up to 5 values. The allowable data depends on the data type and scope settings specified in the Variables Settings section on the Attributes page.

Note that the key must not start with a & character. Otherwise, you can save the Variable object but an error will occur when an attempt is made to access these lines via script.

A key can include a maximum of 200 characters.

The following value ranges are allowed depending on the selected data type selected in the Data Type field in the Data & Formatting section.

Data Type

Content Length

String

Unlimited

If the Limit text length checkbox in the Data & Formatting section is selected , this restriction only affects the first value column.

Number

Between 0 and 2147483647.

Timestamp

Date and time value depending on the output format.

Time Time value depending on the output format.
Date Date value depending on the output format.

The values are sorted according to the settings that have been made in the Attributes page. By default, the Key column is sorted in an ascending order.

Working in the Variables Table

To: Do this:
Add a row to the table

Click in the appropriate section. Click the cells in the table to edit their values.

Edit a cell in table row

Click the cell in the table and edit its value.

Delete one of more rows to the table

Check the checkbox for the row(s) and click .

Delete all rows to the table

Check the checkbox column header and click .

Cut one or more rows and them to the AWI clipboard

Check the checkbox for the row(s) and click .

Copy one or more rows and them to the AWI clipboard

Check the checkbox for the row(s) and click .

Paste row(s) from the AWI clipboard to the bottom of the table

Click .

An editor is available for the value columns of static VARA objects. This provides simple and user-friendly content editing. The editor is helpful particularly for changing long values.

Attributes Sub Page

To Define the Variable Attributes

  1. Specify the Data & Formatting settings:

    Field

    Description

    Data Type

    The data type decides the format of the variable's values in the first value column. The data type "Text" is always used for all other value columns.

    • Text: An alphanumeric string. Blanks at the end are removed, leading blanks are kept. If the Limit Text Length checkbox is not checked, there will be no limit to the length of the character string.

      You can format the string further:

      • Select Limit text length to display the Max. text length input box allowing you to limit the text length.
        Possible values: 1 to 1024
      • Select Force upper case to convert the variable's text to upper case.
    • Number: Singed integer, i.e. a number between 0 and 2147483647.

      You can format the string further:

      • Select from the Output format drop-down list, how the number will be displayed.
      • Select Set Min. value to display the Min. value input box.
        Possible values: max. 16 digits before and 16 digits after the decimal point
      • Select Set max. value to display the Max. value input box.
    • Time: The default time format is hh:mm:ss. You can:
      • Select another format from the drop-down list.
      • Define a minimum and maximum value.
    • Date: The default date format is yyyy-mm-dd. You can:
      • Select another format from the drop-down list.
      • Define a minimum and maximum value. Note that you cannot define a date before 01.01.1980 as the minimum value.
    • Timestamp: The default timestamp format is yyyy-mm-dd hh:mm:ss. You can:
      • Select another format from the drop-down list.
      • Define a minimum and maximum value. Note that you cannot define a date before 01.01.1980 as the minimum value.

    The exact format of the selected data type (with the exception of "String") can be determined in the Output Format field.

    The data type of the values that are available in the first column is checked. The variable's data type must match the data type of the first column returned by the SQL statements when you use the sources "SQL" or "SQL internally". Data can also be processed using specific SQL statements. An error occurs if static variables should be stored or dynamic variables are accessed and the data types do not match.

    Note the following if you change the data type of static Variable objects that already include values:

    • You can easily change "Number", "Timestamp", "Time", and "Date" to "Text". The values are converted without any changes.
    • An output format must be selected if "Text" has been changed to "Number", "Timestamp", "Time", or "Date". When the Variable object is saved, the system verifies that the values match the specified format.
    • You cannot directly modify the data types "Date", "Time", "Number", and "Timestamp". They must be converted to the data type "Text" before you can modify them.

    The data type of variables with the type "Multi", "SQL", or "SQL internally" can be changed at any time.

    The data type of the script variable in question ("float", "signed", "unsigned", or "string") is irrelevant in values that have been retrieved from Variable objects with the data type "Number" when using the script element GET_VAR. The value can always be stored. Algebraic signs and decimal places are removed if they are not supported by the script variable's data type. The values are always passed on to the script as a "string" if a different data type has been specified in the Variable object.

    Output Format

    This setting defines the format that should be used to store values in the Variable object (source: static variables) or to retrieve values from the data source (dynamic variables).

    The contents of this selection menu depend on the data type. Several different formats are available for each data type (except for the String type).

    The output format only refers to the first column. In static variables, this is the column Value 1; in Database and Multi variables, it is the first basic column. Note that Multi variables use the first basic column as their reference column. This means that the source variable's output format can affect the retrieved values.

    The output format of static variables for a particular datatype can be changed at any time. In doing so, the values are converted to the new format. If the values do not match the old format, they cannot be converted to a new format.

    The format that is used to enter value in static variables is irrelevant unless it is an AE-supported format of the data type in question. The values are then converted to the relevant output format.

    The data type "Text" does not show this combo box.

    Data type Available formats Default format

    Timestamp

    • YYYYMMDDHH24MISS
    • YYYY-MM-DD HH:MM:SS

    YYYY-MM-DD HH:MM:SS

    Date

    • DD-MON-YYYY
    • DD-MON-RR
    • MM-DD-YYYY
    • YYYYMMDD
    • MMDDRR
    • DDMMRR
    • MM-DD-RR
    • MM/DD/RR
    • YYMMDD
    • YY.MM.DD
    • YY-MM-DD
    • YYYYMMDD
    • YYYY.MM.DD
    • YYYY-MM-DD
    • DDMMYY
    • DD.MM.YY
    • DD-MM-YY
    • DDMMYYYY
    • DD.MM.YYYY
    • DD-MM-YYYY
    • MMDDYY
    • MMDDYYYY
    • MM/DD/YY
    • MM/DD/YYYY

    YYMMDD

    Time
    • HHMMSS
    • HH:MM:SS
    • HHMM
    • HH:MM
    • MMSS
    • MM:SS

    HHMMSS

    Number
    • 00.00
    • +00.00
    • -0.00
    • 0
    • +0
    • -0
    • 16 digits
    16 digits

    Some date formats include RR as a placeholder for the abbreviated year. Having both YY and RR accommodates different century-counting conventions based on the two digits of the abbreviated year value.
    YY - The current century applies for numbers between 00 and 80. The previous century applies for 81 - 99. 
    RR - The current century applies for numbers between 00 and 49. The previous century applies for 50 - 99.

    For example:
    Date format DDMMYY and the resulting complete dates:
    010305 - corresponds to 01 March 2005
    010365 - corresponds to 01 March 2065
    010380 - corresponds to 01 March 2080
    010385 - corresponds to 01 March 1985

    For example:
    Date format DDMMRR and the resulting complete dates:
    010305 - corresponds to 01 March 2005
    010365 - corresponds to 01 March 1965
    010380 - corresponds to 01 March 1980
    010385 - corresponds to 01 March 1985

    The time value for the data type "Time" or "Timestamp" must be a 4 or 6-digit number. Decimal places are removed. 4-digit numbers are converted to hours and minutes.

    Examples:
    Data type: Time
    Output Format: HH:MM:SS
    Value of the user or the data source: 1234, 1234.5, 123400, 12:34, 12:34:00
    Resulting variable value: 12:34:00

    Data type: Timestamp
    Output Format: YYYY-MM-DD HH:MM:SS
    Value of the user or the data source: 20110325 2201, 20110325 2201.5, 20110325 220100
    Resulting variable value: 2011-03-25 22:01:00

    Set min. value

    Min. value

    Enforces a minimum value.

    The data type "Text" does not show these fields.

    Set max. value

    Max value

    Enforces a maximum value.

    The data type "Text" does not show these fields.

    Limit text length

    Max. Text Length

    Enforces a maximum character length.

    Allowed values: 1 to 1024

    If this option is deactivated, there is no limit.

    The Key column of VARA objects has a maximum limit of 200 characters. This limit always exists and cannot be increased or deactivated.

    The result column of dynamic variables has no limit. The length depends on the value columns.

    In static and dynamic variables, this limit refers to the first value column. The Key or result column is not checked.

    Values that exceed the maximum length are excluded.

    Only the data type "Text" shows these fields.

    Force upper case

    Lower case letters that are used in variable values are automatically converted to upper case. This only affects the first value column.

    Only the data type "Text" shows this field.

    Sort by column

    Specifies the column whose values are used to sort the entries.

    Possible options: Key, 1, 2, 3, 4, or 5

    Sort order

    Type of sorting.

    Possible options: Descending or ascending

    The underlying type of sorting such as binary or alphabetic, depends on what is defined in your database.

  2. Specify the Variable Settings:

    Field

    Description

    Type This read-only field shows STATIC as the variable type. You determine the variable type when you create the object. It cannot be changed once the variable is defined.

    Scope

    This setting can be used to simplify the script that writes values to variables or reads them. Usually, the key must be specified as a parameter in the script element :PUT_VAR or GET_VAR. However, this makes it difficult to ensure that values are stored with unique keys. By specifying a particular scope, you can simplify design of scripts that write to or read from the variable. For all values of scope except Freely selected, the key is optional, and the default key used to access the variable if no key is specified depends on the characteristics of the task that is accessing the variable.

    For: Specifying a key is: The key used to access the variable, when none is specified is:
    No scope Optional *
    Freely selected Required

    N/A

    Since a key is required, Runtime error U00003712 occurs if a key is not specified.

    Host - each host name Optional The name of the agent where the task is running
    Task - each task name Optional The name of the running executable object
    Workflow name - each workflow name Optional The name of the parent workflow of the task
    Workflow session - each workflow session Optional The run ID of the parent workflow in which the task is running
    User - each user name Optional The name of the executing user
    User session - each user session Optional The run ID of the user session

    The entry (row) corresponding to the user session will be deleted when the user session ends.

    If the VARA object has the scope Freely selected, you must specify the key when writing to or reading from the VARA object.

    :SET &VARA_NAME# = "UC0.MAL.TEST#1_1.VARA_STATIC_USERNAME"

    :PUT_VAR &VARA_NAME#, &$USER#, "Mercury", "Venus", "Earth", "Mars", "Jupiter"

    :SET &VALUE# = GET_VAR(&VARA_NAME#, &$USER# ,1)

    :PRINT "Value: &Value#"

    If the VARA object has the scope User - each user name, you can omit the key when accessing the VARA object.

    :SET &VARA_NAME# = "UC0.MAL.TEST#1_1.VARA_STATIC_USERNAME"

    :PUT_VAR &VARA_NAME#, , "Mercury", "Venus", "Earth", "Mars", "Jupiter"

    :SET &VALUE# = GET_VAR(&VARA_NAME#, &$USER# ,1)

    :PRINT "Value: &Value#"

    The two scopes that are more useful are User session - each user session and Workflow session - each workflow session. With these two scopes, the default key that is used if none is specified is user session ID or the workflow run ID, respectively. And importantly, with these two scopes, the rows are deleted when the corresponding run ID is deactivated.

    For example, let’s say you want to store some information in a VARA object as long as a user is logged in, but remove the information when the user logs out. You can set the scope of the VARA object to User session - each user session, and put values into the VARA object without specifying a key as shown below.

    :SET &VARA_NAME# = "UC0.MAL.TEST#1_1.VARA_STATIC_USERSESSION"

    :PUT_VAR &VARA_NAME#, , "Mercury", "Venus", "Earth", "Mars", "Jupiter"

    :SET &VALUE# = GET_VAR(&VARA_NAME#, &$USER# ,1)

    :PRINT "Value: &Value#"

    The key used to write the values will be the session ID of the user who runs the script. In this example, running the script caused the following row to be added to the VARA object:

    Key Value 1 Value 2 Value 3 Value 4 Value 5
    1168010 Mercury Venus Earth Mars Jupiter

    1168010 is the user's session ID. Users' session IDs are visible under Users in the Administration perspective. As soon as the user logs out, this row is removed from the VARA object.

    The scope Workflow session - each workflow session works in a similar way. Any row written to such a VARA object (without a key specified) will be automatically removed as soon as the executing workflow is deactivated.

  3. Specify the Script Access settings:

    You can specify what happens if a key is not found with the If key not found radio buttons.

    To:

    Choose:

    Have an error message displayed if an object attempts to access an item that is not available at runtime via script Return error
    Not use the result of output format of when it is " " Return initial values
  4. In client 0 only: Specify how the VARA object will behave in clients other than 0.

    When you define Variable objects in system Client 0, they can be used in other clients, either because they refer to the values set in the Variable in Client 0 or because you copy the original object from Client 0 to other clients and, if necessary, edit its values in the target clients.

    With the Share object with other clients and options you define the behavior of this Variable object in clients other than 0:

    Option

    Description

    Don't share but allow duplicates

    If you select this option, this VARA object is available in clients other than 0 and you can use it there. You can modify all of its parameters in the non-0 clients, which can then be different per client.

    The name of the variable can be kept in non-0 clients. This means that if there is already a VARA object in the non-0 client with this name, two independent VARA objects with the same name will be available.

    You can modify all the parameters of both variables independently per client.

    Share and allow read-only access

    If you select this option, this VARA object is available in clients other than 0 and you can use it there but you cannot modify any of its parameters.

    Additionally, the name of this VARA object must be unique system-wide.

    Share but keep attribute settings from system client

    If you select this option, this VARA object can be copied to non-0 clients. If you do so, it keeps all the definitions made on the Attributes page but you can edit the Key and Value settings in the non-0 clients. Each client can have its own Key/Value definitions.

    Only available for STATIC variables.

Reading Variable Object Values with the GET_VAR Script Function

The values of static and dynamic Variable objects can be read using the script function GET_VAR.

Retrieving a List of Variable Object Values with the PREP_PROCESS_VAR Script Function

Use the script function PREP_PROCESS_VAR to access all or several particular entries of a variable. This prepares the processing of a data sequence.

Adding, Editing, and Deleting Static Variable Objects with Script Elements

In addition to the manual handling of static Variable objects, you can also use the following script elements:

The editor does not support the editing of VARA objects that contain arbitrary binary values (such as 0x00-0x08, 0x0b, 0x0c, 0x0e-0x19). When you try to save any of these values, the character "?" (0x3f) will always be saved instead.