Chapter Contents
Previous
Next
SAS/AF Software: Class Dictionary

Using the Data Set Data Model Class

Using SCL for Data Validation with the Data Set Data Model Class

The Data Set Data Model class allows you to use SCL to perform data validation in your data entry application, as well as control other aspects of your application.

Accessing the Column Name of the SCL Column Label

You can use the SCL variable, _column_name_, in the model SCL for data form objects and data table objects to get access to 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_. When a column has been modified and the label for that column is driven for the model, the value contained in the SCL variable called _column_name is the name of the column. The _column_name_ variable must be specified as a character.

Example

The following example assumes you have created a frame with a data form. The table used contains columns, COLUMN1 - COLUMN5, which are all numeric. The following SCL code is the model SCL for the data form. 

length _column_name_ $32;

column1: column2: column3:
 column4: column5:
   call send(_self_, '_getColumnValue',
             _column_name_, value);
   if (value > 9) then
      call send(_self_, '_erroronColumn',
                _column_name_);
   else call send(_self_, '_erroroffColumn',
                  _column_name_);
   return;

Assigning an SCL Entry to an Object

You can use the _setSource method to assign an SCL catalog entry, the model SCL, to an instance of the Data Set Data Model class. The SCL entry must have been previously compiled to assign it for use on a Data Set Data Model object. The variable types in the compiled entry must match the types of the variables displayed in your data entry application.

You can compile your SCL entry when you assign it to a Data Set Data Model object using the optional parameter on the _setSource method. Compiling your SCL entry in this way helps you identify potential problems in your data entry application through compiler warnings and error messages.

Note:If you use the Data Form or Data Table class and you specify an SCL entry via the attribute windows, the _setSource method as well as the methods to drive the individual labels are run for you automatically.

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 labelled sections:

  1. DFINIT: an initialization phase before any rows are displayed, marked by the label DFINIT. This labelled 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:

    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

    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.  [cautionend]

  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

    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.  [cautionend]

    During the main processing phase, the application may interact with the user 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 to another row, if the current row has been modified. 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 to another source entry method is called.

    Typical uses of the statements following the DFTERM label are to

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

    The model SCL for a dataform accepts the following SCL CONTROL statement arguments:

Summary of SCL Label Running

The following SCL labels are run when the viewer is a data form, a form editor, or a subclass of the form editor:

The following SCL labels are run when the viewer is a data table, a table editor, or a subclass of the table editor:

SCL Variables

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.  [cautionend]

Each column in the data set data 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. The Data Set Data Model class defines four system variables:

Commands for the Data Set Data Model Class

The following commands are supported by the Data Set Data Model class through the _execCmd method. Note that SCL programs should use the method which corresponds to the command; commands are provided for interactive end-user use. Commands not understood by the Data Set Data Model class are delegated to the Data Set Model class.

ADD
adds a pending row.

Note:   The ADD command is not valid when browsing a table or if the NOADD option is specified.  [cautionend]

By default, all values in a new row are missing. If an initial value has been stored for the column, the value for a new row contains the initial value for the column.

This command corresponds to the method _addRow.

DROPcolumn<...column-n>);
excludes one or more columns from the display. See also the _hideColumn method.

DUP<n<row>>
copies the current row to a pending row. In record level locking you must lock the row you wish to copy.

Note:   The DUP command is not valid when browsing a table or if the NOADD option is specified.  [cautionend]

By default, the row is duplicated once. To duplicate the same row again, leave the cursor on the command line and execute the DUP command again. Alternatively, you can follow the DUP command with the desired number of copies. Only the last added row is displayed. The rest of the rows are automatically committed to the table. For example, the dup 3 command duplicates the current row three times, committing the first two rows and leaving the third row in pending mode.

In member level locking, the DUP command copies the specified row n times and adds n - 1 rows to the table. The last row is a pending row presented for editing. If no row is specified, the current row is used.

You can select the row to copy by supplying its number as the row argument in the DUP command. To specify the row argument, you must also specify the n argument (the number of times you want the row duplicated). For example, the following command duplicates row 5 two times:

dup 2 5

This command corresponds to the method _copyRow.

CREATE dsname <REPLACE><WITH <ALL | varlist>>
creates a new SAS table using some or all of the columns from the current table. The new table duplicates both the structure and contents of the current table.

If you issue the CREATE command from an attached viewer, then computed columns are not written to the created table. For more information, see the Data Set Model class.

This command corresponds to the Data Set Data Model _saveAs method.

MOVE start end after
moves a range of columns that start with the start column and end with the end column after the after column.

This command corresponds to the method _moveColumn.

PROTECT ON|OFF column <...column-n>
protects a column or range of columns.

This command corresponds to the method _protectColumn.

SHOW column<...column-n>
redisplays dropped or hidden columns.

This command corresponds to the method _unhideColumn.

Default Pop-up Menu

The pop-up menu displayed by a viewer using the Data Set Data Model class is a combination of the viewer-specific items and the items listed in this section, which the Data Set Data Model class provides. The Data Set Data Model class defines and processes the following pop-up menu items via the _getActions method. Note that items on the pop-up menu may be grayed depending on current option settings and the current state of the model. The viewer is responsible for actually displaying the pop-up menu. Thus, you must have a viewer to have access to the pop-up menu.

The methods processed by the _getActions method must not require parameters. If you want to add custom actions to the pop-up, you need to have _getActions process your custom method to specify the parameters that need to be sent to the method being executed.

Add Row
runs the _addRow method to add a pending row.

Browse/Edit
runs the _setOpenMode method to alternate between BROWSE mode and EDIT mode.

Cancel Row Edits
runs the _reread method to reread the current row from the table. If you have added or copied a row, this item cancels the add or copy without saving the pending row on the table. Otherwise, this item cancels any edits that you have made on the locked row.

Commit New Row
runs the _commitNewRow method to add the pending row to the table if you have added or copied a row.

Copy Row
runs the _copyRow method to make a pending copy of the locked row in the table.

Delete Row
runs the _deleteRow method to delete the locked row from the table.

Help
runs the _columnHelpText method to obtain column help from the model.

Override
runs the _override method to override required and error fields. This item enables you to override a column that is in error if option settings allow.

Record/Member
runs the _setOpenMode method to change alternate between RECORD level locking and MEMBER level locking.

Where
runs the _setWhere method to open the interactive WHERE window to specify a WHERE clause for the data.

Where Clear
runs the _setWhere method to clear a WHERE clause for the data.


Chapter Contents
Previous
Next
Top of Page

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