Work with Library Links

Display 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 Display > Library Links 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 Defined — displays only links to user libraries

    4. All — displays all links

  2. Observe the library link indicators.

    The library link indicator is a badge in the bottom left corner of each block. You can right-click the link badge to access link menu options.

The color and icon of the link badge indicates the status of the link. If you open a linked block, the Model Editor displays the same link badge at bottom left. You can right-click the link badge in the corner of the canvas to access link options such as Go To Library Block.

Link BadgeStatus

Black links

Active link

Grey separated links

Inactive link

Black links with a red star icon

Active and modified (parameterized link)

White links, black background

Locked link

    Note:   If you have a variant subsystem block inside a link block, modifying the parameters on the variant subsystem creates a link data on the topmost link block. If the link badge is visible, presence of link data is indicated by a red star on the link badge.

Lock 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 Diagram > Lock Links To Library.

  • At the command line, use the LockLinksToLibrary property:

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

    where MyModelName 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 Diagram or right-click the linked block, you see the Library Link menu has changed to Locked Library Link, 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. The bottom left corner shows a lock icon and a link badge.

  • 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 Diagram > 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.

Disable 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 Lock 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, right-click a linked block and select Library Link > Disable Link.

  2. Alternatively, select a linked block and select the menu item Diagram > Library Link > 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')

Restore 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 Diagram menu (or right-click context menu), select Library Link > 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 ChoiceLinks Tool Action
    PushThe 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.
    RestoreThe 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 IndividualIn 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 IndividualIn 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.

Check and Set 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.

Get LinkStatus ValueDescription
none

Block is not a linked block.

resolved

Resolved link.

unresolved

Unresolved link.

implicit

Block resides in library block and is itself not a link to a library block. For example, suppose that A is a link to a subsystem in a library that contains a Gain block. Further, suppose that you open A and select the Gain block. Then, get_param(gcb, 'LinkStatus') returns implicit.

inactive

Disabled link.

Set LinkStatus ValueDescription
none

Breaks link. Use none to break a link, e.g., set_param(gcb, 'LinkStatus', 'none')

inactive

Disables link. Use inactive to disable a link, e.g., set_param(gcb, 'LinkStatus', 'inactive')

restore

Restores an inactive or disabled link to a library block and discards any changes made to the local copy of the library block. For example, set_param(gcb, 'LinkStatus', 'restore') replaces the selected block with a link to a library block of the same type, discarding any changes in the local copy of the library block.

This is equivalent to Restore Individual in the Links Tool.

propagate

Pushes any changes made to the disabled link to the library block and re-establishes its link.

This is equivalent to Push Individual in the Links Tool.

restoreHierarchy

Restores all disabled links in the hierarchy with their corresponding library blocks. This is equivalent to Restore in hierarchy mode in the Links Tool.

propagateHierarchy

Pushes all links with changes in the hierarchy to their libraries. This is equivalent to Push in hierarchy mode in the Links Tool. See Restore Disabled or Parameterized Links.

    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.

Break 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 Masking).

To break the link between a linked block and its library block, you can use any of the following actions.

  • Disable the link, then right-click the block and choose Library Link > Break Link .

  • At the command line, change the value of the LinkStatus parameter to 'none' using this command:

    set_param(gcb, 'LinkStatus', 'none')
    
  • Right-click and drag to copy a block, and you see an offer to break links, unless the parent library has LockLinksToLibrary set to on. If your copied block will be a locked link, then you do not see the option to break links.

    To copy and break links to multiple blocks simultaneously, select multiple blocks and then drag. Any locked links are ignored and not broken.

  • When saving the model, you can break links by supplying arguments to the save_system command. See save_system.

    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.

Fix 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 changes the appearance of these blocks.

If you double-click the unresolved block, the parameter dialog box displays an error similar to the following:

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

To fix an unresolved 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 Simulation > Update Diagram or Diagram > Refresh Blocks.

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

Was this topic helpful?