qc_perform_substitutions :: QUARC MATLAB Functions

navigation bar

qc_perform_substitutions

Substitutes for standard QUARC format specifiers in a string.

Syntax

text = qc_perform_substitutions(format_string)                           % Use the active configuration of the current model for substitutions
text = qc_perform_substitutions(block, format_string)                    % Use the block to determine the active configuration for substitutions
text = qc_perform_substitutions(model, format_string)                    % Use the model to determine the active configuration for substitutions
text = qc_perform_substitutions(config_set, format_string)               % Use the given configuration for substitutions. Restrict output to given class.
text = qc_perform_substitutions(format_string, restriction)              % Use the active configuration of the current model for substitutions. Restrict output to given class.
text = qc_perform_substitutions(block, format_string, restriction)       % Use the block to determine the active configuration for substitutions. Restrict output to given class.
text = qc_perform_substitutions(model, format_string, restriction)       % Use the model to determine the active configuration for substitutions. Restrict output to given class.
text = qc_perform_substitutions(config_set, format_string, restriction)  % Use the given configuration for substitutions

Description

Returns the format string after substituting for format specifiers. The following format specifiers are recognized and replaced with the appropriate values:

Format Specifier	Description
%d	the current Matlab directory in quotes e.g. "C:\Documents and Settings\myname\My Documents\MATLAB"
%D	the current Matlab directory using short filenames (PC) or escaped spaces (UNIX) e.g. "C:\Docume~1\myname\MyDocu~1\MATLAB" (requires Simulink Coder)
%m	the model name e.g. mymodel
%u	the model URI e.g. tcpip://localhost:17001?nagle='no'
%s	the scheme from the model URI e.g. tcpip
%h	the hostname from the model URI e.g. localhost
%p	the port from the model URI (not usually used) e.g. 17001
%P	the path from the model URI i.e. the portion following the '/' after the hostname and port (not usually used)
%a	the authority from the model URI and any path separator e.g. '//hostname:port/', if present
%o	the options from the model URI i.e. the portion following the '?' after the path (not usually used)
%f	the fragment from the model URI i.e. the portion following the '#' (not usually used)
%q	replaced with a double quote (since MATLAB does not accept double quote characters)
%t	the target type for the given model or configuration set (e.g. windows, qnx_x86, etc.)
%%	replaced with a single percent sign
%(var)	the value of environment variable 'var' (on the host!) e.g. %(PATH)
%{expr}	the value of a MATLAB expression e.g. %{x + 1}

The current MATLAB directory specifiers, %d or %D, are particularly useful in the model arguments, where %d is employed by default to set the current working directory of the model.

The model name and specifiers revolving around the model URI are generally used when specifying the target URI, since the model URI and the target URI should refer to the same target machine. See qc_set_default_target_uri for details.

The environment variable specifier is convenient for accessing the user's home directory, for example, by using the format specifier %(HOME).

The ability to substitute a MATLAB expression is useful in many instances. For example, the filename parameter of the To Host File allows format specifiers to be used so that the date and/or time may be embedded in the filename of the data file. Some particularly useful expressions are:

Expression	Description
%{date}	the current date. See date.
%{time}	the current time. See time.
%{datestr(now,format)}	the date or time in a particular format. See datestr for valid formats.
%{instance(3)}	an instance count, incremented every time the substitution is performed. See instance.
%{qc_get_step_size}	the step size (sampling period) of the model in seconds
%{1/qc_get_step_size}	the sampling frequency of the model in Hz
%{Kp}	the value of MATLAB variable, Kp

Sometimes substitutions add unwanted characters. For example, the format string "data_%{time}.mat" would form a filename containing the time, but unfortunately the time function returns a time of the form "hh:mm:ss". The colon is generally not acceptable in a filename. In this case, the restriction argument may be used to modify the output such that it is an acceptable filename.

Valid values for the restriction argument are 'file', 'variable' and 'uri'. Passing 'file' as the restriction causes the output to be coerced into a valid file name. It may still include path components. For example:

            f = qc_perform_substitutions('data_%{time}.mat', 'file'); % Results in data_10-35-29.mat, even though %{time} is '10:35:29'

Passing 'variable' as the restriction coerces the output to be a valid variable name. The output may be truncated to the length returned by namelengthmax.

Passing 'uri' as the restriction coerces the output to be a valid URI, if possible.

When substitutions are allowed within a block parameter, the block will do such character replacements automatically. For example, the To Host File block does these replacements for its filename and variable name parameters, which allow format specifiers.

Parameters

format_string

A string containing the format specifiers. eg. 'data_%{date}.mat'.

block

A string containing the path of a block or handle of a block within the model. The model containing the block is used to determine the active configuration for substitutions involving the model URI or components of it.

model

A string containing the name of a model. The model is used to determine the active configuration for substitutions involving the model URI or components of it.

config_set

A Simulink.ConfigSet configuration set used to find the substitution values (see getConfigSet). The configuration set is used for substitutions involving the model URI or components of it.

restriction

A string restricting the output to a certain class. Valid values are currently 'file', 'variable' and 'uri'. Setting this argument to 'file' ensures that the output is a valid filename. Passing 'variable' for this argument (including the single quotes) results in a valid variable name at the output. Setting this argument to 'uri' results in a valid URI at the output (if possible).

Outputs

text

The format string after substituting for the format specifiers.

Examples

text = qc_perform_substitutions('shmem://%m:2', 'uri');      % Substitute for the model name e.g. "shmem://mymodel:2"
text = qc_perform_substitutions('data_%{date}.mat', 'file'); % Substitute for the current time e.g. "data_11-Jun-2010.mat"