File Call.lua

Functions

Call:abort (message, ...) Abort call or service.
Call:assureStats (names) Initialize call stats - optional, but recommended - to avoid nagging when debug is enabled.
Call:cancel (message) Cancel call or service.
Call:cleanup (status, message) "Cleanup" function called after main function, even if main aborted due to error.
Call:closeStats () Determine if any stats have not been used (only does something if (adv) debug mode enabled).
Call:getCaption () Get caption, usually for subsequent restoral.
Call:getStat (name) get stat value, 0 if undefined.
Call:incrStat (name, amt) Increment a call stat: may or may not be initialized.
Call:initStats (names) Initialize call stats - optional, but recommended - to avoid nagging when debug is enabled.
Call:isAborted () Determine if call has been aborted.
Call:isCanceled () Determine if a call was canceled.
Call:isQuit (scope) Determine if call has quit due to cancelation or abortion.
Call:new (t) Constructor for new instance objects.
Call:newClass (t) Constructor for class extension.
Call:newStats (names) Constructor for a call-like object that just keeps a set of stats, without being "performed" (no main function...).
Call:perform (context, ...) Call (perform) main function.
Call:setCaption (fmt, ...) Set a caption on a progress indicator.
Call:setPortionComplete (amt, ttl) Convenience function for setting portion complete on encapsulated scope.
Call:setStat (name, val) get stat value, 0 if undefined.
Call:unQuit () Used by background task so it can be canceled, but not stay canceled forever.


Functions

Call:abort (message, ...)
Abort call or service.

Parameters:

  • message:
  • ...:

Usage:

    Note: Do not call base class abort method here. 
Call:assureStats (names)
Initialize call stats - optional, but recommended - to avoid nagging when debug is enabled.

Parameters:

  • names:
Call:cancel (message)
Cancel call or service.

Parameters:

  • message:

Usage:

    cancelation means don't bother user again. 
Call:cleanup (status, message)
"Cleanup" function called after main function, even if main aborted due to error.

I'm not real crazy about the term "cleanup", but the big deal is that its guaranteed to be called regardless of the status of main function execution. "cleanup" activities can include things like clearing recursion guards, logging results, and displaying a successful completion or error message.

Parameters:

  • status:
  • message:

Usage:

  • Normally no need to override - pass finale function to constructor instead.
  • App calls this in protected fashion - if error in cleanup function, default error handler is called. 
Call:closeStats ()
Determine if any stats have not been used (only does something if (adv) debug mode enabled).

Usage:

    unsused means not set, incr'd, nor gotten. (it does NOT mean it couldn't have been set, incr'd, or gotten, given another program path). 
Call:getCaption ()
Get caption, usually for subsequent restoral.
Call:getStat (name)
get stat value, 0 if undefined.

Parameters:

  • name:
Call:incrStat (name, amt)
Increment a call stat: may or may not be initialized.

Parameters:

  • name:
  • amt:
Call:initStats (names)
Initialize call stats - optional, but recommended - to avoid nagging when debug is enabled.

Parameters:

  • names:
Call:isAborted ()
Determine if call has been aborted.
Call:isCanceled ()
Determine if a call was canceled.

Usage:

    cancelation means don't bother user again. 

Return value:

    cancel-message which serves as boolean (if not nil) and optional message (if not the empty string).
Call:isQuit (scope)
Determine if call has quit due to cancelation or abortion.

Parameters:

  • scope:

Usage:

    Does not check for scope canceled, nor scope done. 
Call:new (t)
Constructor for new instance objects.

Table parameter elements:

- name: (string, required) operation name, used for context debugging and as guard key.
- async: (boolean, default false) true => main function runs as asynchronous task. false => synchronous.
- guard: (number, default 0) 0 or nil => no guard, 1 => silent, 2 => vocal. Hint: Use App constants; App.guardSilent and App.guardVocal.
- object: (table, default nil) if main (and finale if applicable) is method, object is required, else leave blank to call main (and finale if applicable) as static function.
- main: (function, required) main function or method.
- finale: (function, default nil) pass finale function if something to do after main completes or aborts.

Parameters:

  • t: Table holding call paramaters.
Call:newClass (t)
Constructor for class extension.

Parameters:

  • t:
Call:newStats (names)
Constructor for a call-like object that just keeps a set of stats, without being "performed" (no main function...).

Parameters:

  • names:
Call:perform (context, ...)
Call (perform) main function.

Parameters:

  • context:
  • ...:

Usage:

  • Normally no need to override - pass main function to constructor instead.
  • Called as static function if object nil, else method.
  • Errors thrown in main are caught by App and passed to finale. 
Call:setCaption (fmt, ...)
Set a caption on a progress indicator.

Parameters:

  • fmt:
  • ...:

Usage:

    normally pre-created, but will create default scope on demand if need be. 
Call:setPortionComplete (amt, ttl)
Convenience function for setting portion complete on encapsulated scope.

Parameters:

  • amt: (number, required) number completed.
  • ttl: (number, default=1) out of total.
Call:setStat (name, val)
get stat value, 0 if undefined.

Parameters:

  • name:
  • val:
Call:unQuit ()
Used by background task so it can be canceled, but not stay canceled forever.

Valid XHTML 1.0!