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.

The Sorcerers Apprentice.

Hi,

I have been aware of the 'Varianted Source Code' models that Roger Griffith has made available for the community for quite a while and today with the release of version 1.1 which has C# client code support all ready for the GA Release of CA Plex 7.0.  We now have some additional sources :-).  FYI - I don't know when this is coming out but it can't be far away now :-).

See the link below.

http://wiki.plexinfo.net/index.php?title=Varianted_Source_Code_Solution_For_CA_Plex&oldid=4855

There are always Pro's and Con's of any approach but this solution seems pretty fair to me. Obviously, if you are a C++ and RPGIV typical client server customer and not changing in the near future then this post will be of little relevance (or is it - read on).  I can think of only one other small issue in that if you prefer to use triples for setting the language at a function level rather than variants then this might need some re-factoring.

If, however, you are planning on migrating your client (or server for that matter) to c# .NET/Java etc you may as well start to reduce your impact for the big move.  By replacing your own source code calls for the shipped code supported by the varianted models sooner in the process you can only win. Remember these are available NOW and can be used with Plex 6.1.

This only leaves your own 'personal' or 'application specific' source code.  A little like User Source in 2E sometimes these are just fit for a purpose and not migratable.  Others simply may need tweaking.  Not a bad time to do some impact analysis and determine whether you need to brush up on some C#.

Therefore, I have a small challenge for people.  If you have some useful generic Source Code.  Any language (Java, C++, RPG IV or C#), let's share it and see if others can convert it across all the platforms.  Then Roger and his team could keep the shipped models up to date and everyone's a winner.  For every routine that is sent to me I will PERSONALLY ensure that they are all converted to relevant C# code.  Any volunteers from the community to pick up C++, Java and RPG IV?  I can get these done but not as quickly I am afraid :-(.  This is courtesy of my bosses at www.sasit.co.nz. 

I'm thinking of advanced String routines like.

• Count xString occurs y times in zString
• Replace Double Spaces with single space
• IsNumeric?
• IsAlphaNumeric?
• PasswordStrength
• Is CharactersOnly
• CalculateStringLength
• ReserveString
• SentenceStyleCase
• IsEmailAddress?
• Replace xString with yString in zString
• GenerateRandomNumber (Start, Max, ZeroFill?)
• GenerateRandomString xLength

I'm sure that this list could get quite exhaustive (Suggestions welcome) but I am happy to co-ordinate this effort if people just add some stuff they want to share to the comments section.  So cut and paste some code and a description or just make a request.  

Thanks for reading. 

Lee.

P.S. Disclaimer - if code is Copyright please include and acknowledge source etc.

Community Links

Added a few links.  Lucio's site and Desynit's Feed Aggregator for Plex and 2E .

That's them.  The community ones.....

Tidied a few broken links whilst I was there. If you want yours added. Drop me a comment in the comments section below.

Thanks for reading.
Lee.

Translator for CA Plex project!!!

Translator required!   Übersetzer erforderlich!  Traductor necesario!  
Traducteur obligatoires!   Vertaler Verplicht!   Traduttore obbligatori!
翻译 ! अनुवादक आवश्यक!!  Þýðandi Nauðsynleg! Translator Kinakailangan!!
Traduttore obbligatori!   翻訳者は​​必要！

Some of you know that I have been working on a small project with .NET C# and the CA Plex Model API.  The project was for an entity creator and I have decided that I wanted to learn and understand a little more about localisation with this technology too.

Here is the link - Entity Creator Blog post.

Well the good news is that I worked it out...... The bad news is that I struggle a little with the actual translation.

I struggle with two areas.

1. Context - Everytime I type a small sentence or single word I get a few choices (Google Translate) which doesn't help me one little bit.
2. Plex centric words - I know that many of us use the Plex terms from an English perspective.  i.e. I assume we all know a parent child relationship as "Known By".

My call to the community is that I would like to internationali(s/z)e the entity creator before I aim to get it open sourced for the community to extend (if you want to), or to discect if that is also of interest.

So calling all German, Spanish, Danish, Indian, Tivolian or other language converters in the community to assist with the translation of around 40 or 50 literals.  If you are interested please email me via LinkedIn (See link on blog) or put a comment and your email (I won't publish it) and I will contact you.

Thanks for reading.
Lee.

The great CA Plex 'Entity Creator' - Update

What started out as a wee (little) test application for me to learn and understand a bit about DotNet C# and the CA Plex ModelAPI has blown out (my obsession) into a full featured Entity Creation Utility.   I am also fully aware of the differences in terminology and approach between us Plexers and DotNetters which has been really useful for my company as we have a whole host of different development skills and disciplines and I feel like I can cross communicate J

The cool thing is that my employer http://www.sasit.co.nz/ (shameless plug I know) and our clients (current and future) will benefit hugely from this development when they see just how easy it is to enter all the relevant details into a CA Plex application model and generate code for all our target databases.

If I am to be honest there is still quite a lot to finish off like:-

·         Entering Non-Key fields (Next project)

·         Dealing for Foreign Key Relationships/OptionalitySYS and Virtual Fields

·         Advanced validations

·         Error Rollback

·         Schema Import

Not to mention a rethink on the GUI and the application C# architecture now that I have learnt a lot more about this environment.

·         Code layout and structure

·         Object design

·         GUI i.e. A TreeView control or something similar etc

However, for a work in progress (WIP), another one of those TLA’s  I think that it is worthy blogging about and giving some screenshots.  All feedback is useful and appreciated and I believe I have finally fixed the comments section too. J

This all started in a innocent post called RTFM and I will also follow up with some addition posts around the way I went about it and the features of the ModelAPI, along with a few of the traps that I fell into along the way.

The premise of the original exercise was to be able to quickly create a standard CA Plex entity with our default inheritance, Surrogate Key field and some internal naming conventions honoured....  I am now at the stage where the utility handles Surrogate (The DotNetters call this an auto increment key) and/or Natural Keys, File to File key relations, override attributes, labels, narratives and low level field and file/view implementation naming.  A far cry from the original brief and I still have a roadmap as long as my arm.

So take a look below at a few screen prints with some basic commentary of what the utility currently achieves for me and future posts will show you the finished utility (Hopefully).

Overview

A simple model with three entities

Fig 1. CA Plex Object Browser

These represent a standard Grandparent, Parent, Child hierarchy.  These could have been modelled differently without ‘Owned By’ etc but that modelling approach is debate for another day.  For now the triples that describe this 3 tier relationship have been entered as below.

Fig 2. The selected entities definition triples.

Taking a closer look at Entity ‘LV3 level 3’ you will see its entity attributes described as

Fig 3. The entity attributes showing no overrides.

i.e. Very simple and no attributes and no renaming of fields etc.

We implemented a policy at our shop of using TLA (Three letter acronyms) to describe of business entities and we like to replace the inherited field names whether they are resolved via a Owned By, Refers to or even as virtual fields.  This is just a ‘in-house’ preference and (we feel) aides with the myriad of people who need to write queries, data warehouse data extraction and other extracts like data downloads and excel spreadsheets.

We also tend to follow through the TLS naming convention for our tables (physical files) and views etc rather than defaulting to the generated names.

Fig 4. The File and Implementation names for the table and default views.

And I haven’t even covered labels for the fields and entity and field narratives.  As you are all aware this can lead to quite a bit of entry on our part for even a simple entity.

HENCE MY LITTLE UTILITY!!!!!.

I introduce the aptly named ‘Entity Creator’, I wanted to say that with a Boxing Ring influenced Master of Ceremonies voice but realised that wouldn’t translate on a textual blog. 

Entity Creator as described a little above is a wizard that guides the developer through the perilous task of setting up an entity and its fields. (Currently tailored to our environment, but adaptable and extendable enough for others to take a look).

So let’s for demonstrable purposes add an extra level to our setup called ‘LVL Level 4’.

Fig 5. The first of the Wizard screens.

By not selecting a Surrogate based key we are therefore selecting natural keys and we get an opportunity to enter the ‘Owned By’ and ‘Known By’ relationships.

Fig 6. Natural keys showing ‘Owned By’ entities for selection.

This shows a selection of ‘Owned By’ and a list of the business entities in the model.  The application stores a list of the business entities so some set up is required for old models but that would be straight forward to complete or I might even just import them sometime in the future.  Roadmap item?

You will see that the keys of the chosen entity are displayed for instant developer feedback.

Fig 7. Natural keys showing ‘Known By’ field and the options for key selection.

Now let’s enter the ‘Known By’ for this entity.  You will see that a different field set up is presented to the user and you simply enter the field name (The prefix is automatically applied so no need to repeat this).  And the select from a choice of fields (Configuration roadmap item already noted J).

If applicable the character length and decimal places override are available.  If these are left blank the details as depicted on the screen apply through normal inheritance.

Note: As I was new to C# and .NET (DotNet) I decided to hard this to 5 fields.  I don’t regret doing this from a learning perspective but I will refactor the application in the future to perhaps display these in the different way.

Clicking next will take us to the Field Labels and Narrative screen which can be bypassed (if you wish).

Fig 8. Editing of the labels for a field.

You will see I have indicated the values for the labels and field narrative for the ‘Known By’  The ‘Owned by’ labels and narratives are already present due to the inheritance (assuming you entered them).  In the future this screen will also handle the non key attributes, refers to and virtual fields too.  I’ve just got to get a bit better at Dot Net first.

The final screen is the confirmation screen.

You get to choose what triples/objects are or are not created for your entity and also you can see the statistics i.e. what was created.  ‘Show Summary only’ is the number of objects, triples and narratives and the timings.  ‘Summary and Detail’

Once you have created the entity you should see something like this.

Fig 9. Options for what we want created and the user feedback.

This is 17 objects, 33 triples and 2 narratives created and entered in 377ms.  Not bad aye!!!

Fig 10. Some of the new objects, triples and narratives shown in the model.

So I hope you like what you have seen and I thank my company http://www.sasit.co.nz/ with allowing me the time to learn more about these technologies. (Visit our website for ideas on what we can do for your IT business).   I hope that this blog inspires you to look at this technology yourself and I’d be delighted to assist with your projects.

Until next time.

Thanks for reading. 
Lee.

Engineering Flowchart

Rory Hewitt one of the developers for the 2E product that we all love to use recently posted an image which made perfect sense for solving common engineering problems.

I couldn't help but consider this problem with my 2E glasses on. :-)

Thanks for reading.
Lee.

A little look at Plex-XML

Many of you may have had read about the Plex-XML framework from Allabout Gmbh.  There have been mentions online (LinkedIn - Plex group or PlexWiki for example).  The guys were at the conference in 2007 and this caused quite a stir in the Plex community.  Well the technology is still going strong.

I decided that I’d take a look.  This is the great thing about having a role which is focused on R&D and application architecture, you get to play with things, this is of course allowed by my employer www.sasit.co.nz who specialise in mission critical systems hosting and development (Harmless plug) so take a  look at the web page.  The pressure comes when you need to back up your decisions, so interesting times.....

My investigation was a case of downloading the relevant stuff from the guys as well as Eclipse (IDE), MySQL (Database), Java JRE (Runtime), Senchas ExtJS (Javascript control library), Tomcat (Web Server) and some drivers etc.  A full list of requirements and how to put this all together is on the Plex-XML website (Wiki).

So after some great support from the guys at Allabout I did end up with a fully working tutorial application.  

A screenshot from the tutorial.

But that’s cheating though isn’t it.  All the hard work was done for me.  I needed to know what all the heaving lifting requirements are in order to evaluate further.  So I then decided to replicate this for one of my own entities from ‘Plex entity entry’ right through to all the configuration files and framework parameters. 

I chose a very basic entity with a numeric key, short description, date, long description (notes) and a status and “NO!!!!”, I am not going to describe every step here as:-

1.       It’s not the scope of this blog post.

2.       It’s already described in the Plex-XML wiki

So I followed the instructions once more and I made quite a few small mistakes with my naming conventions etc so be careful when doing these.  But, I did manage to get it all working once I knew what to change and create.

My new entity :-)

What I liked was the out of the box stuff.  I never coded the date picker or the x of xxx characters remaining stuff.  It just happened!!! J

As I have already alluded to, the pain for me was the configuration files etc and I am chuffed to bits to hear of another company from Germany who have been promoting their utility to help them with the Plex-XML framework.  Te@mconsult.  Check out this link. These two combined make all the difference and I for one can’t wait until the public beta commences.

So ‘all in all’ this was a great experience.  I strongly recommend that everyone takes a look at many of the 3^rd party patterns that are available for CA Plex.  Sure it’s great to be a developer and cut your own, but some of these frameworks and patterns from some of the major players have been on the go for a few years now and that effort vs price (if applicable) really is a “no brainer”.

Thanks for reading.

Lee.

Beginners Guide to the CA Plex Model API using C# .NET

Firstly thank you to Rob Layzell for inspiring this blog.   If it wasn’t for his lab exercises I would have done this Model API exercise and subsequent blog using CA Plex and component import.  Now, whilst this is probably a cool thing using a code generation tool to interrogate and update the code generation tool repository (I am sure there must be a word in the OO world to describe this. JJJ).  In the back of my mind I was also acutely aware that release 7.0 is entering beta testing and the much anticipated C#.NET (WPF) client will soon be upon us.  So there isn’t a better opportunity for me to sharpen the old grey matter with some learning than this. 

I chose to continue with the C# coding for the simple reason that it would be worthwhile me understanding what .NET developers need to do as I will ultimately be looking to target .NET for my future applications.  And, of course, enable me an opportunity to learn Visual Studio, some pigeon C# and understand the inner workings of this environment.  All worthwhile skills for when the 4GL needs a little investigation, tweaking or debuggingJ.

We have had C# for server code generation since release 6.0.  Release 6.1 brought WCF to strengthen this offering.  With 7.0 we will have the client side resolved too with the promise of XAML and WPF.  The web service import is another tool that simplifies the integration and consumption of web services, so, all in all, good times ahead.

So back to Rob's unintended blog influence.  His tutorials for .NET used numerous examples of Visual Studio and C#.NET.  One in particular that took my fancy was Lab 10 and related to consuming the PlexAPI COM component and creating triples in the local model.  The ModelAPI is described as being useful for pattern designers in the online help in order for them to automate much of the configuration and setup for using their patterns.  I also see it as an opportunity to ensure that another level of automation is included in the tool.

Anyhow, seasoned CA Plex developers know we already have metacode to influence the generated code.  We also have patterns and inheritance to ensure consistent design or as I call it, conformity to the application architecture.  There are still of course plenty of areas with regard to modelling that a developer could easily get wrong when entering the triples.

In my last blog I alluded to a small entity creation tool that I am creating (UPDATE – This has blown into a full blown too now).  This is to ensure that the fields and files that I enter into the application model conform to our standards i.e. naming, inheritance, default field lengths, narrative being entered and labels etc.  As we are a new CA Plex (long time 2E shop) I am still working on these standards and experimenting but I will share the code and a sample model on request (note that this does currently have a degree of hardcoding at the moment but more than enough detail for people to get acquainted).

For those that are interested in taking this further and perhaps helping me improve the utility, just drop me your email in the comments section. J

For me this (ModelAPI) is too quickly overlooked but if you are serious about CA Plex and modelling then these are exactly the type of utilities (Add-Ins) that one should be considering.  These will further improve your team’s productivity as it is pretty quick and easy to tailor for your environment once you get your head around the API and the underlying model structure.  Just take a look at the StellaTools from George.

I recommend any CA Plex developer to take some time to understand what you can achieve with this feature.  This is quite an in depth subject so I feel that this will eventually become a four part series, so, if you are keen....

Part II – ‘Model API and the model repository’ will cover the underlying architecture of the model.

Part III – ‘Key Model API commands’ will go into detail about some of the core commands that you will need to understand in order to develop against the COM API and sow some of the theory covered in part II together.

Part IV – ‘Some DotNet Tips and Tricks’ will show some programming tips and I hope should be enough to inspire a few of you to ‘RTFM’ with regard to the Model API.

All feedback is appreciated.  Until then.

Thanks for reading.
Lee.

RTFM

“RTFM!” (Read the effing manual) - that was the polite version.

That’s what I was told when I first started programming.  Not every time (obviously), but on that odd occasion where the question was a repeatedly asked one (by me) or that time the more senior programmer didn't eat his oats in the morning.

To this day I still hear this from the more seasoned developers around me.  But I must say that this phrase (I believe) is in steep decline.  Could it be said that my generation of developers may be the last to utter this immortal programming phrase.  You see (or should I say hear) more and more “RTFM” is being replaced by “Just Google it.”

Today I was working with CA Plex 6.1’s Model API.  I was trying to automate a common task that I perform in my model and ultimately cut down on some keystrokes, mistakes and most importantly, ensure ‘THAT I’ conform to the standards ‘THAT I’ have decided and (hopefully) along the way help the other developers in the team J.

I was working from some excellent examples from CA regarding the Model API and thought I’d try a small example using C# WinForms and Visual Studio 2008.  All I wanted to do was create a new entity with appropriate naming standards, fields and keys all with correct inheritance from our patterns etc.  So breaking the problem domain down into small manageable chunks (isn’t that now known as an agile sprint), I decided to get the Entity Prefix (I like these), Entity Name and Entity Inheritance easily created.  The rest will come as the AddIn matures and I implement all the ideas and wizardry in the roadmap. 

As I have said I am creating this pioneering utility using the Model API (Version 3.0) in Plex 6.1 and I will deploy the final program as an AddIn. I have also used this as an excuse to brush up a little on Visual Studio and C# as we are going to be heavily reliant on this IDE once Plex 7.0 comes out and we are all doing DotNet stuff galore. 

I will blog a little more in the future about how I did this (It is only basic and I am still learning) but I have to say that the Model API 3.0 is quite powerful, just ask George Jeffcock about his Stella Tools. 

Here is a sneak peek at the current screen. 

As you can see it is about as simple as one can get, but, without much knowledge of C# I quickly became stuck, stranded, frustrated, challenged and peeeeeeed off.    Anyhow, forget asking Jeeves or posting on some technical forum.  For older scholars picking up the manual or downloading that e-book PDF you had been considering is also a waste of time and effort. 

If you want to code nowadays, it appears you just “Google it”. 

I am not sure whether this is like

1.       4GL of C# coding

2.       Cheat sheet

3.       Or simply just good common sense to utilise a million experts rather than one book

.......BUT.......

I got the answers I needed pretty quickly and was able to continue with pilot project in earnest.

I have a great mental roadmap for the utility and only time will tell how it matures.  But for all us elder statesman of the Plex community, I'll borrow terminology from one of Ramon Chen’s key marketing phrases from the early days of Obsydian.

“Stop coding, start Googling.”

Thanks for reading. 

Lee.