diff options
Diffstat (limited to 'perl/.svn/text-base/NASTD.pm.svn-base')
| -rw-r--r-- | perl/.svn/text-base/NASTD.pm.svn-base | 313 |
1 files changed, 0 insertions, 313 deletions
diff --git a/perl/.svn/text-base/NASTD.pm.svn-base b/perl/.svn/text-base/NASTD.pm.svn-base deleted file mode 100644 index 70be2ff..0000000 --- a/perl/.svn/text-base/NASTD.pm.svn-base +++ /dev/null @@ -1,313 +0,0 @@ -# $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 |