prompt_c

Index Page prompt_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
       SpiceChar * prompt_c ( ConstSpiceChar * prmptStr,
                              SpiceInt         lenout,
                              SpiceChar      * buffer )
#### Abstract
       This function prompts a user for keyboard input.
#### Required_Reading
       None.
#### Keywords
       UTILITY
#### Brief_I/O
       Variable  I/O  Description
       --------  ---  --------------------------------------------------
       prmptStr   I   The prompt string to display when asking for input.
       lenout     I   Minimum number of characters for response plus one.
       buffer     O   The string containing the response typed by a user.

       The routine also returns a pointer to the output buffer.
#### Detailed_Input
       prmptStr   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 prmptStr
                  are considered significant and will be displayed.

       lenout     The integer number of characters plus one for the
                  response string.
#### Detailed_Output
       buffer     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 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 error SPICE(STRINGTOOSHORT) is
          signaled and a null pointer is returned.
#### 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
       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 program illustrates the aquisition of input
       values using prompt_c:

       #include <stdlib.h>
       #include <stdio.h>

       #include "SpiceUsr.h"

       #define   STRLEN    32

       void main()
          {
          SpiceChar    utc    [STRLEN];
          SpiceChar    obs    [STRLEN];
          SpiceChar    targ   [STRLEN];
          SpiceChar  * utc1;
          SpiceChar  * obs1;
          SpiceChar  * targ1;

          /. Call the routine as a subroutine. ./

          prompt_c ( "Enter UTC epoch             > ", STRLEN, utc  );
          prompt_c ( "Enter observer name         > ", STRLEN, obs  );
          prompt_c ( "Enter target name           > ", STRLEN, targ );

          /. Or call the routine as a function. ./

          utc1   = ( SpiceChar * ) malloc (STRLEN);
          obs1   = ( SpiceChar * ) malloc (STRLEN);
          targ1  = ( SpiceChar * ) malloc (STRLEN);

          utc1 = prompt_c ( "Enter UTC epoch        > ", STRLEN, utc1 );
          obs1 = prompt_c ( "Enter observer name    > ", STRLEN, obs1 );
          targ1= prompt_c ( "Enter target name      > ", STRLEN, targ1);

          /.
          Now do stuff with your strings.
          ./

            ...

          }
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman    (JPL)
       K.R. Gehringer  (JPL)
       W.L. Taber      (JPL)
       E.D. Wright     (JPL)
#### Version
       -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

    Thu Apr 16 08:58:52 2009