@NEW
Syntax
@NEW(FILE, <filename>, READ|WRITE|CREATE|APPEND)
@NEW(LIST {, SORTED})
@NEW(XMLDOC)
@NEW(JSON)
@NEW(ZIP)
@NEW(DRIVE)
Description
This function creates or opens an existing file, or creates a new string list, XML document or [VDS7] a JSON document or ZIP archive, and returns an identifier that can be used to access it in subsequent commands and functions.
[VDS7] Used as @NEW(DRIVE,<network path>[,<login>,<password>]), it instead mounts a network share and returns its access prefix (a drive letter such as Z: on Windows) rather than a numeric identifier; see Network drives.
When used to create or open a file, the required filename must be specified, together with the mode of access. The access mode may be:
| READ | File is opened with shareable read access. The file must exist. |
| WRITE | File is opened with read / write access. A new file will be created if it does not exist. |
| CREATE | A new file is created with write access. If a file of the same name exists, it is overwritten. |
| APPEND | File is opened with write access, and the pointer is positioned at the end of the file ready for appending. If the file does not exist, it will be created. |
When used to create a new string list, you may optionally specify whether the data is to be maintained sorted. (You may sort an unsorted list at any time using the LIST SORT command.)
String list and XML document types are only created in memory, so the appropriate LOADFILE subcommand must be used if it is required to load a file from disk at the outset.
OK
For @NEW(FILE, ...) may be set to false if the function fails (for example, a file does not exist or cannot be created, or the requested access cannot be granted.)
Example
%%myfile = @NEW(FILE,C:\DATA\MYFILE.DAT,WRITE)
%%mylist = @NEW(LIST)