AdabasPerl is a Perl module providing access to an Adabas D Database Server. It consists of a collection of perl functions. Each AdabasPerl function generally invokes several Adabas D library functions.
The first of the following two sections will cover all procedures of the AdabasPerl call interface. The second section give hints, how to use AdabasPerl in your Perl interpreter.
Adabas::logon (connect-str)
Adabas::logon (connect-str, serverdb)
Adabas::logon (connect-str, serverdb, sql-mode)
Connect to an Adabas D server using connect-str. The connect string should be a string in one of the following forms:
If name and password are given (comma separated), both are translated into upper case before they are used to connect to the database.
If a userkey is given (with a leading comma), the data for name and password are extracted from the xuser record. If only a comma is given, it stands for the DEFAULT xuser entry.
The special connect string -noconnect signals, that only a low level connection to the database server is established, but no connection at the user level is made. Currently this connection can only be used for the Adabas::logoff command.
A logon handle is returned and should be used for all other AdabasPerl functions that require a logon handle. Multiple connections to the same or different servers are allowed. Adabas::logon returns a null string, if the connection is not made for any reason (login or password incorrect, network unavailable, etc.). In this case Adabas::errortxt will yield the error message of the database server.
If a serverdb is given, the connection is made to this serverdb. Else the value of the environment variable SERVERDB, which resides in the global hash $ENV{SERVERDB}, is used as the name of the server. If SERVERDB isn't set, the environment variable DBNAME is tested also.
The name of a serverdb may be prefixed by a colon separated hostname. An example call of Adabas::logon would be:
$logon = Adabas::logon("demo,adabas","mycomp:mydb");
If a sqlmode is given, the connection is made in this sqlmode. Sqlmode can be any of adabas, ansi or oracle. Default is sqlmode adabas.
You can create multiple connections to the database server by calling Adabas::logon multiple times. The limit is set by the configuration of the database or by the amount of available memory, not by AdabasPerl. Since you can create multiple cursors out of one logon handle, it only makes sence to have multiple logons with different users on each connection.
Adabas::logoff (logon-handle)
Logoff from the Adabas D server connection associated with logon-handle. Logon-handle must be a valid handle previously opened with Adabas::logon. Adabas::logoff returns a null string. Adabas::logoff raises a Tcl error if the logon handle specified is not open.
Adabas::open (logon-handle)
Open a SQL cursor to the server. Adabas::open returns a cursor to be used on subsequent AdabasPerl commands that require a cursor handle. Logon-handle must be a valid handle previously opened with Adabas::logon. Multiple cursors can be opened through the same or different logon handles.
Adabas::open returns an undefined value if the logon handle specified is not open. In this case Adabas::errortxt will yield the error message of the database server.
No programs should depend on the form of the returned cursor; instead you should store the returned cursor handle into a variable:
$cursor = Adabas::open($logon) or die Adabas::errortxt;
Adabas::close (cursor-handle)
Closes the cursor associated with cursor-handle. Adabas::close silently ignores if the logon handle specified is not open.
Adabas::sql (cursor-handle, sql-statement)
Adabas::sql (cursor-handle, sql-statement, sqlmode)
Adabas::sql (cursor-handle, sql-statement, sqlmode, resulttable)
Send the Adabas D SQL statement sql-statement to the server. Cursor-handle must be a valid handle previously opened with Adabas::open. Adabas::sql will return the numeric return code 0 on successful execution of the sql statement.
In case of an error a subsequent call of Adabas::rc will yield the return code; Adabas::errorpos will contain the error position.
Only a single SQL statement may be specified in sql-statement. Adabas::fetch allows retrieval of return rows generated.
If sqlmode is specified, then the sql-statement will be parsed and executed in this sqlmode, and not in the session wide sqlmode determined by Adabas::logon. Note, that it may be neccesary to give the same sqlmode option when calling Adabas::fetch.
If resulttable is specified, this will become the name of the resulttable of the SELECT statement. For any other statement kind (e.g. UPDATE or CREATE) the resulttable option will be ignored.
You have to give an explicit resulttable name, if you want to fetch from more than one cursor at once. The resulttable names can be arbitrary (max. 18 characters long), but should be distinct between all cursors of one logon handle, you want to fetch from.
Adabas::sql returns a value different to 0 (zero), if the cursor handle specified is not open, if the SQL statement is syntactically incorrect or if no data was found for a SELECT or no row was affected by an UPDATE or DELETE command.
If the given sql-statement denotes a select into, the selected values are stored directly into the mentioned parameters. The parameter names must denote scalar variables. E.g.
Adabas::sql ($cursor,"SELECT DATE, TIME INTO :resDate, :resTime FROM dual");
After the above call of Adabas::sql the current date and time is stored into the variables resDate and resTime.
Adabas::fetch (cursor-handle)
Adabas::fetch (cursor-handle,position)
Adabas::fetch (cursor-handle,position,sqlmode)
position may be any of the following.
Return the next row from the last SQL statement executed with Adabas::sql as a list. Cursor-handle must be a valid handle previously opened with Adabas::open. Adabas::fetch returns a false value if the cursor handle specified is not open. All returned columns are converted to character strings.
An empty list is returned if there are no more rows in the current set of results. The list that is returned by Adabas::fetch contains the values of the selected columns in the order specified by SELECT.
The cursor can be moved in any direction by means of the position option. Its value can have any of the forms first, last, next, prev or it can be a number. The textual variants specify the direction, in which the cursor should be moved. A direction of e.g. first rewinds the cursor to the start of the result set. A number denotes the rownum of the result row to fetch; the first row has the rownum 1. Default position is next.
It may be nessecary, to give the same sqlmode option, as you give to Adabas::sql, since some mode dependend computations (e.g. date format) are delayed to the call of Adabas::fetch.
Adabas::fetch performs conversions for all data types. For long data only a long descriptor is returned, which currently cannot be used by any AdabasPerl function.
A subsequent call of Adabas::errortxt will yield the return code of the fetch. 0 indicates the row was fetched successfully; 100 indicates the end of data was reached.
Adabas::fetchHash (cursor-handle)
Adabas::fetchHash (cursor-handle,position)
Adabas::fetchHash (cursor-handle,position,sqlmode)
position may be any of the following.
Return the next row from the last SQL statement executed with Adabas::sql as a list describing a hash. Cursor-handle must be a valid handle previously opened with Adabas::open. Adabas::fetch returns a false value if the cursor handle specified is not open. All returned columns are converted to character strings.
An empty list is returned if there are no more rows in the current set of results. The list that is returned by Adabas::fetch contains the values of the selected columns in the order specified by SELECT.
An example session follows.
% Adabas::sql ($cursor, "SELECT USER \"my_name\" FROM dual");
% %x = Adabas::fetchHash ($cursor);
% print $x(my_name);
krischan
The cursor can be moved in any direction by means of the position option. Its value can have any of the forms first, last, next, prev or it can be a number. The textual variants specify the direction, in which the cursor should be moved. A direction of e.g. first rewinds the cursor to the start of the result set. A number denotes the rownum of the result row to fetch; the first row has the rownum 1. Default position is next.
It may be nessecary, to give the same sqlmode option, as you give to Adabas::sql, since some mode dependend computations (e.g. date format) are delayed to the call of Adabas::fetch.
Adabas::fetch performs conversions for all data types. For long data only a long descriptor is returned, which currently cannot be used by any AdabasPerl function.
A subsequent call of Adabas::errortxt will yield the return code of the fetch. 0 indicates the row was fetched successfully; 100 indicates the end of data was reached.
Adabas::commit (logon-handle)
Commit any pending transactions from prior Adabas::sql commands that use a cursor opened through the connection specified by logon-handle. Logon-handle must be a valid handle previously opened with Adabas::logon. Adabas::commit returns 1 if the logon handle specified is not open.
Adabas::rollback (logon-handle)
Rollback any pending transactions from prior commands that use a cursor opened through the connection specified by logon-handle. Logon-handle must be a valid handle previously opened with Adabas::logon. Adabas::rollback returns 1 if the logon handle specified is not open.
Adabas::autocommit (logon-handle,on-off)
Enables or disables automatic commit of SQL data manipulation statements using a cursor opened through the connection specified by logon handle. Logon-handle must be a valid handle previously opened with adalogon. on-off must be a integer representing a boolean value. Adabas::autocommit returns 1 if the logon handle specified is not open.
AdabasPerl provides feedback of Adabas D server messages by means of some parameterless functions returning information about recently invoked AdabasPerl functions. This status informations are shared among all open AdabasPerl handles. The following list shows all status functions of AdabasPerl.
Typical values are:
As the introduction already said, AdabasPerl is a module usable by Perl. It is available with the name Adabas, following the Perl conventions with capitalized module names.
The module consists of two parts: a Perl module (written in Perl) and a shared library (on Unix systems with the extension .so or .sl) waiting in the lib/perl subdirectory of $DBROOT. You can tell Perl to use it with a command sequence like the following. Note, that it is essential to modify the INC variable in the BEGIN block, since code in this block will be executed before the use statement is compiled.
BEGIN {@INC = (@INC, "$ENV{DBROOT}/lib/perl");}
use Adabas;
An alternative way to tell Perl, where to look for the Adabas module, is to give the directory with the -I command line option like this:
perl -I$DBROOT/lib/perl script.pl
You can copy (or move) the contents of $DBROOT/lib/perl
into the path, where all the Perl extensions live on your computer.
The pathname of this directory depends on your installation,
it could be something like /usr/lib/perl5/i586-linux/5.004.
Probably you have to be the superuser to copy something into this directory.
If both files (Adabas.pm and auto/Adabas/Adabas.so) can be
found in the mentioned directory, you can use the Adabas module without
changing the @INC variable or giving the -I option.
The following is an example for a command sequence to select and fetch the first row with two columns from a table.
# First load the Adabas module into the Perl interpreter.
BEGIN {@INC = (@INC, "$ENV{DBROOT}/lib/perl");}
use Adabas;
# Define the variables.
my $logon, $cursor, $resultHash;
# First open the connection to the database and one cursor.
$logon = Adabas::logon("DEMO,DEMO", "MYDB") or die Adabas::errortxt;
$cursor = Adabas::open($logon) or die Adabas::errortxt;
# Now fire up the select statement.
Adabas::sql($cursor, "select firstname, name from employee order by empno")
and die Adabas::rc, " at pos ", Adabas::errorpos, ": ", Adabas::errortxt;
# Fetch the first row; put the result into a hash.
%resultHash = Adabas::fetchHash ($cursor) or die Adabas::errortxt;
print "The first employee is $resultHash{FIRSTNAME} $resultHash{NAME}\n";
# Finally close everything, that was opened.
Adabas::close($cursor);
Adabas::logoff($logon);