Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

mdlInitializeSampleTimes

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

Required

Yes

Languages

C, C++

Syntax

#define MDL_INITIALIZE_SAMPLE_TIMES
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.

Introduced before R2006a

Was this topic helpful?