Index Page stpool_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 stpool_c ( ConstSpiceChar    * item,
                       SpiceInt            nth,
                       ConstSpiceChar    * contin,
                       SpiceInt            lenout,
                       SpiceChar         * string,
                       SpiceInt          * size,
                       SpiceBoolean      * found  )
#### Abstract
       Retrieve the nth string from the kernel pool variable, where the
       string may be continued across several components of the kernel pool
       variable.
#### Required_Reading
        None.
#### Keywords
        POOL
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       item       I   Name of the kernel pool variable.
       nth        I   Index of the full string to retrieve.
       contin     I   Character sequence used to indicate continuation.
       lenout     I   Available space in output string.
       string     O   A full string concatenated across continuations.
       size       O   The number of characters in the full string value.
       found      O   Flag indicating success or failure of request.
#### Detailed_Input
       item       is the name of a kernel pool variable for which
                  the caller wants to retrieve a full (potentially
                  continued) string.

       nth        is the number of the string to retrieve from the kernel
                  pool.  The range of `nth' is 0 to one less than the
                  number of full strings that are present.

       contin     is a sequence of characters which (if they appear as the
                  last non-blank sequence of characters in a component of a
                  value of a kernel pool variable) act as a continuation
                  marker:  the marker indicates that the string associated
                  with the component containing it is continued into the
                  next literal component of the kernel pool variable.

                  If contin is blank, all of the components of `item'
                  will be retrieved as a single string.

       lenout     is the available space in the output string, counting
                  room for the terminating null.  Up to lenout-1 "data"
                  characters will be assigned to the output string.
#### Detailed_Output
       string     is the nth full string associated with the kernel
                  pool variable specified by item.

                  Note that if `string' is not sufficiently long to hold
                  the fully continued string, the value will be truncated.
                  You can determine if `string' has been truncated by
                  examining the variable `size'.  `string' will always be
                  null-terminated, even if truncation of the data occurs.

       size       is the index of last non-blank character of the continued
                  string as it is represented in the kernel pool.  This is
                  the actual number of characters needed to hold the
                  requested string.  If `string' contains a truncated
                  portion of the full string, strlen(string) will be less
                  than `size'.

                  If the value of `string' should be a blank, then
                  SIZE will be set to 1.

       found      is a logical variable indicating success of the
                  request to retrieve the nth string associated
                  with item.  If an nth string exists, `found' will be
                  set to SPICETRUE; otherwise `found' will be set to
                  SPICEFALSE.
#### Parameters
       None.
#### Exceptions
       1) If the variable specified by item is not present in the kernel
          pool or is present but is not character valued, string will be
          returned as a null string, size will be returned with the value 0
          and found will be set to SPICEFALSE.

       2) If the variable specified has a blank string associated
          with its nth full string, string will be blank, size
          will be 1 and found will be set to SPICETRUE.

       3) If string is not long enough to hold all of the characters
          associated with the nth string, it will be truncated on the
          right.  string will still be null terminated.

       4) If the continuation character is a blank, every component
          of the variable specified by item will be inserted into
          the output string.

       5) If the continuation character is blank, then a blank component
          of a variable is treated as a component with no letters.
          For example:

             STRINGS = ( 'This is a variable'
                         'with a blank'
                         ' '
                         'component.' )

          Is equivalent to

             STRINGS = ( 'This is a variable'
                         'with a blank'
                         'component.' )

          from the point of view of stpool_c if contin is set to the
          blank character.

       6) If either the input or output string pointers are null, the error
          SPICE(NULLPOINTER) will be signaled.

       7) If any input strings have length zero, the error
          SPICE(EMPTYSTRING) will be signaled.

       8) 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) will be signaled.
#### Files
       None.
#### Particulars
       The SPICE Kernel Pool provides a very convenient interface for
       supplying both numeric and textual data to user application
       programs.  However, any particular component of a character valued
       component of a kernel pool variable is limited to 80 or fewer
       characters in length.

       This routine allows you to overcome this limitation by "continuing"
       a character component of a kernel pool variable. To do this you need
       to select a continuation sequence of characters and then insert this
       sequence as the last non-blank set of characters that make up the
       portion of the component that should be continued.

       For example, you may decide to use the sequence "//" to indicate
       that a string should be continued to the next component of a kernel
       pool variable.   Then set up the kernel pool variable as shown below:

          LONG_STRINGS = ( 'This is part of the first component //'
                           'that needs more than one line when //'
                           'inserting it into the kernel pool.'
                           'This is the second string that is split //'
                           'up as several components of a kernel pool //'
                           'variable.' )

       When loaded into the kernel pool, the variable LONG_STRINGS
       will have six literal components:

          component[0] == "This is part of the first component //"
          component[1] == "that needs more than one line when //"
          component[2] == "inserting it into the kernel pool."
          component[3] == "This is the second string that is split //"
          component[4] == "up as several components of a kernel pool //"
          component[5] == "variable."

       These are the components that would be retrieved by the call

          gcpool_c ( "LONG_STRINGS", 1, 6, 81, &n, component, &found );

       However, using the routine stpool_c you can view the variable
       LONG_STRINGS as having two long components.

          string [0] == "This is part of the first component that "
                        "needs more than one line when inserting "
                        "it into the kernel pool. "

          string [1] == "This is the second string that is split "
                        "up as several components of a kernel pool "
                        "variable. "

       These string components would be retrieved by the following two
       calls.  We will use 81 as the length of the elements of the string
       array.

          stpool_c( "LONG_STRINGS", 0, "//", 81, string[0], &size, &found );
          stpool_c( "LONG_STRINGS", 1, "//", 81, string[1], &size, &found );
#### Examples
       Example 1.  Retrieving file names.

          Suppose a you have used the kernel pool as a mechanism for
          specifying SPK files to load at startup but that the full names
          of the files are too long to be contained in a single text line
          of a kernel pool assignment.

          By selecting an appropriate continuation character ("*" for
          example)  you can insert the full names of the SPK files into the
          kernel pool and then retrieve them using this routine.

          First set up the kernel pool specification of the strings
          as shown here:

                SPK_FILES = ( 'this_is_the_full_path_specification_*'
                              'of_a_file_with_a_long_name'
                              'this_is_the_full_path_specification_*'
                              'of_a_second_file_with_a_very_long_*'
                              'name' )

          Now to retrieve and load the SPK_FILES one at a time,
          exercise the following loop.

             #include <stdio.h>
             #include <string.h>
             #include "SpiceUsr.h"
                 .
                 .
                 .
             #define FILSIZ          255

             SpiceBoolean            found;

             SpiceChar               file [ FILSIZ ];

             SpiceInt                handle;
             SpiceInt                i;
             SpiceInt                size;

             i = 0;

             stpool_c ( "SPK_FILES", i, "*", FILSIZ, file, &size, &found );

             while (  found  &&  ( strlen(file) == size )  )
             {
                spklef_c ( file, &handle );

                i++;

                stpool_c ( "SPK_FILES",  i,      "*",    FILSIZ,
                           file,         &size,  &found          );
             }

             if (  found  &&  ( strlen(file) != size )  )
             {
                printf ( "The %d th file name was too long\n", i );
             }

       Example 2. Retrieving all components as a string.

       Occasionally, it may be useful to retrieve the entire
       contents of a kernel pool variable as a single string.  To
       do this you can use the blank character as the
       continuation character.  For example if you place the
       following assignment in a text kernel

           COMMENT = (  'This is a long note '
                        ' about the intended '
                        ' use of this text kernel that '
                        ' can be retrieved at run time.' )

       you can retrieve COMMENT as single string via the call below. Here
       LENOUT is the declared length of commnt.

          stpool_c ( "COMMENT", 1, " ", commnt, LENOUT, &size, &found );

       The result will be that commnt will have the following value.

          commnt == "This is a long note about the intended use of "
                    "this text kernel that can be retrieved at run "
                    "time. "

       Note that the leading blanks of each component of COMMENT are
       significant; trailing blanks are not significant.

       If COMMENT had been set as

           COMMENT = (  'This is a long note '
                        'about the intended '
                        'use of this text kernel that '
                        'can be retrieved at run time.' )

       Then the call to stpool_c above would have resulted in several
       words being run together as shown below.

          commnt == "This is a long noteabout the intendeduse of "
                    "this text kernel thatcan be retrieved at run "
                    "time. "

       resulted in several words being run together as shown above.
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman    (JPL)
       W.L. Taber      (JPL)
#### Version
       -CSPICE Version 1.2.0, 06-SEP-2004 (NJB)

          Bug fix: added CHKOSTR call to check output string pointer
          and length.  Made some minor header updates.

       -CSPICE Version 1.1.0, 06-MAY-2003 (NJB)

          Bug fix:  removed extra #include statement referencing
          SpiceZfc.h.

       -CSPICE Version 1.0.1, 10-JUN-2001 (NJB)

          Header was corrected:  kernel variable assignments were shown
          using double quotes; these have been changed to single quotes.

          Various instances of the '=' operator were replaced with the
          '==' operator in comments where the intent was to indicate
          equality of two items.

       -CSPICE Version 1.0.0, 10-JUN-1999 (NJB) (WLT)
#### Index_Entries
       Retrieve a continued string value from the kernel pool
#### Link to routine stpool_c source file stpool_c.c

    Wed Jun  9 13:05:31 2010