|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > Arrays and Data-Structures > ASA. - Associative Array > Assoc. Array to/from Variable > ASA. - Associative Array Operations |
SPR Script Language
ASA.Store
Stores the contents of an associative array into a variable.
Intention
The ASA.Store command moves data from an associative array (AV-Tree) identified by a handle into a variable. It's designed to create a serialized backup of your array data that can be later restored using ASA.Restore. This is useful for temporarily saving array state, making copies, or transferring array contents between scripts.
The command takes all key-value pairs from the array and converts them into a structured format that can be saved in a string variable. Unlike ASA.FileStore which saves to disk, ASA.Store keeps the data in memory for immediate access.
Illustration
🗄️ Backup: For an array with handle $$TRE holding several key-value pairs, ASA.Store preserves the entire structure in a variable.
📋 Memory Snapshot: The array data is now safely stored in your variable, ready to be restored later with ASA.Restore.
Syntax
ASA.Store|$$TRE|$$VAR
ASA.Store|$$TRE
Parameter Explanation
P1 - $$TRE - (Variable, 5 characters max)
This is the handle of the array you're storing. It's a 5-character variable (like $$TRE or $$ARR) created by ASA.New. The command uses this to access the array.
P2 - $$VAR - (Variable, Optional)
This is the variable where the array data will be stored. If omitted, the result is placed on the top of the stack, where it can be used by subsequent commands or stored manually.
Examples
'***********************************
' ASA.Store - Sample 1: Storing an array to a variable
'***********************************
ASA.New|$$TRE|s
ASA.Set|$$TRE|KeyA|ValA
ASA.Set|$$TRE|KeyB|ValB
ASA.Store|$$TRE|$$STR
PRT.Array stored in memory
ASA.Clear|$$TRE
PRT.Array cleared
ASA.Restore|$$TRE|$$STR
PRT.Array restored from memory
'
'***********************************
' ASA.Store - Sample 2: Using the stack
'***********************************
ASA.New|$$TRE|s
ASA.Set|$$TRE|KeyC|ValC
ASA.Store|$$TRE
POP.$$BAK
PRT.Array stored to stack and retrieved to $$BAK
'
'***********************************
' ASA.Store - Sample 3: Making an array backup
'***********************************
ASA.New|$$TRE|i
ASA.Set|$$TRE|Count|50
ASA.Store|$$TRE|$$BAK
ASA.Set|$$TRE|Count|100
ASA.Get|$$TRE|Count|$$NOW
PRT.Current value: $$NOW
ASA.Clear|$$TRE
ASA.Restore|$$TRE|$$BAK
ASA.Get|$$TRE|Count|$$OLD
PRT.Restored value: $$OLD
'
Remarks
- $$TRE must be a valid array handle created with ASA.New.
- Stores all key-value pairs along with datatype information for proper restoration.
- The stored data format is internal and should only be used with ASA.Restore.
- When P2 is omitted, the result is placed on top of the stack for subsequent use.
Limitations
- $$TRE must be 5 characters—wrong lengths might cause errors.
- Very large arrays may create lengthy string data that could exceed variable size limitations.
- The stored format may change between software versions—always use the same version for storing and restoring.
See also:
• ASA.New