FS_INIT

Initialize a file‑stack system

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall FS_INIT([filename], [channel][, size])

Arguments

filename

(optional) The name of the physical scratch file to be created and used for the file stack. (a)

channel

(optional) Returned with the file‑stack channel. (n)

size

(optional) The size (in bytes) of the memory to be allocated for the file‑stack cache. If not specified, the default is 16,384. (n)

Discussion

FS_INIT initializes a file‑stack system.

If filename is not passed, a filename in the form DTKTMP:XFSnnn.SCR will be used, where nnn is the value returned from the %JBNO routine.

The scratch file will be opened in output mode and the resulting Toolkit channel will be promoted to global status.

If channel is not passed, the default file stack will be initialized. If the default file stack has already been initialized, a fatal error occurs.

The scratch file will be opened with the TEMPFILE OPEN qualifier to ensure a unique scratch file for each call to the FS_INIT subroutine. The DTKTMP environment variable can be assigned to indicate where the file should be created. The file will be only created when the internal memory cache overflows.

The default file‑stack cache size can be specified with the environment variable DTKFSWINSIZ. This size specifies the amount of memory allocated by the file‑stack if no larger size is specified to FS_INIT, nor is subsequently needed by the file‑stack routines. Any value specified will be rounded up to the nearest multiple of 16,384 but not more than 114,688. Increasing the size may result in improved performance for applications that traverse a large number of records on the file stack (for example, large lists).

Examples

The following example will initialize a file‑stack system by creating a scratch file named pages.scr, and will return the virtual channel number in pgchn.

xcall fs_init("pages.scr", pgchn)