RegisterAutomationModalHandler

Release:

…  • 4.6 •  5.0 •  5.1 •  5.2 •  5.3 •  5.4 •  6.0 •  6.1 •  6.2 •  6.3 •  6.4 •  6.5 •   •  6.6 •  7.0 •  7.1 •  7.2

RegisterAutomationModalHandler( handler )

New to Analytica 7.2.

Registers «handler» as the function that answers modal dialogs while Analytica is running in automation mode — that is, while the process was launched with the command line option /Automation. Returns the previously registered handler, or Null if there was none.

In automation mode, every modal dialog that would otherwise block is answered automatically instead of being shown. When a handler is registered, it is called with a description of each dialog and its return value supplies the answer. When no handler is registered, or when the handler returns Null, a built-in default answer is used.

The function may be called at any time, and the registration succeeds whether or not the process is in automation mode. The handler is only consulted in automation mode, so it is harmless to leave the call in a model that people also use interactively.

For a guide to using this — including the full table of built-in defaults, worked examples, and how to package a handler as a driver library for benchmarks or for an AI agent — see Analytica Command Line/Automation.

The «handler» parameter

«handler» is required, and must be a callable that accepts one parameter:

RegisterAutomationModalHandler( Handle(My_dialog_handler) )
RegisterAutomationModalHandler( Function(s) ::= If s->kind = 'SaveChanges' Then 'No' Else Null )

An error is reported if «handler» is not callable.

There is no separate "unregister" form. A handler that returns Null for every dialog behaves identically to having no handler at all — the built-in defaults apply — so registering such a handler stands the previous one down. Because the previous handler is returned, a library can also chain to it: 

Variable Prior_handler := RegisterAutomationModalHandler( Handle(My_handler) )

The «s» parameter of the handler

The handler receives one AutomationDialogStruct value describing the dialog. Read its fields with the -> operator, e.g. s->kind.

Field Type Meaning
kind Text The dialog family. One of 'MsgBox', 'Ask', 'AskText', 'AskNumber', 'AskChoice', 'FileOpen', 'FileSave', 'Warning', 'Redefine', 'SaveChanges', 'Comment', 'LinkedModuleChanged', 'Win32Dialog', 'MacAppDialog', 'Alert', 'CmdLineWarning'
id Text or Null A stable identity for the particular dialog when one is known, such as 'SaveQuitting', 'CheckFailure' or 'ContinueReading', or the internal name of a template dialog
caption Text or Null The dialog's title bar text
body Text or Null The dialog's message text
buttons List of Text, or Null The button names offered, e.g. ['Yes','No','Cancel']
defaultAnswer Text What the built-in default would answer if the handler returns Null
obj Handle or Null The object the dialog concerns, when there is one
att Text or Null The attribute concerned, when relevant
seq Number This dialog's sequence number, matching the seq field in the /AutomationTrace: log

The field set is fixed for Analytica 7.2 and will only grow by addition, so a handler that reads these fields will keep working.

The handler's return value

Return value Effect
Null Use the built-in default answer for this dialog
Text For a button dialog: the name of the button to press — 'Yes', 'No', 'OK', 'Cancel', 'Ignore', 'Retry', 'Abort'. For 'AskText': the text to enter. For 'FileOpen' or 'FileSave': the full path of the file to use, which is treated exactly as if the user had selected it
Number For 'AskNumber': the value entered. For 'AskChoice': the 1-based index of the option chosen

Answering 'Cancel' has exactly the same effect as a user pressing Cancel, including aborting the computation in progress where that is what Cancel normally does.

If the return value is not one of the above — a button name that the dialog does not offer, or the wrong data type for the dialog — the built-in default is used and the event is recorded in the trace log as handler-error-fallback.

Rules the handler runs under

  • Main thread only. A dialog raised on a worker thread (during parallel evaluation, for example) is answered with the built-in default without calling the handler. Such events are recorded as offthread-default.
  • Not re-entrant. A dialog raised while the handler is running takes the built-in default rather than calling the handler again, and is recorded as reentrant-default. Note that WriteTextFile can itself raise a dialog, so pass warn: False when logging from a handler.
  • Errors are contained. If the handler raises an error, the built-in default is used, the event is recorded as handler-error-fallback, and evaluation continues. The handler is not called a second time and no dialog is shown about the failure.
  • Cannot change the model. The handler runs with model dirtying and autosave suppressed, so observing a dialog cannot mark the model as changed. Do not use a handler to modify the model.
  • Error state is preserved. Most dialogs occur while an error or warning is pending. That state is saved before the handler is called and restored afterwards.
  • Timed. The handler's wall-clock time is recorded in the trace log as handlerMs.

Examples

Answer one specific question and default everything else: 

Function Qa_handler( s : atom ) :=
   If s->id = 'CheckFailure' Then 'No'
   Else If s->kind = 'FileOpen' Then 'C:\Scenarios\input1.csv'
   Else Null
RegisterAutomationModalHandler( Handle(Qa_handler) )

Record every dialog without changing any answer: 

Function Watch_handler( s : atom ) :=
   ( WriteTextFile( 'dialogs.log',
                    s->seq & Chr(9) & s->kind & Chr(9) & s->defaultAnswer & Chr(13) & Chr(10),
                    append: True, warn: False );
     Null )

Notes

  • The handler is a property of the process, not of the model. It survives closing one model and opening another, which is what makes it useful in a library loaded with /lib:.
  • If the UDF a registered handle refers to is deleted (for instance because its model was closed), the handler is treated as unregistered and the built-in defaults resume.
  • This function is hidden from the function list (it has a low Intellisense level); type its name to use it.

See Also

Comments
Loading comments...