## Files

iziBasic is limited to work on database files (pdb), it does not work on program files (prc). It is even limited to work on specific database files ("DATA", "Data" and "data" types) in most instructions. This was made on purpose, to avoid any risk of performing dangerous actions on files or deleting programs on the devices.

Legend:

- #v|n is the File Handle and is in the range [0...9]; this means that you can work with up to 10 files simultaneously
- c|t is the name of the database file; do not put the ".pdb" extension in this name

CLOSE #v|n

Closes the file indicated by #v|n which has been previously opened by the OPEN statement, and releases the #v|n handle

Notes:

- Raises a FILEERROR if the operation fails

$ COPY c|t1, c|t2[, c|t3]

Creates file with name c|t2 and copies content of file c|t1 into this new file. If the c|t3 parameter is passed, sets Creator ID in destination file c|t2 with a new 4 characters value passed in c|t3 instead of the Creator ID of c|t1

Notes:

- If file c|t2 already exists does nothing and raises a FILEERROR

Warning: you are allowed to copy databases with any Creator ID, this means that you can copy almost any database file (with "DATA", "Data" or "data" type) on your device.

INPUT #v|n, v|c

Reads data from an opened file with OPEN and moves to next record.

Notes:

- Raises a FILEERROR if the operation fails
- All data, even numerical values, is stored in text string format in the file (using PRINT #). So you may write a number and read it back in a text string

$ KILL c|t

Deletes the file specified by c|t

Warning: you are allowed to delete databases with any Creator ID, this means that you can delete almost any database file (with "DATA", "Data" or "data" type) on your device.

Notes:

- Raises a FILEERROR if the operation fails

OPEN c|t FOR INPUT|OUTPUT|APPEND|RANDOM AS #v|n

Makes file c|t available for sequential input, sequential output and reserves the #v|n handle for all read and write accesses to this file.

The FOR part of the instruction passes the file open mode:

- INPUT sequential reading (with INPUT #), starting at first record
- OUTPUT sequential writing (with PRINT #), erasing all content of file if any when opening it or creating it if does not exist
- APPEND sequential writing, beginning at current end of file (see EOF function), creates the file if it does not exist
- RANDOM random-access reading and writing (see SEEK statement), starting at first record, creates the file if it does not exist

  Notes:

  - Raises a FILEERROR if the operation fails
  - To avoid any risk of deleting important files on your Palm device, the OUTPUT, APPEND and RANDOM file modes only work with databases having a "LDIB" Creator ID if the SECUREFILES compiling directive is set to ON
  - Be careful: if you erase iziBasic from your device, which has "LDIB" as a Creator ID, the standard Palm OS deletion mode will also erase all databases having a "LDIB" Creator ID
  - Would you wish to work on external files anyway (meaning not having a "LDIB" Creator ID), you may:
    o either set the SECUREFILES compiling directive to OFF
    o or do it in 3 steps by using the COPY instruction with "LDIB" as Creator ID for the destination file before using the OPEN instruction with this destination file. After you finish working on this file, CLOSE it. Then you may KILL the original file and COPY the destination back to the original one.

  Warning: In the case you work on such databases, be careful that applications using categories may not work correctly afterwards! This is due to how Palm OS manages categories. In the case of the Memo Pad for instance, my own tests have shown that the APPEND mode works fine when the RANDOM mode would give unpredictable results.

  PRINT #v|n, v|n|c|t

  Writes data to file and moves to next record

  Notes:

  - Raises a FILEERROR if the operation fails
  - In RANDOM mode, erases the current record and replaces it with the new one, unless the file pointer is at the end of file (see EOF function)
  - All data, even numerical values, is stored in text string format in the file. So you may write a number and read it back (using INPUT #) in a text string

  $ RENAME c|t1, c|t2

  Renames file from name c|t1 to name c|t2

  Notes:

  - Raises a FILEERROR if the operation fails

  Warning: you are allowed to rename databases with any Creator ID, this means that you can rename almost any database file (with "DATA", "Data" or "data" type) on your device.

  $ RUN c|t1[, c|t2]

  Exits from the current program and launches program c|t1 with a optional c|t2 string text parameter to pass to the new program

  Notes:

  - if the program passed in parameter c|t1 does not exist, remains in the current program and you might then want to handle the error with FILEERROR in the lines following the RUN instruction…
  - the c|t2 parameter is passed to the new program which may retrieve it with the RUN$ function

  $ SEEK #v|n1, v|n2

  Sets file position to the given v|n2 record

  Notes:

  - SEEK is available for files opened in INPUT or RANDOM modes

  EOF(#v|n)

  Returns if End Of File is reached (1=true/0=false)

  Notes:

  - The current record number is the next record to read or write. For instance, if you just read the 3rd record (with the INPUT #v|n, v|c statement) out of 4 records, EOF will return true.
  - As a consequence, to parse all records of a database you should code something like this:

    WHILE F=0
    F=EOF(#1) : INPUT #1,A$ : PRINT A$
    WEND

    and not like this which will skip the last record:

    WHILE F=0
    INPUT #1,A$ : F=EOF(#1) : PRINT A$
    WEND

  FILEERROR

  Returns if last file operation generated an error (1=true/0=false)

  FILEEXISTS(c|t)

  Returns 1=file exists or 0=file does not exist

  FINDFIRST$(c|t1, c|t2)

  Returns the name of the first file found which complies with the given parameters (see notes) or empty text string if none found

  FINDFIRST$ works in conjunction with FINDNEXT$. You initiate a search for files with FINDFIRST$ and then search for all given files with FINDNEXT$ in a loop.

  Notes:

  - c|t1 is a 4 characters Type (application, database...) of files to search for, pass empty text string to scan all types
  - c|t2 is a 4 characters CreatorID of files to search for, pass empty text string to scan all Creator IDs
  - scan for the next files complying with the search criteria using the FINDNEXT$ function

  FINDNEXT$(c|t1, c|t2)

  Returns the name of next file found which complies with the given parameters (see notes) or empty text string if none was found anymore

  FINDNEXT$ works in conjunction with FINDFIRST$. You initiate a search for files with FINDFIRST$ and then search for all given files with FINDNEXT$ in a loop.

  Notes:

  - c|t1 is Type and c|t2 is CreatorID of database to search for
  - be careful to pass the same parameters as for the FINDFIRST$ function, otherwise you will get unexpected results

  Example of use:

    ' Scan for all iziBasic database files
    F$=FINDFIRST$("DATA","LDIB")
    WHILE F$<>""
    PRINT F$
    F$=FINDNEXT$("DATA","LDIB")
    WEND

  LOC(#v|n)

  Returns Location in File = current record number

  Notes:

  - The current record number is the next record to read or write. For instance, if you just read the 3rd record (with the INPUT #v|n, v|c statement), LOC will return 4.

  LOF(#v|n)

  Returns Length Of File = number of records

  RUN$

  Retrieves a string text parameter passed to the program.

  Notes:

  - see the RUN statement