Skip to main content

This is documentation for Caché and Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

Please read this important announcement about the future of Caché and Ensemble maintenanceOpens in a new tab. Contact your account team to migrate to InterSystems IRIS.

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:

  1. Starting the MV shell.

  2. At the MV shell prompt, importing the class definition.

  3. Using MVBasic to perform basic object manipulation: instantiation, setting some properties, and saving an instance.

  4. Examining the data in the MV shell with a simple MV query.

  5. Using the Caché data population utility to instantiate a larger number of objects.

  6. Running more complex MV queries against the data.

  7. In the Management Portal, running SQL queries against the data.

  8. 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:

USER>MV

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.OBJOpens in a new tab class in the MV shell:

USER: ; "%SYSTEM.OBJ"->Load(<class definition file>, "c")

where

  • 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).

Note:

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:

  • 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.
Note:

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.PopulateOpens in a new tab class (often known simply as %PopulateOpens in a new tab), 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.PopulateUtilsOpens in a new tab 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:

  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

     Studio-UnknownUser-CacheMVTest/USER-Default_

  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:

    • Select File-Open from the menu.

    • Press Ctrl-O.

    • Click the Open icon from the menu.

    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 Studio.

Available Flavors / EmulationsNext section
Previous sectionStarting MultiValue