Customize Bus Object Import and Export

You can use the Bus Editor to import Bus objects to the base workspace and to export Bus objects from the base workspace, as described in Save Simulink.Bus Objects. By default, the Bus Editor can save bus objects to, and import Bus objects from, a function or MAT-file. The files must be in a location that is accessible using an ordinary Open or Save dialog box.

You can write customized MATLAB^® functions that provide alternative import or export (or both) functionality. For example, you can write a customized function that stores the objects as records in a database, in a format that your organization uses.

After you design and implement a custom Bus object import or export function, use the Simulink^® Customization Manager to register the function. The registration process establishes custom import and export functions as callbacks for the Bus Editor Import to Base Workspace and Export to File commands. The callbacks replace the default capabilities of the Bus Editor. Customizing the Bus Editor import and export capabilities has no effect on other MATLAB or Simulink functions. Canceling import or export customization restores the default Bus Editor capabilities for that operation without affecting the other.

To create Bus objects from external C code, you do not need to make customizations. See Create Bus Objects from External C Code.

Required Background Knowledge

Customizing Bus object import or export requires that you understand:

• MATLAB language and programming techniques

• Simulink Bus object syntax

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

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

Write a Bus Object Export Function

A custom Bus object export function requires at least one argument. You can use additional arguments to handle special actions by the function. The value of the first argument is a cell array containing the names of all Bus objects that the Bus Editor has selected. 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.

This example shows 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.']);
end

Although this function does not export any Bus objects, it is syntactically valid and can be registered. It accepts a cell array of Bus object names, iterates over them, and prints each name. An operational export function:

• Uses each name to retrieve the corresponding Bus object from the base workspace

• Converts the object to proprietary format

• Stores the converted object

The additional logic is enterprise-specific.

Write a Bus Object Import Function

A custom Bus object import function can take zero or more arguments to perform its task. You can use functions, global variables, or any other MATLAB technique to provide argument values. Also, the function can 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.

This example shows 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 can be registered with the Simulink Customization Manager. An operational import function:

• Gets a designation of where to obtain the Bus objects to import

• Converts each Bus object to a Simulink.Bus object

• Stores the object in the base workspace

The additional logic is enterprise-specific.

Register Customizations

To customize Bus object import or export, provide a customization registration function that inputs and configures the Customization Manager whenever you start Simulink software or 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. Alternatively, you can 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 is 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 folder. Alternatively, you can extend the search path.

Here is a simple example of a customization registration function:

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

When Simulink starts up, it traverses the MATLAB search path looking for files named sl_customization.m. Simulink 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 example customization function displays a message (which an actual function probably would not). The function establishes 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 can be undefined when the registration occurs. However, it must be defined when the Bus Editor calls the function. The same latitude and requirement applies to any functions or global variables used to provide the values of 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. Any changes to functions in the customization file are ignored until one of those events occurs. By contrast, changes to other functions on the MATLAB path take effect immediately.

For more information, see Registering Customizations.

Change Customizations

You can change the handles established in the sl_customization function by:

• Changing the function to specify the changed handles

• Saving the function

• Refreshing customizations by executing sl_refresh_customizations

Simulink 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 in the sl_customization function the appropriate BusEditorCustomizer element to [] and then refreshing customizations. Alternatively, you can eliminate both customizations in one operation by executing:

cm.BusEditorCustomizer.clear

where cm was previously set to a customization manager object (see Register 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. If the callback functions are in the sl_customization.m file, they take effect next time you refresh customizations. Keeping the callback functions in separate files usually provides more flexible and modular results.