Documentation

Forwarding Tables

If you edit an existing library block, you would want to ensure that the changes do not break the model when the model is saved with an older version of the library block. The type of edits in the library block can include, library path change, library block name change, or addition, removal, or rename of parameters.

The Forwarding Table helps you to maintain compatibility of library blocks and thus ensures that the models continue to work. You can use the Forwarding table to create a map between the old and the new library blocks without any loss of data or functionality. After the mapping of old library blocks to new library blocks is specified in the forwarding table, links to the old library blocks update automatically during model load. For example, if you rename or move a block in a library, you can use a forwarding table to update the models that have link to the old library block.

Create Forwarding Table

Note

Models that have broken or disabled links cannot be updated using the forwarding tables.

  1. Open the library model.

  2. Click Diagram > Unlock Library. The library is now unlocked for editing.

  3. Click File > Library Properties > Library Properties. The Library Properties dialog box opens.

  4. Click the Forwarding Table tab.

  5. Click (Add New Entry) button. A new row is added in the Forwarding Table.

  6. Specify values in the Old Block Path and New Block Path columns. To get the path of a block, select the block in the model and click .

  7. In the Version column, you can choose to specify a version number for the library block.

    If the old block name and the new block name are the same, the forwarding table populates the version number automatically. The initial value of the library version (LibraryVersion) is derived from the model version (ModelVersion) of the library at the time the library link is created. Any subsequent updated to the library block would update the library version to match the model version of the library.

    Note

    • Version number must be a numeric value.

    • When the old and the new block paths are the same, the version number must be of the format <major_version>.<minor_version>. For example, while renaming a library block.

    • The version number cannot have more than one dot notation. For example, a version number of 1.3 is acceptable whereas, version number 1.3.1 is not acceptable.

    • When you use forwarding table to move a library block from one library to another, the version number format is not critical.

  8. In the Transformation Function column, you can specify a MATLAB® file that corrects the mismatch of parameter data between the old and the new link. Transforming old link parameter data for the new library block enables you to load old links and preserve parameter data. For more information, see Transformation Functions.

    If no transformation function is specified, the Transformation Function column displays No Transformation when you save the library.

  9. To apply the changes and close the dialog box, click OK. The mapping of old path to new path is created in the Forwarding Table. The links to the old library blocks are updated automatically when you open a model containing links to the library.

An example of user-defined forwarding table is as shown:

When you specify identical library block name and path for the older and the newer blocks, the Forwarding Table populates the version number automatically. For the first entry with identical names and path, the version number of the old block starts with 0, and the new version of the block is set as the model version of the library. You can view the model version of the library under the History tab of the Forwarding Table.

A transformation function must be specified when the instance-specific parameters (InstanceData) have changed in the old and the new library block.

In this example,

  • Block path for Block A changes from LibA to LibB.

  • Block name for Block X changes to Block Y while the library path remains the same.

  • Block name for Block M changed to Block N. A transformation function is specified to take care of the instance-specific changes.

  • Block version and instance-specific parameter changed for Block L.

Create Forwarding Table Programmatically

At the command line, you can create a simple forwarding table specifying the old locations and new locations of blocks that have moved within the library or to another library. You associate a forwarding table with a library by setting its ForwardingTable parameter to a cell array of two-element cell arrays, each of which specifies the old and new path of a block that has moved. For example, the syntax to create a forwarding table and assign it to a library named Lib1 is,

set_param('Lib1', 'ForwardingTable', {{'Lib1/A', 'Lib2/A'} 
{'Lib1/B', 'Lib1/C'}});

Here,

  • Lib1 is the library associated to the forwarding table.

  • Block A is transferred from Lib1 to Lib2.

  • Block B is renamed to Block C in the same library.

Transformation Functions

A linked block instance is associated with instance-specific parameters called InstanceData. When you create versions of a library block, parameter sets can get added or removed from the InstanceData.

A transformation function corrects the mismatch of parameters in the InstanceData of the new and old library links thus ensuring that the library links continue to work.

You can define a transformation function using a MATLAB file on the path, then specify the function in the Transformation Function column of the Forwarding Table.

The new block path defined in the forwarding table overrides the values defined in the transformation function. If the new block path is a dynamic value that changes based on certain conditions, then the new block path must be only defined using the transformation function.

The syntax for transformation function must be;

function outData = TransformationFcn(inData)

Here,

  • inData is a structure with fields ForwardingTableEntry and InstanceData, and ForwardingTableEntry is also a structure.

  • outData is a structure with fields NewInstanceData and NewBlockPath.

A general transformation function can have many local functions defined in it. The function calls the appropriate local functions based on old block names and versions. You can use this to combine multiple local functions into a single transformation function, to avoid having many transformation functions on the MATLAB path.

Consider the Compare to Const block in Simulink® Library. Versions of this block are created without changing the name and the block path but parameters are added to the newer library block.

The table displays the parameter difference in two versions of the Compare to Const block. The instance data in each version has been highlighted.

Old VersionNew Version
Block {
BlockType		      Reference
Name		      "Compare\nTo Constant"
Ports		        [1, 1]
Position		     [210, 60, 250, 100]
SourceBlock	  "fixpt_lib_4/Logic & Comparison/Compare\nTo Constant"
SourceType	    "Fixed-Point Compare To Constant"
relop	           "=="
const	           "3.0"
    }
Block {
BlockType		      Reference
Name		      "Compare\nTo Constant"
SID		                      "15"
Ports		                     [1, 1]
Position		      [125, 50, 155, 80]
ZOrder		      -5
LibraryVersion	      "1.271"
SourceBlock	       "simulink/Logic and Bit\nOperations/Compare\nTo Constant"
SourceType	        "Compare To Constant"
relop		          "<="
const		             "3.0"
OutDataTypeStr	      "boolean"
ZeroCross		      on
    }
  

The New Version of the Compare to Const block has additional parameters (OutDataTypeStr and ZeroCross) associated with it. For such cases, the transformation function must ensure that the additional parameters in the InstanceData are set so that the old library links work.

An example of transformation function for the Compare to Const block to add the OutDataTypestr parameter with a value of uint8 is as follows,

function [outData] = TransformationCompConstBlk(inData)
outData.NewBlockPath = ''; % No change in the library block path
outData.NewInstanceData = [];
instanceData = inData.InstanceData;
% Get the field type 'Name' from instanceData
[ParameterNames{1:length(instanceData)}] = instanceData.Name;

if (~ismember('OutDataTypeStr',ParameterNames))
    % OutDataTypeStr parameter is not present in old link. Add it and set value uint8
    instanceData(end+1).Name = 'OutDataTypeStr';
    instanceData(end).Value = 'uint8';
end

outData.NewInstanceData = instanceData;

Create Mask Parameter Aliases

If a mask parameter is renamed, you must ensure that the existing MATLAB scripts that use the old parameter names, continues to work. To ensure the compatibility, you can create alias (alternate names) for a mask parameter name. Alias allows you to change the name of a mask parameter in a library block without having to recreate links to the block in existing models.

Consider a masked block that contains an Edit parameter. The mask parameter name for this Edit parameter is p1.

MaskObj= 
% MaskParameter with properties:

           Type: 'edit'
    TypeOptions: {0×1 cell}
           Name: 'p1'
         Prompt: 'p1'
          Value: '0'
       Evaluate: 'on'
        Tunable: 'on'
      NeverSave: 'off'
         Hidden: 'off'
        Enabled: 'on'
        Visible: 'on'
        ToolTip: 'on'
       Callback: ''
          Alias: ''

Notice that the Edit mask parameter does not have any alias name. To add an alias name for the mask parameter, you can set a value for the Alias mask parameter property.

MaskObj.Alias = 'pa'

You can either use the mask parameter name or the alias to do a function call on the mask parameter. For example, in this case you can either use set_param(gcb, 'p1, '10) (mask parameter name) set_param(gcb, 'pa, '10) (mask parameter alias) to set a value for the Edit mask parameter.

Related Topics

Was this topic helpful?