|
Using Python with Caché
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:
-
-
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.
-
-
All Caché datatypes are supported. See the following sections for information on specific datatypes:
connect_now()
conn = intersys.pythonbind.connection()
conn.connect_now(url,user,password, timeout)
secure_connect_now()
conn = intersys.pythonbind.connection()
conn.secure_connect_now(url, srv_principal, security_level, timeout)
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:
-
-
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:
For example:
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:
-
-
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.
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>
For example, the sample programs use the following connection string:
"localhost[1972]:Samples"
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".
Here is a complete listing of
Database methods:
create_new()
obj = database.create_new(type, init_val)
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)
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)
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])
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.
Here is a complete listing of
Object methods:
get()
value = object.get(prop_name)
run_obj_method()
value = object.run_obj_method(method_name, [LIST])
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)
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)
Here is a complete listing of
Query methods:
prepare query
prepare()
Prepares a query using the SQL string in
string.
prepare_class()
query.prepare_class(class_name, query_name)
Prepares a query in a class definition
set parameters
set_par()
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)
Returns
1 if parameter
idx is nullable, else
0.
is_par_unbound()
unbound = query.is_par_unbound(idx)
Returns
1 if parameter
idx is unbound, else
0.
num_pars()
Returns number of parameters in query.
par_col_size()
size = query.par_col_size(idx)
Returns size of parameter column.
par_num_dec_digits()
num = query.par_num_dec_digits(idx)
Returns number of decimal digits in parameter.
par_sql_type()
type = query.par_sql_type(idx)
Returns sql type of parameter.
execute query
execute()
Generates a result set using any parameters defined by calls to
set_par().
fetch results
fetch()
data_row = query.fetch([None])
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)
Returns name of column.
col_name_length()
length = query.col_name_length(idx)
Returns length of column name.
col_sql_type()
sql_type = query.col_sql_type(idx)
Returns sql type of column.
num_cols()
num_cols = query.num_cols()
Returns number of columns in query.
%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()
Create a new Time object.
get_hour()
Return hour
get_minute()
minute = time.get_minute()
Return minute
get_second()
second = time.get_second()
Return second
set_hour()
Set hour (an integer between 0 and 23, where 0 is midnight).
set_minute()
Set minute (an integer between 0 and 59).
set_second()
Set second (an integer between 0 and 59).
toString()
stringrep = time.toString()
%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()
Create a new Date object.
get_year()
Return year
get_month()
Return month
get_day()
Return day
set_year()
Set year (a four-digit integer).
set_month()
Set month (an integer between 1 and 12).
set_day()
Set day (an integer between 1 and the highest valid day of the month).
toString()
stringrep = date.toString()
%TIMESTAMP
Here is a complete listing of TimeStamp methods:
new()
timestamp = PTIMESTAMP_STRUCTPtr.new()
Create a new Timestamp object.
get_year()
year = timestamp.get_year()
Return year in
yyyy format.
get_month()
month = timestamp.get_month()
Return month in
mm format.
get_day()
day = timestamp.get_day()
get_hour()
hour = timestamp.get_hour()
Return hour in
hh format.
get_minute()
minute = timestamp.get_minute()
Return minute in
mm format.
get_second()
second = timestamp.get_second()
Return second in
ss format.
get_fraction()
fraction = timestamp.get_fraction()
Return fraction of a second in
fffffffff format.
set_year()
Set year (a four-digit integer).
set_month()
timestamp.set_month(month)
Set month (an integer between 1 and 12).
set_day()
Set day (an integer between 1 and the highest valid day of the month).
set_hour()
Set hour (an integer between 0 and 23, where 0 is midnight).
set_minute()
timestamp.set_minute(minute)
Set minute (an integer between 0 and 59).
set_second()
timestamp.set_second(second)
Set second (an integer between 0 and 59).
set_fraction()
timestamp.set_fraction(fraction)
Set fraction of a second (an integer of up to nine digits).
toString()
stringrep = timestamp.toString()
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();
Identifies the version of Caché running on the Python client machine.
setlocale()
newlocale = intersys.pythonbind.setlocale(category, locale)
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
would set all locale categories to Russian and return the following string:
Russian_Russia.1251
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";
English_United States.1252
set_thread_locale()
intersys.pythonbind.set_thread_locale(lcid)
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:
For detailed information on locale settings, see the MSDN library entry for the
SetThreadLocale() function, listed under "National Language Support".