Learn more about Simulink

mdlCheckParameters - Check the validity of an S-function's parameters

Required

C Syntax

#define MDL_CHECK_PARAMETERS

void mdlCheckParameters(SimStruct *S)

C Arguments

S: SimStruct representing an S-Function block.

M Syntax

CheckParameters(s)

M Arguments

s: Instance of Simulink.MSFcnRunTimeBlock class representing a Level-2 M-File S-Function block.

Description

Verifies new parameter settings whenever parameters change or are reevaluated during a simulation. For C MEX S-functions, this method is only valid for simulation, and must be enclosed in a #if defined(MATLAB_MEX_FILE) statement to be compatible with code generation targets that support non-inlined S-functions.

When a simulation is running, changes to S-function parameters can occur at any time during the simulation loop, that is, either at the start of a simulation step or during a simulation step. When the change occurs during a simulation step, the Simulink engine calls this routine twice to handle the parameter change. The first call during the simulation step is used to verify that the parameters are correct. After verifying the new parameters, the simulation continues using the original parameter values until the next simulation step, at which time the new parameter values are used. Redundant calls are needed to maintain simulation consistency.

Note You cannot access the work, state, input, output, and other vectors in this routine. Use this routine only to validate the parameters. Additional processing of the parameters should be done in mdlProcessParameters.

C Example

This example checks the first S-function parameter to verify that it is a real nonnegative scalar.

Note Since mdlCheckParameters is an optional method, a #define MDL_CHECK_PARAMETERS statement precedes the function. Also, since the Real-Time Workshop product does not support code generation for mdlCheckParameters, the function is wrapped in a #if defined(MATLAB_MEX_FILE) statement.

#define PARAM1(S) ssGetSFcnParam(S,0)
#define MDL_CHECK_PARAMETERS   /* Change to #undef to remove function */
#if defined(MDL_CHECK_PARAMETERS) && defined(MATLAB_MEX_FILE)
static void mdlCheckParameters(SimStruct *S)
{
  if (mxGetNumberOfElements(PARAM1(S)) != 1) {
    ssSetErrorStatus(S,"Parameter to S-function must be a scalar");
    return;
  } else if (mxGetPr(PARAM1(S))[0] < 0) {
    ssSetErrorStatus(S, "Parameter to S-function must be nonnegative");
    return;
  }
}
#endif /* MDL_CHECK_PARAMETERS */

In addition to the preceding routine, you must add a call to this method from mdlInitializeSizes to check parameters during initialization, because mdlCheckParameters is only called while the simulation is running. To do this, after setting the number of parameters you expect in your S-function by using ssSetNumSFcnParams, use this code in mdlInitializeSizes:

static void mdlInitializeSizes(SimStruct *S)
{
  ssSetNumSFcnParams(S, 1);  /* Number of expected parameters */ 
#if defined(MATLAB_MEX_FILE)
   if(ssGetNumSFcnParams(S) == ssGetSFcnParamsCount(S) {
     mdlCheckParameters(S);
     if(ssGetErrorStatus(S) != NULL) return;
   } else {
     return; /* The Simulink engine reports a mismatch error. */
   }
#endif
 ...  
}

Note The macro ssGetSFcnParamsCount returns the actual number of parameters entered in the dialog box.

See matlabroot/toolbox/simulink/simdemos/src/sfun_errhdl.c for an example.

M Example

In a Level-2 M-file S-function, the setup method registers the CheckParameters method as follows

s.RegBlockMethod('CheckParameters', @CheckParam);

The subfunction CheckParam then verifies the S-function parameters. In this example, the function checks that the second parameter, an upper limit value, is greater than the first S-function parameter, a lower limit value.

function CheckParam(s)

% Check that upper limit is greater than lower limit
lowerLim = s.DialogPrm(1).Data;
upperLim = s.DialogPrm(2).Data;

if upperLim <= lowerLim,
   error('The upper limit must be greater than the lower limit.');
end

Languages

C, C++, M