Simulink® Verification and Validation™

Linking to Custom Types of Requirements Documents

Why Create a Custom Link Type?

In addition to linking to built-in types of requirements documents as described previously, you can register your own custom types of requirements documents with the Requirements Management Interface, and then create requirement links to these types of documents.

Custom link types let you define how a document will be opened and navigated, and how you or another user can 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 Requirements Management Interface invokes the registered code when navigating to a document with the new link type, and 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 communicate 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 loading external applications.

Custom link types enable you to

• Link to requirement items in commercial requirement tracking software

• Link to in-house database systems

• Link to document types that are not internally supported in the tool

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. It 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

where mytargetfilename is the name of the MATLAB function contained in the M-file named mytargetfilename.m.

Once you register a link type, it appears as an entry in the Document type drop-down list in the Requirements dialog box. The list of registered link types is stored in a file in your preference directory, so it can be restored 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 registration name is saved in the model. When you attempt to navigate a link, the Requirements Management Interface resolves the link type against the registered list and displays an error message if the link type is not found.

Back to Top

Built-In Link Types

Built-in link types use the same format and naming convention as custom types, although they use a different system for identification in the model file that supports backwards and forwards compatibility. You can use the built-in types as examples when developing your custom link types. The files for built-in link types are contained in the private directory 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

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 can get and set the links on a block using the rmi command. Link information is encapsulated within 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 requirement interfaces. The document and ID fields of links uniquely identify the linked item in an external document. The Requirements Management Interface passes both of these string parameters to the navigation command of the associated link type when it follows a link from the model or a generated report.

Back to Top

Link Type Properties

Link type properties define how links are created, identified, navigated and stored within the requirement management tool. The following table explains 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 format, which is 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 double quotes (").

You provide the ability to see a document index, containing a listing of all the requirement items. When navigating from the Simulink model to the requirements document, the document opens in the MATLAB editor and pans the display to the line containing the desired requirement item.

Use the following procedure 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 file rmicustabcinterface.m, containing the function rmicustabcinterface that implements the ABC files, is included in the installation. You can view it below, or by typing edit rmicustabcinterface at the MATLAB prompt.

   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.4.3 $  $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

   This will cause the ABC file type to be added to the drop-down list of document types in the Requirements dialog box.

3. Create a text file with the .abc extension, containing several requirement items marked by the Requirement:: string, as described above. For your convenience, an example of such a file is included in the installation. It is named demo_req_1.abc, and is located in matlabroot\toolbox\slvnv\rmidemos. The contents of this file is displayed below.

   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 my_sf_car.

5. Right-click the Engine block and, from the resulting pop-up menu, select Requirements > Edit/Add Links.

   The Requirements dialog box appears.

6. Click New to add a new default requirement. Note that ABC file type is now available in the Document type drop-down list, as shown.

   

7. Set Document type to ABC file (for demonstration) and browse to the demo_req_1.abc file, or to your own .abc requirements file that you created in Step 3. Note that the browser shows only the files with the .abc extension.

8. Define a particular location in the document. In this example, you can either use a line number or a requirement name as the item identifier, so the location delimiters in the rmicustabcinterface function are specified as '>@'. As a result of this parameter, the Location drop-down menu contains these two items whenever the document type is set to ABC file, as shown.

   

Creating a Document Index

The example file format clearly defines requirement items that are easily listed. To generate a document index, set the ContentsFcn to a valid function. The MATLAB M-code uses file I/O functions to read the contents into a MATLAB variable. The Requirements Management Interface uses the regular expression utility in the MATLAB software to extract a list of requirement items that it returns.

The following code generates an index for the ABC files.

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 functions
  fList1 = regexpi(contents,'\nRequirement:: "(.*?)"','tokens');

  % Combine and sort the list
  items = [fList1{:}]';
  items = sort(items);
  items = strcat('@',items);

  locations = [items];
  labels = [items];
  depths = [];

For example, for the demo_req_1.abc file discussed earlier in Creating a Custom Link Requirement Type, this function generates the document index as shown in the following illustration.

Back to Top

Navigating to Simulink^® Models from External Documents

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

Providing Unique Object Identifiers

Whenever you create a requirement link for a Simulink or Stateflow object, a globally unique identifier is created for that object. This identifier is used to identify the object and will not change if the object is renamed or moved or when requirement links are added or deleted. Although the unique identifier is only used to resolve an object within a model, the identifier is globally unique and should not collide with identifiers in other models unless the two models derive from the same original model. Unique object identifiers have formats like GIDa_cd14afcd_7640_4ff8_9ca6_14904bdf2f0f.

Using the rmiobjnavigate Utility

The rmiobjnavigate function performs the required actions to identify the appropriate Simulink or Stateflow object, highlight that object, and bring the appropriate editor window to the front of the screen. When you navigate to a Simulink model from an external application, invoke this command. Internally this function creates a table of all the unique object identifiers within a model, which is used for efficient object lookup.

The first time you navigate to an item in a particular model, there may be a slight delay while the internal navigation table is constructed. Subsequent navigation should have minimal delay.

Determining the Navigation Command

Once you have created a requirement link for a Simulink or Stateflow object, you can find the appropriate navigation command string by using the rmi function at the MATLAB prompt. 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);

You need to 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

A special Microsoft^® ActiveX^® control is included with the Simulink^® Verification and Validation™ software and is used to enable linking to Simulink models from Microsoft^® Word and Excel^® documents. You can use this same control from 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 ToolTip of the control. The MLEvalCmd property is the string that is passed to the MATLAB software for evaluation when the control is pushed.

Typical Code Sequence for Establishing Two-Way Links

When you create an interface to an external tool, the procedure for establishing links can often be automated so that no dialog fields need to be manually updated. This type of automation is part of the selection-based linking that is implemented for certain built-in types, such as Microsoft Word and Excel documents.

In generic terms, use the following process:

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 and create a requirement link on the selected object using rmi('createempty') and rmi('cat').

4. Determine the MATLAB navigation command string that must be embedded 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 and set the MATLAB navigation command string in the appropriate property.

You can use the code for selection-based linking to the Word, Excel, and Telelogic^® DOORS^® software as an example of this type of automation. 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

Adding and Viewing Requirement Links

Viewing Objects with Requirement Links