Functions
CommonMCodeModule	GetInstance (func_name)
	Get a tagged Mach4 instance handle for the current macro instance.
CommonMCodeModule	InitializeScrAPI ()
	Initialize the screen IPC API for M-code to screen communication.
CommonMCodeModule	InvokeMacro (macro_name,...)
	Entry point for typical macros with no pre/post/finally behavior.
CommonMCodeModule	InvokeMacroEx (macro_name, opt_behavior,...)
	Invoke an M code (macro) in the standard way, including error checking, alarms, etc.

Function Documentation

◆ GetInstance()

CommonMCodeModule GetInstance ( func_name )

Get a tagged Mach4 instance handle for the current macro instance.

Returns a tagged instance handle for the current macro instance (MINSTANCE). If func_name is nil, returns the raw MINSTANCE value directly. Otherwise, looks up a cached tagged handle in the instance handle cache (CommonMCodeModule.__ihc). If no cached handle exists for the given function name, creates a new tagged instance handle via mc.mcGetInstance() with a descriptive name and stores it in the cache to avoid creating redundant tagged handles.

Parameters

func_name (string|nil) The function name to embed in the tagged instance handle for diagnostic log identification. If nil, returns the raw instance number

Returns: (number) A tagged Mach4 instance handle for the current macro instance, or the raw MINSTANCE value if func_name is nil

Note: Documentation generated by AI on 2026-03-04

References func_name().

◆ InitializeScrAPI()

CommonMCodeModule InitializeScrAPI ( )

Initialize the screen IPC API for M-code to screen communication.

Loads the 'screenipc' Lua module and initializes the IPC connection to the screen process via a named pipe at 'pipe://localhost:48500'. If the scr global is already initialized, this function is a no-op. Displays a wxMessageBox error dialog if the IPC initialization fails.

Note: This function is idempotent - it only initializes once if scr is already set; Documentation generated by AI on 2026-03-04

◆ InvokeMacro()

CommonMCodeModule InvokeMacro	(	macro_name	,
			... )

Entry point for typical macros with no pre/post/finally behavior.

CommonMCodeModule.InvokeMacro

This facility is here primarily for uniformity of error handling and reporting.

Examples m.InvokeMacro('m19',hVars,S)

m.InvokeMacro('m3')

Entry point for typical macros with no pre/post/finally behavior

Provides a simplified interface for invoking M-code macros that do not require pre/post/finally hook callbacks. Delegates directly to m.InvokeMacroEx() with nil opt_behavior, preserving all standard hook execution and error handling behavior.

Parameters

macro_name	(string) The precise name of the macro to invoke
...	(any) All arguments to pass verbatim to the underlying macro function

Returns: (boolean) True if the macro succeeded, false if there was an error

-- Invoke M19 with local variable handle and S parameter
m.InvokeMacro('m19', hVars, S)
 
-- Invoke M3 with no additional arguments
m.InvokeMacro('m3')

See also: CommonMCodeModule.InvokeMacroEx() for the full version with pre/post/finally support

Note: Documentation generated by AI on 2026-03-04

◆ InvokeMacroEx()

CommonMCodeModule InvokeMacroEx	(	macro_name	,
		opt_behavior	,
			... )

Invoke an M code (macro) in the standard way, including error checking, alarms, etc.

CommonMCodeModule.InvokeMacroEx

Returns: true if the macro succeeded/finished, false otherwise (if there was an error)

Macros do not really return anything. They do something. When they fail, they should error(). This function is departing from the "a,b,c" return value convention employed in earlier code.

Because this function is intended as the main entry point for common macro behavior, it will never (deliberately) create an error. It will raise alarms if anything fails.

The pre/post/finally hooks are intended to provide a (machine type-specific) macro with a way to slightly customize its behavior from the default implementation. Normal modifications of this behavior could (and probably should) be implemented as a UserMCodeModule hook.

Invocation Order

pre hook

standard hook script

check return value

macro

post

finally

Hooks

This function will invoke common hooks in the same way that the macros (implemented here, e.g.) would do it. Thus, new macro implementations should never need to run the general hooks (e.g. user.Userm3, user.m3, m.Machinem3) except for specific ones that only the macro implementation knows how/when to use (e.g. GUI/CycleStartFinal).

Backward Compatibility

There are numerous macros that call m.RunHooks() or attempt to manually run a user hook. We need to ensure that this facility doesn't result in the macro being invoked twice every time the macro is run.

Scheme 1: Code Name "Nacho Hook"

Maintain a separate, "secret namespace" for the real hooks that this script will invoke. The "formal namespace" is how the hooks are defined in their respective source code.

Before we attempt to m.RunHooks(...), check for to see if the hook exists in the "formal namespace."

If it exists, "move" it to the "secret namespace" (removing the entry from the "formal namespace").

Invoke m.RunHooks(...) with the "secret namespace" hook.

The "formal namespace" hook will no longer exist. Any explicit attempt to invoke it (probably in customization code, custom M codes, etc.) will fail.

Parameters

Parameters

macro_name	the (precise) name of the macro to invoke
opt_behavior	(optional) a table of information used to govern exceptional behavior e.g. cleanup action, other special behavior These hooks should error() if something goes wrong. The return value is meaningful, but it is not used to make decisions. 'pre': called before the macro is invoked ('pre_args' passed as the only argument) If this fails (return false or error()), the macro call and 'post' will not happen, but 'finally' will. 'post': called after the macro returns, but NOT if earlier steps fail 'finally': called after the macro returns, EVEN IF earlier steps fail
...	all the arguments given to the macro entry point that should be passed verbatim to the underlying macro function

Examples

return m.InvokeMacro('m19',hVars,S)

– Invoke the macro implementation and invoke a "finally" function (always invoked, even if the macro fails) return m.InvokeMacroEx('LubeSystem', { ["finally"] = function() w.SetOEMRegValueString("LubeSystemInCycle", "false") if w.IsOEMParamSigMapped("LubeOutputName") then w.SetOEMParamSig("LubeOutputName", false) end end }, ...)

Invoke an M-code macro in the standard way with full hook and error handling

This is the primary entry point for executing common macro behavior. It orchestrates the complete macro invocation sequence in the following order:

Invokes the optional 'pre' hook callback (if provided in opt_behavior)
Moves standard hooks to the internal "secret" namespace to prevent double-invocation
Runs the standard hooks for the macro via w.pcall(m.RunHooks, ...)
Invokes the common macro function (m['_'..macro_name]) if all prior steps succeeded
Invokes the optional 'post' callback (only if all prior steps succeeded)
Invokes the optional 'finally' callback (always, even if earlier steps failed)
Raises an alarm via w.AlarmError() for the first failure encountered

This function is designed to never itself raise an error; all failures are communicated via w.AlarmError(). The opt_behavior hooks should use error() to signal failure.

Parameters

macro_name	(string) The precise name of the macro to invoke
opt_behavior	(table\|nil) Optional table controlling exceptional behavior with keys: pre (function): Called before the macro. Receives pre_args as its only argument. If this fails, the macro and post will not run, but finally will. pre_args (any): Argument passed to the pre callback post (function): Called after the macro returns, only if all prior steps succeeded post_args (any): Argument passed to the post callback finally (function): Called after the macro returns, even if earlier steps failed finally_args (any): Argument passed to the finally callback
...	(any) All arguments to pass verbatim to the underlying macro function

Returns: (boolean) True if all steps (pre, hooks, macro, post, finally) succeeded; false otherwise

See also: CommonMCodeModule.InvokeMacro() for the simplified entry point without pre/post/finally

Note: Documentation generated by AI on 2026-03-04

Functions

Function Documentation

◆ GetInstance()

◆ InitializeScrAPI()

◆ InvokeMacro()

◆ InvokeMacroEx()

Invocation Order

pre hook

standard hook script

check return value

macro

post

finally

Hooks

Backward Compatibility

Scheme 1: Code Name "Nacho Hook"

Before we attempt to m.RunHooks(...), check for to see if the hook exists in the "formal namespace."

If it exists, "move" it to the "secret namespace" (removing the entry from the "formal namespace").

Invoke m.RunHooks(...) with the "secret namespace" hook.

Parameters