File Functions

The file functions include: Fname, Fopen, Fclose, Fread, Fremove, Fgets, Fputs, Frename, Gets, Create Dir, Active Dir List Dir.

Fname

This function obtains a file name from the user. The user is prompted to enter the name of: an existing file to open if the file open mode is "r", or a new file name if the file open mode is "w". This function returns the file name.

There are at least 3 parameters:

default file name - the default name of the file to use.
file open mode - file open mode to be used in fopen. Should contain "r" (read access) or "w" (write access).
prompt string - prompt string to describe the file.
optional type string - filter to select the type of file to open.

fname("default file name","open mode","prompt string"["type string"]);

theFile = fname("Scallop 1991.dat","r","Name of data file to read");
input = fopen(theFile,"r");
theRecord = fgets(input);
fclose(input);

See the example File Input/Output

Fopen

This functions opens an ASCII file for reading or writing (see Load_Data for reading binary files, and Overlay_File for binary overlay files). An existing file is opened if the file open mode is "r", or a new file is created or overwritten if the open mode is "w". This function returns the file identifier as a FILE number.

There are 2 parameters:

file name - the name of the file to open (the name must conform to the limitations of the operating system.
file open mode - file access mode ("r" =`read, "w" = write, or "wa" = write append).

file identifier = fopen("file name","open mode");

input = fopen("Scallop 1991.dat","r");
theRecord = fgets(input);
fclose(input);

See the example File Input/Output

Fclose

This function closes an existing file (opened by the fopen command). This function returns no result.

There is 1 parameter:

file identifier - the FILE number referencing the open file.

fclose(file identifier);

input = fopen("Scallop 1991.dat","r");
theRecord = fgets(input);
fclose(input);

See the example File Input/Output

Fread

This function reads a number of bytes of text from an existing file (opened by the fopen command). FREAD is used when you need to read a specific number of characters from a text file. Optionally you may read the data as an integer vector.
Fread() returns 0 on error.

There are 3 parameters:

file identifier - the FILE number referencing the open file. It's the unique ID number of the file the user wants to read data from.

number of bytes - number of bytes (or integers) the user wants to read.

format flag - type of data to read (0 = default is character string, 1 = integer vector).

fread(file identifier, number of bytes[,format type]);

FileNumber = fopen("Scallop 1991.dat","r");
FREAD(FileNumber, 200); //reads the next 200 bytes from the open file identified as FileNumber

Fremove

This function removes (deletes) an existing (closed) file from the disk. This function returns TRUE if the file was successfully deleted, or FALSE if the file was not deleted.

fremove("file name");

fremove("Scallop_1991.dat");

Fgets

This function reads the next record of an existing file (opened by the fopen command). This function returns the record as a character string.

There is 1 parameter:

file identifier - the FILE number referencing the open file.

fgets(file identifier);

input = fopen("Scallop 1991.dat","r");
theRecord = fgets(input);
fclose(input);

See the example File Input/Output

Create Dir

This function creates a file directory using the file path argument.

There is 1 parameter:

file path - a character string containing the file path to be created.

create_dir("file path");

create_dir("C:\newdir");


Active Dir

This function sets the current active directory for reading or writing files. The default active directory is the folder in which the acon executable resides. All internal ACON commands let you explictly provide a full path name when creating/reading a file. DLL_Cmd() is one case where you may need to change the active directory before calling an external DLL (e.g. when the external DLL uses the active directory without permitting a full file pathname).

There is 1 parameter:

file path - a character string containing the file path to be activated.

active_dir("file path");

active_dir("C:\Mydir");


Gets

This function gets a character string from stdin. It works on both Acon Console and Acon GUI versions and returns the input as a character string. With the console version, it will halt execution of your script and prompt for user input from the console DOS window. With the GUI version, it is redundant, as alternate ways of providing input are available.

There is no parameter.

Result = gets();

Here is how to use gets() on the GUI version:

x = gets(); // get the next line of the text as a string
This is a test // run these two first lines then print(x)
print(x);


Here is how to use gets() on the Console version:

puts("Enter your string:");
my_var=Gets();
puts(my_var);


Fputs

This function writes a character string to an existing file (opened by the fopen command). This function returns no result.

There are 2 parameters:

text string - the text string to write. You normally should include a carriage return as the last character of the string.
file identifier - the FILE number referencing the open file.

fputs("string",file identifier);

output = fopen("Scallop 1991.txt","w");
answer = 6321.5;
line = sprintf("%8.1f",answer);
fputs(cat(line,numtochar(13)),output);
fclose(output);

See the example File Input/Output

Fflush

This function flushes the buffers associated with an open file (opened by the fopen command), or stdlist. This function returns no result.

There is 1 optional parameters:

file identifier - the FILE number referencing the open file.

fflush(file identifier);

fflush(fileID);
fflush(); // flush stdlist, commonly used with web output.

Frename

This functions renames an existing file.This function returns a boolean value indicating if the file was sucessfully renamed.

There are 2 parameters:

old file name - the name of the file to rename.

new file name - the new name of the file.

boolean = frename("old file name","new file name");

result = frename("Scallop 1991.dat","Scallop_1991.txt");


List Dir

This function creates a character matrix which contains a list of file names found using the file path argument. Each row of the resultant matrix is padded with blank characters in those rows whose length is less than the maximum length in the matrix. This function supports wildcard characters.

There are 2 parameters:

file path - a character string containing the file path for which a list of files is to be returned.
recursive flag - a flag indicating whether the list is to include nested directories recursively (0 = default is no recursion, 1 = recursion).

cmat = list_dir("file path",recursive flag);

output = list_dir("C:/test/");
output = list_dir("C:/temp*/");


GetFileTime

This function returns either the file creation date or the last modified date of a file as a decimal julian date.

There are 2 parameters:

filename - a character string containing the full filename path for which the creation or modfication date is to be returned.
access flag - a flag indicating whether to return the creation or modification date (0 = default is creation date, 1 = modification date).

juliandate = GetFileTime("file path",access flag);

creationdate = GetFileTime("C:/myfile.dat");
print(ymd(creationdate));
2004 5 11 18 35