Introduction
Transactions provide a powerful way to read one row or a specified part of the row and store the contents into a structure. For every item read from the table, a new member will be created, given the name of the corresponding column header name and the contents placed into the member variable variable. The following rules apply for these transactions:
- Only simple and horizontal table accesses are allowed. Vertical table accesses and matrix table accesses will be rejected and cause exceptions.
- Use '..' or keep blank to specify all column entries in the specified row, e.g. [t:..,1] or [t:,1].
- Partial table specifications are allowed, provided the context information for the table and row number is available (e.g. inside the function parameters of the table process() call)
- Transactions from tables to variables generate only one level of structure members and no further nesting. Arrays are not created.
- For automatic type conversions from tables to variables the same rules as if table contents are read out. See table configure() to modify the rules.
- The table name is assigned to the base variable unless the ^ suffix is used behind the transction operator to preserve the base variable value if existing.
- Table accesses resulting in no values read (empty sets) will at least intialize the destination variable with zero members variable form, but contains no members.
- Make sure every table header in the table to include are unique. Otherwise, the same member variable will be overwritten since the same name is used repeatedly. Alternatively, you can use column numbers.
- Blank table header names translate into blank member names which are valid. Note that members with blank member names are also treated as default members.
The following table applies to transactions from a table row (example: table name 't', row 1, all columns) to a variable.
| Transaction | Symbol | Explanation | Description |
|---|---|---|---|
| Copy | <== | a[] <== [t:..,1]; | Step 1: If a[] does not yet exist, then it will be created. Otherwise, the variable will be initialized, including deleting all members. Step 2: The table name will be copied into the base variable a[]. Step 3: For every cell retrieved from the table, a dedicated member will be created. The header name (row 0) will be used for the member name and the contents will be written into the member variables. |
| Copy Members | <==^ | a[] <==^ [t:..,1]; | Step 1: If a[] does not yet exist, then it will be created. Otherwise all members will be deleted. The base variable will be preserved. Step 2: Will be skipped. Step 3: Like above. |
| Move | <<= | a[] <<= [t:..,1]; | Steps 1-3: Like the copy-transaction Step 4: The specified row in the table will be deleted. The rows below will shift upwards. |
| Move Members | <<=^ | a[] <<=^ [t:..,1]; | Steps 1-3: Like the copy-members-transaction Step 4: The specified row in the table will be deleted. The rows below will shift upwards. |
| Swap | <=> | a[] <=> [t:..,1]; | The contents in the member variable and the table row will be exchanged. Void value will be assigned to the base variable. |
| Swap Members | <=>^ | a[] <=>^ [t:..,1]; | The contents in the member variable and the table row will be exchanged. The base variable will be preserved. |
In the swap transaction, all members in the original variable will be written back to the table. For further details, see transactions from variables to tables how members are transferred to the table row.
Copy Transaction Example
table initialize( animals,
{ { Name, Leg count, Special ability },
{ Owl, 2, Night vision },
{ Dog, 4, Sensitive nose },
{ Ape, 2 or 4, Relatively smart } } );
animal1[] = "My animal";
animal2[] = "My animal";
animal1[] <== [ animals: Name, Dog, .. ]; // Pick up entire row
animal2[] <==^ [ animals: Name, Ape, {Name, Leg count} ]; // Pick up 2 fields only
see( animal1[] );
see( animal2[] );
animal1[] animals (quoted string,full access)
Leg count 4 "4" (numeral,full access)
Name Dog (quoted string,full access)
Special ability Sensitive nose (quoted string,full access)
animal2[] My animal (quoted string,full access)
Leg count 2 or 4 (quoted string,full access)
Name Ape (quoted string,full access)
Move Transaction Example
table initialize( animals,
{ { Name, Leg count, Special ability },
{ Owl, 2, Night vision },
{ Dog, 4, Sensitive nose },
{ Ape, 2 or 4, Relatively smart } } );
animal1[] = "My animal";
animal2[] = "My animal";
animal1[] <<= [ animals: Name, Dog, .. ]; // Pick up entire row
animal2[] <<=^ [ animals: Name, Ape, {Name, Leg count} ]; // Pick up 2 fields only
see( animal1[] );
see( animal2[] );
table list( animals ); // The owl is left overanimal1[] animals (quoted string,full access)
Leg count 4 "4" (numeral,full access)
Name Dog (quoted string,full access)
Special ability Sensitive nose (quoted string,full access)
animal2[] My animal (quoted string,full access)
Leg count 2 or 4 (quoted string,full access)
Name Ape (quoted string,full access)
0 : Name | Leg count | Special ability
1 : Owl | 2 | Night vision
Swap Transaction Example
table initialize( animals,
{ { Name, Leg count, Special ability },
{ Owl, 2, Night vision },
{ Dog, 4, Sensitive nose },
{ Ape, 2 or 4, Relatively smart } } );
structure( animal1[], { Name, Leg count, Weapon }, { Snake, 0, poison } );
structure( animal2[], { Name, Leg count, Weapon, Special ability }, { Wolf, 4, teeth, teamwork } );
animal1[] = "Was a snake";
animal2[] = "Was a wolf";
animal1[] <=> [ animals: Name, Dog, .. ]; // Pick up entire row
animal2[] <=>^ [ animals: Name, Owl, ];
see( animal1[] );
see( animal2[] );
table list( animals ); // Snake, Wolf, Ape. Additional column included (weapon)animal1[] animals (quoted string,full access)
Leg count 4 "4" (numeral,full access)
Name Dog (quoted string,full access)
Special ability Sensitive nose (quoted string,full access)
animal2[] Was a wolf (quoted string,full access)
Leg count 2 "2" (numeral,full access)
Name Owl (quoted string,full access)
Special ability Night vision (quoted string,full access)
0 : Name | Leg count | Special ability | Weapon
1 : Wolf | 4 | teamwork | teeth
2 : Snake | 0 | | poison
3 : Ape | 2 or 4 | Relatively smart |