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 data set is a collection of data values organized into a table-like structure. The data values are organized into rows called observations and columns called variables. As needed for clarity, the terms table, row, and column are used to describe the Data Form and Data Table classes instead of the terms data set, observation, and variable.

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.

Controlling Execution in the SCL

Program execution in the SCL entry assigned to a Data Set Data Model object is controlled by grouping statements into sections. Each section of the program begins with an SCL label and ends with a RETURN statement. Data Set Data Model object application 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 run when the _setSource method of the Data Set Data Model class is called. This section is invoked only once for each SCL entry. 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 data sets or external files used or referenced by the application.

   You cannot assign initial values to columns (variables displayed in the attached viewer, whether computed columns or data set columns) in the DFINIT section. Only columns which are not part of the data display can be initialized in this section because no rows are open 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 per row, when the _getData method is called for the row. Typical uses of the statements following the INIT label are to
   • initialize columns for the row

   • initialize computed columns.

   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.  
   

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. Column labels allow you to separate specialized data validation code for each column in the table.

4. MAIN: a phase to process user input, marked by the label MAIN. This section is repeated each time the user modifies a field in the window or the _setData method of the object is driven by the attached viewer. When a field is modified, the Data Set Data Model class
   • checks the input values for validity. The Data Set Data Model class uses any column attributes assigned for the column.

   • executes the SCL statements following the MAIN label only if the input values are valid. If errors are detected, then statements are not executed and the class issues an error message. When the user corrects the error, the MAIN section is executed.

   Note:Column values are checked for validity only before the SCL program is entered, not after. No error is detected if manipulations in the SCL program produce a field value that is outside the range specified in the MIN and MAX column attributes.

   During the main processing phase, the user interacts directly with the application to accomplish specific tasks. The SCL program can prompt the user for information, verify values, check data sets, and call other programs that prompt the user for information.

5. TERM: a termination phase, marked by the label TERM, that executes before moving from a locked row. This label is driven when the _getUpdateStatus method of the Data Set Data Model class is called.

   A typical use of the TERM section is to update an auxiliary data set.

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. This section is executed when the _term method or _setSource method is called.

   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 dataform 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 that you can type into columns that are protected, but the widgets revert to their previous state when you press enter. In addition, in a data form you cannot tab to or tab out of a protected column. If you are using a data table, the effect of protecting a column is that you can not type into the column at all.

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.

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

(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 EDIT SCL window.

• select

  Form

  or

  Table

  from the build-time pop-up menu and 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.  

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

noncolumn variables

variables that do not correspond to columns in the object. 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 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 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 variables, _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 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.

• _msg

• _columnName, 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 _columnName is _blank.

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

• _addComputedColumn

• _deleteComputedColumn

• _findRow

• _repeatFindRow

• _setData

• _setDataset

• _setEntry

• _setProperties

• _setSource

• _select

The following methods must be called from the model's SCL entry:

• _getViewerAttribute

• _setViewerAttribute

When are data sets opened?

The data set associated with a data form or data table is opened at build-time using the mode and level defined in the object attributes window.

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 contains 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 you 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.