F.46 CtreeFlushFileXtd

---

Flush cache for specific files and groups of files.

Short Name

CTFLUSHX

TYPE

Function

DECLARATION

LONG CtreeFlushFileXtd(COUNT filno, NINT mode, LONG parm)

DESCRIPTION

CtreeFlushFileXtd extends CtreeFlushFile with mode and parm values to allow applications to flush cache for specific files and groups of files. Calling CtreeFlushFileXtd with mode and parm set to zero is identical to calling CtreeFlushFile(filno).

This function call causes files to be flushed by an asynchronous thread when the server physically closes the files.

The following mode options may be appropriately mixed and matched:

ctFLUSHX_ASYNC	Launch flush and return immediately
ctFLUSHX_ISAM	Treat filno as an ISAM data file and flush data and associated indices (only when filno!= -1)
ctFLUSHX_TRAN	Only flush TRNLOG and PREIMG files (filno == -1)
ctFLUSHX_NONTRAN	Only flush non-transaction files (filno == -1)
ctFLUSHX_SYSALL	Flush all files opened by system (filno == -1)
ctFLUSHX_USRALL	Flush all files opened by calling user (filno == -1)
ctFLUSHX_BYTES	Limit flush to specified number of bytes (parm holds the limit on the number of bytes to flush)
ctFLUSHX_PERCENT	Limit flush to specified percent of bytes (parm holds a percentage between 1 and 100)
ctFLUSHX_LAST	This option only applies to asynchronous flushes that do not attempt to flush all system files (ctFLUSHX_SYSALL which is the default when filno is passed in as a -1). When used, the asynchronous flush will only flush the file if the caller is the last (i.e., only) client to have the file open. This permits the client to terminate without concern that a file close will take an inordinate amount of time due to the close flushing all the file's buffers.

Not all combinations of these modes make sense. CtreeFlushFileXtd eliminates conflicting modes before attempting the flush. For example, supplying a valid filno and then specifying ctFLUSHX_TRAN, ctFLUSHX_NONTRAN, ctFLUSHX_SYSALL, and/or ctFLUSHX_USRALL is inconsistent. In this case the filno is used and the conflicting mode option is ignored.

RETURN

CtreeFlushFileXtd returns the handle, a positive LONG value, associated with a successfully launched asynchronous thread (if mode contains ctFLUSHX_ASYNC), NO_ERROR if CtreeFlushFileXtd completes successfully (no thread launched), or a negative error code in the case of a problem.

LIMITATIONS

The only option available with stand-alone applications is ctFLUSHX_ISAM.