Working with Library Links

Displaying Library Links

A model can have a block linked to a library block, or it can have a local instance of a block that is not linked. To enable the display of library links:

1. In the Model Editor window, select Format > Library Link Display and from the submenu, select one of these options:

   1. None — displays no links

   2. Disabled — displays only disabled links (the default for new models)

   3. User — displays only links to user libraries

   4. All — displays all links

2. Observe the library link indicators.

   The library link indicator is an arrow in the bottom left corner of each block.

The color of the link arrow indicates the status of the link.

Back to Top

Locking Links to Blocks in a Library

You can lock links to a library. Lockable library links enable control of end user editing, to prevent unintentional disabling of these links. This ensures robust usage of mature stable libraries.

To lock links to a library, either:

• In your library window, select Edit > Lock Links To Library.

• At the command line, use the LockLinksToLibrary property:

   set_param('MyModelName', 'LockLinksToLibrary', 'on')
  

  where MyModelName.mdl is the library file.

When you copy a block to a model from a library with locked links:

• The link is locked.

• You cannot disable locked links from the Model Editor.

  If you select Edit or right-click the linked block, you see the Link Options menu has changed to Locked Link Options, and the only enabled option is now Go To Library Block.

  

• If you display library links, the locked link icon has a black background.

  

• If you open a locked link, the window title is Locked Link: blockname.

• You cannot edit locked link contents. If you try to make a structural change to a locked link (such as editing the diagram), you see a message stating that you cannot modify the link because it is either locked or inside another locked link.

  • The mask and block parameter dialogs are disabled for blocks inside locked links. For a resolved linked block with a mask, its parameter dialog is always disabled.

  • You cannot parameterize locked links in the Model Editor.

• You can disable locked links only from the command line as follows:

  set_param(gcb, 'LinkStatus', 'inactive')

To unlock links to a library:

• In your library window, select Edit > Unlock Links To Library

• At the command line:

   set_param('MyModelName', 'LockLinksToLibrary', 'off')
  

  The status of a link (locked or not) is determined by the library state when you copy the block. If you copy a block from a library with locked links, the link is locked. If you later unlock the library links, any existing linked blocks do not change to unlocked links until you refresh links.

If you use sublibraries as an organizational tool, when you lock links to a library, you might want also to lock links to any sublibraries.

Back to Top

Disabling Links to Library Blocks

To make a structural change to a linked block, you need to disable the link between the block and the library block that serves as its prototype.

You cannot disable locked links from the Model Editor. See Locking Links to Blocks in a Library.

Note   When you use the Model Editor to make a structural change (such as editing the diagram) to a block with an active library link, Simulink offers to disable the library link for you (unless the link is locked). If you accept, Simulink disables the link and allows you to make changes to the subsystem block. Do not use set_param to make a structural change to an active link; the result of this type of change is undefined.

To disable a link:

1. In the Model Editor window, select a linked block.

2. From the Edit menu, select Link Options, and then select Disable link.

   The library link is disabled and the library link indicator changes to gray. When a library block is disabled and it is within another library block (a child of a parent library block), the model also disables the parent block containing the child block.

To disable a link from the command-line, set the LinkStatus property to inactive as follows:

set_param(gcb, 'LinkStatus', 'inactive')

Back to Top

Restoring Disabled or Parameterized Links

After you make changes to a disabled linked block, you may want to restore its link to the library block and resolve any differences between the two blocks. The Links Tool helps you with this task.

1. In the Model Editor window, select a linked block with a disabled library link.

2. From the Edit menu, select Link Options, and then select Resolve link.

   The Links Tool window opens.

   

   The Edited links table has the following columns:

   • Linked block — List of linked blocks. The list of links includes library links with structural changes (disabled links), parameterized library links (edited links), and library links that were actively chosen to be resolved.

   • Action — Select an action to perform on the linked block or library.

   • Library — List of library names and version numbers.

3. Select the check box Show all disabled links if you want to view disabled links as well as parameterized links.

4. Under Push/Restore Mode, choose a mode of action:

   • If you want to act on individual links, select Individual.

   • If you want to act on the whole link hierarchy, leave the default setting on Hierarchy. See Pushing or Restoring Link Hierarchies.

5. From the Linked block list, select a block name.

   The Links Tool updates the Paths for selected link panel with links to the linked block in the model and in the library.

6. From the Action list, select Push or Restore for the currently selected block.

   Action Choice	Links Tool Action
   Push	The Links Tool looks for all changes in the link hierarchy and pushes all links with changes to their libraries. Push replaces the version of the block in the library with the version in the model.
   Restore	The Links Tool looks for all disabled or edited links in the link hierarchy and restores them all with their corresponding library blocks. Restore replaces the version of the block in the model with the version in the library.
   Push Individual	In Individual mode, the disabled or edited block is pushed to the library, preserving the changes inside it without acting on the hierarchy. All other links are unaffected.
   Restore Inidividual	In Individual mode, the disabled or edited block is restored from the library, and all other links are unaffected.

   To select the same action for all linked blocks, click Push all, Restore all, or Clear all.

7. When you click OK or Apply, the Links Tool performs the push or restore actions you selected in the edited links table.

   After resolving a link, the versions in the library and the linked block now match.

   Note   Changes you push to the library are not saved until you actively save the library.

If a linked block name has a cautionary icon before it, the model has other instances of this block linked from the same library block, and they have different changes. Choose one of the instances to push changes to the library block and restore links to the other blocks , or choose to restore all of them with the library version.

Pushing or Restoring Link Hierarchies

Caution   Be cautious using Push or Restore in hierarchy mode if you have a large hierarchy of edited and disabled links. Ensure that you want to push or restore the whole hierarchy of links.

Pushing a hierarchy of disabled links affects the disabled links inside and outside in the hierarchy for a given link. If you push changes from a disabled link in the middle of a hierarchy, the inside links are pushed and the outside links are restored if without changes. This operation does not affect outside (parent) links with changes unless you also explicitly selected them for push. The Links Tool starts from the lowest links (the deepest inside) and then moves upward in the hierarchy.

Some simple examples:

1. Link A contains link B and both have changes.

   • Push A. The Links Tool pushes both A and B.

   • Push B. The Links Tool pushes B and not A.

2. Link A contains link B. A has no changes, and B has changes.

   • Push B. The Links Tool pushes B and restores A. When parent links are unmodified, they are restored.

If you have a hierarchy of parameterized links, the Links Tool can manipulate only the top level.

Back to Top

Checking and Setting Link Status Programmatically

All blocks have a LinkStatus parameter and a StaticLinkStatus parameter that indicate whether the block is a linked block.

Use get_param(gcb, 'StaticLinkStatus') to query the link status without updating out-of-date linked blocks.

Use get_param and set_param to query and set the LinkStatus, which can have the following values.

Note   Using get_param to query a block's LinkStatus also resolves any out-of-date block links. Use get_param to update library links in a model programmatically. Querying the StaticLinkStatus property does not resolve any out-of-date links. Query the StaticLinkStatus property when the call to get_param is in the callback of a child block querying the link status of its parent.

If you call get_param on a block inside a library link, Simulink resolves the link if necessary. This operation may involve loading part of the library and executing callbacks.

Back to Top

Breaking a Link to a Library Block

You can break the link between a linked block and its library block to cause the linked block to become a simple copy of the library block, unlinked to the library block. Changes to the library block no longer affect the block. Breaking links to library blocks may enable you to transport a masked subsystem model as a standalone model, without the libraries (see Working with Block Masks).

To break the link between a linked block and its library block, first disable the link. Then select the block and choose Break Link from the Link Options menu. You can also break the link between a linked block and its library block from the command line by changing the value of the LinkStatus parameter to 'none' using this command:

set_param(gcb, 'LinkStatus', 'none')

You can also break links to library blocks when saving the model, by supplying arguments to the save_system command. See save_system in the Simulink reference documentation.

Note   Breaking library links in a model does not guarantee that you can run the model standalone, especially if the model includes blocks from third-party libraries or optional Simulink blocksets. It is possible that a library block invokes functions supplied with the library and hence can run only if the library is installed on the system running the model. Further, breaking a link can cause a model to fail when you install a new version of the library on a system.

For example, suppose a block invokes a function that is supplied with the library. Now suppose that a new version of the library eliminates the function. Running a model with an unlinked copy of the block results in invocation of a now nonexistent function, causing the simulation to fail. To avoid such problems, you should generally avoid breaking links to libraries.

Back to Top

Fixing Unresolved Library Links

If Simulink is unable to find either the library block or the source library on your MATLAB path when it attempts to update the linked block, the link becomes unresolved. Simulink issues an error message and displays these blocks using red dashed lines. The error message is

Failed to find block "source-block-name" 
in library "source-library-name"
referenced by block
"linked-block-path".

The unresolved linked block appears like this (colored red).

To fix a bad link, you must do one of the following:

• Delete the unresolved block and copy the library block back into your model.

• Add the folder that contains the required library to the MATLAB path and select either Edit > Update Diagram or Edit > Links and Model Blocks > Refresh.

• Double-click the unresolved block to open its dialog box (see the Bad Link block reference page). On the dialog box that appears, correct the pathname in the Source block field and click OK.

Back to Top

Creating and Working with Linked Blocks

Creating Block Libraries

Related Products & Applications

• Simulink
• Control Design
• Signal Processing & Communications
• Model-Based Design
• Physical Modeling
• Verification & Validation

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit