|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > Arrays and Data-Structures > ASA. - Associative Array > Assoc. Array Operation > ASA. - Associative Array Operations |
SPR Script Language
ASA.GetKey
Retrieves the key from a specific node in an associative array.
Intention
The ASA.GetKey command lets you peek at the key part of a key-value pair in an associative array in SPR. You give it a node handle (like $$NODE from ASA.First or ASA.Next), and it puts the key—like "Name" or "Temp"—into $$KEY. This is your way to see the “name” part of a pair when you’re stepping through nodes with ASA.First, ASA.Next, or ASA.Prev. Pair it with ASA.GetVal to get the full picture.
Think of a phonebook array—you’re at a node with "Alice" → "123-4567", and ASA.GetKey pulls out "Alice". Or in a robot script with "Speed" → "3.14", it grabs "Speed". It’s a fast, simple way to check the key as you loop through, perfect for tasks like listing all keys or finding a specific one in your data.
Illustration
🔑 Key Peek: From a node with $$NODE (like "Name" → "Alice"), ASA.GetKey gives you "Name".
📋 Result: $$KEY holds the key so you can see or use it!
Syntax
ASA.GetKey|$$TRE|$$NOD[|$$KEY]
Parameter Explanation
P1 - $$NODE - (Variable, 5 characters max)
This is the node handle you’re looking at. It’s a 5-character variable (like $$NODE) from ASA.First, ASA.Next, ASA.Prev, or ASA.Last. The command uses this to grab the key.
P2 - $$KEY - (Optional, Variable, 5 characters max)
This is where the key goes. It’s an optional 5-character variable (like $$KEY). SPR puts the key string here—like "Name" or "Speed"—if the node is valid, or an empty string if it’s not. Skip this if you don’t need the key saved.
Examples
'***********************************
' ASA.GetKey - Sample 1: Get Key from First Node in String Array
'***********************************
ASA.New|$$TRE|s
ASA.Set|$$TRE|Alice|123-4567
ASA.Set|$$TRE|Bob|987-6543
ASA.First|$$TRE|$$NOD
ASA.GetKey|$$TRE|$$NOD|$$KEY
MBX.First key is $$KEY (should be Alice)
MBX.Ready
'
'***********************************
' ASA.GetKey - Sample 2: Get Key from Last Node in Quad Array
'***********************************
ASA.New|$$TRE|i
ASA.Set|$$TRE|Red|50
ASA.Set|$$TRE|Blue|75
ASA.Last|$$TRE|$$NOD
ASA.GetKey|$$TRE|$$NOD|$$KEY
PRT.Last key is $$KEY (might be Blue)
MBX.Ready
'
'***********************************
' ASA.GetKey - Sample 3: Get Key After Stepping in Extended FP Array
'***********************************
ASA.New|$$TRE|f
ASA.Set|$$TRE|Temp|23.5
ASA.Set|$$TRE|Speed|3.14
ASA.First|$$TRE|$$NOD
ASA.Next|$$TRE|$$NOD|$$NXT
ASA.GetKey|$$TRE|$$NXT|$$KEY
PRT.Second key is $$KEY (might be Speed)
MBX.Ready
'
Remarks
- $$NODE must be a valid node handle from ASA.First, ASA.Next, ASA.Prev, or ASA.Last—check validity if unsure.
- If $$NODE is 0 or invalid, $$KEY might get an empty string.
- It’s fast and doesn’t change the array—just reads the key.
- Works with any datatype array (String, Quad, Extended) since keys are always strings.
Limitations
- $$NODE must be 5 characters—wrong lengths might cause errors.
- If $$NODE isn’t valid, $$KEY might get unpredictable results—no error warning.
- Only gets the key—use ASA.GetVal for the value.
See also:
• ASA.Next
• ASA.Prev