Directives and Built-in Functions (Target Language Compiler)

Target Language Compiler

Built-In Functions and Values

Table 6-5, TLC Built-in Functions and Values, lists the built-in functions and values that are added to the list of parameters that appear in the model.rtw file. These Target Language Compiler functions and values are defined in uppercase so that they are visually distinct from other parameters in the model.rtw file, and by convention, from user-defined parameters.

Table 6-5: TLC Built-in Functions and Values
Built-In Function Name
Expansion

CAST(expr, expr)
The first expression must be a string that corresponds to one of the type names in the Target Language Values table, and the second expression will be cast to that type. A typical use might be to cast a variable to a real format as in
  CAST("Real", variable-name)An example of this is in working with parameter values for S-functions. To use them within C code, you need to typecast them to real so that a value such as "1" will be formatted as "1.0" (see also %realformat).

EXISTS(var)
If the var identifier is not currently in scope, the result is TLC_FALSE. If the identifier is in scope, the result is TLC_TRUE. var can be a single identifier or an expression involving the . and [] operators.
Note: prior to TLC release 4, the semantics of EXISTS differed from the above. See Compatibility Issues.

FEVAL(matlab-command,    TLC-expressions)
Performs an evaluation in MATLAB. For example
%assign result = FEVAL("sin",3.14159)
The %matlab directive can be used to call a MATLAB function that does not return a result. For example,
  %matlab disp(2.718)
Note: if the MATLAB function returns more than one value, TLC only receives the first value.

FILE_EXISTS(expr)
expr must be a string. If a file by the name expr does not exist on the path, the result is TLC_FALSE. If a file by that name exists on the path, the result is TLC_TRUE.

FORMAT(realvalue, format)
The first expression is a Real value to format. The second expression is either "EXPONENTIAL" or "CONCISE". Outputs the Real value in the designated format where EXPONENTIAL uses exponential notation with 16 digits of precision, and CONCISE outputs the number in a more readable format while maintaining numerical accuracy.

FIELDNAMES(record)
Returns a array of strings containing the record field names associated with the record. As it returns a sorted list of strings, function is O(n*log(n)).

GETFIELD(record,    "fieldname")
Returns the contents of the specified field name, if the field name is associated with the record. By virtue of hash lookup, executes in constant time

GENERATE(record,    function-name,    ...)
This is used to execute function calls mapped to a specific record type (i.e., Block record functions). For example, use this to execute the functions in the .tlc files for built-in blocks. Note, TLC automatically "scopes" or adds the first argument to the list of scopes searched as if it appears on a %with directive line.

GENERATE_FILENAME(type)
For the specified record type, does a .tlc file exist? Use this to see if the GENERATE_TYPE call will succeed.

GENERATE_FORMATTED_VALUE    (expr, string)
Returns a potentially multiline string that can be used to declare the value(s) of expr in the current target language. The second argument is a string that is used as the variable name in a descriptive comment on the first line of the return string. If the second argument is the empty string, "", then no descriptive comment is put into the output string.

GENERATE_FUNCTION_EXISTS    (record, function-name)
Determines if a given block function exists. The first expression is the same as the first argument to GENERATE, namely a block scoped variable containing a Type. The second expression is a string that should match the function name.

GENERATE_TYPE    (record, function-name,    type, ...)
Similar to GENERATE, except type overrides the Type field of the record. Use this when executing functions mapped to specific S-function blocks records based upon the S-function name (i.e., name becomes type).

GENERATE_TYPE_FUNCTION_EXISTS    (record, function-name,    type)
Same as GENERATE_FUNCTION_EXISTS except it overrides the Type built into the record.

GET_COMMAND_SWITCH
Returns the value of command-line switches. Only the following switches are supported:v, m, p, O, d, r, I, aSee also Command Line Arguments

IDNUM(expr)
expr must be a string. The result is a vector where the first element is a leading string (if any) and the second element is a number appearing at the end of the input string. For example:
IDNUM("ABC123") yields ["ABC", 123]

IMAG(expr)
Returns the imaginary part of a complex number.

INT8MAX
127

INT8MIN
-128

INT16MAX
32767

INT16MIN
-32768

INT32MAX
2147483647

INT32MIN
-2147483648

INTMIN
Minimum integer value on target machine

INTMAX
Maximum integer value on target machine

ISALIAS(record)
Returns TLC_TRUE if the record is a reference (symbolic link) to a different record, and TLC_FALSE otherwise.

ISEQUAL(expr1, expr2)
Where the datatypes of both expressions are numeric: returns TLC_TRUE if the first expression contains the same value as the second expression; returns TLC_FALSE otherwise.
Where the datatype of either expression is non- numeric (e.g. string or record): returns TLC_TRUE if and only if both expressions have the same datatype and contain the same value; returns TLC_FALSE otherwise.

ISEMPTY(expr)
Returns TLC_TRUE if the expression contains an empty string, vector, or record, and TLC_FALSE otherwise.

ISFIELD(record, "fieldname")
Returns TLC_TRUE if the field name is associated to the record, and TLC_FALSE otherwise.

ISINF(expr)
Returns TLC_TRUE if the value of the expression is inf and TLC_FALSE otherwise.

ISNAN(expr)
Returns TLC_TRUE if the value of the expression is NAN, and TLC_FALSE otherwise.

ISFINITE(expr)
Returns TLC_TRUE if the value of the expression is not +/- inf or NAN, and TLC_FALSE otherwise.

NULL_FILE
A predefined file for no output that you can use as an argument to
%selectfile to prevent output.

NUMTLCFILES
The number of target files used thus far in expansion.

OUTPUT_LINES
Returns the number of lines that have been written to the currently selected file or buffer. Does not work for STDOUT or NULL_FILE

REAL(expr)
Returns the real part of a complex number.

REMOVEFIELD(record, "fieldname")
Removes the specified field from the contents of the record. Returns TLC_TRUE if the field was removed; otherwise returns TLC_FALSE.

ROLL_ITERATIONS()
Returns the number of times the current roll regions are looping or NULL if not inside a %roll construct.

SETFIELD(record, "fieldname", value)
Sets the contents of the field name associated to the record. Returns TLC_TRUE if the field was added; otherwise returns TLC_FALSE.

SIZE(expr[,expr])
Calculates the size of the first expression and generates a two-element, row vector. If the second operand is specified, it is used as an integral index into this row vector; otherwise the entire row vector is returned. SIZE(x) applied to any scalar returns [1 1]. SIZE(x) applied to any scope returns the number of repeated entries of that scope type (e.g., SIZE(Block) returns
[1,<number of blocks>].

SPRINTF(format,var,...)
Formats the data in variable var (and in any additional variable arguments) under control of the specified format string, and returns a string variable containing the values. Operates like C library sprintf(), except that output is the return value rather than contained in an argument to sprintf.

STDOUT
A predefined file for stdout output. You can use this as an argument to %selectfile to force output to stdout.

STRING(expr)
Expands the expression into a string; the characters \, \n, and " are escaped by preceding them with \ (backslash). All the ANSI escape sequences are translated into string form.

STRINGOF(expr)
Accepts a vector of ASCII values and returns a string that is constructed by treating each element as the ASCII code for a single character. Used primarily for S-function string parameters in Real-Time Workshop.

SYSNAME(expr)
Looks for specially formatted strings of the form <x>/y and returns x and y as a 2-element string vector. This is used to resolve subsystem names in Real-Time Workshop. For example,
%<sysname("<sub>/Gain")>
returns
["sub","Gain"]
In Block records, the name of the block is written similar to <sys/blockname> where sys is S# or Root. You can obtain the full pathname by calling LibGetBlockPath(block); this will include newlines and other troublesome characters that cause display difficulties. To obtain a full pathname suitable for one line comments but not identical to the Simulink pathname, use LibGetFormattedBlockPath(block).

TLCFILES
Returns a vector containing the names of all the target files included thus far in the expansion. See also NUMTLCFILES.

TLC_FALSE
Boolean constant which equals a negative evaluated Boolean expression.

TLC_TRUE
Boolean constant which equals a positive evaluated Boolean expression.

TLC_TIME
The date and time of compilation.

TLC_VERSION
The version and date of the Target Language Compiler.

TYPE(expr)
Evaluates expr and determines the result type. The result of this function is a string that corresponds to the type of the given expression. See value type string in Table 6-2, Target Language Values for possible values.

UINT8MAX
255U

UINT16MAX
65535U

UINT32MAX
4294967295U

UINTMAX
Maximum unsigned integer value on target machine.

WHITE_SPACE(expr)
Accepts a string and returns 1 if the string contains only whitespace characters ( , \t, \n, \r); returns 0 otherwise.

WILL_ROLL(expr1, expr2)
The first expression is a roll vector and the second expression is a roll threshold. This function returns true if the vector contains a range that will roll.

**Table 6-5: TLC Built-in Functions and Values**
Built-In Function Name	Expansion
`CAST(expr, expr)`	The first expression must be a string that corresponds to one of the type names in the Target Language Values table, and the second expression will be cast to that type. A typical use might be to cast a variable to a real format as in `CAST("Real",` `variable-name)`An example of this is in working with parameter values for S-functions. To use them within C code, you need to typecast them to `real` so that a value such as "1" will be formatted as "1.0" (see also `%realformat`).
`EXISTS(var)`	If the `var` identifier is not currently in scope, the result is `TLC_FALSE.` If the identifier is in scope, the result is `TLC_TRUE`. `var` can be a single identifier or an expression involving the `.` and `[]` operators. Note: prior to TLC release 4, the semantics of `EXISTS` differed from the above. See Compatibility Issues.
`FEVAL(matlab-command, TLC-expressions)`	Performs an evaluation in MATLAB. For example `%assign result = FEVAL("sin",3.14159)` The `%matlab` directive can be used to call a MATLAB function that does not return a result. For example, `%matlab disp(2.718)` Note: if the MATLAB function returns more than one value, TLC only receives the first value.
`FILE_EXISTS(expr)`	`expr` must be a string. If a file by the name `expr` does not exist on the path, the result is `TLC_FALSE`. If a file by that name exists on the path, the result is `TLC_TRUE`.
`FORMAT(realvalue, format)`	The first expression is a `Real` value to format. The second expression is either "`EXPONENTIAL`" or "`CONCISE`". Outputs the `Real` value in the designated format where `EXPONENTIAL` uses exponential notation with 16 digits of precision, and `CONCISE` outputs the number in a more readable format while maintaining numerical accuracy.
`FIELDNAMES(record)`	Returns a array of strings containing the record field names associated with the record. As it returns a sorted list of strings, function is O(n*log(n)).
`GETFIELD(record, "fieldname")`	Returns the contents of the specified field name, if the field name is associated with the record. By virtue of hash lookup, executes in constant time
`GENERATE(record, function-name, ...)`	This is used to execute function calls mapped to a specific record type (i.e., Block record functions). For example, use this to execute the functions in the `.tlc` files for built-in blocks. Note, TLC automatically "scopes" or adds the first argument to the list of scopes searched as if it appears on a `%with` directive line.
`GENERATE_FILENAME(type)`	For the specified record type, does a `.tlc` file exist? Use this to see if the `GENERATE_TYPE` call will succeed.
`GENERATE_FORMATTED_VALUE (expr, string)`	Returns a potentially multiline string that can be used to declare the value(s) of `expr` in the current target language. The second argument is a string that is used as the variable name in a descriptive comment on the first line of the return string. If the second argument is the empty string, `""`, then no descriptive comment is put into the output string.
`GENERATE_FUNCTION_EXISTS (record, function-name)`	Determines if a given block function exists. The first expression is the same as the first argument to `GENERATE`, namely a block scoped variable containing a `Type`. The second expression is a string that should match the function name.
`GENERATE_TYPE (record, function-name, type, ...)`	Similar to `GENERATE`, except `type` overrides the `Type` field of the record. Use this when executing functions mapped to specific S-function blocks records based upon the S-function name (i.e., name becomes type).
`GENERATE_TYPE_FUNCTION_EXISTS (record, function-name, type)`	Same as `GENERATE_FUNCTION_EXISTS` except it overrides the `Type` built into the record.
`GET_COMMAND_SWITCH`	Returns the value of command-line switches. Only the following switches are supported:`v, m, p, O, d, r, I, a`See also Command Line Arguments
`IDNUM(expr)`	`expr` must be a string. The result is a vector where the first element is a leading string (if any) and the second element is a number appearing at the end of the input string. For example: `IDNUM("ABC123") yields ["ABC", 123]`
`IMAG(expr)`	Returns the imaginary part of a complex number.
`INT8MAX`	`127`
`INT8MIN`	`-128`
`INT16MAX`	`32767`
`INT16MIN`	`-32768`
`INT32MAX`	`2147483647`
`INT32MIN`	`-2147483648`
`INTMIN`	Minimum integer value on target machine
`INTMAX`	Maximum integer value on target machine
`ISALIAS(record)`	Returns `TLC_TRUE` if the record is a reference (symbolic link) to a different record, and `TLC_FALSE` otherwise.
`ISEQUAL(expr1, expr2)`	Where the datatypes of both expressions are numeric: returns `TLC_TRUE` if the first expression contains the same value as the second expression; returns `TLC_FALSE` otherwise. Where the datatype of either expression is non- numeric (e.g. string or record): returns `TLC_TRUE` if and only if both expressions have the same datatype and contain the same value; returns `TLC_FALSE` otherwise.
`ISEMPTY(expr)`	Returns `TLC_TRUE` if the expression contains an empty string, vector, or record, and `TLC_FALSE` otherwise.
`ISFIELD(record, "fieldname")`	Returns `TLC_TRUE` if the field name is associated to the record, and `TLC_FALSE` otherwise.
`ISINF(expr)`	Returns `TLC_TRUE` if the value of the expression is `inf` and `TLC_FALSE` otherwise.
`ISNAN(expr)`	Returns `TLC_TRUE` if the value of the expression is `NAN`, and `TLC_FALSE` otherwise.
`ISFINITE(expr)`	Returns `TLC_TRUE` if the value of the expression is not +/- `inf` or `NAN,` and `TLC_FALSE` otherwise.
`NULL_FILE`	A predefined file for no output that you can use as an argument to `%selectfile` to prevent output.
`NUMTLCFILES`	The number of target files used thus far in expansion.
`OUTPUT_LINES`	Returns the number of lines that have been written to the currently selected file or buffer. Does not work for `STDOUT` or `NULL_FILE`
`REAL(expr)`	Returns the real part of a complex number.
`REMOVEFIELD(record, "fieldname")`	Removes the specified field from the contents of the record. Returns `TLC_TRUE` if the field was removed; otherwise returns `TLC_FALSE`.
`ROLL_ITERATIONS()`	Returns the number of times the current roll regions are looping or `NULL` if not inside a `%roll` construct.
`SETFIELD(record, "fieldname", value)`	Sets the contents of the field name associated to the record. Returns `TLC_TRUE` if the field was added; otherwise returns `TLC_FALSE`.
`SIZE(expr[,expr])`	Calculates the size of the first expression and generates a two-element, row vector. If the second operand is specified, it is used as an integral index into this row vector; otherwise the entire row vector is returned. `SIZE(x)` applied to any scalar returns `[1 1]`. `SIZE(x)` applied to any scope returns the number of repeated entries of that scope type (e.g., `SIZE(Block)` returns `[1,<number of blocks>]`.
`SPRINTF(format,var,...)`	Formats the data in variable `var` (and in any additional variable arguments) under control of the specified format string, and returns a string variable containing the values. Operates like C library `sprintf()`, except that output is the return value rather than contained in an argument to `sprintf`.
`STDOUT`	A predefined file for `stdout` output. You can use this as an argument to `%selectfile` to force output to `stdout`.
`STRING(expr)`	Expands the expression into a string; the characters `\`, `\n`, and `"` are escaped by preceding them with `\` (backslash). All the ANSI escape sequences are translated into string form.
`STRINGOF(expr)`	Accepts a vector of ASCII values and returns a string that is constructed by treating each element as the ASCII code for a single character. Used primarily for S-function string parameters in Real-Time Workshop.
`SYSNAME(expr)`	Looks for specially formatted strings of the form `<x>/y` and returns `x` and `y` as a 2-element string vector. This is used to resolve subsystem names in Real-Time Workshop. For example, `%<sysname("<sub>/Gain")>` returns `["sub","Gain"]` In `Block` records, the name of the block is written similar to `<sys/blockname>` where `sys` is `S#` or `Root`. You can obtain the full pathname by calling `LibGetBlockPath(block)`; this will include newlines and other troublesome characters that cause display difficulties. To obtain a full pathname suitable for one line comments but not identical to the Simulink pathname, use `LibGetFormattedBlockPath(block)`.
`TLCFILES`	Returns a vector containing the names of all the target files included thus far in the expansion. See also `NUMTLCFILES`.
`TLC_FALSE`	Boolean constant which equals a negative evaluated Boolean expression.
`TLC_TRUE`	Boolean constant which equals a positive evaluated Boolean expression.
`TLC_TIME`	The date and time of compilation.
`TLC_VERSION`	The version and date of the Target Language Compiler.
`TYPE(expr)`	Evaluates `expr` and determines the result type. The result of this function is a string that corresponds to the type of the given expression. See value type string in Table 6-2, Target Language Values for possible values.
`UINT8MAX`	`255U`
`UINT16MAX`	`65535U`
`UINT32MAX`	`4294967295U`
`UINTMAX`	Maximum unsigned integer value on target machine.
`WHITE_SPACE(expr)`	Accepts a string and returns 1 if the string contains only whitespace characters ( , `\t`, `\n`, `\r`); returns 0 otherwise.
`WILL_ROLL(expr1, expr2)`	The first expression is a roll vector and the second expression is a roll threshold. This function returns `true` if the vector contains a range that will roll.

FEVAL Function

The FEVAL built-in function calls MATLAB M-file functions and MEX-functions. The structure is

%assign result = FEVAL( matlab-function-name, rhs1, rhs2, ...
    rhs3, ... );

Note Only a single left-side argument is allowed when calling MATLAB.

This table shows the conversions that are made when calling MATLAB.

Table 6-6:
TLC Type
MATLAB Type

"Boolean"
Boolean (scalar or Matrix)

"Number"
Double (scalar or Matrix)

"Real"
Double (scalar or Matrix)

"Real32"
Double (scalar or Matrix)

"Unsigned"
Double (scalar or Matrix)

"String"
String

"Vector"
If the vector is homogeneous, it will convert to a MATLAB vector of the appropriate value. If the vector is heterogeneous, it converts to a MATLAB cell array.

"Gaussian"
Complex (scalar or Matrix)

"UnsignedGaussian"
Complex (scalar or Matrix)

"Complex"
Complex (scalar or Matrix)

"Complex32"
Complex (scalar or Matrix)

"Identifier"
String

"Subsystem"
String

"Range"
expanded vector of Doubles

"Idrange"
expanded vector of Doubles

"Matrix"
If the matrix is homogeneous, it will convert to a MATLAB matrix of the appropriate value. If the matrix is heterogeneous, it converts to a MATLAB cell array. (Cell arrays can be nested.)

"Scope" or "Record"
Structure with elements

Scope or Record alias
String containing fully qualified alias name

Scope or Record array
Cell array of structures

Any other type
Conversion not supported

**Table 6-6:**
TLC Type	MATLAB Type
`"Boolean"`	`Boolean (scalar or Matrix)`
`"Number"`	`Double (scalar or Matrix)`
`"Real"`	`Double (scalar or Matrix)`
`"Real32"`	`Double (scalar or Matrix)`
`"Unsigned"`	`Double (scalar or Matrix)`
`"String"`	`String`
`"Vector"`	`If the vector is homogeneous, it will convert to a MATLAB vector of the appropriate value. If the vector is heterogeneous, it converts to a MATLAB cell array.`
`"Gaussian"`	`Complex (scalar or Matrix)`
`"UnsignedGaussian"`	`Complex (scalar or Matrix)`
`"Complex"`	`Complex (scalar or Matrix)`
`"Complex32"`	`Complex (scalar or Matrix)`
`"Identifier"`	`String`
`"Subsystem"`	`String`
`"Range"`	`expanded vector of Doubles`
`"Idrange"`	`expanded vector of Doubles`
`"Matrix"`	`If the matrix is homogeneous, it will convert to a MATLAB matrix of the appropriate value. If the matrix is heterogeneous, it converts to a MATLAB cell array. (Cell arrays can be nested.)`
`"Scope" or "Record"`	`Structure with elements`
`Scope or Record alias`	`String containing fully qualified alias name`
`Scope or Record array`	`Cell array of structures`
`Any other type`	`Conversion not supported`

When values are returned from MATLAB, they are converted as shown in this table. Note that conversion of matrices with more than 2 dimensions is not supported, nor is conversion or downcast of 64-bit integer values,

Table 6-7:
MATLAB Type
TLC Type

String
String

Vector of Strings
Vector of Strings

Boolean (scalar or Matrix)
Boolean (scalar or Matrix)

INT8,INT16,INT32 (scalar or Matrix)
Number (scalar or Matrix)

INT64
Not supported

UINT64
Not supported

Complex INT8,INT16,INT32 (scalar or Matrix)
Gaussian (scalar or Matrix)

UINT8,UINT16,UINT32 (scalar or Matrix)
Unsigned (scalar or Matrix)

Complex UINT8,UINT16,UINT32 (scalar or Matrix)
UnsignedGaussian (scalar or Matrix)

Single precision
Real32 (scalar or Matrix)

Complex single precision
Complex32 (scalar or Matrix)

Double precision
Real (scalar or Matrix)

Complex double precision
Complex (scalar or Matrix)

Sparse matrix
Expanded out to matrix of Doubles

Cell array of structures
Record array

Cell array of non-structures
Vector or matrix of types converted from the types of the elements

Cell array of structures and non-structures
Conversion not supported

Structure
Record

Object
Conversion not supported

**Table 6-7:**
MATLAB Type	TLC Type
`String`	`String`
`Vector of Strings`	`Vector of Strings`
`Boolean (scalar or Matrix)`	`Boolean (scalar or Matrix)`
`INT8,INT16,INT32 (scalar or Matrix)`	`Number (scalar or Matrix)`
`INT64`	Not supported
`UINT64`	Not supported
`Complex INT8,INT16,INT32 (scalar or Matrix)`	Gaussian (scalar or Matrix)
`UINT8,UINT16,UINT32 (scalar or Matrix)`	`Unsigned (scalar or Matrix)`
`Complex UINT8,UINT16,UINT32 (scalar or Matrix)`	UnsignedGaussian (scalar or Matrix)
`Single precision`	`Real32 (scalar or Matrix)`
`Complex single precision`	`Complex32 (scalar or Matrix)`
`Double precision`	`Real (scalar or Matrix)`
`Complex double precision`	`Complex (scalar or Matrix)`
`Sparse matrix`	`Expanded out to matrix of Doubles`
`Cell array of structures`	Record array
`Cell array of non-structures`	Vector or matrix of types converted from the types of the elements
`Cell array of structures and non-structures`	Conversion not supported
`Structure`	`Record`
`Object`	Conversion not supported

Other value types are not currently supported.

As an example, this statement uses the FEVAL built-in function to call MATLAB to take the sine of the input argument.

%assign result = FEVAL( "sin", 3.14159 )

Variables (identifiers) can take on the following constant values. Note the suffix on the value one.

Constant Form
TLC Type

1.0
"Real"

1.0[F/f]
"Real32"

1
"Number"

1[U|u]
"Unsigned"

1.0i
"Complex"

1[Ui|ui]
"UnsignedGaussian"

1i
"Gaussian"

1.0[Fi|fi]
"Complex32"

Constant Form	TLC Type
`1.0`	`"Real"`
`1.0[F/f]`	`"Real32"`
`1`	`"Number"`
`1[U\|u]`	`"Unsigned"`
1.0i	`"Complex"`
`1[Ui\|ui]`	`"UnsignedGaussian"`
`1i`	`"Gaussian"`
`1.0[Fi\|fi]`	`"Complex32"`

Note The suffix controls the Target Language Compiler type obtained from the constant.

This table shows Target Language Compiler constants and their equivalent MATLAB values.

TLC Constant(s)
Equivalent MATLAB Value

rtInf, Inf, inf
+inf

rtMinusInf
-inf

rtNan, NaN, nan
nan

rtInfi, Infi, infi
inf*i

rtMinusInfi
-inf*i

rtNaNi, NaNi, nani
nan*i

TLC Constant(s)	Equivalent MATLAB Value
`rtInf`, `Inf`, `inf`	`+inf`
`rtMinusInf`	`-inf`
`rtNan`, `NaN`, `nan`	`nan`
`rtInfi,` `Infi`, `infi`	`inf*i`
`rtMinusInfi`	`-inf*i`
`rtNaNi`, `NaNi`, `nani`	`nan*i`

Asserts, Errors, Warnings, and Debug Messages TLC Reserved Constants