The Caché Perl Binding
The Caché Perl binding provides a simple, direct way to manipulate Caché objects from within a Perl application. It allows Perl programs to establish a connection to a database on Caché, create and open objects in the database, manipulate object properties, save objects, run methods on objects, and run queries. All Caché datatypes are supported.
The Perl binding offers complete support for object database persistence, including concurrency and transaction control. In addition, there is a sophisticated data caching scheme to minimize network traffic when the Caché server and the Perl applications are located on separate machines.
This document assumes a prior understanding of Perl and the standard Perl modules. Caché does not include a Perl interpreter or development environment.
Perl Binding Architecture
The Caché Perl binding gives Perl applications a way to interoperate with objects contained within a Caché server. The Perl binding consists of the following components:
-
The Intersys::PERLBIND module — a Perl C extension that provides your Perl application with transparent connectivity to the objects stored in the Caché database.
-
The Caché Object Server — a high-performance server process that manages communication between Perl clients and a Caché database server. It communicates using standard networking protocols (TCP/IP), and can run on any platform supported by Caché. The Caché Object Server is used by all Caché language bindings, including Perl, Python, C++, Java, JDBC, and ODBC.
The basic mechanism works as follows:
-
You define one or more classes within Caché. These classes can represent persistent objects stored within the Caché database or transient objects that run within a Caché server.
-
At runtime, your Perl application connects to a Caché server. It can then access instances of objects within the Caché server. Caché automatically manages all communications as well as client-side data caching. The runtime architecture consists of the following:
-
A Caché database server (or servers).
-
The Perl interpreter (see Perl Client Requirements).
-
A Perl application. At runtime, the Perl application connects to Caché using either an object connection interface or a standard ODBC interface. All communications between the Perl application and the Caché server use the TCP/IP protocol.
-
Quick Start
Here are examples of a few basic functions that make up the core of the Perl binding:
-
Create a connection and get a database
$url = "localhost[1972]:Samples" $conn = Intersys::PERLBIND::Connection->new($url,"_SYSTEM","SYS",0); $database = Intersys::PERLBIND::Database->new($conn);
$database is your logical connection to the namespace specified in $url.
-
Open an existing object
$person = $database->openid("Sample.Person","1", -1, -1);
$person is your logical connection to a Sample.Person object on the Caché server.
-
Create a new object
$person = $database->create_new("Sample.Person",undef);
-
Set or get a property
$person->set("Name","Adler, Mortimer"); $name = $person->get("Name");
-
Run a method
$answer = $person->Addition(17,20);
-
Save an object
$person->run_obj_method("%Save")
-
Get the id of a saved object
$id = $person->run_obj_method("%Id")
-
Run a query
$query = $database->alloc_query(); $query->prepare("SELECT * FROM SAMPLE.PERSON WHERE ID=?",$sqlcode); $query->set_par(1,2); $query->execute($sqlcode); while (@data_row = $query->fetch($sqlcode)) { $colnum = 1; foreach $col (@data_row) { $col_name = $query->col_name($colnum); print "column name = $col_name, data=$col\n"; $colnum++; } }
Installation and Configuration
The standard Caché installation places all files required for Caché Perl binding in <cachesys>/dev/perl. (For the location of <cachesys> on your system, see Default Caché Installation Directory in the Caché Installation Guide). You should be able to run any of the Perl sample programs after performing the following installation procedures.
Perl Client Requirements
Caché provides client-side Perl support through the Intersys::PERLBIND module, which implements the connection and caching mechanisms required to communicate with a Caché server.
This module requires the following environment:
-
Perl version 5.10 — InterSystems supports only the ActiveState distribution (www.activestate.comOpens in a new tab).
-
A C++ compiler — On Windows, use Visual Studio 2008 or later. On UNIX®, use GCC.
-
Your PATH must include the <cachesys>\bin directory. (For the location of <cachesys> on your system, see Default Caché Installation Directory in the Caché Installation Guide).
-
Your environment variables must be set to support C compilation and linking (for example, on Windows call VSVARS32.BAT). Otherwise, linker errors will be reported on the make step.
UNIX® Installation
-
Make sure <cachesys>/bin is on your PATH and in your LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH on OSX). For the location of <cachesys> on your system, see Default Caché Installation Directory in the Caché Installation Guide.
For example:
export PATH=/usr/cachesys/bin:$PATH export LD_LIBRARY_PATH=/usr/cachesys/bin:$LD_LIBRARY_PATH
-
Run Makefile.PL (located in <cachesys>/dev/perl). You can supply the location of <cachesys>as an argument. For example:
perl Makefile.PL /usr/cachesys
If you run it without an argument, it will prompt you for the location of <cachesys>.
-
After making sure that <cachesys>/bin is on your path, run:
make
-
If make runs with no errors, test it with:
make test
-
If make test is successful, run:
make install
Windows Installation
-
Make sure <cachesys>\bin is on your PATH. (For the location of <cachesys> on your system, see Default Caché Installation Directory in the Caché Installation Guide).
-
Run Makefile.PL (located in <cachesys>\dev\perl). You can supply the location of <cachesys> as an argument. For example:
perl Makefile.PL C:\InterSystems\Cache
If you run it without an argument, it will prompt you for the location of <cachesys>.
-
After making sure that <cachesys>\bin is on your path, run:
nmake
-
If nmake runs with no errors, test it with:
nmake test
-
If nmake test is successful, run:
nmake install
Caché Server Configuration
Very little configuration is required to use a Perl client with a Caché server. The Perl sample programs provided with Caché should work with no change following a default Caché installation. This section describes the server settings that are relevant to Perl and how to change them.
Every Perl client that wishes to connect to a Caché server needs the following information:
-
A URL that provides the server IP address, port number, and Caché namespace.
-
A username and password.
By default, the Perl sample programs use the following connection information:
-
connection string: "localhost[1972]:Samples"
-
username: "_SYSTEM"
-
password: "SYS"
Check the following points if you have any problems:
-
Make sure that the Caché server is installed and running.
-
Make sure that you know the IP address of the machine on which the Caché server is running. The Perl sample programs use "localhost". If you want a sample program to default to a different system you will need to change the connection string in the code.
-
Make sure that you know the TCP/IP port number on which the Caché server is listening. The Perl sample programs use "1972". If you want a sample program to default to a different port, you will need change the number in the sample code.
-
Make sure that you have a valid username and password to use to establish a connection. (You can manage usernames and passwords using the Management Portal). The Perl sample programs use the administrator username "_SYSTEM" and the default password "SYS" or "sys". Typically, you will change the default password after installing the server. If you want a sample program to default to a different username and password, you will need to change the sample code.
-
Make sure that your connection URL includes a valid Caché namespace. This should be the namespace containing the classes and data your program uses. The Perl samples connect to the SAMPLES namespace, which is pre-installed with Caché.
Sample Programs
Caché comes with a set of sample programs that demonstrate the use of the Caché Perl binding. These samples are located in the <cachesys>/dev/perl/samples/ subdirectory of the Caché installation. (For the location of <cachesys> on your system, see Default Caché Installation Directory in the Caché Installation Guide). They are named, numbered, and implemented to correspond to the Java binding samples.
The sample programs include:
-
CPTest2.pl — Get and set properties of an instance of Sample.PersonOpens in a new tab.
-
CPTest3.pl — Get properties of embedded object Sample.Person.Home.
-
CPTest4.pl — Update embedded object Sample.Person.Home.
-
CPTest5.pl — Process datatype collections.
-
CPTest6.pl — Process the result set of a ByName query.
-
CPTest7.pl — Process the result set of a dynamic SQL query.
-
CPTest8.pl — Process employee subclass and company/employee relationship.
All of these applications use classes from the Sample package in the SAMPLES namespace (accessible in Atelier). If you have not used the Sample package before, you should open it in Atelier and make sure it is properly compiled.
The sample programs are controlled by various switches that can be entered as arguments to the program on the command line. The sample program supplies a default value if you do not enter an argument.
For example, CPTest2.pl accepts the following optional arguments:
-
-user — the username you want to login under (default is "_SYSTEM").
-
-password — the password you want to use (default is "SYS").
-
-host — the host computer to connect to (default is "localhost").
-
-port — the port to use (default is "1972").
A -user argument would be specified as follows:
perl CPTest2.pl -user _MYUSERNAME
The CPTest7.pl sample accepts a -query argument that is passed to an SQL query:
perl CPTest7.pl -query A
This query will list all Sample.Person records containing names that start with the letter A.