This article describes the various names for the primary key for a MultiValue developer working within the Cache’ software development environment. I would think this would only be of interest to those writing MultiValue applications using extended features of Cache’ and possibly to InterSystems employees who I am hoping will agree with me that this could be a bit overwhelming for a Cache’ beginner.
If you are converting a MultiValue application from another MV implementation, then primary keys and their names convert as you would expect, so this only applies once you want to expand into the wealth of add-on features that Cache’ brings to the table for a MultiValue developer. If you were to use a variety of tools for the variety of work we can do using Cache’ alone, then you might have a similar, if not more complex, scenario.
If using the Cache’ MultiValue Query Language, CMQL, from the colon prompt or in an MV select statement executed from MVBASIC, you can always refer to the primary key for a file as the @ID in our application. It is not a Property in a persistent Cache’ Class, however, which means it is not a Property we can reference anywhere outside of CMQL.
In the case of auto-incremented files, our Cache’ class for that file does not generate the @ID in the DICT automatically (rats), so we force that field into the DICT by coding it in an XData MVAdditionalDictItems section of the persistent class.
2. PartyId or similarly named key
We have coded our metadata source in Cache’ classes, so that each key has a synonym that is typically, but not always, the file name, sans package name, followed by Id. We have PartyId, ProfileId, OrgId, and AddressId, for example. An example of where it is otherwise is in the file that is keyed by Email, which is an e-mail address, one of the non-numeric primary keys.
There is a big caveat with this name for the primary key. In an auto-increment class it is also specified along with the @ID in the XData MVAdditionalDictItems section of the class. That means it is not an actual Property of the class. It is a Property when the @ID is not an auto-increment key, but otherwise it cannot be referenced within Zen pages or other Cache’ classes. It is then secret metadata that only CMQL knows about, just like the @ID. You can likely guess that I’m not delighted with that approach, but I can roll with it.
Think of ID in SQL as a synonym for @ID in CMQL.
For our software, we use ID instead of %ID in any SQL code, although these will function the same for us. There are a couple of cases where these would give different results, but we have no such cases in our application, so, for us, %ID returns the same results as ID in an SQL statement. Don’t use %ID in SnupNow–think of it as something we translate to ID when we see it in any examples or documentation.
Use %id only with Zen M-V-C and only with a Model, whether a persistent class or otherwise, where the primary key is an auto-increment key. In those cases, we could not give the primary key a name except for the DICT projection, so Zen gives it the name of %id.
I wish I could say that where it is @ID in CMQL and ID in SQL, it is %id in Zen M-V-C, but that is not the case. That is only true with an auto-increment key, otherwise you must use the synonym for @ID that is specified as the primary key property in the persistent class.
This is one case where I would have liked to see a different implementation so that %id would be the name for the modelId no matter how the values of a primary key are determined.
modelId is an attribute of a dataController object, corresponding to a hidden dataController component placed on a page and used by a form on the page, for example. This modelId does correspond to the @ID in all cases.
This is a method of %Persistent classes. If you call this method on an instance of a persistent class (a record), you get the value of the @ID for that record. The only place I am currently using this is in Model classes when I need the @ID from a record where the file has an auto-increment primary key. In those cases, we do not have another name for the primary key, so we can retrieve it this way. If we have a P.Party record (object) that we have named r.party, then in our OO-enhanced MVBASIC we might write
partyid = r.party->%Id()
This is related to SQL. We are not using this and it might be specific to COS (Cache’ ObjectScript), I dunno. Maybe someday we will need it. The documentation says “%ROWID is set to the RowID of the last row modified by the most recent INSERT, UPDATE, or DELETE operation” which might prompt us to ask for the definition of RowId, but I’m thinking by now you might be exhausted.
I am exhausted and have perhaps exhausted this topic, although we haven’t even gotten to %XML.Id. That is fine, however, because, PTL, it is NOT another name for our @ID.