Click above to get retro games delivered to your door ever month!

##############################################################################
###+-----+####################################################################
#+-| GET |--------------------------------------+#############################
#| +-----+ The GET subcommand converts variable |#############################
#|         data into a character string         |#############################
#+----------------------------------------------+#############################
##############################################################################
##############################################################################
#+--| Syntax |-----------------------------------------------------+##########
#|     @<Int-exp,Int-exp> GET <C-exp> [PICTURE <C-exp>             |##########
#|     || FUNCTION <C-exp>] [VALID <L-exp>] [FILTER <Uint-exp>]    |##########
#|     [ ID <Uint-exp> ]                                           |##########
#+-----------------------------------------------------------------+##########
##############################################################################
##############################################################################
#######+---| Description |--------------------------------------------+#######
#######| The GET subcommand converts variable data into a character   |#######
#######| string, displays the string and puts an entry in the READ    |#######
#######| table.  The GET subcommand displays a string using the same  |#######
#######| format rules as the SAY subcommand, execpt:                  |#######
#######|                                                              |#######
#######|  *  If the string exceeds one line, then GET wraps it to the |#######
#######|     next row.  The column position of the next row will be   |#######
#######|     the starting position of the previous row.  SAY always   |#######
#######|     starts the next row at column position 0.                |#######
#######|                                                              |#######
#######|  *  The GET subcommand bypasses the device selected in the   |#######
#######|     SET DEVICE TO command.                                   |#######
#######|                                                              |#######
#######|  *  GET desplays characters with attributes set from the     |#######
#######|     enhanced display string of the SET COLOR TO command.     |#######
#######|     SAY displays characters with attributes set from the     |#######
#######|     standard display string of the SET COLOR TO command.     |#######
#######|                                                              |#######
#######|  *  GET templates are used in GET picture string.  GET       |#######
#######|     functions are used in GET picture and function strings.  |#######
#######| ------------------------------------------------------------ |#######
#######| GETs with <Uint> variables accept negative numbers.  The     |#######
#######| value accepted will be altered by simple sign extension.     |#######
#######| A VALID clause may be used to prevent entry of negative      |#######
#######| values.                                                      |#######
#######| ------------------------------------------------------------ |#######
#######| Global, private, local or field variables may be used in a   |#######
#######| GET subcommand.  If a GET is issued for a local variable,    |#######
#######| a WARNING error is generated by the compiler.  You are       |#######
#######| warned because the subsequent READ command must be issued    |#######
#######| within the scope of the local variable.                      |#######
#######| for example, this code will not work:                        |#######
#######|                                                              |#######
#######|      PROCEDURE setup_gets                                    |#######
#######|          VARDEF                                              |#######
#######|              CHAR    variable_name                           |#######
#######|          ENDDEF                                              |#######
#######|          @ x,y GET variable_name                             |#######
#######|      ENDPRO                                                  |#######
#######|                                                              |#######
#######|      PROCEDURE read_gets                                     |#######
#######|          DO setup_gets                                       |#######
#######|          READ                                                |#######
#######|          {...}                                               |#######
#######|                                                              |#######
#######| This is because the READ is issued when the variable         |#######
#######| variable_name does not exist.                                |#######
#######+--------------------------------------------------------------+#######
##############################################################################
##############################################################################
######+---------------------------| NOTE: |----------------------------+######
######| Compiler WARNINGS are designed to inform you about a condition |######
######|   which MIGHT cause an error.  You must make a decision about  |######
######|     whether the warning error is relevant to your program.     |######
######|  Y O U   M A Y   I G N O R E   A   W A R N I N G   E R R O R.  |######
######+----------------------------------------------------------------+######
##############################################################################
##############################################################################
########+-------------------------------------------------------------+#######
########| The PICTURE and FUNCTION template and function symbols      |#######
########| have dual meaning.  The GET subcommand outputs information  |#######
########| already in a variable, and accepts and formats input.       |#######
########| ----------------------------------------------------------- |#######
########| GET<Function-symbol>s are shown in the GET FUNCTION DISPLAY |#######
########| TABLE and GET FUNCTION READ TABLE.                          |#######
########| ----------------------------------------------------------- |#######
########| GET<Template-symbol>s are shown in the GET TEMPLATE DISPLAY |#######
########| TABLE and the GET TEMPLATE READ TABLE.                      |#######
########+-------------------------------------------------------------+#######
##############################################################################
##############################################################################
#########+--| Example 1 |-------------------------------------------+#########
#########| *    One @ command will:                                 |#########
#########| *    1) Locate the cursor to row 0, column 0             |#########
#########| *    2) Display a prompt with the SAY subcommand.        |#########
#########| *    3) Display the current contents of a field          |#########
#########| *       and insert an "element" into the READ            |#########
#########| *       table with the GET subcommand.                   |#########
#########|                                                          |#########
#########| @ 0,0 SAY "Enter data: " GET dbf->data                   |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 2 |-------------------------------------------+#########
#########| *    A GET may have a VALID function.  The               |#########
#########| *    specified function must be LOGICAL.                 |#########
#########|                                                          |#########
#########| @ 3,2 GET radio->request VALID check_rqst()              |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 3 |-------------------------------------------+#########
#########| *    A GET may have an optional attached ID.  The ID     |#########
#########| *    is a number assigned to the GET which facilitates   |#########
#########| *    context sensitive functions - i.e., help.           |#########
#########| *    In this example, two GETS are issued, each with     |#########
#########| *    a different ID.  The ID is queried through the      |#########
#########| *    get_id() function.                                  |#########
#########|                                                          |#########
#########| #include keys.hdr                                        |#########
#########| FUNCTION UINT key_filter                                 |#########
#########|     VARDEF                                               |#########
#########|         INT   k                 && last key pressed      |#########
#########|     ENDDEF                                               |#########
#########|                                                          |#########
#########|     k = lastkey()                                        |#########
#########|     IF k = &K_F1                && user wants help?      |#########
#########|         !help GOTO get_id()     && goto the help         |#########
#########|                                 && record in our         |#########
#########|                                 && help database.        |#########
#########|                                                          |#########
#########|     *--- just display the help through m_edit()          |#########
#########|                                                          |#########
#########|         m_edit( help->m, r, c, r1, c1, .T.)              |#########
#########|                                                          |#########
#########|     *--- Loop until a key is pressed                     |#########
#########|                                                          |#########
#########|          REPEAT                                          |#########
#########|          UNTIL is_key() <> 0                             |#########
#########|          k = 0                  && return 0 to inform    |#########
#########|                                 && the READ  to get      |#########
#########|                                 && another key.          |#########
#########|     ENDIF                                                |#########
#########|     RETURN k                                             |#########
#########| ENDPRO                                                   |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 4 |-------------------------------------------+#########
#########| *    GET a telephone number.  Upon keyboard input        |#########
#########| *    after the READ command, cursor will not             |#########
#########| *    position itself over the "(", ")"                   |#########
#########| *    and "-" characters.                                 |#########
#########|                                                          |#########
#########| @ 10,10 GET dbf->phone PICTURE "(999)-999-9999"          |#########
#########| READ                                                     |#########
#########+----------------------------------------------------------+#########
##############################################################################