README File for FileIO Wingz External
		 Version: @(#)FILEIO.README	2.1.2.1	95/05/11
     copyright 1994, Investment Intelligence Systems Corporation

FileIO is an example of a Wingz external that allows arbitrary
read/write access to files using C language calls.

FileIO is not production quality code and is provided "as is" as an aid
to programmers who may wish to write externals providing similar
capabilities. FileIO carries no warranties at all, users are urged not
to employ the code as it stands but purely to use it as an aid to
understanding external functions and file handling.

It was written under the AIX (Unix) operating system on an IBM RS/6000
machine. It should work with any Unix operating system albeit with
possibly minor modifications (particularly to the #include
statements). It should be relatively straightforward to port to any
operating systems that support the open(), close(), read(), write()
and lseek() system calls.

FileIO exports the following functions to Wingz:

NumLines:
	syntax: NumLines(filename)
	returns: the number of lines in the file

OpenFile:
	syntax: OpenFile(filename,mode)
		mode may be "r" for read-only, or "w" for read/write
	returns: integer file handle for use by following commands or
		-1 if file cannot be opened

CloseFile:
	syntax: CloseFile(handle)
	returns: 1 on success, 0 on failure
	Closes a file descriptor created by OpenFile()

ReadFile:
	syntax: ReadFile(handle)
	returns: a text string of max 254 characters, read from
		the current file position until the next linefeed.
		Leaves the file pointer at the next character to
		be read (after the linefeed).

WriteFile:
	syntax: WriteFile(handle,string)
	returns: 1 on success or 0 if error
		The string is written at the current file position
		and a linefeed is appended. The file pointer is left
		pointing at the following character.
GetBytes:
	syntax: GetBytes(handle,position,count)
	returns: string of count chars (max 254) or
		ERR 6 (Lookup Failed) if seek to position failed.
		The string is read starting position bytes into
		the file. The file pointer is left pointing at
		the following character.

PutBytes:
	syntax: PutBytes(handle,position,string)
	returns: 0 on success, or ERR 6 if seek to position failed.
		The string is written to the file starting position
		bytes into the file. NB a linefeed is not appended.
		The file pointer is left pointing at the following
		character.

FilePos:
	syntax: FilePos(handle)
	returns: current position in the file or ERR 6 if 
		seek to position failed.

Shell:
	syntax: Shell(command)
	returns: the return code from the command
		If the command is terminated by an '&' character
		the command is run in the background and Shell()
		returns 0 immediately. Otherwise Shell() waits until
		command completion.

POpen:
	syntax: POpen(command,mode)
	returns: File handle.
		Command specifies the command to run. Mode is "r"
		to read output from the command, or "w" to pipe
		input to the command. The file read and write commands
		can then be used on the returned handle.

PClose:
	syntax: PClose(handle)
	returns: 1 if handle is valid and close successful, else 0
		Should be used to close a file handle opened with the
		POpen() call.

Before accessing any of these functions, the FileIO external must first
be loaded using the following HyperScript command:

	GET EXTERNAL "FileIO"

The commands can then be accessed by prepending the function name with
FileIO:, ie to open a file (read-only):

	call FileIO:openfile("filename","r")