Skip to main content

%SYSTEM.BGUtil

This class provides helper functions for monitoring and control of a background task using a shared memory structure. %SYS.BackgroundTask provides an extended surrounding framework and user interface, but this class can, in principle, be used independently.

Method Inventory

Methods

classmethod CheckRequest() as %Integer
Called by background code to periodically check pause and cancel requests.

If the calling process is not associated with a shared memory structure of this class, then this method does nothing and returns 0. Otherwise, the description that follows applies.

Returns the value of the request code in memory, and it is the callers responsibility to respond appropriately (or ignore it). See Pause() for responding to pause requests. Returns 0 if no request code has been set. In general, callers should simply ignore any unexpected values.

Note that the same check is also done by PostProgress().

classmethod GetInfo(memidx As %Integer, version As %Integer, debug As %Boolean = 0) as %List
Get the progress and other details from shared memory given by 'idx' and 'version'. If the arguments are omitted and the calling process is the one that called ProcessStart(), it returns information about the shared memory associated with this process.

Returns null string if the memory structure isn't valid (e.g. the task has since finished and released the memory). Otherwise returns a $list with the following elements.

  • jobid (internal jobid, not pid) of job with reservation
  • version number, which shall match the value of version passed in the 'version' parameter. This is included only for completeness of information. The caller does not need to check this value; the null string would have been returned instead if they didn't match.
  • New? True if the memory has been allocated but ProcessStart() has never been called.
  • Administrator request code
  • Paused? True if the task is paused due to a posted pause request.
  • Posted 1st argument from PostProgress()
  • Posted 2nd argument from PostProgress()
  • Posted 2nd argument from PostProgress()
  • classmethod IncrProgress(count As %Integer = 1) as %Integer
    Same as PostProgress() except increments the current progress count by the amount specified in the 'count' parameter.

    Return value is identical to PostProgress()

    classmethod Pause() as %Integer
    Called by background code to respond to a pause request.

    If the calling process is not associated with a shared memory structure of this class, then this method does nothing and returns 0. Otherwise, the description that follows applies.

    This function waits until the request code in memory no longer indicates that a pause is requested. While waiting it sets a flag to indicate that the processing is paused. Returns the new value of the request code in memory.

    classmethod PostProgress(current As %Integer = 0, total As %Integer = 0, detail As %Integer = 0) as %Integer
    Called by background code to post progress updates in shared memory. Input paramters are stored in the structure as unsigned 64-bit integers. Zero values are ignored and do not alter the values in memory.

    If the calling process is not associated with a shared memory structure of this class, then this method does nothing and returns 0. Otherwise, the description that follows applies.

    Returns the value of the request code in memory, and it is the callers responsibility to respond appropriately (or ignore it). See Pause() for responding to pause requests. Returns 0 if no request code has been set. In general, callers should simply ignore any unexpected values.

    FeedbackOpens in a new tab