Index of Functions: A B C D E F G H I J K L M N O P Q R S T U V W X
Index Page prompt_c

Table of contents

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

       prompt_c ( Prompt a user for a string )

       SpiceChar * prompt_c ( ConstSpiceChar * dspmsg,
                              SpiceInt         buflen,
                              SpiceChar      * buffer )

#### Abstract

       Prompt a user for keyboard input.

#### Required_Reading

       None.

#### Keywords

       UTILITY

#### Brief_I/O

       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       dspmsg     I   The prompt string to display when asking for input.
       buflen     I   Minimum number of characters for response plus one.
       buffer     O   The string containing the response typed by a user.

       The routine returns a pointer to the output buffer.

#### Detailed_Input

       dspmsg      is a character string displayed from the current cursor
                   position which describes the requested input. The prompt
                   string should be relatively short, i.e., 50 or fewer
                   characters, so a response may be typed on the line where
                   the prompt appears.

                   All characters (including trailing blanks) in `dspmsg'
                   are considered significant and will be displayed.

       buflen      is the integer number of characters plus one for the
                   response string.

#### Detailed_Output

       buffer      is the user supplied string which holds the response. The
                   string's memory is allocated in the calling routine.

       The routine returns a pointer to buffer as well as passing the
       pointer back via an argument.

#### Parameters

       None.

#### Exceptions

       1)  If the `buffer' output string pointer is null, the error
           SPICE(NULLPOINTER) is signaled.

       2)  If the `buffer' output string has length less than two
           characters, the error SPICE(STRINGTOOSHORT) is signaled.

#### Files

       None.

#### Particulars

       This is a utility that allows you to "easily" request information
       from a program user. The calling program declares an array or
       allocate memory to contain the user's response to the prompt.

#### Examples

       The numerical results shown for these examples 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) Suppose you have an interactive program that computes state
          vectors by calling spkezr_c. The program prompts the user for
          the inputs to spkezr_c. After each prompt is written, the program
          leaves the cursor at the end of the string as shown here:

             Enter UTC epoch  > _

          (The underscore indicates the cursor position).

          The following code example illustrates the acquisition of input
          values using prompt_c as a void function.

          Use the meta-kernel shown below to load the required SPICE
          kernels.

             KPL/MK

             File: prompt_ex1.tm

             This meta-kernel is intended to support operation of SPICE
             example programs. The kernels shown here should not be
             assumed to contain adequate or correct versions of data
             required by SPICE-based user applications.

             In order for an application to use this meta-kernel, the
             kernels referenced here must be present in the user's
             current working directory.

             The names and contents of the kernels referenced
             by this meta-kernel are as follows:

                File name                        Contents
                ---------                        --------
                de430.bsp                        Planetary ephemeris
                mar097.bsp                       Mars satellite ephemeris
                naif0011.tls                     Leapseconds

             \begindata

                KERNELS_TO_LOAD = ( 'de430.bsp',
                                    'mar097.bsp',
                                    'naif0011.tls' )

             \begintext

             End of meta-kernel

          Example code begins here.

          /.
             Program prompt_ex1
          ./
          #include <stdlib.h>
          #include <stdio.h>
          #include "SpiceUsr.h"

          int main()
          {
             /.
             Local parameters
             ./
             #define   STRLEN    37

             /.
             Local variables.
             ./
             SpiceChar      utc    [STRLEN];
             SpiceChar      obs    [STRLEN];
             SpiceChar      targ   [STRLEN];

             SpiceDouble    et;
             SpiceDouble    lt;
             SpiceDouble    state [6];

             /.
             Load kernel.
             ./
             furnsh_c ( "prompt_ex1.tm" );

             /.
             Prompt for the required inputs
             ./
             prompt_c ( "Enter UTC epoch             > ", STRLEN, utc  );
             prompt_c ( "Enter observer name         > ", STRLEN, obs  );
             prompt_c ( "Enter target name           > ", STRLEN, targ );

             /.
             Convert the UTC request time to ET (seconds past
             J2000, TDB).
             ./
             str2et_c ( utc, &et );

             /.
             Look up the state vector at the requested `et'
             ./
             spkezr_c ( targ, et, "J2000",  "NONE", obs, state, &lt );

             printf( "\nEpoch               : %22.10f\n", et     );
             printf( "   x-position   (km): %22.10f\n", state[0] );
             printf( "   y-position   (km): %22.10f\n", state[1] );
             printf( "   z-position   (km): %22.10f\n", state[2] );
             printf( "   x-velocity (km/s): %22.10f\n", state[3] );
             printf( "   y-velocity (km/s): %22.10f\n", state[4] );
             printf( "   z-velocity (km/s): %22.10f\n", state[5] );

             return ( 0 );

          }

          When this program was executed on a Mac/Intel/cc/64-bit
          platform, using the time string "2017-07-14T19:46:00" as epoch,
          "MARS" as target and "EARTH" as observer, the output was:

          Enter UTC epoch             > 2017-07-14T19:46:00
          Enter observer name         > MARS
          Enter target name           > EARTH

          Epoch               :   553333628.1837273836
             x-position   (km):   173881563.8231496215
             y-position   (km):  -322898311.5398598909
             z-position   (km):  -147992421.0068917871
             x-velocity (km/s):          47.4619819770
             y-velocity (km/s):          19.0770886182
             z-velocity (km/s):           7.9424268278

       2) The following code example illustrates the acquisition of input
          values using prompt_c as a non-void function.

          Use the meta-kernel from the first example.

          Example code begins here.

          /.
             Program prompt_ex2
          ./
          #include <stdlib.h>
          #include <stdio.h>
          #include "SpiceUsr.h"

          int main()
          {
             /.
             Local parameters
             ./
             #define   STRLEN    37

             /.
             Local variables.
             ./
             SpiceChar    * utc;
             SpiceChar    * obs;
             SpiceChar    * targ;

             SpiceDouble    et;
             SpiceDouble    lt;
             SpiceDouble    state [6];

             /.
             Load kernels.
             ./
             furnsh_c ( "prompt_ex1.tm" );

             /.
             Allocate memory to each of the input variables.
             ./
             utc   = ( SpiceChar * ) malloc (STRLEN);
             obs   = ( SpiceChar * ) malloc (STRLEN);
             targ  = ( SpiceChar * ) malloc (STRLEN);

             /.
             Prompt for the required inputs
             ./
             utc  = prompt_c ( "Enter UTC epoch        > ", STRLEN, utc  );
             obs  = prompt_c ( "Enter observer name    > ", STRLEN, obs  );
             targ = prompt_c ( "Enter target name      > ", STRLEN, targ );

             /.
             Convert the UTC request time to ET (seconds past
             J2000, TDB).
             ./
             str2et_c ( utc, &et );

             /.
             Look up the state vector at the requested `et'
             ./
             spkezr_c ( targ, et, "J2000",  "NONE", obs,  state,  &lt );

             printf( "\nEpoch               : %22.10f\n", et     );
             printf( "   x-position   (km): %22.10f\n", state[0] );
             printf( "   y-position   (km): %22.10f\n", state[1] );
             printf( "   z-position   (km): %22.10f\n", state[2] );
             printf( "   x-velocity (km/s): %22.10f\n", state[3] );
             printf( "   y-velocity (km/s): %22.10f\n", state[4] );
             printf( "   z-velocity (km/s): %22.10f\n", state[5] );

             return ( 0 );

          }

          When this program was executed on a Mac/Intel/cc/64-bit
          platform, using the time string "2017-07-14T19:46:00" as epoch,
          "MARS" as target and "EARTH" as observer, the output was:

          Enter UTC epoch        > 2017-07-14T19:46:00
          Enter observer name    > MARS
          Enter target name      > EARTH

          Epoch               :   553333628.1837273836
             x-position   (km):   173881563.8231496215
             y-position   (km):  -322898311.5398598909
             z-position   (km):  -147992421.0068917871
             x-velocity (km/s):          47.4619819770
             y-velocity (km/s):          19.0770886182
             z-velocity (km/s):           7.9424268278

#### Restrictions

       None.

#### Literature_References

       None.

#### Author_and_Institution

       N.J. Bachman        (JPL)
       J. Diaz del Rio     (ODC Space)
       E.D. Wright         (JPL)

#### Version

       -CSPICE Version 1.1.0, 13-AUG-2021 (JDR)

           Changed the input argument names "prmptStr" and "lenout" to
           "dspmsg" and "buflen" for consistency with other routines.

           Updated -Exceptions section to include missing exceptions.

           Edited the header to comply with NAIF standard. Converted the
           existing code fragments into complete examples and added required
           meta-kernel and inputs to produce the presented solution.

       -CSPICE Version 1.0.0, 25-JUN-1999 (EDW) (NJB)

#### Index_Entries

       Prompt for keyboard input
       Prompt for input with a user supplied message

#### Link to routine prompt_c source file prompt_c.c

    Fri Dec 31 18:41:10 2021