



                         Library Creator v1.0
                         --------------------

                         Written by Terry King

                          Ninth Wave Software

                      Last update 30th April 1995




Library  Creator  is essentially a tool for GFA Basic  programmers  who 
wish  to  construct a single external file instead of lots  of  smaller 
external files.  However,  users of any langauge may find this  program 
useful, especially assembly programmers. Alternatively this program can 
be  used to group together files that can then be packed to  provide  a 
simple archiving utility.

Using this program
------------------

This program requires to be run from a resolution other than  low.  The 
program  was  designed  to run in medium  resolution  and  running  the 
program in high resolution will result in some minor cosmetic glitches, 
but this will not effect the running of the program.

When  you  run  the  program you will be presented  with  a  large  GEM 
interface with the library window on the left and the current directory 
source  window on the right.

The  maximum size of the library is displayed near the bottom  left  of 
the  screen.  The program will grab as much memory as possible for  the 
library but still leave 100k free that any resident/accessory  programs 
may use.

The source window
-----------------

The  window on the right is the source window from where files  can  be 
loaded into the library or extracted from the library.

To select a new drive or directory click on the top left symbol of  the 
window which will bring up a fileselector allowing you to select a  new 
path.  Once selected,  the drive is displayed at the top of the  window 
and the pathname below that.

To select one or more files to copy into the library simply left  click 
on  the filename with the mouse.  By holding down the mouse button  you 
can drag along selecting files as you go,  if the mouse is moved  above 
or below the window the files will scroll as they are  selected.  Files 
can  be  deselected by selecting them again.  To clear  all  the  files 
marked  you  can select the top right symbol of the window,  or  if  no 
files have been marked this will select all of them.

To  navigate the directory you simply click on the folder you  wish  to 
enter,  to  go back to the previous directory you must select the  ".." 
folder. All folders are displayed with a symbol before the folder name.

The library window
------------------

The default name for the library file is DEFAULT.LIB,  this is  changed 
once you have selected 'Save' or 'Load'.  This window displays the file 
number  within  the library along with the filename,  size  and  offset 
position within the library.

As  with  the source window,  one or more files can be  selected  by  a 
single mouse click.

Add
---

When  one or more files have been selected from the source window  they 
may be added to the end of the library.  Although the add button  never 
appears  disabled it will only operate if one or more files  have  been 
selected.

As the files are added the two windows are updated in realtime to  show 
the programs progress.  There is no file overwrite so copying the  same 
file  several times will result in several copies in the  library  each 
with the same filename.

Copying  will automatically abort if the library becomes full  even  if 
further smaller files may have fitted in the library.

Insert
------

Insert  only  becomes  active when one file has been  selected  in  the 
library  and  one or more files selected in the  source  window.  Those 
files  from the source will be inserted into the selected  position  in 
the library with the selected file and those below being shifted down.

Delete
------

You can delete any number of files from the library,  but at least  one 
file must be selected for the option to become active.

Extract
-------

As with delete,  this option only becomes active when one or more files 
have been selected from the library. Those files selected will be saved 
to the current directory in the source window.

File format
-----------

The  first  four  bytes of the file contain  a  "LIBF"  identification, 
followed by a two byte integer of the number of files contained  within 
the library.

Each  file  descriptor is then stored in 20 bytes,  12  bytes  for  the 
filename  then a 4 byte integer for the size and a 4 byte  integer  for 
the offset.  The data is then stored in one continuous block after  the 
descriptors.

Using libraries within GFA
--------------------------

There  are two versions of the GFA listing that are needed to read  the 
library  files.  Version 1 uses Malloc to allocate library  memory  and 
version 2 uses DIM to allocate memory.

To  load  a library you must enter the  line  @load_library("filename") 
near the start of your program.  If the library is small enough to  fit 
into memory then the entire file will be loaded into memory,  otherwise 
files will be read from the library on disk if and when they're needed.

For  loading  a  file  by  number  use  the  procedure  @load_by_num(n, 
address%) which will load n'th file in the library into memory location 
pointed to by address%.

If  you  wish  to load a file by its filename then  use  the  procedure 
@load_by_name("filename", address%). 

For example, you may have a number of BLOAD commands in your program :

     BLOAD "graphics.gfx", graphics%
     BLOAD "level_1.map", map%
     BLOAD "samples.dat", samples%

These  numerous external files can be stored in a library  then  loaded 
with the procedures provided :

     @load_library("filename")
     '
     @load_by_name("graphics.gfx", graphics%)
     @load_by_name("level_1.map", map%)
     @load_by_name("samples.dat", sample%)

Bugs and limitations 
--------------------

Currently  the  source window will only accomodate 200  files  and  the 
library can only accomodate 100 files.

This  is only the first version of this program and was written  fairly 
quickly,  as  such  the program will probably break  if  pushed  !  The 
program  was  written in GFA Basic 3.0 and GFA has the nasty  habit  of 
intercepting all errors that occur, however the most common problem (in 
my mind) is the disk full error which I have managed to put a patch  in 
for  so  it should'nt cause the program to exit to  desktop  when  this 
error occurs.

Please inform me of any bugs or features that you would like to see.

This  program is DONATIONWARE (aka DESPERATE WARE) which means  if  you 
find  this program useful you should send 'something' to me.  Disks  of 
PD, blank disks or stamps are always welcome ......

     Mr T.King,
     Ninth Wave Software,
     172 Spencers Croft,
     Harlow,
     Essex CM18 6JR


