Beginners Guide to the CA Plex Model API using C# .NET - Part III – ‘Key Model API commands’

For part III in this series I promised that I would look at some of the Model API methods that are most useful to you the ‘ModelAPI programmer’ and to get you started with how the ModelAPI methods help you traverse the Model Editor.  If you have read the other posts in the series you will know I am building Standards based Entity Creation wizard for www.sasit.co.nz

Links

Part 1

Part II

As there are more than lots of methods available to you I am not going to give a blow by blow breakdown of each one and where best to use them. That would be overkill, quickly forgotten and isn't that was the RTFM is for :-)

If you look at the API documentation you can see that the API allows you to:-

• Open and close models, interrogate the model details like Path, Name and Variants etc.
• Find, Add, Change and Delete objects from the model. i.e. Entities and Fields etc.
• Manipulate the properties of these objects. i.e. Narratives, Owner and Permissions etc.
• Navigate the triples associated with the objects as if you were reading the Model Editor.

All in all the potential is there to create a whole ecosystem around the outside of your Plex environment like George has with Stella Tools. I am sure that CMFirst’s Matchpoint uses the technology extensively too. I have used it for my Entity Creator (In house) and I know of others doing some cool stuff with it too.

The ModelAPI methods are broken down into 6 categories

• Enumerators & Safe Arrays – Lists of xxx things in the model like triples or entities.
• Object(s) – Entities, Fields, Tables, Views etc
• Environment – Open, Close, Variants etc
• Triples – As per entries shown in the model editor
• Verbs – All the verbs we use to model our systems
• Automation – Generate & Build or executing commands

So we are going to look at the following methods. I have highlighted the methods category in brackets.

• OpenModel (Environment)
• FindObj (Object)
• EnumTriplesBySource (Enumerators & Safe Arrays)
• GetCountOfItemsInEnumerator (Enumerators & Safe Arrays)
• GetNextTriple (Triples)
• GetTripleName (Triples)
• GetTripleVerb (Triples)
• EnumVerbs (Enumerators & Safe Arrays)
• GetVerbName (Verbs)
• EndEnum (Enumerators & Safe Arrays)
• AddTriple (Triples)

Hopefully this will be enough to whet your appetite and encourage you to delve a little further.  Output parameters are indicated in bold.

OpenModel

Parameter	Description
Path (string)	The full path to the local model that you wish to open “C:\MyFolder\MyLocalModel.mdl”

Put simply this will open the model supplied.  If Plex is not open and calling the Model API for the first time will instantiate a copy of Plex.  The OpenModel needs the full path and if not correct then will throw an exception so use some defensive programming techniques.  

Related methods of note CloseModel, SaveModel, GetVersionName, GetVariantName and GetLevelName with the last three being based on the current configuration of the local model.

FindObj

Parameter	Description
FullyScopedName (string)	The name of the object you are searching for
ObjectType (int)	The type of object.  Used to narrow down the returned triples e.g. Entity or Field but can be set to 0 for All
Object (int)	**The Model’s internal ID for the object.  i.e.  the model surrogate ID that you weren’t supposed to see J.  For each object that you want to query or manipulate you need this ID.  FindObj is how you get it.  FindObj will return a 0 ID if the object/type is not found in the model so no ‘try/catch’ for you C# guys but be weary of what 0 really means for your program.

Probably the most used method in the ModelAPI I would suggest.  The principle is simple.  Virtually all methods relate to objects or triples etc by their ModelIDSurrogate.  Not to be confused with the Surrogate on the Object Details (Information) tab or for Information menu option (See below).

There is a list of all the object types in plex and their underlying ObjectTypeID in the ModelAPI help.  For ease of use I will tell you that Entity is 5 and a Field is 6. 

There are some smart ways of shielding yourself from having to remember these ID’s that I will go into with post IV next time when we will build a small ModelAPI program in a tutorial in C# .NET. 

Related methods of note AddObj, ChangeObj, DeleteObj and other methods that do get the information in the information tab above like GetObjOwner, GetObjPermissions, GetObjLastChangedDate and GetObjSurrogate (Yes that one in the information window) has been implemented in version 4.0 of the ModelAPI that ships with Plex 7.0. J

EnumTriplesBySource

Parameter	Description
Obj (int)	The ID of the Object on the left of the Model Editor (Source Object)
VerbID (int)	The verb.  Used to narrow down the returned triples but can be set to 0 for All
Enumerator (int)	An API generated ID that points to the list in memory that is created by the ModelAPI

Now would be a good time to explain what a ModelAPI enumerator is.  www.dictionary.com supplies the following interpretation on Enumerator (Enumerate) which is pretty good so we’ll run with this.

To mention separately as if in counting; name one by one;specify, as in a list:

Once we have the enumerator ID we would then use a loop (Do While or For loop etc) to get the details and parse the triples, in context of Triples we could use GetFirstTriple and GetNextTriple.

Related methods of noteEnumTriplesByTarget.

If we were to use the EnumTriplesBySource for the YesNo field and VerbID of 0 for All.  We would get the following from my local model

Enumerator 87200904 (This changes every call). 

The enumerator will have 9 entries which are the underlying internal ID’s (don’t change) :-

87814200
87814344
87814488
87805848
87812760
87812904
87813048
87813192
87813336

All of these relate to the triples (real or inherited) that define the field as defined in the Object Properties window.

So to summarise an enumerator is a list of ID’s that point to objects or triples within the plex model, the enumerator is created on the fly with a unique ID.

GetCountOfItemsInEnumerator

Parameter	Description
Enumerator (int)	The ID of the enumerator created by the Enum* method.  Note that these are temporary ID’s that are generated uniquely each time an Enum method is called.
Count (int)	Integer value of the number of triples in the enumerator.

Once you have an enumerator you need to loop though it.  Understanding how many items have been returned can be useful for ‘Count Fields’ or of course enabling you to safely control the calls to the GetNextTriple method without causing you ‘Index out of bounds’ type errors.

GetNextTriple

               

Parameter	Description
Enumerator (int)	The ID of the enumerator created by the Enum* method.  Note that these are temporary ID’s that are generated uniquely each time an Enum method is called.
Triple (int)	The ID for the individual triple

Each time GetNextTriple is called it advances on one from within the Enumerator. 

Related methods GetFirstTriple always gets the first triple in the enumerator.  Note, this can be useful for resetting the underlying pointer for the GetNextTriple if you need to read through the enumerator more than once.

GetTripleName

Parameter	Description
Triple (int)	The ID for the individual triple
Name (string)	A string with the full triple name i.e. Source, Verb and Target.  i.e. My Entity/ENT known by FLD/My Key

GetTripleVerb

Parameter	Description
Triple (int)	The ID for the individual triple
Verb (int)	The internal ID for the Verb.

Currently there are over 640 verbs in plex and this grows with every release.  These verbs like the ObjectType have unique internal ID’s

GetTripleVerb returns the ID of the verb for the triple.

Related methods GetTripleSource, GetTripleTarget and GetVerbName (covered later).

EnumVerbs

Parameter	Description
SrcType (int)	As ObjectType i.e. Entity or Field.  Can be 0 for All.
TgtType (int)	As ObjectType i.e. Entity or Field.  Can be 0 for All.
Enumerator (int)	An API generated ID that points to the list in memory that is created by the ModelAPI

You can show all verbs related to Entity by select SourceObjectType as Entity and TargetObjectType as All.  Or be really specific with as Entity and Entity which brings back verbs like ENT Refers To ENT and ENT Owned By ENT etc

GetVerbName

Parameter	Description
Verb (int)	Internal verb ID i.e. FLD Displayed as FLD = 8 and is an example of a verbs FullName
WhichName (int)	See table below.
VerbName (string)	An API generated ID that points to the list in memory that is created by the ModelAPI

Assuming we use the example above i.e. Verb = 8 then WhichName will return the verb formatted as follows:-

WhichName (int)	Description	Verb = 8 returns...
0	AliasName	displayed as FLD
1	FullName	FLD Displayed as FLD
2	ResolvedName	FLD Displayed as FLD
3	SimpleName	FldDisplayedFld

This return the formatted name is various way and also saves us having to parse the GetTripleName string.

EndEnum

Parameter	Description
Enumerator (int)	Deletes the enumerator from memory.

Every enumerator you create using an Enum* method creates a new enumerator list with a new ID.  If you don’t destroy these they will stay in memory until you close the program.  Basic housekeeping to reduce memory usage.

AddObj

Parameter	Description
SourceObj (int)	The object you wish to link (scope) the new object with.  Tip. Leave as 0 for an unscoped object.
Name (string)	The name of the new object (Remember to conform to Plex naming standards i.e. restricted characters and 32 in length.
ObjType (int)	Same is ObjectType i.e. Entity = 5 etc
Object (int)	The ID of the object just created in case you want to add other stuff like narratives etc.  Saves you finding the object you just created.

Next time we will put most of these into action with a C#.NET Tutorial using Visual Studio 2008. You won’t need the professional edition either although I will be using it.

See you then.

Thanks for reading.

Lee.