=head1 NAME

afsperlmisc - Miscellaneous functions and variables.

=head1 SYNOPIS

   use AFS;              # import all AFS names
   use AFS @AFS::MISC;   # import just the misc names

   $AFS::CODE
   afsok
   checkafs
   AFS::raise_exception
   AFS::error_messages
   AFS::constant
   setpag
   XSVersion
   get_syslib_version
   get_server_version

=head1 DESCRIPTION

This document describes the miscellaneous features
available from the AFS module.

=head1 $AFS::CODE

The special variable $AFS::CODE contains the statue value of the last AFS
function call. A non-zero value indicates an error occurred, while a
zero indicates success. This variable is magical. (like the $! variable)
If you reference it as a string you will get an error message, and
if you reference it as a numeric value (use the int() function or add 0 to
it) it will equal the numeric error code.

=head2 EXAMPLE

 if ($AFS::CODE eq "User or group doesn't exist") ....

 if ($AFS::CODE == &AFS::PRNOENT) ....

=head1 afsok

Convenience function that returns true if $AFS::CODE is equal to 0.

=head2 EXAMPLE

   $acl = getacl($path);

   if (afsok) ....

=head1 checkafs

Convenience function that calls die and prints an error message
if $AFS::CODE is not equal to 0. Used mainly for debugging.

=head2 EXAMPLE

   $acl = getacl($path);
   checkafs("getacl");

=head1 AFS::raise_exception

 $current = AFS::raise_exception([$new]);

 If raise_exception is set, then a perl exception will be raised whenever
 an error is returned from an AFS function call. This is used mainly for
 debugging and testing.

=head2 EXAMPLE

  $old = AFS::raise_exception(1);

  ... make some calls you want to raise exceptions for
  ... there is an error

  AFS::raise_exception($old);

=head1 AFS::error_message

  Converts numeric code into a string.

=head2 EXAMPLES

 $mess = AFS::error_message($code);

=head1 AFS::constant

  $value = AFS::constant($name);

  Converts a constant (i.e, #define) into scaler. Returns undef for
  unknown constants. For example:

=head2 EXAMPLES

  $value = AFS::constant("PRIDEXIST"); # value = 267265

=head1 &AFS::CONSTANT

  All values referenced through the constant function can 
  by referenced as functions in the AFS package. This is the
  preferred way of accessing constants.

=head2 EXAMPLES

  $value = AFS::constant("PRIDEXIST"); # value = 267265

  $value = &AFS::PRIDEXIST;            # value = 267265, preferred method 

=head1 setpag

  Creates a new PAG.

=head2 EXAMPLES

  $ok = setpag();

=head1 XSVERSION

  Reports the version number of the underlying XS file.

=head2 EXAMPLES

  print 'XS-Version = ', XSVERSION, "\n";

=head1 get_syslib_version

  Reports the version number of the underlying AFS system library.

=head2 EXAMPLES

  print 'Syslib Version = ', get_syslib_version, "\n";

=head1 get_server_version(SERVER [, HOST [, VERBOSE]])

  Reports the version number of the SERVER process running at HOST
  (default localhost).

=head2 EXAMPLES

  print 'Server Version = ', get_server_version('pts', 'ibm-1'), "\n";

