Using the MultiValue Features of Caché
Using a Caché Class and MultiValue: A Sample Session
[Back] [Next]
Go to:

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:
  1. At the MV shell prompt, importing the class definition.
  2. Using MVBasic to perform basic object manipulation: instantiation, setting some properties, and saving an instance.
  3. Examining the data in the MV shell with a simple MV query.
  4. Using the Caché data population utility to instantiate a larger number of objects.
  5. In the Management Portal, running SQL queries against the data.
  6. 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 Caché 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:

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")
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:
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:
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:
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
25019         Ott,Barbara T.               460-920-4165
25020         Vonnegut,Maria Y.            874-843-5492
25021         Sands,Roger J.               781-540-8221
25022         Wakefield,Phil U.            635-827-9697
25023         Ortiz,Mario O.               229-472-7806
25024         Finn,Bob Z.                  214-929-6674
25025         Jones,Chris K.               874-204-8174
25026         Yeats,Phil H.                345-959-9979
25027         Goldman,Phil O.              423-344-9508
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:
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:
                                             02:23:27pm  26 Jul 2006  PAGE    1
ID........    Name.....................    Phone.......
26040         Yeats,Quigley S.             201-507-5264
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
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:
 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:
  1. 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.
  2. On the Portal's main page, choose SQL from the middle column (Data Management). This displays the Portal's SQL page.
  3. Choose the USER namespace from the Namespace list on the left.
  4. Choose Execute SQL Statement from the left column (SQL Operations). This displays the Execute SQL Query page.
  5. 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:
  1. 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.
  2. 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>
    such as
  3. 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.
  4. Open the MVDEMO.PERSON class. To do this:
    Any of these actions displays the Open dialog for the USER namespace.
  5. In the Open dialog, look only for class definitions by specifying Class Definition (*.cls) in the Files of type field.
  6. 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 Caché Studio.