$TEST (ObjectScript)
Synopsis
$TEST
$T
Description
$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 at the Terminal prompt 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.
Setting $TEST
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.
Maintaining $TEST
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 ZBREAK command maintains the value of $TEST when calling execute_code. For details, refer to the ZBREAK command.
Example
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 does not use $TEST in any way.
Unsuccessful Timed Operations
InterSystems IRIS does not produce an error message after an unsuccessful timed operation. Your application must check $TEST and then produce an appropriate message.