Programmer Guide/Shell Items/File/NEW FILE

NEW FILE

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

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

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.

/P

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 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