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.

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 ABL 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 object 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 does not 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. The BUFFER-COMPARE() method compares the field values in the two buffers and returns a report of their differences. The BUFFER-COPY() method 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. Note that indexing errors with these methods are treated differently than errors with other widget methods. Most widget method errors just return false and continue on. If there is an error when you use the BUFFER-CREATE(), BUFFER-DELETE(), and BUFFER-RELEASE() methods, an index error results and both the record and the index activity must be backed out together to avoid system errors in the database.

BUFFER-VALIDATE method

BUFFER-VALIDATE() 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).