getmsg_c

Index Page getmsg_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 getmsg_c ( ConstSpiceChar  * option,
                       SpiceInt          lenout,
                       SpiceChar       * msg     )
#### Abstract
       Retrieve the current short error message,
       the explanation of the short error message, or the
       long error message.
#### Required_Reading
       ERROR
#### Keywords
       ERROR
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       option     I   Indicates type of error message.
       lenout     I   Available space in the output string msg.
       msg        O   The error message to be retrieved.
#### Detailed_Input
       option  Indicates the type of error message to be retrieved.
               The choices are:  The current short error message,
               the explanation of the short error message,
               or the current long error message.

               Possible values of option are:

                  "SHORT"   -- indicates that the short message is to
                               be retrieved

                  "EXPLAIN" -- indicates that the explanation of the
                               short message is to be retrieved

                  "LONG"    -- indicates that the long message is to
                               be retrieved

               The input strings indicating the choice of option
               may be in mixed case.  For example, there is no
               problem with the call,

                  getmsg_c ( "loNg", MSGLEN, msg );

       lenout  is the maximum allowed length of the output message string,
               including the terminating null character.  For example,
               if the caller wishes to be able to accept an 1840-character
               message, lenout must be set to (at least) 1841.  The current
               maximum long error message length is in fact 1840 characters.
#### Detailed_Output
       msg     is the error message to be retrieved. Its value depends on
               option, and on whether an error condition exists.

               When there is no error condition, msg is empty.

               If an error condition does exist,

                 When option is

                 "SHORT"    --  msg is the current short error message.
                                This is a very condensed, 25-character
                                description of the error.

                 "EXPLAIN"  --  msg is the explanation of the current
                                short error message.  This is a one-line
                                expansion of the text of the short
                                message.

                                Most CSPICE short error messages
                                have corresponding explanation text.
                                For other short error messages, if
                                there is no explanation text, msg
                                will be blank.

                 "LONG"     --  msg is the current long error message.
                                The long error message is a detailed
                                explanation of the error, possibly
                                containing data specific to the
                                particular occurrence of the error.
                                Not all errors have long error messages.
                                If there is none, msg will be empty.
                                Long error messages are no longer than
                                320 characters.

                 invalid    --  msg will remain unchanged from
                                its value on input.
#### Parameters
       None.
#### Exceptions
       1) If the input string option is invalid, the error
          SPICE(INVALIDMSGTYPE) will be signaled.  In that case no message
          is returned; msg retains the value it had on input.

       2) The error SPICE(NULLPOINTER) is signaled if either string pointer
          argument is null.

       3) The caller must pass a value indicating the length of the output
          string.  If this value is not at least 2, the error
          SPICE(STRINGTOOSHORT) is signaled.

       This routine is part of the interface to the
       CSPICE error handling mechanism.  For this reason,
       this routine does not participate in the trace scheme,
       even though it has external references.
#### Files
       None.
#### Particulars
       Please read the "required reading" first!

       A good time to call this routine would be when an error
       condition exists, as indicated by the CSPICE function,
       failed_c.
#### Examples
       Here's an example of a real-life call to getmsg_c to get the
       explanation of the current short error message.

       In this example, a CSPICE routine, ckopn_c, is called.
       Following the return from ckopn_c, the logical function,
       failed_c, is tested to see whether an error occurred.
       If it did, the message is retrieved and output via
       a user-defined output routine:

          #include "SpiceUsr.h"
          #include <stdio.h>

          #define  MSGLEN         1841

          SpiceChar               msg [ MSGLEN ];

                .
                .
                .
          /.
          We call ckopn_c; then test for errors...
          ./

          ckopn_c ( filename, ifname, ncomch, &handle );

          if ( failed_c() )
          {
             /.
             Get explanation text for the current short message
             and print it:
             ./

             getmsg_c ( "EXPLAIN", MSGLEN, msg );

             [Output message]
                      .
                      .
                      .
          }
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman    (JPL)
#### Version
       -CSPICE Version 1.0.0, 5-APR-1999 (NJB)
#### Index_Entries
       get error message
#### Link to routine getmsg_c source file getmsg_c.c

    Thu Apr 16 08:58:10 2009