WAIT

Having covered the shutdown script in the last article, we now turn our attention to one of the new CUSPs used therein: WAIT. First, the user documentation, then the source code for the program.

WAIT

WAIT places the process into a wait state for the specified amount of time. It is used to delay execution of a script, or a part thereof.

Format

WAIT time

Parameters

time
This is a delta time, relative to the point at which WAIT is encountered. This can either be a integer number indicating the number of minutes to wait, or a delta time interval with the following format:

hour:minute:second.hundreth

The fields have the following meaning:

Field	Meaning
hour	Number of hours
minute	Number of minutes
second	Number of seconds
hundreth	Number of one-hundreth seconds

All values must be integers and the colons (:) and period (.) are required if the respective fields are specified.

Description

If entered interactively, the process will pause until the time interval is over or a Control-C or Control-Y is pressed on that terminal. Wait does not prompt the user under any circumstances. If no time is specified, it does nothing.

Example

$ RUN PREPARE
$ WAIT 0:15
$ RUN COMPLETE

In this example, the script runs the PREPARE program, then waits for 15 seconds, and then runs the COMPLETE program.

function Run : int64 ;

var C : string ;
    E : int64 ;
    OS : POS_UOS ;

begin
    OS := new( POS_UOS, Init ) ;
    E := _Wait( PChar( OS^.Command_Line ), True ) ;
    if( E <> 0 ) then
    begin
        OS^.OutputLn( 0, LIB_Get_Exception_Text( 0, E ) ) ;
    end ;
    OS.Free ;
    SYS_EXIT( 0 ) ;
end ;

function _Wait( Command : PChar ; Standalone : boolean ) : int64 ;

var I : integer ;
    S : string ;
    T : int64 ;

begin
    // Setup...
    Result := 0 ;
    S := trim( Command ) ;
    if( S = '' ) then
    begin
        exit ;
    end ;

    // Parse command...
    if( trystrtoint( S, I ) ) then
    begin
        // A single number is a minute specification
        S := S + ':00.0' ;
    end ;

    // Process command...
    T := BINTIM( S ) ;
    if( T = 0 ) then
    begin
        Result := Last_Error ;
        exit ;
    end ;
    T := T + LIB_Get_Timestamp ;

    SYS_SETIMR( 0, int64( @T ) ) ;
    SYS_WAITFR( 0 ) ;
end ; // Run

Otherwise, if this is an integer value, we know that a minute has been specified. Otherwise it is a time specification (or some sort of erroneous input). In the case of a minute specification, we convert it to a time specification by adding ":00.0" to the end. Thus,
WAIT 15
would be interpreted as
WAIT 15:00.0
(either way means 15 minutes).

Now, we take our time specification (modified or not) and use the BINTIM service to convert it to a UOS timestamp. If the specification is invalid, BINTIM returns 0 and we get the error and exit. Otherwise, we now have a delta timestamp, which we add to the current time to get an absolute time that indicates when the wait will be over.

Finally, we call the SETIMR services to set a timer for that time, then we call the WAITFR service to wait until the timer goes off. We will cover these system services in the next article, but I'll make a comment about our use of the timer here. Timers can fire off AST calls back to the application, set event flags, and have other options. We don't specify an event flag (first parameter), so it uses event flag 0. Nor do we want any other behavior, such as callbacks. Timers operate asynchronously, so once we create one, we have to tell UOS that we want to wait until the timer fires. The call to WAITFR doesn't come back to us until the timer fires, or the user interrupts things with a control-C or control-Y. This is the simplest possible use of a timer.

Event Flags

Before we continue on to the new system services, we need to discuss event flags. Several articles in the past have mentioned event flags, but we haven't discussed what they are until now.

Event flags are boolean values (set/clear, 0/1, on/off) maintained by UOS. There are five sets of event flags, called event flag clusters, each containing 32 flags (not to be confused with UOS Clusters). The EF clusters can be either Local or Common. Local EF clusters are process-specific. Common EF clusters are shared between processes in a group. The flags are numbered 0 through 159, though some are reserved for UOS use. Local event flags are all zero when a process begins.

Event flags are used for synchronization when performing asynchronous operations. When an asychronous operation begins, the specified flag is cleared to 0. When the operation completes, the specified flag is set to 1. This allows programs to detect when a specific asynchronous operation completes, especially when multiple asynchronous operations are pending.

Event flag 0 is the default flag used if no event flag is specified in a system service call. Therefore, programs should avoid specifically using this flag since it is likely to be used within called library code. Event flag 128 is for use in certain cases, such as calls to SYS$QIOW, since the completion of those calls is synchronized through the status blocks used with the call. This avoids contention on other event flags and operates with less overhead.

Event flags should be allocated and deallocated (freed) to avoid inadvertant side-effects. The flags can be used as semaphores within a program, but the main use of the flags is to put the process or thread into a wait state until an asynchronous operation completes.

The following table describes the event flags.

Cluster number	Flag number	Type	Description
0	0	Local	Default flag.
0	1 to 23	Local	General use.
0	24 to 31	Local	Reserved for UOS use.
1	32 to 63	Local	General use.
2	64 to 95	Common	General use.
3	96 to 127	Common	General use.
4	128	Local	General use without explicit allocation.
4	129 to 159	Local	Reserved for future use.

There are system services that allocate, free, and manipulate event flags. We will discuss these services in the future.

I realize that this is a short article, but - as you have seen - WAIT is one of the simplest of the CUSPs. However, if I were to try to include the documentation and code for either of the new system services, the article would be overlong.

In the next article, we will look at the new system services used above.