The command NEW FILE creates a new file item. File items are used to read and write files to disk. There are special SET commands to deal with different types of files (e.g. XML files or files using the 'section' format). The availability of these commands is dependant on the NEW FILE command variant which was used to create the item (see below).
See SET file for the SET commands and FILE Item Attributes for a list of attributes.
When you have finished with a file item, you can delete it with the command DELETE.
You should surround file names with inverted commas (e.g. NEW FILE * '$#fileName') if you cannot be sure that the file name is free of spaces. Otherwise, the command will fail, although the filename itself is valid.
General Options
The following options are available for all NEW FILE commands.
/G - turns automatic garbage collection on. If specified, the item is automatically deleted when exiting the macro.
/I - if set, error messages are suppressed, and warnings are generated instead.
File System Items
The following file items cannot access files on disk, but are useful for accessing system information about files and directories.
NEW FILE name /File [ /G ]
Create a file item that can be used for file-system functions (STATUS, RENAME (=move), COPY, DELETE), but cannot access the content of a file.
name
The parameter name is a unique identifier for this item within the shell. If you pass an asterisk, the identifier is automatically generated and stored in the local variable #new.
NEW FILE name /List [ /G ]
Create a file item that can be used to search for files or list directories/files (FIND, NEXT), but cannot access the content of a file.
name
The parameter name is a unique identifier for this item within the shell. If you pass an asterisk, the identifier is automatically generated and stored in the local variable #new.
Text Files
NEW FILE name fileName /Text /Read|Write|Append [ /G ]
Create a new file item to access a file in text mode.
name
The parameter name is a unique identifier for this item within the shell. If you pass an asterisk, the identifier is automatically generated and stored in the local variable #new.
fileName
The name of a file on disk containing plain ASCII text. This can be an absolute or a relative path.
/Text
This option is mandatory when creating a text file.
/Read|Write|Append
One of these options is mandatory. The option /Read opens a file in read-only mode. The option /Write creates a new file if fileName does not exist or overwrites the existing file. The option /Append creates a new file if the file fileName does not exist or appends new data to an existing file.
Example:
#f := new file * 'afile.txt' /Text /Append
Create a new file item referencing the text file 'afile.txt' in the present working directory. Save the unique automatically generated shell item id in the variable #f.
Section Files
NEW FILE name fileName /Section [ /G ]
Create a file item to access a file in section mode. A section file consists of sections marked by a section header ([sectiontype {sectionname}]). Use the macros SECTIONFILE and SOURCEFILE for section-file access.
name
The parameter name is a unique identifier for this item within the shell. If you pass an asterisk, the identifier is automatically generated and stored in the local variable #new.
fileName
The name of a file on disk. This can be an absolute or a relative path.
/Section
This option is mandatory when creating a section file.
XML Files
NEW FILE name [ fileName ] /XML [/Load] [/Exclusive] [ /G ]
Create an XML file item. If a fileName is specified, it must refer to an existing and valid XML file on disk, otherwise the NEW command will fail. If the option /Load is used, the content of the file is loaded and parsed and the root element is selected, otherwise the document is empty.
name
The parameter name is a unique identifier for this item within the shell. If you pass an asterisk, the identifier is automatically generated and stored in the local variable #new.
fileName
If a file name is specified, then this is used for loading and saving the file (unless overridden).
/XML
This option is mandatory when creating an XML file.
/Load
Load the contents of the XML file specified by fileName from disk
/Exclusive
If this flag is used, the file will be locked to all other users and programs until the item is deleted.
Binary Files
NEW FILE name fileName /Binary [ /Read ] [ /Delete ] [ /G ]
Create a new binary file item.
name
The parameter name is a unique identifier for this item within the shell. If you pass an asterisk, the identifier is automatically generated and stored in the local variable #new.
fileName
The path to the file on disk.
/Binary
This option is mandatory when creating a binary file.
/Read
Use this option to open the file in read-only mode. Otherwise the file is opened in read/write mode.
/Delete
Use this option to delete the contents of the file. This option is only possible in read/write mode.
GDX Files
NEW FILE /Y name fileName [ format rows columns ] [ /D ]
Create a GDX file. If the file does not yet exist, the format, rows and columns parameters are mandatory.
name
The parameter name is a unique identifier for this item within the shell. If you pass an asterisk, the identifier is automatically generated and stored in the local variable #new.
filePath
The path to an existing GDX file on disk.
format
The following data formats are supported:
1 - short
2 - int
3 - float
4 - double
Note that if the file fileName does not exist, then this parameter is mandatory.
rows
The number of data rows.
columns
The number of data columns.
/D
If specified the contents of the file are deleted (if the file already exists). Note that the contents cannot be deleted if the file is currently being accessed.
Example:
#gdxfile := new file /Y * 'test.gdx' 4 1024 1000