128
Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

Embed Size (px)

Citation preview

Page 1: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

Working with CachéExercises

Introduction to Caché Object Script

and Caché Objects

Page 2: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

2

Overview

Using Caché Using Caché Studio Methods. ObjectScript commands. Namespaces. Databases. Packages. Unit testing. Persistent classes. Properties. Objects.

Tables. Using Mangement Portal Classes, Routines,

Globals. SQL. Data population. Class documentation.

Page 3: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

3

Exercises Overview

1. Create a class and a method, run the method.

2. Run unit tests for a class.

3. Create Simple.Human class.

4. Create, save, and retrieve objects.

5. View Simple.Human data in a table.

6. View the list of classes in the Simple package.

7. View the list of running processes.

8. Populate Simple.Human class with objects for testing.

9. View Simple.Human class documentation.

10. Export classes in Simple package.

Page 4: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

4

Caché Cube

Cube icon appears in Windows system tray.

Click cube for menu. Start and Stop Caché on

local system only. Studio, Terminal, System

Management Portal, and Documentation run on Preferred Server.

Page 5: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

5

Interactive Tools

Studio. Integrated development environment (IDE).

Terminal. Command line interface.

System Management Portal. Browser-based tools for system managers, operators,

and developers. Remote System Access.

Allows one system to run GUI components on remote servers.

Page 6: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

6

Documentation

Caché documentation stored in Caché database. Stored/retrieved as XML.

Fully searchable, by document element. Displayed as web pages. On Cube: Right click → Documentation

Page 7: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

7

Object Components

Caché Language Bindings Supports connecting to Caché from client applications

in .net, Java, C++, Delphi, Perl, and Python. Caché ActiveX Gateway

Supports usage of ActiveX components from within Caché.

Page 8: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

8

SQL Components

Caché SQL Server Allows connection from any ODBC/JDBC-compliant

application or development tool. Caché SQL Gateway

Provides connection to external ODBC-compliant databases.

Provides relational and object access to data.

Page 9: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

9

Web Components

Caché Server Pages Connect to Caché database via web server using

dynamic web pages. Web Services

Interacts as client or server with other SOAP-based applications.

Page 10: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

10

Documentation Options

http://www.intersystems.com/cache/downloads/documentation.html

Page 11: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

11

Working with Caché Studio

Integrated development environment (IDE). Develop database applications with Studio Studio supports two programming languages:

Caché Object Script and Object Basic

Page 12: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

12

Creating New Documents

New button displays dialog of document types. Click and hold New button to switch it to a

particular document type: ObjectScript routine. Basic routine. CSP page. Class definition.

Page 13: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

13

Interface Components

Windows. Workspace. Code. Inspector. Output. Watch. Class Browser.

Bookmarks. All windows may anchor in

place or float. Code and Class Browser

anchor only.

Page 14: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

14

Project

You can open/edit/save/compile each document individually.

Or, create a project: a named list of items with which you’re working. Some may be read-only.

You can open/edit/save/build all items in a project collectively.

Page 15: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

15

Project Settings

Description. Web Server for testing CSP pages. Debugging Target. Breakpoints.

Page 16: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

16

Workspace Window

Project tab. Windows tab.

View currently open windows.

Some may not belong to project (yet).

Namespace tab. Browse entire namespace. Studio displays packages

and sub-packages as folders.

Page 17: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

17

XML

File format for exporting/importing: an entire project. one or more of its components (classes, routines, CSP

pages). XML version of a component is used by source

code control systems.

Page 18: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

18

Code Window

Edit class definition directly. Edit code directly.

ObjectScript, Basic, HTML, CSP, JavaScript, CSS, XML. Use <Ctrl><Tab> to cycle through open windows.

Page 19: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

19

Syntax Errors

Syntax errors in any document are marked in red.

Page 20: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

20

Goto

Right-click a method or routine and click Goto "Method" or Goto "Routine" to jump to the method in its class or the routine.

Page 21: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

21

Inspector

View/edit attributes of all members of class definition.

Changes in Class Inspector automatically update Code Window.

Changes in Code Window update Class Inspector once clicked.

Also displays basic information for routines.

Page 22: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

22

Saving

Save documents from time to time. Or use Tools Options Misc. tab Auto Save.

Saving a document doesn’t automatically compile it. Exception: Tools Options Misc. tab

Compile .INT/.MAC on Save compiles routines when saved.

Page 23: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

23

Compiling and Building

Compile: A single document (class, routine, CSP Page).

Compiling also saves document. A package of classes.

Build a project. Saves and compiles all documents in project.

Compiling reports any errors in document(s) it’s compiling.

Page 24: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

24

Compiling Routines

MAC Compilation produces INT routine and OBJ routine. Normally edit MAC version. Optionally edit INT version during a debugging session.

Debugging changes made to INT overwritten when MAC is re-compiled.

BAS and INT Compilation produces OBJ routine.

Page 25: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

25

Deleting Routines

Deleting a routine within Studio deletes MAC, INT, and OBJ code.

Use Portal to selectively delete.

Page 26: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

26

Automatic Backups

Studio automatically keeps backup versions (last 5) of routines.

Use File Open dialog to load. Format: filename.ext;version#

Examples: Specific file: test.mac;3 All test files: test.*;* All test.mac files: test.mac;*

To purge backups: do ^%RPURGE

Page 27: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

27

Output Window

Result Tab: displays compilation messages and error messages.

For routines, double-click line containing error to jump cursor to line. Find in Files tab: displays results of text searches.

Double-click line containing text to jump cursor to line.

Page 28: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

28

Watch Window

Active while using Studio Debugger, displays values of variables and expressions.

Red indicates changed value. You can change values of variables while stepping through

code. Refer to Debugging modules for details.

Page 29: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

29

Class Browser

Review contents of any class in namespace. Optionally include %* packages.

Access class documentation. Open class in Code Window. Add class to project.

Page 30: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

30

Bookmarks

Mark one or more lines in a Studio document for easy traversal of document. <Ctrl><F2>: Toggle Bookmark <F2>: Next Bookmark <Shift><F2>: Previous Bookmark

Bookmark results of a text search.

Page 31: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

31

Studio Preferences

Use Tools Options to specify preferences for: Fonts and Colors. Syntax Checking, Indentation, Bracket Matching. Compilation. …and others.

Now use Studio for programming applications

Page 32: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

32

Methods

Where is program code defined in an object oriented application?

In methods of a class. A method is code that performs a specific task. Create classes using Studio. Write method code using ObjectScript or Basic.

ObjectScript is default. Examples and exercises use ObjectScript.

Page 33: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

33

Running Methods of a Class

Syntax:do ##class(package.class).method(arguments)

set variable = ##class(package.class).method(arguments)

Use Terminal to run methods if you haven't developed a front end yet.

Page 34: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

34

Exercise 1

Create the Hello() method of the Simple.Demo class.

Run the method.

Page 35: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

35

ObjectScript Commands

ObjectScript command syntax is:command argument1, argument2, …,argumentN

Follow each command with one space. Multiple commands on a line are allowed.

Precede each command with at least one space. Each line of code in a method must begin with at

least one space/tab before first command. Characters before first space/tab interpreted as line

label.

Page 36: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

36

First Commands To Learn

Write Set Do Quit Halt Kill If {} ElseIf {} Else {} For {}

Page 37: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

37

Write

Display information.write !, "3 + 4 = ", (3 + 4)

Evaluate expressions and display result. Without argument, display current list of variables

in memory. Used when debugging.

Quotes (") around strings. Not required for numeric strings.

Line feed (!), tab (?), clear screen (#).

Page 38: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

38

Set

Assign value to variable.set x = (3 + 4) * (5 / 6)

Evaluate expression and assign result to variable. Note: variable names are case sensitive. Arithmetic operators:

+, -, *, /, \, #, ** No precedence! Order of evaluation is left-to-right. Use

parentheses. Concatenation operator: _

Page 39: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

39

Do

Execute routines, procedures, and methods.do ##class(Simple.Demo).Hello("Peter")

do ^%CD

Note: routine/procedure names are case sensitive. Use caret (^) before routine name.

Page 40: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

40

Quit

Terminate method, and return to calling method.quit (name _ " is your friend.")

With argument, return it as result to calling method.

Page 41: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

41

Halt

Stop ObjectScript process. Close Caché Terminal.

Page 42: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

42

Kill

Destroy variable. kill x

Without argument, destroy all variables. Use mostly when testing or debugging.

Page 43: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

43

If {} ElseIf {} Else {}

Evaluate condition(s) and branch.if condition {code }

elseif condition {code }

else {code }

ElseIf and Else are both optional, and there may be more than one ElseIf.

Example:if (weather="cloudy") {write !, "wear a jacket" }

else {write !, "wear sunglasses" }

Page 44: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

44

Conditional Operators

Use parentheses around conditions. Relational operators:

=, >, <, >=, <= Logical operators:

And (&&). Or (||).

Negation operator: Not (') Use either outside condition in parentheses, or next to

relational operator.

Page 45: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

45

For {}

Execute code repeatedly.for variable=start:increment:end {code }

for variable=item1,item2,item3 {code }

Options: Increasing or decreasing sequence that ends.

for count=1:1:4 {write !, "welcome to class!" }

List of values. Increasing or decreasing sequence without end. Without any argument, repeat forever.

Follow with 2 spaces.

Quit within code block terminates loop.

Page 46: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

46

Namespace and Database

A namespace references a database. A database contains:

Class definitions. Code. Data.

Page 47: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

47

What is a Package?

A package is a folder that organizes class definitions, within a namespace/database.

Full name of a class is Package.Class.

Page 48: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

48

Creating and Deleting Packages

Create a package by naming it when you create its first class. Case-sensitive letters or numbers. First character must

be a letter. Package names may contain periods which creates sub-

packages. Class names may not contain periods.

Delete a package by deleting last class it contains.

Page 49: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

49

Display of Packages

Use Studio or Portal Portal displays class definitions as Package.Sub-

package.Class.

Page 50: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

50

%* Packages

%* Packages contain InterSystems-supplied classes. %* packages are automatically usable from any

namespace. For example, %Library package contains classes

used as “building blocks” for your classes. You can add classes from %* Packages to your

project. Read-only.

Page 51: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

51

%Library and User Packages

Optionally, refer to classes in %Library or User package using a shorthand: %Persistent = %Library.Persistent Person = User.Person

Page 52: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

52

Unit Testing

Unit testing, one of the 12 practices of Extreme Programming, is a formalized way to test a module of code, and prove that it works. Module could be a class, or a method only.

Unit tests are a sort of specification of the behaviour of your classes.

Page 53: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

53

Unit Testing (cont.)

Exercises use test driven development model. You will: Use pre-written unit testing methods for each module

you’re about to create. You’ll write your own unit tests later.

Run tests before creating module, and see them fail. Create module, and re-run tests, fixing problems in

module until all tests pass.

Page 54: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

54

Unit Testing Benefits

Proving a module works. Proving you’ve correctly followed instructions.

Regression testing when modules change. Focusing your mind on goal/usage of a module

before developing it. Each step of a test is: Run some lines of code that use module. Assert what you think result should be.

Page 55: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

55

Unit Testing Benefits (cont.)

Creating a server-side client for an application. Capturing module test code in methods instead of

just entering it—and losing it—at the Terminal prompt.

Page 56: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

56

Unit Testing Framework

Caché provides a Unit Testing framework, similar to other xUnit frameworks. %UnitTest.TestCase class for defining test cases. %UnitTest.Manager class for running test cases. Web page for viewing test results.

Page 57: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

57

Exercise 2

Run unit tests for the Simple package. Add a RunTests method to the Simple.Human

class Run the RunTests method in Terminal View the results

Page 58: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

58

Persistent ObjectProperties and Methods

Syntax:set object.property = value

write object.property

do object.method(arguments)

set variable = object.method(arguments)

Page 59: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

59

Methods for Persistent Classes

Method Purpose Success Failure

%New() Create new object in memory

object ""

%Save() Save object 1 error status

%Id() Return object ID object ID ""

%OpenId(id) Retrieve saved object and place in memory

object ""

Page 60: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

60

Persistent Methods (cont.)

Method Purpose Success Failure

%DeleteId(id) Delete saved object

1 error status

%DeleteExtent() Delete all saved (and related) objects

1 error status

%KillExtent()(during development

only)

Delete all saved objects

1 ""

%ClassName(1) Display object’s class name

name of class

Page 61: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

61

Persistent Methods (cont.)

Method Purpose Success Failure

%ValidateObject() Called by %Save() to validate object

1 error status

Page 62: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

62

Failure Status

If an error occurs when calling a method, it returns a status. Capture status in a variable:

set status = human.%Save()

Status automatically captured in %objlasterror variable:do human.%Save()

Variable not very human-readable:USER>write status

0WCE.Branch::Phone([email protected],ID=)%%ValidateObject+7^FCE.Branch.1:USERa

Page 63: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

63

Failure Status (cont.)

To display status in human-readable form, use:do $system.OBJ.DisplayError() // uses %objlasterror

do $system.OBJ.DisplayError(status) // uses status

Example:USER>do $system.OBJ.DisplayError(status)

ERROR #5659: Property 'FCE.Branch::Phone([email protected],ID=)' required

Page 64: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

64

Exercise 3

Description: Create the Simple.Human class. Run methods of a persistent class, to create and

save an object. Retrieve a saved object.

Page 65: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

65

Objects in Memory

%New()and %OpenId() methods place an object in memory.

No method needed for removing an object from memory. Use:USER>set human = ""

To remove all objects from memory:USER>kill

Page 66: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

66

Objects

A persistent class contains its objects along with their data. The extent of a class is the collection of all its objects.

Simple.Human class

1. Peter Parker

3. Harry Osborn

2. Mary Jane Watson

Page 67: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

67

Tables

Persistent objects are rows in relational tables. Object id number is ID column. Package name is schema name.

User package is SQLUser schema.

Simple.Human table: Contains extent of Simple.Human class.

ID Name Phone State

1 Peter Parker 212-323-4545 NY

2 Mary Jane Watson 212-454-2323 NY

3 Harry Osborn 789-234-5611 CA

Page 68: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

68

Exercise 4

Description: View the Simple.Human table.

Page 69: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

69

System Management Portal

System Management Portal replaces Explorer, Configuration Manager, Control Panel, and SQL Manager from v5.0.

Caché must be running to use Portal. Open several Portals to avoid jumping from

function to function.

System Management Portal

Page 70: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

70

Portal Layout

Portal organized in three sections, based on roles. System Administration.

Restricted to certain role(s). Data Management

Accessible by most roles. Operations.

Restricted to certain role(s).

Eight major groupings of tasks. Use Go To to jump directly to common tasks.

System Management Portal

Page 71: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

71

Architectural Configuration

Settings for architecture of system. In System Administration section, click

Configuration. System Configuration section. Examples:

Namespaces and databases. Memory allocation. Startup (port selection).

Page 72: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

72

Operations Configuration

Settings that govern operations. In System Administration section, click

Configuration. System Configuration section. Examples:

Backups. Journals. Task Manager.

Page 73: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

73

Connectivity

Settings for connections between systems. In System Administration section, click

Configuration. Connectivity section. Examples:

Enterprise Cache Protocol (ECP). Shadow Server.

Page 74: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

74

Security

Settings for security and database encryption. In System Administration section, click Security

Management. Security Definitions section. Examples:

Users and Roles. Resources and Services.

In System Administration section, click Database Encryption.

Encryption Key Management section.

Page 75: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

75

Operations

Operational tasks. Operations section. Examples:

Running backups. Reviewing running processes. Reviewing System Dashboard (v5.1).

Page 76: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

76

Exercise 5

Description: View the list of running processes.Instructions: Using the Portal, in the Operations section, click

Processes. Find your process(es) by looking for student in the

User column. Click on the User column to sort the list by this

value. Enter student in the Filter field to filter list.

Page 77: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

77

Classes, Routines, Globals

Application component management tasks. In Data Management section, click Routines,

Globals, or Classes. Examples:

Searching routines, globals, or classes. Use combination of search mask and filter to produce list.

Compiling classes.

Page 78: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

78

Exercise 6

Description: View the list of classes in the Simple package.

Instructions: Using the Portal, use the Go to dropdown list and

click View Classes. If you don’t see the Simple classes, make sure

you’re in the USER namespace.

Page 79: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

79

SQL

SQL management tasks. In Data Management section, click SQL. Execute SQL Statement provides access to an

interactive Query Builder. Examples:

Reviewing table schema. Viewing table data. Importing data.

Page 80: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

80

Data Population

Provides methods to generate multiple objects for a class.

Methods generate test data for each object’s properties. Many are automatic based on property name or

datatype. Customizable

Page 81: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

81

Exercise 7

Description: Use data population method to add data to the Simple.Human class/table.

Instructions: Using Terminal, enter this line of code to add 10

new humans.do ##class(Simple.Human).Populate(10)

Use the Portal to see the new data.

Page 82: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

82

Class Documentation

Caché generates Class Documentation for any saved class.

To view from Studio: Right-click class name in Workspace window (Project or

Windows tab), and click Show Class Documentation. While editing a class, click View Show Class

Documentation. From Caché Documentation home page, click

Class Reference Information. Requires authentication.

Page 83: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

83

Writing Class Documentation

Class documentation that you write can contain links to other parts of the class documentation. Syntax: <class>ClassName</class> <property>PropertyName</property> <method>MethodName</method>

Review the %CSP.Documatic class definition for a full list.

Page 84: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

84

Exercise 8

Description: View class documentation.

Instructions: Right-click a class in Workspace window and click

Show Class Documentation. Find other classes from list on left and view their

documentation. Note links to other class documentation.

Page 85: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

85

Exercise 9

Description: Run unit tests for the Simple package.

Instructions: Using Terminal, run the method:

USER>do ##class(Simple.Demo).RunTests()

View test results. All tests pass. Testing of the suite passes.

Review the test results using a browser, as in Exercise 2.

Page 86: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

86

Errors When Using Terminal

Terminal displays error messages.USER>do ##class(Simple.Demo).Runtests()

<METHOD DOES NOT EXIST> *Runtests,Simple.Demo

Following *, more information about error appears. Refer to Caché Development References Caché

Error Reference for list of all error messages and meanings.

Page 87: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

87

Terminal Prompt

Sometimes Terminal prompt changes to indicate debugger is active:USER 2d0> Enter Q to change back to standard prompt.

Refer to Caché Development Guides Using Caché ObjectScript Processing Errors in Programmer Mode (section 15.6) for more information about debugger prompt.

Refer to Debugging module for debugging information.

Page 88: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

88

How To:Export Studio Documents

Click Tools Export. Click Export current Project or click Add button to

select documents individually. Enter path and filename in Export to Local File text

box. Click OK.

Page 89: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

89

How To:Import Studio Documents

Click Tools Import Local. Browse and select xml file for import. Review list of documents contained in file.

Optionally, exclude some documents from import. Available options:

Add Imported Items to Project Compile Imported Items

Click OK.

Page 90: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

90

Exercise 10

Description: Export classes in Simple package.

Instructions: Using Studio, click Tools Export. Use Add button to pick the Simple.Demo and

Simple.Human classes. Export the classes to h:\ModernDBTechniques\

simple. Click OK.

Page 91: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

Development Setup

Page 92: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

92

Overview

Development sandbox. Memory setup. Namespaces and databases. Globals and routines. Namespace and database setup. Resource and role setup. User setup. ODBC setup. Remote System Access setup. Developer’s Corner.

Page 93: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

93

Exercises Overview

11. Create development sandbox.

12. Add ODBC access to the DEV namespace.

Page 94: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

94

USER and SAMPLES

Caché provides two general purpose namespaces, for simple testing, development, and learning: USER is empty, and not affected by a Caché upgrade. SAMPLES contains sample classes, code, and data, and

is completely restored by a Caché upgrade.

Page 95: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

95

Development Sandbox

We recommend creating a “sandbox” for development work, consisting of: Namespace. Database. Resource and Role.

Control access to database.

Create each one individually, or start by creating a new namespace. Prompts to create new database.

Prompts to create new resource, and role with read/write access on resource.

Page 96: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

96

Development Sandbox (cont.)

Creator must be a member of %Manager role. Installer of Caché is a member of %All role, which

encompasses %Manager.

Page 97: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

97

FinancialsClientsVendors

Databases

NamespacesBilling Purchasing

Basic Structure

Data and code are stored in Caché in databases, referred to by namespaces. Database is a physical storage location. Namespace defines logical references to several

databases.

Page 98: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

98

Basic Structure (cont.)

Each namespace has default (primary) database. Several namespaces can refer to same database.

Databases

Namespaces

FinancialsClientsVendors

Billing Purchasing

Page 99: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

99

Namespaces

Each Caché application process runs in one namespace.

Process accesses code and data in databases referenced by that namespace.

FinancialsClients

Databases

Namespaces Billing

Page 100: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

100

Namespace Benefits

Allows code in one database to access code and data in other databases, regardless of physical location.

Allows code and data to be distributed among multiple databases.

FinancialsClients

Databases

NamespacesBilling

Page 101: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

101

How To:Pick Namespace

In Terminal, use: zn "<namespace>" do ^%CD and enter

namespace at prompt. In Studio, click File

Change Namespace.

Page 102: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

102

How To:Pick Namespace (cont.)

In Portal, click namespace on left.

Page 103: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

103

Databases

Each Caché database represents CACHE.DAT file in OS file system.

Database contains routines (code) and globals (data).

Data and code may be spread among multiple databases.

Block Format Maximum Size Support

2 KB 16 GB Upgrade-only as of v5.1

8 KB 32 TB v4.1+

Page 104: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

104

Globals

Globals are persistent multi-dimensional arrays. Global names start with ^.

^abc(1,2,3) is a global. Store all data types including character and binary

streams. Term global indicates that potentially all users on

system can access data. %* globals are readable from any namespace.

Page 105: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

105

Multi-Dimensional

Multiple dimensions allow globals to contain hierarchical data.

Globals efficiently store hierarchichal data as sparse multi-dimensional arrays

For example, invoices containing transactions. One global contains invoice data at one level, and

transactions for each invoice at another level. “Joins” are implicit and fast.

Page 106: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

107

Routines

Code written by hand or generated. For example, compiling class definition generates routine

code. %* routines are callable from any namespace.

Page 107: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

108

ObjectScript.

Caché Basic.

.MACmacro

.INCinclude

.INTintermediate

.OBJobject

.BASbasic

.OBJobject

Routine Extensions

Page 108: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

109

Routine Extensions (cont.)

INC (like .h files in C). Macro definitions to be included in MAC routines.

MAC. ObjectScript code with references to INC routines. Embedded SQL and/or Embedded HTML.

BAS and INT. Caché Basic or ObjectScript code only.

OBJ (like .exe files in C). Executable code (interpreted).

Page 109: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

110

Routines in Globals

Caché stores source code of routines in globals. Routines are data too. Cannot view OBJ routine source.

Global Name Routines

^rINC INC

^rMAC MAC

^ROUTINE BAS and INT

^rOBJ OBJ

Page 110: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

111

Installation Databases

System databases: CACHESYS (System manager database). CACHELIB (System-wide utilities). CACHEAUDIT (Event logging). CACHETEMP (Temporary storage). DOCBOOK (Documentation).

Testing/learning databases: SAMPLES (Samples). USER (Empty).

Page 111: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

112

CACHETEMP

Namespace Default Mappings

By default, each namespace maps to: CACHESYS. CACHELIB. CACHETEMP.

CACHELIBCACHESYS CLIENTS

System routinesand globals.

User-created routinesand globals.

Billing

Page 112: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

113

Naming Conventions

Database and Namespace names. Capital letters or numbers.

First character must be letter. May contain _ and - characters.

Routine and global names. Case-sensitive letters or numbers.

First character must be letter. May contain periods.

Page 113: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

114

Memory Setup

v5.1 automatically allocates a large amount of memory to global and routine caches.

In some cases, reducing allocation is recommended.

Page 114: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

115

How To: Reduce Size of Global and Routine Caches

Using Portal, click Configuration Memory and Startup.

Specify sizes: Memory Allocated for Routine Cache Memory Allocated for 8 KB Database Cache

Click Save. Restart Caché (required).

Page 115: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

116

How To:Create a Namespace

Using Portal, click Configuration Namespaces Create New Namespace.

Specify name. Choose an existing database, or click Create a

New Database. To allow CSP applications access to namespace,

click Create a default CSP application…. Click Save.

Page 116: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

117

How To:Create a Database

Using Portal, click Configuration Local Databases Create New Database. Or, start Wizard when creating namespace.

Specify name and physical path. Click Next. Specify initial size and journal settings. Click Next.

Page 117: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

118

How To:Create a Database (cont.)

Assign resource, by clicking one of: %DB_%DEFAULT: catch-all for databases without

database-specific resource. Use an existing resource (pick from list). Create a new resource.

Click Next to confirm choices. Click Finish.

Page 118: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

119

How To: Create a Database Resource

Using Portal, click Security Management Resources Create New Resource. Or, start Wizard when creating database.

Specify name (%DB_Database) and description. Don’t click This is a public resource, in order to

restrict access using associated %DB_Database role. Or, allow it to be a public resource, and assign Read or

Write permissions.

Page 119: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

120

How To:Create a Database Resource (cont.)

Click Save. Resource and role created. Click Security Management Roles. Verify %DB_Database role has Read/Write

privileges on %DB_Database resource.

Page 120: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

121

How To: Switch a User to a New Default Namespace

Using Portal, click Security Management Users. Find the user, and click Edit. Change Default Namespace to the desired

namespace.

Page 121: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

122

How To: Open Access to Class Documentation

Using Portal, click Security Management CSP Applications.

Find the /csp/documatic application, and click Edit. Remove %Development from Resource required to

run the application. Click Save.

Page 122: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

123

Exercise 11

Description: Create development sandbox.

Instructions: Reduce memory allocation to 20 MB for global and

routine caches. Don’t restart Caché yet. Create DEV namespace. Create DEV database. Create %DB_DEV resource. Switch student user’s default namespace to DEV. Open access to Class Documentation. Restart Caché.

Page 123: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

124

How To: Add ODBC Access to a Namespace

Click Windows Start Settings Control Panel. Click Administrative Tools Data Sources

(ODBC). Click the System DSN tab. Note DSNs for USER

and SAMPLES. Click Add, and double-click InterSystems ODBC.

Page 124: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

125

How To: Add ODBC Access to a Namespace (cont.)

Specify Name (containing the namespace name). This is the Data Source Name (DSN) providing access to

this namespace. Specify Namespace. To constrain users of this DSN to a particular user:

Specify User Name and Password. Click Test Connection to test.

To allow users to authenticate when accessing, leave User Name and Password blank.

Click OK.

Page 125: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

126

Exercise 12

Description: Add ODBC access to the DEV namespace.

Instructions: Create an ODBC DSN to the DEV namespace.

Specify: User Name: YourAccount. Password: YourPassword.

Test the connection. Optionally, remove User Name and Password. Click OK to save DSN.

Page 126: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

127

How To:Define Preferred Server

Click Add/Edit to define list of remote servers. Specify:

Name. IP Address. Caché SuperServer port.

Designate one as Preferred Server.

Page 127: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

128

How To:Use Remote System Access

Click a component. Click name of remote

server on which to run component.

Page 128: Working with Caché Exercises Introduction to Caché Object Script and Caché Objects

129

Developer’s Corner

http://www.intersystems.com/cache/devcorner/index.html

Latest information for developers. Samples and documentation.