SAS Component Language Dictionary

FIELD

Performs an action on or reports the state of FRAME entry widgets or fields

Category:

Widget or Field

Syntax
Values for the action Argument
Details
Examples
	Example 1: Using FIELD to Allow Smooth Scrolling
	Example 2: Using FIELD to Check for Error Status of Fields
	Example 3: Using FIELD to Turn on an Error Flag
	Example 4: Using FIELD to Change a Field's Color
	Example 5: Using FIELD to Change Color and Display Attributes for a Field
	Example 6: Using FIELD to Specify a SASCOLOR Window Element
See Also

Syntax

rc=FIELD(action<,wvar-name-1<,wvar-name-2
<,wvar-name-3>>>);

rc

contains the return code for the operation. The return value is dependent on the action.

Type: Numeric

action

is an action from the list of actions described in Values for the action Argument.

Type: Character

wvar-name-1, wvar-name-2, wvar-name-3

are character columns or expressions whose values are the names of one or more FRAME entry widgets or fields in a window, separated by spaces. At least one name is required for all actions except ALARM, BLOCKCUROFF, BLOCKCURON, CURSCREEN, HOME, NSCREEN, and SMOOTHSCRL.

Type: Character

Values for the action Argument

The following list contains the values that you can specify for action. The list also includes the corresponding methods that can be used in FRAME entries, which are documented with FRAME entry classes in the online Help for SAS/AF software.

'ALARM'

sounds a bell. This action has a corresponding SCL statement.

'BLOCKCUROFF'

turns the block cursor off so that fields or text entry widgets are not highlighted when a user tabs or moves the cursor to them.

'BLOCKCURON'

turns the block cursor on, which causes input fields to be highlighted when the cursor is on the text entry widget or field.

'COLOR color <attribute>'

changes the color and display attribute of a field, text entry widget, or text label widget in the window. Colors are: BLACK, BLUE, BROWN, CYAN, GRAY, GREEN, MAGENTA, ORANGE, PINK, RED, WHITE, and YELLOW. Attributes are: NONE, BLINKING, HIGHLIGHT, HIREV, REVERSE, and UNDERLINE. SASCOLOR window elements can be used for color. If you specify a SASCOLOR window element for color, then attribute is not allowed, because the SASCOLOR window element already contains a display attribute.

'COLUMN'

returns the column where a FRAME entry widget or field is located. This option is valid only in SAS/AF software. FRAME entry widgets can also use the _column method.

'CUROBS'

returns the current row number for FSEDIT and FSVIEW for the specified field.

'CURSOR'

positions the cursor in the FRAME entry widget or field. If more than one field or widget is specified, the cursor is positioned in the last one specified. This action has a corresponding SCL statement. FRAME entry widgets can also use the _cursor method.

'CURSCREEN'

returns the current screen number. For SAS/AF software, this is valid only for multipage PROGRAM entries. For FSEDIT, it reports which screen of a multiscreen application is displayed.

'DISPLAYED'

returns the total number of FRAME entry widgets or fields that are visible, or 0 if none of them are currently displayed. For example, if you pass three field names and two are visible, then rc is 2. This action has a corresponding SCL function. FRAME entry widgets can also use the _isDisplayed and _isHidden methods.

'ERROR'

returns the total number of FRAME entry widgets or fields that are in error, or 0 if none of the specified fields are in error. For example, if you pass two field names and one is in error, then rc is 1. This action has a corresponding SCL function. FRAME entry widgets can also use the _inError method.

'ERROROFF'

removes the error status from one or more FRAME entry widgets or fields. This action has a corresponding SCL statement. FRAME entry widgets can also use the _erroroff method.

'ERRORON'

turns on the error status for one or more FRAME entry widgets or fields. Turning on the error status prevents users from ending the SAS/AF application or from leaving the current row in FSEDIT. The error status also highlights the field or widget, using the error color and display attributes that were assigned in the Attribute (or ATTR) window. This action has a corresponding SCL statement. FRAME entry widgets can also use the _erroron method.

'GETOBS'

reports whether a formula is being executed in an FSVIEW application because a column is being read. If rc is 1, then the formula is being executed because a column is being read. If rc is 0, then the formula is being executed because a column has been modified. If you are on a new row, rc is always 1. This is the opposite of PUTOBS.

'HOME'

moves the cursor to the command line. This entry has a corresponding SCL statement.

'ICON icon-number'

assigns a number for an icon that represents the field if it is a pushbutton in PROGRAM entries. This option is valid only in SAS/AF software. FRAME entry widgets can use the _setIcon method.

'MODIFIED'

returns the total number of FRAME entry widgets or fields that were modified, or 0 if none of them were modified. For example, if you pass two field names and both were modified, then rc is 2. This action has a corresponding SCL function. FRAME entry widgets can also use the _isModified method.

'NSCREEN'

returns the number of screens (for FSEDIT applications) or the number of panes (for SAS/AF applications).

'PROTECT'

protects one or more FRAME entry widgets or fields. This prevents a user from modifying the FRAME entry widget or field. This action has a corresponding SCL statement. FRAME entry widgets can also use the _protect method.

'PROTECTED'

reports whether a FRAME entry widget or field is protected. FRAME entry widgets can also use the _isProtected method.

'PUTOBS'

reports whether a formula is being executed in an FSVIEW application because a column has been modified. If rc is 1, then the formula is being executed because a column has been modified. If rc is 0, then the formula is being executed to read a column. If you are on a new row, rc is always 0. This is the opposite of GETOBS.

'ROW'

returns the row where a FRAME entry widget or field is positioned. This option is valid only in SAS/AF software. FRAME entry widgets can also use the _row method.

'SMOOTHSCRL'

sets smooth scrolling to ON, OFF, or TOGGLE. Allows smooth scrolling when users drag the thumb in the scroll bar. When smooth scrolling is on, the getrow sections of AF extended tables are called while the thumb is dragged. In the FSVIEW procedure, the display is refreshed while the thumb is dragged. When smooth scrolling is turned off, the redisplay is deferred until the thumb is released. By default, smooth scrolling is off for SAS/AF and on for FSVIEW.

If you do not specify ON or OFF, SMOOTHSCRL is toggled from OFF to ON or from ON to OFF.

'UNPROTECT'

unprotects one or more fields or FRAME entry widgets. This enables a user to modify the field or FRAME entry widget. This action has a corresponding SCL statement. FRAME entry widgets can also use the _unprotect method.

Details

The FIELD function combines the functionality of the field statements (CURSOR, DISPLAYED, ERROROFF, ERRORON, PROTECT, and so on). It also provides additional widget over the fields.

At least one window column name is required for all actions except ALARM, BLOCKCUROFF, BLOCKCURON, CURSCREEN, HOME, NSCREEN, and SMOOTHSCRL.

The smooth scrolling action enables you to turn on, turn off, or toggle the scrolling mode.

Examples

Example 1: Using FIELD to Allow Smooth Scrolling

Allow smooth scrolling:

rc=field ('smoothscr1', 'on');

Example 2: Using FIELD to Check for Error Status of Fields

Create the array FLDNAMES and pass its elements to the FIELD function to check the error status of the fields. If necessary, move the cursor to the field that contains invalid data.

array fldnames{*} $ 8 ('tablename','colname','list',
                       'x','y');
do i=1 to dim(fldnames);
   if (field('error',fldnames{i})) then
      do;
         _msg_='Field name '||
         fldnames{i}||' is bad.';
         rc=field('cursor',fldnames{i});
         return;
      end;
end;

Example 3: Using FIELD to Turn on an Error Flag

Turn on the error flag for FIELD1 and FIELD2:

rc=field('erroron','field1','field2');

Example 4: Using FIELD to Change a Field's Color

Change the color of FIELD1:

rc=field('color blue','FIELD1');

Example 5: Using FIELD to Change Color and Display Attributes for a Field

Change FIELD1's color and display attributes:

rc=field('color red reverse','field1');

Example 6: Using FIELD to Specify a SASCOLOR Window Element

Specify FIELD1's color, using the name of a SASCOLOR window element:

rc=field('color foreground','field1');