MATRIXx 8.0 Release Notes

NOTE: The term “inoperative” refers to a feature/capability that is known to be not working, but maybe visible in the product. Inoperative features are expected to be fixed in a future update release. A “deprecated” feature is one that was deliberately removed or has limited support just for compatibility. However, a deprecated feature is one that will likely be completely removed in a future release. Continued use of a deprecated feature is not recommended.

Version 8.0.1

This section describes important changes made for this release.

• Editor window(s) forced to save if any Simulation, AutoCode, etc. command is initiated.
• This is to maintain compatibility with customer SBA scripts that assumed this behavior and the lack of an explicit save command in SBA
• Condition SuperBlock
• Navigating to a procedure from a Conditional SuperBlock can only be done from the block’s context menu
• All procedures of the block are listed in the submenu, allowing you to choose any one to navigate into
• Property dialog fixed so that the referenced procedures are displayed within the Code tab.
• Command history added to the Editors’ Xmath Command Line Dock Window’s Xmath command line
• Use CTRL-UpArrow, CTRL-DownArrow keys to cycle through the history
• Improved memory utilization when using SBA scripts

Compiler Requirements for Xmath, Simulator and AutoCode

Configuring environment variables for C++ compiler [Windows]

Visual C++ should be configured for "command line compilation". Normally at the end of Visual C++ compiler installation you will be presented with a dialog "Setup Environment Variables". Check the box "Register Environment Variables" and finish the installation.

If you failed to do the above described configuration during installation, you will have to re-install the whole Visual C++ package to re-configure. However, there are some alternate ways you can set the environment for MATRIXx. See Setting the Environment for .NET 2003/2005 Compilation (UCBs and LNXs)  [Windows only].

FORTRAN Compiler Requirement [Windows]

Due to upgrading to the .NET 2003 suite, you must also upgrade the FORTRAN compiler to one that is compatible with .NET 2003. We recommend the Intel Visual Fortran Compiler 10.0 or later.

HyperBuild

This advanced simulation capability was found to be broken in the previous release. The issues have been resolved and now work as documented in its user guide, with the following addendums:

• The generated “hyperbuild model” with the name _HB_Model is no longer created as a component
• The _HB_Model and its additional SuperBlocks are loaded back into the current project
• These SuperBlocks are now exposed for editing but should not be modified nor should any of the contained blocks be copied and reused in another SuperBlock

UCB Compatibility

Compatibility with a simucb.dll built in v7.x [Windows]

A simucb.dll built in v7.x is automatically recognized in v8 by the Simulator tool and the simulator will use that DLL ‘as is’ for the purposes of simulation. The simucb.dll is treated as a “Manual” built UCB DLL, which means that it will not rebuild the UCBs to use it within v8. The simucb.dll will be rebuilt to the new format when the simucb.dll does not contain the UserCodeBlocks the simulation requires.

This capability facilitates moving between both v7.x and v8.0.x of the same simulation without any changes. Note however that a simucb.dll built by v8.0.x is not backward compatible with v7.x.

Project System

FileSuperBlock Compatibility

The FileSuperBlock is partially deprecated within v8.0 but due to compatibility requirements, it is partially supported. The following is a summary of the compatibility features present in this version.

• Existing FileSuperBlock objects loaded from a savefile now appear within the project system, just like other SuperBlocks
• A FileSuperBlock can be copied within the project or between projects, just like other SuperBlocks
• A FileSuperBlock can be removed or renamed, just like other SuperBlocks
• A FileSuperBlock can be dragged and dropped into a SuperBlock diagram editor and a reference block to that FileSuperBlock is created
• SBA can be used to create a reference block to FileSuperBlocks as it was in v7.x (e.g. createblock “filesuperblock”,{name=“actuator1”})
• Simulation including FileSuperBlock(s) works the same as in v7.x

The following capabilities are not supported in v8.

• Creating new FileSuperBlocks (other than copying or renaming existing ones)
• The SBLIBS SystemBuild default value is not recognized by the project system
• There is no ‘libraries’ folder from which to create FileSuperBlocks

If possible, we recommend transitioning your models away from using FileSuperBlocks. In future releases, there should be complete project system capability to do the kinds of things FileSuperBlocks were intending to do in a much more open and flexible paradigm. Eliminating a model’s FileSuperBlocks is relatively easy and there are at least three approaches you can take.

One approach is to obsolete your use of FileSuperBlocks completely and use the project system.

• Create an empty project
• Open (or import) the model savefile(s) containing the FileSuperBlocks.
• Open (or import) each of the files that were specified within the SBLIBS into the project system.  Upon loading, the project system resolves and updates all of the FileSuperBlocks to regular SuperBlock block references.
• Configure and save the new project
• By using the “open” method of loading the existing savefiles, you are configuring the new project to use that file as part of the project. If you use the ‘import’ method, the contents of the savefile are used and the existing savefiles are discarded (See project system documentation for more about ‘open’ and ‘import’)

The second approach is similar to the first approach, except that you don’t need a project, you save everything to a new savefile, essentially merging all of the diagrams into one.

• Create an empty project (do not configure it)
• Import the model savefile(s) containing the FileSuperBlocks.
• Import each of the files that were specified within the SBLIBS into the project system. Upon loading, the project system resolves and updates all of the FileSuperBlocks to regular SuperBlock block references.
• Right-click on the Diagrams folder and select save. This will save all of the diagrams into a single savefile.

The third approach is to keep the basic idea of FileSuperBlocks (i.e. models kept in separate files not normally loaded) within v8. You can ultimately use a project or not. This approach converts the FileSuperBlocks into regular superblocks, yet keeps them ‘undefined’ for later resolution. Note, this approach will require that for simulation all of the savefiles are loaded into the project system before simulation.

• Open (or import) the model savefile(s) containing the FileSuperBlocks.
• Open (not import!) each of the files that were specified within the SBLIBS into the project system. Upon loading, the project system resolves and updates all of the FileSuperBlocks to regular SuperBlock block references.
• Then, remove the folder(s) used to contain the diagrams that were opened from the files of the SBLIBS specification. By removing the diagrams, you now create undefined references to those diagrams which is the functional equivalent of a FileSuperBlock
• Save the original model savefile

Known Issue

• The length of the project’s name is not limited, but a name larger than 32 characters may cause errors when using SBA.
• Limit the length of the name you give a project to 32 characters or less.

Xmath

Changes worth mentioning:

• get({path=”xxx”})
• This Xmath command’s keyword returns the same result as v7.x, the difference between the v8.0.0 version was how the current working directory was handled
• A new keyword, absolute, is now recognized and if used will return the absolute path
• get({path=”xxx.txt”,absolute})  could return: “c:\workingdir\xxx.txt”
• Special consideration is required to handle Windows 8.3 conforming pathnames. When using this command, an 8.3 conformant path is expanded to its full name equivalent only when the ‘absolute’ keyword is used.
• In all other cases, when Xmath shows a path, it will be an absolute path that has been expanded to its full name equivalent.
• get({version})
• This keyword returns version information of Xmath in a usable form
• Return values representing separately the major, minor, patch and stage numbers of the product
• Example: [major,minor,patch,stage] = get({version})
• Return the major,minor,patch numbers in a vector
• Example: version = get({version})
• Return the major, minor, patch and stage numbers as a string
• Example: version = get({version,string})
• get({partition})
• Added partitions keyword to Xmath 'get' command for returning a StringMatrix or List of the names of the all Xmath partitions
• partitionStringMatrix = get({partitions,string});
• namesStringMatrix = get({variables,partition="mydata",string});
• new partition
• Creating an new partition no longer displays a message dialog (confirm error) if the partition already exists
• A fatal error is now generated if the specified partition already exists
• When used in a script, we recommend that you test for the existence of the specified partition before executing the command
• Example: if !exist("testdata",{partition}), new partition testdata; endif;
• Added compass angle orientation for polar plots where 0 degrees is at 12 o'clock and angle increases clockwise where as a normal polar plot has 0 degrees at 3 o'clock and angle increases counter-clockwise.
• plot(ang,r,{polar=1} # Normal polar plot
• plot(ang,r,{polar=2} # Compass polar plot
• Update the 3rd party HOOPS graphics library from version 13.10 to 15.10 to fix various display update and hardcopy problems. The HOOPS graphics libraries are the graphics engine used to render graphics for plot and plot2d commands.
• The Xmath getenviron lnx function has been changed to a msf (MathScriptFunction) which internally uses the built-in function get({environment=name}).
• Added Xmath environment variable MathScriptCommands
• setenviron {name,value}
• unsetenviron {name}
• showenviron {name}.
• Added Xmath string manipulations functions split, join, upper and lower, see their corresponding MSF files for syntax and usage details.

Xmath Processor Affinity [Windows]

We removed the hard-coded limitation on processor affinity for the Xmath server process. Tests show that multiple Xmath sessions properly utilize multiple cores/processors. As a result, spawned processes from the Xmath session (e.g. sim) will run on multiple cores/processors.

PGUI

Small changes worth mentioning:

• uiFileSelection
• The ‘value’ keyword can be a path, complete pathname (path and filename) or just a plain filename. When a path is specified, dialog will start in the specified path. If a plain filename is specified, the Xmath’s current directory is used as the starting directory and the filename is the default filename in the dialog. Also, if ‘value’ is empty or incorrect path, or not specified, Xmath’s current working directory is used and no default filename is given.
• The ‘flags’ keyword has a new flag, “d”, which is to prompt the user to select a directory.  When this option is used, ‘value’ should be a path or complete pathname (in which case the filename is ignored). Also, the ‘pattern’ keyword is ignored.

PGUI Issue

There are a couple of PGUI commands that use a modal dialog to prompt the user for input. In some cases, when the command is used without any other PGUI windows, the dialog window will appear behind the IDE’s windows. A work-around is to create a PGUI window before prompting for a file. (This applies to uiPrompt as well). The following is a portion of a script which shows creating the PGUI tool and window before calling the uiFileSelection command.

alias T "getfile"

## created a tool context and a window to ensure fileselect is 'on top'

void = uiToolCreate(T);

uiWindow(T, {name="xx",title="",visibility=1,height=0,width=0,xr=0,yr=0});

result = uifileselection(T, {pattern = "*,*", flags="o", title="Select File", value="c:\program files\"});

display result

# destroy the tool

uiDestroy(T);

It’s important to note that this issue only appears when there are no other PGUI windows yet created. Thus, a typical PGUI mathscript command does not have this GUI issue as there would likely be a ‘main window’ created before any file selection or other prompt occurs.

SystemBuild

Changes worth mentioning:

• Interactive Animation Blocks can now be created and modified using SystemBuild Access scripting. This enables exporting SuperBlocks with IA blocks without losing data.
• Interactive Animation Block Dialogs in SystemBuild have been updated to be consistent with native SystemBuild Dialogs by having a Parameter, Input, Output and Display tabs.

SBA

A new command was added to SBA.

• DELETEPROJECTFOLDER
• Deletes a whole folder within the project system, equivalent to the ‘remove’ right-click menu item action
• All diagrams and subfolders are also deleted
• This option accepts only one argument, the name of the folder
• The first folder matching the name of a subfolder within the Diagram folder is the one deleted
• This command is temporary in that it is expected that more complete and detailed project folder manipulation will exist in a later version
• The need for this command is to help script a capability that’s equivalent to FilesSuperBlock behavior.

Version 8.0.0

The following items are not in the 8.0 release. We are planning to include these features in a subsequent release.

• Built-in source code control
• Components
• Xmath 3D matrix

Notes on MATRIXx IDE Application

• The MATRIXx IDE can be started from the command line, but you must use the launching script in the common bin directory $MATRIXX\bin\matrixx.bat, where $MATRIXX is the installation directory.
• Command line options are supported. These options can be specified as options to the batch script but it is preferred to use the standard Windows application shortcut with the additional command line options specified in the Target field.

o Specify the name of a solution, project file, SystemBuild model file or Xmath data file (.xmd only) to load.

§ Example: $MATRIXX\bin\matrixx.bat c:\proj\engine_project.proj-mtx

o The option –newproject creates an new project with the name “Empty Project”

§ Use –newproject=name to create a new project with the specified name.

§ Use –newproject=name,modelfile to create a new project with the specified name and the model file loaded into it.

· example: -newproject=Engine,c:\projects\engine.sbd-mtx

§ If the name or modelfile contains spaces, you must quote the whole option, for example “-newproject=Cruise Control”

Notes on the Project System

Some additional notes regarding the project system are listed below.

• Cut/Copy/Paste of objects (SuperBlocks, STD, etc) is inoperative. Copy and paste functionality can be achieved using the one of the following techniques.
• Use the SBA command COPYPROJECTOBJECT to copy an object to another name
• Example: copyprojectobject “controller logic”, “copy of controller logic”
• Open the object for edit; select the Update As menu from the primary menu (the first menu, usually with the same name as the type of object being edited) of that editor; enter in a unique name for the object; continue editing as desired
• The “undo” system is inoperative; it is recommended, therefore, to not disable the delete confirmation dialog
• Drag and Drop from the project system is operational
• Drag any object from the project system and drop it into a SuperBlock editor window to create a reference block to that object within that editor
• If that object is inappropriate for that kind of SuperBlock, (i.e. a Procedure SuperBlock can’t be referenced within a Continuous SuperBlock), the drop is not allowed and the cursor changes to the “disallowed” cursor
• Dragging multiple objects into the editor will create a separate reference for each object
• Drag any project object from one folder within a project and drop it into another folder
• Multiple objects from different folders can be dropped at the same time
• If an object is dropped into a folder within the same project, this is effectively a ‘move’ operation between two folders. You can never create two objects of the same name within a project
• If an object is dropped into a folder within a different project, this is effectively a ‘copy’ operation. The object will remain in the project where it was dragged from and a new object created within the project being dragged into.
• If there is already an object the same name, you will be prompted to overwrite the existing object or not
• GUI note about dropping.
• When dropping within a project, the GUI may display feedback of an ‘insert bar’ between items within the view tree
• The insert bar is meant to allow you to change the order of the objects within the folder.
• The project system automatically orders the objects in the tree, therefore you can’t change the order within a folder
• There is no way to turn off the insert bar feedback in the current version of our GUI package.
• You can not drag objects between the different views of a project
• The Model Hierarchies view only supports drag and drop into a SuperBlock editor. You can not change the model hierarchy using drag and drop techniques
• UserTypes (within the Data Dictionaries view) can not be dropped into an editor window

Xmath Data and the Project System

The project system treats Xmath data as foreign data to some extent. You are responsible to decide how to save the Xmath variables and there are several ways to accomplish this task. Experienced users tend to save multiple data files of Xmath data. Sometimes, startup scripts or other scripts manually executed perform the loading and saving tasks needed for a model. Another way to help with this issue is to use the project system and configured projects. A configured project offers startup, closedown and data save features.

When enabled, the data save occurs when the project closes, i.e. when it is removed from the solution, the solution is closed or the application closes. This save is not related to the save of the project. The Xmath data save feature of the project system may not be suitable under all circumstances because it is effectively a ‘blind’ save of the data in Xmath when the project closes. More complicate data arrangements may require the use of the closedown script feature to better selectively save data. In some circumstances maybe only you can judge when to save the Xmath data, therefore you must initiate the save manually.

Xmath data files saved with the .xmd file extension are recognized by MATRIXx. If you double-click on this kind of file from the Windows desktop, MATRIXx IDE will start and a new empty project will be created with the data file loaded into the Xmath session. Also, if you add a file with the .xmd extension into a project’s Files folder, you can select one or more of those kinds of files, right-click and select the Load Xmath Data menu option, which will load the files into the project’s Xmath session.

We are desirous of customer feedback on how Xmath data should be managed by the project system to better assist your day-to-day use of the product. In future updates of MATRIXx, we expect to reflect our customer’s needs in this area of the product.

Notes on the SystemBuild Editor

The new editor is quite a departure from the previous one. It conforms to “standard” Microsoft Windows behaviors:

• Cut/Copy/Paste  within and between editor windows and between third-party applications, such as Microsoft® Word/PowerPoint documents

• Resize handles on all objects to use dragging to resize them
• CTRL-drag to duplicate an object
• “Quick connect” Wiring Tool Feature
• Connect a single output to a single input without needing the Connection Editor
• Move the wiring tool within the a block to highlight the output pin as the source of the connection; click and drag to the input block and move the tool within that block to highlight the input pin; click again to finalize the connection
• You can add or replace a connection using this method
• Hold down the <CTRL> key when clicking to finalize the connection to use the Connection Editor to make the connection
• Quick connect only works if both input and output pin modes are Scalar mode
• Connection Editor
• Drag and drop connections
• Easier complex wiring (e.g. by dragging groups of outputs to groups on inputs)
• Please refer to the online help for more about using the Connection Editor

Short-cut Keys

The following table contains the short-cut key sequences supported within the SystemBuild editors. The table uses a common Windows notation for describing key sequences. For example, “Ctrl+X” means pressing both the <Ctrl> key and <X> key simultaneously.

Key Sequence	Meaning	Selection Sensitive	SuperBlock	STD	UDT	DataStore
Ctrl+X	Cut to clipboard	ü	ü	-	-	-
Ctrl+C	Copy to clipboard	ü	ü	-	-	-
Ctrl+V	Paste from clipboard		ü	-	-	-
Ctrl+S	Update into project		ü	ü	ü	ü
Ctrl+P	Print	ü	ü	ü	-	-
Ctrl+W	Close		ü	ü	ü	ü
Delete	Delete	ü	ü	ü	-	-
Alt+D	Toggle normal/reverse block direction	ü	ü	-	-	-
Alt+F	Fit diagram to display in window		ü	ü	-	-
Alt+Shift+F	Normal size (100% zoom)		ü	ü
Alt+H	Show/hide block ID	ü	ü	-	-	-
Alt+I	Cycle input pin mode	ü	ü	-	-	-
Alt+L	Show/hide output labels	ü	ü	-	-	-
Alt+N	Cycle name location	ü	ü	-	-	-
Alt+O	Cycle output pin mode	ü	ü	-	-	-
Alt+R	Cycle block rotation	ü	ü	-	-	-
Alt+T	Cycle icon types	ü	ü	-	-	-
Alt+Shift+I	Connection Editor to connect to external inputs	ü	ü	-	-	-
Alt+Shift+O	Connection Editor to connect to external output	ü	ü	-	-	-
Alt+Shift+B	Connection Editor between two blocks	ü	ü	-	-	-
Alt+=	Enlarge (increase zoom) diagram view		ü	ü	-	-
Alt+-	Reduce (decrease zoom) diagram view		ü	ü	-	-

Setting the Environment for .NET 2003/2005 Compilation (UCBs and LNXs)  [Windows only]

The MATRIXx Simulator tool and Xmath cooperate in automatically compiling and linking UserCode block source files and your LNX executables. This requires that the environment to run the Microsoft®.NET compiler is properly configured. The environment must be setup before starting the MATRIXx IDE. The following techniques are the recommended ways to accomplish this task.

• Run from a correctly configured cmd shell
• The .NET product provides a way to quickly create a cmd shell that is properly configured to run its compiler tools. There is shortcut, generally found at Start»All Programs»Microsoft Visual Studio .NET 2003»Visual Studio .NET Tools»Visual Studio .NET 2003 Command Prompt.
• There is usually a batch script that will setup the environment, vsvars32.bat, and it is generally located at: C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Tools\vsvars32.bat.
• After creating a properly configured shell, start the MATRIXx IDE from the command line. See Notes on MATRIXx IDE Application.
• NOTE: this approach does not allow for you to utilize launching the MATRIXx IDE from the Windows Explorer, such as double-clicking a shortcut to the application or double-clicking one a MATRIXx IDE savefile. The tool will work, but the environment will not be augmented for the .NET compilation.
• Change your user account’s environment variables
• This approach requires you to figure out the environment variables needed by .NET (examine the vsvars32.bat file) and add them into your account’s settings.
• This approach will make launching the MATRIXx IDE from the Windows Explorer have the correct .NET environment
• To change the environment variables, use the System Properties Control Panel Tool and select the Advanced Tab and press the Environment Variables button. Then, use that dialog to change the settings.
• In general, expect to add/modify at least the PATH, INCLUDE and LIB environment variables, but there maybe more.

Notes on PGUI

The underlying graphical system of Xmath's Programmable Graphical User Interface (PGUI) has been completely replaced with a new GUI layer. As a result, the graphic look of PGUI windows is now more modern and consistent with the specific platform being run on. However, the new graphical system has exposed many design flaws in the PGUI scripting language. As much as possible, we've matched the old behavior, but in many cases, it's not possible to match, as the old behavior was wrong, crashed, or non-existent. The scripts will work 'as is'. But, you may need certain 'tweeks' to make the UI look better.  The PGUI scripts within Xmath have been updated, so you can use those as examples.

Here's some of the issue that were discovered that may help you updating your scripts:

• All windows are FIXED in size, i.e. they are not resizable, by default. To make a window proportionally resize, change the window's type to resize.
• The geometry flags of child widgets within a table now work properly. Use these to help get better proportional sizes and restrictions, when needed.
• Width/height specifications of a child widget of a table are NOT absolute sizes. These are taken as proportions of the size of the table cell. The absolute sizes work, but changing a size of a child may not affect its size in the table, unless the proper geometry flags are used.
• Tables have a 1 pixel border that takes up part of the total size of the widget. In some nested table cases (tables within tables), a slight change to the width of the nested table was needed to get the border to show properly.
• The close box should ALWAYS be connected to the script's "close fragment". Use the "xmath_cancel=<frag>" keyword of the uiWindow to enable this feature.
• When using a table, try not to use explicit heights/widths of the child widgets. The table will automatically equally divide the rows and columns within the size given for the table, but some width specification maybe needed in at least one child per row and per column.
• A new child geometry flags added: 'm' : horizontal center; 'v' : vertical center;  'c' : center of cell ('equivalent to specifying 'mv'); 'j' horizontally justified.
• Label alignment flags added: m,v,j (see description of child geometry flags above)
• The alignment flags of "l r m j' can be combined with 't b v'. For example, 'lv' would be 'left side and vertically centered'.
• A Table widget should always have height/width specifications, unless it is nested within a table cell.
• When used in a table, label, separator and button widgets should not normally need height/width specifications.
• When used in a table, the uiVarEdit widget should have a height specified. Without it, the widget may be excessively large because the table cell size will take on the distributed size as computed by the table, which is based on the total number of rows in the table and the table size.
• Separators should only be used in tables.
• A Separator configured as vertical should have a width specification of 1.
• For all panels (other than the first panel) added into a Tab widget, the panel should be configured with visibility=0 to avoid initial display overlap.
• Some HTML keywords are recognized: line break (<br>); bold (<b>); italic (<i>); etc., within label text is recognized.
• The uiSlider automatically recomputes the min/max if the value is specifically set to a value outside of the current min/max. When the min, max and/or value attributes are associated with Xmath variables, it is not recommended that you try to override the built-in algorithm for the recomputation of min and max. The reason is that you might create a cycle in the updating of the Xmath variables and the values of the slider.
• Use of uiPrompt, uiGetValue, uiMessage may create a modal dialog that is not visible to you. It is actually behind the IDE window and can be accessed by moving the IDE window, minimizing it, or selecting the dialog from the Windows start bar.
• Widgets added into a uiPanel are automatically placed into a horizontal layout. If you need to layout widgets within the panel, use a uiTable added as the only widget into the panel, then add the other widgets into the table.

Notes on SBA

Having to make SBA work within the new framework, required us to make some changes and additions to SBA commands. It also allowed us to fix a lot of discrepancies between documentation and actual behavior and command inconsistencies. Below are the changes that might create some migration issues or are worth noting because of a difference in behavior.

General information about SBA changes is listed below:

• Creating an object (SuperBlock, StateTransition) will first create an empty object in the project with the specified name, then opens the object for further editing.
• For a configured project, SBA will create a new object within the Diagram folder.
• For an unconfigured project, SBA will try to create a new object within the first folder contained within the Diagram folder that is associated with a file. If there is no such folder, the new object is placed into the Diagrams folder.
• For commands and functions that do not require to name the object being operated on, those use "the current object". This used to be called the "currently edited" SuperBlock (or STD). The change is that SBA now does not change its current object simply by opening a diagram from the project system or clicking to bring front-most an already opened diagram editor window. So, there must be a command used to set SBA's current object explicitly.  Here are the possible ways to set the current object.

o Use the EditCatalog command and specify the object to be the current object.

o The CREATESUPERBLOCK, CREATESTD, CREATEUSERTYPE set the current object to be the new object just created.

o Specifying an object name for the MODIFYSUPERBLOCK, MODIFYSTD, MODIFYUSERTYPE commands set the current to the specified object.

• Using the Xmath Command Line within a SuperBlock and STD editor window will set that diagram as the current object when ANY command is issued from that command line window.
• For all the query function variants, those WILL NOT change the current object. Also, when object name is not specified for the query function, if the current object is not defined or is not of the appropriate type, query functions do not report an error, by convention. For example, [a=inputs]=querysuperblock() would not return an error, while [a=inputs]=querysuperblock("xyz") would return an error (assuming xyz did not exist or was not a SuperBlock).
•  All Component related SBA commands are not available (inoperative) in v8.

Specific issues regarding SBA commands are listed below.

• CREATESUPERBLOCK, MODIFYSUPERBLOCK
• InputNaming has a different meaning. It will no longer copy input labels. Rather, it just sets the display mode for the SuperBlock regarding where to get its input labels.
• Name, when used to modify a SuperBlock, immediately affects the project. When a new name is given to a SuperBlock, the current data is saved (under the old name) then immediately renamed to the specified name. Finally, the renamed SuperBlock is opened for continued editing.
• Newwindow can never be used to create multiple editors to the same object.  An exact same set of names is used.  Here is that.
• UserParameterName can be 'updated in place' only if the same names are used. If not you will get an error. If not the same set of names, you have to explicitly 'clear' all names (setting UserParameterName to an empty array) before setting your new parameter names.
• Window is now a query-only keyword. The row-vector result is the left,bottom,right,top coordinates of a rectangle containing of all blocks within the diagram (extent bounds).
• MaximumFontSize is deprecated.
• CREATEUSERTYPE, MODIFYUSERTYPE
• The UserType editor is never opened as a result of these commands.
• When no keywords specified, the datatype is configured as 'float'.
• These commands never affect the 'current object' of SBA.
• Previously undocumented keywords:
• Datatype
• A string identifying the type, "float","logical","integer", and for fixed point, use the pattern {signed,unsigned}{byte,short,long}, example "signedlong"
• Radix
• An integer indicating the radix of the fixed-point type.
• QueryUserType
• Previously undocumented function. Use similarly to other query commands.
• Using the keywords from CREATEUSERTYPE, you can extract information out about a UserType.
• There is no queryusertypeoptions function.
• QueryCatalog
• Previously undocumented input keywords:
• toplevel   (Boolean values accepted)
• Select only top-level SuperBlocks for querying
• catalogtype   (possible values: "SuperBlock", "STD", "DataStore", "UserType", "Any")
• Select only catalog objects of the specified type for querying
• opened  (Boolean values accepted)
• Select only objects with open editors for querying
• Previously undocumented output keyword:
• dtvalues
• For UserTypes only, return its datatype number, which is an internal encoding the datatype
• The order and scope keywords were previously deprecated in an earlier release and remain deprecated.
• The results of the parents keyword returns a project path string. That is a string consisting of the project name slash objectname, as in 'project1\engine controller'.
• CREATEBLOCK, MODIFYBLOCK
• A size value of [0,0] for a block indicates that it is the 'editor's default size'.
• The location keyword specifies the top-left coordinate of the block boundary, if size=[0,0].
• When the block is contained within a IfThenElse or While Block, the block's specified location is relative to the container block. This is a significant change from the past as previously all locations were absolute coordinates.
• If the type of block is datastore, the DataStore catalog object is immediate affected. As a result, all other references to the modified DataStore get updated along the way.
• Thus, if you need to make a change to a DataStore object, you have to make the change to one of its reference blocks.
• CREATEBLOCK
• If location keyword not specified, a location is chosen based on the block's ID. If no ID was specified, the ID is the next available ID starting with 1.
• The default size of the block is no longer 80x80. The exact default size is a chosen by the editor. It is possible that in the future the default size maybe a user-configurable value.
• The default grid used to create the default location of a block is changed. The starting block position for block ID 1 is 64,0 and increments left to right, top to bottom in increments of 64 units.
• When creating a block and neither location nor size keywords specified, the block size is the editor's default ([0,0]) and the location is computed and that represents the top-left coordinate of the block's boundary.
• QueryBlock
• Querying for size may return [0,0] indicating that the block's size is currently the 'editor default' size. This value occurs when you create a block and a specific size is not specified or when you create a block via the palette or context menu.
• The location keyword returns the top-left coordinate of the block boundary, if its size=[0,0]. Once a specific size is assigned, the location will then reflect the bottom-left coordinate.
• When the block is contained within a IfThenElse or While Block, the block's specified location is relative to the container block. This is a significant change from the past as previously all locations were absolute coordinates.
• EXPORTBLOCK
• Does not properly handle the position of contained blocks with IfThenElse and While blocks.
• The connections to the output-side of the IfThenElse container are not generated at all.
• CREATECONNECTION, MODIFYCONNECTION
• The arrowstyle,linestyle,showinputsignals keywords are inoperative.
• QueryConnections
• The arrowstyle,linestyle,showinputsignals keywords are inoperative
• The query-only keywords simple,xystart,xyend,ycrossover are deprecated
• CREATESTD
• The newwindow keyword can never be used to create multiple editors to the same object.
• MODIFYSTD
• The name keyword immediately affects the project. When a new name is given to a STD, the current data is saved (under the old name) then immediately renamed to the specified name. Finally, the renamed STD is opened for continued editing.
• CREATESTD, MODIFYSTD
• The maximumfontsize keyword is deprecated.
• The window keyword is now a query-only keyword. The row-vector result is the left,bottom,right,top coordinates of a rectangle containing of all bubbles within the diagram (extent bounds).
• QuerySTD
• The maximumfontsize keyword is deprecated.
• Added superbubbleorder keyword which returns the depth-first order of SuperBubbles (by ID) in the diagram.
• The following query-only keywords are deprecated:
• ActivatingBubble, ActivatingTransition
  DeactivatingBubble, DeactivatingTransition
  ExtInLocations, ExtOutLocations
  Level, SuperBubble, DisplayedBubbleList
• QueryBubble
• Added childbubbles keyword which returns bubble ids that are proper children (i.e. bubbles of a SuperBubble) of the SuperBubble.
• Added expanded keyword which returns expanded state of the bubble, if it is a SuperBubble.
• MODIFYBUBBLE
• Added expanded keyword which sets the expanded state of the bubble, if it is a SuperBubble    
• DELETEBUBBLE
• The transitions keyword is depreciated and ignored.
• If a SuperBubble is specified, it will now be deleted as well as all of its contained bubbles and transitions. Use ExpandSuperBubble if you want to just remove the SuperBubble container and keep its contents.
• Added command COPYPROJECTOBJECT - copy any named object to another name (indifferent to type of object, SuperBlock, DataStore, STD, UserType)
• COPYPROJECTOBJECT, COPYDATASTORE, COPYSTD, COPYSUPERBLOCK commands
• If 'fromName' is open in an editor, the content of the editor is copied. There are no side-effects to the command, unlike in v7, where the content of the editor was saved before the copy commenced.
• You can use these commands to copy between projects using a project path, like: copystd "xyz","proj2\xyz", as long as both projects are not removed during the copy process.
• The new object is located in the same folder as the source object, if copying within the same project. If copying between projects, the new object will go into the 'Diagrams' folder in the destination's project.
• COPYDATASTORE, COPYSTD, COPYSUPERBLOCK
• Will likely be deprecated in a future release. Use the more general-purpose COPYPROJECTOBJECT command instead.
• There was never a copy command for UserTypes and one will not be created.
• Added command DELETEPROJECTOBJECT - delete any named object in the project. (Indifferent to type of object)
• DELETEPROJECTOBJECT , DELETEDATASTORE, DELETESTD, DELETESUPERBLOCK, DELETEUSERTYPE
• Commands have a keyword, quiet, which suppresses any error messages.
• Specifying the command with no arguments will not delete all objects of that type. (Documentation error)
• You can not specify a string matrix as documented (documentation error). You must assign an xmath variable to the string matrix and then pass that variable to the command.
• DELETEDATASTORE, DELETESTD, DELETESUPERBLOCK, DELETEUSERTYPE
• Will likely be deprecated in a future release. Use the more general-purpose DELETEPROJECTOBJECT command instead.
• Added command RENAMEPROJECTOBJECT - rename any named object in the project. (Indifferent to type of object)
• RENAMEPROJECTOBJECT, RENAMEDATASTORE, RENAMESTD, RENAMESUPERBLOCK
• The 'To' object must be specified with the same project as the 'From' object. In other words, you can not use these commands as a copy between projects.
• You can rename an object in another project.
• Renaming an object currently open in an editor will not result in saving of the pending changes of the editor. The editor will just take on the new name of the object
• RENAMEDATASTORE, RENAMESTD, RENAMESUPERBLOCK
• Will likely be deprecated in a future release. Use the more general-purpose RENAMEPROJECTOBJECT command instead.
• MAKESUPERBLOCK, EXPANDSUPERBLOCK are inoperative.
• SBAdisplay
• The refresh, header and hide keywords are ignored and likely deprecated in a future release.
• The normal keyword effectively sets the magnification factor to 1.0 (100%)
• QueryBrowser, MODIFYBROWSER
• Deprecated; scripts report a warning if used.
• PRINTMODEL
• Inoperative, could be deprecated unless a customer need is determined.

Notes on Xmath

Console Visibility

The Xmath Server process is a console application. By default, the Server's console window is not shown when running MATRIXx. You may show  or hide  this console window using the following commands.

show console

hide console

These commands may be placed in one of your startup.ms scripts.

User and Home Directory Information

Xmath expands environment variables when in constructs a filename for any of its commands or functions that expect a filename.

Xmath also expands '~' (local home directory) and '~user' (for a user's network home directory). This capability is typically used on UNIX systems; however, Xmath extends it use for the Windows user.

In the following description, the rules for the Windows platform (as shown below) use environment variables delimited by '%' characters. On a UNIX platform, these rules will not be used. In place of these rules, Xmath, on the UNIX platform, will use the information returned from the getpwnam_r() system call.

To show your user settings type the following.

show user

On Windows, the command displays the following for "MySelf", the current logged in user.

Setting username to MySelf

1. $HOME = U:\MySelf

2. %HOMEDRIVE% = C:, %HOMEPATH% = \Documents and Settings\MySelf

3. %USERPROFILE% = C:\Documents and Settings\MySelf

Home directory is set to U:\MySelf

1. $SHELL = c:\vendors\hamilton\v2.2.116\bin\csh.exe

2. %ComSpec% = C:\WINDOWS\system32\cmd.exe

Command shell is set to c:\vendors\hamilton\v2.2.116\bin\csh.exe.

NOTE: Xmath's oscmd uses C:\WINDOWS\system32\cmd.exe by default.

Note that it also shows the process by which Xmath chooses the home directory and command shell. It uses $HOME and $SHELL, respectively. This means that you can control the interpretation of '~' in a filename by setting $HOME. If you do not set $HOME, Xmath looks at the standard environment variables (or system calls) for the platform.

Xmath does not use the command shell setting. It does maintain the setting for you in case you want to code your scripts to use it. Xmath expands '~user' according to different rules. It refers to this expansion as the network home directory for the user.

For example, the following command can show the expansion of the current user, '~MySelf'.

show user "MySelf"

Setting username to MySelf

1. $NETHOME =

2. %HOMESHARE% = \\<host>\Users\MySelf

3. $HOME = U:\MySelf

4. %HOMEDRIVE% = C:, %HOMEPATH% = \Documents and Settings\MySelf

5. %USERPROFILE% = C:\Documents and Settings\MySelf

Home directory is set to \\<host>\Users\MySelf.

1. $SHELL = c:\vendors\hamilton\v2.2.116\bin\csh.exe

2. %ComSpec% = C:\WINDOWS\system32\cmd.exe

Command shell is set to c:\vendors\hamilton\v2.2.116\bin\csh.exe.

NOTE: Xmath's oscmd uses C:\WINDOWS\system32\cmd.exe by default.

Note that in this case, it uses $NETHOME as the override. If you set $NETHOME, it will use that for the parent directory for your user home directories. Otherwise, it will consult with the platform specific environment variables. On Windows it may use %HOMESHARE%. If neither the $NETHOME or %HOMESHARE% environment variables are set '~user' defaults to '~' for the currently logged in user.

You can use the '~user' path for other users in your network. If you use it on another user, it can only expand the path using the network home directory rules.

show user "OtherUser"

Setting username to OtherUser

1. $NETHOME =

2. %HOMESHARE% = \\<host>\Users\OtherUser

Home directory is set to \\<host>\Users\OtherUser.

Command shell is set to C:\WINDOWS\system32\cmd.exe.

If user "bob" tells you to load a model from his public directory, you might type in something like the following.

load "~bob/public/model.xmd"

The Xmath get function has been extended to support the user information.

shell = get ({user, shell})  # command shell for the current user

home = get ({user, homedirectory})  # local home directory for the current user

home = get ({path="~"})             # equivalent

home = get ({user="name", homedirectory}) # network home directory for the user

home = get ({path="~name"})               # equivalent

Startup Script Details

Xmath executes various startup.ms scripts when it launches. The startup scripts are located in the following places.

(1) startup.ms files in the directories specified with $XMATH_STARTUP

a. $XMATH_STARTUP is an environment variable which contains a comma or semi-colon separated list of directories. Each path element in this list may be encoded to use environment variables lending more levels of indirection.

b. There is no limit as to how many directories can be specified in the $XMATH_STARTUP environment variable.

c. Xmath may augment your definition of  $XMATH_STARTUP with additional required directories that contain  startup.ms  files.

(2) ~/xmath/startup.ms

a. Xmath also looks for a startup under the  xmath  subdirectory under the current logged in user's local home directory. (See the discussion on show user).

(3) ./startup.ms

a. Finally, Xmath will execute a startup.ms in the current directory from which Xmath was launched. If MATRIXx was launched from a command shell, the current directory is managed by the command shell.

b. For Windows users, the current directory can be managed by a Windows shortcut wherein it manages a "Start in" property.

To provide visibility into the startup process, Xmath provides the following command.

show startup

# Processing startups in getenv("XMATH_STARTUP"):

# (XMATH_STARTUP is delimited with commas or semicolons)

     execute file="$SYSBLD\etc\startup.ms";

# Processing startup in directory: "~/xmath"

     execute file="~\xmath\startup.ms";

# Processing startup in directory: "."

     execute file=".\startup.ms";

Enhancements to oscmd

Xmath's oscmd function has been enhanced. For compatibility with previous versions of Xmath, oscmd uses %SystemRoot%\system32\cmd.exe as the command shell for Windows. On UNIX, it uses /bin/csh. You can now specify the shell keyword to have oscmd issue the command to a particular shell.

On Windows, you can produce a directory listing with the following commands.

oscmd ("dir");   ## using the default shell

oscmd ("dir", {shell="c:\windows\system32\cmd.exe /Q /C"});  ## equivalent

On UNIX, you would produce the directory listing with the following command.

oscmd ("ls");   ## using the default shell

oscmd ("ls", {shell="/bin/csh -f -c"});  ## equivalent

When filenames have spaces in them and/or when the OS command to be issued has arguments which have quoted strings, you may want to specify an argument vector to oscmd.

## Send an ARG Vector to CreateProcess

oscmd ([ "cmd.exe", "/Q", "/C", "dir", "*.bat" ]);

oscmd ("cmd.exe /Q /C dir *.bat", {shell=""});  ## equivalent

In the following we send a command directly to an interpreter which acts as its own command shell, in this case Perl.

## Send the print command directly to perl

oscmd ("print ""Hello World\n"";", shell="perl -e");

## Equivalent to:

oscmd ("perl -e 'print ""Hello World\n"";'", {shell=""});

oscmd ([ "perl", "-e", "print ""Hello World\n"";" ]);

We could have also invoked the Perl interpreter via a command shell as the following illustrates.

## Send the perl print command through the C-Shell

oscmd ("perl -e 'print ""Hello World\n"";'", {shell="csh -f -X -C"});

If you have UNIX shells available (even on the Windows platform), you may develop more sophisticated commands as in the following.

## Other commands sent to Hamilton C-Shell

oscmd ("ls -t | head -20", {shell="csh -f -X -C"});

oscmd (shell="csh -f -X -C", ...

"ls -lF | awk '{print $6 ""\t"" $7 ""\t"" $8 ""\t"" $9}'");

Xmath's oscmd function also supports a tee keyword which redirects standard output and error to a named file.

oscmd ("myprog arg1 arg2", {tee="myfile.txt"});

You can redirect output to a file as well as capture the output into an Xmath string variable.

[myvar] === oscmd ("myprog arg1 arg2", {tee="myfile.txt"});

Executing Perl Commands from Xmath command line

Due to the popularity of Perl, Xmath now supports a perlcmd function. This function constructs a command and uses oscmd.

Here are some variations.

perlcmd ("print ""Hello World\n"";");

perlcmd (file="myscript.pl");

By default  perlcmd  uses the Perl interpreter located at the path: $MATRIXX/perl/perl.

You can specify perlcmd to use your own version of Perl. For example, the following command is directed to use the perl executable in your $PATH environment variable.

perlcmd ("print ""Hello World\n"";", {perl="perl"});

The  perl keyword specifies the path to the Perl executable. In this case we leave it up to the OS to find Perl simply by specifying "perl".

To display the path to the Perl executable, type one of the following.

perlcmd ({which});               ## for $MATRIXX/perl/perl

perlcmd ({which, perl="perl"});  ## for Perl in $PATH

To display the Perl version, type one of the following.

perlcmd ({version});               ## for $MATRIXX/perl/perl

perlcmd ({version, perl="perl"});  ## for Perl in $PATH

Since perlcmd uses oscmd for its implementation, it also supports the tee keyword to redirect standard output and error to a named file.

Access to Environment Variables

The MATRIXx product uses environment variables to influence various operations. For example, the expansion of '~' may use $HOME and the expansion of '~user' may use $NETHOME. Also, Xmath executes startup.ms files in directories listed in the $XMATH_STARTUP variable.

To support the use of environment variables, Xmath supports the following commands and functions. Examples are shown.

showenviron   ## Prints out the list of environment variable settings

showenviron "XMATH"  ## prints out the setting for $XMATH

setenviron "MYVAR", "myvalue"   ## set $MYVAR=myvalue

unsetenviron "MYVAR" ## clears the setting of $MYVAR

x = getenviron ("MYVAR")  ## Sets Xmath variable, x, to $MYVAR

x = getenviron()   ## returns all environment variables in an MSO variable.

Accessing the content of a Partition or MSO

The list of variable names in a partition or MathScript Object (MSO), can be retrieved with the get command.

names = get ({variables, partition="main"});

names = get ({variables, mso=mymso});

By default, get ({variables}) returns a list of names. To return the same information as a string array, type one of the following.

names = get ({variables, partition="main", string});

names = get ({variables, mso=mymso, string});

Issues

• Ctrl+c keyboard command not affective in stopping LNX processes in all cases, especially if the LNX is communicating messages to the Xmath process and the LNX process hangs or does not complete the message

Known Bugs

• Displaying propagated input signals within an editor diagram inoperative (CAR 47Q703QQ)
• A SuperBlock (and STD) Input Display property configured to InputSignals  mode does not show the propagated signals after navigating from a reference block into the SuperBlock (or STD). In this case, for the SuperBlock, the input terminals will not show any text and for the STD, the transition expressions will only display the “U” symbols.
• Cut/Copy/Paste within a State Diagram editor inoperative (CAR 47FGQ2QQ)

Q & A

• How do you create a SuperBlock?
• Creating Superblocks is primary done from within the project system. Select a folder, right-click and select ‘New SuperBlock’.
• Where’s the SuperBlock Palette?
• The “References” palette replaces the SuperBlock palette.
• Where are the other elements from the old SuperBlock palette?
• The Condition SuperBlock, ReadFrom Variable and WriteTo Variable are now located in the software constructs palette. The Altia block is no longer supported.
• Can the palettes be customized?
• Not available in this release.
• Can I turn off the project system?
• Yes! Go to the Tools->Options dialog and select the Project settings. Change the project configuration to the ‘Never Configure a Project’. Close the dialog to save the change. Now, from that point on, you will not be prompted to configure a new project.
• Can I turn off the solution?
• You can not disable the solution capability.
• How do I get help about a block? / Where’s the Help button?
• The Help button is replaced by the ‘?’ button, which exists on the window frame (near the close box). Other dialogs and wizards will also have the ‘?’ which will bring up the appropriate online help topic.
• What is the Transformation attributes in the SuperBlock Properties dialog?
• These options expose the existing capability in the tool to help transform the contained blocks when SuperBlock attributes change. The most dramatic type of change is a switch from discrete to continuous (or vice versa). Also, changing the sample rate may cause block transformations. When transformations are enabled, the editor will automatically update block parameter data to reflect the update SuperBlock attributes.
• Why are some tabs missing from the property dialogs?
• Related tabs were combined into a paned spreadsheet presentation. For example, the document tab is complete gone and exists now as a sheet within the spreadsheet that the documentation information pertains.
• What are the ways to create blocks in a diagram?
• There are 2 methods to create a new block in a diagram. One is to click a block in the palette, then click within the diagram window. The other is to right-click within an empty area of the diagram, then select the ‘Add Block’ cascaded menus to find the specific kind of block you want to create.
• When you click a block from the palette then click and drag within the diagram window, the new block will be resized to the size of the dragged region.
• Special feature! The menus in the ‘Add Block’ menu tree can be ‘torn off’. This feature is not common on Windows applications but is prevalent in Unix/Linux applications. To tear off the menu, click on the dashed line. To use the tear off menu, select the block from the menu(s) then click within the diagram. Drag/drop won’t work from the tear off menus.
• Xmath appears to hang when running some PGUI scripts, like the Parameter Root Locus tool, why?
• Some PGUI functions create a modal dialog and desktop policy issues prevent that window from being made top-most. The result is that it appears that Xmath is not responding and the status indicator remains in a ‘busy’ state.
• The solution is to bring the modal dialog to the front-most window on your desktop and do what the dialog requests.
• You may have to minimize the IDE window or find the window listed in the Window’s task bar
• A sim or Xmath build process fails because ‘cl is an unrecognized command’ message (UCBs or LNXs), why?
• A sim or hyperbuild build process fails with an error ‘Error creating child process’ why?
• The MATRIXx IDE does not have the required environment variables set for your .NET compiler. See Setting the Environment for .NET 2003/2005 Compilation (UCBs and LNXs)  [Windows only].