diff --git a/CHANGES b/CHANGES index 2942097..302a959 100644 --- a/CHANGES +++ b/CHANGES @@ -213,6 +213,14 @@ The following are the changes from calc version 2.14.3.5 to date: E_FUNC COMPLEX *c_sec(COMPLEX *c, NUMBER *eps); E_FUNC COMPLEX *c_cot(COMPLEX *c, NUMBER *eps); + Added help/errorcodes rule to the top level Makefile. + + Added E_USERMAX symbol (== 32767) to indicate the maximum value + allowed for user error codes. + + Improve help/error. Added text about error code ranges and + range symbols. + The following are the changes from calc version 2.14.3.4 to 2.14.3.5: diff --git a/Makefile b/Makefile index d26fe08..690b00d 100644 --- a/Makefile +++ b/Makefile @@ -325,7 +325,8 @@ STATIC_FIRST_TARGETS= ${LICENSE} .static # late targets - things needed after the main build phase is complete # LATE_TARGETS= calc.1 calc.usage \ - cal/.all help/.all help/builtin cscript/.all + cal/.all help/.all help/builtin help/errorcodes \ + cscript/.all # calc tools - tools used by the maintainers of the calc source base # @@ -2465,6 +2466,15 @@ help/builtin: help/Makefile \ ${V} echo '=-=-=-=-= Back to the main Makefile for $@ rule =-=-=-=-=' ${V} echo '=-=-=-=-= ${MAKE_FILE} end of $@ rule =-=-=-=-=' +help/errorcodes: help/Makefile \ + calcerr.h help/errorcodes.hdr help/errorcodes.sed + ${V} echo '=-=-=-=-= ${MAKE_FILE} start of $@ rule =-=-=-=-=' + ${V} echo '=-=-=-=-= Invoking builtin rule for help =-=-=-=-=' + ${RM} -f $@ + cd help; ${MAKE} -f Makefile errorcodes + ${V} echo '=-=-=-=-= Back to the main Makefile for $@ rule =-=-=-=-=' + ${V} echo '=-=-=-=-= ${MAKE_FILE} end of $@ rule =-=-=-=-=' + cscript/.all: ${CSCRIPT_TARGETS} ${CSCRIPT_TARGETS}: cscript/Makefile diff --git a/calcerr_c.awk b/calcerr_c.awk index fbe06f5..79fc6bf 100644 --- a/calcerr_c.awk +++ b/calcerr_c.awk @@ -2,7 +2,7 @@ # # calcerr_c - help produce calcerr.c from calcerr.tbl # -# Copyright (C) 1999 Landon Curt Noll +# Copyright (C) 1999,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 @@ -34,12 +34,12 @@ BEGIN { printf(" * names of calc error values\n"); printf(" */\n"); printf("CONST char *error_table[E__COUNT+2] = {\n"); - printf(" \"No error\",\n"); + printf(" \"No error\",\t\t/* MUST be first */\n"); } { print $0; } END { - printf(" NULL\n"); + printf(" NULL\t/* MUST be last */\n"); printf("};\n"); } diff --git a/calcerr_h.awk b/calcerr_h.awk index 2e4d5f0..64d5c1b 100644 --- a/calcerr_h.awk +++ b/calcerr_h.awk @@ -43,6 +43,7 @@ NF > 1 { END { printf("\n#define E__HIGHEST\t%d\t/* highest calc error */\n", NR+ebase); printf("#define E__COUNT\t%d\t/* number of calc errors */\n", NR); - printf("#define E_USERDEF\t20000\t/* base of user defined errors */\n\n"); + printf("#define E_USERDEF\t20000\t/* base of user defined errors */\n"); + printf("#define E_USERMAX\t32767\t/* maximum user defined error value */\n\n"); printf("/* names of calc error values */\n"); } diff --git a/help/error b/help/error index d3e532f..b914f55 100644 --- a/help/error +++ b/help/error @@ -5,30 +5,97 @@ SYNOPSIS error([n]) TYPES - n integer, 0 <= n <= 32767; defaults to errno() + n integer, defaults to errno() return null value or error value DESCRIPTION + If n == 0: - If n is zero, error(n) returns the null value. + error(n) returns the null value. - For positive n, error(n) returns a value of error type n. + The "global calc_errno value" is set to 0. - error(n) sets calc_errno to n so that until another error-value - is returned by some function, errno() will return the value n. + The global calc error count is not changed. + + For 0 < n <= 32767: + + error(n) 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 n. + + 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 n are reserved for future use and currently + will generate an error. + + The term "global calc_errno value" is an internal calc state. + This is NOT a calc variable called calc_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(n) 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: + + n < 0 Reserved for future use + + n == 0 calc_errno cleared: libc errno codes above here + + 1 <= n <= 9999 system error and libc errno codes + + n == 10000 Reserved for "No error" calc internal state + + 10001 <= n <= E__HIGHEST calc computation error codes + + E__HIGHEST < n < 20000 Reserved for future calc error codes + + 20000 < n <= 32767 User defined error codes start here + + n >= 32768 Reserved for future use + + The following constants are part of the calc error code mechanism: + + E__BASE == 10000 + E_USERDEF == 20000 + E_USERMAX == 32767 + E__BASE < E__HIGHEST < E_USERDEF + E__COUNT == E__HIGHEST - E__BASE + + See help errorcodes for the actual values of the above constants. EXAMPLE - ; errmax(errcount()+1) - 20 + ; errcount(0),; errmax(20),; + ; print errcount(), errmax() + 0 20 + ; a = error(10009) - ; a - Error 10009 + + ; print errcount(), errmax() + 1 20 + ; print a + Error 10009 + ; print iserror(a) + 10009 ; strerror(a) "Bad argument for inverse" + ; b = error(0) + + ; print errcount(), errmax() + 1 20 + ; print isnull(b) + 1 + LIMITS - none + 0 <= n <= 32767 LINK LIBRARY none @@ -37,7 +104,7 @@ SEE ALSO errcount, errmax, errorcodes, iserror, errno, strerror, newerror, stoponerror -## Copyright (C) 1999-2006 Landon Curt Noll +## 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 diff --git a/help/errorcodes.hdr b/help/errorcodes.hdr index 4272d56..d36d441 100644 --- a/help/errorcodes.hdr +++ b/help/errorcodes.hdr @@ -1,6 +1,6 @@ Calc generated error codes (see the error help file): -## Copyright (C) 1999 Landon Curt Noll +## Copyright (C) 1999,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 @@ -21,3 +21,5 @@ Calc generated error codes (see the error help file): ## ## chongo /\oo/\ http://www.isthe.com/chongo/ ## Share and enjoy! :-) http://www.isthe.com/chongo/tech/comp/calc/ + 0 calc_errno cleared: libc errno codes above here + 10000 calc errors start above here