GPR_$ACQUIRE_DISPLAY              GPR Calls               GPR_$ACQUIRE_DISPLAY


NAME
     gpr_$acquire_display - accesses the display hardware.

FORMAT
     unobscured := gpr_$acquire_display (status)

DESCRIPTION
     This routine establishes exclusive access to the display hardware and the
     display driver.

   Return
     unobscured
          A Boolean value that indicates whether or not the window is obscured
          (false = obscured).  This parameter is always true unless the option
          gpr_$ok_if_obs was specified to gpr_$set_obscured_opt.

   Output Parameters
     status
          Completion status, in status_$t format.

SEE ALSO
     gpr_$release_display, gpr_$set_acq_time_out.

NOTES
     While the display is acquired, the Display Manager  cannot  run.   Hence,
     the  program  cannot  respond to pad calls or to stream calls to input or
     transcript pads.  If you need to call any of  these  routines,  you  must
     release the display (with gpr_$release_display) to do so.

     Since no other display output can occur while the display is acquired, it
     is  not a good idea to acquire the display for long periods of time.  The
     acquire routine automatically times out after a  default  period  of  one
     minute;   programs   can   change   this   time-out   with   the  routine
     gpr_$set_acq_time_out.

     Although this call is needed only in direct mode, it can be  called  from
     any  of the other display modes.  In the other display modes, the routine
     performs no operations.

     If the display is already acquired when this call is  made,  a  count  of
     calls is incremented such that pairs of acquire/release display calls can
     be nested.

     An appliction cannot acquire the display when the window is iconized.