padv.builtin.query.FindFileWithAddress Class

Namespace: padv.builtin.query
Superclasses: padv.Query

Query for finding file with address

Description

This class requires CI/CD Automation for Simulink Check.

The padv.builtin.query.FindFileWithAddress class provides a query that can return the file at the specified address in the project. You can specify additional settings by using the optional name-value arguments.

You can use this query in your process model to find artifacts for your tasks to iterate over or use as inputs. For example, you can use this query to find a Model Advisor configuration file to use with the built-in task padv.builtin.task.RunModelStandards.

The padv.builtin.query.FindFileWithAddress class is a handle class.

Creation

Description

q = padv.builtin.query.FindFileWithAddress(Type = ArtifactType,Path = FilePath) finds a file, of type ArtifactType, at the address specified by FilePath.

q = padv.builtin.query.FindFileWithAddress(___,Name=Value) finds and returns a file using the settings specified by one or more name-value arguments. For example, if you do not want the build system to track changes to the returned file, specify TrackArtifacts=false.

The padv.builtin.query.FindFileWithAddress class also has other properties, but you cannot set those properties during query creation.

Input Arguments

ArtifactType — Type of artifact

"padv_output_file" (default) | "ma_config_file" | "m_file" | ...

Type of artifact, specified as one or more of the values in this table. To specify multiple values, use an array.

Category	Artifact Type	Description
MATLAB®	"m_class"	MATLAB class
	"m_file"	MATLAB file
	"m_func"	MATLAB function
	"m_method"	MATLAB class method
	"m_property"	MATLAB class property
Model Advisor	"ma_config_file"	Model Advisor configuration file
	"ma_justification_file"	Model Advisor justification file
Process Advisor	"padv_dep_artifacts"	Related artifacts that current artifact depends on
	"padv_output_file"	Process Advisor output file
Project	"project"	Current project file
Requirements	"mwreq_file"	Requirement file (since R2024b)
	"mwreq_item"	Requirement (since R2024b)
	"sl_req"	Requirement (for R2024a and earlier)
	"sl_req_file"	Requirement file (for R2024a and earlier)
	"sl_req_table"	Requirements Table
Stateflow®	"sf_chart"	Stateflow chart
	"sf_graphical_fcn"	Stateflow graphical function
	"sf_group"	Stateflow group
	"sf_state"	Stateflow state
	"sf_state_transition_chart"	Stateflow state transition chart
	"sf_truth_table"	Stateflow truth table
Simulink®	"sl_block_diagram"	Block diagram
	"sl_data_dictionary_file"	Data dictionary file
	"sl_embedded_matlab_fcn"	MATLAB function
	"sl_block_diagram"	Block diagram
	"sl_library_file"	Library file
	"sl_model_file"	Simulink model file
	"sl_protected_model_file"	Protected Simulink model file
	"sl_subsystem"	Subsystem
	"sl_subsystem_file"	Subsystem file
System Composer™	"zc_block_diagram"	System Composer architecture
	"zc_component"	System Composer architecture component
	"zc_file"	System Composer architecture file
Tests	"harness_info_file"	Harness info file
	"sl_harness_block_diagram"	Harness block diagram
	"sl_harness_file"	Test harness file
	"sl_test_case"	Simulink Test™ case
	"sl_test_case_result"	Simulink Test case result
	"sl_test_file"	Simulink Test file
	"sl_test_iteration"	Simulink Test iteration
	"sl_test_iteration_result"	Simulink Test iteration result
	"sl_test_report_file"	Simulink Test result report
	"sl_test_result_file"	Simulink Test result file
	"sl_test_resultset"	Simulink Test result set
	"sl_test_seq"	Test Sequence
	"sl_test_suite"	Simulink Test suite
	"sl_test_suite_result"	Simulink Test suite result

The Type argument controls the DefaultArtifactType property value.

Example: "ma_config_file"

Example: ["sl_model_file" "m_file"]

FilePath — Path to file

string | character vector | cell array of character vectors

Path to file, specified as a string, a character vector, or a cell array of character vectors.

Example: fullfile("02_Models","AHRS_Voter","specification","AHRS_Voter.slx")

Example: [fullfile("myFiles","myModel.slx"), fullfile("myFiles","myScript.m")]

Data Types: char | string | cell

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: query = padv.builtin.query.FindCodeForModel(Name = "MyCodeQuery")

Name — Unique identifier for query

string

Unique identifier for query, specified as a string.

Example: "FindMyFile"

Data Types: string

Type — Type of artifact

"padv_output_file" (default) | "ma_config_file" | "m_file" | ...

Type of artifact, specified as one or more of the values in this table. To specify multiple values, use an array.

Category	Artifact Type	Description
MATLAB	"m_class"	MATLAB class
	"m_file"	MATLAB file
	"m_func"	MATLAB function
	"m_method"	MATLAB class method
	"m_property"	MATLAB class property
Model Advisor	"ma_config_file"	Model Advisor configuration file
	"ma_justification_file"	Model Advisor justification file
Process Advisor	"padv_dep_artifacts"	Related artifacts that current artifact depends on
	"padv_output_file"	Process Advisor output file
Project	"project"	Current project file
Requirements	"mwreq_file"	Requirement file (since R2024b)
	"mwreq_item"	Requirement (since R2024b)
	"sl_req"	Requirement (for R2024a and earlier)
	"sl_req_file"	Requirement file (for R2024a and earlier)
	"sl_req_table"	Requirements Table
Stateflow	"sf_chart"	Stateflow chart
	"sf_graphical_fcn"	Stateflow graphical function
	"sf_group"	Stateflow group
	"sf_state"	Stateflow state
	"sf_state_transition_chart"	Stateflow state transition chart
	"sf_truth_table"	Stateflow truth table
Simulink	"sl_block_diagram"	Block diagram
	"sl_data_dictionary_file"	Data dictionary file
	"sl_embedded_matlab_fcn"	MATLAB function
	"sl_block_diagram"	Block diagram
	"sl_library_file"	Library file
	"sl_model_file"	Simulink model file
	"sl_protected_model_file"	Protected Simulink model file
	"sl_subsystem"	Subsystem
	"sl_subsystem_file"	Subsystem file
System Composer	"zc_block_diagram"	System Composer architecture
	"zc_component"	System Composer architecture component
	"zc_file"	System Composer architecture file
Tests	"harness_info_file"	Harness info file
	"sl_harness_block_diagram"	Harness block diagram
	"sl_harness_file"	Test harness file
	"sl_test_case"	Simulink Test case
	"sl_test_case_result"	Simulink Test case result
	"sl_test_file"	Simulink Test file
	"sl_test_iteration"	Simulink Test iteration
	"sl_test_iteration_result"	Simulink Test iteration result
	"sl_test_report_file"	Simulink Test result report
	"sl_test_result_file"	Simulink Test result file
	"sl_test_resultset"	Simulink Test result set
	"sl_test_seq"	Test Sequence
	"sl_test_suite"	Simulink Test suite
	"sl_test_suite_result"	Simulink Test suite result

The Type argument controls the DefaultArtifactType property value.

Example: "ma_config_file"

Example: ["sl_model_file" "m_file"]

Path — Path to file

string | character vector | cell array of character vectors

Path to file, specified as a string, a character vector, or a cell array of character vectors.

Example: fullfile("tools","sampleChecks.json")

Example: [fullfile("myFiles","myModel.slx"), fullfile("myFiles","myScript.m")]

Data Types: char | string | cell

ValidateFileExistence — Validate that file exists before returning in query results

1 (true) (default) | 0 (false)

Validate that the file exists before attempting to return the file in the query results, specified as a numeric or logical 1 (true) or 0 (false).

Example: false

Data Types: logical

TrackArtifacts — Setting that controls whether build system tracks changes to file the query returns

1 (true) (default) | 0 (false)

Setting that controls whether the build system tracks changes to the file the query returns, specified as a numeric or logical 1 (true) or 0 (false).

For more information, see Turn Off Change Tracking for File and Exclude Files from Change Tracking in Process Advisor.

Note

If you specify TrackArtifacts=false, you can no longer use that query object as an iteration query. The build system needs to track changes iteration artifacts to identify the iterations for the task.

Example: false

Data Types: logical

Properties

Path — Path to file

string | character vector | cell array of character vectors

Path to file, specified as a string, a character vector, or a cell array of character vectors.

Example: fullfile("tools","sampleChecks.json")

Example: [fullfile("myFiles","myModel.slx"), fullfile("myFiles","myScript.m")]

Data Types: char | string | cell

ValidateFileExistence — Validate that file exists before returning in query results

1 (true) (default) | 0 (false)

Validate that the file exists before attempting to return the file in the query results, specified as a numeric or logical 1 (true) or 0 (false).

Example: false

Data Types: logical

TrackArtifacts — Setting that controls whether build system tracks changes to file the query returns

1 (true) (default) | 0 (false)

Setting that controls whether the build system tracks changes to the file the query returns, specified as a numeric or logical 1 (true) or 0 (false).

For more information, see Turn Off Change Tracking for File.

Note

If you specify TrackArtifacts=false, you can no longer use that query object as an iteration query. The build system needs to track changes iteration artifacts to identify the iterations for the task.

Example: false

Data Types: logical

Title — Query title

"Files: ''" (default) | string | character vector

Query title, specified as a string or a character vector.

Example: "Files: 'tools\sampleChecks.json'"

Data Types: string

DefaultArtifactType — Type of artifact

"padv_output_file" (default) | "ma_config_file" | "m_file" | ...

Type of artifact, specified as one or more of the values in this table. To specify multiple values, use an array.

Category	Artifact Type	Description
MATLAB	"m_class"	MATLAB class
	"m_file"	MATLAB file
	"m_func"	MATLAB function
	"m_method"	MATLAB class method
	"m_property"	MATLAB class property
Model Advisor	"ma_config_file"	Model Advisor configuration file
	"ma_justification_file"	Model Advisor justification file
Process Advisor	"padv_dep_artifacts"	Related artifacts that current artifact depends on
	"padv_output_file"	Process Advisor output file
Project	"project"	Current project file
Requirements	"mwreq_file"	Requirement file (since R2024b)
	"mwreq_item"	Requirement (since R2024b)
	"sl_req"	Requirement (for R2024a and earlier)
	"sl_req_file"	Requirement file (for R2024a and earlier)
	"sl_req_table"	Requirements Table
Stateflow	"sf_chart"	Stateflow chart
	"sf_graphical_fcn"	Stateflow graphical function
	"sf_group"	Stateflow group
	"sf_state"	Stateflow state
	"sf_state_transition_chart"	Stateflow state transition chart
	"sf_truth_table"	Stateflow truth table
Simulink	"sl_block_diagram"	Block diagram
	"sl_data_dictionary_file"	Data dictionary file
	"sl_embedded_matlab_fcn"	MATLAB function
	"sl_block_diagram"	Block diagram
	"sl_library_file"	Library file
	"sl_model_file"	Simulink model file
	"sl_protected_model_file"	Protected Simulink model file
	"sl_subsystem"	Subsystem
	"sl_subsystem_file"	Subsystem file
System Composer	"zc_block_diagram"	System Composer architecture
	"zc_component"	System Composer architecture component
	"zc_file"	System Composer architecture file
Tests	"harness_info_file"	Harness info file
	"sl_harness_block_diagram"	Harness block diagram
	"sl_harness_file"	Test harness file
	"sl_test_case"	Simulink Test case
	"sl_test_case_result"	Simulink Test case result
	"sl_test_file"	Simulink Test file
	"sl_test_iteration"	Simulink Test iteration
	"sl_test_iteration_result"	Simulink Test iteration result
	"sl_test_report_file"	Simulink Test result report
	"sl_test_result_file"	Simulink Test result file
	"sl_test_resultset"	Simulink Test result set
	"sl_test_seq"	Test Sequence
	"sl_test_suite"	Simulink Test suite
	"sl_test_suite_result"	Simulink Test suite result

The Type argument controls the DefaultArtifactType property value.

Example: "ma_config_file"

Example: ["sl_model_file" "m_file"]

Parent — Initial query run before iteration query

padv.Query object | Name of padv.Query object

Initial query run before iteration query, specified as either a padv.Query object or the Name of a padv.Query object. When you specify a padv.Query object as the iteration query for a task, the Parent query is the initial query that the build system runs before running the specified iteration query.

The build system ignores the Parent query when you specify a query as an input query or dependency query for a task.

For information on how to improve Process Advisor load times by sharing query instances across your process model, see Best Practices for Process Model Authoring.

Example: padv.builtin.query.FindModels

Example: padv.builtin.query.FindModels(IncludePath = "Control")

Name — Unique identifier for query

string

Unique identifier for query, specified as a string.

Example: "FindMyFile"

Data Types: string

ShowFileExtension — Show file extensions for returned artifacts

0 (false) | 1 (true)

Show file extensions in the Alias property of returned artifacts, specified as a numeric or logical 1 (true) or 0 (false). The Alias property controls the display name for the artifact in the Tasks column in Process Advisor.

By default, queries strip file extensions from the Alias property of each task iteration artifact. To show file extensions for all artifacts in the Tasks column, select the project setting Show file extensions. To keep file extensions in the results for a specific query, specify the query property ShowFileExtension as true.

Example: true

Data Types: logical

SortArtifacts — Setting for automatically sorting artifacts by address

true or 1 (default) | false or 0

Setting for automatically sorting artifacts by address, specified as a numeric or logical 1 (true) or 0 (false). When a query returns artifacts, the artifacts should be in a consistent order. By default, the build system sorts artifacts by the artifact address.

Alternatively, you can sort artifacts in a different order by overriding the internal sortArtifacts method in a subclass that defines a custom sort behavior. For an example, see Sort Artifacts in Specific Order.

The build system automatically calls the sortArtifacts method when using the process model. The sortArtifacts method expects two input arguments: a padv.Query object and a list of padv.Artifact objects returned by the run method. The sortArtifacts method should return a list of sorted padv.Artifact objects.

Example: SortArtifacts = false

Data Types: logical

FunctionHandle — Handle to function that function-based query runs

function_handle

Handle to the function that a function-based query runs, specified as a function_handle.

If you define your query functionality inside a function and you or the build system call run on the query, the query runs the function specified by the function_handle.

The built-in queries are defined inside classes and do not use the FunctionHandle.

Example: FunctionHandle = @FunctionForQuery

Data Types: function_handle

Methods

Specialized Public Methods

This class overrides the following inherited methods.

run

Run query to find the artifacts that meet the criteria specified by the query. The query returns a padv.Artifact object or an array of padv.Artifact objects that represent those artifacts. Note You do not need to manually invoke this method inside your process model. The build system automatically invokes the run method to find artifacts. The run method inside this built-in query runs on a query object obj and returns artifacts artifacts. If you inherit from this built-in query, make sure to use the same method signature inside your custom query: function artifacts = run(obj,~) ... end

Examples

Find and Use Model Advisor Configuration File

By default, the RunModelStandards task runs a subset of high-integrity checks. If you want the task to run the Model Advisor checks specified by the Model Advisor configuration file, you can add the configuration file as an input to the task.

Open a project. For this example, you can open the Process Advisor example project.

processAdvisorExampleStart

Edit the process model to use the following process model instead.

function processmodel(pm)
    % Defines the project's processmodel

    arguments
        pm padv.ProcessModel
    end

    % Add built-in task for Checking Modeling Standards
    maTask = pm.addTask(padv.builtin.task.RunModelStandards);

    % Reconfigure task to specify which Model Advisor configuration to use
    maTask.addInputQueries(padv.builtin.query.FindFileWithAddress( ...
        Type = "ma_config_file",...
        Path = fullfile("tools","sampleChecks.json")));

end

This process model finds the Model Advisor configuration file by using the query FindFileWithAddress and then specifies that query as the input query for the built-in task RunModelStandards by using the addInputQueries function.

For the FindFileWithAddress query:

• The first argument, "ma_config_file", specifies that the file is a Model Advisor configuration file.

• The second argument specifies the path to the Model Advisor configuration file. In this example, the configuration file is a file, sampleChecks.json, in the tools folder in the project.

Find Multiple Files

To find multiple files by their addresses, you can use vectors of the same length.

For example, to find a Model Advisor configuration file and a model file by using the same query, specify the artifact type (Type) and the file path (Path) using vectors of the same length. For example:

padv.builtin.query.FindFileWithAddress(...
    Type=["ma_config_file", "sl_model_file"],...
    Path=[fullfile("tools","sampleChecks.json"),...
        fullfile("02_Models","AHRS_Voter","specification","AHRS_Voter.slx")])

If you only specify one value for Type, the query uses the same artifact type for each specified file specified by Path. For example, the following query finds two Model Advisor configuration files.

padv.builtin.query.FindFileWithAddress(...
    Type="ma_config_file",...
    Path=[fullfile("tools","sampleChecks.json"), fullfile("tools","myCustomChecks.json")])

Turn Off Change Tracking for File

If you do not want the build system to mark a task as outdated when you make changes to a specific input artifact, you can turn off change tracking for that artifact by specifying the name-value argument TrackArtifacts as false when you use the built-in query FindFileWithAddress to find the artifact.

Open a project. For this example, you can open the Process Advisor example project.

processAdvisorExampleStart

Edit the process model to use the following process model instead. This process model code turns off change tracking for a Model Advisor configuration file, myMAConfig.json, that is an input for the Check Modeling Standards task.

function processmodel(pm)
    % Defines the project's processmodel

    arguments
        pm padv.ProcessModel
    end

    % Add built-in task for Checking Modeling Standards
    maTask = pm.addTask(padv.builtin.task.RunModelStandards);
    % Reconfigure task to specify which Model Advisor configuration to use
    % but turn change tracking off for the configuration file
    maTask.addInputQueries(...
        padv.builtin.query.FindFileWithAddress( ...
        Type='ma_config_file', Path=which('myMAConfig.json'), ...
        TrackArtifacts=false));
end

When you run the task, the Process Advisor I/O column shows the outputs as Untracked. If you make a change to an untracked file, the build system does not mark the task as outdated.

By default, the build system marks files outside the project as Untracked because you cannot track changes to files outside the project. The change tracking setting for the artifact is stored in the Track property in the ArtifactAddress property for the padv.Artifact object.

Test Query in Command Window

Although you typically use queries inside your process model, you can run FindFileWithAddress queries outside of your process model to confirm which artifacts a query returns.

Open a project. For this example, you can open the Process Advisor example project.

processAdvisorExampleStart

Create an instance of the query. For example, create a query that finds a file with the artifact type Model Advisor configuration file (ma_config_file) at the file path specified by fullfile("tools","sampleChecks.json").

q = padv.builtin.query.FindFileWithAddress( ...
    Type = "ma_config_file",...
    Path = fullfile("tools","sampleChecks.json"))

Run the query.

run(q)

The query returns the specified artifact.

ans = 

    "tools\sampleChecks.json"

Capabilities and Limitations

This table identifies functionality that is supported by the query.

Functionality	Supported?
Input query for task	Yes.
Iteration query for task	Only when the query property TrackArtifacts is true.