Using a Caché Class and MultiValue: A Sample Session
Caché comes with the file MVDEMO.PERSON.xml, which contains the MVDEMO.PERSON class. This section provides a sample session of loading and manipulating this class. Its steps provide examples of the MultiValue features in Caché, and how the native Caché environment interacts with these features.
The steps are:
At the MV shell prompt, importing the class definition.
Using MVBasic to perform basic object manipulation: instantiation, setting some properties, and saving an instance.
Examining the data in the MV shell with a simple MV query.
Using the Caché data population utility to instantiate a larger number of objects.
Running more complex MV queries against the data.
In the Management Portal, running SQL queries against the data.
Using Studio to examine the class definition.
In addition to supporting traditional MVBasic file manipulation (such as with OPEN, WRITE, and so on), Caché allows you to treat data as objects. This sample highlights the use of Caché object features.
Starting the MV Shell
In a Terminal window, make sure you are in the USER namespace; this is indicated by a prompt of USER>. A Caché namespace is similar to a MultiValue account.
To go from another namespace to the USER namespace, use the ZNSPACE (abbreviated ZN) command — in this example, from the SAMPLES namespace:
SAMPLES>ZN "USER" USER>
Then start the MV Shell by issuing the MV command:
More on the MV Shell can be found in the Operational Differences documentation.
Importing the Class Definition
The definition of the MVDEMO.PERSON class is in the file MVDEMO.PERSON.xml. To import the class definition into Caché, use the Load method of the %SYSTEM.OBJ class in the MV shell:
USER: ; "%SYSTEM.OBJ"->Load(<class definition file>, "c")
The leading semicolon (;) in the MV shell specifies that the rest of the line is MVBasic code (not an MV command). The Cache MV shell has been enhanced to allow for lines of MVBasic code to be executed from the MV shell.
The first argument specifies the quoted name of a XML class definition file, including a full path. The location of this file relative to the Caché installation directory is <cache-installation-dir>\Dev\mv\samples/MVDEMO.PERSON.xml (Windows) or <cache-installation-dir>/dev/mv/samples/MVDEMO.PERSON.xml (UNIX®, Linux, MacOs).
The second argument specifies the required compiler flags (“c” means compile).
All examples of invoking commands from the MV shell in this chapter include the MV shell prompt (“USER: ”).
When you run this command, a series of output statements appear in the Terminal indicating that the file has been imported and compiled.
For a standard Windows installation, the following will do the import:
USER: ; demo = "C:\InterSystems\Cache\Dev\mv\samples\MVDEMO.PERSON.xml" USER: ; stat = "%SYSTEM.OBJ"->Load(demo, "c")
When you run this, a series of output statements appear in the Terminal indicating that the file has been imported, compiled, and exported to a MultiValue file.
With the MV shell, you can specify:
MultiValue Basic (MVBasic) commands. Lines containing MVBasic commands begin with a semicolon.
ObjectScript calls. Lines containing ObjectScript begin with a leading “COS” or a leading left bracket (“[”).
Creating, Manipulating, and Saving an Object
Once the compiled class is available, you can invoke its CreateSome method:
USER: ; "MVDEMO.PERSON"->CreateSome()
This command invokes the CreateSome method of the MVDEMO.PERSON class. This method performs the following actions:
Creates an instance of MVDEMO.PERSON
Sets the values for the properties of that instance.
Saves the instance.
Creates ten other instances of the class using the Caché data population utility (described in the following section on populating the class with test data).
Running Some Simple MV Queries against the Class
Since there are now instances of the class, you can use the available Caché tools to run queries against them. Standard MV shell commands are available in the Caché MV shell, so it is easy to run an MV query:
LIST MVDEMO.PERSON Name
As expected, this query displays the value of Name and ID of each instance of the class. For example, output from this command might look like:
LIST MVDEMO.PERSON Name 02:09:27pm 26 Jul 2006 PAGE 1 ID........ Name..................... 25018 Smith,John 25019 Ott,Barbara T. 25020 Vonnegut,Maria Y. 25021 Sands,Roger J. 25022 Wakefield,Phil U. 25023 Ortiz,Mario O. 25024 Finn,Bob Z. 25025 Jones,Chris K. 25026 Yeats,Phil H. 25027 Goldman,Phil O. 25028 Ng,Valery W. 11 Items listed.
Because the populate utility generates data randomly, the results of this command will differ from what appears here.
A query can also refer to collection properties, such as this class' Phone property:
LIST MVDEMO.PERSON Name Phone 02:15:04pm 26 Jul 2006 PAGE 1 ID........ Name..................... Phone....... 25018 Smith,John 555-123-1234 555-432-4321 25019 Ott,Barbara T. 460-920-4165 661-911-2114 650-886-1018 25020 Vonnegut,Maria Y. 874-843-5492 294-588-4007 25021 Sands,Roger J. 781-540-8221 897-722-5975 25022 Wakefield,Phil U. 635-827-9697 25023 Ortiz,Mario O. 229-472-7806 989-512-1785 25024 Finn,Bob Z. 214-929-6674 483-685-7455 25025 Jones,Chris K. 874-204-8174 25026 Yeats,Phil H. 345-959-9979 25027 Goldman,Phil O. 423-344-9508 533-923-2919 481-245-8553 25028 Ng,Valery W. 479-793-4879
Populating the Class with Test Data
Because MVDEMO.PERSON is a subclass of the %Library.Populate class (often known simply as %Populate), it has built-in functionality for generating test data. Running the CreateSome method creates ten instances of the class using this functionality.
To create one hundred thousand instances of the class, the command is:
USER: ; PRINT "MVDEMO.PERSON"->Populate(100000)
This code uses a number of special features of the Caché MV shell:
The leading semicolon (;) specifies that the subsequent code is an MVBasic command.
The quoted string specifies the name of the class being invoked.
The arrow syntax “->” allows you to refer to a property or method of a class. (If a property is itself an object, this syntax may appear more than once, for example in syntax such as "MYAPP.EMPLOYEE"->SPOUSE->BIRTHDAY.
Since the Populate method returns the number of instances it populated, the MVBasic PRINT command uses this value as an argument.
Regarding the call itself, the data population utility generates test data for the class properties specified in the %Library.PopulateUtils class. For more information, see the chapter “The Caché Data Population Utility” in the book Using Caché Objects.
Running Other MV Queries
More sophisticated queries are also available. These may be more useful when there are larger amounts of data.
For example, queries can attempt to match parts of strings:
LIST MVDEMO.PERSON Name Phone WITH Name LIKE Yeats,Qui... 02:23:27pm 26 Jul 2006 PAGE 1 ID........ Name..................... Phone....... 26040 Yeats,Quigley S. 201-507-5264 946-663-7004 348-807-3906 41436 Yeats,Quigley A. 859-639-9381 2 Items listed.
They can perform multiple matches, with exact and partial matches:
LIST MVDEMO.PERSON Name WITH Hair = brunette AND Name LIKE Presl... 02:27:20pm 26 Jul 2006 PAGE 1 ID........ Name..................... 25070 Presley,Mary N. 26245 Presley,Michael M. 26307 Presley,Orson Q. 26455 Presley,Amanda R. 28654 Presley,Chad L. 28727 Presley,Thelma Q. 29922 Presley,Clint B. 30459 Presley,Richard B. 30799 Presley,Filomena M. 31313 Presley,Wilma E. ...
They can suppress the display of the ID for each row:
LIST MVDEMO.PERSON Name WITH Hair = brunette AND Name LIKE Presl... ID.SUP 2:28:29pm 26 Jul 2006 PAGE 1 Name..................... Presley,Mary N. Presley,Michael M. Presley,Orson Q. Presley,Amanda R. Presley,Chad L. Presley,Thelma Q. Presley,Clint B. Presley,Richard B. Presley,Filomena M. Presley,Wilma E. ...
And they can perform counts:
USER:COUNT MVDEMO.PERSON WITH Hair = brunette 8391 Items counted.
Using the Management Portal to Run SQL Queries
Because Caché provides full support for SQL, you can invoke SQL queries against your data. The Caché Management Portal provides functionality for running ad hoc queries. To run an SQL query:
From the Caché cube menu, choose Management Portal. If you have performed a minimal-security installation of Caché, this displays the main page for the Management Portal; with Normal or Locked-Down installations, a login screen appears.
On the Portal's main page, choose SQL from the middle column (Data Management). This displays the Portal's SQL page.
Choose the USER namespace from the Namespace list on the left.
Choose Execute SQL Statement from the left column (SQL Operations). This displays the Execute SQL Query page.
On this page, Caché allows you to create and run standard SQL queries against your data. You can either write a query in the available editing area or click the Query Builder button to use the interactive SQL Query Builder.
SQL access is also available via any ODBC or JDBC tool.
Using Studio to Examine the Class Definition
Having previously imported the class definition, you can view and edit it in Studio. Studio is a full-featured development environment. To display the class definition in Studio, the process is:
From the Caché cube menu, choose Studio. A login screen appears. With a minimal-security installation, simply click OK and Studio runs under the UnknownUser account, which has all privileges in this type of installation; with normal and locked-down installations, enter a valid username and password.
You should be in the USER namespace. To determine if this is so, check the string that appears in the Studio window's title bar. This is of the form:
Studio-<logged-in user>-<Caché instance>/<active namespace>-<project>
If you are not in the USER namespace, select File-Change Namespace (or F4). This displays the Caché Connection Manager screen. Choose USER from the list and click OK.
Open the MVDEMO.PERSON class. To do this:
Select File-Open from the menu.
Click the Open icon from the menu.
Any of these actions displays the Open dialog for the USER namespace.
In the Open dialog, look only for class definitions by specifying Class Definition (*.cls) in the Files of type field.
Select MVDEMO from the available choices and the PERSON.cls from the choices that then appear.
For more information on Studio, see the book Using Studio.