| Customize Help

Modules, opcodes, and error handling


User-defined MIL functions can be associated with a user-defined module; related functions are typically grouped into the same user-defined module. You can group your functions into a maximum of 7 user-defined modules, each of which can contain up to 128 user-defined MIL functions. A function's opcode indicates both its module and its offset within the module. When allocating the function context using MfuncAlloc(), the opcode is specified as M_USER_MODULE_n + m, where n specifies the user-defined module and m specifies the function's offset within the module.

User-defined MIL functions don't need to be grouped into a module. In this case, specify the function's opcode using M_USER_FUNCTION + m, where m is a value between 0 to 127 that has not already been assigned to another ungrouped function. This means that to generate an opcode, you can have up to 128 ungrouped user-defined functions.

A function's opcode must be unique. The uniqueness of the function's opcode is particularly important when retrieving error codes since the function that returned an error is identified by its opcode. The uniqueness is also critical when executing the slave function remotely; see the Master/slave dynamics on a remote system section later in this chapter.

Error handling in slave functions

A MIL application has specific functionality and settings for error handling. Typically, the settings apply to the entire application. However, a slave function has its own error handling settings.

Current and global errors

An application has a place to store its current error and global error, if any exist. Any errors that come from a function within a slave function, however, are stored in a separate place reserved for the slave function's current and global error. To inquire or clear the slave function's errors, call MappGetError() or MappControl() with M_CLEAR_ERROR, respectively, within the slave function itself. Calling these functions within the slave function will have no effect on the error settings of the application, nor will calling these functions in the rest of the application have any effect on the slave function's error settings.

When a slave function ends, its global error, if any, will be transferred to the current error of the main application. If the slave function's errors were cleared prior to it ending, nothing is transferred. The only way for the main application to inquire an error obtained from a slave function, is by inquiring the current error, using MappGetError() with M_CURRENT while in the main application after the slave function has ended.

Logging errors

When developing user-defined MIL functions, MfuncErrorReport() allows you to create custom error codes and error messages which are treated as normal MIL errors. MfuncErrorReport() also allows you to associate each error code with an error message; up to one hundred such custom error code associations can be defined within MIL.

Any error logged by calling MfuncErrorReport() from within a slave function will be stored as the slave function's new global error. If you set ErrorCode to M_NULL, the slave function's global error is reset, resulting in no error being returned after the slave function has ended.

Print error settings

Each slave function has its own print error setting, which controls whether an error is printed to the screen, independent of the master function's setting. The default value for a slave function's print error setting is different from most other types of functions. The default for a slave function is M_PRINT_DISABLE, while it is M_PRINT_ENABLE for the rest. This setting can be changed using MappControl() set to M_ERROR + M_THREAD_CURRENT. Whatever the setting, you can always check for an error using MappGetError().

Hook functions in a slave function

Within a slave function, you can call MappHookFunction() to hook a user-defined function to an event. However, the HookType cannot be M_ERROR_CURRENT or M_ERROR_GLOBAL. Specifying either of these two event types will result in an error.