TM1 Forum

I've been trying to learn the TM1 API for about a day now, and I have a question that I feel is probably stupid, but I can't seem to find a simple answer to it.

What is a Value Pool, and what is a Value Capsule?
( If you're going to give me an answer along the lines of "It's a place where you store values" or quote something from the Reference manual, please don't bother )

Is a pool similar to an array while a capsule is like an element? are they typed? The simple explanation of what these objects are seems to be lacking.

Value pools hold the value capsules which represent the data.

Eg
String values are turned into a Tm1 value capsule using TM1ValString

The pool might contain 10 such capsules which represent 10 string values.

Guess you can think of a pool as memory allocation to hold the capsules. So it makes sense then that you create a pool for the capsule before you can create the capsule (or handle) - as you may have noticed in sample code you might have looked at.

aking wrote:I've been trying to learn the TM1 API for about a day now

And that would put you about 1% of the way to having a good understanding of how to program with it. Good luck with that.

tomok wrote:

aking wrote:I've been trying to learn the TM1 API for about a day now

And that would put you about 1% of the way to having a good understanding of how to program with it. Good luck with that.

1%? Optimist. And let's not even get started on the .Net API, where the "documentation" is an unstructured compiled help file.

The Tm1 API is not that difficult once you understand the fundamental programming concepts. It is object oriented so you can recycle the same code over most of the Tm1 objects.

Good luck with learning the API. Keep posting your questions and you'll most likely get a response to your problem.

jrizk wrote:The Tm1 API is not that difficult once you understand the fundamental programming concepts. It is object oriented so you can recycle the same code over most of the Tm1 objects.

It's many things, but object oriented it ain't. I'm not seeing any inheritance, polymorphism, or even encapsulation unless you work seriously hard to implement it yourself as a wrapper the way Paul Simon did with his EasyAPI... the concepts of value pools and capsules, not to mention the handles needed to servers and other objects, don't easily lend themselves to any of that.

The TM1 API language manipulates objects within the TM1 object model (and I think this may have been what you meant), but that doesn't make it truly object oriented, nor bring the benefits that real OO languages have.

But I do agree that with many chunks of code can be recycled more or less, particularly those relating to iterating through collections of different objects.

jrizk wrote:Good luck with learning the API. Keep posting your questions and you'll most likely get a response to your problem.

Depending on how one asks the question...

I believe the intention was for the API to lean toward an object oriented architecture - how well this was achieved is worth questioning but what is available is what is available - we can only guide those who would like to learn it.

jrizk wrote:I believe the intention was for the API to lean toward an object oriented architecture - how well this was achieved is worth questioning but what is available is what is available - we can only guide those who would like to learn it.

Are you talking about the Java and .NET APIs? Those I would happily call object-oriented APIs (poor documentation not withstanding). But I'm with Alan on this one if you're talking about the C API - it's a long, flat, ugly list of functions. Sure, they are intended to operate in various ways on the underlying, *conceptual* TM1 object model, but from a programmer's perspective you're not dealing with a nice set of classes, methods, properties, etc when you deal with the TM1 C API. I think Applix, at the time they created the TM1 C API, thought using the word "objects" in the function names and documentation made it "object-oriented", but the fact is it didn't, it isn't, and this particular API won't be object-oriented. As Alan mentions, there are some object-oriented wrappers around the C API bouncing around out there (full disclosure - my company offers one).

I'm not specifically picking on TM1 here - take something like the Windows Clipboard. If your time is limited and you have some options, would you rather use this to program with the Clipboard:
http://msdn.microsoft.com/en-us/library ... S.85).aspx

Or this:
http://msdn.microsoft.com/en-us/library ... board.aspx

The first option, like the TM1 C API, requires you to include declarations of the various functions your'e calling and potentially deal with the complexities of handles, memory, pointers, etc. The latter is a set of classes, methods and properties that largely insulates the programmer from all of those underlying complexities.

In TM1, take an example like creating a new TI process (which you've posted some sample TM1 C/VB API code for in a separate post, I believe). Cutting out the whitespace, that was somewhere from 40-60 lines of code to login and create a new TI process with a few lines of text in a Prolog in Epilog. In more of an object-oriented approach, you'd expect something that was closer to 10 lines of code or less for all of that *and* for it to be more understandable when you read it because you're working on something conceptual like a Server or Process class and not having to call 10 functions just to construct the handles you need in order to login.

One API isn't necessarily better than the other - it depends on what exactly someone needs to do and, most importantly, what they're capable of doing. Unless you have some background in computer programming (which I would guess the OP does not), I always suggest people use the TM1 C API as a last resort - if you can find an easier way to do what you need to do (TI, TM1 VBA "API", Java/.NET API's, and even 3rd party libraries) then I personally view that as a much better/saner choice. As a benefit of avoiding the C API, you are spared dealing with all of the memory management (value pools, for the OP) and pointers (session and object handles) that the TM1 C API barely tries to insulate you from.

Sorry for the prolonged post, but I think it's dangerous to blindly start posting chunks of TM1 C API code on a public forum without some strong warnings. Don't get me wrong - there are a lot more people using TM1 these days than there were a couple years ago and I'm glad to see people showing some interest in, among other things, the TM1 C API. But, the fact is that it's dangerous if someone that has little idea about what they're doing starts blindly copying TM1 C API code. Let's say they try to modify some posted API code in some way and pass a value pool handle where TM1 expects a session handle, for example, or they are using functions/properties that aren't officially supported/published by IBM that someone has posted, but which IBM decides to change completely in version 9.5.2 of TM1. Best case is their application/host application (Excel, Visual Studio, etc) crashes. Or maybe they end up with a small memory leak in their application or on the TM1 Server. Worst case is their production TM1 Server crashes.

Give someone enough rope...

Regards,
Mike

Ok, I think I've got it. You create the pool which is like a mem alloc, and then place a bunch of values in there, with untyped pointers to them.

It probably doesn't help that the sample code I was given was DailyWTF worthy.

Unless you have some background in computer programming (which I would guess the OP does not)

Ouch. I have a BS in Computer Sciences.

But, the fact is that it's dangerous if someone that has little idea about what they're doing starts blindly copying TM1 C API code.

Thus, interest in getting a clear idea about what pools and capsules were. I'm not normally satisfied with the "You do this and then this works" approach of learning, as this doesn't really lead to understanding, it lends itself more to the superstitious type of programming where you end up doing things that aren't necessary.

aking wrote:Ok, I think I've got it. You create the pool which is like a mem alloc, and then place a bunch of values in there, with untyped pointers to them.

It probably doesn't help that the sample code I was given was DailyWTF worthy.

That a good way to think of value pools and the values within them. And, if you forget to destroy any of those value pools or private, unregistered "objects" (e.g., subsets, views, etc) you run a risk of memory leaks (on the TM1 Server, primarily). It's possible that TM1 may doing some form of garbage collection at some stage, but it isn't obvious that anything like that actually happens if you forget to clean up after yourself.

Yes, the TM1-provided samples are pretty rough (not quite DailyWTF-worthy), but then any encapsulated TM1 C API snippet is going to look pretty bad because of the number of functional calls required. Sorry if you've inherited some bad code - that's certainly never fun.

Regards,
Mike