Chapter Contents

Previous

Next

Data Form and Data Table Concepts

Terminology

The Data Form and Data Table classes make use of several key terms and concepts. A SAS table (also known as a "data set") is a collection of data values organized into rows and columns.

Relative row number refers to the relative position of the row within the table (ignoring any deleted rows, and taking into account any WHERE clause or index key). Absolute row number refers to the actual physical location of the row within the table (taking into account deleted rows and ignoring and WHERE clause or index key). Absolute row number is not supported by all SAS data files.

How are "viewers" and "models" used in Data Form and Data Table?

The functionality of the Data Form and Data Table classes is accomplished by the use of a model and viewer. The model retrieves data and delivers it to the viewer for display. Generally, the model controls any action that is directly related to the data that is being displayed, for example, the column labels that are used in the form or table, the columns from the table (data set) that are included in the display, which rows for the columns are displayed, and the format associated with the data values. The viewer, on the other hand, controls the display and how users interact with it, for example, the movement within the form or table, including scrolling or paging through the columns.

Because the functionality is accomplished by using both a model and a viewer, the model and viewer must be able to communicate. The term used for this connection is attached, that is the model is attached to the viewer. When you use the Data Form and Data Table classes, the model is automatically attached for you. The model that is used with Data Form and Data Table is the Data Set Data Model class. Because the model is automatically attached, you can call both the model methods and the viewer methods on the data form or data table.

What is the model SCL?

The model SCL is separate from the frame's associated SCL entry. The model SCL entry is associated with a particular data form or data table object. It initializes computed columns and performs error checking and data validation. It also allows you to reference the columns by name.

Editing and Compiling the Model SCL

The model SCL for a data form or data table is associated with the data form or data table through the SCL Entry field in the object's attributes window. Specify the name of the model SCL entry in this field.

CAUTION:

Use unique names for the frame SCL entry and the model SCL entry. Do not specify the same SCL entry for both the frame SCL entry and the model SCL entry.  

To edit the model SCL for a data form or data table, display the build-mode pop-up menu for the object, select [Form] (if the object is a data form)(or [Table] (if the object is a data table), and then select [Edit SCL...]. Note that the [Edit SCL...] item will be grayed out if you have not specified an SCL entry in the attributes window for the data form or data table.

Compile the model SCL for a data form or data table, by using one of the following:

• issue the COMPILE command from the Source window.

• select [Form] or [Table] from the build-time pop-up menu, then select [Compile SCL].

Note:   Compiling the model SCL from the BUILD window will cause an error at run time.  

Using SCL Variables in Model SCL

You can use the following three types of variables in your SCL program:

column variables

variables that correspond to columns in the table and computed columns, regardless of display status.

Note:   You do not need to declare these in an SCL program; the column variables are automatically declared as the same type and length as the columns in the table.  

Each column in the model has a corresponding column variable in SCL. When a user modifies the column values of the model, the values of the corresponding SCL variables are automatically updated. Similarly, when the SCL program modifies the value of a variable, the value of the corresponding column in the model is updated. If the column variable is associated with a data set column, the column in the data set is updated also.

noncolumn variables

variables that do not correspond to columns in the model. These include temporary variables used in the program, such as variables used to hold the return codes of SCL functions. These variables can be used in calculations and are treated by SCL in the same manner as column variables.

Noncolumn variables are initialized to missing values, blank, or to initial values given in declarative statements (such as ARRAY statements) before SCL is executed.

system variables

reserved variables such as _SELF_ provided by SCL to check information set by the system or to set information displayed or used by the system. Four system variables can be used in the model SCL:

• _SELF_, which contains the model's object identifier. The variable _SELF_ is declared as an object of type sashelp.fsp.Data_m.class so that do notation can be used to access properties of the model. The model methods for Data Form and Data Table show the first argument as object-id. However, if you are calling these methods from the model SCL, you can substitute the system variable _SELF_ for object-id. _SELF_ can only be used with model methods.

• _VIEWER_, which contains the object identifier for the data form or data table. The variable _VIEWER_ is declared as an object of type sashelp.fsp.DataForm.class for a data form and of type sashelp.fsp.DataTabl.class for a data table so that dot notation can be used to access properties of the viewer only. Note that dot notation does not support method delegation, so calling a model method using _VIEWER_ will not work. The model methods for Data Form and Data Table show the first argument as object-id. The viewer methods show the first argument as form-id and table-id. If you are calling the model or viewer methods from the model SCL, you can substitute the system variable _VIEWER_ for object-id, form-id, or table-id. _VIEWER_ can be used with both model and viewer methods using the CALL SEND() syntax.

• _MSG_, which contains the text to be displayed in the message (or status) line of the frame. During execution of a given set of SCL labels, the _MSG_ variable is initially set to a blank. Once the labels have executed, the last value set for _MSG_ will be displayed on the message line. If you want to display multiple messages, use the _setMsg method instead.

• _COLUMN_NAME_, which contains the name of the column for which the SCL column label is being run. In the DFINIT, DFTERM, INIT, MAIN, and TERM labels, the value for _COLUMN_NAME_ is _BLANK_.

Note that the following methods cannot be called from the model's SCL entry:

• _addComputedColumn

• _commitNewRow

• _deleteComputedColumn

• _findRow

• _repeatFindRow

• _rereadAll

• _select

• _setData

• _setDataset

• _setEntry

• _setProperties

• _setSource

The following methods can be called from the model SCL, but they will not execute until the model SCL completes its execution:

• _addRow

• _copyRow

• _deleteRow

• _reread

• _save

• _setWhere

• _updateRow

The following methods must be called from the model's SCL entry in the INIT, MAIN, TERM, or column labels:

• _getViewerAttribute

• _setViewerAttribute

Controlling Execution in the Model SCL

Program execution in the model SCL entry assigned to a Data Form or Data Table object is controlled by grouping statements into sections. Each section of the program begins with an SCL label and ends with a RETURN statement. Model SCL programs can include the following six labeled sections:

1. DFINIT: an initialization phase before any rows are displayed, marked by the label DFINIT. This labeled section is executed only once, each time the SCL entry is loaded. Typical uses of this label are to:
   • import values through macro variables

   • display initial messages on the message line (using the _setMsg method)

   • open auxiliary tables or external files used or referenced by the application.

   You cannot assign initial values to columns variables (whether computed columns or data set columns) in the DFINIT section. Only variables that are not part of the data set can be initialized in this section because there is no current row during the processing of this block.

   The FSEINIT label is synonymous with the DFINIT label; if both labels are present, only the DFINIT label is run.

2. INIT: an initialization phase before each row is displayed, marked by the label INIT. This section is executed once each time the row is read from the data set. Typical uses of the INIT label are to
   • initialize columns for the row

   • initialize computed columns

   • set viewer attributes for a column using the _setViewerAttributes method.

   Note:   If the viewer being used is a table editor, then the INIT label runs for each row that is displayed in the table. For example, if the table displays 10 rows, then INIT runs 10 times, executing the SCL code in it each time. When a row is locked for editing, the INIT label runs for the locked row.  
   

3. Column Labels: a processing phase that runs when a given column is modified, marked by a label corresponding to a column name. Column labels for any modified columns are run before the MAIN processing phase. Typical uses of the column label sections include:
   • specialized data validation for a column

   • setting viewer attributes for a column, based on a new value using the _setViewerAttribute method.

4. MAIN: A generic section that is used to process user input. This section is executed after all modified column labels are run. For each modified column, the new value is validated using the column attributes assigned to then column. The SCL statements in the MAIN section execute only if the new column values are valid. If an error is detected, the the statements are not executed and an error message is issued. The MAIN section will then execute only when the user corrects the error condition.

   CAUTION:

   Column values are checked for validity only before the MAIN section is executed, not after. No error is detected if manipulations in the MAIN section produce a column value that is outside the range specified in the MIN and MAX column attributes.  

5. TERM: a termination phase, marked by the label TERM, that executes before moving from a locked row.

6. DFTERM: a termination phase before the object terminates or when a new SCL entry is assigned to the object, marked by the label DFTERM.

   Typical uses of the statements following the DFTERM label are to

   • close tables or external files used or referenced by the application

   • export values through macro variables.

   The FSETERM label is synonymous with the DFTERM label; if both labels are present, only the DFTERM label is run.

   The model SCL respects the following SCL CONTROL statement arguments:

   • LABEL

   • ERROR

   • ALWAYS

   • ENTER

   • TERM

   See SAS Component Language: Reference for more information on the CONTROL statement.

Effect of Protecting Columns

You can prevent users from modifying a column or columns by "protecting" the column or columns. Columns can be protected by using the _protectColumn method or by setting the "protected" attribute for that column or columns. Note that the effect of protecting columns is different in a data form than in a data table.

• If you are using a data form, the effect of protecting a column is different depending on whether a Version 6 widget or Version 8 control is used. If a Version 6 widget is used, then a user can type in and/or select the widgets that are protected, but the widgets revert to their previous state when the Enter key is pressed or the mouse button is released. If a Version 8 control is used, then the control is grayed and no typing or clicking is accepted by the control. In addition, a user cannot tab to a protected control or widget in a data form.

• If you are using a data table, the effect of protecting a column is that you can not type in the column, although you can tab into a protected column.

When a data form or data table is in browse mode, all of the columns are protected.

In both the data form and data table, labeled sections for protected columns do not run.

When are tables opened?

The table (data set) associated with a data form or data table is opened at build-time in browse mode. If you specify Edit for the Data Mode and Member for Lock Mode in the Attributes window of your object, you cannot test your application from the SAS/AF Build environment.

DATAFORM Catalog Entries

DATAFORM catalog entries can contain column customizations for the following classes: Data Table, Data Form, Table Editor, and Form Editor. In addition, DATAFORM catalog entries also contain layout information for all of these classes.

(For more information on table editors and form editors, see the Table Editor Class and Form Editor Class.)

You can specify that a data table and a data form use the same DATAFORM catalog entry. This approach enables customizations to be shared between both classes with the use of a single catalog entry.

To specify a DATAFORM catalog entry, enter its name in the DATAFORM Entry field of the Data Table or Data Form Attributes window.

CAUTION:

Customizations can be lost. Whether customizations that you make are saved to a DATAFORM catalog entry is determined by what you specify in the DATAFORM Entry field in the Attributes window and by when you make the specification. DATAFORM entries are saved each time you either exit the Attributes window, test the frame, or end from the frame.  

For example, when you initially open the Attributes window, you can enter the name of a catalog entry in the DATAFORM Entry field or you can leave the field blank. Then, you can make customizations to your frame object. When you return to the Attributes window, you again have an opportunity to enter the name of a catalog entry in the DATAFORM Entry field.

For details on how changing the name of the catalog entry in the DATAFORM entry field can save or lose your customizations, see the following table.

Customizations and DATAFORM Catalog Entries

Before customizations, if the DATAFORM Entry field contains...	After you make customizations and specify a name for the DATAFORM entry as...	Then, the customizations are...
nothing (blank)	a new DATAFORM catalog entry	saved to the new DATAFORM catalog entry. In a data form, the layout is not changed.
nothing (blank)	an existing DATAFORM catalog entry	lost; the object uses any customizations from the existing DATAFORM catalog entry. In a data form, the previous layout is lost and replaced by the saved layout in the new DATAFORM entry.
the name of a new DATAFORM catalog entry	another new DATAFORM catalog entry	saved to the new DATAFORM catalog entry that you specify after you make customizations. In a data form, the layout is not changed.
the name of a new DATAFORM catalog entry	an existing DATAFORM catalog entry	lost; the object uses any customizations from the existing DATAFORM catalog entry. In a data form, the previous layout is lost and replaced by the saved layout in the new DATAFORM entry.
the name of an existing DATAFORM catalog entry	a new DATAFORM catalog entry	lost; the object uses default customizations. In a data form, the previous layout is lost and a new default layout will be created for you.
the name of an existing DATAFORM catalog entry	another existing DATAFORM catalog entry	lost; the object uses any customizations from the existing DATAFORM catalog entry that you specify after you make customizations. In a data form, the previous layout is lost and replaced by the saved layout in the new DATAFORM entry.

Chapter Contents

Previous

Next

Top of Page

Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.