NAME
    error - generate a value of specified error type

SYNOPSIS
    error([errnum])

TYPES
    errnum	integer, defaults to errno()

    return	null value or error value

DESCRIPTION
    If errnum == 0:

	error(errnum) returns the null value.

	The "global calc_errno value" is set to 0.

	The global calc error count is not changed.

    For 0 < errnum <= 32767:

	error(errnum) returns a value that is of a special type called
	"error".  The "error" return value, when given to iserror()
	will cause that function to return a true value that happens
	to match the "global calc_errno value".

	The "global calc_errno value" is then set to errnum.

	The global calc error count (see help errcount) is incremented.
	If the global calc error count exceeds the maximum count
	(see help errmax), any ongoing calc execution is aborted.

    All other values of errnum are reserved for future use and currently
    will generate an error.

    NOTE:

	Calling error() without an argument will return the current
	"global calc_errno value" AND will also increment the
	global calc error count.

    Use errno() instead of error() to return the "global calc_errno
    value" without incrementing the global calc error count.

    The term "global calc_errno value" is an internal calc state.
    This is NOT a calc variable called calc_errno.  The value of the
    "global calc_errno value" may be returned by errno() (see help errno).

    The "global calc_errno value" be set to some other non-zero
    value by other builtin functions and calculations, especially
    if they result in an error.  Thus, while calling errno(errnum) may
    set calc_errno, some other error may later overwrite the
    "global calc_errno value".

    By convention, the "global calc_errno value" has the following ranges:

	errnum < 0			Reserved for future use

	errnum == 0			calc_errno cleared: libc errno codes above here

	1 <= errnum <= 9999		system error and libc errno codes

	errnum == 10000			Reserved for "No error" calc internal state

	10001 <= errnum <= E__HIGHEST	calc computation error codes

	E__HIGHEST < errnum < 20000	Reserved for future calc error codes

	20000 < errnum <= 32767		User defined error codes start here

	errnum >= 32768			Reserved for future use

    The following constants are part of the calc error code mechanism:

	E__BASE == 10000			# 1 less than the 1st calc computation error code
	E_USERDEF == 20000			# User defined error codes start
	E_USERMAX == 32767			# maximum user defined error code
	E__BASE < E__HIGHEST < E_USERDEF	# How E__HIGHEST is bounded
	E__COUNT == E__HIGHEST - E__BASE	# Number of calc computation error codes

    See help errorcodes for the actual values of the above constants.

EXAMPLE
    ; errcount(0),; errmax(20),;
    ; print errcount(), errmax()
    0 20

    ; a = error(10009)

    ; print errcount(), errmax()
    1 20
    ; print a
    Error 10009
    ; print iserror(a)
    10009
    ; print strerror(a)
    "Bad argument for inverse"
    ; print errno()
    10009

    ; b = error(0)

    ; print errcount(), errmax()
    1 20
    ; print isnull(b)
    1
    ; print errno()
    0

LIMITS
    0 <= errnum <= 32767

LINK LIBRARY
    int calc_errno;	/* global calc_errno value */

SEE ALSO
    errcount, errmax, errorcodes, iserror, errno, strerror, newerror,
    stoponerror

## Copyright (C) 1999-2006,2023  Landon Curt Noll
##
## Calc is open software; you can redistribute it and/or modify it under
## the terms of the version 2.1 of the GNU Lesser General Public License
## as published by the Free Software Foundation.
##
## Calc 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.
##
## A copy of version 2.1 of the GNU Lesser General Public License is
## distributed with calc under the filename COPYING-LGPL.  You should have
## received a copy with calc; if not, write to Free Software Foundation, Inc.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## Under source code control:	1995/12/18 03:30:59
## File existed as early as:	1995
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/