Progress
Language Tutorial
for Windows


Using the FIND and DISPLAY Statements

The first step in implementing the database access form, shown in Figure 8–5, is to let users move through, or navigate, the records of a database table. In this example, when the procedure starts, it finds the first record in the Item table and displays data from that record. Choosing the Next button finds and displays the next Item record. The Prev button finds and displays the previous Item record. The Next and Prev buttons implement the navigation and display functions of the form.

Figure 8–5: Data Form with Navigation Buttons Enabled

The FIND statement retrieves an individual record and is the basis for the triggers associated with the navigation buttons. FIND copies a record from a database to a record buffer, as shown in Figure 8–6.

Figure 8–6: Data Movement with the FIND Statement

This is a partial syntax for the FIND statement.

SYNTAX
FIND
  { FIRST | NEXT | PREV | LAST | CURRENT } record-phrase
  NO-ERROR 

When you think about it, there are four records that you search for most often in database applications. They are the first record, the record next after the one currently in the record buffer, the record previous to the one currently in the record buffer, and the last record. Progress supports four keywords for the FIND statement to specify these records: FIRST, NEXT, PREV, and LAST.

With just these four keywords, you have enough context to create an application that interactively searches one by one through the records of a database table. The record phrase only has to specify a table name to complete a valid statement, as shown below:

FIND FIRST Item. 

The FIND statement uses the primary index of the database table to determine which record is first and last. In the next chapter, you’ll learn how to navigate through the records in different orders.

The NO-ERROR option suppresses the normal error messages and default behavior that the RDBMS executes if the FIND attempt fails. Use NO-ERROR when you want to handle error conditions in your procedure. The programming example at the end of this section demonstrates error handling.

Once you have a record in the buffer, you can display that record. You’ve already seen the DISPLAY statement several times. The function of the DISPLAY statement is to move data from a record buffer into a screen buffer, and thus make the data visible to the user, as shown in Figure 8–7.

Figure 8–7: Data Movement with the DISPLAY Statement

As you learned in "Programming the Progress Way," a widget and the data it represents are two different things. DISPLAY manipulates the data in a widget. But, if the widget that contains the data is not already visible when Progress executes DISPLAY, Progress makes the widget visible. After a widget is visible, you can use the DISPLAY statement repeatedly to update the data in the screen buffer, which refreshes the widget with the most current data. Remember, when data changes in the record buffer, Progress does not update the associated data in the screen buffer. If you want your user to see the current data, use another DISPLAY statement.

This is a partial syntax for the DISPLAY statement.

SYNTAX
DISPLAY
  [   expression [ format-phrase ]
    | SPACE [ ( n ) ]
    | SKIP [ ( n ) ]
  ] ...  
  { [ frame-phrase ] } 

This is an alternate syntax (partial) of the DISPLAY statement for displaying whole records.

SYNTAX
DISPLAY record 
  [ EXCEPT field ... ]
  { [ frame-phrase ] } 

Table 8–1 describes the DISPLAY statement syntax components:

Table 8–1: DISPLAY Statement Syntax 
Component
Description
expression
Expression can be a database field, variable, constant, or any legal combination of these. For each expression in the DISPLAY statement, you can use the options provided by the format phrase.
SPACE ( n )
Specify a number of spaces to place after an expression.
SKIP ( n )
Specify a number of lines to skip after an expression.
frame-phrase
The frame phrase lets you specify a particular frame in which to display the data, as well as frame-formatting options.
EXCEPT
Specify fields from the record to not display with the record.

FIND and DISPLAY Programming Example

Follow these steps for a demonstration of the FIND statement and the NO-ERROR option using the database access form for the Item table:

  1. Open lt-08-01.p and run it. The Database Access Form appears.
  2. Choose the Next button several times and notice the changes to the Item No. field. The procedure navigates through the records starting with the lowest item number and moving to the highest. FIND uses the Item-Num field for the navigation order because it is the primary index of the Item table.
  3. Choose Prev until the form displays item number 1. Now choose Prev again. Normally, trying to find the previous record of the first record would be an error. This procedure, however, defines the LAST record as the PREV record of the FIRST record. The procedure also defines the NEXT record of the LAST record as the FIRST record.
  4. Choose Exit, then press SPACEBAR to return to the Procedure Editor.

Here is the code for the form:

lt-08-01.p
       /**********  DEFINE FORM  **********/
/*1*/  {lt-08-f1.i}
  
       /**********  DEFINE TRIGGERS  **********/     
/*3*/   ON CHOOSE OF btn-Prev 
        DO:
/*4*/      FIND PREV Item NO-ERROR.
/*5*/      IF NOT AVAILABLE(Item) THEN FIND LAST Item.   
/*6*/      DISPLAY Item.Item-Num Item-Name Price On-Hand 
               Allocated Re-Order 
             On-Order Cat-Page Cat-Description WITH FRAME Frame1.
        END.
/*7*/   ON CHOOSE OF btn-Next 
        DO:
/*8*/      FIND NEXT Item NO-ERROR.
/*9*/      IF NOT AVAILABLE(Item) THEN FIND FIRST Item.
             DISPLAY Item.Item-Num Item-Name Price On-Hand 
                  Allocated Re-Order 
                On-Order Cat-Page Cat-Description WITH FRAME Frame1.
        END.
       /**********  MAIN LOGIC  **********/
/*2*/   FIND FIRST Item.
       DISPLAY Item.Item-Num Item-Name Price On-Hand Allocated Re-Order 
          On-Order Cat-Page Cat-Description WITH FRAME Frame1 USE-TEXT.
       ENABLE btn-Next btn-Prev btn-Exit WITH FRAME Frame1.
        WAIT-FOR CHOOSE OF btn-Exit. 

These notes help to explain the code:

  1. This statement includes the file that contains the frame and button definitions that make up the interface.
  2. The first FIND statement (in the Main Logic section) creates the Item buffer and copies the first record from the database to the record buffer. The NO-ERROR option is not necessary here. As long as the table contains one record, Progress will find a record that satisfies the request. If the RDBMS encounters any other errors, then you want the default messages and behaviors to execute.
  3. This trigger executes when the user chooses the Prev button. It finds the previous record, which is the record that comes before the current record according to the primary index. If the current record is the first record (no previous record exists) it finds the last record.
  4. This FIND statement clears the Item buffer, locates the previous record, and copies it to the Item buffer. The NO-ERROR option suppresses the normal error response. Normally, if Progress cannot find the previous record, the RDBMS sends a message to the user and the procedure stops execution of the current code block, which is the trigger. With the NO-ERROR option, the user gets no error message and the procedure continues executing the code block. However, because Progress clears the Item buffer during the FIND request, there is no current record. Any attempt to access the buffer later results in an error.
  5. This IF statement checks the Item buffer with the AVAILABLE function. This test allows you to handle error conditions. If there is no record in the Item buffer, then the FIND statement failed. If it failed, then it probably failed because the user tried to find the previous record of the first record. In this situation, finding the last record puts data into the empty buffer.
  6. The DISPLAY statement refreshes the form with the new data in the record buffer.
  7. This trigger executes when the user chooses the Next button. It finds the next record, which is the record that comes after the current record according to the primary index. If the current record is the last record (no next record exists) it finds the first record.
  8. This FIND statement copies the next record to the Item buffer.
  9. This IF statement defines the normal behavior for trying to find the next record of the last record—find the first record.

Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095