/* -Procedure fchain_pdt_c (Extract the frame chain connecting frames) -Abstract Retrieve the list of frame names connecting FROM to TO at epoch ET in the state or position transformation trees. -Copyright Copyright (2001), California Institute of Technology. U.S. Government sponsorship acknowledged. -Required_Reading KERNEL -Keywords FRAME */ #include "SpiceUsr.h" #include "SpiceZfc.h" #include "SpiceZst.h" #include "SpiceZmc.h" void fchain_pdt_c ( ConstSpiceChar * from, ConstSpiceChar * to, SpiceDouble et, SpiceBoolean state, SpiceInt room, SpiceInt lenout, SpiceInt * n, void * chain, SpiceBoolean * found ) /* -Brief_I/O VARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- from I Name of the frame to transform from to I Name of the frame to transform to et I Epoch at which the connecting chain is computed state I Boolean that indicates to use the state tree room I Number of strings in the chain array lenout I The length of the output string. n O Number of values returned for chain. chain O List of frames connecting from to to. found O True if a connecting chain was found. -Detailed_Input from is the name of some reference frame in which states or positions are known. to is the name of some reference frame in which it is desired to represent states or positions. et is the epoch in ephemeris seconds past the epoch of J2000 (TDB) at which the state or position transformation chain should be computed. state is SPICETRUE when this routine is to compute chain in the state transformation tree. If SPICEFALSE it will compute chain from the position transformation tree. room is the maximum number of frame names that can be stored in chain. Since chain is a workspace as well as the output buffer, it nominally should be twice the longest path present in the frame tree at any giving time. For Cassini, 30 frames should be a sufficient. lenout The allowed length of the output string. This length must large enough to hold the output string plus the terminator. If the output string is expected to have x characters, lenout needs to be x + 1. 32 is a reasonable value for lenout (31 characters plus the null terminator). -Detailed_Output n is the number of frames returned in chain. chain lists the frames connecting from to to from the state or position transformation tree at epoch et. In the case where the connection from from to to can be made: chain [0] = FROM chain [1] = NEXT_FRAME . . . . . . chain [n-2] = NEXT_TO_LAST_FRAME chain [n-1] = TO In the case where no connection at the requested epoch in the desired tree can be made, the following is returned in chain: chain [1] = FROM chain [2] = NEXT_FRAME_FOUND . . . . . . chain [m-1] = FURTHEST_FRAME_FROM chain [m] = "" chain [m-2] = FURTHEST_FRAME_TO . . . . . . chain [n-2] = NEXT_TO_LAST_FRAME chain [n-1] = TO found is SPICETRUE if chain contains the path in the requested tree that connects from to to, and SPICEFALSE if no connection was made or more space than room was required to compute it. -Parameters None. -Exceptions 1) If chain has declared length less than the size of a string to be returned, the value will be truncated on the right. See the discussion of lenout above for a reasonable value. 2) If the input string pointer is null, the error SPICE(NULLPOINTER) will be signaled. 3) If the input string has length zero, the error SPICE(EMPTYSTRING) will be signaled. 4) If the output string has length less than two characters, it is too short to contain one character of output data plus a null terminator, so it cannot be passed to the underlying Fortran routine. In this event, the the error SPICE(STRINGTOOSHORT) is signaled. 5) If either or both of the input frames from and to are not known, then the error SPICE(UNKNOWNFRAME) is signaled. found is set to SPICEFALSE, n to 0, and chain is set to a series of empty strings. 6) If there is not sufficient room to compute and store the results the error SPICE(NOTENOUGHROOM) is signaled. found is set to SPICEFALSE, n to 0, and chain is set to a series of empty strings. 7) Routines in the call tree of this routine may signal errors. In the event that one does, found is set to SPICEFALSE, n to 0, and chain is set to a series of empty strings. -Files None. -Particulars This routine provides the user interface to retrieving the list of frames from the state or position transformation trees at a particular epoch of interest, et, that connects the frames from to to. -Examples The following code fragment demonstrates how one would look up and display the list of frames connecting IAU_SATURN to CASSINI_ISS_NAC at the J2000 epoch. The fragment does not assume all the appropriate kernels have been loaded to support making the connection. In the case a breakdown has occurred due to unavailable data, a simple message is displayed indicating where the disconnect occurs. #include #include #include "SpiceUsr.h" #include "SpiceZmc.h" #define LENOUT 32 #define NUMVALS 30 #define J2000 0.0 void main() { SpiceInt n; SpiceChar chain[NUMVALS][LENOUT]; SpiceBoolean found; SpiceInt i; SpiceInt from_index; SpiceInt to_index; /. Load the necessary SPICE kernels. ./ . . . /. Retrieve the list of frames from the position transformation tree. ./ fchain_pdt_c ( "IAU_SATURN", "CASSINI_ISS_NAC", J2000, SPICEFALSE, NUMVALS, LENOUT, &n, chain, &found ); /. Display the results. ./ if ( !found ) { /. Check to see if n is positive. If so, we have two chain fragments separated by an empty string. Display the disconnect message. ./ if ( n > 0 ) { for ( i = 0; i < n; i++ ) { if ( !strncmp(chain[i], "", LENOUT) ) { from_index = i - 1; to_index = i + 1; } } printf ( "Can not connect %s with %s at epoch %f\n", chain[from_index], chain[to_index], J2000 ); } } else { for ( i = 0; i < n; i++ ) { printf ( "%s\n", chain[i] ); } } exit(0); } -Restrictions None. -Literature_References None. -Author_and_Institution F.S. Turner (JPL) -Version -fchain_pdt_c Version 1.0.0, 03-MAY-2001 (FST) */ { /* Begin fchain_pdt_c */ /* Local Variables */ logical yes; logical use_state; /* Participate in error tracing. */ chkin_c ( "fchain_pdt_c"); /* Check the input strings to make sure the pointer is non-null and the string length is non-zero. */ CHKFSTR ( CHK_STANDARD, "fchain_pdt_c", from ); CHKFSTR ( CHK_STANDARD, "fchain_pdt_c", to ); /* Make sure the output string has at least enough room for one output character and a null terminator. Also check for a null pointer. */ CHKOSTR ( CHK_STANDARD, "fchain_pdt_c", chain, lenout ); /* Cast the SpiceBoolean state into a logical to insert into the f2c'd routine. */ use_state = state; /* Call the f2c'd routine */ fchain_pdt_ ( ( char * ) from, ( char * ) to, ( doublereal * ) &et, ( logical * ) &use_state, ( integer * ) &room, ( integer * ) n, ( char * ) chain, ( logical * ) &yes, ( ftnlen ) strlen(from), ( ftnlen ) strlen(to), ( ftnlen ) lenout - 1 ); /* Cast the logical back to SpiceBoolean */ *found = yes; F2C_ConvertTrStrArr ( *n, lenout, chain ); chkout_c ( "fchain_pdt_c"); } /* End fchain_pdt_c */