AX1591

GetSharedVariable function

Returns the value of a named shared variable.

This function is only for use in embedded formsBy using an Embedded Form component, a parent form can display one or more child forms within the same form instance. These forms can share values and leverage other special update and save behaviors., where there is a parent form with one or more child forms displayed using the Embedded Form component. Shared variables provide a way to pass information between the parent form and the child forms.

Syntax

GetSharedVariable("VariableName", "DefaultValue")

Parameter	Description
VariableName	The name of a particular shared variable for which you want to return the value.
DefaultValue	Optional. The value to be used for the shared variable, if no value has yet been set for the variable. When the GetSharedVariable function is calculated, Axiom Software checks the shared variable list that is stored in memory for the shared form instance. If no value currently exists for the specified variable, the variable value is set to the default value defined in the function. This becomes the actual defined value for the variable, to be shared with the other forms in the shared form instance. If a value already exists for the specified variable, then the default value is ignored and the function returns the defined value for the variable.

Parameter

Description

VariableName

The name of a particular shared variable for which you want to return the value.

DefaultValue

Optional. The value to be used for the shared variable, if no value has yet been set for the variable.

When the GetSharedVariable function is calculated, Axiom Software checks the shared variable list that is stored in memory for the shared form instance.

If no value currently exists for the specified variable, the variable value is set to the default value defined in the function. This becomes the actual defined value for the variable, to be shared with the other forms in the shared form instance.
If a value already exists for the specified variable, then the default value is ignored and the function returns the defined value for the variable.

All non-numeric entries must be placed in double quotation marks, unless you are using cell references to reference the text held in another cell.

Shared variable values

Variables and their values can be defined using the following methods:

SetSharedVariable function: Each time this function is evaluated, it sets the current value of a named shared variable to the value defined in the function, overwriting any existing value for the variable. This method takes precedence over any other method of setting the variable value.
Interactive component: An interactive form component, such as a combo box, can be configured to store its value using a named shared variable. Each time the component value is submitted to the source file, it sets the current value of the shared variable to the component value, overwriting any existing value for the variable.
Apply Shared Variable command: A button in an Axiom form can be configured to use this command, which sets the value for one or more named shared variables. When a user clicks the button, the variables are set to the specified values, overwriting any existing value for the variables.
GetSharedVariable function: If no value currently exists for a named shared variable when this function is evaluated, then the value of the variable is set to the value defined in the DefaultValue parameter of the function. This approach only works once, when the variable has no defined value. Once the variable has a value, the DefaultValue parameter is no longer evaluated and cannot affect the value of the variable.

Variable values can be set within the parent form or within any child form. Once the variable value is set, it is then available to all forms within the shared form instance, though forms must be updated in order to reflect a changed variable value. For more information see Sharing variables between parent and child forms.

Remarks

When an Axiom form with an Embedded Form component is first opened, the functions in the parent form are evaluated before the embedded child form. Therefore, the DefaultValue parameter in the child form only applies if the parent form does not already set a value for the shared variable.
It is typically not feasible to use an Axiom function or a data lookup to determine the value to be used in the DefaultValue parameter, because the GetSharedVariable function will calculate and set the variable value before the other queries resolve.
GetSharedVariable is a volatile function.

NOTE: Generally speaking, shared variables are stored in memory as strings. If you want the return value to be presented as a number or date, cell formatting and/or additional conversion functions may be necessary. For more information on special behaviors when returning shared variable values, see Sharing variables between parent and child forms.

Examples

=GetSharedVariable("PlanCode")

This example returns the value of the shared variable PlanCode—for example: 42000. If no value has yet been set for this shared variable, the function will return blank.

=GetSharedVariable("PlanCode","1000")

This example is the same as the first example, except that if no value has yet been set for the shared variable PlanCode, then the value will be set to 1000 and the function will return 1000. If the variable value is subsequently changed by using a SetSharedVariable function or an interactive component, then the default value of 1000 will be ignored and the function will return the currently defined value for the function.