summaryrefslogtreecommitdiffstats
path: root/perl/.svn/text-base/NASTD.pm.svn-base
diff options
context:
space:
mode:
Diffstat (limited to 'perl/.svn/text-base/NASTD.pm.svn-base')
-rw-r--r--perl/.svn/text-base/NASTD.pm.svn-base313
1 files changed, 313 insertions, 0 deletions
diff --git a/perl/.svn/text-base/NASTD.pm.svn-base b/perl/.svn/text-base/NASTD.pm.svn-base
new file mode 100644
index 0000000..70be2ff
--- /dev/null
+++ b/perl/.svn/text-base/NASTD.pm.svn-base
@@ -0,0 +1,313 @@
+# $Id: NASTD.pm,v 1.7 2001/10/29 11:18:20 shmit Exp $
+
+package NASTD;
+
+use strict;
+use Carp;
+use vars qw($VERSION @ISA @EXPORT @EXPORT_OK $AUTOLOAD);
+
+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(
+ NAST_OK
+ NAST_SERVER_GONE
+ NAST_NOMEM
+ NAST_UNKNOWN_RESPONSE
+ NAST_TIMEDOUT
+ NAST_UNKNOWN_OPT
+ NAST_SERVER_ERR
+);
+$VERSION = '0.01';
+
+sub AUTOLOAD {
+ # This AUTOLOAD is used to 'autoload' constants from the constant()
+ # XS function. If a constant is not found then control is passed
+ # to the AUTOLOAD in AutoLoader.
+
+ my $constname;
+ ($constname = $AUTOLOAD) =~ s/.*:://;
+ croak "& not defined" if $constname eq 'constant';
+ my $val = constant($constname, @_ ? $_[0] : 0);
+ if ($! != 0) {
+ if ($! =~ /Invalid/) {
+ $AutoLoader::AUTOLOAD = $AUTOLOAD;
+ goto &AutoLoader::AUTOLOAD;
+ }
+ else {
+ croak "Your vendor has not defined NASTD macro $constname";
+ }
+ }
+ no strict 'refs';
+ *$AUTOLOAD = sub () { $val };
+ goto &$AUTOLOAD;
+}
+
+bootstrap NASTD $VERSION;
+
+# Preloaded methods go here.
+
+# Autoload methods go after =cut, and are processed by the autosplit program.
+
+1;
+__END__
+# Below is the stub of documentation for your module. You better edit it!
+
+=head1 NAME
+
+NASTD - Low level Perl extension for NASTD access methods
+
+=head1 SYNOPSIS
+
+ use NASTD;
+
+ $nasthole = &NASTD::nast_sphincter_new();
+ &NASTD::nast_sphincter_close($nasthole);
+
+ $rv = &NASTD::nast_options_get($nasthole);
+ $rv = &NASTD::nast_options_set($nasthole, @options);
+
+ @values = &NASTD::nast_get_result($nasthole);
+
+ $rv = &NASTD::nast_add($sphincter, $key);
+ $rv = &NASTD::nast_del($sphincter, $key);
+ $rv = &NASTD::nast_get($sphincter, $key);
+ $rv = &NASTD::nast_upd($sphincter, $key, $values);
+
+ $rv = &NASTD::nast_stats($sphincter);
+
+ $errcode = &NASTD::nast_geterr($sphincter);
+ $errstring = &NASTD::nast_errmsg($sphincter);
+
+=head1 DESCRIPTION
+
+The Perl NASTD module allows access to the NASTD server via a Perl
+interface. It allows you to do anything you could do through C, such as
+get records, update records, or delete records. It also allows setting
+of various NASTD connection options, as you would through C.
+
+=head2 Opening a sphincter
+
+To do any work with NASTD at all, you must first open a sphincter,
+through which you talk to your NASNASTole. This is fairly
+straightforward: just call C<nast_sphincter_new()> and save the
+returned handle. When you're done with the connection to your NAST, call
+C<nast_sphincter_close()> to terminate it and free all memory of it.
+
+You may specify an optional argument, which points to the unix domain
+socket name that you wish to use. By default, this is set to
+"/tmp/nastd.sock".
+
+When an error occurs in C<nast_sphincter_new()>, you cannot call
+C<nast_geterr()> since there's no sphincter with which to call it.
+Instead, an error message will be printed on B<STDERR> for you to
+diagnose, and the return value will be undefined.
+
+=head2 Checking errors
+
+There are many places during an NASTD session that errors can be
+generated. To check for the presense of an error, call C<nast_geterr()>
+with the sphincter returned from C<nast_sphincter_new()>. This will
+return an error code, which is defined below under B<CONSTANTS>.
+
+If you would rather a printable string be returned, you can call
+C<nast_errmsg()> with an open sphincter, and a printable string will be
+returned.
+
+=head2 Performing a query
+
+Once you have an open sphincter, obtained via C<nast_sphincter_new()>,
+you can start to query it with C<nast_add()>, C<nast_del()>,
+C<nast_get()>, and C<nast_upd()>.
+
+The B<$key> is just that, a case-sensitive key for the database you're
+querying. It's function depends on which query function you're using:
+
+ Function Key Meaning
+ -------- -----------
+ nast_add() Add this key to NASTD, with default values.
+ nast_del() Delete this key from NASTD.
+ nast_get() Return values associated with this key.
+ nast_upd() Update this key in NASTD with my values.
+
+All four of these functions return a status. If everything went okay,
+then 0 is returned, otherwise -1 is returned, and you should check for
+an error with C<nast_geterr()>.
+
+In the case of C<nast_add()>, C<nast_del()>, and C<nast_upd()> all you
+need to do is call the query function and check for errors. If there
+are no errors, then everything went fine.
+
+However, in the case of C<nast_get()>, you probably want the values
+nastociated with the query you made. To get these values, you have to
+call C<nast_get_result()>, which returns an array of values.
+
+=head2 Updating the database via C<nast_upd()>
+
+C<nast_upd()> works like the other query functions, except that in
+addition to the key, you also need to pass an array of values. The
+array needs to have the same number of elements as the NASTD database
+has, and the elements should be in the same order as that specified in
+the special key, "B<_VALUES_>" (see B<Key concepts and values>,
+below).
+
+If the key you are trying to update does not exist, the server creates
+it and gives it the values you specified in your value array. For this
+reason C<nast_upd()> is preferable to C<nast_add()>. In fact,
+C<nast_add()> may not exist very much longer.
+
+=head2 Key concepts and values
+
+It is recommended that before you try to do any real work with a
+particular NASTD suppository, you first investigate the contents of the
+special keys B<_KEY_> and B<_VALUES_>. You can do a regular query on
+them using C<nast_get($nasthole, "_VALUES_")> followed by
+C<nast_get_result()> to investigate their columns.
+
+ Special Key Value Meaning
+ ----------- -------------
+ _KEY_ The type of key the database is keyed on,
+ e.g., "username" would mean this database
+ is a username -> _VALUES_ mapping.
+ _VALUES_ The data being stored for every key in
+ the database. The order here is important,
+ as it's the same order that you'll get
+ when calling nast_get_result().
+ _DELIM_ Only used internally to the NASTD server.
+
+As noted above, the B<_VALUES_> key shows what data you can find in the
+NASTD database, as well as the order it is returned in. This is why you
+should investigate this key before trying to do any real work with
+NASTD. You have to know what columns mean what values for any real
+decision making to be done.
+
+=head2 Server options
+
+In order to fine-tune server performance and behaviour, it is possible
+to set various server-side options through the C<nast_options_get()> and
+C<nast_options_set()> APIs.
+
+The interface is a bit clumsy at the low level - you pass in an array
+to C<nast_options_set()> which has the options in a specific order, and
+you get an array back from C<nast_options_get()> which contains the
+options in a specific order.
+
+It is recommended that before you call C<nast_options_set()> that you
+first obtain the default options from the server through
+C<nast_options_get()> and manipulate the values you care about. Then
+pass that array back to C<nast_options_set()>.
+
+The options you can set are as follows (remember to keep this order!):
+
+ Index C Option Name Meaning (type)
+ ----- ------------- --------------
+ 0 use_qcache Whether or not to use the
+ in-memory query cache. (BOOL)
+ 1 use_localdb Whether or not to use the on-disk
+ database. (BOOL)
+ 2 fallthrough_async Whether or not to use an
+ asynchronous API for fallthrough
+ queries. (BOOL)
+ 3 always_fallthrough Whether or not to always check
+ the fallthrough cache over the
+ local ones. Setting this to 1
+ is the same as setting use_qcache
+ and use_localdb to 0. (BOOL)
+ 4 fail_once Whether or not to check a query
+ in the local and in-memory storage
+ once, and fail if the result isn't
+ found the first time, then defer
+ the next query to the fallthrough
+ queue. (BOOL)
+ 5 no_fallthrough Disable fallthrough queriers to
+ MySQL server. (BOOL)
+
+=head1 STATISTICS
+
+The C<nast_stats()> function is used to gather server statistics. First
+you call C<nast_stats()>, which grabs the statistics and stores them as
+a result. Then you call C<nast_getresult()> as you would for a query.
+
+The statistics come back in a human readable array, suitable for printing.
+
+=head1 CONSTANTS
+
+The only constants returned are via C<nast_geterr()>:
+
+ Error Code Meaning
+ ---------- -------
+ NAST_OK No errors occured.
+ NAST_SERVER_GONE The connection to the server no longer
+ exists.
+ NAST_NOMEM The client has run out of memory performing
+ an operation.
+ NAST_UNKNOWN_RESPONSE The server sent us a response we can't
+ understand.
+ NAST_TIMEDOUT The soft timeout on a query has elapsed.
+ This normally means the server is a bit
+ bogged down, and the query should be
+ retried.
+ NAST_UNKNOWN_OPT The server sent us an unknown option or
+ we tried to set an unknown option.
+ NAST_SERVER_ERR Generic server side error. Check
+ nast_errmsg() for more details.
+
+=head1 SAMPLE PROGRAM
+
+ #!/usr/bin/env perl
+
+ use NASTD;
+
+ $nasthole = &NASTD::nast_sphincter_new();
+ if (!defined($nasthole)) {
+ # Error message already printed.
+ exit(1);
+ }
+
+ # Don't fallthrough to MySQL for this query.
+ # First we get the default options from the server, then tweak
+ # the ones we care about, and update the server with our options.
+ @options = &NASTD::nast_options_get($nasthole);
+ if (!defined(@options)) {
+ print STDERR "Couldn't get options: " .
+ &NASTD::nast_errmsg($nasthole) . "\n";
+ }
+ $options[5] = 1;
+
+ if (&NASTD::nast_options_set($nasthole, @options) == -1) {
+ print STDERR "Couldn't set options: " .
+ &NASTD::nast_errmsg($nasthole) . "\n";
+ }
+
+ # Get some values.
+ if (&NASTD::nast_get($nasthole, "shmit") == -1) {
+ print STDERR "Couldn't perform get: " .
+ &NASTD::nast_errmsg($nasthole) . "\n";
+ &NASTD::nast_close_sphincter($nasthole);
+ exit(1);
+ }
+
+ @vals = &NASTD::nast_get_result($nasthole);
+ $nitems = $#vals + 1;
+ print "Number of columns: $nitems.\n";
+ for ($i = 0; $i < $nitems; $i++) {
+ $val = shift(@vals);
+ print "Result[$i]: $val\n";
+ }
+
+ &NASTD::nast_sphincter_close($nasthole);
+
+=head1 BUGS
+
+fail_once behaviour is not working as of this writing.
+
+=head1 AUTHOR
+
+Brian Cully <L<shmit@rcn.com|mailto:shmit@rcn.com>>
+
+=cut