Some ModelRight Programming Topics in more Detail

Contents

• Accessing MRObject Properties
  • Read a Property
  • Write a Property
  • Reading/Setting Properties of various datatypes
  • Reading and writing a Property which holds a Point datatype value
  • Special case: SetDataType
• Transactions
• VB Scripts and the User Interface
  • Prompting or getting input from the user

Accessing MRObject Properties

While the various objects (Tables, Views, Columns etc) in a ModelRight database model are represented by MRObjects, their properties are stored in the Properties collection of each MRObject. Each individual property is actually stored in an MRProperty object, and its value in an MRPropertyValue object.  While this provides great flexibility in the model structure, it's a little puzzling to know how to access it. In fact there are helper methods that make it easier. The following sections provide the basic procedures.

Read a Property

In general, when reading a model property from an MRObject, you usually just want to capture the value into a simple variable. This can be done in one step:

MyVariable = SomeMRObject.Property("SomePropertyName").AsString   ' or AsInteger etc

example:

L = AColumn.Property("Datatype Length").AsInteger

The names of properties that can be used can be found from the Metamodel browser.

Write a Property

Writing to a property is more involved as it requires creating a new MRPropertyValue object with the new value, and then providing that to the parent object:

Set PropValue = Framework.CreatePropertyValue("SomeParentObjectType", "SomePropertyName")
PropValue.FromInteger([number])         ' or FromString etc
Col.SetProperty "SomePropertyName", PropValue

example

PropName = "Datatype Length"
Set PropValue = Framework.CreatePropertyValue("Column", PropName)
PropValue.FromInteger(33)
SomeCol.SetProperty PropName, PropValue

The SetProperty method adds the new MRPropertyValue object to the parent object's Properties collection. If there was already a MRPropertyValue object for the property name, then it will be discarded, and the new one takes its place.

If you have many properties to set, you will probably want to write a subroutine to make this more streamlined.

Reading/Setting Properties of various datatypes

Although the preceding sections covered the basic steps for reading and writing properties, there are more details relating to how to handle properties with different datatypes.  In summary, if the property has a single value of simple datatype, like string or integer, then your code can use the AsXxx and FromXxx methods for reading and writing that property.

If instead the property holds values of a more complicated datatype, then there are various different methods for reading and writing them. These details are shown in the table below.

When using the AsString and FromString methods, in general the string returned by AsString is of the exact format which can be used with FromString. The exception is when the property actually involves an object reference: Here AsString returns the object's Name, while FromString for requires the object's Id number (as the name is not necessarily unique). You can view an object's Id number in the Model Browser: it appears in brackets after the object's name.

Reading and writing a Property which holds a Point datatype value

Here's a complete sample for reading/writing a Point property. The sample code moves a table, involving the "Top Left Point" property, which contains point data, and can be read or written as a string: (left,top). 

Sub Evaluate_OnLoad
  Set Context = CreateObject("SCF.ScriptContext")
  Set Document = Context.ScriptDocument
  Set Framework = CreateObject("SCF.ScriptFramework")
  Set Model = Framework.CurrentModel
  Set ModelMRObject = Model.AsObject

  Document.WriteLine "--- start ---"
  Set ModelSubset = ModelMRObject.ChildByName("Model Subset", "Model Subset 1")
  Set Diagram = ModelSubset.ChildByName("Diagram", "Diagram 1")

  '-------------------------------------------
  ' Get the Graphics for table "actor"
  '------------------------------------------- 
  Set TableGraphics = Diagram.ChildByName("Table Graphics", "actor")

  '-------------------------------------------
  ' Read position
  '------------------------------------------- 
  PropName = "Top Left Point"
  LeftTop = TableGraphics.Property(PropName).AsString
  Document.WriteLine "actor Position: " & LeftTop

  PointStrToXY LeftTop, X, Y
  X = X + 100
  Y = Y + 10
' Document.WriteLine "X Y " & X & "," & Y 

  '-------------------------------------------
  ' Set position
  '------------------------------------------- 
  Model.BeginTransaction "Fiddle with graphics"

  Set PropValue = Framework.CreatePropertyValue("Table Graphics", PropName)
  PropValue.FromString X & "," & Y
  TableGraphics.SetProperty PropName, PropValue

  Model.EndTransaction
end sub

'---------------------------------
sub PointStrToXY(PointStr, X, Y)
'---------------------------------
  P = InStr(PointStr, ",")
  LStr = Trim(Left(PointStr, P-1))
  RStr = Trim(Mid(PointStr, P+1,1000))
  X = 1 * LStr 
  Y = 1 * RStr
end sub  

Special case of Column data type: SetDataType

Setting a column's Datatype property is slightly different. Note: this discussion is not about the about datatype of a property. Instead, it is about an MRObject holding specs for a Column, which has a property called DataType which sets the datatype of the Column. This Datatype property expects to hold an object reference -- a reference to a Type object (in the Type collection, (which you can view in the ModelBrowser).

A shortcut is provided to do that, the MRObject.SetDataType method. Example:

Col.SetDataType("VARCHAR")

Transactions

Any changes to the model must be bracketed by Model.BeginTransaction and Model.EndTransaction statements. This gives ModelRight a batch of changes to commit and reconcile at once.

A transaction is used in a couple of ways in ModelRight:

• It places that batch of changes into the Undo queue, and permits you to use the Undo button to undo it, or the Edit > Undo menu item.  The latter shows a list of recent transactions by caption, so it's helpful to provide a distinctive caption when calling BeginTransaction.
• It can be the basis for creating an Alter SQL script

If your code makes a large number of changes, these can be wrapped in a single transaction, or many individual ones, depending on how you might make used of Undo or Alter scripts after the changes.

VB Scripts and the User Interface

Prompting or getting input from the user

The usual VB Script popups can be called, as follows:

MsgBox: Shows a small modal message box (interrupting the progress of the script, and ModelRight).  Most useful to tell the user something at the end of the script (or on error).  Unlike in a VBA applications, in ModelRight MsgBox is not very useful in the middle of script execution, as MsgBox is modal with respect to ModelRight, and consequently the user can't interact with the application to take any action anyway. MsgBox might be useful debugging, but here Document.WriteLine can be more helpful (the messages accumulate) and less intrusive.

InputBox: Shows a modal dialog into which the user can enter a string which your script can then use.

Example of both MsgBox and InputBox:

Sub Evaluate_OnLoad
  Set Context       = CreateObject("SCF.ScriptContext")
  Set Document      = Context.ScriptDocument
  MsgBox("Hello")
  S = InputBox("Enter something")
  Document.WriteLine("InputBox returned: " & S)
end sub

Next - Sample ModelRight Scripts  >>