  |
GoFiler Legato Script Reference
Legato v 1.5b Application v 5.24b
|
| Table of Contents | < < Previous | Next >> |
Chapter Four — Flow Control (continued)
TestAndSetSessionValue Function
Overview
The TestAndSetSessionValue function performs an atomic test for a matching string value and, if it matches, sets a new string value. The test and set operation cannot be interrupted by another script.
Syntax/Parameters
Syntax
int = TestAndSetSessionValue ( [string group], [string section], string name,
dword
flags, param match, param data );
Parameters
group
An optional string specifying a qualifying group. The value cannot be larger than 127 bytes.
section
An optional string specifying a qualifying section. The value cannot be larger than 127 bytes.
name
A string specifying the name of the value. The value cannot be larger than 127 bytes.
flags
A dword value specifying bitwise flags indicated the type of match to make.
match
A parameter as a string or integer base value. If a literal integer value is used, it will be treated as an int base type.
data
A parameter as a string or integer base value. If a literal integer value is used, it will be treated as an int base type.
Return Value
Returns an int as FALSE if the string did not match, TRUE is the string matched and the data was set or a formatted error code on failure. Use the GetLastError function to retrieve a formatted error code and GetLastErrorMessage to retrieve additional details.
Remarks
TestAndSetSessionValue allows for a value to be tested, and, depending on the outcome, a new value to be set. This is useful for control arbitration for data and resources. The operation is performed in a atomic operation. No other script can modify the value during the test process. For example, if three scripts ask for the same item at the (essentially) same time, a test and set operation will only allow one to receive an answer. It assumes all scripts vying for control use the same named value under the same operating arrangement.
If the qualified name does not exist, the match is always treated as positive and the data value is set.
The flags parameter can be either:
TASSV_MATCH (0x00000000) — The match string must match.
TASSV_NO_MATCH (0x00000001) — The match string does not match.
The match and data parameters can be a string or integer-based value, but both must be the same type. If an integer type is provided, the match is performed based on the translated string value of the integer.
Use of this function assumes other scripts will not simply use the SetSessionValue function unless within a critical section which will obviously upset the atomic nature of the operation. Consider the following example:
// Setup
int rc, stop;
stop = GetSessionInteger("Stop");
// Work Loop
while ((stop == 0) && (count < 10000)) {
rc = TestAndSetSessionValue("Token", TASSV_MATCH, 0, 1);
if (IsError(rc)) { break; }
if (rc == FALSE) {
Sleep(10);
stop = GetSessionInteger("Stop");
continue;
}
// Enter Critical Section
// do some critical stuff
SetSessionValue("Token", 0);
stop = GetSessionInteger("Stop");
}
In the above example, “Token” is used to indicate that the program can enter a critical section. That is, where two or more scripts are executing the same code at the same time, a conflict could occur. With ‘test and set,’ as soon as a match condition is met, the new value is set. If the return value is FALSE, the condition was not met, or in the above case, the token was busy. Otherwise (assumed TRUE), the token is locked and the script can enter the critical section. Note that the token is reset with the SetSessionValue function, but within the critical section when the script essentially owns the token.
Note that in the above example, the method of waiting is not very efficient and is used to illustrate using test and set. Also note, using a simple, unqualified name, such as ‘Token’ is not advisable since it could be stepped on by another script written by another program.
Ownership and timestamp information is only altered on a positive match condition.
Under the hood, the TestAndSetSessionValue function employs a mutex such that, once a script enters the API function, all other threads have to wait should they use the same function. This is a blanket operation such that any test and set operation performed will be locked out until the previous function completes. By default, the other operations use a thread safe mutex in their underlying operations to avoid issues with session table management.
Related Functions
Platform Support
Go13, Go16, GoFiler Complete, GoFiler Corporate, GoFiler, GoFiler Lite, GoXBRL
Legato IDE, Legato Basic
| Table of Contents | < < Previous | Next >> |
© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.