The Caché Python binding provides a simple, direct way to manipulate Caché objects from within a Python application. It allows Python 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 Python 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 Python applications are located on separate machines.
This document assumes a prior understanding of Python and the standard Python modules. Caché does not include a Python interpreter or development environment.
The Caché Python binding gives Python applications a way to interoperate with objects contained within a Caché server. The Python binding consists of the following components:
The Caché Object Server
a high performance server process that manages communication between Python 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 Python, Perl, 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 Python 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).
A Python application. At runtime, the Python application connects to Caché using either an object connection interface or a standard ODBC interface. All communications between the Python application and the Caché server use the TCP/IP protocol.
Here are examples of a few basic functions that make up the core of the Python binding:
conn = intersys.pythonbind.connection()
database = intersys.pythonbind.database(conn)
is your logical connection to the namespace specified in url
person = database.openid("Sample.Person",str(id),-1,-1)
person = database.create_new("Sample.Person", None)
person.set("Name","Doe, Joe A")
name = person.get("Name")
answer = person.run_obj_method("Addition",[17,20])
id = person.run_obj_method("%Id",)
sqlstring ="SELECT ID, Name, DOB, SSN \
FROM SAMPLE.PERSON \
WHERE Name %STARTSWITH ?"
query = intersys.pythonbind.query(database)
cols = query.fetch([None])
if len(cols) == 0: break
Caché provides client-side Python support through the intersys.pythonbind
module, which implements the connection and caching mechanisms required to communicate with a Caché server.
This module requires the following environment:
Python version 2.7 or Python 3.0+. For Windows, Intersystems supports only the ActiveState distribution, ActivePython© (www.activestate.com
A C++ compiler to generate the Python C extension. On Windows, you need Visual Studio .NET 2008 or higher (required by the ActiveState distribution). On UNIX®, you need GCC.
The bitness of both your Python distribution and your compiler must match the bitness of Caché: 64-bit systems require the 64-bit versions of Python and compiler, and 32-bit systems require the 32-bit versions of Python and compiler.
On RedHat Linux, the python-devel
package must be installed in order to compile the python sample.
Set up your environment variables to support C compilation and linking, as described in the following sections.
Make sure your path and environment is setup to run the Microsoft C/C++ compiler. Follow the Microsoft instructions. For example from the command line, run:
for 32-bit systems, or:
for 64-bit systems. These files set up the path and environment variables for using the Microsoft C/C++ compiler. Please read your Microsoft documentation to determine the location of these .bat
files, since the location varies depending on the version of Visual Studio you are using.
python setup.py install
The following prompt is displayed:
enter directory where you installed Cache'
At the prompt, supply the location of <cachesys>
. For example:
The resulting lib and include paths will be displayed:
Do not run test programs from <cachesys>\dev\python
or the test program will not be able to find the pythonbind module. The python path is relative and you will pick up files from the intersys subdirectory instead.
Caché Server Configuration
Very little configuration is required to use a Python client with a Caché server. The Python 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 Python and how to change them.
Every Python client that wishes to connect to a Caché server needs the following information:
By default, the Python sample programs use the following connection information:
Check the following points if you have any problems:
The standard Caché installation contains a set of sample programs that demonstrate the use of the Caché Python binding. These samples are located in:
The following sample programs are provided:
All of these applications use classes from the Sample
package in the SAMPLES
namespace (accessible in Atelier).
The sample programs are controlled by various switches that can be entered as arguments to the program on the command line. A default value is supplied if you don't enter an argument.
For example, CPTest2.py
accepts the following optional arguments:
argument would be specified as follows:
python CPTest2.py -user _MYUSERNAME
python CPTest7.py -query A
This query will list all Sample.Person
records containing names that start with the letter A.