CML mini tutorial - Discussion thread

[Mark Stega]

This is the companion thread for the CML mini tutorial. All discussion should be here.

[IVB]

Tutorial seems a little light so far...

[Mark Stega]

Tutorial seems a little light so far...There is one in every crowd :-)

[beelzerob]

This is the companion thread for the CML mini tutorial. All discussion should be here.

Noooooooooooooo.....you'll give away all our secrets!! :shock:

We're supposed to cultivate the idea that writing CML drivers is well beyond a mortal's reach... :cool

[znelbok]

FOr those attempting this tutorial and dont like the editor in the driver harness and want to use something else, crimson editor is a great package. Rohan has created syntax highliting for CML based code (http://www.charmedquark.com/vb_forum/showthread.php?t=2584&highlight=crimson+editor)

Crimson Editor can be found here
http://www.crimsoneditor.com/

As the errors that come up when compiling have line numbers, you may want to turn on line numbers (Tools preferences Visual - Show Line Numbers)

Mick

[ellisr63]

Thanks Mark for doing the tutorial for us non programmers

[znelbok]

When you create a Method there is a return. Is this just a way of exiting the method. If the metod does not return any values for use elsewhere then it would appear that we return either a true or an integer

Why in our example for the FreeCommResource do we return a Boolean and for the Start metod we return a 0.

Why is there a difference?

If we returned a false instead of a true, what impact would that have, similarily if we returned a value other than 0 what impact would that have.

Keep up the good work

Mick

[znelbok]

what does the significance of the m_ have.

eg in the FreeCommResource method
m_Port.GetIsOpen()
m_Port.Close()

[Dean Roddey]

When you create a Method there is a return. Is this just a way of exiting the method. If the metod does not return any values for use elsewhere then it would appear that we return either a true or an integer


Some methods return some status value, and some don't. They can also return information back to the caller by way of [Out] parameters, but it's a convention, long used in software, that they can also return some value. The return can be of any class type that is 'copyable' meaning that a copy can be made of it. Each class is either copyable or not and it's indicated in the class documentation.


Why in our example for the FreeCommResource do we return a Boolean and for the Start metod we return a 0.


The get and free comm resource method is asking you to return true if you successfully created/freed the comm resource, or false if you did not. This lets the caller (CQC itself in this case) know whether it worked or not. If you say it did, you return true, then it moves on to the next step in getting your driver up and running.

Start() is a generic method that is used to invoke a method from the outside world. There has to be some convention for what method is used to start the processing of the macro, and Start() is it. The return is some arbitrary value that you can return to indicate something to the caller. Mostly it's not used, and it's definitley not used in drivers since the Start() method is just there to allow the driver to invoke a simulator that simulates how the driver works when it's running in CQCServer. It's not used at all when actually used in the real CQCServer environment. Instead CQCServer just calls the various methods that it knows are there.

Most macros, OTOH, are invoked in a very generic way and the caller can only assume that there is a Start() method that returns an Int4 value.

Note that Start() is only called from the 'outside world', to start the macro running. Once that is done, the macro is free to call any other methods it needs to, of its own, or in other classes that it imports. So only classes intended to be run from the outside will have a Start(), not classes that are just for use by other macro classes.

[znelbok]

The get and free comm resource method is asking you to return true if you successfully created/freed the comm resource, or false if you did not.


Ok so while I understand that, the way I read that method is that if the port is open then close it and then end the if and return true. This will return true regarldess of the outcome from the if statement - so we dont know if it has been closed or not (not until we try to in the GetCOmmResource method at least)

mick

[bph]

what does the significance of the m_ have.

eg in the FreeCommResource method
m_Port.GetIsOpen()
m_Port.Close()
It's a variable naming convention (http://en.wikipedia.org/wiki/Identifier_naming_convention) (or part of one). Since CML calls a "global variable" a "member", the m is probably short for Member. Many other programming languages would use "m" for a module-level, and in CML a macro or driver would be a "module (http://en.wikipedia.org/wiki/Module_%28programming%29)". As a global variable, a member is scoped (http://en.wikipedia.org/wiki/Variable#Scope_and_extent) to the entire class. In other words this is a variable that can be accessed and changed anywhere in the module.

Global variables are a two-edged sword. They are very convenient, but they also allow some bad coding practices to sneak in (especially with inexperienced programmers).

The other kind of scope is a local variable, which can only be used in one particular function or subroutine.

Note that the m_ doesn't MAKE it a global variable (being declared as a member does), but it indicates in a very clear way that this variable global. This helps avoid those programming errors.

--

Edit: I include "objects" in my concept of "variable", and realize that members (and other variables) are all objects in CML.

[Dean Roddey]

If the close failed, it would throw an exception and there would be no return value coming back. CQCServer would see that something went awry and the driver would still be in the state where it's trying to close the comm resource. As a practical matter though, there's little that can go wrong in that, since the port is either open or not. If it is, it'll be closed, else nothing will happen. Either way, it'll be closed before the return.

It is possibly for a driver to screw up and not close the resource of course, which isn't good since it'll stay open and they won't be able to open it next time. So it's something that you do want to make sure you get right.

[znelbok]

Hey Mark

What happened. I have been poised for the next installment of your thread and youve kept me hanging for two days now :-)

Mick

[Mark Stega]

Mick,

It's coming -- It has been interrupted by a 102 degree fever, massive head cold, & sore throat leading to an overwhelming need to sleep, a lot...

[znelbok]

Oh, Umm - Thats one way to make a guy feel guilty about asking.

Hope you get better soon - take it easy

[rhamer]

Mick,

It's coming -- It has been interrupted by a 102 degree fever, massive head cold, & sore throat leading to an overwhelming need to sleep, a lot...

But don't you have access to some really good drugs :shock:

Cheers

Rohan

[Mark Stega]

But don't you have access to some really good drugs :shock:

Yes, but not ones that do any good for viral infections :-)

[Ripper]

The last 2 years anytime me or the fiance are sick we take something called "ColdFX" and it seems within 24 hours I'm feeling much better and 72 hours later seem normal again...not sure if its the placebo effect or what but it seems to work for us every time we get a cold.

[znelbok]

I am assuming that you have beaten the virus you had by now.

Can we continue with this mini tutorial please - if you have the time

mick

[Mark Stega]

I am assuming that you have beaten the virus you had by now.

Can we continue with this mini tutorial please - if you have the time

mickMick,

Sorry, this totally slipped my mind! After being sick I launched into 1.7 DNV work and couldn't do driver work for a couple of releases due to a small 1.7 bug.

I'll pick it up again and aim to have the next installment out very shortly.

[Mark Stega]

The tutorial has now been updated. The driver creates dynamic field depending upon the answers given during driver installation as driven by the manifest file.

[znelbok]

I have read this tut and have a few questions but I wont ask them until it is completed as I suspect some will be answered when all is revealed.

Mark - Can you continue with it when you get a chance

Thanks

Mick

[Squintz]

znelbok,

Go ahead and ask your questions. Mark is going to be busy getting the .Net IV up to date with the 2.0 release.

[znelbok]

Thanks

Any chance someone else could take up the torch and continue the tutorial if Mark is going to be busy. This method is really working well for me.

I'll compile all my questions tonight, although I believe they are based on upcoming information.

Mick

[znelbok]

wrt the tutorial example

In the members section there is this

FieldIDArray m_FieldID_STBCommand;

Now I know what an array is from my maths - Is this the same thing, or has Array got a slightly different meaning here.

Under the constructor we have

m_FieldID_STBCommand(kMaxSTBs);

Why use a literal here instead of a value (in this case 2).

What is the Contructor doing for us - why do I need something here?


Enum

I guess this is something like the mapping in the PDL structure. What I cant work out is how to use it.
eg
STBCommand has this
Digit0 : "0"

Does this mean that that when we use a value of Digit0 in the driver it sends a 0 - something like assigning a constant?

From the manifest, the user is aksed for the type of stb's to be used (2 max). The first has a name of STB1 and the second has a name of STB2. I assume that the selected value here is what is passed to the driver, yet I cant find any reference to STB1 or STB2 - is this because the driver has not been completed

Thats all for now - more to come

[Mark Stega]

FieldIDArray m_FieldID_STBCommand;

Now I know what an array is from my maths - Is this the same thing, or has Array got a slightly different meaning here.
It is the same thing, a list of field ID's that will be referenced via an index.
m_FieldID_STBCommand(kMaxSTBs);

Why use a literal here instead of a value (in this case 2).

What is the Contructor doing for us - why do I need something here?I use a literal as sometime later I might want to change the number of STB's that are supported (there is a box that supports 6 if I remember correctly). So by having a literal, kMaxSTBs, I change that value in one place, and everywhere I use it, the constructor, loops iniitalizing values, etc. it is changed in all places, rather than searching code for the constant 2 and having to decide if the 2 refers to the STB quantity or is unrelated. The constructor is sizing the array to have two elements.
From the manifest, the user is aksed for the type of stb's to be used (2 max). The first has a name of STB1 and the second has a name of STB2. I assume that the selected value here is what is passed to the driver, yet I cant find any reference to STB1 or STB2 - is this because the driver has not been completed
We do use the types given by the user to set the allowable commands in the following loop: While ( index < kMaxSTBs)
// Get the STB type
stb := "STB";
stb.AppendCard4( index + 1 , Radices.Hex );
m_STBTypes[index].FromText(PromptVals.GetValue(stb, "Selected"));

// Based on the type, create a command field

If (m_STBTypes[index] != STBType.None)
fldName := "STB";
fldName.AppendCard4(index + 1, Radices.Dec);
fldName.Append("Command");
stbCommand.FormatList(limStr, "Enum: ", ',', False);
tmpFld.SetWithLimits( fldName, CQCFldTypes.String, CQCFldAccess.Write, limStr);
tmpFld.SetAlwaysWrite(True);
fields.AddObject(tmpFld);
EndIf;

// Set up for the next STB definition
index++;
EndWhile;
Look at the use of PromptVals.GetValue(...)

[znelbok]

Thanks Mark

m_STBTypes[index].FromText(PromptVals.GetValue(stb, "Selected"));

I still dont see how it is referred to the prompt in the manifest. Should the stb be stb1 (or stb2)?

edit:- I think I see it now, the stb actually has a value of "STB1" or "STB2" depending on the index value due to the appending of the stb variable

What in this line tells the driver to refer to the first or second prompt?

Can I use the PromptVals in a literal

eg

kMaxZones(PromptVals.GetValue(NoOfZones, "Selected"))

where NoOfZones is the prompt name from the manifest and is a card4 (1-32)

Mick

[Dean Roddey]

He's building up the name dynamically. He's putting STB into a string, and then appending the current loop index value.


stb := "STB";
stb.AppendCard4( index + 1 , Radices.Hex );

[zaccari]

Mark,
I'd love to see an addition on how to use the tools. I'm trying to work with a serial driver and although I've used similar tools before, I don't seem to get the information coming across the port and troubleshooting it seems difficult without a bit more information.

Thanks,
Russ...

[noworries]

Here's a gentle bump as a reminder to continue the CML tutorial when possible.

Mark,
I'd love to see an addition on how to use the tools. I'm trying to work with a serial driver and although I've used similar tools before, I don't seem to get the information coming across the port and troubleshooting it seems difficult without a bit more information.

Thanks,
Russ...

I'll also second adding a primer on using the debugger. I seem inconsistently to see variable values- it'll often just list the variable itself, yet the code continues as if its been set to the expected value. I'd also like to set up a variable watch list if possible in addition to the field browser.

[znelbok]

I too am eagerly awaiting the continuation of the tutorial

Bring it on Mark :-)

[znelbok]

Mark - Can you please continue with this tutorial

I am relying on you to teach me CML.

Mick

[Squintz]

znelbok,

Have you tried re-reading the Driver Dev and CML tutorials. Those will teach you more than Mark ever could. You might be surprised at how much easier you pick things up now that you have been exposed to the language a little.

[znelbok]

Reading is not the method that I learn best from. People learn best by one of three ways, reading, watching and doing. I am not Reading, but moreso the doing, hence the example that Mark is doing has gotten me further than any reading I have done.

But it looks like I will have to resign myself to a ardious task of trying to learn from reading the manual.

Mick

[Squintz]

I am a hands-on type of learner myself. I was just suggesting that you read as well as follow along. Dean has provided more details in his documentation than Mark ever could. But as you start to understand why Mark is doing some of the things he does you will be able to read Deans documentation and actually follow along with what Dean says. I think it took me 3 or 4 attempts at reading Deans docs before I saw the complete picture of how things work.

Either Way... Good Luck!

[Mark Stega]

Are there any specific requests for the tutorial in terms of topics? It seems that we kiund of ran out of steam on the Sky example... Or is there something to add to that that would be useful?

[jpants]

I think takings a simple PDL driver and translating that into CML might be the best since most of us can grasp the PDL thingy. Maybe take a one way driver translate to CML for CML 101 then make it 2-way for CML 202...

Just my .02 (I, We know how busy you are.)


John

[zaccari]

I can relate what would have helped me pick it up easier but unfortunately, I think that's going to take a Dean video to get a portion of it right. A video on the environment would be great. The other thing is a side-by-side of the manual with the actual process of doing a driver. I know Dean has some of that in the documentation but I had an extremely hard time figuring out how CML connected to my driver. Now that I have a better grasp on what's where, I can relate to the documentation but finding the important parts in the documentation just isn't easy.

Russ...

[Dean Roddey]

I'm kind of iffy as to how well some of those more advanced programming things could be gotten across in a video. There would be a lot of code involved and videos are more for getting the big picture, not so good for drilling down into heavy details.

[zaccari]

Actually, the video I was suggesting was more about using the IDE. I agree, you can't teach someone to program via video. I haven't totally lost my mind yet.

Russ...

[Squintz]

Actually there is a site dedicated to teaching people Visual Studio programming via video. It's something like www.LearnVisualStudio.net. I purchased their lifetime membership when it was available and I learned a lot through their videos.

I think you can teach the basic concepts of programming rather fast. The written tutorials are certainly better for references. A video outlining the class structure and programming a simple driver which uses the Device Simulator would not be bad.

Dean, has created a couple videos on the IDE already which are not that bad for starters. I really think you should all give reading a shot again tho. Google for a general tutorial on object oriented programming. The more sources and examples you have the easier it will be for you to learn.

I also had a good bit of success with the Web Conference I did a few month back. Many people picked up enough to allow them to jump right in.

The Documents that Dean has written do lack in the example department. However, since each CML driver is open source they are great examples.

My recommendation for you guys is to take a simple CML driver. The one I used to learn from was the NetCallerID driver which is not in the official CQC Release. You can find it on the downloads page I think. I printed out that code and went through it line by line while looking up Keywords and Class Methods in Deans documentation. I made small notes next to the code as I figured something out. Then I skimed through the Driver Dev Tutorial again after that and it all made perfect since.

[zaccari]

Actually, I'd make a suggestion that extends on Squintz's. I'd suggest getting the Serial Monitor, get a driver for a device that you have and that is fairly simple and follow it through the steps. I think a flow diagram would have helped me. Something to connect the dots persay.

Russ...

[Squintz]

Serial monitors are very helpful and also ethereal for TCP/IP communications also.

An easy driver that does not require hardware would be the parsing of a web page. Take my Astrology.com Horoscope Driver for example. That was my first driver (Second being the BetaBrite). Pick a site with some information that you might want to view. CocoonTech has an RSS Feed for its news section. Other popular ones are the Amber Aleart, CNN News Headlines, Funny Jokes, Bible Reading, Random Quotes. Obviously weather has already been done.

I think my next web page parsing driver will be one for vonage.

But the only way you are going to learn is to dive in and start coding. Look up the information as you need it. There is a good How-To Parse a webpage article(http://www.cocoontech.com/index.php?showtopic=46) in the CocoonTechs how-to section. It was written in VBScript but its a short example and can easily be converted to CML. This is exactly what I used to create the Horoscope Driver.

[zaccari]

I'd love a pointer to that article. I have a web page parsing driver I want to write that won't be of any value to anyone else but will make my life MUCH easier.

Russ...

[Squintz]

Here it is. I will edit my post to include it.
http://www.cocoontech.com/index.php?showtopic=46

[znelbok]

Are there any specific requests for the tutorial in terms of topics? It seems that we kiund of ran out of steam on the Sky example... Or is there something to add to that that would be useful?
THe Sky example did the field creation but did not cover the polling or sending commands.

The suggestion for taking a simple two way PDL and converting it isa great idea.

If you want a suggestion, then my driver for the Mitubishi XD400U projector would suit me.

Mick

[Mark Stega]

I am cranking up a second thread for more CML examples. I am taking a one way PDL driver and converting it to two way in this example. The new thread is here (http://www.charmedquark.com/vb_forum/showthread.php?p=56581#post56581).

[znelbok]

Excellent news - very much appreciated

mick

[damian.flynn]

double cool, i just purchased one of these babies and at total of 12 plates.
-d

[Mark Stega]

double cool, i just purchased one of these babies and at total of 12 plates.
-dDamian,

Could you jump into testing? We have one other user also testing. We should be able to include the driver in the formal 2.1 release.

[znelbok]

You asked if anyone is reading - I am, I just dont have the time to digest it through the week. I hope to read it in depth on the weekend. I truly appreciate the effort.

Mick

[damian.flynn]

Mark,

My device arrived in Waltham MA, last firday, I am just waiting on some Xantec devices also to be delivered to the office, and I will have them picked up and droped back here in Ireland.

I expect to be able to play with the driver in about 2 weeks (assuming the customs officers have no objection!)

I have read the CML thread in detail, and its quite similar to most OO Languages, Thanks so much for this example and walk trought, I am going to shortly have time to take advantage of this and make a bash at coding for Quark.

cheers
Damian

[damian.flynn]

Hi,

Just got the tracking number for the Xantec kit, Its due to arrive in Waltham on May 4th, I will call the Pick Up crew to collect these next Monday/Tuesday and assuming Customs have no issues should be able to get testing within the next 14 days, etc.

This is the kit I'm looking forwarf to play with

AVAtrix

1 * AVAtrix Home Theater Routing System with DVI and Component Video - Model AVX-661
1 * 6x6 Cat 5 Matrix Router Expander - Model 1176
6 * Cat 5 to HDTV Connection Wallplate - Model 9878
2 * 1U Rack Ears - Model 1191
1 * 2U Rack Ears - Model 1192

Xantec

2 * Xantec MRC88 (Controller/Amp Only - No External Pads)
2 * Xantec PA4100X (100 WATT Four-Channel Power Amp)
Cheers
Damian

[Mark Stega]

Mark,

My device arrived in Waltham MA, last firday, I am just waiting on some Xantec devices also to be delivered to the office, and I will have them picked up and droped back here in Ireland.

I expect to be able to play with the driver in about 2 weeks (assuming the customs officers have no objection!)

I have read the CML thread in detail, and its quite similar to most OO Languages, Thanks so much for this example and walk trought, I am going to shortly have time to take advantage of this and make a bash at coding for Quark.

cheers
DamianGood - Just keep us posted and feel free to ask as many questions as needed!

[znelbok]

I have finally gotten back to looking at this tutorial

I am following it through and came accross this issue


Method GetCommResource() Returns Boolean
Begin
// Let's try to open our port
Try
m_Port.OpenCfg(m_PortPath, m_PortCfg, 2048, 2048);
EndTry;

Catch
Return False;
EndCatch;
Return True;
EndMethod
This is based on the code in post #3 - When I compile it I get an error

Line/Col=82/49
Expected a close parenthesis ')' here.
That puts a ) in the m_Port.Open line after m_PortCfg and before the 2048

i.e.
m_Port.OpenCfg(m_PortPath, m_PortCfg);
Why is this so, has something changed.

I am still in 2.4.x

Mick

PS - I noticed that Mark has removed it from a later post (#5) so what I have must be correct and it was carried over from before. Can Mark please fix it for the sake of consistency.

[Dean Roddey]

The version that takes the two buffer size values is OpenCfgBufs. OpenCfg only takes the first two parms.

[znelbok]

Doh - sorry for my stupidity. Mark said this
We look at GetCommResource() and FreeCommResource and we change the call to OpenCfgBufs() to OpenCfg() since we will not have really big amounts of protocol traffic.

And I took it literally without thinking about the two numbers at the end.

[znelbok]

After recovering from a PC failure (Its all working against me here lately), I finally got to the end of the Part I tutorial.

What happened to the rest of it. We get to a point where we have created fields, but there are no write commands for the readwrite fields. Mark has left it as if there is more to go.

Part II just looks at the conversion of a PDL to CML - and this refers to knowledge such as writing to a field that I would assume was in part I.

Mick.

[znelbok]

Bump - Is there an answer to the above question.

Mick

[Mark Stega]

Bump - Is there an answer to the above question.

Mick
The tutorials are as designed. Part I has the intent of writing a one way CML driver and Part II intorduces read-write fields in CML in the context of converting an existing PDL driver to be a two way CML driver.

[znelbok]

Yeah I understand what the intent was, but I dont think you finished it off - Part I at least.

Part I stops at the field creation and does not have any one way aspect to it - it does not write anything at all to the serial port.

Part II
makes this claim


1) The registration of fields (there are three, AutoSelect, AutoSelectLock, and GenericCommand).

2) How the BoolFldChanged and StringFldChanged methods cause text to be sent to the serial port.

3) What SendMessage does.

I am not going into detail here for this step as it has no more than what we did in the Sky driver previously. Hwever, if any of this is not clear, just post a message over in the discussion thread (http://www.charmedquark.com/vb_forum/showthread.php?t=2638).


number 1 was was covered mostly in Part I

numbers 2 & 3 were not covered in Part I, hence my question on is it finished.

Can you please check over it and see if I have erred here and if possible, when time permitts complete the sending of messages as I struggle to learn from reading (I learn better other ways, such as by example - which this tutorial helped immensely in doing).

Thanks

Mick

[Mark Stega]

Yeah I understand what the intent was, but I dont think you finished it off - Part I at least.

Part I stops at the field creation and does not have any one way aspect to it - it does not write anything at all to the serial port.

Part II
makes this claim



number 1 was was covered mostly in Part I

numbers 2 & 3 were not covered in Part I, hence my question on is it finished.

Can you please check over it and see if I have erred here and if possible, when time permitts complete the sending of messages as I struggle to learn from reading (I learn better other ways, such as by example - which this tutorial helped immensely in doing).

Thanks

Mick

#2 &3 are covered in the 2nd half of the tutorial, see posts #8 & #9