: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

• :PUT_VAR
  Writes values to a VARA object

• VARA object
  Name of the VARA object

• Key
  (Optional) 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.
  • Include the commas even if you omit the Key.
  Format: script literal, script variable or script function

• Value
  Values to write to the value column(s) in the VARA object
  Format: script literal, script variable, or number specified without quotation marks
  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.
  Example: The following script writes "Value1" column 1, and "Value2, Value3, Value4"to column 2.
  :PUT_VAR VARA.TEST, "KEY1", "Value1", "Value2, Value3, Value4"
  If you specify a single value with commas, then you do not need to use quotes.
  (XML VARA objects) Complete, well-formed XML only

Notes:

• If the VARA object does not contain any values, then the system adds the Key and values that you define.
• If the line that you specify already contains values in the VARA object, then the existing values are overwritten.
• Values of 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 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 saves the object, a warning is displayed to inform the user that the VARA object has been modified in the meantime. The user can choose whether to store or discard modifications.

Important!

• Do not use this script statement with dynamic VARA objects. 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 you use a :PUT_VAR statement before a :READ statement, and script generation is canceled, the VARA object still contains the values set by the :PUT_VAR statement. Script generation can be canceled manually by pressing the Cancel button, or automatically due to invalid default values if the Generate Task at Runtime setting is activated on the Attributes page of the object that contains the script.
  More Information:
  • :PUT_VAR
  • Generating at Activation or at Runtime

The Data Type of the VARA object has an impact on the values that you can specify with the :PUT_VAR statement. For more information, see User-Defined VARA Objects.

When you store a value in a VARA object that has a Timestamp data type, use one of the following formats:

• YYYY-MM-DD HH:MM:SS
• YYMMDD HHMMSS
• YYYYMMDD HHMMSS
• YYYYMMDDHH24MISS

For time, date and number data types, format your value according to the format defined for the VARA object (Result Format on the Attributes page).

Important! For number data types, redundant decimal places are truncated when you store a number that has more decimal places than the result format for the VARA object allows.

For more information, see Script Variable Data Types.

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 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>"

See also: