Release 10.1A: OpenEdge Development:
Progress 4GL Handbook

> ## Buffer handle methods

> There are many methods you can use to perform operations dynamically on a buffer handle, both for static and for dynamic buffers. These are all dynamic equivalents of static statements you’re already familiar with. The principal value of these methods is that they let you define selection criteria for data retrieval and other values needed by the methods at run time. In many cases, you can use these methods effectively with queries and buffers that are defined as static objects, where the table names are known at compile time. The example that follows the method descriptions shows how to extend the Customers and Orders windows to use these dynamic methods on the query and buffer for the Customer table. These are summary method descriptions to make you aware of what is possible in working with buffer handles. As always, consult the online help or OpenEdge Development: Progress 4GL Reference for complete descriptions.

> ##### BUFFER-FIELD method

> The `BUFFER-FIELD` method takes an argument, which can be either the name of a field or its ordinal position within the buffer, and returns the handle of that field object. You can then use the `BUFFER-FIELD` handle in turn to access various attributes of the field that are defined below. Note that `BUFFER-FIELD` is considered a method, rather than an attribute, only because it takes an argument to identify which field object you want. Beyond identifying the field, this method doesn’t really do anything except return its handle.

> ##### BUFFER-COMPARE and BUFFER-COPY methods

> These two methods on a target buffer handle take a source buffer handle (and other optional values) as an argument. `BUFFER-COMPARE` compares the field values in the two buffers and returns a report of their differences. `BUFFER-COPY` copies the field values in the source buffer to the target buffer.

> ##### BUFFER-CREATE, BUFFER-DELETE, and BUFFER-RELEASE methods

> These methods perform the same function as the `CREATE`, `DELETE`, and `RELEASE` statements do.

> ##### BUFFER-VALIDATE method

> This method verifies that a record in a buffer complies with mandatory field and unique index definitions. It corresponds to the `VALIDATE` statement.

> ##### Buffer FIND methods

> There is a whole set of methods you can use to perform a `FIND` operation on a buffer dynamically. Some of these include:

> - `FIND-BY-ROWID` — Takes a record RowID as an argument and reads that record into the record buffer. This method can be useful after a separate operation has recorded the RowID of a record using some other criteria and you wish to re-retrieve that record.

> - `FIND-CURRENT` — Re-reads the current record from the database, replacing the contents of the record buffer. This method can be useful if you want to refresh the record in case it has been changed, for example by another user, since it was originally read.

> - `FIND-FIRST` — Takes a `WHERE` clause (including the initial `WHERE` keyword) as an argument and retrieves the first record from the buffer’s table that satisfies the `WHERE` clause into the buffer.

> - `FIND-LAST` — Takes a `WHERE` clause as an argument and retrieves the last record from the buffer’s table that satisfies the `WHERE` clause into the buffer.

> - `FIND-UNIQUE` — Takes a `WHERE` clause as an argument that identifies a single record, and retrieves the one record from the buffer’s table that satisfies the `WHERE` clause into the buffer. If more than one record satisfies the `WHERE` clause, then no record is retrieved and the `AMBIGUOUS` buffer attribute is set to true.

> The `FIND` methods are a very useful and efficient way of identifying a single record without the overhead of preparing and opening a query with selection criteria that identify that one record, and then doing a `GET-FIRST()` to position the query cursor to that one record.

> In addition to the RowID argument for `FIND-BY-ROWID` and the `WHERE` clause argument for the `FIND-FIRST`, `FIND-LAST`, and `FIND-UNIQUE` methods, all five of these methods take optional arguments that you can use to specify the lock mode (`NO-LOCK`, `SHARE-LOCK`, or `EXCLUSIVE-LOCK`) and wait mode (if it is `NO-WAIT`). The default lock mode is `SHARE-LOCK`. You will generally want to change this to specify either `NO-LOCK` or `EXCLUSIVE-LOCK`, depending on whether you need to prepare to allow it to be changed and protect the record against changes by other users.

> This example changes the lock mode to `NO-LOCK`:

>     hBuffer:FIND-UNIQUE(“WHERE CustNum = 125”, NO-LOCK).

> This example changes the lock mode to `EXCLUSIVE-LOCK` and the wait mode to `NO-WAIT`:

>     hBuffer:FIND-UNIQUE(“WHERE CustNum = 125”, EXCLUSIVE-LOCK, NO-WAIT).

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