Using Perl with Caché
Perl Client Class Reference
[Back] 
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

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

Datatypes
All Caché datatypes are supported. See the following sections for information on specific datatypes:
Limitations
In some cases, the Caché language binding engine will map a Perl variable to an intermediate datatype that does not precisely match a Caché datatype. This increases processing efficiency, but can impose minor constraints on the way the datatype is used. See Perl Binding Constraints and Limitations for details.
Null support
In the Perl binding, Perl undef corresponds to Caché null (i.e., ""). Perl has the concept of an empty string, but the Perl binding will not interpret this as a Caché null.
Connections
Methods of the Intersys::PERLBIND::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 Perl 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:
new()
$conn = Intersys::PERLBIND::Connection->new($url, $user, $pwd, $timeout) 
See Connection Information later in this section for a detailed discussion of the parameters.
new_secure()
$conn = Intersys::PERLBIND::Connection->new_secure($url, $srv_principal,
    $security_level, $timeout)
Connection->new_secure() returns the connection proxy that is used to get the proxy for the Caché namespace identified by $url. This method takes the following parameters:
Connection Information
The following information is needed to establish a connection to the Caché database:
Database
Database objects provide a logical connection to a Caché namespace. Methods of the Intersys::PERLBIND::Database package are used to open or create Caché objects, create queries, and run Caché class methods. Database objects are created by the Database->new() method. See Connecting to the Caché Database for more information on creating a Database object.
Here is a complete listing of Database methods:
alloc_query()
$query = $database->alloc_query()
Create a new Query object. See Queries for details on Query object 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 "". See Objects for details on the objects created with this method.
new()
$database = Intersys::PERLBIND::Database->new($conn)
Creates a Database object, which provides a logical connection to a Caché namespace. The Connection object $conn supplies a physical connection to the namespace that the Database object will access.
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.
Objects
Methods of the Intersys::PERLBIND::Object package provide access to a Caché object. An Object object is created by the Intersys::PERLBIND::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)
Returns the value of property $prop_name in Caché object $object.
get_methods()
@methodlist = $object->get_methods(); 
$methodcount = $object->get_methods(); 
In list context, returns a list containing the names of methods in Caché object $object. In scalar context, returns the number of methods in $object.
get_properties()
@proplist = $object->get_properties(); 
$propcount = $object->get_properties();
In list context, returns a list containing the names of properties in Caché object $object. In scalar context, returns the number of properties in $object. Private and multidimensional properties are not returned, and are not accessible through the Perl binding.
is_method()
$bool = $object->is_method($name);
Returns 1 if $name is a valid method name for $object, or 0 otherwise.
is_property()
$bool = $object->is_property($name);
Returns 1 if $name is a valid property name for $object, or 0 otherwise.
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)
Sets property $prop_name in Caché object $object to $val.
Queries
Methods of the Intersys::PERLBIND::Query package provide the ability to prepare a query, set parameters, execute the query, and and fetch the results. A Query object is created by the Intersys::PERLBIND::Database alloc_query() method (see Database for a detailed description). See Using Queries for information on how to use the Query methods.
Here is a complete listing of Query methods:
prepare query
prepare()
$query->prepare($string, $sqlcode)
Prepares a query using the SQL string in $string.
prepare_class()
$query->prepare_class($class_name, $query_name, $sqlcode)
Prepares a query in a class definition
set parameters
set_par()
$query->set_par($idx, $val)
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()
$num = $query->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()
$query->execute($sqlcode)
Generates a result set using any parameters defined by calls to set_par().
fetch results
fetch()
@data_row = $query->fetch($sqlcode)
$column_count = scalar($query->fetch($sqlcode))
When run in a list context, the method 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.
When run in a scalar context, the method returns the number of columns in a row.
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.
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()
Create a new Time object.
get_hour()
$hour = $time->get_hour()
Return hour
get_minute()
$minute = $time->get_minute()
Return minute
get_second()
$second = $time->get_second()
Return second
set_hour()
$time->set_hour($hour)
Set hour (an integer between 0 and 23, where 0 is midnight).
set_minute()
$time->set_minute($minute)
Set minute (an integer between 0 and 59).
set_second()
$time->set_second($second)
Set second (an integer between 0 and 59).
toString()
$stringrep = $time->toString()
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()
Create a new Date object.
get_year()
$year = $date->get_year()
Return year
get_month()
$month = $date->get_month()
Return month
get_day()
$day = $date->get_day()
Return day
set_year()
$date->set_year($year)
Set year (a four-digit integer).
set_month()
$date->set_month($month)
Set month (an integer between 1 and 12).
set_day()
$date->set_day($day)
Set day (an integer between 1 and the highest valid day of the month).
toString()
$stringrep = $date->toString()
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()
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()
Return day in dd format.
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()
$timestamp->set_year($year)
Set year (a four-digit integer).
set_month()
$timestamp->set_month($month)
Set month (an integer between 1 and 12).
set_day()
$timestamp->set_day($day)
Set day (an integer between 1 and the highest valid day of the month).
set_hour()
$timestamp->set_hour($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()
Convert the timestamp to a string yyyy-mm-dd hh:mm:ss.fffffffff.
Locale and Client Version
Methods of the Intersys::PERLBIND 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::PERLBIND::get_client_version();
Identifies the version of Caché running on the Perl client machine.
setlocale()
$newlocale = Intersys::PERLBIND::setlocale($category, $locale)
Sets the default locale and returns a locale string for the new locale. For example:
   $newlocale = Intersys::PERLBIND::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::PERLBIND::setlocale(0, "English")
   $mylocale = Intersys::PERLBIND::setlocale(0, ""),"\n";
the value of $mylocale would be:
   English_United States.1252
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::PERLBIND::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. It is equivalent to calling setlocale() from the C++ runtime library inside the current thread, but a direct call to setlocale() may fail without throwing an exception in some cases.
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".