CREATE BUFFER statement


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

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

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.

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.

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.

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.

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 */

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 */

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 */

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 */