Programming Guide

VIEW

Fetches data from the database for display purposes 

int sm_tm_command ("VIEW [ tableViewName [ tableViewScope ] ]");

Arguments

tableViewName
The name of a server view in the current transaction. This parameter is case sensitive.

If tableViewName is specified, the command is applied according to the tableViewScope parameter. (Since the entire table view tree might not be included, this is known as a partial command, and sm_tm_command sets TM_FULL to 0.) The specified table view must either be a server view or be the server view to which the desired table view belongs.

If tableViewName is not specified, the command is applied for each table/server view, starting with the root table view. This is known as a full command, and sm_tm_command sets TM_FULL to 1.

tableViewScope
One of the following parameters, which must be preceded by a table view name.

Description

VIEW fetches data from the database for display purposes only.

When VIEW is selected the following steps occur:

  1. If you have made changes in the table views on which this command operates in a previous NEW, COPY, COPY_FOR_UPDATE, or SELECT, you are prompted to discard your changes. If you choose OK, changes are discarded and fields in the specified table views are cleared. If you choose Cancel, you return to the screen so you can save your changes.
  2. The transaction mode is set to view unless a table view is specified. By default, view mode protects all fields from data entry.
  3. If the Count Select property is set to Yes, the transaction manager issues a SELECT statement using COUNT(*) to find the number of rows in the select set. If this number exceeds the amount set in the Count Threshold property, a message box offers the user the choice of discontinuing data selection.
  4. The screen displays the first set of data for all linked table views. When you choose VIEW, the common transaction model has the SQL generator execute a SELECT statement for the database table named in the root table view and any table views connected to it via a server link. Then, recursively, SELECT statements are issued for the child table views having sequential links, and any table views connected to those child table views by server links. If the query does not return any rows for the first server view, no data are displayed for the remaining server views. (A query which successfully returns rows sets TM_OCC_COUNT as part of the TM_SEL_CHECK slice. When TM_OCC_COUNT is greater than 0, the query is generated for the next server view.)

Push buttons and menu selections for the VIEW command can choose to set the class property to view_button. By default, view_button is active in initial or view modes.

Using QBE

If you want to select a specific record or group of records, you need to set the use_in_where property to PV_YES and set the type of operator (where_operator property) to be used in the WHERE clause. Then, in the transaction manager, choose CLEAR to clear the fields, enter a value in your query field, and then choose VIEW. The screen displays the specified information.

Using the Count Select Property

If the server view's Count Select and Count Warning properties are set to Yes, the application will warn users about large select sets; however, the SELECT statement is performed twice, and the tables must remain locked for the result to be the same for both statements.

Sequence

To display additional data in two-tier processing, choose any CONTINUE command.

Events

The following request events can be generated by the VIEW command to ascertain whether the changes from the previous command have been saved and, if desired, discard those changes:

The VIEW command generates TM_CLEAR requests if TM_VIEW for a parent table view returns no data. In that case, TM_CLEAR is generated for all subordinate table views, but not for table views at the same level of the tree. TM_CLEAR requests are described under CLEAR.

Table 8-34 Transaction manager command.

Table 8-35 Request events for VIEW

Request Traversal Typical Processing

TM_PRE_VIEW

By table/server view from the specified table view

Do nothing

TM_VIEW

By table/server view from the specified table view

Slices:

TM_VIEW, TM_GET_SEL_CURSOR, TM_PREPARE_CONTINUE, TM_SET_SEL_COUNT_FLAG, TM_SEL_GEN, TM_SEL_BUILD_PERFORM, TM_SEL_COUNT_CHECK, TM_CLEAR_SEL_COUNT_FLAG, TM_SEL_CHECK (sm_bi_suppress is called for the table view by the transaction manager after this request.)

TM_POST_VIEW

By table/server view from the specified table view

Do nothing

Table 8-36 Slice event processing for VIEW

Slices Typical Processing

TM_VIEW

TM_OCC_COUNT is zeroed. At the end of processing for this request, it contains the number of rows fetched (set, if at all, by TM_SEL_CHECK).

If the table view is the first one in the current server view:

-Push the TM_GET_SEL_CURSOR (only if there is no select cursor already) and the TM_PREPARE_CONTINUE events on the stack.

-If use_select_count is set to 1, push TM_SET_SEL_COUNT_FLAG, TM_SEL_GEN, TM_SEL_BUILD_PERFORM, TM_SEL_COUNT_CHECK, and TM_CLEAR_SEL_COUNT_FLAG events on the stack.

-Push the TM_SEL_GEN, TM_SEL_BUILD_PERFORM, and TM_SEL_CHECK events on the stack.

If the table view is not the first one in the server view, nothing more is done for this request, and the number of rows fetched for this request is correctly reported as zero.

TM_GET_SEL_CURSOR

If a name does not exist for the Panther select cursor, generate it.

(Depending on the engine, a Panther cursor may or may not correspond to a database cursor.)

TM_PREPARE_CONTINUE

If the select cursor does not already exist, a dummy DBMS DECLARE CURSOR command is issued.

If sm_tm_continuation_validity reports that continuation file commands (like CONTINUE_TOP) are valid, DBMS STORE FILE is issued. If the function reports that those commands are invalid, DBMS STORE is issued.

TM_SET_SEL_COUNT_FLAG

If count_select is set to Yes, set TM_SV_SEL_COUNT to 1.

TM_SEL_GEN

Generate data structures with dm_gen_sql_info that are used in the TM_SEL_BUILD_PERFORM slice to build the SQL statements.

If TM_SV_SEL_COUNT is 1, modify the structure to use count(*) and alias the result into the server view's count_result property.

TM_SEL_BUILD_PERFORM

Build, and then, if there was no error in building, perform SELECT (and other DBMS commands) with dm_exec_sql. Free the select information.

TM_SEL_COUNT_CHECK

If count_result > count_threshold, check count_warning to see if a Y/N message box should be displayed.

If count_result is 0, push the TM_GIVE_UP_SEL_CURSOR event and call sm_tm_clear.

TM_CLEAR_SEL_COUNT_FLAG

Set TM_SV_SEL_COUNT to 0.

TM_SEL_CHECK

If there was an error in earlier processing, give up the select cursor. Otherwise, report the number of rows fetched to TM_OCC_COUNT. Give up the select cursor if there are no more rows un less a continuation file is in use.

If TM_VIEW for a parent table view returns no data, TM_CLEAR requests are generated for all subordinate table views, but not for table views at the same level of the tree. TM_CLEAR requests are described under CLEAR.