Caché ObjectScript Reference
$TEST
|
|
Contains the truth value resulting from the last command using the timeout option.
Synopsis
$TEST contains the truth value (1 or 0) resulting from the last command with a timeout.
$TEST is set by the following commands, regardless of whether they are entered from programmer mode or encountered in routine code:
-
A timed
JOB sets
$TEST to 1 if the attempt to start the new job succeeds before the timeout expires. If the timeout expires,
$TEST is set to 0.
-
A timed
LOCK sets
$TEST to 1 if the lock attempt succeeds before the timeout expires. If the timeout expires,
$TEST is set to 0.
-
A timed
OPEN sets
$TEST to 1 if the open attempt succeeds before the timeout expires. If the timeout expires,
$TEST is set to 0.
-
A timed
READ sets
$TEST to 1 if the read completes before the timeout expires. If the timeout expires,
$TEST is set to 0.
Issuing these commands without a timeout does not set
$TEST.
Note:
$TEST is also set by the legacy version of the
IF command. It is neither set nor checked by the current block-structured
IF command. When the test expression of a legacy
IF command is evaluated,
$TEST is set equal to the resulting truth value. In other words, if the
IF expression tests true,
$TEST is set to 1. If it tests false,
$TEST is set to 0 (zero).
You can use the
SET command to set
$TEST to a boolean value. A value of 1, or any non-zero numeric value, sets
$TEST=1. A value of 0, or a non-numeric string value, sets
$TEST=0.
$TEST can be set by any command or function that can return a logical condition.
A successful
JOB,
LOCK,
OPEN, or
READ command that did not specify a timeout does not change the existing value of
$TEST.
The
DO command maintains the value of
$TEST when calling a procedure, but not when calling a subroutine. For details, refer to the
DO command.
The following code performs a timed read and uses
$TEST to test for completion of the read.
READ !,"Type a letter: ",a#1:10
IF $TEST { DO Success(a) }
ELSE { DO TimedOut }
Success(val)
WRITE !,"Received data: ",val
TimedOut()
WRITE !,"Timed out"
Operations That Do Not Set $TEST
JOB,
LOCK,
OPEN, and
READ commands without a timeout have no effect on
$TEST. Postconditional expressions also have no effect on
$TEST.
The block-oriented
IF command (which defines a block of code by enclosing it in curly braces) does not use
$TEST in any way. The following invocations of the legacy
IF command also do not use
$TEST: legacy
IF without an argument and the
ELSE command have no effect on
$TEST.
Unsuccessful Timed Operations
Caché does not produce an error message after an unsuccessful timed operation. Your application must check
$TEST and then produce an appropriate message.