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.

Beginners Guide to the CA Plex Model API using C# .NET - Part II - 'Model API and the model repository'

The first post in this series late last year touched on the power of the Model API and how it could be useful for us Plexxers out there. 

http://www.leedare-plex2e.blogspot.co.nz/2011/10/beginners-guide-to-ca-plex-model-api.html

I envisage us automating trivial tasks, extracting information from a model, import system designs into CA Plex, integrate the IDE with other environments/tools as well as code generation productivity tools like my Entity Creator!!!!!

Today we will cover some of the theory, Part III will highlight some of the core methods that you can use to interrogate/update the model and finally Part IV will show you a basic example in C#.NET (DotNet) and give you some other little tips and tricks along the way.

We all know what the Model API is, “don't we!”, but just in case here is my take on it.  Put simply, it is a gateway, interface, framework for interacting with your CA Plex environment and your local model(s) and it is implemented as a COM API.  CA ships a great local model and plenty of documentation to get you going and Google will reveal numerous posts from community members in our forums.

So let's get started.  To truly get the Model API and how it works you need to remind yourself of the underlying repository that CA Plex uses.  A great place to start is with the 'Model Editor' and understanding its design layout.  The ‘Model Editor’ is probably one of the most used editors and with a good understanding of how this triple store works you are set up for Model API programming and Meta Coding techniques also .

Fig 1. Below shows the CA Plex Model Editor focused on a field object FIELDS/YesNo which is a basic single byte status field with a couple of values that is shipped as part of the CA Plex patterns.

The next couple of images might be a bit patronising for the long term CA Plex user so apologies if the next minute of your life is repeating what you already know.

You will see that the model editor has three distinct columns.  Column A is the Source Object column in CA Plex terms, Column C indicates the Target Object and Column B contains the linking Verb that help describes the relationship between the two objects.  Collectively this line is known as a Triple, multiples of these are known affectionately as Triples and they reside in the Triple Store.

Above this area highlighted in yellow below are fields that tell you what the source and target objects are.   This is the Object Type.  i.e. Entity, Field, Table, Interface etc.

So let’s transpose this knowledge onto Fig 1.

Column A (Red) = Source Object(s)
Column B (Red) = Verb
Column C (Red) = Target Object(s)
Object Types (Yellow)
Triple (Blue)

Let’s recap, key learning items for Model API terminology are Source Object, Target Object, Verb, Triple and Object Type and these will be referred to throughout this series of posts.

Back to the Model Editor

We know that the Model Editor can show you all triples for a Source Object and defaults to one level.  All the triples at this level are known as real i.e. they are implicit and not inherited.  If you show the object properties for the field FIELDS/YesNo you will see this clearly in the Object Properties window.  This is a key reference window when using the Model API and is your friend, trust me.

The other three properties that are NOT real are of course inherited.  As inheritance is defined using the ‘Is A’ verb, in this case FIELDS/YesNo – FLD Is a FLD – FIELDS Status.  YesNo inherits from the FIELDS/Status field. 

Double click the Target Object FIELDS/Status in the Model Editor and you will see the inherited triples mostly relate to the details in the Object Properties window.  There is a small exception with the Control SYS triple which is a bug/feature/design consideration but I will leave that out of scope for this post, just note that it is there.

Generally speaking if a triple is repeated or overridden at a higher level it (the implicit triple) takes precedence over the inherited triple and therefore they are not shown.  i.e. The Limits SYS (All) triple only shows at level 1 but in fact it is entered at both Level 1 (FIELDS/YesNo) and Level 2 (FIELDS/Status).

The rest is just about understanding how to traverse through objects and related triples in the model.  There are also lots of other cool API methods to help with automation.

Post III will go into more detail about the methods that are available within the Model API with a focus on traversing the Model Editor and its triples.  Hopefully, introducing the concepts above will help you succeed.

Thanks for reading.

Lee.

The great CA Plex ‘Entity Creator’ – Update 2.0

Things have been a little quite on the ‘Entity Creator’ front for a while, this is mainly due to other projects and priorities, like leaning .NET C# to assist me more when Plex 7.0 comes to GA which is soon, which is great J

I had a few items outstanding from my last update

http://leedare-plex2e.blogspot.co.nz/2011/11/great-ca-plex-entity-creator-update.html

I have made some progress with these in recent weeks.  Mainly around the entry of non key attributes for the new entity.  This was quite a challenge as I wanted to cater for field replacement overrides, for text and field naming clashes.  I have also managed to improve the workflow, error messaging and validations to ensure the new entity and all its related objects and triples are added correctly.

I am pleased to say that the next part of the puzzle is complete.

Assuming that you have read the previous postings here is a sneak preview with the latest editions to the tool.

So! What’s new on the eye candy and functionality part then Lee?

This is the Entity Attributes entry screen.  You can select a field from a user defined pick list, give it a name (which is validated) and override the field and decimals place lengths as appropriate.

You can also select other entities in the model to create a ‘Refers To’ foreign key relationship.

‘For Text’ if supported if you wish and just like CA Plex itself, if referring to any file more than once then a ‘For Text’ qualifier is required for second and subsequent relationship declarations.

Upon clicking next and assuming you have passed the relevant validations then the following screen shows a summary of the entity to be created and a easy to view tree control.  (In the future I will allow you to expand the ‘Owned By’ or ‘Refers To’ relations and select virtual fields.

That’s about it for now apart from the fact that you can also decide if ‘Sharing’ is used when you confirm the entity creation on the confirmation screen.

Another little note is that internally the system handles replacement field (automatic override) name clashes in a similar way to Plex and 2E by using a surrogate suffix.  As you would expect the tool advises you if this happens.

Hope you like what you have seen.

Thanks for reading.

Lee.