User Tools

Site Tools


jvs:cigal:manual:chapter3:accept

CIGAL Reference Manual, Chapter 3 (Functions): accept

Accept -- Get data from keyboard, cursor, screen, or current input

usage: variable = accept(prompt_string,default_value,data_type,word_size)
or: variable = accept(prompt_string,default_value,2)
or: variable = {

}

There are two forms of this command. The explicit “Accept” command:

                        variable = accept( ... )

(usually used in macro programs or menus to prompt for user input) and the implicit command:

                        variable = { ... }

(to get data from the current input source). Both versions serve the same purpose: to load data into a data variable.

The explicit ACCEPT command will usually display a prompt and then accept user input. The display and input can either occur within the Command window, in command line mode, or they can appear in a new dialog window created just for that purpose. To get the dialog window, specify 2 as the 3rd function argument (data_type).

The ACCEPT command reads the input data into a temporary variable, which can then be assigned to another variable, or used as an argument to another CIGAL command. For example:

                a1 = accept("enter array values: ")
         or:    read accept("enter filename: ",,STRING)

NOTE: At present ACCEPT may not be used as an argument to another function command (i.e., a command that returns a value– see HELP FUNCTIONS if you are not sure which are the function commands). The arguments to the ACCEPT command are described below.

The second (implicit) form of the command, using the syntax:

                Variable = { ... }
        or,     Variable = {
                 ...
                }

is used to load multi-valued variables (i.e., arrays, matrices, string lists, solids) with input read from the current input source. The keyboard or a macro file is the current input can be either.

For NUMBERs (and STRINGs when WORD_SIZE is 1 – see Note 2 below) only a single word of input is read. For other data types, input is read from the terminal until you enter a blank line (i.e. 2 <ENTERS> in a row) or a line beginning with a “}”.

The size of the temporary variable created by either form of ACCEPT is automatically determined by the number of values entered. If this temporary variable is assigned to another variable of fixed-dimensions, the number of values should match (extra values are ignored, while missing values are undefined.) If the receiving variable does not have memory permanently assigned (see DECLARE) that variable will be resized to match the input data. When reading data into a 2-dimensional variable (i.e., MATRIX or IMAGE) in which dimensions have not been explicitly defined previously, the horizontal dimension will be set to the number of values entered on the first line of data.

ACCEPT Command Arguments:

  ACCEPT arguments are position dependent and are:
     PROMPT_STRING:
        The first argument is an optional character string to be printed as
        a prompt before ACCEPT waits for input.
     
     DEFAULT_VALUE:
        This value will be used as the result if the user does not enter
        data.  It should be of the same type as the target variable.
     
     DATA_TYPE:
        2 - Prompt for input using a Dialog box
     
     WORD_SIZE:
        If you directly assign a data variable do not specify these arguments.
        The type and size of the target data variable will be used as the
        input type.  For example:
                declare array xarray
                xarray = accept("Enter X values: ")
        However, if the ACCEPTed data are not directly assigned to a variable,
        then DATA_TYPE should be explicitly declared to be one of the following:
              NUMBER        MATRIX        VECTOR
              STRING        IMAGE         1 (see Note 1)
              ARRAY         SOLID
        WORD_SIZE can be specified as one of:
              BYTE          INTEGER       LONG          REAL
              BIT           CRUMB         NIBBLE
        If not specified, WORD_SIZE defaults to BYTE for STRING, IMAGE, or
        SOLID data, and to REAL for NUMBER, ARRAY, or MATRIX input.  (See
        [VARIABLES][1] for more on data types and word sizes.)

        For example:
                read accept("Enter filename: ",,string)
        will prompt for a character string and then pass this as the first
        argument to the READ command.

Note 1: DATA_TYPE specified as 1 is a special case. Telling ACCEPT that you are entering a flag variable in response to a yes or no question, the value will be either 0 or 1. In this special case, ACCEPT returns a 1 if the first character you enter is a 1, 'y', or 'Y'; it returns 0 if you enter 0, 'n', or 'N'. If you simply type <ENTER>, ACCEPT will return the default value (0/1) if specified, otherwise it assumes “no” and returns a value of 0. Example:

                flg = accept("Do you want to continue? ",0,1)

Note 2: Entering STRING data and WORD_SIZE specified as 1 or 2 makes the command behave somewhat differently than usual. A WORD_SIZE of 1 means accept only a single word as opposed to a whole line of text. This is most useful when entering data by pointing the cursor at text on the screen, which allows you to enter values with a single key click, rather than highlighting a whole block of text. A WORD_SIZE of 2 means accept many lines of text, until you enter a blank line (i.e., 2 <ENTERs> in a row). You can enter a blank line as part of the text as a line containing only the \ character. Enter text with the cursor as normal when WORD_SIZE is 2.

EXAMPLES:

                declare number x
                declare integer matrix kernal1 kernal2
                x = accept('next value:',-1)
                kernal1 = {
                        1 -1 -1
                        1  1 -1
                        1  1 -1
                }
                kernal2 = accept('enter kernal:')

(This example configures KERNAL1 as a 3×3 matrix; the dimensions of KERNAL2 depend on the number of values entered when executing the command.)

NOTE: Illegal values (e.g. a non-numerical value or blank where a number is expected) are stored as “missing values” (-0) for variables of type INTEGER, LONG, or REAL (they are stored as 0 for BYTE data, which is unsigned). Missing values (-0) are omitted from computations, and appear as '**' when the variable is listed.

See Also:
VARIABLES(1)

CIGAL Home, CIGAL Manual, Functions List, Manual Help

jvs/cigal/manual/chapter3/accept.txt · Last modified: 2014/08/04 16:03 (external edit)