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.

Examples

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