ANY-maze Help > The ANY-maze reference > The Protocol page > The elements of a protocol > Testing > Procedures > Elements of a procedure > Statements available to procedures > The Wait until statement

The Wait until statement

Introduction

The Wait until statement allows a procedure to respond to a specific event occurring in a test. For example, it could wait for the animal to enter a specific zone, a switch to be activated, or a specific time period to elapse.

Execution of the procedure will pause until this specific event occurs, at which point, the next statement after the Wait until statement will be executed.

For full details of the events available to a procedure, see Events available to procedures.

Example

In the following example, the procedure will wait until the animal enters the 'Island' zone. If it does, the action will be executed (to end the test). If the animal never enters the island zone, then the procedure will never run the action (and the test will end when its test duration has elapsed).

Figure 1. An example of a procedure with a Wait until statement.

More information

A procedure should almost always contain a Wait until statement at some point, particularly if the procedure contains a loop - either within a Repeat statement or within a loop created by a Label statement and a Go to statement. An exception to this is a procedure that simply does some set-up for the test (for example, setting up some I/O devices before the test starts). In this case, it's perfectly valid for it not to contain a Wait until statement.

If your procedure doesn't have any Wait until statements, you'll get a warning in the procedure editor when you check the procedure for errors, or leave the procedure.

A Wait until statement allows the procedure to pause and allow other processing to be done (including allowing other procedures to run). If a procedure contains a loop, but no Wait until statements, then the statements will just run continually without letting other things have a chance to take their turn. (In fact ANY-maze tries to detect this situation, and compensates for it by allowing other procedures to run anyway, but this is an inefficient way to run a procedure and so it's much better to have a Wait until statement in a procedure with a loop).

As an example, consider the following procedure, which uses a loop but does not include a Wait until statement.

Figure 2. A procedure that contains a loop without a Wait until statement.

This procedure will repeat this loop continuously throughout the test, but the absence of a Wait until statement will mean that it won't take a break and give other procedures the chance to run. To fix this, you need to insert a Wait until statement.

Figure 3. The solution to this is to insert a Wait until statement. The procedure will do exactly the same thing, but will run more efficiently and also allow any other procedures to run properly.

If the warning given for the procedure in figure 2 is ignored, and it is used in a test anyway, a run-time warning will also be generated.

A Wait until statement will usually be used to wait for an event. However, it can actually be used to wait for anything that evaluates to a True or False value. This could be the value of a built-in variable, a user-defined variable, or any expression that evaluates to True or False. It can also use Logical operators to look for any or all of multiple True/False values at the same time.

There is one limitation to this, however - if a Wait until statement uses the logical AND operator, you can't use events on both sides of the AND. This is because the events that occur within an ANY-maze test occur one at a time, and so the procedure can't actually receive more than one event simultaneously.

So what would happen if you actually wanted to wait for two things? Let's say that you had four zones for the corners of an apparatus (NW, NE, SW and SE) and wanted to wait for the animal to have entered BOTH of the top corners, in any order (i.e. the animal to enter NW and then NE, or NE and then NW). You might be tempted to write something like the following, but this is NOT a valid procedure:

Figure 4. This procedure is NOT valid; it contains an error and cannot be run.

These two events cannot occur at the same time, so the procedure (if allowed to run) would wait forever. So how would you achieve what you want?

ANY-maze provides you with a number of built-in variables that the procedure can use to ascertain the state of the test. In most cases, you should be able to find one that will help you out, although if you can't, then you can use a user-defined variable to keep track of a specific state and then use that in the Wait until statement.

In this case, what you really want to know is when the animal enters the NW zone (having already entered the NE) or when the animal enters the NE zone (having already entered the NW). ANY-maze provides you with a built-in variable that tells you how many times the animal has visited a specific zone, so you can use this in conjunction with the event to achieve this objective:

Figure 5. Using events AND built-in variables to wait for an animal to have entered both zones.

You could also achieve this using multiple procedures - one procedure that waits for a NW zone entry and sets a 'NW entered' shared variable; another procedure that waits for a NE zone entry and sets a 'NE entered' shared variable; and a third that waits for 'NW entered' AND 'NE entered'.

Waiting for times to elapse

ANY-maze waits for times to elapse using the Time elapsed event. Note that this is not the time elapsed since the beginning of the test, but is the time elapsed from the point that the procedure gets to the Wait until statement that contains the Time elapsed event.

If you want to wait for the time elapsed since the beginning of the test, use the

Create event button to open the Event trigger wizard and select 'A specific duration since the start of the test' from the list of 'Triggers that relate to time'.

Within an ANY-maze procedure, there is a time resolution of approximately 50ms. This should be perfectly fine for most procedures, and you'll only need to change this if you need a finer resolution than this. You might need a finer resolution, for example, if you have a switch that you need to toggle on and off with a very short interval.

If you need to do this, you'll need to use the Set timer resolution action to alter the timer resolution for this procedure. So if you need your switch to be toggled for 10ms, you'd need to change the resolution to 10ms or less, as follows:

Figure 6. This procedure alters the time resolution at the start of the test, and then uses it to ensure a small time interval for the toggling of an output switch.

Changing the timer resolution in this way only affects the procedure that it is used in, and not any other procedures. However it does mean that the procedure needs to process its statements much more often, using more of the computer's processing power, so it's not a good idea to alter the resolution unless you really need to (or are advised to do so by ANY-maze Support).

The timer resolution can be set to anything between 1ms and 60 seconds; however, note that there's a small margin of error, particularly for I/O devices, and a resolution of 1ms actually means a time interval of approximately 1-2ms.

Limitations

For most possible events, a Wait until statement cannot be used before a test starts (i.e. in the shaded section at the top of the procedure editor). This is because most events cannot occur before a test start (the animal cannot enter any zones, for example). The only events that can be used in a Wait until statement before the test starts are I/O events, a Time elapsed event, or a Test is waiting to start event.

I/O events (for example, lever presses or new temperature sensor values) can occur before the test starts, and you may want to wait for these events in order to determine whether the apparatus is in the desired state to start the test - for example, wait until a temperature controller has reached the desired temperature. The Prevent test start and Allow test start actions can be used to prevent or allow the starting of the test if an I/O device is not yet ready - See Preventing a test from starting until an I/O device is ready for more details.

The Time elapsed event can be used before a test starts, if you are waiting for something to change in order to start the test. For example, your test might rely on the value of a specific Field being set before the test can start. You can find out more details about this in the topic Preventing a test from starting until an I/O device is ready. The example here waits for an I/O event, but you can apply the same principle to check that the value of a field has been entered, for example. In this case, waiting for a Time elapsed event within the loop will simply ensure that the procedure runs more efficiently, and the time elapsed should be relatively short (usually less than a second or so).

Note that the Test is waiting to start event will only happen if your protocol is set to start tests automatically. If it's not, then the procedure will just start running the code in the un-shaded area as soon as you click the (Start test) button on the Tests page.