1 /*
2 
3 -Procedure setmsg_c  ( Set Long Error Message )
4 
5 -Abstract
6 
7    Set the value of the current long error message.
8 
9 -Disclaimer
10 
11    THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE
12    CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S.
13    GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE
14    ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE
15    PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS"
16    TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY
17    WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A
18    PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC
19    SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE
20    SOFTWARE AND RELATED MATERIALS, HOWEVER USED.
21 
22    IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA
23    BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT
24    LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND,
25    INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS,
26    REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE
27    REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY.
28 
29    RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF
30    THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY
31    CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE
32    ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE.
33 
34 -Required_Reading
35 
36    ERROR
37 
38 -Keywords
39 
40    ERROR
41 
42 */
43 
44    #include "SpiceUsr.h"
45    #include "SpiceZfc.h"
46    #include "SpiceZst.h"
47    #include "SpiceZmc.h"
48 
49 
setmsg_c(ConstSpiceChar * message)50    void setmsg_c ( ConstSpiceChar * message )
51 
52 /*
53 
54 -Brief_I/O
55 
56    VARIABLE  I/O  DESCRIPTION
57    --------  ---  --------------------------------------------------
58    message    I   A long error message.
59 
60 -Detailed_Input
61 
62    message        A ``long'' error message.
63                   message is a detailed description of the error.
64                   message is supposed to start with the name of the
65                   module which detected the error, followed by a
66                   colon.  Example:
67 
68                      "rdtext_c:  There are no more free logical units"
69 
70                   Only the first LMSGLN (see setmsg.c) characters of
71                   message are stored; any further characters are
72                   truncated.
73 
74                   Generally, message will be stored internally by the
75                   CSPICE error handling mechanism.  The only exception
76                   is the case in which the user has commanded the
77                   toolkit to ``ignore'' the error indicated by message.
78 
79                   As a default, message will be output to the screen.
80                   See the required reading file for a discussion of how
81                   to customize toolkit error handling behavior, and
82                   in particular, the disposition of message.
83 
84 -Detailed_Output
85 
86    None.
87 
88 -Parameters
89 
90    None.
91 
92 -Exceptions
93 
94    This routine does not detect any errors.
95 
96    However, this routine is part of the interface to the
97    CSPICE error handling mechanism.  For this reason,
98    this routine does not participate in the trace scheme,
99    even though it has external references.
100 
101 -Files
102 
103    None.
104 
105 -Particulars
106 
107    The CSPICE routine sigerr_c should always be called
108    AFTER this routine is called, when an error is detected.
109 
110    The effects of this routine are:
111 
112       1.  If acceptance of a new long error message is
113           allowed:
114 
115           message will be stored internally.  As a result,
116           The CSPICE routine, getmsg_ , will be able to
117           retrieve message, until message has been ``erased''
118           by a call to reset_c, or overwritten by another
119           call to setmsg_c.
120 
121 
122       2.  If acceptance of a new long error message is not allowed,
123           a call to this routine has no effect.
124 
125 -Examples
126 
127 
128     In the following example, an error is signaled because the
129     double precision variable x contains an invalid value.  The
130     value of x and the maximum allowed value MAXVAL are substituted
131     into the error message at the locations indicated by the # signs
132     below.
133 
134        /.
135        Indicate that x is out of range if x is too large.
136        ./
137 
138        if ( x > MAXVAL )
139        {
140           setmsg_c ( "Variable x = #; maximum allowed value is #" );
141           errdp_c  ( "#",  x                                      );
142           errdp_c  ( "#",  MAXVAL                                 );
143           sigerr_c ( "SPICE(VALUEOUTOFRANGE)"                     ) ;
144           return;
145        }
146 
147 
148 -Restrictions
149 
150    sigerr_c must be called once after each call to this routine.
151 
152 -Literature_References
153 
154    None.
155 
156 -Author_and_Institution
157 
158    N.J. Bachman    (JPL)
159 
160 -Version
161 
162    -CSPICE Version 1.2.1, 25-MAR-1998 (EDW)
163 
164       Corrected errors in header.
165 
166    -CSPICE Version 1.2.0, 08-FEB-1998 (NJB)
167 
168       Re-implemented routine without dynamically allocated, temporary
169       strings.  Made various header fixes.
170 
171    -CSPICE Version 1.0.0, 25-OCT-1997 (EDW)
172 
173 -Index_Entries
174 
175    set long error message
176 
177 -&
178 */
179 
180 { /* Begin setmsg_c */
181 
182    /* Local Variables */
183 
184    /*
185    Check the input string to make sure the pointer is non-null
186    and the string length is non-zero.
187    */
188    CHKFSTR ( CHK_DISCOVER, "setmsg_c", message );
189 
190 
191    /*
192    Call the f2c'd Fortran routine.
193    */
194    setmsg_ ( ( char  * ) message,
195              ( ftnlen  ) strlen(message) );
196 
197 
198 } /* End setmsg_c */
199