Customize Bus Object Import and Export

You can use the Bus Editor to import bus objects to the base workspace, as described in Import Bus Objects, and to export bus objects from the base workspace, as described in Export Bus Objects. By default, the Bus Editor can import bus objects only from a MATLAB® code file or MAT-file, and can export bus objects only to a MATLAB code file or MAT-file, with the files stored somewhere that is accessible using an ordinary Open or Save dialog.

Alternatively, you can customize the Bus Editor's import and export commands by writing MATLAB functions that provide the desired capabilities, and registering these functions using the Simulink® Customization Manager. When a custom bus object import or export function exists, and you use the Bus Editor to import or export bus objects, the editor calls the custom import or export function rather than using its default capabilities.

A customized import or export function can have any desired effect and use any available technique. For example, rather than storing bus objects in MATLAB code files or MAT-files in the file system, you could provide customized functions that store the objects as records in a corporate database, perhaps in a format that also meets other corporate data management requirements.

This section describes techniques for designing and implementing a custom bus object import or export function, and for using the Simulink Customization Manager to register such a custom function. The registration process establishes the custom import and export functions as callbacks for the Bus Editor Import to Base Workspace and Export to File commands, replacing the default capabilities of the editor.

Customizing the Bus Editor's import and export capabilities has no effect on any MATLAB or Simulink API function: it affects only the behavior of the Bus Editor. You can customize bus object import, export, or both. You can establish, change, and cancel import or export customization at any time. Canceling import or export customization restores the default Bus Editor capabilities for that operation without affecting the other.

Prerequisites for Customization

To perform bus object import or export customization, you must understand:

  • The MATLAB language and programming techniques that you will need.

  • Simulink bus object syntax. See About Bus Objects, Simulink.Bus, Simulink.BusElement, and Nest Bus Definitions.

  • The proprietary format into which you will translate bus objects, and all techniques necessary to access the facility that stores the objects.

  • Any platform-specific techniques needed to obtain data from the user, such as the name of the location in which to store or access bus objects.

The rest of the information that you will need, including all necessary information about the Simulink Customization Manager appears in this section. For complete information about the Customization Manager, see Simulink Environment Customization.

Writing a Bus Object Import Function

A function that customizes bus import can use any MATLAB programming construct or technique. The function can take zero or more arguments, which can be anything that the function needs to perform its task. You can use functions, global variables, or any other MATLAB technique to provide argument values. The function can also poll the user for information, such as a designation of where to obtain bus object information. The general algorithm of a custom bus object import function is:

  1. Obtain bus object information from the local repository.

  2. Translate each bus object definition to a Simulink bus object.

  3. Save each bus object to the MATLAB base workspace.

An example of the syntactic shell of an import callback function is:

function myImportCallBack
disp('Custom import was called!');

Although this function does not import any bus objects, it is syntactically valid and could be registered with the Simulink Customization Manager. A real import function would somehow obtain a designation of where to obtain the bus object(s) to import; convert each one to a Simulink bus object; and store the object in the base workspace. The additional logic needed is enterprise-specific.

Writing a Bus Object Export Function

A callback function that customizes bus export can use any MATLAB programming construct or technique. The function must take one argument, and can take zero or more additional arguments, which can be anything that the function needs to perform its task. When the Bus Editor calls the function, the value of the first argument is a cell array containing the names of all bus objects selected within the editor to be exported. You can use functions, global variables, or any other MATLAB technique to provide values for any additional arguments. The general algorithm of a customized export function is:

  1. Iterate over the list of object names in the first argument.

  2. Obtain the bus object corresponding to each name.

  3. Translate the bus object to the proprietary syntax.

  4. Save the translated bus object in the local repository.

An example of the syntactic shell of such an export callback function is:

function myExportCallBack(selectedBusObjects)
disp('Custom export was called!');
for idx = 1:length(selectedBusObjects)
    disp([selectedBusObjects{idx} ' was selected for export.']);

Although this function does not export any bus objects, it is syntactically valid and could be registered. It accepts a cell array of bus object names, iterates over them, and prints each name. A real export function would use each name to retrieve the corresponding bus object from the base workspace; convert the object to proprietary format; and store the converted object somewhere. The additional logic needed is enterprise-specific.

Registering Customizations

To customize bus object import or export, you provide a customization registration function that inputs and configures the Customization Manager whenever you start the Simulink software or subsequently refresh Simulink customizations. The steps for using a customization registration function are:

  1. Create a file named sl_customization.m to contain the customization registration function (or use an existing customization file).

  2. At the top of the file, create a function named sl_customization that takes a single argument (or use the customization function in an existing file). When the function is invoked, the value of this argument will be the Customization Manager.

  3. Configure the sl_customization function to set importCallbackFcn and exportCallbackFcn to be function handles that specify your customized bus object import and export functions.

  4. If sl_customization.m is a new customization file, put it anywhere on the MATLAB search path. Two frequently-used locations are matlabroot and the current working directory; or you may want to extend the search path.

A simple example of a customization registration function is:

function sl_customization(cm)
disp('My customization file was loaded.');
cm.BusEditorCustomizer.importCallbackFcn = @myImportCallBack;
cm.BusEditorCustomizer.exportCallbackFcn = @(x)myExportCallBack(x);

When the Simulink software starts up, it traverses the MATLAB search path looking for files named sl_customization.m. The software loads each such file that it finds (not just the first file) and executes the sl_customization function at its top, establishing the customizations that the function specifies.

Executing the previous customization function will display a message (which an actual function probably would not) and establish that the Bus Editor uses a function named myImportCallBack() to import bus objects, and a function named myExportCallBack(x) to export bus objects.

The function corresponding to a handle that appears in a callback registration need not be defined when the registration occurs, but it must be defined when the Bus Editor later calls the function. The same latitude and requirement applies to any functions or global variables used to provide the values of any additional arguments.

Other functions can also exist in the sl_customization.m file. However, the Simulink software ignores files named sl_customization.m except when it starts up or refreshes customizations, so any changes to functions in the customization file will be ignored until one of those events occurs. By contrast, changes to other MATLAB code files on the MATLAB path take effect immediately.

Changing Customizations

You can change the handles established in the sl_customization function by changing the function to specify the changed handles, saving the function, then refreshing customizations by executing:


The Simulink software then traverses the MATLAB path and reloads all sl_customization.m files that it finds, executing the first function in each one, just as it did on Simulink startup.

You can revert to default import or export behavior by setting the appropriate BusEditorCustomizer element to [] in the sl_customization function, then refreshing customizations. Alternatively, you can eliminate both customizations in one operation by executing:


where cm was previously set to a customization manager object (see Registering Customizations).

Changes to the import and export callback functions themselves, as distinct from changes to the handles that register them as customizations, take effect immediately unless they are in the sl_customization.m file itself, in which case they take effect next time you refresh customizations. Keeping the callback functions in separate files usually provides more flexible and modular results.

See Also




Related Examples

More About

Was this topic helpful?