Progress
Language Reference


DEFINE BUFFER Statement

Interfaces
OS
SpeedScript
All
All
Yes

Progress provides you with one buffer for each table that you use in a procedure. Progress uses that buffer to store one record at a time from the table as the records are needed during the procedure. If you need more than one record at a time from a table, you can use the DEFINE BUFFER statement to define additional buffers for that table. If you need to share buffers among procedures, use the DEFINE SHARED BUFFER statement.

SYNTAX

DEFINE [ [ NEW ] SHARED ] BUFFER buffer FOR table 
       [ PRESELECT ] [ LABEL label ] 

NEW SHARED

Defines a buffer that can be used by other procedures. When the procedure using this statement ends, the buffer is no longer available.

SHARED

Defines a buffer that was created in another procedure with the DEFINE NEW SHARED BUFFER statement.

BUFFER buffer

Identifies the name of the buffer you want to define to hold records from table.

FOR table

Identifies the name of the table for which you are defining an additional buffer. This can also be the built-in buffer name, proc-text-buffer, to define a buffer that returns table rows from a stored procedure.

To define a buffer for a table defined for multiple databases, you might have to qualify the table name with the database name. See the Record Phrase reference entry for more information.

PRESELECT

If you use the PRESELECT option with a DO or REPEAT block, Progress creates an internal list of the records selected. The PRESELECT option tells Progress to apply that internal list to the buffer you define. You can also use the PRESELECT option in the DEFINE SHARED BUFFER statement.

LABEL label

Specifies a label for the buffer. This label is used in error messages in place of the buffer name.

EXAMPLES

This procedure allows the user to create a new customer record. Initially, the City, State, and Country fields are not shown. After the user enters a Postal-Code value, the procedure searches for an existing customer with the same postal code. If such a customer is found, the City, State, and Country values from that record are displayed in the fields for the new record. The user can then update those fields.

r-defb.p
DEFINE BUFFER other-cust FOR Customer.

FORM
   Customer
   WITH FRAME cre-cust.
   
ON LEAVE OF Customer.Postal-Code
   DO:
      FIND FIRST other-cust WHERE other-cust.Postal-Code =
                                  Customer.Postal-Code:SCREEN-VALUE AND
                                  other-cust.Cust-num <>
                                  Customer.Cust-num NO-ERROR.
      IF AVAILABLE(other-cust)
      THEN DISPLAY other-cust.City @ Customer.City
                   other-cust.State @ Customer.State 
                   other-cust.Country @ Customer.Country
                   WITH FRAME cre-cust. 
      ENABLE Customer.City Customer.State Customer.Country
         WITH FRAME cre-cust.
   END.
   
CREATE Customer.
UPDATE Customer EXCEPT Customer.City Customer.State Customer.Country
   WITH FRAME cre-cust. 

The following gather a group of records so that the user can enter any table name and any set of record selection criteria and then look at the records in the table that meet those criteria.

r-defb2.p
DEFINE VARIABLE fname AS CHARACTER 
  FORMAT "x(12)" LABEL "Table name".
DEFINE VARIABLE conditions AS CHARACTER 
  FORMAT "x(60)" LABEL "Conditions".

REPEAT:
  /* Get the name of a table and, optionally,
    some record selection criteria */
  UPDATE fname COLON 12 conditions COLON 12
    WITH SIDE-LABELS 1 DOWN.
  HIDE ALL.
  IF conditions <> "" 
    /* Pass the table name and the record selection
       criteria as parameters */
  THEN RUN r-defb3.p fname "WHERE" conditions.
  ELSE RUN r-defb3.p fname.
END. 

The r-defb2.p procedure gets the name of a table (such as customer) and a condition (such as credit-limit > 4000) and passes them as arguments to the r-defb3.p procedure.

r-defb3.p
DEFINE NEW SHARED BUFFER rec FOR {1} PRESELECT.
DEFINE VARIABLE flist AS CHARACTER EXTENT 12.
DEFINE VARIABLE I AS INTEGER.
/* Look in _File the table named in the filename variable */
FIND _File "{1}".
/* Store the table’s field names in the first array */
FOR EACH _Field OF _File USE-INDEX _Field-posit:
  IF i >= 12 THEN LEAVE.
  i = i + 1.
  flist[i] = _Field._Field-name.
END.
/* Preselect records */
DO PRESELECT EACH rec {2} {3} {4} {5} {6} {7}
        {8} {9} {10} {11} {12}:
/* Pass the filenames and all field names to r-defb4.p */
RUN r-defb4.p "{1}" flist[1] flist[2] flist[3] 
       flist[4] flist[5] flist[6] 
       flist[7] flist[8] flist[9]
       flist[10] flist[11] flist[12].
END. 

The r-defb3.p procedure:

The r-defb4.p procedure has access to the rec buffer (and through it to the set of preselected records). This connection is made by using PRESELECT on the DEFINE SHARED BUFFER statement. The r-defb4.p procedure displays those records.

r-defb4.p
DEFINE SHARED BUFFER rec FOR {1} PRESELECT.

REPEAT:
  FIND NEXT rec.
  display {2} {3} {4} {5} {6} {7} {8} {9} {10} 
  {11} {12} {13} WITH 1 COLUMN 1 DOWN.
END. 

Because r-defb3.p and r-defb4.p use run-time argument passing, they cannot be precompiled. Having separate versions of r-defb4.p for each table and running the appropriate one in r-defb3.p, should improve response time. This approach is worthwhile if there are many lines of code in r-defb4.p a procedure.

If you define a NEW SHARED BUFFER in a procedure, then call a subprocedure that puts a record into that buffer, and display the buffer in the main procedure, Progress displays this message.

Missing FOR, FIND or CREATE for customer. 

This message is displayed when the FIND statement is not in the main procedure.

/* Main procedure */

DEFINE NEW SHARED BUFFER x FOR customer.
RUN proc2.p.
DISPLAY x. 

/* proc2.p */

DEFINE SHARED BUFFER x FOR customer.
FIND FIRST x. 

To avoid this, explicitly scope the customer record to the main procedure block.

/* Main procedure */

DEFINE NEW SHARED BUFFER x FOR customer.
RUN proc2.p.
DO FOR x:
  DISPLAY x.
END. 

NOTES

SEE ALSO

DEFINE PARAMETER Statement, RUN Statement, RUN STORED-PROCEDURE Statement


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