Skip to main content
Previous sectionNext section

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);
    Copy code to clipboard

    $database is your logical connection to the namespace specified in $url.

  • Open an existing object

       $person = $database->openid("Sample.Person","1", -1, -1);
    Copy code to clipboard

    $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);
    Copy code to clipboard
  • Set or get a property

       $person->set("Name","Adler, Mortimer");
       $name = $person->get("Name");
    Copy code to clipboard
  • Run a method

       $answer = $person->Addition(17,20);
    Copy code to clipboard
  • Save an object

       $person->run_obj_method("%Save")
    Copy code to clipboard
  • Get the id of a saved object

       $id = $person->run_obj_method("%Id")
    Copy code to clipboard
  • 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++; }
       }
    Copy code to clipboard

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

  • A C++ compiler — On Windows, use Visual Studio 2008 or 2010 (for more information, see Windows Compilers for Perl Modules on the ActiveState site). 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
    Copy code to clipboard
  • 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
    Copy code to clipboard

    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
    Copy code to clipboard
  • If make runs with no errors, test it with:

       make test
    Copy code to clipboard
  • If make test is successful, run:

       make install
    Copy code to clipboard

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
    Copy code to clipboard

    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
    Copy code to clipboard
  • If nmake runs with no errors, test it with:

       nmake test
    Copy code to clipboard
  • If nmake test is successful, run:

       nmake install
    Copy code to clipboard

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

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

Arguments

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
Copy code to clipboard

The CPTest7.pl sample accepts a -query argument that is passed to an SQL query:

   perl CPTest7.pl -query A
Copy code to clipboard

This query will list all Sample.Person records containing names that start with the letter A.