Examples:

        ZALLOCATE A
        ZALLOCATE ^A
        ZALLOCATE ^A(1)
        ZALLOCATE (^B("smith"),^C("jones"))
        ZALLOCATE @A
        

The first command ZALLOCATEs A; the second, ^A; the third, ^A(1) and the fourth, both ^B("smith") and ^C("jones") simultaneously. The last command ZALLOCATEs the resources named by the value of the variable A.

Example:

        ZALLOCATE A,^B,@C
        ZALLOCATE (A,B,C)
        

If ZALLOCATE arguments are enclosed in parentheses, the command waits until all names in the argument list become available before reserving any of the names. For example, in the statement ZA (A,B,C), if the resource named C is not available, ZALLOCATE waits until C becomes available before reserving A and B. Using the format illustrated in the first line above, can cause deadlocks because the resource names are reserved as they come available.

When a process attempts to ZALLOCATE a name currently ZALLOCATEd or LOCKed (with the LOCK command) by another process, the ZALLOCATEing process hangs until the other process releases the name. In the event that names remain unavailable for significant periods oftime, timeouts allow the process issuing a ZALLOCATE to regain program control.

Example:

          ZALLOCATE ^D:5
        

This example specifies a timeout of five seconds. If GT.M reserves ^D before the five seconds elapses, ZALLOCATE sets $TEST to TRUE. If GT.M cannot reserve ^D within the five second timeout, ZALLOCATE sets $TEST to FALSE.

When you ZALLOCATE a name, no names previously reserved with ZALLOCATE or the LOCK command are released (similarly, LOCKing a name does not release names that have been ZALLOCATEd). For example, after ZALLOCATEing A and LOCKing B, LOCKing B does not release A, and ZALLOCATEing C does not release A or B.

To release a ZALLOCATEd name, use the ZDEALLOCATE command. The ZDEALLOCATE command can only release previously ZALLOCATEd (not LOCKed) names.

Resource name arguments for LOCKs and ZALLOCATEs intersect. That is, if one process holds a LOCK or ZALLOCATE, another process can neither LOCK nor ZALLOCATE any name falling in the hierarchy of the resource name held by the first process. When a process holds a LOCK or ZALLOCATE, that same process may also LOCK or ZALLOCATE resource names falling in the hierarchy of the currently held resource name. When a single process holds both LOCKs and ZALLOCATEs, a LOCK does not release the ZALLOCATEd resource(s) and a ZDEALLOCATE does not release the LOCKed resource(s).

For a description of the ZDEALLOCATE command, refer to the section describing it later in this chapter.

Example:

        L ^AR(PNT)
        .
        .
        .
        ZALLOCATE ^AR(PNT,SUB)
        .
        .
        .
        L ^TOT(TDT)
        .
        .
        ZDEALLOCATE ^AR(PNT,SUB)
        

This LOCKs ^AR(PNT), then, after performing some unspecified commands, it ZALLOCATEs ^AR(PNT,SUB). Because ZALLOCATE does not imply any change to LOCKs or existing ZALLOCATEd resource names, the LOCK of ^AR(PNT) remains in effect. Assuming the routine does not modify the variable PNT, ^AR(PNT,SUB) is already protected by the LOCK. Next, because an unsigned LOCK releases all resource names currently LOCKed by the process, the routine releases ^AR(PNT) with the LOCK of ^TOT(TDT). This leaves the ZALLOCATE of ^AR(PNT,SUB). The name ^AR and all its subscripts except for those that begin with ^AR(PNT,SUB) are now available for LOCKing by other processes. Finally the routine releases ^AR(PNT,SUB) with a ZDEALLOCATE command. The ZDEALLOCATE does not affect the LOCK on ^TOT(TDT). Note that this example was constructed to illustrate the interaction between LOCK, ZALLOCATE and ZDEALLOCATE, and not to illustrate sound programming practice.

Because the ZALLOCATE command reserves names without releasing previously reserved names, it can lead to deadlocks. For example, a deadlock occurs if two users ZALLOCATE names A and B in the following sequence:

To avoid deadlocks, use a timeout. Because unsigned LOCKs always release previously reserved names, such LOCKs inherently prevent deadlocks.