:PUT_VAR

Use the :PUT_VAR statement to store one or more values in a static VARA object. Define parameters for the statement to assign values to a particular line and specific columns in the VARA object.

Syntax

:PUT[_VAR] VARA object, [Key], Value [, Value [, Value [, Value [, Value]]]]

Parameters

Parameter	Description	Format
VARA object	Defines the name of the VARA object.	n.a.
Key	(Optional) Specifies the line in the VARA object in which to write the value(s). Notes: The Key parameter is optional if the VARA object is configured to have No scope. For more information, see STATIC VARA Objects. You must include the commas even if you omit the Key. You can use the FORCE_VARA_KEY_CI key of the UC_SYSTEM_SETTINGS variable to force context-insensitive read/write actions on STATIC VARA objects while defining the key. When the variable is set to Y, the key is converted to and remains in uppercase. For more information, see FORCE_VARA_KEY_CI.	Script literal, script variable, or script function
Value	Defines the values to write to the value column(s) in the VARA object. Notes: Separate individual values with commas to write them to different columns in the VARA object. Write a value that includes one or more commas in single-quote or double-quote characters. If you specify a single value with commas, then you do not need to use quotes. (XML VARA objects) Use complete, well-formed XML only.	Script literal, script variable, or number specified without quotation marks

Parameter

Description

Format

VARA object

Defines the name of the VARA object.

n.a.

Key

(Optional) Specifies the line in the VARA object in which to write the value(s).

Notes:

The Key parameter is optional if the VARA object is configured to have No scope. For more information, see STATIC VARA Objects.
You must include the commas even if you omit the Key.
You can use the FORCE_VARA_KEY_CI key of the UC_SYSTEM_SETTINGS variable to force context-insensitive read/write actions on STATIC VARA objects while defining the key. When the variable is set to Y, the key is converted to and remains in uppercase. For more information, see FORCE_VARA_KEY_CI.

Script literal, script variable, or script function

Value

Defines the values to write to the value column(s) in the VARA object.

Notes:

Separate individual values with commas to write them to different columns in the VARA object.
Write a value that includes one or more commas in single-quote or double-quote characters. If you specify a single value with commas, then you do not need to use quotes.
(XML VARA objects) Use complete, well-formed XML only.

Script literal, script variable, or number specified without quotation marks

Important Considerations

Keep the following rules and behaviors in mind when working with the :PUT_VAR statement:

Do not use this script statement with dynamic VARA objects, as doing so causes a runtime error.
You cannot enter more values than the VARA object provides. Static VARA objects have a maximum of 5 columns for storing values.
If the VARA object does not contain any values, the system adds the Key and values that you define.
If the specified line already contains values in the VARA object, the existing values are overwritten. Values in non-specified columns are deleted.
If you use the :PUT_VAR statement with an XML VARA object, the XML data type values are automatically beautified. If you write XML in a single script line, the value is rearranged according to the XML standard in the object.
For string data types, leading and trailing blanks remain intact in the content.
If a user has the VARA object open when the script is processed, the :PUT_VAR statement still writes values to the object. When the user attempts to save the object, a warning alerts them that it was modified in the meantime, giving them the choice to store or discard their changes.
If you execute a :PUT_VAR statement before a :READ statement and script generation is subsequently canceled, the VARA object will still contain the values set by the :PUT_VAR statement. Script generation can be canceled manually or automatically due to invalid default values.
The Data Type of the VARA object dictates the formats and values you can specify. For time, date, and number data types, you must format your value according to the Result Format defined on the Attributes page of the VARA object. For more information, see User-Defined VARA Objects.
Important! For number data types, redundant decimal places are automatically truncated when you attempt to store a number with more decimal places than the result format allows.
When storing a value in a VARA object configured with a Timestamp data type, use one of the following exact formats: YYYY-MM-DD HH:MM:SS, YYMMDD HHMMSS, YYYYMMDD HHMMSS, or YYYYMMDDHH24MISS.

Examples

The following example writes values to all 5 columns in a VARA object:

:PUT_VAR VARA.TEST, "KEY1", "Value1", "Value2", "Value3", "Value4", "Value5"

In the following example, the SYS_DATE and SYS_TIME functions retrieve the current date and time. The values are assigned to script variables. The :PUT_VAR statement then writes the values in a VARA object called BOOKING.DATE.

:SET &DATE# = SYS_DATE("YYYY-MM-DD")

:SET &TIME# = SYS_TIME("HH:MM:SS")

:PUT_VAR BOOKING.DATE,, "&DATE# &TIME#"

In the following example, assume that the VARA object called ATTRIBUTES is configured with a Freely selected scope. In this case, you must define the Key (the "CurrentPriority" below) in the parameters:

:SET &PRIO# = GET_ATT("UC4_PRIORITY")

:PUT_VAR ATTRIBUTES, "CurrentPriority", &PRIO#

The following example retrieves several values (the RunID, name, and object type of a task and its parent). The single :PUT_VAR statement writes the retrieved values to separate columns in a VARA object called OBJECT_STAT.

:SET &PNAME# = SYS_ACT_PARENT_NAME()

:SET &PNR# = SYS_ACT_PARENT_NR()

:SET &PTYPE# = SYS_ACT_PARENT_TYPE()

:SET &NAME# = SYS_ACT_ME_NAME()

:SET &NR# = SYS_ACT_ME_NR()

:SET &TYPE# = SYS_ACT_ME_TYPE()

:PUT_VAR OBJECT_STAT, "&NR#", "object name: &NAME#", "object type: &TYPE#", "parent name: &PNAME#", "parent RunID: &PNR#", "parent object type: &PTYPE#"

The following example writes a single value to an XML VARA object, as that object type only contains one value field:

:PUT_VAR VARA.XML, "KEY1", "<Value1>this is a test</value1>"