The implicit reading of the input file and the writing to the output (using PRINT and PRINTLN) could be not enough to deal with particular situations.
The functions in this category allow to operate with different text or binary files, in a way very similar to other programming languages: open the file and use the returned handle for all the following operations.
In this chapter you will also find the functions to read and write to standard input/output.
The character separating directories from file names depends on the interpreter version; by using the command line parameter -k it is possible to automatically convert file names, without modifying the script (at least for this aspect).

The functions are divided in the following classes:

• functions using handles;
• functions on standard input;
• functions without handles;
• dictionary functions;
• directory functions.

Functions with handles:

FOPEN(cPathName, nMode)

opens cPathName in nMode and returns its handle; returns -1 in case of error; cPathName can include a path; nMode is the binary OR of the following values (see common.prt):

Constant	Value	Meaning
FO_READ	1	open for reading only
FO_WRITE	2	open for writing only
FO_RDWR	4	open for reading/writing
FO_CREATE	8	create the file if it does not exist
FO_TRUNC	16	truncate the file if it exists

FSEEK(h, nOffset, nFromWhere)

changes the position of the pointer on the file corresponding to the handle h; the new position is nOffset from nFromWhere. This function returns the new offset from the beginning of the file (on success) or -1 (wrong handle); the values allowed for nFromWhere are (see common.prt):

Constant	Value	Meaning
SEEK_SET	0	from the beginning
SEEK_CUR	1	from the current position
SEEK_END	2 (or other)	from the end

FREAD(h, nBytes)

returns a string of nBytes, which is read from the current position of file h; if less than nBytes bytes are left, the result is shorter than nBytes; if the handle is invalid or the pointer is at End-Of-File, an empty string is returned

FCLOSE(h)

closes the file corresponding to the handle h and frees the handle; returns 0 on success, -1 otherwise

FEOF(h)

returns 1 if the file pointer is at EOF, 0 otherwise; if the handle is invalid, returns -1

FGETC(h)

reads and returns a single character from the file h; same as FREAD(h, 1)

FWRITE(h, exp)

writes the string exp at the current position on file h; returns the number of characters written, or -1 in case of error

FWRITELN(h, exp)

writes the string exp, followed by the variable EOL, at the current position on file h; returns the number of characters writter, or -1 in case of error

FSIZE(h)

returns the size of the file h, -1 if the handle is invalid

FRESIZE(h, nBytes)

changes the size of file h to nBytes (which can be greater than or lesser than the current size); returns the previous size, -1 in case of error

FREADLN(h)

reads up to the line terminator and returns the contents of the line (without the terminator); works on Dos, Macintosh™ and Unix™ files. At the end, the file pointer is positioned at the beginning of the next line. This function assumes that, on call, the file pointer is already positioned at the beginning of a line. If the handle is invalid (or the pointer is at EOF), the function returns an empty string.

Functions on standard input:

STDEOF()

returns 1 if we are at the end of the standard input, 0 otherwise

STDGETCH()

returns a string with the next character from the standard input, an empty string at EOF; same as STDREAD(1)

STDUNGETCH(c)

re-inserts the character c in the standard input; returns its ASCII code if the function is successfull, -1 otherwise

STDREAD(nBytes)

reads up to nBytes from the standard input and returns the string, which can be shorter if EOF is encountered

STDREADLN()

reads a line from the standard input; returns an empty string if at EOF

Functions without handles:

TRUENAME([@]cPathName)

returns the true name of cPathName, by substituting '.' and '..'; under Windows™, short names (Dos 8.3) are transformed to the corresponding long names. The function returns an empty string if cPathName could not be resolved.
Note: this function is not useful for checking if a file or directory exists (use ISFILE for this purpose); it returns a qualified pathname even for non-existing files, if the directory before the last name exists

LONGNAME([@]cPathName)

returns the long name for cPathName, or an empty string on error; this function is specific to the Ms-Dos™/Windows™ version of Proteus

SHORTNAME([@]cPathName)

returns the short name for cPathName, or an empty string on error; this function is specific to the Ms-Dos™/Windows™ version of Proteus

FREMOVE(cPathName)

removes cPathName; returns 0 on success, -1 otherwise

FRESET(cPathName)

changes the size of cPathName to 0 (but does not remove it); returns the previous size or -1 (file not found/error)

FINSERT(cPathName)

writes the contents of cPathName to output and returns the number of lines copied; the lines are terminated by EOL

FAPPEND(cPathName, c)

writes c at the end of cPathName and returns the number of bytes written (-1 on error); FAPPEND does not append line terminators - append EOL to c when working with text files

FSAVE(cPathName, c)

writes c to cPathName, which is created or truncated (if it exists); returns the number of bytes written (the length of c) or -1 in case of error

FLOAD(cPathName)

returns the contents of cPathName as a single string; no conversion is done on the contents; returns an empty string on error

FRENAME(cOldPathName, cNewPathName)

renames cOldPathName to cNewPathName; this function can also be used to move files from one directory to another (on the same disk, under Ms-Dos™/Windows™); returns -1 on error, 0 otherwise

FCOPY(cSourcePathName, cDestPathName)

copyes cSourcePathName to cDestPathName; returns -1 in case of error, 0 otherwise

DRIVEGET()

returns the current drive, in the form "A:"; this function is specific to the Ms-Dos™/Windows™ version of Proteus

DIRGET(cDrive)

returns the current directory on cDrive (in the format "A" or "A:"); under Unix™, this function has no parameters: DIRGET(). In case of error, it returns an empty string; on success, returns the directory (which includes the drive under Dos/Windows™)

DIRSET(cPath)

changes the current directory to cPath; under Dos/Windows™, changes the current drive to the one specified; returns 0 on success, -1 on error

DIRMAKE(cPath)

creates the directory cPath; returns 0 on success, -1 on error

DIRREMOVE(cPath)

removes the directory cPath; returns 0 on success, -1 on error

ISFILE(cPathName)

determines if the file/directory cPathName exists; returns one of the following values (see common.prt):
 

Constant	Value	Meaning
ISFILE_ERR	0	does not exist or cPathName is wrong
ISFILE_FILE	1	exists as a file
ISFILE_DIR	2	exists as a directory
ISFILE_LINK	3	exists as a symbolic link (only Unix™ version)

No wildcards ('*' or '?') are allowed in pathname

TEMPNAME()

returns a temporary file name

MKTEMP([@]cMask)

returns a unique filename determined from the string cMask, which must be a valid path that ends with 6 characters X; e.g. "C:\TEMP\XXXXXX"

FATTRIB(cPathName)

returns the attributes of the file matching cPathName (which can be a file, a directory or a symbolic link), -1 in case of error; this function returns different values according to the version of the interpreter.
Under Ms-Dos™/Windows™, the value returned is the binary OR of the following numbers (see common.prt):

Constant	Value	Meaning
ATTR_RDONLY	1	read-only
ATTR_HIDDEN	2	hidden
ATTR_SYSTEM	4	system file
ATTR_DIRECTORY	16	directory
ATTR_ARCHIVE	32	archive

Under Unix™, the result is the OR of the following values:

Constant	Value	Meaning
ATTR_USREXE	1	execute (user)
ATTR_USRWRITE	2	write (user)
ATTR_USRREAD	4	read (user)
ATTR_DIRECTORY	8	directory
ATTR_LINK	16	symbolic link
ATTR_GRPEXE	32	execute (group)
ATTR_GRPWRITE	64	write (group)
ATTR_GRPREAD	128	read (group)
ATTR_OTHEXE	256	execute (other)
ATTR_OTHWRITE	512	write (other)
ATTR_OTHREAD	1024	read (other)

CHMOD(cPathName, nFlags)

sets the attributes of cPathName to nFlags: returns 0 on success, -1 on error; under Unix™, nFlags is a string of three octal numbers, from "000" to "777", which represents the access rights to the file for the owner, the group and the other users, respectively; every digit is the sum of the following values (see common.prt):
  

Constant	Value	Meaning
RIGHT_EXE	1	execute right
RIGHT_WRITE	2	write access
RIGHT_READ	4	read access

Under Dos/Windows™, nFlags is the binary OR of the following values:

Constant	Value	Meaning
ATTR_RDONLY	1	read-only
ATTR_HIDDEN	2	hidden
ATTR_SYSTEM	4	system file
ATTR_ARCHIVE	32	archive

LINK(cPathName, cLinkPath)

creates in cLinkPath a symbolic link to cPathname; this function is specific to the Unix™ version of Proteus

UMASK(cNewMask)

sets the umask for the process to the specified value, represented by a string of three octal digits (from "000" to "777"); this function returns the previous value, in the same format. For further information, see the predefined variable FILE_MASK; this function is specific to the Unix™ version of Proteus

Dictionary functions:

A dictionary file is a text file whose lines have the following format:

label1:string1
label2:string2
.. 

Each line begins with a label followed by ':' and a string of data.
Dictionary files are useful to store configuration data and small data bases. Since the information is not indexed, every search is done sequentially: as the size of the dictionary increases, the search time increases in a linear way.
Every label can be at most 80 character long.

DICLOOKUP(cLabel, cPathDictionary)

returns the string in cPathDictionary associated to cLabel; if cLabel is missing or cPathDictionary does not exist, returns an empty string

DICUPDATE(cLabel, exp, cPathDictionary)

sets to exp (interpreted as a string) the value for cLabel in cPathDictionary; if the file does not exist, it is created; if exp is empty, the definition is removed from the dictionary; this function returns one of the following values (see common.prt):

Constant	Value	Meaning
DIC_ERROR	0	error
DIC_ADDED	1	the definition was added
DIC_MODIFIED	2	the definition was modified
DIC_REMOVED	3	the definition was removed

The string exp cannot include the characters '\r' or '\n'; use the functions CINVTRAN and CTRAN as a filter, to store strings over the full ASCII set.

DICTRAVERSE(cPathDictionary, udffunction)

allows to scan the file cPathDictionary, invoking udffunction for every definition; the UDF must accept exactly two parameters (label, data) and return 0 (continue with the following item) or 1 (stop traversing the dictionary); DICTRAVERSE returns -1 if the dictionary file was not found, 0 if it was completely traversed, 1 if the UDF requested to stop

DICTOAVL(cPathDictionary)

creates an AVL tree containing all the definitions in cPathDictionary; it returns:

• -2 dictionary file not found
• -1 empty dictionary
• aHandle (handle of the AVL)

DICFROMAVL(cPathDictionary, aHandle)

writes to cPathDictionary the contents of the AVL tree corresponding to aHandle (in-order crossing); if the file exists, it is overwritten. The function returns:

• -1 wrong handle
• 0 could not create the dictionary file/write error
• 1 success

The line terminator corresponds to EOL. All the labels longer than 80 characters are truncated

DICMATCH2AVL(cPathDictionary, rExp)

creates an AVL tree including all the definitions from cPathDictionary whose label satisfies the simple regular expression rExp; the comparison is case-sensitive. Returns:

• -2 file not found
• -1 no definition satisfies the expression
• aHandle (handle of the AVL tree).

DICIMATCH2AVL(cPathDictionary, rExp)

creates an AVL tree including all the definitions from cPathDictionary whose label satisfies the simple regular expression rExp; the comparison is case-unsensitive. Returns:

• -2 file not found
• -1 no definition satisfies the expression
• aHandle (handle of the AVL tree).

DICREXMATCH2AVL(cPathDictionary, xExp)

creates an AVL tree including all the definitions from cPathDictionary whose label satisfies the extended regular expression xExp; the comparison is case-sensitive. Returns:

• -3 incorrect extended regular expression
• -2 file not found
• -1 no definition satisfies the expression
• aHandle (handle of the AVL tree).

DICREXIMATCH2AVL(cPathDictionary, xExp)

creates an AVL tree including all the definitions from cPathDictionary whose label satisfies the extended regular expression xExp; the comparison is case-unsensitive. Returns:

• -3 incorrect extended regular expression
• -2 file not found
• -1 no definition satisfies the expression
• aHandle (handle of the AVL tree).

Directory functions:

DIROPEN(cPathSpec, nFlags)

allocates a search structure; returns the handle to the structure, or -1 in case of error (invalid cPathSpec or no file found); use DIRCLOSE on the handle as soon as the search is over; nFlags is represented by the binary OR of the following values (see common.prt):

Constant	Value	Meaning
DO_FILE	1	include files
DO_DIRECTORY	2	include directories
DO_DOT	4	include the special directory "." (DO_DIRECTORY is implicit)
DO_DDOT	8	include the special directory ".." (DO_DIRECTORY is implicit)
DO_LINK	16	include symbolic links (Unix™ specific, DO_FILE and DO_DIRECTORY are implicit)

DIRNEXT(yHandle)

finds the next matching file; when DIROPEN returns a value different from -1, a value is already loaded and can be retrieved by using DIRLAST; DIRNEXT should be used only after having used this value; this function returns:

• 0 no other file matching;
• 1 file found;
• -1 invalid yHandle

DIRLAST(yHandle, nField)

returns the specified field, retrieved by the last call to DIRNEXT or DIROPEN; if an invalid handle or field is specified, the function returns an empty string ("" = 0 = 0.0). The allowed fields are (see common.prt):

Constant	Value	Meaning
DL_NAME	1	name
DL_SIZE	2	size (bytes)
DL_MDATE	3	last update (date)
DL_MTIME	4	last update (time)
DL_ATTRIB	5	attributes (see FATTRIB)
DL_CDATE	6	creation date
DL_CTIME	7	creation time
DL_ADATE	8	last access date
DL_ATIME	9	last access time

The fields 6-9 are specific to Windows™ and Unix™. Time format follows TIME_TYPE; ':' is used for separator. Date format follows DATE_TYPE; '/' is used for separator and the year is expressed in short form according to EPOCH

DIRCLOSE(yHandle)

closes the search handle, freeing the information maintained for DIRLAST; this function should be invoked when the search is over; the function returns 0 on success, -1 if the handle is invalid