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 
 
Wed Apr  5 17:54:35 2017