Enhancements in MasterStudio 2.0

Please note: MasterStudio version 2.0 is a paid upgrade and requires a new registration code.

MasterStudio 1.1.0 incorporated all enhancements through alpha release 20 and is the last release that will run on Omnis Studio versions 4.1.1 and 4.2 (as well as 4.3, like MasterStudio 2.0). Licensed MasterStudio developers can download the stable release here.

Introduced in MasterStudio 2.0 beta 1:

  • Fully updated 299-page Developer Manual.
  • Support for Omnis Studio 4.3.2 (non-Unicode) and Omnis Studio 5.0.1 (Unicode).
  • Numerous performance improvements throughout the foundation framework (class broker, contexts, controllers, sessions, tables, list managers, record managers, notification centers).
  • Use of Object References for controllers, commands, schemas, schema columns, session statements, and various managers: There is no longer a limit of 100 controllers. For improved performance, the controller hierarchy no longer stores objects in nested instance variables. A new MoObject(pfrObjectPath,pfrIdent,prClassOrPrototype) call returns a new object reference for the current context, setting pfrObjectPath and a unique id in pfrIdent. The MoContext.$recycleObject({ident}) call is used to remove an object or object reference that is no longer in use. To instantiate a manager using the new object pool, use MoManager(prClassOrPrototype).
  • Scratch libraries and modules (libraries in subfolders) will now be converted automatically (and without user prompts) when opened in a new Omnis Studio version.
  • The MasterStudio folders (storing classes and preferences) are now named MasterStudio (instead of "MasterObjects").
  • On Windows, the MasterStudio Preferences will be stored in the user profile Application Data folder instead of the root of the user profile. For example, Windows Vista and Windows 7 will use C:\Documents and Settings\Username\AppData\Local\. See page 16 of the updated Developer Manual.
  • Improved handling of "larger than", "smaller than", and "range" search for individual fields in Find mode ("query by example").
  • It is now possible for users to open nested entity panes or grids in a new window: Even when the entity frameset itself is hidden (e.g., in a tab or in an expanded frameset), the panel will remain functional. This is because component controllers that are inactivated will only deactivate themselves after closing their last panel. If a component panel is still open, then the corresponding supercontrollers cannot be deactivated.
  • Icons were added to the demo and database menus.
  • The MasterStudio database table superclass was improved:
    • It automatically checks for its validity (refusing database actions if invalid) and now provides reference variable iMoObjectRef that points to the list associated with the table instance.
    • Smart lists based on the MasterStudio table superclass now call the table instance $insert, $update, and $delete methods rather than the separate built-in $do... methods. So it is no longer to implement these database methods twice.
    • New superclass methods $moStart, $moAction, and $moFinish are called at the start, during, and after each database transaction. The session automatically manages actions within nested transactions so that the outer transaction commits or rolls back changes.
    • New superclass method $moDoSql is a convenience method that performs any SQL action for the list.
    • New template method $willDestruct can be used to clean up a list instance before it is destroyed. MasterStudio will automatically call $moDestruct, but you can also do this for lists that you manage yourself.
  • Entity controllers now create only a single table instance (instead of three). The function manager's new method $copyListFromList can be used to copy a list without the associated table instance.
  • Refetching of database records was sped up by using a bind variable for the primary key and thus allowing the use of a single $prepare with multiple $executes.
  • New context variables were added. This increases performance and greatly improves the readability of method lines (and makes it easier to type them, too):
    • New context variable MoClass serves as a shortcut for MoContext.$classRef .
    • New context variable MoF serves as a convenience shortcut for MoManagerFunctions .
    • New method MoObject(pfrObjectPath,pfrObjectIdent,rClassOrPrototype,copyNY_opt) returns a new object reference based on a class, and can be used to instantiate an unlimited number of objects. When you no longer need an object, call MoContext.$recycleObject(objectIdent) .
    • New context variable MoNC serves as a convenience shortcut for the current context's notification center.
  • MasterStudio superclasses now group their method lines under appropriate headers, making methods easier to find. Headers start with "$_ ", making them visible in subclasses.
  • New comments and explanations in all classes. Inherited methods now have a description that shows the names of superclasses that they override.
  • When running in a developer version of Omnis Studio, MasterStudio code errors that are only sent to the trace log will sound the bell. In the runtime version, code errors are now also sent to the trace log (if you want end users to see the trace log, you will have to provide your own function).
  • New method MoContext.$log(text,pkAddTimeStampYN_opt) writes an entry to the trace log, including an optional time stamp in hundredths of a second, even if debugging of the MasterStudio libraries is disabled.
  • In places where notation errors may occur (e.g., when checking for the validity of objects that may legally be invalid), the framework now temporarily sets the $nodebug library property so that you won't break into the debugger, using the following mechanism:

    Begin reversible block
      Calculate $clib.$nodebug as kTrue
    End reversible block
    ;; calculations that may raise #ERRCODE...
  • The new MoF.$testObjectIsValid(object) function returns true if the object exists and if object's $objectIsValid attribute is true.
  • The new MoF.$setProperty function sets the $property property of an object, without raising #ERRCODE if it is currently out of scope.
  • A new "MS developer menu" provides access to new developer functions. It can be installed using the MS Developer Menu Toggle Add-On tool. Once installed, it will remain installed until you close it or remove the Preferences.

Introduced in MasterStudio 2.0 beta 2:

  • Naming of object and menu instances was improved for significantly easier selection and debugging of instances in the Omnis method editor. By default, object instance names include their class name. Dependent objects and subcontrollers now include the names of their parent object(s), using > as a separator.
  • Object and context instances have a new $objectName attribute, which returns their unique name. (Note that using the standard Omnis notation objectRef.$name may return the name of the variable that contains the instance. In such cases, you can now use objectRef.$objectName)
  • Scratch libraries can now be made private by passing kTrue as the fifth parameter of their $construct.
  • Scratch libraries used by MasterStudio's developer tools (such as the MS Component Store) are now private so they no longer show up in the Omnis Studio Browser.
  • Bugfix: Methods $controllerEnumeration and $invokeMethod now properly return the filtered list of controllers matching the optional pTypeName_opt parameter.
  • Bugfix: Entity grid report will now fetch (and thus print) unfetched column values when printing records that have not been viewed or selected before.
  • Fixed an issue introduced in beta 1 that prevented panel subcontrollers to be properly destroyed.
  • Fixed an issue introduced in beta 1 that caused MD entity grid reports to fail.

Introduced in MasterStudio 2.0.0 final release:

  • Addition of class MoDatabaseSessionPgSql (support for PostgreSQL).
  • Improved error handling when a database login fails.
Bugfixes in MasterStudio 2.0.0
  1. Notifications with coalescing settings ckCoalescingOnName+ckCoalescingOnObjectPath are no longer coalesced if only one of these conditions is met.
  2. Login panels now properly listen for database notifications from their session.
  3. MasterStudio-managed lists now properly dispose of their MasterStudio statement objects when no longer in use.
  4. When inserting a new record causing a list to scroll, the list will fetch unfetched columns for newly-visible rows.
  5. Function $getFromCsv was fixed so it accepts empty strings in comma-separated values. This means that schema prompts (labels) may now be empty. This is useful in prompts for enumerated types, such as "Appointment type" in the demo application.
  6. Function $isNullOrEmpty no longer causes the method stack to grow while debugging.
  7. Optional pane parameters pf3_opt...pf10_opt are no longer mapped to pf1_opt...pf8_opt in pane controller subclasses.
  8. Contexts will now correctly display OK messages for errors that may occur before the managers have instantated (including the functions manager responsible for more advanced error handling). Previously, it was possible that a new context would close itself without any error handling.
  9. Methods $controllerEnumeration and $invokeMethod now properly return the filtered list of controllers matching the optional pTypeName_opt parameter.
  10. Entity grid reports will now fetch (and thus properly print) unfetched column values when printing records that have not been viewed or selected before.
MasterStudio 2.0 Upgrade Instructions

To upgrade your libraries for use with MasterStudio 2.0, please perform the following steps. If you are upgrading from a version prior to 1.1 (or prior to 2.0 alpha 20), make sure that you first follow the upgrade instructions for version 1.1.0.

  1. MasterStudio 2.0 requires Omnis Studio 4.3.2 (non-Unicode) or 5.0.1 (Unicode). (MasterStudio 1.1.x is still supported for Omnis Studio 4.2-4.3.2)
  2. Install main library classes:
    Copy the latest versions of MoContextRoot and MoClassBroker as well as the #STYLES system table into your main library. The new demo library has a MasterStudio class folder that also includes the #ICONS table. If you use MasterStudio's icons, you can simply drag the entire class folder into your library.

    Before you start up your library, follow all upgrade steps listed below. When you are ready to launch your application, the class broker will automatically open libraries in subfolders of your MasterStudio applications. If you open your MasterStudio application with Omnis Studio 5, its libraries will now be converted by Omnis automatically, i.e. without user prompts. Be sure that you have a backup of your libraries in the old Omnis Studio version.

    Note: When you first open the demo database with Omnis Studio 5, you will be prompted to convert the data file. We recommend that you perform a "Full" conversion.
  3. Replace framework libraries:
    Replace your old MasterObjects folder by the new MasterStudio folder.
  4. Note that the framework libraries and some demo application classes were renamed. Library "MoBaseClasses" is now called "MoFoundationModule". Its internal name leaves out the word "Module": MoFoundation. The other libraries also no longer include the word "Classes" in their names. The first time you load the new version of MasterStudio, the class broker will take care of renaming your $superclass and $designtaskname attributes. Be sure to let the class broker finish updating its class references. If you do not, you must do so manually.
  5. MasterStudio 2.0 was designed so that your applications will continue to work with very little effort on your part. However, there have been significant changes "under the hood". The following functionality has changed and may break in your existing application. Here are instructions on how to make the proper changes to your applications:
    • MasterStudio table subclasses (subclasses of MoDatabaseTableSuperclass) now require passing in their object path, i.e., the notation path to your list instance. (Earlier MasterStudio versions already did this, but did not require it)

      Unless you only use MasterStudio tables managed by the list manager, you should verify your current libraries by searching for .$definefromsqlclass(. The path should be the first parameter after the empty parameter (i.e., the first parameter passed into the table's $construct method). For example in a window or menu instance:

      iEmployeesTable.$definefromsqlclass(
      MoContext.$classRef('DemoEmployeesTable'),, con($cinst().$fullname,'.',nam(iEmployeesTable)), iSessionRef.$ref)


      or in a controller, context, or delegate, where the iObjectPath variable points to the current object instance notation path:

      iYourList.$definefromsqlclass(
      MoContext.$classRef('YourTableClassName'),, con(iObjectPath,'.',nam(iYourList)), iYourSession.$ref)


      Important: MasterStudio lists now must have a valid notation path. They will no longer allow database actions if you use them in a local variable. When you copy a list to a different variable, you should call $objectPathSwitch(newPath).

      Also, when overriding any database actions without calling the inherited method, table subclasses should call $cinst.$objectIsValid. This allows the table to set its references and verify its object path.
    • Contexts now use a short object path that starts with $itasks. instead of $root.$itasks.. This means that a task's object path no longer matches its $fullname. It is unlikely that this causes issues in your application, since you will already use iObjectPath and $objectPath. But please verify that you do not specifically refer to $root. anywhere in your code. Instead of MoContext.$fullname, $ctask().$fullname or $cinst().$fullname, use MoContext.$objectPath.
    • Nested MasterStudio controllers are no longer stored as instance variables inside of each other. This means that destroying a subcontroller by simply setting it to #NULL no longer cleans up any nested subcontrollers (sub-subcontrollers) automatically. Of course, MasterStudio will clean up nested controllers if you call $destructController (was: $destructSubcontroller) for a parent controller. Omnis will also clean up any remaining object references when a context is closed.

      By default, $destructController() (was: $destructSubcontroller()) destroys any nested subcontrollers automatically. So you only need to worry about this new situation if you called .$destructController(kFalse) (parameter kFalse tells the controller not to destroy nested subcontrollers). If your application did this, to avoid a memory leak, you must verify that nested subcontrollers are destroyed explicitly in some other way.
    • The following is only relevant if you subclassed any MasterStudio contexts or controllers: Method $connectToSuperController no longer receives parameter pObjectPath. Variable iControllersSubCount was removed; you should replace it by iControllersSub.$linecount.
    • The following is only relevant if you subclassed any MasterStudio managers (MoManagerSuperclass): Method $switchObjectPath was renamed into $objectPathSwitch.
    • The following is only relevant if you subclassed the generic entity controller or the list manager: Instead of $construct, method $objectPathChanged of the list manager MdManagerListGeneric now receives references to the fields manager and record manager classes, instead of the corresponding class names.
  6. Some internal variables and methods were removed or renamed. Unless you created your own subclasses of classes in the MasterStudio foundation layer, it is unlikely that this causes issues in your application:
    • Column (and class variable) cObjectIndex was removed from the controller implementation. It is unlikely that you used this variable in your own code, but you should do a search anyway.
    • Variables iControllerSubRef and cControllerRef were removed. If your application contains context or controller subclasses, please ensure that you replace iControllerSubRef() by [iControllerSubPathRef].
    • Context attribute .$baseClassFactory was renamed to .$baClassFactory. Although it is unlikely that your applications access this method, please make sure by doing a search.
    • The context managers manager was renamed from MoManagersSubcontexts to MoContextManagers and MoManagersRoot to MoContextManagersRoot.
    • The language manager classes were renamed for consistency with other managers: MoBaLanguages became MoManagerLanguages and MoMdLanguages became MdManagerLanguages.

      In prior MasterStudio versions, the $switchObjectPath (now renamed into: $objectPathSwitch) call received a reference to the current context (prContext) as its first parameter. Now, iObjectOwnerRef.$ref is used instead.
    • This point is only relevant if you subclassed the MD list manager MdManagerListGeneric: The list manager no longer has iSchema... instance variables for attributes unmodified from the schema object values. If you created a subclass of the list manager, please verify that you don't refer to these deprecated variables. Instead, use iSchema.$... attributes. You can easily find the deprecated variables by searching for $cinst.iSchema after upgrading to the new MasterStudio libraries.
    • The following is only relevant if you subclassed the MD list manager MdManagerListGeneric or the MD record manager MdManagerRecordGeneric: The list manager and the record manager were refactored so they now inherit from new MoManagerListSuperclass and MoManagerListRowSuperclass. Some internal variables were renamed. Notably:
      • iSearchFlagsRow became mSearchFlagsRow
      • iSearchLargerRow became mSearchLargerRow
      • iSearchSmallerRow became mSearchSmallerRow
      The various lists maintained by the list manager no longer create copies of the entity table instance. This means that you can no longer perform database actions (such as $select or $fetch) on iMdEntityListEmptyRow and iMdEntityListSwappedOut.

      Instance variable iObjectWillDestructNY was replaced by superclass variable iObjectWillDestruct.
    • The following is only relevant if you created your own fields manager: Class MoManagerListFields was renamed into MoManagerListFieldsSuperclass.
  7. MasterStudio now uses Omnis' Object reference data type to store various objects. This affects your applications as follows:
    • Schema objects now use the Object Reference variable type, instead of being copies of an Object. If you created your own classes that work with MasterStudio schema objects, you should change the variable types from Object into Object reference. You can do this by searching for .$getSchema and .$moSchemaObject.
    • Schema column objects also use the Object Reference variable type, instead of being copies of an Object. If you created your own classes that work with MasterStudio column objects, you should change the variable types from Object into Object reference. You can do this by searching for .$findColumn and .$moColumns.
    • Command objects now use the Object Reference variable type, instead of being copies of an Object. If your windows used custom MasterStudio commands, you should change the variable types from Object into Object reference. You can do this by searching for .$newCommand(.

      Notes, only relevant if you created your own command subclasses: The class broker's $prototypeCommand method now returns a new Object reference (instead of an Object). Old command instance variables iTargetControllerPath and iCommandControllerRef were renamed.
    • Database Statement objects now use the Object Reference variable type, instead of being copies of an Object maintained inside their session. This should have no impact on your application, unless you overrode the MoSessionSuperclass and/or MoStatementSuperclass. Notably, statement variable iStatementSessionRef is now iObjectOwnerRef and variable iStatementSessionPath was removed. Also, statement objects no longer receive the session object path as their second construction parameter.
    • For Omnis Studio object references, the $destruct method is called automatically when they are deleted or when their task closes. To avoid confusion with object reference variables, MasterStudio managers no longer use $destruct to clean up, but instead use $willDestruct, which is called before a manager is recycled.
      • You should search your own subclasses of MoManagerSuperclass and ensure that you rename their $destruct method into $willDestruct.
      • For the same reason, $destruct was also replaced by $willDestruct in MoNotificationCenter and MoScratchLibrary. You should rename the method if you created your own subclasses of these.
      In general, we recommend that you reserve the $destruct call for use by Omnis. Your code should no longer contain any .$destruct() calls.
    • The following is only relevant if you subclassed the MasterStudio database session object MoDatabaseSessionSuperclass: Statement objects (as managed in list iSessionStatements) are now Object references, instead of Objects. Session objects no longer have the $newObject and $recycleObject methods.
    • The following is only relevant if you have your own context subclasses that override .$constructManagers: Now, the managers manager iContextManagers is an object reference.
  8. Some methods were deprecated. Although they currently still work, you should replace them as follows:
    • Method $newObject in the controller superclass was deprecated. This method is now supported only by contexts. So, please search for .$newObject in your own library and ensure that it is prefixed by a context reference, e.g. MoContext.$newObject instead of $cinst.$newObject. Note that each context will still allow up to 100 $newObject calls. The new MoObject(newObjectPath,newObjectIdent,classReferenceOrPrototype) method returns a new object reference based on a class or an object reference prototype, and can be used to instantiate an unlimited number of objects. To instantiate a manager in the object reference pool, use MoManager(prClassOrPrototype,prOwner).
    • Controller method $destructSubcontroller was renamed into $destructController.
  9. You can optimize your application further:
    • MasterStudio-managed lists now properly dispose of their statement objects when no longer in use. To clean up your own lists, you may implement the new $willDestruct method. If you create your own MasterStudio list instances (using $definefromsqlclass), when you no longer need them, you should destroy them by calling the new .$moDestruct() method.
    • The MasterStudio table superclass now provides the iMoStatementRef reference, pointing to the default MasterStudio statement associated with the table. Your table subclasses may use this instance variable instead of calling $cinst.$moStatementObject.
    • New context item reference MoClass serves as a shortcut for MoContext.$classRef. You may replace all occurrences of MoContext.$classRef( by MoClass(.
    • New context variable MoF serves as convenience shortcut for MoManagerFunctions. After upgrading to MasterStudio 1.1.0 or 2.0, you can replace MoManagerFunctions. by MoF. throughout your own libraries (be sure to include the trailing period when performing the replace operation).
    • New context item reference MoManager serves as a shortcut for MoContext.$managers().$newPooledManager. You can use this function to easily instantiate pooled manager objects. "Managers" are objects that provide some helper function to other objects. MasterStudio 2.0 supports three ways to instantiate managers:
      • MoContext.$managers().$newPooledManager (new, recommended shortcut: MoManager): Returns an object reference to a new manager instance (created either from a class reference or from an existing object reference instance). The caller of $newPooledManager is responsible for its destruction: It should call $moDestruct to destroy the manager instance when it is no longer needed. If $moDestruct is never called, then Omnis will destroy the manager when its context closes. This would happen after the context may have already become invalid and skips the usual $objectPathWillChange(kTrue) and $willDestruct so the manager can't clean up after itself.
      • MoContext.$managers().$openManager/$openManagerByRef: Uses a context instance variable or a task variable that will either hold the manager instance itself (if the variable is of type Object), or the path to the newly instantiated manager (if the variable is of type Character). The context manager will properly destroy the manager when the context is closed, unless the manager is stored in a class variable. If the manager is in a class variable, then the manager is instantiated only once and it will be destroyed when the last instance of the context is closed. The context managers manager will properly call $objectPathWillChange(kTrue) on the manager.
      • MoContext.$managers().$newManager/$newManagerByRef: Instantiates a new manager in an instance variable in the current context's object pool and returns a reference to it. The context managers manager will properly call $objectPathWillChange(kTrue) on the manager.
    • New context variable MoNC serves as convenience shortcut for the current context's notification center. After upgrading to MasterStudio 1.1.0 or 2.0, you can replace MoContext.$notificationCenter(). by MoNC. throughout your own libraries (be sure to include the trailing period when performing the replace operation).
    • MasterStudio's object pool uses the shortest possible notation path for object instances. For example, when testing with Omnis Studio 4.3.1 and 5.0 beta, calls to
      $itasks.TaskName.iObjectPool.i_1.$objectPath
      were about 20% faster than calls to
      $root.$itasks.YourTask.$ivars.TaskName.$ivars.i_1.
      So when working with notation paths you can gain performance by stripping $root. and $ivars. from them.

      Even more significantly and not surprisingly, setting an item reference to these notation paths and then using that (instead of square bracket notation) is about twice as fast.
    • Controllers, contexts, managers, and windows now have an iObjectRef item reference that points to the instance itself using the optimized object path. Generally, it is better to use iObjectRef.$ref instead of $cinst when passing a reference to other objects.
    • Managers, controllers, and database table instances now have an iObjectOwnerRef item reference that points to the instance that "owns" them. For static managers opened using $newManager or $openManager, this is the current context.
  10. After you have your application running, you can perform the following cleanup:
    • MasterStudio 2.0 no longer needs the MoMasterStudioLicense and MoPlanBoardLicense classes. These may be removed from your main library.
    • MasterStudio 2.0 applications can run alongside MasterStudio 1.x applications. If you no longer need MasterStudio 1.x, you and your users may delete the old MasterObjects Preferences folder. MasterStudio 2.0 uses MasterStudio Preferences.
  11. A new naming convention was introduced: Table instance variables that are used for columns in the list are now prefixed by the letter m. The "m" stands for "member variable". This avoids that list column names are confused with "regular" instance variables.

    Note: This change means that there should no longer be any occurrences of .i in MasterStudio method lines. After upgrading to MasterStudio 2.x, .i should only occur in window and report object properties.
  12. It is recommended that you test your application and:
    • View the Omnis trace log if you hear any unexpected "Sound bells": Some non-fatal code errors are sent to the trace log only.
    • Check for notation errors by setting a "Break on field change" on the Omnis #ERRTEXT variable and then launching and testing your application.
  13. Omnis Studio may not always return the correct value if an Enter data statement is executed as part of a switch or if/then/else statement. For this reason, in MasterStudio 2.0 beta 2 all occurrences of .$message, .$okMessage, .$yesNoMessage, and .$noYesMessage were modified so they are executed using Do and return their value into a variable that is subsequently tested using Switch or If.

    So, instead of using:
    Switch ...$message(...)
    you should use:
    Do ...$message(...) returns answer
    Switch answer
Back to General Release Notes


Copyright © 2014 Master Object AB Terms of Use