Skip to main content

HANG (ObjectScript)

Suspends execution for a specified number of seconds.

Synopsis

HANG:pc hangtime,...
H:pc hangtime,...

Arguments

Argument Description
pc Optional — A postconditional expression.
hangtime The amount of time to wait, in seconds. An expression that resolves to a positive numeric value, or a comma-separated list of expressions that resolve to positive numeric values.

Description

HANG suspends the executing routine for the specified time period. If there are multiple arguments, InterSystems IRIS suspends execution for the duration of each argument in the order presented. The HANG time is calculated using the system clock, which determines its precision.

HANG has the same minimum abbreviation (H) as the HALT command. HANG is distinguished by its required hangtime argument.

Arguments

pc

An optional postconditional expression. InterSystems IRIS executes the HANG command if the postconditional expression is true (evaluates to a nonzero numeric value). InterSystems IRIS does not execute the command if the postconditional expression is false (evaluates to zero). For further details, refer to Command Postconditional Expressions.

hangtime

The amount of time to wait, in seconds. This time can be expressed as any numeric expression. You can specify hangtime as an integer to specify whole seconds, or as fractional number to specify fractional seconds. You can use exponentiation (**), arithmetic expressions, and other numeric operators.

You can set hangtime to 0 (zero), in which case no hang is performed. Setting hangtime to a negative number or a nonnumeric value is the same as setting it to 0.

You can specify multiple hangtime arguments as a comma-separated list of numeric expressions. InterSystems IRIS suspends execution for the duration of each argument in the order presented. Negative numbers are treated as zero. Therefore, a hangtime of 16,-15 would hang for 16 seconds.

That each hangtime argument is separately executed can affect operations that use the current time in hang calculations, as shown in the following example:

  SET start=$ZHOROLOG
  SET a=$ZHOROLOG+5
  HANG 4,a-$ZHOROLOG
  SET end=$ZHOROLOG
  WRITE !,"elapsed hang=",end-start

In this example, HANG first suspends execution for 4 seconds. When the next argument is parsed, the current time is now 4 seconds after the variable was set, so the second suspension is only for 1 second. Because HANG executes each argument in turn, the total hang time in this example is (roughly) 5 seconds, rather than the (roughly) 9 seconds one might otherwise expect.

Examples

The following example suspends the process for 10 seconds:

   WRITE !,$ZTIME($PIECE($HOROLOG,",",2))
   HANG 10
   WRITE !,$ZTIME($PIECE($HOROLOG,",",2))

The following example suspends the process for 1/2 second. $ZTIMESTAMP, unlike $HOROLOG, can return fractional seconds if the precision parameter of the $ZTIME function is specified.

   WRITE !,$ZTIME($PIECE($ZTIMESTAMP,",",2),1,2)
   HANG .5
   WRITE !,$ZTIME($PIECE($ZTIMESTAMP,",",2),1,2)

Returns values such as the following:

14:34:19.75
14:34:20.25

HANG Compared with Timed READ

You can use HANG to pause the routine while the user reads an output message. However, you can handle this type of pause more effectively with a timed READ command. A timed READ allows the user to continue when ready, but a HANG does not because it is set to a fixed duration.

HANG and ^JOBEXAM

The HANG command is used to pause execution of the current process.

The ^JOBEXAM utility can be used to suspend and resume execution of other running processes; it cannot be used to suspend execution of the current process. You cannot use ^JOBEXAM to resume process execution that has been paused by a HANG command. If you use ^JOBEXAM to suspend a process that has been paused by a HANG command, the ^JOBEXAM resume activates the process, which must complete whatever portion of the HANG time that remained when it was suspended.

^JOBEXAM displays State information about all running processes. A process that is paused by a HANG command is listed as State HANGW. A process that is suspended by ^JOBEXAM is listed as State SUSPW.

The ^JOBEXAM utility must be invoked by the Terminal from the %SYS namespace. You must have appropriate privileges to invoke this utility. Utility names are case-sensitive. You can execute ^JOBEXAM as follows:

  • DO ^JOBEXAM: displays a listing of all running processes. It provides letter code options to terminate, suspend, or resume a running process.

  • DO View^JOBEXAM displays a listing of all running processes. It does not provide options to terminate, suspend, or resume a process.

If you want to use ^JOBEXAM on a process, it can be helpful to use the HANG command to pause the process to give you time to use ^JOBEXAM on it. For example, you could add the following to your code, at the spot you want to pause the process:

set ^zMyProcessID = $JOB
while ( $DATA(^zMyDebugGlobal) = 1 ) 
{
    hang 1
} 

To use this trick, set the global ^zMyDebugGlobal to 1 before running your process. Then run ^JOBEXAM. The global ^zMyProcessID will be set to the process ID (PID) to make it easier to find your process when running ^JOBEXAM. To resume your process after examining it, kill the global ^zMyDebugGlobal.

See Also

FeedbackOpens in a new tab