Linking to Custom Types of Requirements Documents

Built-In Link Types

The files for built-in link types are in the private folder of the requirements management tool (matlabroot\toolbox\slvnv\reqmgt\private):

linktype_rmi_doors.m
linktype_rmi_excel.m
linktype_rmi_html.m
linktype_rmi_pdf.m
linktype_rmi_text.m
linktype_rmi_word.m

Built-in link types use the same format and naming convention as custom types. However, built-in link types use a different system for identification in the model file that supports backward and forward compatibility. Use the built-in link types as examples when developing your custom link types.

Back to Top

Why Create a Custom Link Type?

In addition to linking to built-in types of requirements documents, you can register custom requirements document types with the RMI. Then you can create requirement links to these types of documents.

Custom link types let you define how you open and navigate to a document, browse for a document, and view an index of its contents. When you define a custom link type, you create MATLAB M-code functions that perform these operations. The RMI invokes the registered code:

• When navigating to a document with the new link type that you created.

• When browsing for a document or displaying the index of a document within the Requirements dialog box.

Using the external interfaces supported by the MATLAB software, you can interface with external applications and run programs from the command shell. You can also use the built-in Web browser and text editor to display custom variants of HTML and text files without installing external applications.

With custom link types, you can:

• Link to requirement items in commercial requirement tracking software

• Link to in-house database systems

• Link to document types that the RMI does not support

Back to Top

Custom Link Type Registration

You register custom link types with a unique MATLAB function name. The function must exist on the MATLAB path and must not require any input arguments. The function must return a single output argument that is an instance of the requirements link type class. You can register your link type with the following MATLAB command:

rmi register mytargetfilename

mytargetfilename is the name of the MATLAB function in the M-file, mytargetfilename.m.

Once you register a link type, it appears in the Requirements dialog box as an entry in the Document type drop-down list. A file in your preference folder contains the list of registered link types, so you can restore it in new MATLAB sessions. You can remove a link type with the following MATLAB command:

rmi unregister mytargetfilename

When you create links using custom link types, the software saves the registration name in the model. When you attempt to navigate to a link, the RMI resolves the link type against the registered list. If the software cannot find the link type, you see an error message.

Back to Top

Link Properties

Requirement links are the data structures, saved in the Simulink model, that identify a specific location within a document. You get and set the links on a block using the rmi command. The RMI encapsulates link information in a MATLAB structure array. Each element of the array is a single requirement link.

Links and link types work together to perform navigation and manage requirements. The document and ID fields of links uniquely identify the linked item in external documents. The RMI passes both of these strings to the navigation command when you navigate a link from the model.

Back to Top

Link Type Properties

Link type properties define how links are created, identified, navigated to, and stored within the requirement management tool. The following table describes each of these properties.

feval(LinkType.NavigateFcn, Link.document, Link.id)

Back to Top

Creating a Custom Link Requirement Type

In this example, you implement a custom link type to a hypothetical document type, a text file with the extension .abc. Within a document, the requirement items are identified with a special text string, Requirement::, followed by a single space and then the requirement item inside quotation marks (").

Create a document index containing a list of all the requirement items. When navigating from the Simulink model to the requirements document, the document opens in the MATLAB Editor at the line of the requirement that you want.

To create a custom link requirement type:

1. Write a function that implements the custom link type and save it as an M-file on the MATLAB path. In this example, the M-file is rmicustabcinterface.m, containing the function, rmicustabcinterface, that implements the ABC files shipping with your installation. You can view it here, or at the MATLAB prompt, type edit rmicustabcinterface.

   function linkType = rmicustabcinterface
   %RMICUSTABCINTERFACE - Example custom requirement link type
   %
   % This file implements a requirements link type that maps
   % to "ABC" files.
   % You can use this link type to map a line or item within an
   % ABC file to a Simulink or Stateflow object.
   %
   % You must register a custom requirement link type before
   % using it. Once registered, the link type will be reloaded in
   % subsequent sessions until you unregister it. The following
   % commands perform registration and registration removal.
   %
   % Register command:   >> rmi register rmicustabcinterface
   % Unregister command: >> rmi unregister rmicustabcinterface
   %
   % There is an example document of this link type contained in
   % the requirement demo directory to determine the path to the
   % document invoke:
   %
   % >> which demo_req_1.abc
   
   %  Copyright 1984-2005 The MathWorks, Inc.
   %  $Revision: 1.1.8.2 $  $Date$
   
       % Create a default (blank) requirement link type
       linkType = ReqMgr.LinkType;
       linkType.Registration = mfilename;
   
       % Label describing this link type
       linkType.Label = 'ABC  file (for demonstration)';
   
       % File information
       linkType.IsFile = 1;
       linkType.Extensions = {'.abc'};
   
       % Location delimiters
       linkType.LocDelimiters = '>@';
       linkType.Version = '';             % not needed
   
       % Uncomment the functions that are implemented below
       linkType.NavigateFcn = @NavigateFcn;
       linkType.ContentsFcn = @ContentsFcn;
   
   
   function NavigateFcn(filename,locationStr)
     if ~isempty(locationStr)
         findId=0;
         switch(locationStr(1))
         case '>'
             lineNum = str2num(locationStr(2:end));
             openFileToLine(filename, lineNum);
         case '@'
             openFileToItem(filename,locationStr(2:end));
         otherwise
             openFileToLine(filename, 1);
         end
     end
   
   
   function openFileToLine(fileName, lineNum)
     if lineNum > 0
         err = javachk('mwt', 'The MATLAB Editor');
         if isempty(err)
            editor = com.mathworks.mlservices.MLEditorServices;
            editor.openDocumentToLine(fileName, lineNum);
         end
     else
         edit(fileName);
     end
   
   
   function openFileToItem(fileName, itemName)
     reqStr = ['Requirement:: "' itemName '"'];
     lineNum = 0;
     fid = fopen(fileName);
     i   = 1;
     while lineNum == 0
         lineStr = fgetl(fid);
         if ~isempty(strfind(lineStr, reqStr))
             lineNum = i;
         end;
         if ~ischar(lineStr), break, end;
         i = i + 1;
     end;
     fclose(fid);
     openFileToLine(fileName, lineNum);
   
   
   function [labels, depths, locations] = ContentsFcn(filePath)
     % Read the entire M-file into a variable
     fid = fopen(filePath,'r');
     contents = char(fread(fid)');
     fclose(fid);
   
     % Find all the requirement items
     fList1 = regexpi(contents,'\nRequirement:: "(.*?)"','tokens');
   
     % Combine and sort the list
     items = [fList1{:}]';
     items = sort(items);
     items = strcat('@',items);
   
     if (~iscell(items) && length(items)>0)
        locations = {items};
        labels = {items};
     else
        locations = [items];
        labels = [items];
     end
   
     depths = [];
   
   
   
   

2. To register the custom link type ABC, type the following MATLAB command:

   rmi register rmicustabcinterface

   The ABC file type appears on the Requirements dialog box drop-down list of document types.

3. Create a text file with the .abc extension containing several requirement items marked by the Requirement:: string. For your convenience, an example file ships with your installation. The example file is demo_req_1.abc and resides in matlabroot\toolbox\slvnv\rmidemos. demo_req_1.abc contains the following content:

   Requirement:: "Altitude Climb Control"
   
   Altitude climb control is entered whenever:
   |Actual Altitude- Desired Altitude | > 1500
   
   Units:
   Actual Altitude - feet
   Desired Altitude - feet
   
   Description:
   
   When the autopilot is in altitude climb
   control mode, the controller maintains a
   constant user-selectable target climb rate.
   
   The user-selectable climb rate is always a
   positive number if the current altitude is
   above the target altitude.  The actual target
   climb rate is the negative of the user
   setting.
   
   <END "Altitude Climb Control">
   
   
   
   Requirement:: "Altitude Hold"
   
   Altitude hold mode is entered whenever:
   |Actual Altitude- Desired Altitude | <
     30*Sample Period*(Pilot Climb Rate / 60)
   
   Units:
   Actual Altitude - feet
   Desired Altitude - feet
   Sample Period - seconds
   Pilot Climb Rate - feet/minute
   
   Description:
   
   The transition from climb mode to altitude
   hold is based on a threshold that is
   proportional to the Pilot Climb Rate.
   
   At higher climb rates the transition occurs
   sooner to prevent excessive overshoot.
   
   <END "Altitude Hold">
   
   
   
   Requirement:: "Autopilot Disable"
   
   Altitude hold control and altitude climb
   control are disabled when autopilot enable
   is false.
   
   Description:
   
   Both control modes of the autopilot
   can be disabled with a pilot setting.
   
   <END "Autopilot Disable">
   
   
   
   Requirement:: "Glide Slope Armed"
   
   Glide Slope Control is armed when Glide
   Slope Enable and Glide Slope Signal
   are both true.
   
   Units:
   Glide Slope Enable - Logical
   Glide Slope Signal - Logical
   
   Description:
   
   ILS Glide Slope Control of altitude is only
   enabled when the pilot has enabled this mode
   and the Glide Slope Signal is true.  This indicates
   the Glide Slope broadcast signal has been
   validated by the on board receiver.
   
   <END "Glide Slope Armed">
   
   
   
   Requirement:: "Glide Slope Coupled"
   
   Glide Slope control becomes coupled when the control
   is armed and (Glide Slope Angle Error > 0) and
    Distance < 10000
   
   Units:
   Glide Slope Angle Error - Logical
   Distance - feet
   
   Description:
   
   When the autopilot is in altitude climb control
   mode the controller maintains a constant user
   selectable target climb rate.
   
   The user-selectable climb rate is always a positive
   number if the current altitude is above the target
   altitude the actual target climb rate is the
   negative of the user setting.
   
   <END "Glide Slope Coupled">
   
   
   

4. Open the model aero_dap3dof.

5. Right-click the Reaction Jet Control subsystem and select Requirements > Edit/Add Links.

   The Requirements dialog box opens.

6. Click New to add a new requirement link. The Document type drop-down list now contains the ABC file (for demonstration) option.

   

7. Set Document type to ABC file (for demonstration) and browse to the demo_req_1.abc file. The browser shows only the files with the .abc extension.

8. To define a particular location in the requirements document, use the Location field.

   In this example, the rmicustabcinterface function specifies two types of location delimiters for your requirements:

   • > — Line number in a file

   • @ — Named item, such as a bookmark, function, or HTML anchor

   Note   The rmi reference page describes other types of requirements location delimiters.

   The Location drop-down list contains these two types of location delimiters whenever you set Document type to ABC file (for demonstration).

   

9. Select Line number. Enter the number 26, which corresponds with the line number for the Altitude Hold requirement in demo_req_1.abc.

10. In the Description field, enter Altitude Hold, to identify the requirement by name.

11. Click Apply.

12. Verify that the Altitude Hold requirement links to the Reaction Jet Control subsystem. Right-click the subsystem and select Requirements > 1. "Altitude Hold".

Creating a Document Index

A document index is a list of all the requirements in a given document. To create a document index, MATLAB M-code uses file I/O functions to read the contents of a requirements document into a MATLAB variable. Then the RMI extracts the list of requirement items.

The example requirements document, demo_req_1.abc, defines four requirements using the string Requirement::. To generate the document index for an ABC file, the ContentsFcn function, in the rmicustabcinterface.m file, extracts the requirements names and inserts @ before each name.

Note   To see the code for the ContentsFcn file, go to step 1 in Creating a Custom Link Requirement Type.

For the demo_req_1.abc file, in the Requirements: Engine dialog box, click the Document Index tab. The ContentsFcn function generates the document index automatically.

Back to Top

Navigating to Simulink Objects from External Documents

The RMI includes several functions that simplify creating navigation interfaces in external documents. The external application that displays your document must support an application programming interface (API) for communicating with the MATLAB software.

Providing Unique Object Identifiers

Whenever you create a requirement link for a Simulink or Stateflow object, the RMI creates a globally unique identifier for that object. This identifier identifies the object. The identifier does not change if you rename or move the object, or add or delete requirement links. The RMI uses the unique identifier only to resolve an object within a model. The identifier is globally unique and does not collide with identifiers in other models, unless the two models derive from the same original model. Unique object identifiers have formats such as:GIDa_cd14afcd_7640_4ff8_9ca6_14904bdf2f0f.

Using the rmiobjnavigate Function

The rmiobjnavigate function identifies the appropriate Simulink or Stateflow object, highlights that object, and brings the appropriate editor window to the front of the screen. When you navigate to a Simulink model from an external application, invoke this function. Internally, this function creates a table of all the unique object identifiers within a model for efficient object lookup.

The first time you navigate to an item in a particular model, you might experience a slight delay while the software constructs the internal navigation table. You do not experience a long delay on subsequent navigation.

Determining the Navigation Command

Once you create a requirement link for a Simulink or Stateflow object, at the MATLAB prompt, use the rmi function to find the appropriate navigation command string. The return value of the navCmd method is a string that navigates to the correct object when evaluated by the MATLAB software:

cmdString = rmi('navCmd', block);

Send this exact string to the MATLAB software for evaluation as part of navigating from the external application to the Simulink model.

Using the ActiveX Navigation Control

The RMI uses software that includes a special Microsoft ActiveX control to enable navigation to Simulink objects from Microsoft Word and Excel^® documents. You can use this same control in any other application that supports ActiveX within its documents.

The control is derived from a push button and has the Simulink icon. There are two instance properties that define how the control works. The tooltipstring property is the string that is displayed in the control ToolTip. The MLEvalCmd property is the string that you pass to the MATLAB software for evaluation when you click the control.

Typical Code Sequence for Establishing Navigation Controls

When you create an interface to an external tool, you can automate the procedure for establishing links. This way, you do not need to manually update the dialog box fields. This type of automation occurs as part of the selection-based linking for certain built-in types, such as Microsoft Word and Excel documents.

To automate the procedure for establishing links:

1. Select a Simulink or Stateflow object and an item in the external document.

2. Invoke the link creation action either from a Simulink menu or command, or a similar mechanism in the external application.

3. Identify the document and current item using the scripting capability of the external tool. Pass this information to the MATLAB software. Create a requirement link on the selected object using rmi('createempty') and rmi('cat').

4. Determine the MATLAB navigation command string that you must embed in the external tool, using the navCmd method:

   cmdString = rmi('navCmd',obj)

5. Create a navigation item in the external document using the scripting capability of the external tool. Set the MATLAB navigation command string in the appropriate property.

For example, you can use the code for selection-based linking to the Microsoft Word, MicrosoftExcel, and IBM Rational DOORS software. The files are contained in matlabroot\toolbox\slvnv\reqmgt\private:

selection_link_doors.m
selection_link_excel.m
selection_link_word.m

Back to Top

Navigating from Requirements Documents to Simulink Objects

Using the System Requirements Block in a Model

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