1 /* 2 3 -Procedure tpictr_c ( Create a Time Format Picture ) 4 5 -Abstract 6 7 Given a sample time string, create a time format picture 8 suitable for use by the routine timout_c. 9 10 -Disclaimer 11 12 THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE 13 CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. 14 GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE 15 ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE 16 PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" 17 TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY 18 WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A 19 PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC 20 SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE 21 SOFTWARE AND RELATED MATERIALS, HOWEVER USED. 22 23 IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA 24 BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT 25 LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, 26 INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, 27 REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE 28 REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. 29 30 RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF 31 THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY 32 CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE 33 ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. 34 35 -Required_Reading 36 37 None. 38 39 -Keywords 40 41 TIME 42 43 */ 44 45 #include "SpiceUsr.h" 46 #include "SpiceZfc.h" 47 #include "SpiceZmc.h" 48 #include "SpiceZst.h" 49 50 tpictr_c(ConstSpiceChar * sample,SpiceInt lenout,SpiceInt lenerr,SpiceChar * pictur,SpiceBoolean * ok,SpiceChar * errmsg)51 void tpictr_c ( ConstSpiceChar * sample, 52 SpiceInt lenout, 53 SpiceInt lenerr, 54 SpiceChar * pictur, 55 SpiceBoolean * ok, 56 SpiceChar * errmsg ) 57 /* 58 59 -Brief_I/O 60 61 VARIABLE I/O DESCRIPTION 62 -------- --- -------------------------------------------------- 63 sample I A sample time string. 64 lenout I The length for the output picture string. 65 lenerr I The length for the output error string. 66 pictur O A format picture that describes sample. 67 ok O Flag indicating whether sample parsed successfully. 68 errmsg O Diagnostic returned if sample cannot be parsed. 69 70 -Detailed_Input 71 72 73 sample is a representative time string to use as a model to 74 format time strings. 75 76 lenout is the allowed length for the output picture. This length 77 must large enough to hold the output string plus the null 78 terminator. If the output string is expected to have x 79 characters, lenout needs to be x + 1. 80 is a reasonable 80 value for lenout (79 characters plus the null 81 terminator). 82 83 lenerr is the allowed length for the output error string. 84 85 86 -Detailed_Output 87 88 89 pictur is a format picture suitable for use with the SPICE 90 routine timout_c. This picture, when used to format an 91 epoch via timout_c, will yield the same time components in 92 the same order as the components in sample. 93 94 ok is a logical flag indicating whether the input format 95 sample could be parsed. If all of the components of 96 sample are recognizable, ok will be returned with the 97 value SPICEFALSE. If some part of pictur cannot be 98 parsed, ok will be returned with the value SPICEFALSE. 99 100 errmsg is a diagnostic message that indicates what part of 101 sample was not recognizable. If sample was successfully 102 parsed, ok will be SPICEFALSE and errmsg will be 103 returned as an empty string. 104 105 -Parameters 106 107 None. 108 109 -Files 110 111 None. 112 113 -Exceptions 114 115 Error free. 116 117 1) All problems with the inputs are diagnosed via ok and errmsg. 118 119 2) If a format picture can not be created from the sample 120 time string, pictur is returned as a blank string. 121 122 -Particulars 123 124 Although the routine timout_c provides CSPICE users with a great 125 deal of flexibility in formatting time strings, users must 126 master the means by which a time picture is constructed 127 suitable for use by timout_c. 128 129 This routine allows CSPICE users to supply a sample time string 130 from which a corresponding time format picture can be created, 131 freeing users from the task of mastering the intricacies of 132 the routine timout_c. 133 134 Note that timout_c can produce many time strings whose patterns 135 can not be discerned by this routine. When such outputs are 136 called for, the user must consult timout_c and construct the 137 appropriate format picture "by hand." However, these exceptional 138 formats are not widely used and are not generally recognizable 139 to an uninitiated reader. 140 141 -Examples 142 143 Suppose you need to print epochs corresponding to some events and 144 you wish the epochs to have the same arrangement of components as in 145 the string "10:23 P.M. PDT January 3, 1993". 146 147 The following subroutine call will construct the appropriate format 148 picture for use with timout_c. 149 150 tpictr_c ( "10:23 P.M. PDT January 3, 1993", 151 lenout, lenerr, pictur, &ok, errmsg ); 152 153 The resulting picture is: 154 155 "AP:MN AMPM PDT Month DD, YYYY ::UTC-7" 156 157 This picture can be used with timout_c to format a sequence 158 of epochs, et[0],...,et[n-1] (given as ephemeris seconds past J2000) 159 as shown in the loop below: 160 161 #include "SpiceUsr.h" 162 . 163 . 164 . 165 for ( i = 0; i < n; i++ ) 166 { 167 timout_c ( et[i], pictur, string ); 168 printf ( "Epoch: %d --- %s\n", i, string ); 169 } 170 171 -Restrictions 172 173 None. 174 175 -Author_and_Institution 176 177 W.L. Taber (JPL) 178 E.D. Wright (JPL) 179 180 -Literature_References 181 182 None. 183 184 -Version 185 186 -CSPICE Version 1.0.0, 23-JUL-1999 (EDW) (WLT) 187 188 -Index_Entries 189 190 Use a sample time string to produce a time format picture 191 192 -& 193 */ 194 195 { /* Begin tpictr_c */ 196 197 /* 198 Local variables 199 */ 200 logical okeydoke; 201 202 /* 203 Participate in error tracing. 204 */ 205 chkin_c ( "tpictr_c" ); 206 207 208 /* 209 Check the input string sample to make sure the pointer is non-null 210 and the string length is non-zero. 211 */ 212 CHKFSTR ( CHK_STANDARD, "tpictr_c", sample ); 213 214 215 /* 216 Make sure the output strings have at least enough room for one output 217 character and a null terminator. Also check for a null pointer. 218 */ 219 CHKOSTR ( CHK_STANDARD, "tpictr_c", pictur, lenout ); 220 CHKOSTR ( CHK_STANDARD, "tpictr_c", errmsg, lenerr ); 221 222 223 /* 224 Call the f2c'd routine. 225 */ 226 tpictr_( ( char * ) sample, 227 ( char * ) pictur, 228 ( logical * ) &okeydoke, 229 ( char * ) errmsg, 230 ( ftnlen ) strlen( sample ), 231 ( ftnlen ) lenout - 1, 232 ( ftnlen ) lenerr - 1 ); 233 234 235 /* 236 Convert the output strings to C style. 237 */ 238 F2C_ConvertStr( lenout, pictur ); 239 F2C_ConvertStr( lenerr, errmsg ); 240 241 242 /* 243 Convert the status flag from logical to SpiceBoolean. 244 */ 245 246 *ok = okeydoke; 247 248 249 chkout_c ( "tpictr_c" ); 250 251 252 } /* End tpictr_c */ 253 254 255