%% text

Single-line comment where text is the comment.

/% text%/

Single (or multiline) comment where text is the comment.

%matlab

Calls a MATLAB function that does not return a result. For example, %matlab disp(2.718).

%<expr>

Target language expressions that are evaluated. For example, if you have a TLC variable that was created via %assign varName = "foo", then %<varName> would expand to foo. Expressions can also be function calls, as in %<FcnName(param1,param2)>. On directive lines, TLC expressions need not be placed within the %<> syntax. Doing so causes a double evaluation. For example, %if %<x> == 3 is processed by creating a hidden variable for the evaluated value of the variable x. The %if statement then evaluates this hidden variable and compares it against 3. The efficient way to do this operation is to write %if x == 3. In MATLAB notation, this would equate to writing if eval('x') == 3 as opposed to if x = 3. The exception to this is during an %assign for format control, as in

 %assign str = "value is: %<var>"

Note: Nested evaluation expressions (e.g., %<foo(%<expr>)> ) are not supported.

There is not a speed penalty for evaluations inside strings, such as

%assign x = "%<expr>"

Avoid evaluations outside strings, such as the following example.

%assign x = %<expr>

%if expr
%elseif expr
%else
%endif

Conditional inclusion, where the constant expression expr must evaluate to an integer. For example, the following code checks whether a parameter, k, has the numeric value 0.0 by executing a TLC library function to check for equality.

%if ISEQUAL(k, 0.0)
  <text and directives to be processed if k is 0.0>
%endif

In this and other directives, you do not have to expand variables or expressions using the %<expr> notation unless expr appears within a string. For example,

%if ISEQUAL(idx, "my_idx%<i>"), where idx and i are both strings.

As in other languages, logical evaluations do short-circuit (are halted when the result is known).

%switch expr
  %case expr
  %break
  %default
  %break
%endswitch

The %switch directive is similar to the C language switch statement. The expression expr should be of a type that can be compared for equality using the == operator. If the %break is not included after a %case statement, then it will fall through to the next statement.

%with
%endwith

%with recordName is a scoping operator. Use it to bring the named record into the current scope, to remain until the matching %endwith is encountered (%with directives can be nested as desired).

Note that on the left side of %assign statements contained within a %with / %endwith block, references to fields of records must be fully qualified (see Assign Values to Fields of Records), as in the following example.

%with CompiledModel
	 %assign oldName = name
	 %assign CompiledModel.name = "newname"
 	%endwith

%setcommandswitch string

Changes the value of a command-line switch as specified by the argument string. Only the following switches are supported:

v, m, p, O, d, r, I, a

The following example sets the verbosity level to 1.

%setcommandswitch "-v1"

See also Command-Line Arguments.

%assert expr

Tests a value of a Boolean expression. If the expression evaluates to false, TLC issues an error message, a stack trace and exit; otherwise, the execution continues normally. To enable the evaluation of assertions outside the code generator environment, use the command-line option -da. When building from within the code generator, this flag is ignored, as it is superseded by the Enable TLC assertion check box in the Advanced parameters section of the Code Generation pane. To control assertion handling from the MATLAB Command Window, use

set_param(model, 'TLCAssertion', 'on|off')

to set this flag on or off. Default is Off. To see the current setting, use

get_param(model, 'TLCAssertion')

%error
%warning
%trace
%exit

Flow control directives:

When reporting errors, use the following command if the error is produced by an incorrect configuration that the user needs to fix in the model.

%exit Error Message

If you are adding assert code (that is, code that should never be reached), use

%setcommandswitch "-v1" %% force TLC stack trace 
%exit Assert message

%assign

Creates identifiers (variables). The general form is

%assign [::]variable = expression 

The :: specifies that the variable being created is a global variable; otherwise, it is a local variable in the current scope (i.e., a local variable in the function).

If you need to format the variable, say, within a string based upon other TLC variables, then you should perform a double evaluation, as in

%assign nameInfo = "The name of this is %<Name>"

or alternately

%assign nameInfo = "The name of this is " + Name

To assign a value to a field of a record, you must use a qualified variable expression. See Assign Values to Fields of Records.

%createrecord

Creates records in memory. This command accepts a list of one or more record specifications (e.g., { foo 27 }). Each record specification contains a list of zero or more name-value pairs (e.g., foo 27) that become the members of the record being created. The values themselves can be record specifications, as the following illustrates.

%createrecord NEW_RECORD { foo 1 ; SUB_RECORD {foo 2} }
%assign x = NEW_RECORD.foo                  /* x = 1 */
%assign y = NEW_RECORD.SUB_RECORD.foo       /* y = 2 */

If more than one record specification follows a given record name, the set of record specifications constitutes an array of records.

%createrecord RECORD_ARRAY { foo 1 } ...
							        { foo 2 } ...
							        { bar 3 } 
%assign x = RECORD_ARRAY[1].foo             /* x = 2 */
%assign y = RECORD_ARRAY[2].bar             /* y = 3 */

Note that you can create and index arrays of subrecords by specifying %createrecord with identically named subrecords, as follows:

%createrecord RECORD_ARRAY { SUB_RECORD { foo 1 } ... 
                             SUB_RECORD { foo 2 } ... 
                             SUB_RECORD { foo 3 } }
%assign x = RECORD_ARRAY.SUB_RECORD[1].foo  /* x = 2 */
%assign y = RECORD_ARRAY.SUB_RECORD[2].foo  /* y = 3 */

If the scope resolution operator (::) is the first token after the %createrecord token, the record is created in the global scope.

%addtorecord

Adds fields to an existing record. The new fields can be name-value pairs or aliases to already existing records.

%addtorecord OLD_RECORD foo 1

If the new field being added is a record, then %addtorecord makes an alias to that record instead of a deep copy. To make a deep copy, use %copyrecord.

%createrecord NEW_RECORD { foo 1 }
%addtorecord OLD_RECORD NEW_RECORD_ALIAS NEW_RECORD

%mergerecord

Adds (or merges) one or more records into another. The first record will contain the results of the merge of the first record plus the contents of the other records specified by the command. The contents of the second (and subsequent) records are deep copied into the first (i.e., they are not references).

%mergerecord OLD_RECORD NEW_RECORD

If duplicate fields exist in the records being merged, the original record’s fields are not overwritten.

%copyrecord

Makes a deep copy of an existing record. It creates a new record in a similar fashion to %createrecord except the components of the record are deep copied from the existing record. Aliases are replaced by copies.

%copyrecord NEW_RECORD OLD_RECORD

%realformat

Specifies how to format real variables. To format in exponential notation with 16 digits of precision, use

%realformat "EXPONENTIAL"

To format without loss of precision and minimal number of characters, use

%realformat "CONCISE"

When inlining S-functions, the format is set to concise. You can switch to exponential, but should switch it back to concise when done.

%language

This must appear before the first GENERATE or GENERATE_TYPE function call. This specifies the name of the language as a string, which is being generated as in %language "C". Generally, this is added to your system target file.

The only valid value is C which enables support for C and C++ code generation as specified by the configuration parameter TargetLang (see Language for more information).

%implements

Placed within the .tlc file for a specific record type, when mapped via %generatefile. The syntax is %implements "Type" "Language". When inlining an S-function in C or C++, this should be the first noncomment line in the file, as in

%implements "s_function_name" "C"

The next noncomment lines will be %function directives specifying the functionality of the S-function.

See the %language and GENERATE function descriptions for further information.

%generatefile

Provides a mapping between a record Type and functions contained in a file. Each record can have functions of the same name but different contents mapped to it (i.e., polymorphism). Generally, this is used to map a Block record Type to the .tlc file that implements the functionality of the block, as in

%generatefile "Sin" "sin_wave.tlc"

%filescope

Limits the scope of variables to the file in which they are defined. A %filescope directive anywhere in a file declares that variables in the file are visible only within that file. Note that this limitation also applies to files inserted, via the %include directive, into the file containing the %filescope directive.

You should not use the %filescope directive within functions or GENERATE functions.

%filescope is useful in conserving memory. Variables whose scope is limited by %filescope go out of scope when execution of the file containing them completes. This frees memory allocated to such variables. By contrast, global variables persist in memory throughout execution of the program.

%include

Use %include "file.tlc"to insert the specified target file at the current point.

The %include directives behave as if they were in a global context. For example,

%addincludepath "./sub1"
%addincludepath "./sub2"

in a .tlc file enables either subfolder to be referenced implicitly:

%include "file_in_sub1.tlc"
%include "file_in_sub2.tlc"

Use forward slashes for folder names, as they work on both UNIX^® and PC systems. However, if you do use back slashes in PC folder names, be sure to escape them, e.g., "C:\\mytlc". Alternatively, you can express a PC folder name as a literal using the L format specifier, as in L"C:\mytlc".

%addincludepath

Use %addincludepath "folder" to add additional paths to be searched. Multiple %addincludepath directives can appear. The compiler evaluates multiple %addincludepath directives from the bottom up.

Using %addincludepath directives establishes a global context. For example,

%addincludepath "./sub1"
%addincludepath "./sub2"

in a .tlc file enables either subfolder to be referenced implicitly:

%include "file_in_sub1.tlc"
%include "file_in_sub2.tlc"

Use forward slashes for folder names, as they work on both UNIX and PC systems. However, if you do use back slashes in PC folder names, be sure to escape them, e.g., "C:\\mytlc". Alternatively, you can express a PC folder name as a literal using the L format specifier, as in L"C:\mytlc".

%roll
%endroll

Multiple inclusion plus intrinsic loop rolling based upon a specified threshold. This directive can be used by most Simulink^® blocks that have the concept of an overall block width that is usually the width of the signal passing through the block.

This example of the %roll directive is for a gain operation, y=u*k:

%function Outputs(block, system) Output
  /* %<Type> Block: %<Name> */
  %assign rollVars = ["U", "Y", "P"]
  %roll sigIdx = RollRegions, lcv = RollThreshold, block,... 
        "Roller", rollVars
    %assign y = LibBlockOutputSignal(0, "", lcv, sigIdx)
    %assign u = LibBlockInputSignal(0, "", lcv, sigIdx)
    %assign k = LibBlockParameter(Gain, "", lcv, sigIdx)
      %<y> = %<u> * %<k>;
  %endroll
%endfunction

The %roll directive is similar to %foreach, except that it iterates the identifier (sigIdx in this example) over roll regions. Roll regions are computed by looking at the input signals and generating regions where the inputs are contiguous. For blocks, the variable RollRegions is automatically computed and placed in the Block record. An example of a roll regions vector is [0:19, 20:39], where there are two contiguous ranges of signals passing through the block. The first is 0:19 and the second is 20:39. Each roll region is either placed in a loop body (e.g., the C language for statement) or inlined, depending upon whether or not the length of the region is less than the roll threshold.

Each time through the %roll loop, sigIdx is an integer for the start of the current roll region or an offset relative to the overall block width when the current roll region is less than the roll threshold. The TLC global variable RollThreshold is the general model-wide value used to decide when to place a given roll region in a loop. When the decision is made to place a given region in a loop, the loop control variable is a valid identifier (e.g., "i"); otherwise it is "".

The block parameter is the current block that is being rolled. The "Roller" parameter specifies the name for internal GENERATE_TYPE calls made by %roll. The default %roll handler is "Roller", which is responsible for setting up the default block loop rolling structures (e.g., a C for loop).

The rollVars (roll variables) are passed to "Roller" functions to create roll structures. The defined loop variables relative to a block are

To roll your own vector based upon the block’s roll regions, you need to walk a pointer to your vector. Assuming your vector is pointed to by the first PWork, called name,

datatype *buf = (datatype*)%<LibBlockPWork(name,"","",0)
%roll sigIdx = RollRegions, lcv = RollThreshold, block, ...
      "Roller", rollVars
  *buf++ = whatever;
%endroll

Note: In the above example, sigIdx and lcv are local to the body of the loop.

%breakpoint

Sets a breakpoint for the TLC debugger. See %breakpoint Directive.

%function
%return
%endfunction

A function that returns a value is defined as

%function name(optional-arguments) 
    %return value 
  %endfunction

A void function does not produce output and is not required to return a value. It is defined as

%function name(optional-arguments) void 
  %endfunction

A function that produces outputs to the current stream and is not required to return a value is defined as

%function name(optional-arguments) Output 
  %endfunction

For block target files, you can add to your inlined .tlc file the following functions that are called by the model-wide target files during code generation.

%foreach
%endforeach

Multiple inclusion that iterates from 0 to the upperLimit-1 constant integer expression. Each time through the loop, the loopIdentifier, (e.g., x) is assigned the current iteration value.

%foreach loopIdentifier = upperLimit 
   %break -- use this to exit the loop 
   %continue -- use this to skip the following code and  
                continue to the next iteration 
%endforeach

Note: The upperLimit expression is cast to a TLC integer value. The loopIdentifier is local to the loop body.

%for

Multiple inclusion directive with syntax

%for ident1 = const-exp1, const-exp2, ident2 = const-exp3
  %body
    %break
    %continue
  %endbody
%endfor

The first portion of the %for directive is identical to the %foreach statement. The %break and %continue directives act the same as they do in the %foreach directive. const-exp2 is a Boolean expression that indicates whether the loop should be rolled (see %roll above).

If const-exp2 evaluates to TRUE, ident2 is assigned the value of const-exp3. Otherwise, ident2 is assigned an empty string.

Note: ident1 and ident2 above are local to the loop body.

%openfile
%selectfile
%closefile

These are used to manage the files that are created. The syntax is

%openfile streamId="filename.ext" mode  {open for writing} 
%selectfile streamId                    {select an open file} 
%closefile streamId                     {close an open file}

Note that the "filename.ext" is optional. If a filename is not specified, a variable (string buffer) named streamId is created containing the output. The mode argument is optional. If specified, it can be "a" for appending or "w" for writing.

Note that the special string streamIdNULL_FILE specifies no output. The special string streamIdSTDOUT specifies output to the terminal.

To create a buffer of text, use

%openfile buffer
text to be placed in the 'buffer' variable.
%closefile buffer

Now buffer contains the expanded text specified between the %openfile and %closefile directives.

%generate

%generate blk fn is equivalent to GENERATE(blk,fn).

%generate blk fn type is equivalent to GENERATE(blk,fn,type).

See GENERATE and GENERATE_TYPE Functions.

%undef

%undef var removes the variable var from scope. If var is a field in a record, %undef removes that field from the record. If var is a record array, %undef removes the entire record array.

TLC Data Promotions

When the Target Language Compiler operates on mixed types of expressions, it promotes the results to the common types indicated in the following table.

The table uses the following abbreviations:

The top row (in bold) and first column (in bold) show the types of expression used in the operation. The intersection of the row and column shows the resulting type of expressions.

For example, if the operation involves a Boolean expression (B) and an unsigned expression (U), the result will be an unsigned expression (U).

%if

The constant-expression must evaluate to an integer expression. It controls the inclusion of the following lines until it encounters an %else, %elseif, or %endif directive. If the constant-expression evaluates to 0, the lines following the directive are not included. If the constant-expression evaluates to an integer value other than 0, the lines following the %if directive are included until the %endif, %elseif, or %else directive.

When the compiler encounters an %elseif directive, and no prior %if or %elseif directive has evaluated to nonzero, the compiler evaluates the expression. If the value is 0, the lines following the %elseif directive are not included. If the value is nonzero, the lines following the %elseif directive are included until the subsequent %else, %elseif, or %endif directive.

The %else directive begins the inclusion of source text if the previous %elseif statements or the original %if statement evaluates to 0; otherwise, it prevents the inclusion of subsequent lines up to and including the following %endif.

The constant-expression can contain any expression specified in Target Language Expressions.

%switch

The %switch statement evaluates the constant expression and compares it to expressions appearing on %case selectors. If a match is found, the body of the %case is included; otherwise the %default is included.

%case ... %default bodies flow together, as in C, and %break must be used to exit the switch statement. %break exits the nearest enclosing %switch, %foreach, or %for loop in which it appears. For example,

%switch(type)
%case x         
	/* Matches variable x. */
	/* Note: Any valid TLC type is allowed. */
%case "Sin"
	/* Matches Sin or falls through from case x. */
   %break
	/* Exits the switch. */
%case "gain"
	/* Matches gain. */
   %break
%default
	/* Does not match x, "Sin," or "gain." */
%endswitch

In general, this is a more readable form for the %if/%elseif/%else construction.

%foreach

The syntax of the %foreach multiple inclusion directive is

%foreach identifier = constant-expression
   %break
   %continue
%endforeach

The constant-expression must evaluate to an integer expression, which then determines the number of times to execute the foreach loop. The identifier increments from 0 to one less than the specified number. Within the foreach loop, you can use x, where x is the identifier, to access the identifier variable. %break and %continue are optional directives that you can include in the %foreach directive:

%for

The syntax of the %for multiple inclusion directive is

%for ident1 = const-exp1, const-exp2, ident2 = const-exp3
  %body
    %break
    %continue
  %endbody
%endfor

The first portion of the %for directive is identical to the %foreach statement in that it causes a loop to execute from 0 to N-1 times over the body of the loop. In the normal case, it includes only the lines between %body and %endbody, and the lines between the %for and %body, and ignores the lines between %endbody and %endfor.

The %break and %continue directives act the same as they do in the %foreach directive.

const-exp2 is a Boolean expression that indicates whether the loop should be rolled. If const-exp2 is true, ident2 receives the value of const-exp3; otherwise it receives the null string. When the loop is rolled, the lines between the %for and the %endfor are included in the output exactly one time. ident2 specifies the identifier to be used for testing whether the loop was rolled within the body. For example,

%for Index = <NumNonVirtualSubsystems>3, rollvar="i"

    {
        int i;

        for (i=0; i< %<NumNonVirtualSubsystems>; i++)
        {
          %body
	x[%<rollvar>] = system_name[%<rollvar>];
          %endbody

        }
    }
%endfor

If the number of nonvirtual subsystems (NumNonVirtualSubsystems) is greater than or equal to 3, the loop is rolled, causing the code within the loop to be generated exactly once. In this case, Index = 0.

If the loop is not rolled, the text before and after the body of the loop is ignored and the body is generated NumNonVirtualSubsystems times.

This mechanism gives each individual loop control over whether or not it should be rolled.

%roll

The syntax of the %roll multiple inclusion directive is

%roll ident1 = roll-vector-exp, ident2 = threshold-exp, ... 
               block-exp [, type-string [,exp-list] ]
  %break
  %continue
%endroll

This statement uses the roll-vector-exp to expand the body of the %roll statement multiple times as in the %foreach statement. If a range is provided in the roll-vector-expand that range is larger than the threshold-exp expression, the loop will roll. When a loop rolls, the body of the loop is expanded once and the identifier (ident2) provided for the threshold expression is set to the name of the loop control variable. If no range is larger than the specified rolling threshold, this statement is identical to the %foreach statement. For example,

%roll Idx = [ 1 2 3:5, 6, 7:10 ], lcv = 10, ablock
%endroll

In this case, the body of the %roll statement expands 10 times, as in the %foreach statement, because there are no regions greater than or equal to 10. Idx counts from 1 to 10, and lcv is set to the null string, "".

When the Target Language Compiler determines that a given block will roll, it performs a GENERATE_TYPE function call to output the various pieces of the loop (other than the body). The default type used is Roller; you can override this type with a string that you specify. Extra arguments passed to the %roll statement are provided as arguments to these special-purpose functions. The called function is one of these four functions:

RollHeader(block, ...).  This function is called once on the first section of this roll vector that will actually roll. It should return a string that is assigned to the lcv within the body of the %roll statement.

LoopHeader(block, StartIdx, Niterations, Nrolled, ...).  This function is called once for each section that will roll prior to the body of the %roll statement.

LoopTrailer(block, Startidx, Niterations, Nrolled, ...).  This function is called once for each section that will roll after the body of the %roll statement.

RollTrailer(block, ...).  This function is called once at the end of the %roll statement if any of the ranges caused loop rolling.

These functions should output language-specific declarations, loop code, and so on as required to generate code for the loop.

An example of a Roller.tlc file is

%implements Roller "C"
%function RollHeader(block) Output
	{
		int i;
	%return ("i")
%endfunction
%function LoopHeader(block,StartIdx,Niterations,Nrolled) Output
 	for (i = %<StartIdx>; i < %<Niterations+StartIdx>; i++)
	{
%endfunction
%function LoopTrailer(block,StartIdx,Niterations,Nrolled) Output
	}
%endfunction
%function RollTrailer(block) Output
	}
%endfunction

Extending the former example to a loop that rolls,

%language "C"
%assign ablock = BLOCK { Name "Hi" }
%roll Idx = [ 1:20, 21, 22, 23:25, 26:46], lcv = 10, ablock
	Block[%< lcv == "" ? Idx : lcv>] *= 3.0;
%endroll

This Target Language Compiler code produces this output:

{
	int             i;
	for (i = 1; i < 21; i++)
	{
	    Block[i] *= 3.0;
	}
	Block[21] *= 3.0;
	Block[22] *= 3.0;
	Block[23] *= 3.0;
	Block[24] *= 3.0;
	Block[25] *= 3.0;
	for (i = 26; i < 47; i++)
	{
	    Block[i] *= 3.0;
	}
}

%language

The %language directive specifies the target language being generated. It is required as a consistency check to verify the implementation files found for the language being generated. The %language directive must appear prior to the first GENERATE or GENERATE_TYPE built-in function call. %language specifies the language as a string. For example:

%language "C"

Simulink blocks have a Type parameter. This parameter is a string that specifies the type of the block, for example "Sin" or "Gain". The object-oriented facility uses this type to search the path for a file that implements the block. By default the name of the file is the Type of the block with .tlc appended, so for example, if the Type is "Sin" the Compiler would search for "Sin.tlc" along the path. You can override this default filename using the %generatefile directive to specify the filename that you want to use to replace the default filename. For example,

%generatefile "Sin" "sin_wave.tlc"

The files that implement the block-specific code must contain an %implements directive indicating both the type and the language being implemented. The Target Language Compiler will produce an error if the %implements directive does not match as expected. For example,

%implements "Sin" "Pascal"

causes an error if the initial language choice was C.

You can use a single file to implement more than one target language by specifying the desired languages in a vector. For example,

%implements "Sin" "C"

Finally, you can implement several types using the wildcard (*) for the type field:

%implements * "C"

GENERATE and GENERATE_TYPE Functions

The Target Language Compiler has two built-in functions that dispatch object-oriented calls, GENERATE and GENERATE_TYPE. You can call a function appearing in an implementation file (from outside the specified file) only by using the GENERATE and GENERATE_TYPE special functions.

GENERATE.  The GENERATE function takes two or more input arguments. The first argument must be a valid scope and the second a string containing the name of the function to call. The GENERATE function passes the first block argument and any additional arguments specified to the function being called. The return argument is the value, if any, returned from the function being called. Note that the compiler automatically “scopes” or adds the first argument to the list of scopes searched as if it appears on a %with directive line. (See Variable Scoping.) This scope is removed when the function returns.

GENERATE_TYPE.  The GENERATE_TYPE function takes three or more input arguments. It handles the first two arguments identically to the GENERATE function call. The third argument is the type; the type specified in the Simulink block is ignored. This facility is used to handle S-function code generation by the build process. That is, the block type is S-function, but the Target Language Compiler generates it as the specific S-function specified by GENERATE_TYPE. For example,

GENERATE_TYPE(block, "Output", "dp_read")

specifies that S-function block is of type dp_read.

The block argument and any additional arguments are passed to the function being called. Like the GENERATE built-in function, the compiler automatically scopes the first argument before the GENERATE_TYPE function is entered and then removes the scope on return.

Within the file containing %implements, function calls are looked up first within the file and then in the global scope. This makes it possible to have hidden helper functions used exclusively by the current object.

%openfile

The %openfile directive opens a file or buffer for writing; the required string variable becomes a variable of type file. For example,

%openfile x               /% Opens and selects x for writing. %/
%openfile out = "out.h"   /% Opens "out.h" for writing. %/

%selectfile

The %selectfile directive selects the file specified by the variable as the current output stream. Output goes to that file until another file is selected using %selectfile. For example,

%selectfile x               /% Select file x for output. %/

%closefile

The %closefile directive closes the specified file or buffer. If the closed entity is the currently selected output stream, %closefile invokes %selectfile to reselect the previously selected output stream.

There are two possible cases that %closefile must handle:

If desired, you can append to an output file or string by using the optional mode, a, as in

%openfile "foo.c", "a"             %% Opens foo.c for appending.

%include

The %include directive searches the path for the target file specified by string and includes the contents of the file inline at the point where the %include statement appears.

%addincludepath

The %addincludepath directive adds an additional include path to be searched when the Target Language Compiler references %include or block target files. The syntax is

%addincludepath string

The string can be an absolute path or an explicit relative path. For example, to specify an absolute path, use

%addincludepath "C:\\folder1\\folder2"     (PC)
%addincludepath "/folder1/folder2"         (UNIX)

To specify a relative path, the path must explicitly start with .. For example,

%addincludepath ".\\folder2"                  (PC)
%addincludepath "./folder2"                   (UNIX)

Note that for PC, the backslashes must be escaped (doubled).

When an explicit relative path is specified, the folder that is added to the Target Language Compiler search path is created by concatenating the location of the target file that contains the %addincludepath directive and the explicit relative path.

The Target Language Compiler searches the folders in the following order for target or include files:

Typically, %addincludepath directives should be specified in your system target file. Multiple %addincludepath directives will add multiple paths to the Target Language Compiler search path.

FEVAL Function

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

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

This table shows the conversions that are made when you use FEVAL.

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

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.

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

Creating Records

Use the %createrecord directive to build new records in the current scope. For example, if you want to create a new record called Rec that contains two items (e.g., Name "Name" and Type "t"), use

%createrecord Rec {  Name "Name"; Type "t" }

Adding Records

Use the %addtorecord directive to add new records to existing records. For example, if you have a record called Rec1 that contains a record called Rec2, and you want to add an additional Rec2 to it, use

%addtorecord Rec1 Rec2 {  Name "Name1"; Type "t1" }

This figure shows the result of adding the record to the existing one.

If you want to access the new record, you can use

%assign myname = Rec1.Rec2[1].Name

In this same example, if you want to add two records to the existing record, use

%addtorecord Rec1 Rec2 {  Name "Name1"; Type "t1" }
%addtorecord Rec1 Rec2 {  Name "Name2"; Type "t2" }

This produces

Adding Parameters to an Existing Record

You can use the %assign directive to add a new parameter to an existing record. For example,

%addtorecord Block[Idx] N 500 /% Adds N with value 500 to Block %/
%assign myn = Block[Idx].N    /% Gets the value 500 %/

adds a new parameter, N, at the end of an existing block with the name and current value of an existing variable, as shown in this figure. It returns the block value.

Scopes

The following sections describe the possible scopes that a TLC variable can have.

Global Scope.  By default, TLC variables have global scope. Global variables are visible to, and can be referenced by, code anywhere in a TLC program. Global variables persist throughout the execution of the TLC program. Global variables are said to belong to the global pool.

Note that the CompiledModel record of the model.rtw file has global scope. Therefore, you can access this structure from your TLC functions or files.

You can use the scope resolution operator (::) to explicitly reference or create global variables from within a function. See The Scope Resolution Operator for examples.

Note that you can use the %undef directive to free memory used by global variables.

File Scope.  Variables with file scope are visible only within the file in which they are created. To limit the scope of variables in this way, use the %filescope directive anywhere in the defining file.

In the following code fragment, the variables fs1 and fs2 have file scope. Note that the %filescope directive does not have to be positioned before the statements that create the variables.

%assign fs1 = 1
%filescope
%assign fs2 = 3

Variables whose scope is limited by %filescope go out of scope when execution of the file containing them completes. This lets you free memory allocated to such variables.

Function (Local) Scope.  Variables defined within the body of a function have function scope. That is, they are visible within and local to the defining function. For example, in the following code fragment, the variable localv is local to the function foo. The variable x is global.

%assign x = 3

%function foo(arg)
   %assign localv = 1
   %return x + localv
%endfunction

A local variable can have the same name as a global variable. To refer, within a function, to identically named local and global variables, you must use the scope resolution operator (::) to disambiguate the variable references. See The Scope Resolution Operator for examples.

%with Scope.  The %with directive adds a new scope, referred to as a %with scope, to the current list of scopes. This directive makes it easier to refer to block-scoped variables.

The structure of the %with directive is

%with expression
%endwith

For example, the directive

%with CompiledModel.System[sysidx]
   ...
%endwith

adds the CompiledModel.System[sysidx] scope to the search list. This scope is searched before anything else. You can then refer to the system name simply by

Name

instead of

CompiledModel.System[sysidx].Name

Generate Scope.  Generate scope is a special scope used by certain built-in functions that are designed to support code generation. These functions dispatch function calls that are mapped to a specific record type. This capability supports a type of polymorphism in which different record types are associated with functions (analogous to methods) of the same name. Typically, this feature is used to map Block records to functions that implement the functionality of different block types.

Functions that employ generate scope include GENERATE, GENERATE_TYPE, GENERATE_FUNCTION_EXISTS, and GENERATE_TYPE_FUNCTION_EXISTS. See GENERATE and GENERATE_TYPE Functions. This section discusses generate scope using the GENERATE built-in function as an example.

The syntax of the GENERATE function is

GENERATE(blk,fn)

The first argument (blk) to GENERATE is a valid record name. The second argument (fn) is the name of a function to be dispatched. When a function is dispatched through a GENERATE call, TLC automatically adds blk to the list of scopes that is searched when variable references are resolved. Thus the record (blk) is visible to the dispatched function as if an implicit %with <blk>... %endwith directive existed in the dispatched function.

In this context, the record named blk is said to be in generate scope.

Three TLC files, illustrating the use of generate scope, are listed below. The file polymorph.tlc creates two records representing two hypothetical block types, MyBlock and YourBlock. Each record type has an associated function named aFunc. The block-specific implementations of aFunc are contained in the files MyBlock.tlc and YourBlock.tlc.

Using GENERATE calls, polymorph.tlc dispatches to a function for each block type. Notice that the aFunc implementations can refer to the fields of MyBlock and YourBlock, because these records are in generate scope.

The invocation and output of polymorph.tlc, as displayed in the MATLAB Command Window, are shown below:

tlc -v polymorph.tlc

The value of MyRecord.data is: 123
The value of YourRecord.theStuff is: 666

The Scope Resolution Operator

The scope resolution operator (::) is used to indicate that the global scope should be searched when a TLC function looks up a variable reference. The scope resolution operator is often used to change the value of global variables (or even create global variables) from within functions.

By using the scope resolution operator, you can resolve ambiguities that arise when a function references identically named local and global variables. In the following example, a global variable foo is created. In addition, the function myfunc creates and initializes a local variable named foo. The function myfunc explicitly references the global variable foo by using the scope resolution operator.

%assign foo = 3   %% this variable has global scope
.
.
.
%function myfunc(arg)
   %assign foo = 3   %% this variable has local scope
   %assign ::foo = arg   %% this changes the global variable foo
%endfunction

You can also use the scope resolution operator within a function to create global variables. The following function creates and initializes a global variable:

%function sideffect(arg)
   %assign ::theglobal = arg   %% this creates a global variable
%endfunction

How TLC Resolves Variable References

This section discusses how the Target Language Compiler searches the existing scopes to resolve variable references.

Global Scope.  In the simplest case, the Target Language Compiler resolves a variable reference by searching the global pool (including the CompiledModel structure).

%with Scope.  You can modify the search list and search sequence by using the %with directive. For example, when you add the following construct,

%with CompiledModel.System[sysidx]
   ...
%endwith

the System[sysidx] scope is added to the search list. This scope is searched first, as shown by this picture.

This technique makes it simpler to access embedded definitions. Using the %with construct (as in the previous example), you can refer to the system name simply by

Name

instead of

CompiledModel.System[sysidx].Name

Function Scope.  A function has its own scope. That scope is added to the previously described search list, as shown in this diagram.

For example, in the following code fragment,

% with CompiledModel.System[sysidx]
...
   %assign a=foo(x,y)
...
%endwith
...
%function foo(a,b)
...
   assign myvar=Name
...
%endfunction
...
%<foo(1,2)>

If Name is not defined in foo, the assignment uses the value of Name from the previous scope, CompiledModel.System[SysIdx].Name.

In a nested function, only the innermost function scope is searched, together with the enclosing %with and global scopes, as shown in the following diagram:

File Scope.  File scopes are searched before the global scope, as shown in the following diagram.

The rule for nested file scopes is similar to that for nested function scopes. In the case of nested file scopes, only the innermost nested file scope is searched.

Variable Scoping Within Functions

Within a function, the left-hand member of an %assign statement defaults to creating a local variable. A new entry is created in the function’s block within the scope chain; it does not affect the other entries. An example appears in Function Scope.

You can override this default behavior by using %assign with the scope resolution operator (::).

When you introduce new scopes within a function, using %with, these new scopes are used during nested function calls, but the local scope for the function is not searched.

If a %with is included within a function, its associated scope is carried with nested function calls, as shown in the next figure.

%return

The %return statement closes all %with statements appearing within the current function. In this example, the %with statement is automatically closed when the %return statement is encountered, removing the scope from the list of searched scopes:

%function foo(s)
    %with s
        %return(name)
    %endwith
%endfunction

The %return statement does not require a value. You can use %return to return from a function without a return value.