File System

Introduction

Interface

Block commands

Load Binary File (QB comp.)

BLOAD filespec [,address]

Loads a specified memory-image file into memory.

filespec

A string expression that follows OS file naming conventions; may include any device, except "KYBD:".

address

Specifies the memory address at which filespec is loaded. If address is not specified, the address of BSAVE is used.

Save a Binary File (QB comp.)

BSAVE filespec, address, length

Copies a specified portion of memory to a specified file.

filespec

A string expression that follows OS file naming conventions; may include a device name and path.

address

Specifies the address from which the memory image will be saved.

length

Specifies the number of bytes to be saved.

Loads a Text File

TLOAD filespec {INTO | , } variable [{ {AS ARRAY| AS STRING} | , type}]

Loads a whole text-file into memory.

filespec

A string expression that follows OS file naming conventions.

address

Specifies the memory address at which filespec is loaded. If address is not specified, the address of BSAVE is used.

type

It can be 0 for array or 1 for string. The default is to build an array from text-lines. The other way is to load as a string.

Notes:
In the case of 'string', the CR/LFs must be converted to Unix style which is the default.

In the case of 'array', the CR/LFs must removed.

Saves a Text File

TSAVE filespec {FROM | ,} variable

Creates a text file and stores the contents of 'variable'.

filespec

A string expression that follows OS file naming conventions.

variable

Data to be written. If the variable is an array, each element represents a text line.

Notes:
By default the carriage-return character will be not used, except if the C library supports it (fopen(...,"wt")).

OPEN

Syntax for Sequential I/O

OPEN filespec [FOR mode] AS #filenum [ACCESS [access]] [share]

Syntax for Random I/O

OPEN filespec FOR RANDOM AS #filenum {LEN|STRUCT}=recl [ACCESS [access]] [share]

Syntax for Simple Database

OPEN DATABASE filespec AS #filenum [ACCESS [access]] [share]

Alternative syntax

filenum = OPEN(filespec, modestr[, recl])

Makes a file or device available for sequential input, sequential output, random access (either input or output). Also, it can open a simple database file.

filespec

A string expression that follows OS file naming conventions.

filenum

A free file number (see FREEFILE).

mode

File I/O mode

INPUT

Sequential input

OUTPUT

Sequential output

APPEND

Sequential output, beginning at current EOF

RANDOM

Random input/output

access

If included, must be one of the following:

READ

File is opened for reading only.

WRITE

File is opened for writing only.

READWRITE

File is opened for both reading and writing. (this is the default)

share

If included, must be one of the following:

SHARED

Any process may read from or write to the file. (this is the default)

DENYREAD

No other process is granted read access to the file.

DENYWRITE

No other process is granted write access to the file.

EXCLUSIVE

No other process is granted either read or write access to the file.

recl

Sets the record length for random files. Also, instead of record-length, we can use a structure name.

modestr

A string which can had the following attributes:

r

Sequential input. If recl is specified then it is used for random input.

w

Sequential output. If recl is specified then it is used for random output.

a

Sequential output, beginning at current EOF. If recl is specified then it is used for random input.

+

Ignored, since r/w is the default.

a:{r|w|+}

What access, (r)ead, (w)rite, or both (+). (default "a:+")

s:{{-|x}|r|w|+}

What access for other processes, (-) none or e(x)clusive, (r)ead, (w)rite, or both (+). (default "s:+")

Notes:
'output' modes are creating the file. The default attributes for Unices are 0664.

CLOSE

CLOSE #filenum

Closes file or device.

filenum

The file number.

FREEFILE

filenum = FREEFILE

Returns an unused filenum.

EOF

bool = EOF(filenum)

Checks for end of file. For devices, EOF returns -1 when connection is lost or the "session" (whatever) is closed.

filenum

The number under which the file was OPENed.

LOF

n = LOF(filenum)

Returns the length of the file. If the file is RANDOM, then returns the number of the records. If the file is a device/driver, then returns the remaining bytes in the input buffer.

filenum

The number under which the file was OPENed.

SEEK()/LOC()

n = SEEK(filenum)

Returns the current position on file. If the file is RANDOM, then returns the number of the current record starting from 0. If the file is a device/driver, then returns the "received" bytes. The keyword LOC() is used for compatibility with QB.

filenum

The number under which the file was OPENed.

SEEK#

SEEK #filenum, position

Moves the file-pointer to specified position of the file. If the file is RANDOM, then position represents the record number. If the file is a device/driver, then its moves the file-pointer to the next 'position' bytes.

filenum

The number under which the file was OPENed.

position

Position in the file.

Sequential I/O

Get Input from Sequential File or Device

INPUT #filenum, variable [,variable]...

Receives input from a sequential file or device and assigns it to one or more numeric or string variables.

filenum

The number under which the input file was OPENed. It may refer to a disk file, a other-device file.

variable

The name of a variable (string or numeric) that will receive input.

Notes:
String input need not be enclosed within quote marks, unless it contains one or more line feeds or a double quote mark or comma.

When receiving input, BASIC looks for the first character other than a space, line feed, or carriage return. If that character is a quote mark, BASIC considers the string to be everything from the character following the quote mark up to the next quote mark. If the first character is not a quote mark, BASIC terminates the string when it encounters a line feed, a comma or when it has received 1024 characters.

For compatibility between Unix and DOS systems. Carriage return character must be ignored.

Read Line from File, Ignoring Delimiters

LINE INPUT # filenum, stringvar

Assigns a line of input (up to 1024 characters) from a sequential file or device to a string variable.

filenum

The number under which the file was opened.

stringvar

The name of a string variable that will receive input.

Notes:
LINE INPUT # treats all commas and quote marks as part of the input string. Input is terminated by a line-feed (the line feed are included in the string variable assignment).

For compatibility between Unix and DOS systems. Carriage return character must be ignored.

Output to Sequential File (QB comp.)

PRINT #filenum; var [...]

Writes one or more expressions. Same as screens output.

WRITE #filenum; var [...]

Writes one or more expressions.

var

BASIC outputs a line feed at the end of the list. If no items are included, a blank line is written.

Notes:
WRITE# differs from PRINT# in the following ways:
* The data items (at disk) are separated by a comma.
* The String expressions are output enclosed in double-quote marks.

Random I/O

Set Record Structure (Optional)

STRUCT name; { field=[type]len [, ...] | array }

Setting structure of record for the file 'filenum'. Because we want to use the same commands for databases, this command uses extented syntax.

name

a name for the structure

field

The name of the field. Field names are following the same rules as the variable names.

type

Field type can be one of the following

C

String

N or R

Real number

I

Integer (32bit or bigger)

D

Date

M

Memo (same as C but in some drivers may be needed for big-length fields)

B

Boolean

len

The size of the field

When an array is used instead of fields, each element is a field description. Each field description had two elements, the first is the name and the second is the len (with or without the type).

Structure variables must be applied on strings too.

REM A Structure
STRUCT myrec; ID=4, NAME=32, PHONE=12
h = OPEN("my.db", "r", myrec)
' while
WHILE !EOF(h)
	IF FLD(h, "name") = "NDC" THEN PUT #f; "name" = "Nicholas"
	NEXT #h
WEND
' for
FOR i = 0 TO LOF(h)-1
	IF FLD(h, i, "name") = "NDC" THEN PUT #h; "name" = "Nicholas"
NEXT
' for #2
FOR i = 0 TO LOF(h)-1
	r = REC(h, i)
	IF r(1) = "NDC" THEN r(1) = "Nicholas" : PUT #h; r
NEXT
'
CLOSE #h

Get Input from Random File or Device

variable = REC(filenum[, index])

Returns the data of the 'index' record. If 'index' is omitted then the current record (SEEK) is used. If record contains more than one field then an array is returned.

Writes to Random File or Device

PUT #filenum; [index,] field=var [, field=var [...]]

PUT #filenum; [index,] array

Writes the data on the 'index' record. If 'index' is omitted then the current record (SEEK) is used. If record does not exists it creates one. If the 'index' is biggest than the number of records, then blank records will be inserted.

Standard non-disk Devices/Drivers

Standard Input, Output and Error streams

STDIN:

Standard input

STDOUT:

Standard output

STDERR:

Standard error

Serial Ports

COM1:[speed[,parity-data-stop]]

Serial port 1...

COM2: - COM9:

Other devices if are exists

Socket-client (telnet) Driver

SOCL:server[,port]

Socket client

MEMO-DB emulation driver

MEMO:[category/]memo-title

Memo database On PalmOS this is the memopad, on Linux the KNotes. If there is no a standard memo application, then a database file is used.

CONTACT-DB emulation driver

CONTACT:[category/]name

Contacts database. On PalmOS this is the address book, on Linux the KAddressBook, on Windows the Address book of Outlook express. If there is no a standard address book, then a database file is used.

PDOC emulation driver

PDOC:file

Compressed PalmOS Documents. If the basic file-stream module it is works then there is no need for more coding.

GZIP emulation driver

GZIP:file

Compressed files using zlib. If the basic file-stream module it is works and the zlib exists then there is no need for more coding. If there is no such library, then, a PDOC can be used as a temporary replacement.

The Rest Commands/Functions

There must be exists a lot of other commands that are usual on an OS. GNU/Linux file systems are our prototypes, if some capabilities are not supported by an OS, must emulated.

EXIST(file)

Returns true if the 'file' exists.

ACCESS(file)

Returns the attributes of the 'file'. For details see chmod manual.

CHMOD file, attributes

Sets the attributes of the 'file'. For details see chmod manual.

ISFILE(file)

Returns true if the 'file' is a regular file.

ISDIR(file)

Returns true if the 'file' is a directory.

ISLINK(file)

Returns true if the 'file' is a link.

BGETC(filenum)

Returns the next byte of the stream.

INPUT(filenum[, len)

Returns one or more bytes from the file. Similar to BGETC but used for text-files.

BPUTC #filenum, byte

Writes a byte at the stream.

KILL file

Removes a regular file.

COPY old-name, new-name

Copies a file

RENAME old-name, new-name

Renames(or moves if it is supported) a file

CHDIR dir

Changes the current working directory to 'dir'.

MKDIR dir

Creates a directory (default attributes are the parent directory or 0664)

RMDIR dir

Removes the subdirectory 'dir'.

DIRWALK directory [, wildcards] [USE UDF(name)]

Walks throughs subdirectories.

FILES(wildcards)

Returns the list of the files of the current directory.