Skip to main content
Previous section   

Python Client Class Reference

This chapter describes how Caché classes and datatypes are mapped to Python code, and provides details on the classes and methods supported by the Caché Python binding. The following subjects are discussed:

  • Datatypes%Binary data.

  • Connections — methods used to create a physical connection to a namespace in a Caché database.

  • Database — methods used to open or create Caché objects, create queries, and run Caché class methods.

  • Objects — methods used to manipulate Caché objects by getting or setting properties, running object methods, and returning information about the objects.

  • Queries — methods used to run queries and fetch the results.

  • Times and Dates — methods used to access the Caché %Time, %Date, or %Timestamp datatypes.

  • Locale and Client Version — methods that provide access to Caché version information and Windows locale settings.

Datatypes

All Caché datatypes are supported. See the following sections for information on specific datatypes:

Connections

Methods of the intersys.pythonbind.connection package create a physical connection to a namespace in a Caché database. A Connection object is used only to create a Database object, which is the logical connection that allows Python binding applications to manipulate Caché objects. See Connecting to the Caché Database for information on how to use the Connection methods.

Here is a complete listing of connection methods:

connect_now()
   conn = intersys.pythonbind.connection()
   conn.connect_now(url,user,password, timeout)
Copy code to clipboard

See Connection Information later in this section for a detailed discussion of the parameters.

secure_connect_now()
   conn = intersys.pythonbind.connection()
   conn.secure_connect_now(url, srv_principal, security_level, timeout)
Copy code to clipboard

Connection.secure_connect_now() returns the connection proxy that is used to get the proxy for the Caché namespace identified by url. This method takes the following parameters:

  • url — See Connection Information later in this section for a detailed description of the URL format.

  • srv_principal — A Kerberos "principal" is an identity that is represented in the Kerberos database, has a permanent secret key that is shared only with the Kerberos KDCs (key distribution centers), can be assigned credentials, and can participate in the Kerberos authentication protocol.

    • A "user principal" is associated with a person, and is used to authenticate to services which can then authorize the use of resources (for example, computer accounts or Caché services).

    • A "service principal" is associated with a service, and is used to authenticate user principals and can optionally authenticate itself to user principals.

    • A "service principal name" (such as srv_principal_name) is the string representation of the name of a service principal, conventionally of the form:

      <service>/<instance>@<REALM>

      For example:

      cache/turbo.iscinternal.com@ISCINTERNAL.COM

    On Windows, The KDCs are embedded in the domain controllers, and service principal names are associated with domain accounts.

    See your system's Kerberos documentation for a detailed discussion of principals.

  • security_level — Sets the "Connection security level", which is an integer that indicates the client/server network security services that are requested or required. Security level can take the following values:

    • 0 — None.

    • 1 — Kerberos client/server mutual authentication, no protection for data.

    • 2 — As 1, plus data source and content integrity protection.

    • 3 — As 2, plus data encryption.

  • timeout — Number of seconds to wait before timing out.

Connection Information

The following information is needed to establish a connection to the Caché database:

  • URL — The URL specifies the server and namespace to be accessed as a string with the following format:

    <address>[<port>]:<namespace>
    Copy code to clipboard

    For example, the sample programs use the following connection string:

    "localhost[1972]:Samples"
    Copy code to clipboard

    The components of this string are:

    • <address> — The server TCP/IP address or Fully Qualified Domain Name (FQDN). The sample programs use "localhost" (127.0.0.1), assuming that both the server and the Python application are on the same machine.

    • <port> — The server TCP/IP port number for this connection. Together, the IP address and the port specify a unique Caché server.

    • <namespace> — The Caché namespace containing the objects to be used. This namespace must have the Caché system classes compiled, and must contain the objects you want to manipulate. The sample programs use objects from the SAMPLE namespace.

  • username — The username under which the connection is being made. The sample programs use "_SYSTEM", the default SQL System Manager username.

  • password — The password associated with the specified username. Sample programs use the default, "SYS".

Database

Database objects provide a logical connection to a Caché namespace. Methods of the intersys.pythonbind.Database package are used to open or create Caché objects, create queries, and run Caché class methods. Database objects are created by calling database = intersys.pythonbind.database(conn), where conn is a intersys.pythonbind.connection object. See Connecting to the Caché Database for more information on creating a Database object.

Here is a complete listing of Database methods:

create_new()
obj = database.create_new(type, init_val) 
Copy code to clipboard

Creates a new Caché object instance from the class named by type. Normally, init_val is None. See Objects for details on the objects created with this method.

open()
obj = database.open(class_name, oid, concurrency, timeout, res) 
Copy code to clipboard

Opens a Caché object instance using the class named by class_name and the oid of the object. The concurrency argument has a default value of -1. timeout is the ODBC query timeout.

openid()
obj = database.openid(class_name, id, concurrency, timeout) 
Copy code to clipboard

Opens a Caché object instance using the class named by class_name and the id of the object. The concurrency argument has a default value of -1. timeout is the ODBC query timeout.

run_class_method()
value = database.run_class_method(class_name, method_name, [LIST]) 
Copy code to clipboard

Runs the class method method_name, which is a member of the class_name class in the namespace that database is connected to. Arguments are passed in LIST. Some of these arguments may be passed by reference depending on the class definition in Caché. Return values correspond to the return values from the Caché method.

Objects

Methods of the intersys.pythonbind.object package provide access to a Caché object. An Object object is created by the intersys.pythonbind.database create_new() method (see Database for a detailed description). See Using Caché Object Methods for information on how to use the Object methods.

Here is a complete listing of Object methods:

get()
value = object.get(prop_name)
Copy code to clipboard

Returns the value of property prop_name in Caché object object.

run_obj_method()
value = object.run_obj_method(method_name, [LIST]) 
Copy code to clipboard

Runs method method_name on Caché object object. Arguments are passed in LIST. Some of these arguments may be passed by reference depending on the class definition in Caché. Return values correspond to the return values from the Caché method.

set()
object.set(prop_name, val)
Copy code to clipboard

Sets property prop_name in Caché object object to val.

Queries

Methods of the intersys.pythonbind.query package provide the ability to prepare a query, set parameters, execute the query, and and fetch the results. See Using Queries for information on how to use the Query methods.

A Query object is created as follows:

   query = intersys.pythonbind.query(database)
Copy code to clipboard

Here is a complete listing of Query methods:

prepare query

prepare()
query.prepare(string)
Copy code to clipboard

Prepares a query using the SQL string in string.

prepare_class()
query.prepare_class(class_name, query_name)
Copy code to clipboard

Prepares a query in a class definition

set parameters

set_par()
query.set_par(idx, val)
Copy code to clipboard

Assigns value val to parameter idx. The method can be called several times for the same parameter. The previous parameter value will be lost, and the new value can be of a different type. The set_par() method does not support by-reference parameters.

is_par_nullable()
nullable = query.is_par_nullable(idx)
Copy code to clipboard

Returns 1 if parameter idx is nullable, else 0.

is_par_unbound()
unbound = query.is_par_unbound(idx)
Copy code to clipboard

Returns 1 if parameter idx is unbound, else 0.

num_pars()
num = query.num_pars()
Copy code to clipboard

Returns number of parameters in query.

par_col_size()
size = query.par_col_size(idx)
Copy code to clipboard

Returns size of parameter column.

par_num_dec_digits()
num = query.par_num_dec_digits(idx)
Copy code to clipboard

Returns number of decimal digits in parameter.

par_sql_type()
type = query.par_sql_type(idx)
Copy code to clipboard

Returns sql type of parameter.

execute query

execute()
query.execute()
Copy code to clipboard

Generates a result set using any parameters defined by calls to set_par().

fetch results

fetch()
data_row = query.fetch([None])
Copy code to clipboard

Retrieves a row of data from the result set and returns it as a list. When there is no more data to be fetched, it returns an empty list.

col_name()
name = query.col_name(idx)
Copy code to clipboard

Returns name of column.

col_name_length()
length = query.col_name_length(idx)
Copy code to clipboard

Returns length of column name.

col_sql_type()
sql_type = query.col_sql_type(idx)
Copy code to clipboard

Returns sql type of column.

num_cols()
num_cols = query.num_cols()
Copy code to clipboard

Returns number of columns in query.

Times and Dates

The PTIME_STRUCTPtr, PDATE_STRUCTPtr, and PTIMESTAMP_STRUCTPtr packages are used to manipulate Caché %TIME, %DATE, or %TIMESTAMP datatypes.

%TIME

Methods of the PTIME_STRUCTPtr package are used to manipulate the Caché %DATE data structure. Times are in hh:mm:ss format. For example, 5 minutes and 30 seconds after midnight would be formatted as 00:05:30. Here is a complete listing of Time methods:

new()
time = PTIME_STRUCTPtr.new()
Copy code to clipboard

Create a new Time object.

get_hour()
hour = time.get_hour()
Copy code to clipboard

Return hour

get_minute()
minute = time.get_minute()
Copy code to clipboard

Return minute

get_second()
second = time.get_second()
Copy code to clipboard

Return second

set_hour()
time.set_hour(hour)
Copy code to clipboard

Set hour (an integer between 0 and 23, where 0 is midnight).

set_minute()
time.set_minute(minute)
Copy code to clipboard

Set minute (an integer between 0 and 59).

set_second()
time.set_second(second)
Copy code to clipboard

Set second (an integer between 0 and 59).

toString()
stringrep = time.toString()
Copy code to clipboard

Convert the time to a string: hh:mm:ss.

%DATE

Methods of the PDATE_STRUCTPtr package are used to manipulate the Caché %DATE data structure. Dates are in yyyy-mm-dd format. For example, December 24, 2003 would be formatted as 2003-12-24. Here is a complete listing of Date methods:

new()
date = PDATE_STRUCTPtr.new()
Copy code to clipboard

Create a new Date object.

get_year()
year = date.get_year()
Copy code to clipboard

Return year

get_month()
month = date.get_month()
Copy code to clipboard

Return month

get_day()
day = date.get_day()
Copy code to clipboard

Return day

set_year()
date.set_year(year)
Copy code to clipboard

Set year (a four-digit integer).

set_month()
date.set_month(month)
Copy code to clipboard

Set month (an integer between 1 and 12).

set_day()
date.set_day(day)
Copy code to clipboard

Set day (an integer between 1 and the highest valid day of the month).

toString()
stringrep = date.toString()
Copy code to clipboard

Convert the date to a string: yyyy-mm-dd.

%TIMESTAMP

Methods of the PTIMESTAMP_STRUCTPtr package are used to manipulate the Caché %TIMESTAMP data structure. Timestamps are in yyyy-mm-dd<space>hh:mm:ss.fffffffff. format. For example, December 24, 2003, five minutes and 12.5 seconds after midnight, would be formatted as:

2003-12-24 00:05:12:500000000

Here is a complete listing of TimeStamp methods:

new()
timestamp = PTIMESTAMP_STRUCTPtr.new()
Copy code to clipboard

Create a new Timestamp object.

get_year()
year = timestamp.get_year()
Copy code to clipboard

Return year in yyyy format.

get_month()
month = timestamp.get_month()
Copy code to clipboard

Return month in mm format.

get_day()
day = timestamp.get_day()
Copy code to clipboard

Return day in dd format.

get_hour()
hour = timestamp.get_hour()
Copy code to clipboard

Return hour in hh format.

get_minute()
minute = timestamp.get_minute()
Copy code to clipboard

Return minute in mm format.

get_second()
second = timestamp.get_second()
Copy code to clipboard

Return second in ss format.

get_fraction()
fraction = timestamp.get_fraction()
Copy code to clipboard

Return fraction of a second in fffffffff format.

set_year()
timestamp.set_year(year)
Copy code to clipboard

Set year (a four-digit integer).

set_month()
timestamp.set_month(month)
Copy code to clipboard

Set month (an integer between 1 and 12).

set_day()
timestamp.set_day(day)
Copy code to clipboard

Set day (an integer between 1 and the highest valid day of the month).

set_hour()
timestamp.set_hour(hour)
Copy code to clipboard

Set hour (an integer between 0 and 23, where 0 is midnight).

set_minute()
timestamp.set_minute(minute)
Copy code to clipboard

Set minute (an integer between 0 and 59).

set_second()
timestamp.set_second(second)
Copy code to clipboard

Set second (an integer between 0 and 59).

set_fraction()
timestamp.set_fraction(fraction)
Copy code to clipboard

Set fraction of a second (an integer of up to nine digits).

toString()
stringrep = timestamp.toString()
Copy code to clipboard

Convert the timestamp to a string yyyy-mm-dd hh:mm:ss.fffffffff.

Locale and Client Version

Methods of the intersys.pythonbind. default package provide access to Caché version information and Windows locale settings. Here is a complete listing of these methods:

get_client_version()
clientver = intersys.pythonbind.get_client_version();
Copy code to clipboard

Identifies the version of Caché running on the Python client machine.

setlocale()
newlocale = intersys.pythonbind.setlocale(category, locale)
Copy code to clipboard

Sets the default locale and returns a locale string for the new locale. For example:

   newlocale = intersys.pythonbind.setlocale(0, "Russian") # 0 stands for LC_ALL
Copy code to clipboard

would set all locale categories to Russian and return the following string:

   Russian_Russia.1251
Copy code to clipboard

If the locale argument is an empty string, the current default locale string will be returned. For example, given the following code:

   intersys.pythonbind.setlocale(0, "English")
   mylocale = intersys.pythonbind.setlocale(0, ""),"\n";
Copy code to clipboard

the value of mylocale would be:

   English_United States.1252
Copy code to clipboard

For detailed information, including a list of valid category values, see the MSDN library (http://msdn.microsoft.com/library) entry for the setlocale() function in the Visual C++ runtime library.

set_thread_locale()
intersys.pythonbind.set_thread_locale(lcid)
Copy code to clipboard

Sets the locale id (LCID) for the calling thread. Applications that need to work with locales at runtime should call this method to ensure proper conversions.

For a listing of valid LCID values, see the "Locale ID (LCID) Chart" in the MSDN library (http://msdn.microsoft.com/library). The chart can be located by a search on "LCID Chart". It is currently located at:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/script56/html/vsmsclcid.asp

For detailed information on locale settings, see the MSDN library entry for the SetThreadLocale() function, listed under "National Language Support".