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