#
#/*
#	openisis - an open implementation of the CDS/ISIS database
#	Version 0.8.x (patchlevel see file Version)
#	Copyright (C) 2001-2003 by Erik Grziwotz, erik@openisis.org
#
#	This library is free software; you can redistribute it and/or
#	modify it under the terms of the GNU Lesser General Public
#	License as published by the Free Software Foundation; either
#	version 2.1 of the License, or (at your option) any later version.
#
#	This library is distributed in the hope that it will be useful,
#	but WITHOUT ANY WARRANTY; without even the implied warranty of
#	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
#	Lesser General Public License for more details.
#
#	You should have received a copy of the GNU Lesser General Public
#	License along with this library; if not, write to the Free Software
#	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
#
#	see README for more information
#EOH */
#
#	$Id: OpenIsis.pm,v 1.3 2003/04/08 00:20:53 kripke Exp $
#	perl module wrapper for openisis perl XSUB
#
package OpenIsis;

use strict;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);

require Exporter;
require DynaLoader;
# require AutoLoader;

@ISA = qw(Exporter DynaLoader);
# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.
@EXPORT = qw(
	
);
$VERSION = '0.874';

bootstrap OpenIsis $VERSION;

# query mode constants
*QRY_KEYEQ = \0;
*QRY_KEYPF = \1;
*QRY_KEYAT = \2;
*QRY_SCANE = \64;
*QRY_SCANC = \65;
*QRY_SIMPLE = \128;
*QRY_PROPER = \129;

#	error constants
*ERR_EOF   = \-1;
*ERR_FAULT = \-2;
*ERR_INVAL = \-3;
*ERR_BADF  = \-4;
*ERR_IO    = \-5;
*ERR_NOMEM = \-6;
*ERR_BUSY  = \-7;
*ERR_TRASH = \-8;
*ERR_IDIOT = \-9;

#	loglevel constants
*LOG_OFF     = \0;
*LOG_FATAL   = \1;
*LOG_SYSERR  = \2;
*LOG_IOERR   = \3;
*LOG_ERROR   = \4;
*LOG_WARN    = \5;
*LOG_INFO    = \6;
*LOG_VERBOSE = \7;
*LOG_TRACE   = \8;
*LOG_DEBUG   = \9;
*LOG_ALL     = \10;

# Preloaded methods go here.

sub MHL {
	for ( @_ ) {
		s/(<[^=>]*)=[^>]+>/\1>/g; # dump <a=b> substitutions
		s/></; /g; # replace >< pairs
		s/[><]//g; # nuke other ><
		s/^\^.//; # kill initial subfield spec
		s/\^a/; /; # ^a -> ;
		s/\^[b-i]/, /g; # ^[b-i] -> ,
		s/\^./. /g; # others -> .
	}
}

# Autoload methods go after =cut, and are processed by the autosplit program.

1;
__END__
# Below is the stub of documentation for the OpenIsis module.

=head1 NAME

OpenIsis - Perl extension for accessing ISIS databases

=head1 SYNOPSIS

  use OpenIsis;
  $db = OpenIsis::open( 'basename', '-dbpath', '/home/me/mydb' );
	$maxmfn = OpenIsis::maxRowid( $db );
	for (OpenIsis::query( $db, 'plant * water' )) {
		my $row = OpenIsis::read( $db, $_ ); # get hashref
		$row = OpenIsis::read( $db, $_, 'MHL V24,V26,V71' ); # read formatted
		my $v24 = $row->{'24'}; # field tags map to arrayrefs
		OpenIsis::MHL( @$v24 ); # apply heading mode to array
		print $row->{'mfn'}, "TITLE :", join("\n   ", @$v24 ), "\n";
		my $v30 = $row->{'30'}->[0]; # contents is like ^ap. 233-238 ^billus.
		my $subfields = OpenIsis::subfields( $v30 ); # get subfield values
		print "a = ", $subfields->{'a'}, " b = ", $subfields->{'b'}, "\n";
	}
	# print terms starting with A
	print join('; ',OpenIsis::terms( $db, 'a$' )), "\n";

=head1 DESCRIPTION

The OpenIsis perl extension provides access to ISIS databases
based on the openisis C library.


=over 4

=item OpenIsis::open( name [, args ...] )

Open a CDS/Isis data base.

name: basename of a CDS/Isis database.
If given, will be prepended, and the Isis file extensions appended
to build the actual filename. Depending on the value of dbname and
location of files, this may need to include a path. Dbname may be NULL,
if argv includes a dbname argument. 

args: array of names and values; may be empty.
Contains parameters names, which may be prefixed by a dash
('-'). Depending on the actual parameter, the next string may or must
contain a corresponding parameter value. An optional parameter value
may be omitted, if at end of argv or the next name is prefixed with a
dash. To avoid ambiguity, values never start with a dash.
Unrecognized parameter names are ignored.

Possible values:

	-db: basename of database; same as param name;
	-dbpath: path to database;
	usefull when opening secondary indexes or other files 
	whose names are not based on the db basename;
	-v: set verbosity level.

return value:

	non-negative number (dbid)Success
	OpenIsis::ERR_NOENT
	OpenIsis::ERR_BADF

examples:

	$db = OpenIsis::open( 'cds', '-dbpath', '/var/db/cds/' );
	$db = OpenIsis::open( '/var/db/cds/cds' );
	$db = OpenIsis::open( '/var/db/cds/cds', '-v', -1 );
	if ( 0 <= $db ) {
		print "ok";
	} elsif ( OpenIsis::ERR_BADF == $db ) {
		print STDERR "/var/db/cds/cds does not exist\n";
	} elsif ( OpenIsis::ERR_IO == $db ) {
		print STDERR "/var/db/cds/cds is not accessible\n";
	} else {
		print STDERR "/var/db/cds/cds had strange error $db\n";
	}

see also:Query; Terms; Maxrowid
type:Database


=item OpenIsis::maxRowid( $db )

Get highest rowid (a.k.a. MFN) in data base.

dbid: Data base identifier returned by open

return value:

	positive number correspondent highest rowid
	ZERO  unknown value
	negative number Error

examples:

	$db = OpenIsis::open( $base );
	$maxmfn = OpenIsis::maxRowid( $db );

see also:Open
type:Database

=item OpenIsis::query( $db, $qry )

=item OpenIsis::terms( $db, $key )

=item OpenIsis::read( $db, $rowid [, pft] )

=item OpenIsis::2html( $str )

=item OpenIsis::subfields( $str )

=item OpenIsis::log( $level, $filename )

set logging level to a number between 0 (no logging) and 10 (lots of log).
A filename for logging output is currently ignored.

=item OpenIsis::MHL( ... )

=back

=head1 AUTHOR

Erik Grziwotz, erik@openisis.org

Documentation added by Paulo Cattelan, cattelan@control.com.br

=head1 SEE ALSO

L<perl(1)>.

=cut
