Index Page errprt_c
A B C D E F G H I J K L M N O P Q R S T U V W X
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### Procedure
       void errprt_c ( ConstSpiceChar * op,
                       SpiceInt         lenout,
                       SpiceChar      * list  )
#### Abstract
       Retrieve or set the list of error message items
       to be output when an error is detected.
#### Required_Reading
       ERROR
#### Keywords
       ERROR
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       op         I   The operation:  "GET" or "SET".
       lenout     I   Length of list for output.
       list      I/O  Specification of error messages to be output.
#### Detailed_Input
       op      indicates the operation to be performed.  Possible
               values are "GET" and "SET".

               "SET" means, "the following list specifies the default
               selection of error messages to be output."  These are
               the messages that will be output to the default error
               output device (selected by errdev_c) when an error is
               detected.

               "GET" means, "return the current list of error output
               items."  This is the exact list that was set by the
               last call to this routine with the "SET" option.

               The option can be specified in mixed case.  For example,
               the following call will work:

               errprt_c ( "SeT", lenout, "ALL" )

       lenout  is the allowed length of list when list is returning a
               the error message list.  The size described by lenout
               should be large enough to hold any possible output plus 1.

       list    is a list of error message items.  The items
               are delimited by commas.  The items that can be
               in the list are the words:

               1.  SHORT        ...indicates the short error message
               2.  EXPLAIN      ...the explanation of the short message
               3.  LONG         ...the long error message
               4.  TRACEBACK    ...the traceback
               5.  ALL          ...indicates "output all messages"
               6.  NONE         ...indicates "don't output any messages"
               7.  DEFAULT      ...same as ALL, but includes default
                                    message

               A "list" is a character string containing some or
               all of the above words, delimited by commas.  Examples
               are:

               1.  "SHORT, EXPLAIN"
               2.  "SHORT, LONG"
               3.  "ALL"
               4.  "NONE"
               5.  "ALL, NONE, ALL, SHORT, NONE"

               Each word in the list can be thought of as
               "flipping a switch" to enable or disable the output
               of the message(s) indicated by the word.  The
               words are acted on in the order they occur in the
               list, starting with the leftmost word.  As examples,
               consider the sample lists above.

               The effect of the first list above, "SHORT, EXPLAIN",
               is to enable the output of the short error message
               and the explanatory text corresponding to it.

               The effect of the second list is to enable the output
               of the short and long messages.

               The effect of the third list is to enable the output of
               all of the error messages (short, long, explanation
               of the short message, and traceback).

               The effect of the fourth list is to disable output of
               all of the messages.

               The effect of the fifth list is to disable output of
               all of the messages.  The reason for this is that
               the words in the list are responded to in order,
               from left to right, and "NONE" is the last word.

               If any words other than SHORT, LONG, EXPLAIN, ALL,
               DEFAULT, TRACEBACK or NONE appear in list, those words
               that are recognized are responded to.  The words
               that are not recognized are diagnosed as
               erroneous, and error messages are generated
               for each such unrecognized word.

               The length of list is caller-defined, but only
               the first 100 characters of list will be saved
               for later retrieval.

               Only the first 10 items in the list are used;
               the rest are ignored.
#### Detailed_Output
       list    is a list of error message items.  The value of
               list is that set by the last call to this routine
               using the "SET" option.  See "Detailed Input"
               for a description of the possible values and
               meanings of list.

               The initial value returned is "DEFAULT".

               Only the first 100 characters of list are saved
               when the list is set; any additional characters
               are truncated.  Therefore, the first 100
               characters, at most, of the saved value of list
               will be returned.
#### Parameters
       None.
#### Exceptions
       1) If the input argument op does not indicate a valid operation,
          the error SPICE(INVALIDOPERATION) will be signaled.

       2) If the input argument list does not indicate a valid list of
          error message types, the error SPICE(INVALIDLISTITEM) will be
          signaled.

       3) The error SPICE(EMPTYSTRING) is signalled if the input
          string does not contain at least one character, since the
          input string cannot be converted to a Fortran-style string
          in this case.

       4) The error SPICE(NULLPOINTER) is signalled if the input string
          pointer is null.

       5) The user must pass a value indicating the length of the output
          string, when list is an output.  If this value is not at least 2,
          the error SPICE(STRINGTOOSHORT) is signaled.

       Also, this routine is part of the CSPICE error
       handling mechanism.
#### Files
       None.
#### Particulars
       Please read the "required reading"!

       This routine is intended to be used in conjunction with
       errdev_c, which selects the default output device to which
       the error messages selected by this routine will be
       output.

       Additionally, the error response action must be
       something other than "IGNORE" if the error messages
       are to be output.  Possible choices of the error
       response action are "RETURN", "REPORT", "ABORT", "DEFAULT", and
       "IGNORE".  Use erract_c to set the error response action.

       Only the first 100 characters of list are saved.

       The default set of error messages that are output is the
       set specified by "DEFAULT"; i.e., all of them, including
       the "default" message.
#### Examples
       1.  In this example, we select as the output device
           the file, SPUD.DAT, and then select the error
           messages to be output.  We choose the short
           error message and the traceback.  Since a
           different set of messages may have been selected
           previously, we clear the old setting by putting
           the word, "NONE", at the beginning of the list.

              /.
              Set the error output device to SPUD.DAT:
              ./
              errdev_c (  "SET", lenout, "SPUD.DAT" );

              /.
              Choose error messages:
              ./
              errprt_c (  "SET", lenout, "NONE, SHORT, TRACEBACK" );

       2.  In this example we are retrieving the error message list.

              /.
              Declare the output string and its size.
              ./

             #define     LENOUT  50

             SpiceChar   list[ LENOUT ];

             errdev_c ( "GET", LENOUT, list );
#### Restrictions
       The device to which the selected error messages will
       be written must be selected via errdev_c; otherwise,
       messages will be written to the initial default device.

       Only the first 100 characters of list are saved.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman    (JPL)
#### Version
       -CSPICE Version 1.3.0, 24-JUN-2003 (NJB)

          Bug fix:  case of invalid operation keyword is now
          diagnosed, as per the Exceptions section of the header.

       -CSPICE Version 2.0.0, 09-FEB-1998 (NJB) (EDW)

          Input argument op was changed to type ConstSpiceChar *.

          Re-implemented routine without dynamically allocated, temporary
          strings.

          Corrected errors in examples in which the call sequence
          was incorrect.

       -CSPICE Version 1.0.0, 25-OCT-1997   (EDW)
#### Index_Entries
       get/set error output items
#### Link to routine errprt_c source file errprt_c.c

    Wed Jun  9 13:05:23 2010