Main Content

mdlInitializeSampleTimes

Specify the sample rates at which this C MEX S-function operates

Required

Yes

Languages

C, C++

Syntax

void mdlInitializeSampleTimes(SimStruct *S)

Arguments

S

SimStruct representing an S-Function block.

Description

This method should specify the sample time and offset time for each sample rate at which this S-function operates via the following paired macros

ssSetSampleTime(S, sampleTimeIndex, sample_time)
ssSetOffsetTime(S, offsetTimeIndex, offset_time)

where sampleTimeIndex runs from 0 to one less than the number of sample times specified in mdlInitializeSizes via ssSetNumSampleTimes.

If the S-function operates at one or more sample rates, this method can specify any of the following sample time and offset values for a given sample time:

  • [CONTINUOUS_SAMPLE_TIME, 0.0]

  • [CONTINUOUS_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET]

  • [discrete_sample_period, offset]

  • [VARIABLE_SAMPLE_TIME, 0.0]

The uppercase values are macros defined in sl_sample_time_defs.h.

If the S-function operates at one rate, this method can alternatively set the sample time to one of the following sample/offset time pairs.

  • [INHERITED_SAMPLE_TIME, 0.0]

  • [INHERITED_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET]

If the number of sample times is 0, the Simulink® engine assumes that the S-function inherits its sample time from the block to which it is connected, i.e., that the sample time is

[INHERITED_SAMPLE_TIME,  0.0]

This method can therefore return without doing anything.

Use the following guidelines when specifying sample times.

  • A continuous function that changes during minor integration steps should set the sample time to

    [CONTINUOUS_SAMPLE_TIME, 0.0]
    
  • A continuous function that does not change during minor integration steps should set the sample time to

    [CONTINUOUS_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET]
    
  • A discrete function that changes at a specified rate should set the sample time to

    [discrete_sample_period, offset]
    

    where

    discrete_sample_period > 0.0 
    

    and

    0.0 <= offset < discrete_sample_period
    
  • A discrete function that changes at a variable rate should set the sample time to

    [VARIABLE_SAMPLE_TIME, 0.0]
    

    The Simulink engine invokes the mdlGetTimeOfNextVarHit function to get the time of the next sample hit for the variable-step discrete task.

    Note that VARIABLE_SAMPLE_TIME requires a variable-step solver.

  • To operate correctly in a triggered subsystem or a periodic system, a discrete S-function should

    • Specify a single sample time set to

      [INHERITED_SAMPLE_TIME, 0.0]
      
    • Use ssSetOptions to set the SS_OPTION_DISALLOW_CONSTANT_SAMPLE_TIME simulation option in mdlInitializeSizes

    • Verify that it was assigned a discrete or triggered sample time in mdlSetWorkWidths:

      if (ssGetSampleTime(S, 0) == CONTINUOUS_SAMPLE_TIME) {
         ssSetErrorStatus(S, 
           "This block cannot be assigned a continuous sample 
      			time");
       }
      

    After propagating sample times throughout the block diagram, the engine assigns the sample time

    [INHERITED_SAMPLE_TIME, INHERITED_SAMPLE_TIME]
    

    to discrete blocks residing in triggered subsystems.

If this function has no intrinsic sample time, it should set its sample time to inherited according to the following guidelines:

  • A function that changes as its input changes, even during minor integration steps, should set its sample time to

    [INHERITED_SAMPLE_TIME, 0.0]
    

    A function that changes as its input changes, but doesn't change during minor integration steps (i.e., is held during minor steps) should set its sample time to

    [INHERITED_SAMPLE_TIME, FIXED_IN_MINOR_STEP_OFFSET]
    

The S-function should use the ssIsSampleHit or ssIsContinuousTask macros to check for a sample hit during execution (in mdlOutputs or mdlUpdate). For example, if the block's first sample time is continuous, the function can use the following code fragment to check for a sample hit.

if (ssIsContinuousTask(S,tid)) {
}

Note

The function receives incorrect results if it uses ssIsSampleHit(S,0,tid).

If the function wants to determine whether the third (discrete) task has a hit, it can use the following code fragment.

if (ssIsSampleHit(S,2,tid)) {
}

Note

If you have Simulink Coder™, when generating code for a noninlined S-function that contains this method, make sure the method is not wrapped in a #if defined(MATLAB_MEX_FILE) statement. For example:

#if defined(MATLAB_MEX_FILE) 
static void mdlInitializeSampleTimes(SimStruct *S) 
{ 
   /* Add mdlInitializeSampleTimes code here *
} 
#endif 

The define statement makes the mdlInitializeSampleTimes method available only to a MATLAB® MEX file. If the S-function is not inlined, the Simulink Coder product cannot use this method, resulting in link or run-time errors.

Version History

Introduced before R2006a