Step 6: Coding Triggers and Other Functions

In this section:

You can supply the function logic needed for the Winform's triggers using TED (or any editor of your choice) to edit the Maintain procedure and add the appropriate logic.

When you are finished, Maintain must have the following functions:


Top of page

x
Painter-generated Code

Before adding any new functions, it is important to understand the code the Winform Painter already has generated. As you are building your screen, the Winform Painter is adding code in your Maintain procedure. If you were to save and exit the Painter now, the following code would be generated for you in the Maintain procedure CARSPECS.

Note: Do not change anything on or following the -* >> Generated Code Section line. This section contains code and comments generated by the Winform Painter.

MAINTAIN FILE CAR
 
case PrevCar
endcase
 
case NextCar
endcase
 
-* >> Generated Code Section ...
 
.
.
.
 
END

Top of page

x
Top Function

Now you will add code to the Top function.

Try it now: Select Cases from the menu bar.

The Cases dialog box opens:

Try it now: To edit the Top function, you can exit the Painter and use TED or select top in the combo box. After top appears in the entry field, click the Open button. The Painter invokes TED and displays the following editing screen:

The file name in the upper left corner (TEMP00) is a default name for the temporary file. It doesn't affect your editing session.

Do not enter the numbers (annotations) at the beginning of each line.

Try it now: Add the following code to the Top function:

1. FOR ALL NEXT Country Car INTO CarStack; 
2. PERFORM GetBody; 
3. WINFORM SHOW ShowCars; 
4. FOR ALL UPDATE Dealer_Cost Retail_Cost FROM BodyStack;
  1. Retrieves all the Country and Car combinations into CarStack. The NEXT command specifies which segments to retrieve, and the INTO phrase specifies into which stack to place the retrieved rows. The FOR ALL prefix specifies that all of the rows in the data source must be retrieved.
  2. Performs the GetBody function. GetBody retrieves these same keys, as well as Model, BodyType, and all the non‑key fields in the Body segment into BodyStack. It retrieves only those records (also known as path instances or relational rows) whose Car and Country fields match the values in the current row of CarStack. The grid that you created displays selected columns from BodyStack.
  3. Displays the ShowCars Winform. From this Winform, the application user can browse and edit data using function key and button triggers.
  4. Writes the application user’s last round of edits to the data source after the user leaves the Winform.

For more information on any of the Maintain commands or system variables included here, see Language Rules Reference; Command Reference; Expressions Reference; and the Using Functions manual.

Try it now: To save your work and return to the Cases dialog box, enter FILE at the TED command line.


Top of page

x
PrevCar Function

Try it now: Select the PrevCar function from the dialog box and click Open.

Maintain displays the following editing screen:

Try it now: Add the following function that enables users to scroll backward through the data and write their last changes to the data source each time they scroll. (Changing the generated CASE and ENDCASE keywords to uppercase is optional and is done for consistency. It does not affect execution.)

   CASE PrevCar 
1.  FOR ALL UPDATE Dealer_Cost Retail_Cost FROM BodyStack; 
2.   IF CarStack.FocIndex GT 1 
2.     THEN COMPUTE CarStack.FocIndex=CarStack.FocIndex-1; 
2.     ELSE COMPUTE CarStack.FocIndex = CarStack.FocCount; 
3.  PERFORM GetBody;
   ENDCASE
  1. Writes the application user’s last Dealer_Cost and Retail_Cost changes from BodyStack to the data source. BodyStack contains values for all the records defined by the Country and Car values in the current CarStack row.
  2. Displays the previous values of Car and Country by changing the current row of CarStack to the previous row.

    Winforms display data from stacks based on the value of the stack variable FocIndex. The command reads: if the row the user is currently viewing (indicated by CarStack.FocIndex) is greater than 1, then subtract one from FocIndex; otherwise set FocIndex equal to the number of rows in the stack.

    FocCount is another stack variable that automatically keeps track of the number of rows in the stack. This means when the PrevCar function is executed, the prior row is displayed unless the user is positioned on the first row in the stack. In that case, the last row is displayed. In this way, the user can cycle through the data.

  3. Performs the GetBody function. GetBody retrieves fields from the first four segments of the Car data source into BodyStack, where they can be displayed in the grid you created. Only records whose Car and Country fields match the key values in the current row of CarStack are retrieved.
  4. To save your work and return to the Cases dialog box, enter FILE at the command line.

Top of page

x
NextCar Function

Try it now: Select the NextCar function from the Cases dialog box and click Open. Enter the following function:

CASE NextCar
 FOR ALL UPDATE Dealer_Cost Retail_Cost FROM BodyStack;
   IF CarStack.FocIndex LT CarStack.FocCount
     THEN COMPUTE CarStack.FocIndex = CarStack.FocIndex + 1;
     ELSE COMPUTE CarStack.FocIndex = 1;
 PERFORM GetBody;
ENDCASE

This function is almost identical to the PrevCar function. The only differences are in the COMPUTE and IF commands. Rather than subtracting one from the value of CarStack.FocIndex, it adds one. This is because you want to display the next Country Car combination. The value of CarStack.FocIndex determines which row is displayed in the Winform.

Refer to the comments for the PrevCar function for additional information.

Try it now: To save your work and return to the Cases dialog box, enter FILE at the command line.


Top of page

x
GetBody Function

Now you will enter a new function named GetBody. It is not invoked by any of the Winform's triggers, so the Painter has not generated any code for it. Instead, this function is called by the other functions (Top, NextCar, and PrevCar) when they need to retrieve new values into BodyStack that match the key values in the current row of CarStack.

Try it now: Type GetBody in the Cases entry field and click Open. Enter the following code:

   CASE GetBody 
1.  STACK CLEAR BodyStack; 
2.  REPOSITION Country; 
3.  FOR ALL NEXT Country Car Model BodyType INTO BodyStack 
3.    WHERE CarStack().Country EQ Car.Country 
3.      AND CarStack().Car EQ Car.Car;
   ENDCASE
  1. Clears the existing values from BodyStack.
  2. Repositions the application to the beginning of the data source, ensuring that the next set-based data source retrieval selects records from the entire data source.
  3. Retrieves fields from the first four segments of the Car data source into BodyStack. Only records whose Car and Country fields match the key values in the current row of CarStack are retrieved.

    The FOR ALL prefix means that all rows in the data source are examined to see if they meet the selection criteria. The rows to be retrieved are specified in the WHERE phrase.

    The components of the WHERE phrase are:

    CarStack().Country

    Indicates the value of the Country column—from the CarStack stack—that is currently displayed. This is a qualified field name (actually, in this case, a qualified column name).

    CarStack is the name of a stack that contains the Country column.

    CarStack() indicates the row of CarStack that is currently displayed and is shorthand for CarStack(CarStack.FocIndex). FocIndex is a system variable whose value is always the current stack row.

    CarStack().Car

    Indicates the value of the Car column—from the CarStack stack—that is currently displayed.

    EQ

    Only the data source rows matching the data in the stack are retrieved.

    Car.Car

    Refers to the Car field in the Car data source. This is a qualified field name.

    The first Car is the name of the data source, and the second is the name of the field.

    Car.Country

    Refers to the Country field in the Car data source.

For more information on any of the Maintain commands or system variables included here, see Language Rules Reference; Command Reference; Expressions Reference; and the Using Functions manual.

Try it now: To save your work and return to the Cases dialog box, enter FILE at the command line. Then click Done to exit Cases. Press PF3 to exit the Painter. When prompted about saving your work, click Yes.

If you wish to view a complete Maintain procedure built by the Painter, including the functions you entered, Painter-generated code, and Painter-generated comments, you can issue the command

TED CARSPECS

at the FOCUS command line to see the entire Maintain procedure.


Information Builders