CREATE BUFFER statement

Creates a dynamic buffer object.

Syntax

CREATE BUFFER handle FOR TABLE { table-name | table-handle | buffer-handle}
  [ BUFFER-NAME buffer-name ]
  [ IN WIDGET-POOL widget-pool-name ]

handle

A variable of type HANDLE that represents the handle of the buffer object.

FOR TABLE table-name|table-handle|buffer-handle

A character expression (table-name) that evaluates to a unique database table name or static temp-table name, a temp-table handle (table-handle), or to an existing buffer object handle (buffer-handle), each of which can specify the record source for which to create the buffer object.

If table-name is ambiguous, you must qualify the database table name with a database name or rename the temp-table. Otherwise, if the database table exists in multiple connected databases, the AVM creates the buffer in the first connected database.

BUFFER-NAME buffer-name

An expression of type CHARACTER that evaluates, at run time, to the name of the dynamic buffer you are creating. This option lets a dynamic query have multiple buffers for the same table.

IN WIDGET-POOL widget-pool-name

An expression of type CHARACTER that evaluates, at run time, to the name of the widget pool that contains the dynamic buffer.

Note: Widget pool names are not case-sensitive.

Example

The following example runs the query "for each customer" dynamically against the Sports2000 database using a purely dynamic buffer with no compile time references at all:

r-crtbuf.p

DEFINE VARIABLE ix AS INTEGER NO-UNDO.
DEFINE VARIABLE qh AS HANDLE  NO-UNDO.
DEFINE VARIABLE bh AS HANDLE  NO-UNDO.
DEFINE VARIABLE fh AS HANDLE  NO-UNDO EXTENT 10.

CREATE BUFFER bh FOR TABLE "Customer".
CREATE QUERY qh.

qh:SET-BUFFERS(bh).
qh:QUERY-PREPARE("FOR EACH Customer").
qh:QUERY-OPEN().
qh:GET-FIRST().

DISPLAY bh:NAME.

REPEAT ix = 1 TO 10:
  fh[ix] = bh:BUFFER-FIELD(ix).
  DISPLAY fh[ix]:NAME STRING(fh[ix]:BUFFER-VALUE).
END.

qh:QUERY-CLOSE().
bh:BUFFER-RELEASE().
DELETE OBJECT bh.
DELETE OBJECT qh.

The following code fragment shows several different ways you can create an alternate dynamic buffer for a static temp-table. Note the notation BUFFER tt1:HANDLE and TEMP-TABLE tt1:HANDLE for accessing the default buffer object handle and temp-table object handle, respectively, for the static temp-table, tt1:

DEFINE VARIABLE hbuf  AS HANDLE NO-UNDO. /* Default buffer object */
DEFINE VARIABLE htab  AS HANDLE NO-UNDO. /* Temp-table object */
DEFINE VARIABLE hbuf1 AS HANDLE NO-UNDO. /* 2nd non-default buffer object */

DEFINE TEMP-TABLE tt1 NO-UNDO
  FIELD x AS CHARACTER.

hbuf = BUFFER tt1:HANDLE.     /* Static temp-table's default buffer */
htab = TEMP-TABLE tt1:HANDLE. /* Static temp-table handle (not buffer) */

/* Different ways to create an alternate temp-table buffer */
CREATE BUFFER hbuf1 
  FOR TABLE BUFFER tt1:HANDLE.       /* From static tt's default buffer */
CREATE BUFFER hbuf1 FOR TABLE hbuf.  /* From static tt's default buffer */
CREATE BUFFER hbuf1 
  FOR TABLE TEMP-TABLE tt1:HANDLE.   /* From static tt's handle */
CREATE BUFFER hbuf1 FOR TABLE htab.  /* From static tt's handle */
CREATE BUFFER hbuf1 FOR TABLE "tt1". /* From static tt's name */

Notes

• If the character expression, table-name, identifies a temp-table defined as REFERENCE-ONLY, the statement sets handle to an unbound object that cannot function as a buffer object. To create a valid buffer object for such a table, use FOR TABLE table-handle or buffer-handle instead.
• Unless you need to use an alternate buffer, the most economical and cleanest way to obtain a buffer object handle for a table is to retrieve the handle for its default buffer. For example:

  DEFINE VARIABLE hbuf AS HANDLE NO-UNDO. DEFINE VARIABLE htab AS HANDLE NO-UNDO. DEFINE TEMP-TABLE tt2 NO-UNDO   FIELD x AS CHARACTER. CREATE TEMP-TABLE htab. htab:TEMP-TABLE-PREPARE( "dynTT" ). /* Obtaining the default buffer for a table */ hbuf = BUFFER Customer:HANDLE.     /* For a database table */ hbuf = BUFFER tt2:HANDLE.          /* For a static temp-table */ hbuf = htab:DEFAULT-BUFFER-HANDLE. /* For a dynamic temp-table */

See also

CREATE QUERY statement, DEFINE BUFFER statement