fsc2: 5.2 File handling functions

5.2 File handling functions

All the following functions are for opening files and writing data to these output files with different levels of user defined formatting. Please note that you don't have to explicitly open a file from the EDL script as long as you only are going to use a single output file - fsc2 will automatically ask for a file name the first time you try to write out data in this case.

Please note: under certain circumstances it is also possible to write data to stdout and stderr. To do so you must first either open a regular file via a call of e.g. the function get_file() or by explicitly opening stdout or stderr by a call of open_file() with the number 1 or 2 as the only argument (opening one of them this way will also automatically allow you to write to the other). If this has happened you then can use the numbers 1 and 2 as file handles for stdout and stderr.

List of all file handling functions:

`get_file()'
`get_gzip_file()'
`open_file()'
`open_gzip_file()'
`clone_file()'
`clone_gzip_file()'
`reset_file()'
`delete_file()'
`save()'
`fsave()'
`ffsave()'
`save_program()'
`save_output()'
`save_comment()'
`is_file()'
`file_name()'
`path_name()'

Descriptions of file handling functions:

`get_file()'

Opens a new file and returns a unique identifier for the file that can be stored in an integer variable. This variable can then be used in all the file output functions. Usually a file selector gets shown that lets the user choose a file. If opening the selected file fails the user is asked to select a different file name. If the user cancels the selection of a file (s)he is asked for confirmation since data may get lost.

The function accepts up to five arguments, all of them optional. The first one is usually the prompt string to be printed in the file selector. If it is missing or is the empty string (use `""' to create an empty string) it defaults to `Please select a file name:'. The second argument is a pattern for the file name, per default `*.dat'. You may use all the usual wildcard characters you're used to from the shell. The third argument is the directory searching for the file name starts in. As the fourth argument you may pass a file name to the function as the default file that appears in the entry for the selected file. Finally, the fifth argument can be a default extension for the file. This extension will be appended automatically to the name of the selected file unless that file name already has this extension. This way one can enforce an extension for the file name.

If get_file() has never been called on the first call to a file output function the user is asked to select a file and this file is used exclusively in all further calls of file output functions. This means that calling get_file() after the default file has already been opened is not allowed, it must be either called before the first output operation to a file or never at all!

In batch mode (i.e. if fsc2 got started with the '-B' option) no file select box gets shown because the script is supposed to be run without any user input. Instead the name of the EDL script is used as a template for the output files name, with all path information stripped off (so that the output file always goes into the current directory) and an extension of ".batch_output.#" appended, where the # stands for an integer number that is chosen so that the file name is unique. Numbers start with 0 and are incremented until a file name is found that does not exist yet. The resulting file name is then used as the output file.

This function can only be used in the EXPERIMENT section of an EDL script.

`get_gzip_file()'

This function accepts the exact same arguments as get_file(). The only differences are that the output is automatically compressed as with gzip, that the default file extension (for the optional second argument) is `*.dat.gz' instead of just `*.dat' and that in batch mode the output file will have an extra `.gz' appended. Please note: on case of a crash of the program the contents of the file will be unusable.

`open_file()'

This function is similar to get_file() with the main difference that one may specify an hard-coded file name in the script. The function will use its first argument as the file name and try to open this file. If the file already exists or can't be opened a warning will be shown and, on the user request, will show up a file selector to allow selecting a different file, just as the get_file() function does. Thus the arguments that the function accepts are identical to the ones of get_file() with the only exception that the first argument is an additional argument with a string for the file name.

This function can also be used to explicitly open stdout and stderr. To do so call the function with a single integer argument of 1 or 2 (this is not necessary if another regular file already has been opened since this automatically also opens stdout and stderr).

If running in batch mode (i.e. if fsc2 got started with the '-B' option) and the file to be opened already exists a new file name is created by appending the extension ".batch_output.#" to the file name specified as the argument. The # stands for an integer number that is chosen so that the file name is unique. Numbers start with 0 and are incremented until a file name is found that does not exist yet. The resulting file is used as the output file.

This function can only be used in the EXPERIMENT section of an EDL script.

`open_gzip_file()'

This function accepts the exact same arguments as open_file(). The only differences are that the output is automatically compressed as with gzip, that get_gzip_file() is used in case the file specified as the first argument already exists or can't be opened, and that in batch mode the output file will have an extra `.gz' appended Please note: on case of a crash of the program the contents of the file will be unusable.

`clone_file()'

Sometimes two output files are needed that should only differ in their extension but not in the filename. In this case the function clone_file() can be useful. It expects exactly three arguments. The first one is an identifier for an already existing file as returned by the functions get_file() or open_file(). If in the call of get_file() the user did not choose a file, i.e. pressed the Cancel button, it is silently assumed that also the new file to be created by clone_file() is not to be used. If either the number 1 (for writing to stdout) or 2 (for writing to stderr) was given as the argument a warning is printed out and the output gets written to either stdout or stderr.

The second and third arguments both have to be strings. The second argument is the extension of the file that was opened by the preceding call of get_file() or open_file(). The third argument is the replacement for the extension of that file. Both are to be specified without the starting dot. If the second argument does not fit with the extension of the file the user had chosen, the new extension from the third argument is simply appended to the file name (instead of replacing the old extension). If the replacement extension (i.e. the third argument) is identical to the second it is also appended instead of being used as a replacement.

A typical piece of code to open two files, the first with the extension dat and the second with the same name but the extension list would be:

FILE1 = open_file( "experiment.dat", "", "*.dat", "", "", "dat" );
FILE2 = clone_file( FILE1, "dat", "list" );

If the user chooses experiment.dat as the first file, a second file with the name experiment.list will be opened automatically.

The function also takes care that no files will be overwritten accidentally. If the second file already exists the user is asked to select different file. The program enforces that the extension of the new file is identical to the one passed to it as the third argument.

If running in batch mode (i.e. if fsc2 got started with the '-B' option) and the file to be opened already exists a new file name is made up by appending the extension ".batch_output.#" to the file name that got made up by the replacement procedure described above. The # stands for an integer number that is chosen so that the file name is unique. Numbers start with 0 and are incremented until a file name is found that does not exist yet. The resulting file is used as the output file.

This function can only be used in the EXPERIMENT section of an EDL script.

`clone_gzip_file()'

This function accepts the exact same arguments as clone_file(). The only difference is that the output is automatically compressed as with gzip. Please note: on case of a crash of the program the contents of the file will be unusable.

`reset_file()'

Under some circumstances it may be required to throw away everything already written to file until that moment. That can be achieved by calling this function. If there's only a single file that got opened automatically (by calling a function that writes to a file without calling open_file() before) then the function takes no argument. If a file got opened by a call of open_file() or similar then the function must be called with a single argument, the file handle for the file to be reset.

`delete_file()'

This function allows to delete an already opened file (e.g. if it has become obvious that the data written to it are useless). If there's only a single file that got opened automatically (by calling a function that writes to a file without calling open_file() etc. before) then the function takes no argument. If a file got opened by a call of open_file() or similar then the function must be called with a single argument, the file handle for the file to be deleted. Attempts to write further data to a deleted file will be silently disregarded.

`save()'

Writes one or more data or complete arrays to a file. Per defaul each value gets written into a separate line. But one often would like to have the elements of a 1-dimensional array (or 1-dimensional sub-arrays of a higher-dimensional array) written all into a single line, separated by a space, a comma or something else the tools one uses for data post-processing expect. In this case the first argument should be a string with this separator e.g. ", " if the elements of a line should be separated by a comma and a space.

The second argument must be given if somewhere before in the script a file was opened by using one of the functions for that purpose (e.g. get_file() or open_file()). These functions all return an integer file handle and that value has to be passed to save(). Alternatively, you can use the numbers 1 and 2 to write out the data to stdout or stderr. If no such function for opening a file was called before and you don't pass 1 or 2 the argument must be left out and he user will be asked to select the file the data are to be written to.

All arguments (following the file identifier if there's one) are data. The types of these data can be

Integer data
Floating point data
Strings (with interpretation of escape sequences, see fsave())
One-dimensional arrays (or slices of more-dimensional arrays) of integer or floating point type
Complete more-dimensional arrays

If a separator is not specified the function saves data with each data value being written with a new line character appended to it. In the case of more-dimensional arrays an empty line is output between the individual slices of the array. Here's an example: The array

X[ 3, 2 ] = { { 1, 2 }, { 3, 4 }, { 5, 6 } }
save( X );

will output

while

X[ 3, 2 ] = { { 1, 2 }, { 3, 4 }, { 5, 6 } }
save( ", ", X );

will result in outputs

1, 2
3, 4
5, 6

This function is suitable for storing large amount of data, all other functions that accept formatting information are comparatively slow since they have to analyze the format string for each call (and don't allow to output arrays in a single call).

The function returns the total number of characters that have been written to the file and it can only be used in the EXPERIMENT section of an EDL script.

`fsave()'

This function (the name stands for 'formatted save') can be used to write data to a file in a user defined format. The first argument must be a file identifier if any of the functions for opening a file has been called before, using that functions return vakue (or the numbers 1 and 2 can be used to write to stdout or stderr). If no such function has been called (and you don't use 1 or 2) this argument must be left out and you will be asked to select a file.

The next argument must be a format string with a syntax remotely similar to the one for the C printf(3) function. The format string can contain arbitrary text and conversion specifiers, a # character for each data item from the remaining argument list. In contrast to the save() function this function can not be used to print array slices or complete arrays, but only simple data types. On the other hand, printing of complete arrays can be done using loops, i.e. as in the following example:

VARIABLES:

FILE_ID;
I; J;
X[ 3, 2 ] = { 1, 2, 3, 4, 5, 6 };

EXPERIMENT:

FILE_ID = get_file( );

for I = 1 : 3 {
    for J = 1 : 2 {
        fsave( FILLE_ID, "X[ #, # ] = #\n", I, J, X[ I, J ] );
    }
}

This will print:

X[ 1, 1 ] = 1
X[ 1, 2 ] = 2
X[ 2, 1 ] = 3
X[ 2, 2 ] = 4
X[ 3, 1 ] = 5
X[ 3, 2 ] = 6

Within the format string and the argument strings escape sequences, all starting with a backslash character \, can be used to print otherwise unprintable characters. These are

`\a': prints an alert (bell) character (0x07)
`\b': prints a backspace character (0x08)
`\f': prints a form-feed character (0x0C)
`\n': prints a newline character (0x0A)
`\r': prints a carriage return character (0x0D)
`\t': prints a horizontal tab character (0x09)
`\v': prints a vertical tab character (0x0B)
`\\': prints a backslash \
`\?': prints a question mark ?
`\'': prints a single quote '
`\"': prints a double quote "
`\ooo': replaces the octal number ooo by the corresponding character (as many octal digits are used as long as the resulting number is less then 255)
`\xhh': replaces the hexadecimal number hh by the corresponding character (there must be one or two hexadecimal digits)
`\#': prints a # (this is a special escape sequence to be used with fsave() only)

The function returns the total number of characters that have been written to the file.

This function can only be used in the EXPERIMENT section of an EDL script.

`ffsave()'

This function can also be used to write data into a file using a format string. In comparison to the fsave() function it gives you even more control over the format that is used by accepting a format string that is nearly identical to the one of the C printf(3) family of functions, missing only some elements that wouldn't make sense here. As in the case of the save() and fsave() function the first argument can be a file identifier.

The format string may contain two types of objects: ordinary characters, which are copied to the file, and conversion specifications, each of which conversion and printing of the next successive argument. Each conversion specifier begins with the character % and ends with a conversion character. In between there may first a flag, which modifies the specification:

- which specifies left adjustment of the converted argument in its field,
+ which specifies that a number will always printed with a sign,
space: if the first character is not a sign, a space will be prefixed,
0: for numeric conversions, specifies padding the field with leading zeros,
#, which specifies an alternate output form: for e, E, f, g and G, the output will always have a decimal point, for f and G, trailing zeros will not be removed.

Following the flags the minimum field width as well as the precision can be specified. If the (optional) flags are followed by a number it is taken as the minimum field width. The converted argument will be printed in a field at least this wide, and wider if necessary. If the converted argument has fewer characters than the field width it will be padded on the left (or on the right, if left adjustment has been requested) to make up for the field with. The padding character normally is the space character except and only 0 if the zero padding flag is present.

The next character can be a period, which separates the field width from the precision, followed by another number, the precision, that specifies the maximum number of characters to be printed from a string, or the number of digits to be printed after the decimal point for e, E, or f conversion, or the number of significant digits for g or G conversion, or the minimum number of digits to be printed for an integer (leading 0s will be added to make up the necessary width).

Width or precision or both may be specified as *, in which case the value is computed by converting the next arguments(s), which must be an integer values.

In contrast to the C printf(3) format string no length modifier can be used - fsc2 has no different short, long or long long variable types.

The following table lists all conversion characters. If the character found in the format string is not a valid conversion specifier the function will abort and print an error message.

`d, i': Integer value, if the argument is not an integer but a floating point number its value is rounded to the next integer.
`f': floating point value, if the argument is an integer it is converted to a floating point value; decimal notation of the form [-]mmm.ddd, where the number of d's is specified by the precision. The default precision is 6; a precision of 0 suppresses the decimal point
`e, E': floating point value, if the argument is an integer it is converted to a floating point value; decimal notation in either the form [-]mmm.dddddde[+-]xx or [-]mmm.ddddddE[+-]xx, where the number of d's is specified by the precision. The default precision is 6, a precision of 0 suppresses the decimal point.
`g, G': floating point value, if the argument is an integer it is converted to a floating point value; %e or %E is used if the exponent is less than -4 or greater than or equal to the precision, otherwise %f is used. Trailing zeros and a trailing decimal point are not printed.
`%': no argument is converted, prints a %

The format string as well as argument strings may contain escape sequences, starting with a backslash \, see fsave() for the complete list.

The function returns the total number of characters that were written to the file.

This function can only be used in the EXPERIMENT section of an EDL script.

`save_program()'

This functions writes the currently run EDL script into a file. As usual, the first argument may be a file identifier - the same rules apply as for save() and fsave(). The second argument can be a string that is prepended to each line of the script, i.e. a comment character to make other programs like MATHLAB or octave skip these lines.

If #INCLUDE statements are found in the EDL script also the included files get saved into the output file, embedded into the text of the script.

This function can only be used in the EXPERIMENT section of an EDL script.

`save_output()'

This function has the same arguments as save_program() but prints the content of the output window (i.e. the bottom browser window in the main form) into the file.

This function can only be used in the EXPERIMENT section of an EDL script.

`save_comment()'

This function is used to print comments into the file. When it is called a small editor is shown and the user may enter comments. These will be then written into the file.

The first argument may as usual be a file identifier (or may be missing if get_file() hasn't been called). The second argument is again a string to be prepended to each line of the comment. The third argument is a preset string that appears in the comment editor when it is opened - use "\n" to separate the lines of a multi-line text. The last argument is the label string to be shown on top of the editor - it defaults to "Please enter a comment:".

This function can only be used in the EXPERIMENT section of an EDL script.

`is_file()'

Function returns if a file handle passed to it as the only argument is an opened file, returning 1 if it is an open file and 0 otherwise. stdout and stderr are treated as open files.

`file_name()'

Function returns the name of an opened file (without the path information). If open_file() or get_file() haven't been called but one of the function for writing a file so that a single output file is open the function can be called without an argument and the name of the unique open output file is returned (and when no file has been opened a warning is printed and the function returns the string "null"). Otherwise the function requires a valid file handle as it's argument and the function returns the name of that file. If the file number corresponds to stdout or stderr the name returned is the string "stdout" or "stderr".

`path_name()'

Function like file_name(), but returning the file name with full path information for an opened file. In case that the function is called without an argument and no file has been opened yet a warning is output and the string "/dev/null" is returned.

This document was generated by Jens Thoms Toerring on September 6, 2017 using texi2html 1.82.