Main Content

Handle Errors in S-Functions

About Handling Errors

When working with S-functions, it is important to handle unexpected events such as invalid parameter values correctly.

If your C MEX S-function has parameters whose contents you need to validate, use the following technique to report errors.

ssSetErrorStatus(S,"Error encountered due to ...");
return;

In most cases, the Simulink® engine displays errors in the Diagnostic Viewer. If the error is encountered in mdlCheckParameters as the S-function parameters are being entered into the block dialog, the engine opens the error dialog shown below. In either case, the engine displays the error message along with the name of the S-function and the associated S-function block that invoked the error.

The second argument to ssSetErrorStatus must be persistent memory. It cannot be a local variable in your function. For example, the following causes unpredictable errors.

mdlOutputs()
{
    char msg[256]; /* ILLEGAL: should be "static char */
							/*msg[256];"*/
    sprintf(msg,"Error due to %s", string);
    ssSetErrorStatus(S,msg);
    return;
}

Because ssSetErrorStatus does not generate exceptions, using it to report errors in your S-function is preferable to using mexErrMsgTxt. The mexErrMsgTxt function uses exception handling to terminate S-function execution. To support exception handling in S-functions, the Simulink engine must set up exception handlers prior to each S-function invocation. This introduces overhead into simulation.

Exception Free Code

You can avoid simulation overhead by ensuring that your C MEX S-function contains entirely exception free code. Exception free code refers to code that never long-jumps. Your S-function is not exception free if it contains any routine that, when called, has the potential of long-jumping. For example, mexErrMsgTxt throws an exception (i.e., long-jumps) when called, thus ending execution of your S-function. Using mxCalloc can cause unpredictable results in the event of a memory allocation error, because mxCalloc long-jumps. If memory allocation is needed, use the stdlib.h calloc routine directly and perform your own error handling.

If you do not call mexErrMsgTxt or other API routines that cause exceptions, use the SS_OPTION_EXCEPTION_FREE_CODE S-function option. You do this by issuing the following command in the mdlInitializeSizes function.

ssSetOptions(S, SS_OPTION_EXCEPTION_FREE_CODE);

Setting this option increases the performance of your S-function by allowing the Simulink engine to bypass the exception-handling setup that is usually performed prior to each S-function invocation. You must take extreme care to verify that your code is exception free when using SS_OPTION_EXCEPTION_FREE_CODE. If your S-function generates an exception when this option is set, unpredictable results occur.

All mex* routines have the potential of long-jumping. Several mx* routines also have the potential of long-jumping. To avoid any difficulties, use only the API routines that retrieve a pointer or determine the size of parameters. For example, the following API routines never throw an exception: mxGetPr, mxGetData, mxGetNumberOfDimensions, mxGetM, mxGetN, and mxGetNumberOfElements.

Code in run-time routines can also throw exceptions. Run-time routines refer to certain S-function routines that the engine calls during the simulation loop (see Simulink Engine Interaction with C S-Functions). The run-time routines include

  • mdlGetTimeOfNextVarHit

  • mdlOutputs

  • mdlUpdate

  • mdlDerivatives

If all run-time routines within your S-function are exception free, you can use this option:

ssSetOptions(S, SS_OPTION_RUNTIME_EXCEPTION_FREE_CODE);

The other routines in your S-function do not have to be exception free.

ssSetErrorStatus Termination Criteria

If one of your C MEX S-function callback methods invokes ssSetErrorStatus during a simulation, the Simulink engine posts the error and terminates the simulation as soon as the callback method returns. If your S-function SS_OPTION_CALL_TERMINATE_ON_EXIT option is enabled (see ssSetOptions), The engine invokes your S-function mdlTerminate method as part of the termination process. Otherwise, the engine invokes your S-function mdlTerminate method only if at least one block mdlStart method has executed without error during the simulation.

ssSetErrorStatus is not thread-safe. The function can overwrite existing errors or report inaccurate errors. In parallel executions, use ssSetLocalErrorStatus to ensure thread-safe execution.

Checking Array Bounds

If your C MEX S-function causes otherwise inexplicable errors, the reason might be that the S-function is writing beyond its assigned areas in memory. You can verify this possibility by enabling the array bounds checking feature. This feature detects any attempt by an S-Function block to write beyond the areas assigned to it for the following types of block data:

  • Work vectors (R, I, P, D, and mode)

  • States (continuous and discrete)

  • Outputs

To enable array bounds checking, select warning or error from the Array bounds exceeded options list on the Configuration Parameters dialog box. Alternatively, enter the following command at the MATLAB® command prompt.

set_param(modelName, 'ArrayBoundsChecking', ValueStr)

where modelName is the name of the Simulink model and ValueStr is either 'none', 'warning', or 'error'.

See Also

|

Related Topics