Class
Screen Forms

Purpose
Data entry

Syntax
@ <expN1>,<expN2> GET <memvar> | <field>
[BUTTON <expC1> [LABEL <expC2>] [GROUP <expC3>] [HELP <expC4>] [TRIGGER <expC5>]]
[CALCULATE]
[CALCULATED BY <expr1>]
[CHOICELIST <expC6>]
[COLOR <color> | COLOR SCHEME <expN3>]
[DEFAULT <expr2>]
[DISABLE | ENABLE]
[ERROR <expC7>]
[FONT <expC8>[, <expN4>]]
[FUNCTION <expC9> | PICTURE <expC10>]
[HELP <expC11> | MESSAGE <expC12>]
[LOOKUP IN <alias>]
[MUST_ENTER]
[NAME <expC13>]
[NOECHO]
[POSTFIELD <program | procedure>]
[PREFIELD <program | procedure>]
[PROPERTIES <expC14>]
[RANGE <expr3>,<expr4>]
[READ_ONLY [IF <expL1>] | WHEN <expL2>]
[RELATION [INTO <alias>]
[VALID <expL3> | <expN5> | IN <expC14> | VALIDATE WITH <program | procedure>]

See Also
@...BOX, @...CLEAR, @...FILL, @...MENU, @...PROMPT, @...SAY, @...SCROLL, @...TO, APPEND, CHANGE, CLEAR GETS, CREATE SCREEN, EDIT, FUNCTION, INSERT, MENU AT, SAVE GETS, SHOW GETS, READ, USE, ROW(), COL(), SET UPDATE, SET QUERYMODE, SET CONFIRM, SET FORMAT, DB_NOCALCULATOR, DB_NOCALENDAR

The Recital Forms Designer can be used to create data entry forms containing @…GET commands.  See CREATE SCREEN for full details.

When a READ command is issued, all GETS which have been processed since the last READ or CLEAR GETS command become active.

<expN1>,<expN2>
The <expN1>, <expN2> are numeric expressions specifying the row and column coordinates.  Row numbers start at 0 and are incremented from top to bottom.  Column numbers start at 0 and are incremented from left to right.

<memvar> | <field>
@...GET creates an editing region for the memory variable or array element specified in <memvar> or the field specified in < field>.  Fields in open tables in other (not currently selected) workareas must be prefixed with an alias pointer.  An alias pointer is an alias name followed by the symbol ‘.’ or ‘->’.  Fields have precedence over memory variables with the same name.  Memory variables having the same name as a field in the active table file must be prefixed by a memory variable alias pointer: ‘m.’ or ‘m->’.

@…GET <memvar> | <field> BUTTON <expC1>
[LABEL <expC2>]
[GROUP <expC3>]
[HELP <expC4>]
[TRIGGER <expC5>]
The optional BUTTON keyword is used to define the <memvar> | <field> as a check box or radio button. Check boxes correspond to logical fields or memory variables and can be selected or deselected using the [SPACEBAR].  When a check box is selected, its corresponding <memvar> or <field> is set to true (.T.).  When it is deselected, its corresponding <memvar> or <field> is set to False (.F.).  The check box edit region is represented by square brackets: [ ].  When a check box is deselected, the brackets are empty, when the check box is selected an asterisk is displayed inside the brackets.

Radio buttons form groups, whereby each radio button corresponds to a possible value <expC1> for a character field or memory variable.  Only one radio button may be selected at any one time, since this signifies the <memvar> or <field> value.  The radio button edit region is represented by round brackets: ( ).  When a radio button is deselected, the brackets are empty, when the radio button is selected, an asterisk is displayed inside the brackets.

The optional LABEL <expC2> keyword specifies a label for the check box or radio button.  If no LABEL is specified, the character expression specified in the BUTTON clause is used.

The GROUP <expC3> keyword is used to group radio buttons.  Each radio button that you specify in a group of radio buttons must be given the same GROUP <expC3>.

The optional HELP <expC4> keyword specifies a message that will appear in the message line of the screen when the cursor moves onto the check box or radio button.

The optional TRIGGER <expC5> keyword specifies the name of an event driven procedure to be called when the button is selected or deselected.  The TRIGGER procedure is called with the following three parameters:

CALCULATE
Whenever data is input into an @…GET, which has CALCULATE specified, all of the CALCULATED BY <expr> @…GETS are recalculated and redisplayed.

CALCULATED BY <expr1>
Used to calculate and display the expression in the @...GET edit region.  The expression is calculated when the @...GET is first activated, or when data is entered in another active GET which has the CALCULATE clause.  Any valid expression may be used (including User Defined Functions).  The CALCULATED BY clause makes the @...GET read only.

CHOICELIST <expC6>
The optional CHOICELIST <expC6> keyword allows a pop-up choicelist or a User Defined Function (UDF) to be associated with an @...GET when the [HELP] key is pressed. The CHOICELIST <expC6> can be in one of the following three forms:

A static choicelist made up of a series of character expressions separated by commas: <expCi> [,<expCii>].... Each set of characters between the commas becomes a separate menu option. This choicelist is non-scrollable and can take up to 19 options.

A dynamic choicelist made up of records from tables other than the current table: "@<alias>,<expC>". The <alias> can refer to a workarea or to a table in the current directory. If the table is not opened it will automatically be opened and then closed again once a selection has been made. The <expC> must include a reference to at least one field in the <alias> table. The <expC> can also include literal values and alias pointers to related tables. The dynamic choicelist is scrollable with the [NEXT SCREEN], [PREVIOUS SCREEN] and [ARROW] keys. The [FIND] key can also be used to find menu items in the <alias> table being browsed. When the [FIND] key is selected, a popup DIALOG GET box is displayed, allowing the search string to be entered. If the <alias> table is indexed, a SEEK will be performed. If not, a LOCATE FOR will be performed. A filter condition may be defined on the <alias> table specified in the choicelist to limit the records that will appear as menu items.

A UDF can be used to return a character expression to be placed in the field. To specify a UDF to execute when the [HELP] key is pressed, the UDF name is prefixed with a question mark (?). For example:

@10,3 get account_name;
choicelist "?helpproc()"

The CHOICELIST option can only be used on character fields/variables. There are default help objects on dates (calendar), numerics (calculator), memos (editor) and logicals (fixed choicelist). If a popup choicelist is required on non-character fields/variables, this can be achieved using the VALIDATE WITH clause in combination with one of the many MENU commands. If the VALIDATE WITH option is used, the CHOICELIST option will be ignored. The CHOICELIST specified on an @...GET will override any pre-defined Applications Data Dictionary choicelist.

COLOR <color code> | COLOR SCHEME <expN3>
The color of @...GET output can be specified by including a set of color pairs in the COLOR clause or specifying a numeric COLOR SCHEME <expN3>.  If you do not specify the COLOR | COLOR SCHEME clause then the @...GET is displayed in the default Color of Fields.  The color that is specified overrides the SET COLOR command, but only for the output of the current @…GET command.

DEFAULT <expr2>
The DEFAULT clause is included for FoxPro compatibility.

DISABLE | ENABLE
If the DISABLE clause is included, the GET is not active and cannot be selected or modified. GETs are enabled by default. READ will exit immediately if all GETs are marked DISABLE.

ERROR <expC7>
The optional ERROR <expC7> keyword causes an error message to be displayed if LOOKUP IN, RELATION, VALIDATE WITH or the VALID <condition> fail.  The error message <expC7> is displayed in an ALERT message box, and can be a maximum of 80 characters in length.

FONT <expC8>[, <expN4>]
The name of the font is specified in <expC8> and, optionally, the font size in <expN4>.

FUNCTION | PICTURE
The optional PICTURE or FUNCTION clause allows for specialized formatting to be performed on the data before it is input or output.  It causes each individual character entered in the field to be validated as it is entered.

FUNCTION codes can be included in a PICTURE clause.  In this case, the PICTURE clause must start with @.  Since a FUNCTION clause affects the entire expression, it can only contain FUNCTION codes.

A PICTURE template can include any characters, but only valid picture codes affect the editing, any other value is stored in the data.  Each Picture Code applies to the character at that position only, not to the entire input.

HELP <expC11> | MESSAGE <expC12>
The HELP and MESSAGE clauses are synonymous.  The character expression <expC11> or <expC12>, of up to 80 characters in length, is displayed in the message line when the @...GET has focus.

LOOKUP IN <alias>
The LOOKUP IN clause defines a validity check using a cross-table lookup.  The alias name of the lookup table must be specified as <alias>.  Changing the field value causes the lookup table to be scanned for the new value.  If the value does not exist in the lookup table, a validation failed error message is displayed.  See ERROR for user-defined error messages.

MUST_ENTER
The MUST_ENTER clause is used to enforce data entry in empty GETS.  You cannot commit any changes until the GET with a MUST_ENTER clause has had data entered into it.

NAME <expC13> (Recital Mirage only)
The NAME clause is used to create a 'wrapper' object for the GET. The <expC13> must be a unique name for the current READ. Once defined, the NAME clause allows properties to be set and methods to be called on the client for that GET. For additional information on object properties and methods, please see the Recital Mirage documentation.

NOECHO
The NOECHO option is used to disable the echoing of the input characters.  It is particularly useful for entering passwords.  As each character is entered, “*” is displayed.

POSTFIELD <program | procedure>
The POSTFIELD clause is used to specify a procedure name for the POSTFIELD trigger.  The POSTFIELD trigger procedure is called as the field is exited.

PREFIELD <program | procedure>
The PREFIELD clause is used to specify a procedure name for the PREFIELD trigger.  The PREFIELD trigger procedure is called as the field is entered.

PROPERTIES <expC14> (Recital Mirage only)
The PROPERTIES clause can be used to specify properties for the specified get. For information on the available properties, please see the Recital Mirage documentation.

RANGE<expr3>,<expr4>
The RANGE option can be specified for numeric or date fields.  The lowest value is represented by <expr3> and the highest value by <expr4>.  Input data is checked to verify that it lies within the specified range.  If it is out of range, a message will be displayed in the message line.

READ_ONLY [IF <expL1>] | WHEN <expL2>
The READ_ONLY option disables editing of the specified GET field.  When this option is used, the contents of the field will be redisplayed as each new record is displayed on the screen.  The optional IF <expL1> can be used to make the field READ_ONLY when the specified <expL1> is true (.T.).  If the <expL1> evaluates to false (.F.), the field can be edited.  The WHEN <expL2> has the same effect, but the opposite syntax.  It is used to make the field read only when the specified <expL2> is false (.F.).

RELATION [INTO <alias>]
The RELATION option causes the data entered in the field to be used as a key field for a related table.  The key is searched for in the master index of the specified table, and the record associated with that key read.  The optional INTO <alias> clause specifies the target table.  The INTO <alias> is not needed if relationships have already been established with the SET RELATION command.  When the target table has any relationships to other tables specified with the SET RELATION command, the ‘relationship chain’ is traversed, satisfying the relationships.

VALID <expL3> | <expN5> | IN <expC14>
The VALID clause is used to validate data entry.  When the GET is exited, the validation is called.  If the <expL3> evaluates to true (.T.), the input is considered correct and the editing region is exited.  If it evaluates to false (.F.), the data entered is rejected and a default error message, or the ERROR <expC7> is displayed.  VALID <expL3> cannot be used in conjunction with Application Data Dictionary VALIDATION entries.

The VALID <expN5> option may be used with a function that returns a numeric value to select a GET for input.  GET numbers are assigned in the order that they appear on the screen.  The GETNO() function returns the number of the currently active get.  The numeric value returned can have three different effects.  When <expN5> is 0, the current GET remains in focus.  When <expN5> is positive, the value is used to advance the GET focus the number of GETS specified.  When <expN5> is negative, the value is used to move back the GET focus the number of GETS specified.  VALID <expN5> cannot be used in conjunction with Application Data Dictionary VALIDATION entries.

The VALID IN option causes the input data to be checked against that specified in the character expression <expC14>.  VALID IN is only active with character fields.  It checks that the input data is contained as a sub string in <expC12>.  Note that the <expC12> should consist of multiple strings of the same length as the field.  VALID IN cannot be used in conjunction with the CHOICELIST clause.  The VALID IN clause can be used in conjunction with Application Data Dictionary VALIDATION entries.  The VALID IN check will be evaluated first.

VALIDATE WITH <program | procedure>
The VALIDATE WITH clause causes the specified <program | procedure> to be called, passing the input data as a parameter.  The <program | procedure> must have a PARAMETERS statement with a single parameter defined.  The parameter passed is a character string, regardless of the data type of the field in question.  To signify that the input data has passed the validation checks the command SET VALIDATE ON should be issued.  To reject the input data, the command SET VALIDATE OFF should be issued.  The data itself may be modified using the SET FIELDVAL TO <expC> command.  If the [HELP] key is pressed on a field that has a VALIDATE WITH specified, the <program | procedure> will be called with the parameter of “HELP”.  In this way, default popups and choice lists can be bypassed.  VALIDATE WITH cannot be used in conjunction with the CHOICELIST clause.  The VALIDATE WITH clause can be used in conjunction with Application Data Dictionary VALIDATION entries.  The VALIDATE WITH check will be evaluated first.

Example
@3,3 get m_name;
picture “!XXXXXXXXXX”;
color gr+/b, r/w
read

Products
Recital Mirage Server, Recital Terminal Developer