view release on metacpan or  search on metacpan

doc/AsyncZ.pod  view on Meta::CPAN

=head3 Net::Z3950::AsyncZ methods for ErrMsg handling

C<Net::Z3950::AsyncZ> supplies four methods, two L</"Object Methods">
and two L</"Class Methods">.  

=over 4

=item getErrors

	$err = $asyncZ->getErrors($index);

this method returns a reference to an array of two ErrMsg objects:

	[$errors[$index]->[0], $errors[$index]->[1]]

$index is the index of the server in the C<servers=E<gt>\@servers> array.

See C<Net::Z3950::AsyncZ::getErrors>.

=item getMaxErrors

	$error_number = $asnycZ->getMaxErrors();

the maximum possible errors encountered: some of these may not if fact be errors and therefore
will not test C<true> in C<isZ_Error($err)> 

See C<Net::Z3950::AsyncZ::getMaxErrors>

=item isZ_Error

	$retv = isZ_Error($err)

See C<Net::Z3950::AsyncZ::isZ_Error>

=item isZ_nonRetryable

	$bool = isZ_nonRetryable(isZ_Error($err))        

See C<Net::Z3950::AsyncZ::isZ_nonRetryable>

=back

=head3 Net::Z3950::AsyncZ::ErrMsg methods for ErrMsg Handling

C<Net::Z3950::AsyncZ::ErrMsg> supplies eight object methods, which
enable you to determine the general category under which an
error falls and how serious it is. 
They all return C<true> or C<false>.

The basic syntax for all of these methods is:

	$err->method();

=over 4

=item isSystem

These are ususally errors reported back from Perl or C library
routines.  For instance:

	   Device or resource busy	
	   Too many users
           Permission denied
           Software caused connection abort
           Invalid argument 

An "Invalid argument" will often come back when a query
fails and a library routine attempts to do
something which can't be done without the return value

=item isNetwork

These can be various problems, for instance:

	Connection timed out
	Network is down
        Network is unreachable	
        Connection refused	

=item isTryAgain

This applies to two cases:
	[1] EAGAIN: the system error which returns a "try again" message 
	[2] a process which has been created but never gets far enough to
	    return an exit code, presumably because it has timed out. 

=item isSuccess 

An error which answers C<true> to C<isSuccess> is one for which the
exit code is 0, i.e. one in which the process ended without an
error but did not return any records.

=item isUnspecified

An Unspecified error is generally one which has been reported by the system
but which I have not included among the errors worth reporting
back to ordinary users. (You will, however, find them reported in the log file.)
Even some of the errors which I do list might not be worth
reporting back to the user (usually those answer C<true> to C<isZ_nonRetryable>.)

=item isZ3950

These are error messages returned from the Z3950 module.

=item doRetry

Errors which are temporary and make retrying a worthwhile prospect

=item doAbort

Fatal errors

=back

=head3 Examples of Net::Z3950::AsyncZ::ErrMsg Error Handling

A very basic routine for handling errors is demonstrated in C<basic.pl>:

          sub showErrors {
           my $asyncZ = shift;    # [1]