Writing S-Functions

ssSetOptions

Specify S-function options.

Syntax

void ssSetOptions(SimStruct *S, uint_T options)

Arguments
S
   SimStruct representing an S-function block.

Description

Use in mdlInitializeSizes to specifiy S-function options (see below). The options must be joined using the OR operator. For example:

ssSetOption(S, (SS_OPTION_EXCEPTION_FREE_CODE |
                SS_OPTION_DISCRETE_VALUED_OUTPUT));

S-Function Options

An S-function can specify the following options, using ssSetOptions:

• SS_OPTION_EXCEPTION_FREE_CODE

If your S-function does not use mexErrMsgTxt, mxCalloc, or any other routines that can throw an exception when called, you can set this option for improved performance.

• SS_OPTION_RUNTIME_EXCEPTION_FREE_CODE

Similar to SS_OPTION_EXCEPTION_FREE_CODE except it only applies to the "run-time" routines: mdlGetTimeOfNextVarHit, mdlOutputs, mdlUpdate, and mdlDerivatives.

• SS_OPTION_DISCRETE_VALUED_OUTPUT

Specify this if your S-function has discrete valued outputs. This is checked when your S-function is placed within an algebraic loop. If your S-function has discrete valued outputs, then its outputs will not be assigned algebraic variables.

• SS_OPTION_PLACE_ASAP

Used to specify that your S-function should be placed as soon as possible. This is typically used by devices connecting to hardware.

• SS_OPTION_ALLOW_INPUT_SCALAR_EXPANSION

Used to specify that the input to your S-function input ports can be either 1 or the size specified by the port, which is usually referred to as the block width.

• SS_OPTION_DISALLOW_CONSTANT_SAMPLE_TIME

Use to disable an S-function block from inheriting a constant sample time.

• SS_OPTION_ASYNCHRONOUS

This option applies only to S-functions that have 0 or 1 input ports and 1 output port. The output port must be configured to perform function calls on every element. If any of these requirements are not met, the SS_OPTION_ASYNCHRONOUS is ignored. Use this option when driving function-call subsystems that will be attached to interrupt service routines.

• SS_OPTION_ASYNC_RATE_TRANSITION

Use this when your S-function converts a signal from one rate to another rate.

• SS_OPTION_RATE_TRANSITION

Use this option when your S-function is behaving as a unit delay or a ZOH. This macro support these two operations only. It identifies a unit delay by the presence of mdlUpdate; if mdlUpdate is absent, the operation is taken to be ZOH.

• SS_OPTION_PORT_SAMPLE_TIMES_ASSIGNED

Use this when you have registered multiple sample times (ssSetNumSampleTimes > 1) to specify the rate at when each input and output port is running at. The simulation engine needs this information when checking for illegal rate transitions.

• SS_OPTION_SFUNCTION_INLINED_FOR_RTW

Set this if you have a .tlc file for your S-function and do not have a mdlRTW method. Setting option has no effect if you have a mdlRTW method.

• SS_OPTION_ALLOW_PARTIAL_DIMENSIONS_CALL

Indicates that the S-function can handle dynamically dimensioned signals. See mdlSetInputPortDimensions, mdlSetOutputPortDimensions, or mdlSetDefaultPortDimensions for more information.

• SS_OPTION_FORCE_NONINLINED_FCNCALL

Use this flag if the block requires that all function-call subsystems that it calls should be generated as procedures instead of possibly being generated as inlined code.

• SS_OPTION_USE_TLC_WITH_ACCELERATOR

Use this to force the Accelerator to use the TLC inlining code for a S-function which will speed up execution of the S-function. By default, the Accelerator will use the mex version of the S-function even though a TLC file for the S-function exists. This option should not be set for device driver blocks (A/D) or when there is an incompatability between running the mex Start/InitializeConditions functions together with the TLC Outputs/Update/Derivatives.

• SS_OPTION_SIM_VIEWING_DEVICE

This S-function is a SimViewingDevice. As long as it meets the other requirement for this type of block (no states, no outputs, etc), it will be considered to be an external mode block (show up in the external mode GUI and no code is generated for it). During an external mode simulation, this block is run on the host only.

• SS_OPTION_CALL_TERMINATE_ON_EXIT

This option allows S-function authors to better manage the data cached in run-time parameters and UserData. Setting this option guarantees that the mdlTerminate function is called if mdlInitializeSizes is called. This means that mdlTerminate is called:

• When a simulation ends.

Note that it does not matter if the simulation failed and at what stage the simulation failed. Therefore, if the mdlSetWorkWidths of some block errors out, the model's other blocks have a chance to free the memory during a call to mdlTerminate.

• Every time an S-function block is destroyed.
• If the user is editing the S-function graphically.

If this option is not set, mdlTerminate is called only if at least one of the blocks has had its mdlStart called.

• SS_OPTION_REQ_INPUT_SAMPLE_TIME_MATCH

Use this to option to specify that the input signal sample time(s) match the sample time assigned to the block input port. For example,



generates an error if this option is set. If the block (or input port) sample time is inherited, then there will be no error generated.

Languages

C, C++

ssSetOffsetTime

ssSetOutputPortComplexSignal