Programmer Guide/Shell Items/File/NEW FILE

File Item
INTRODUCING	NEW	SET	ATTRIBUTES	EXAMPLES

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 (apostrophes, e.g. NEW FILE * '$#fileName') if you cannot be absolutely 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 respective execution context (macro).
/I	if set, error messages are suppressed, and warnings are generated instead.

File System Items (Dummy Files)

The following command will create a dummy file item, also called file system item. Such dummy files do not represent actual disk files and, hence, cannot be used for reading and writing to disk. Instead, they allow access to 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.

List File Items (Searching for Files and Directories)

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 ] [ /P ] [ /C ]

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 or /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.
/P	If the option /P is specified, the text file is processed by the STx macro preprocessor. See preprocessed_file_io_example.sts for details.
/C	If the option /C is specified, the STx continuation character "`" will be recognised as a line continuation character. Otherwise, it will be treated like any other character.

Example

#f := new file * 'afile.txt' /Text /Append

This statement will create a new file item referencing the text file "afile.txt" in the present working directory. The unique internal shell item ID for the file item is to be generated automatically (*). This ID is then assigned to the shell variable #f.

Section Files

NEW FILE name fileName /Section [ /G ] [ /P ] [ /C ]

Create a file item to access a section file. A section file is a text file consisting of sections each starting with a section header ([sectiontype {sectionname}]), similar to the well-known Windows ".INI" files. Use the macros SECTIONFILE and SOURCEFILE for operating on section files.

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.
/Preprocess	If the option /P is specified, the section file is processed by the STx macro preprocessor. See preprocessed_file_io_example.sts for details.
/C	If the option /C is specified, the STx continuation character "`" will be recognised as a line continuation character. Otherwise, it will be treated like any other character.

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 meaning that no other users and programs may access the file until the file item is deleted.

Binary Files

NEW FILE name fileName /Binary [ /Read ] [ /Delete ] [ /G ]

Create a new binary file item.

name	parameter name is a unique identifier for this item within the shell. If you pass an asterisk, a unique identifier will be generated automatically. This unique identifier will be stored in the local variable #new. Either way, the command returns the identifier of the file item, meaning that you can assign it to an STx variable.
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 (i.e., shell item ID) for this item within the shell. If you pass an asterisk, a unique identifier is automatically generated. In this case, it will be stored in the local variable #new. Either way, the statement will return the unique identifier so that you can assign it to a shell variable.
filePath	The path to an existing GDX file on disk. This should be quoted and, indeed, must be quoted if containing space characters.
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.
/Delete	If specified, the contents of the file are deleted (provided that 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