Procedure

     LDPOOL ( Load variables from a kernel file into the pool )

     ENTRY LDPOOL ( FNAME )

Abstract

     Load the variables contained in a NAIF ASCII kernel file into the
     kernel pool.

Required_Reading

     KERNEL

Keywords

     CONSTANTS
     FILES

Declarations

    CHARACTER*(*)         FNAME

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     FNAME      I   Name of the text kernel file.

Detailed_Input

     FNAME    is the name of the text kernel file whose variables will
              be loaded into the pool.

Detailed_Output

     None.

Parameters

     None.

Exceptions

     1)  If an I/O error occurs while opening or reading a text kernel,
         the error is signaled by a routine in the call tree of this
         routine.

     2)  If any text kernel parsing error occurs, the error is signaled
         by a routine in the call tree of this routine.

     3)  If a kernel pool overflow is detected, an error is signaled by
         a routine in the call tree of this routine.

Files

     See FNAME in $Detailed_Input.

Particulars

     None.

Examples

     The numerical results shown for this example may differ across
     platforms. The results depend on the SPICE kernels used as
     input, the compiler and supporting libraries, and the machine
     specific arithmetic implementation.

     1) The following program demonstrates how to load the variables
        contained in a NAIF ASCII kernel file into the kernel pool
        and how to determine the properties of a stored kernel
        variable.

        The program prompts for text kernel name and for the name of
        a kernel variable. If the variable is present in the kernel
        pool, the dimension and type of the variable are displayed.


        Example code begins here.


              PROGRAM LDPOOL_EX1
              IMPLICIT NONE

        C
        C     SPICELIB functions
        C
              INTEGER               RTRIM

        C
        C     Local constants
        C
              INTEGER               FILSIZ
              PARAMETER           ( FILSIZ = 256 )

              INTEGER               KVNMLN
              PARAMETER           ( KVNMLN = 33 )

        C
        C     Local variables
        C
              CHARACTER*(FILSIZ)    FNAME
              CHARACTER*(KVNMLN)    VARNAM
              CHARACTER*(1)         VTYPE

              INTEGER               N

              LOGICAL               FOUND

        C
        C     Prompt for the name of a text-kernel file.
        C
              CALL PROMPT ( 'Enter text-kernel name        > ', FNAME )

        C
        C     Load the kernel. The same operation could be done using
        C     a FURNSH call.
        C
              CALL LDPOOL ( FNAME )

              CALL PROMPT ( 'Enter name of kernel variable > ',
             .               VARNAM )

              CALL DTPOOL ( VARNAM, FOUND, N, VTYPE )

              IF ( FOUND ) THEN
                 WRITE(*,*) ' '
                 WRITE(*,*) 'Properties of variable ',
             .               VARNAM(:RTRIM(VARNAM)), ':'
                 WRITE(*,*) ' '
                 WRITE(*,*) '   Size:   ', N

                 IF ( VTYPE .EQ. 'C' ) THEN

                    WRITE(*,*) '   Type:   Character'

                 ELSE

                    WRITE(*,*) '   Type:   Numeric'
                 END IF

              ELSE

                 WRITE(*,*) VARNAM,
             .              ' is not present in the kernel pool.'

              END IF

              END


        When this program was executed on a Mac/Intel/gfortran/64-bit
        platform, using the PCK file gm_de431.tpc to ask for the
        variable 'BODY000_GMLIST', the output was:


        Enter text-kernel name        > gm_de431.tpc
        Enter name of kernel variable > BODY000_GMLIST

         Properties of variable BODY000_GMLIST:

            Size:             65
            Type:   Numeric

Restrictions

     1)  Normally SPICE applications should load kernels via the
         FURNSH routine.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     H.A. Neilan        (JPL)
     B.V. Semenov       (JPL)
     W.L. Taber         (JPL)
     R.E. Thurman       (JPL)
     I.M. Underwood     (JPL)

Version

    SPICELIB Version 8.3.0, 17-AUG-2021 (JDR)

        Changed input argument name KERNEL to FNAME for consistency
        with other routines.

        Edited the header to comply with NAIF standard.
        Added complete code example.

    SPICELIB Version 8.2.0, 30-JUL-2013 (BVS)

        Updated to increment POOL state counter.

    SPICELIB Version 8.1.0, 19-MAR-2009 (NJB)

        Watcher update code was re-written for compatibility
        with new watcher system implementation.

        Filled out $Exceptions section of header, which previously
        contained only the word "None."

        Updated code example to use TXTOPN.

    SPICELIB Version 8.0.0, 04-JUN-1999 (WLT)

        Added the entry points PCPOOL, PDPOOL and PIPOOL to allow
        direct insertion of data into the kernel pool without having
        to read an external file.

        Added the interface LMPOOL that allows SPICE
        programs to load text kernels directly from memory
        instead of requiring a text file.

        Added the entry point SZPOOL to return kernel pool definition
        parameters.

        Added the entry point DVPOOL to allow the removal of a variable
        from the kernel pool.

        Added the entry point GNPOOL to allow users to determine
        variables that are present in the kernel pool

    SPICELIB Version 7.0.0, 20-SEP-1995 (WLT)

        The implementation of the kernel pool was completely redone
        to improve performance in loading and fetching data. In
        addition the pool was upgraded so that variables may be
        either string or numeric valued.

        In addition much greater error checking is performed on
        the input file to guarantee valid inputs.

    SPICELIB Version 6.0.0, 31-MAR-1992 (WLT)

        The entry points SWPOOL and CVPOOL were added.

    SPICELIB Version 5.0.0, 22-AUG-1990 (NJB)

        Increased value of parameter MAXVAL to 5000 to accommodate
        storage of SCLK coefficients in the kernel pool.

    SPICELIB Version 4.0.0, 12-JUN-1990 (IMU)

        All entry points except POOL and CLPOOL now initialize the
        pool if it has not been done yet.

    SPICELIB Version 3.0.0, 23-OCT-1989 (HAN)

        Added declaration of FAILED. FAILED is checked in the
        DO-loops in LDPOOL and WRPOOL to prevent infinite looping.

    SPICELIB Version 2.0.0, 18-OCT-1989 (RET)

        A FAILED test was inserted into the control of the DO-loop
        which reads in each kernel variable in LDPOOL.

    SPICELIB Version 1.2.0, 09-MAR-1989 (HAN)

        Parameters BEGDAT and BEGTXT have been moved into the
        $Declarations section.

    SPICELIB Version 1.1.0, 16-FEB-1989 (IMU) (NJB)

        Parameters MAXVAR, MAXVAL, MAXLEN moved into $Declarations.
        (Actually, MAXLEN was implicitly 32 characters, and has only
        now been made an explicit---and changeable---limit.)

        Declaration of unused function FAILED removed.

    SPICELIB Version 1.0.0, 08-JAN-1989 (IMU)