setlocalsfromdictionary statement

setlocalsfromdictionary

VALUES

The setlocalsfromdictionary statement converts a dictionary into a collection of local variables. The names and values of the local variables will be derived from the dictionary contents.

Parameters

This statement has one parameter:

values – dictionary containing values to be converted into local variables.

Description

This statement converts a dictionary into a collection of local variables. The names and values of the local variables will be derived from the dictionary contents. This example sets up four local variables, x, n, z and color.

setlocalsfromdictionary initializedictionary(
    "x","y",
    "n",42,
    "z","zoz",
    "color","blue"
    )

The example above is identical to this code:

let x = "y"
let n = 42
let z = "zoz"
let color = "blue"

So why not just use let statements? If the variable names are fixed in advance, you should. The advantage of the setlocalsfromdictionary statement is that both the variable names and values can be changed on-the-fly as the code runs. You can use all of Panorama’s options for setting up and modifying dictionaries, then convert the dictionary into variables.

One very useful application of this statement is to transfer local variables from one procedure to another. Normally a procedure cannot access another procedures local variables. You can pass them one at a time, but with setlocalsfromdictionary and the dictionaryfromvariables function you can transfer a batch of local variables at once. Here is an example that passes all the local variables in the current procedure as a single dictionary value to a subroutine it is calling.

call mySubroutine,dictionaryfromvariables(info("localvariables"))

The first line of the mySubroutine procedure can use the setlocalsfromdictionary statement to turn the values back into variables.

setlocalsfromdictionary parameter(1)
// mySubroutine now has all the same variables that the calling procedure had

Important Note: Keep in mind that the mySubroutine procedure now has a copy of the variables in the calling procedure, not the original variables. If you have programmed using other languages, these variables have been passed by value, not by reference. So if you modify any of these variables, the modified value will not be passed back to the original procedure when the subroutine is finished. The original procedure will still have its original, unmodified variables. Of course you could pass the new values back the same way.

See Also

appenddictionaryvalue -- appends a value to an item in a dictionary (see Data Dictionaries).
assign -- assigns a value to a field or variable.
assignfield -- performs an assignment, much like an equals sign or the assign statement. However, the *assignfield* statement only performs the assignment to a database field, not to any variable.
assignfieldwithsideeffects -- performs an assignment, much like an equals sign or the assign statement. However, the *assignfieldwithsideeffects* statement only performs the assignment to a database field, not to any variable. After performing the assignment, it will run any side effects associated with the field, including formulas and code associated with the field.
assignfileglobal -- performs an assignment, much like an equals sign or the assign statement. However, the *assignfileglobal* statement only performs the assignment to a fileglobal variable.
assignglobal -- performs an assignment, much like an equals sign or the assign statement. However, the *assignglobal* statement only performs the assignment to a global variable.
assignlocal -- performs an assignment, much like an equals sign or the assign statement. However, the *assignlocal* statement only performs the assignment to a local variable.
assignwindowglobal -- performs an assignment, much like an equals sign or the assign statement. However, the *assignwindowglobal* statement only performs the assignment to a windowglobal variable.
changedictionaryname -- changes the name (key) of an item in a dictionary (see Data Dictionaries).
changedictionaryvalues( -- changes one or more values in a dictionary (see Data Dictionaries).
classicdictionaryvalue( -- returns the value of an item in the dictionary, given its key (see Data Dictionaries). Unlike getdictionaryvalue(, this function does not treat keys as case sensitive.
clearglobaldictionaryvalues -- clears (removes) all the keys and values from the specified global dictionary.
copypartialdictionary -- builds a new dictionary and initializes it with values from an existing dictionary (see Data Dictionaries).
copypartialdictionary( -- partially copies a dictionary (see Data Dictionaries).
Data Dictionaries -- Overview of Panorama's key/value data dictionaries.
define -- performs an assignment, much like an equals sign or the assign statement. However, the *define* statement only performs the assignment if the variable is currently undefined. If the variable already has a value, the *define* statement leaves it alone. The *define* statement is especially useful for initializing permanent variables.
deletedictionaryvalue -- deletes a key/value pair from a dictionary (see Data Dictionaries).
deletedictionaryvalue( -- deletes one or more key/value pairs from a dictionary (see Data Dictionaries).
deleteglobaldictionaryvalues -- deletes one or more global dictionary values.
dictionaryassignmentscode( -- returns code that can be used to take the values in a dictionary (see Data Dictionaries) and assign them to fields or variables based on the dictionary keys.
dictionarydifference -- builds an array that lists keys of dictionary values that are different between two dictionaries (see Data Dictionaries).
dictionaryfromarray( -- builds a new dictionary and initializes it from a two dimensional text array (see Data Dictionaries and Text Arrays).
dictionaryfromvariables( -- builds a new dictionary and initializes it from a list of variables (carriage return delimited).
dictionaryvalueexists -- returns true or false depending on whether or not a key/value pair exists in a dictionary (see Data Dictionaries).
dictionaryvalueexists( -- returns true or false depending on whether or not a key/value pair exists in a dictionary (see Data Dictionaries).
dumpdictionary -- returns a carriage return separated array of dictionary keys and values (see Data Dictionaries).
dumpdictionary( -- returns a carriage return separated array of dictionary keys and values (see Data Dictionaries).
dumpdictionaryquoted -- returns a carriage return separated array of dictionary keys and values (see Data Dictionaries).
dumpdictionaryquoted( -- returns a carriage return separated array of dictionary keys and values (see Data Dictionaries). The text values are quoted.
dumpdictionarysource( -- returns a carriage return separated array of dictionary keys and values (see Data Dictionaries). The keys and values are quoted so that they could be used to re-assemble the dictionary with the initializedictionary( function.
getdictionarykey -- returns the key of an item in the dictionary, given its value. This is essentially the opposite of the getdictionaryvalue( function (see Data Dictionaries).
getdictionarykey( -- returns the key of an item in the dictionary, given its value). This is essentially the opposite of the getdictionaryvalue( function (see Data Dictionaries).
getdictionaryvalue -- returns the value of an item in the dictionary, given its key (see Data Dictionaries).
getdictionaryvalue( -- returns the value of an item in the dictionary, given its key (see Data Dictionaries).
getglobaldictionary( -- converts a global dictionary into a regular dictionary.
getstructurevalue( -- extracts a value from a structure of nested Data Dictionaries and/or Data Arrays.
Global Dictionaries -- alertnate high performance method to store multiple data items, much faster than regular data dictionaries.
globaldictionarybuild -- builds a global dictionary by scanning a database.
globaldictionarykeys( -- returns a cr()-separated array containing the keys in a global dictionary, or the names of all global dictionaries.
globaldictionaryvalue( -- returns the value of an item in a global dictionary, given its key (see Global Dictionaries).
info("timerinfo") -- returns a dictionary that contains all of the properties of the currently running timer.
initializedictionary -- builds a new dictionary and initializes it with one or more key/value entries (see Data Dictionaries).
initializedictionary( -- builds a new dictionary and initializes it with zero or more key/value entries (see Data Dictionaries).
initializedictionaryvalue( -- builds a new dictionary and initializes it with one or more entries (see Data Dictionaries). This function is deprecated, we recommend using the initializedictionary( function instead.
let -- creates a local variable and assigns a value to it.
letfileglobal -- creates a fileglobal variable and assigns a value to it.
letglobal -- creates a global variable and assigns a value to it.
letpermanent -- creates a permanent variable and assigns a value to it.
letservervariable -- creates a server variable and assigns a value to it.
letwindowglobal -- creates a windowglobal variable and assigns a value to it.
listdictionarykeys( -- returns a list of the keys in a dictionary collection.
listdictionarynames -- returns a list of the names (keys) in a dictionary (see Data Dictionaries).
mergedictionaries -- merges the contents of two or more dictionaries (see Data Dictionaries).
mergedictionaries( -- merges the contents of two or more dictionaries (see Data Dictionaries).
renamedictionarykey( -- changes the key (name) of one or more values in a dictionary (see Data Dictionaries).
set -- performs an assignment, much like an equals sign or the assign statement. However, the destination of the assignment can be calculated on the fly.
setdictionaryvalue -- changes a value in a dictionary (see Data Dictionaries).
setfield -- performs an assignment, much like an equals sign or the assign statement. However, the destination field of the assignment can be calculated on the fly.
setglobal -- sets a value into a global variable. The name of the global variable is calculated on the fly.
setglobaldictionaryvalues -- sets one or more key/value pairs in a global dictionary.
setlocal -- sets a value into a local variable. The name of the local variable is calculated on the fly.
soundinfo( -- returns a dictionary that contains all of the properties of a sound.
timerinfo( -- returns a dictionary that contains all of the properties of a timer.

History

Version	Status	Notes
10.2	New	New in this version.