********************************************************************************
* Hpattl! Delphi Component                                                    *
********************************************************************************

Unit alias:       ZLibPOD
Name:             Custom Compressed Databank
Version:          3.66
Requires:         Delphi 3.0/4.0, ZLib, HueAPI2
Files:            ZLibPOD.pas, ZLibPOD.dcr, ZLibPOD.txt
Last revised:     July 28th, 1999
Notes:            FreeWare!
Updates under:	  www.neveprise.de
Mail to:	  mail@neveprise.de

********************************************************************************
* ZLibPOD Copyright 1998-'99 by Neveprise Inc., SD                            *
********************************************************************************

1. Bugfixes / history
2. Description
3. How to install
4. Working with ZLibPOD
5. Disclaimer




1. Bugfix since last version / history
================================================================================

v3.66

Under special circumstances, the CleanUp() method failed or caused loss of data.
This has been fixed. Remind: CleanUp() only makes sense if OverwriteMode is
zowCopy (recommended mode). Also replaced some internal fileroutines with calls
to the WinAPI for more security.

v3.65

Removed some vars that were no longer used. String handling now allows more than
max_path, now unlimited. Since dis version, there is no theoretical limit
of data entries; the previous toc was limited to 40kb. Better speed now.

v3.64

In the previous version, ZLibPOD caused an error that deleted the zlib file when
OpenMode was set to zmodInstant. This error has been fixed thanx to M. Schubert!
At this point a suggestion: if not needed, please set OpenMode to zmodCopy, so
that ZLibPOD works on a copy and changes to the contents are not done immediately
thus. When using zmod Copy, call SavePOD() whenever the app wants to save per-
manent changes - SavePOD will not work when OpenMode is zmodInstant, cos changes
are done at once.
And: before saving I recommend to call CleanUp() to remove overwritten data. This
can be compared with the Windows trash bin.


2. Description
================================================================================

TZLibPOD is a component that lets you create your own customized files containing
multiple data. You can compare it to apps like ARJ or WinZip: ZLibPOD creates a
file that holds multiple files. You can access'em, write, read, delete and modify.
They are (de-) compressed on the fly at a user-defined level, so that created files
shrink in size.
ZLibPOD offers an easy to use interface for handling files, streams, bitmaps,
strings etc. Use it, it is it worth!

NOTE: TZLibPOD requires ZLib to be installed into Delphi. It is delivered with your
original versions of Delphi since 3.0 and up. It also requires the HueAPI2, avail-
able for free on www.neveprise-inc.de .

*** !!!! Changes since version 3.59 and 3.61 !!!! ***

The old toc interface called ZDataRec has been replaced by a common one named
ZEntryRec, nevertheless, this record uses the former properties.
Property Entries has been removed, so if you want to query the number of entries
in ZEntryRec, just call Length(ZLibPOD.ZEntryRec).
Since v3.61, ZLibPOD provides a second kind of overwriting data / updating existing
data. In the older versions, overwriting data of the same name caused the whole
pod to be reconstructed, thus beeing defragmented. When Setting the Overwrite-
mode to zowRetard, the former data will bemarked as deleted and the new data
is added at the end, so that the pod must not be reconfigured. The advantage is,
that changes to the pod file are done very quickly, the disadvantage is, that
the old data rests in the file. So, when saving the pod file - or during work -
you can call the CleanUp procedure to remove old entries.
Cos old data is left in the file until the CleanUp procedure is called, you can
recover those overwritten entries. All overwritten or deleted data are accessible
via the ZDeletedRec structure array, build the same way like ZEntryRec. Just call
Length(ZDeletedRec) to retrieve the number of old data packages in the pod file.
With UndeleteByIndex, you can restore those entries. Before you do so, it is
*strongly* recommendet that you first rename (and then delete?) the newer one to
avoid errors.

New functions are:

RenameByIndex:	 lets you rename entries
RenameByName:	 shold be obvious
UndeleteByIndex: to undelete old data versions or deleted entries
CleanUp:	 removes undeletable data

New structure:

ZDeletedRec:	contains deleted or overwritten data

New / changes properties:

OnProgress:	 changed parameters
OverwriteMode:   when set to zowRetard (recommended), working with ZLibPOD is faster,
		 cos deletion or updates of existing data not causes the whole file to
		 be reorganized. Old data is kept until CleanUp is called - this allowes
		 to undelete older data.

3. How to install
================================================================================

Shall be very simple:

First, copy the files "ZLibPOD.pas" and "ZLibPOD.dcr" into a special
folder, e.g. "C:\Data\Delphi Progs\Components".
If you haven't already, start your Delphi IDE and select "Components|Install
components". In the dialog displayed, select wether "Into existing package"
(recommended) or "Into new package" (if so, type in a new package filename and
-folder). Click the upper button labeled "Browse" and select the ZLibPOD
file in the location you copied it to.
When done, click "Ok" and let Delphi compile the whole package in the next
dialog. Close this window and TZLibPOD should have been installed.


4. Working with TZLibPOD
================================================================================

First, let me show new properties introduced by TZLibPOD:

- [custom]     Compression:           specs what level of compression you want (good and slow, bad and fast etc.)
- [custom]     OpenMode:              defines if an archive is opened directly (and modifications are done immediately), or if ZLiobPOD shall work on a copy
- [custom]     OverwriteMode:	      defines, how existing data is overwritten / updated
- TNotifyEvent OnProgress:	      raised, when data is (de-) compressed, return in bytes and percent of the whole


All these properties can be set visually through Delphi's Object Inspector.

When dragged the new component onto a form, please commence setting those props:

First, define the level of compression: there are currently four levels:

crDefault:	default, standard compression (good speed, good compression)
crMax:		maximum compression but slower
crFast:		little compression but fast speed
crNone:		if you do not want the file to be compressed

Then decide how your files shall be handeled: cos modifications in your file
are done directly, you can tell ZLibPOD to work on a temprorary file. If the user
in your app wants to save the file, the original will be replaced by the temporary
one. This Option is recommended, if the file shall be modified.
If it is only used for retrieving data, use zmodInstant to open the file directly
- dis is faster.

How to put data into your archive:

if your data is of any format, you can simply use the stream interface:

ZLibPOD.Put(NameOfData, AliasNameOfData, Size, Attribs, Date, Data);

Explanation: NameOfData:	 declare data's name (normaly a filename)
	     AliasNameOfData:	 an alias name for quicker access
	     Size (optional):	 the size of data (not needed, only for personal use)
	     Attribs (optional): the attributes (if the data was a file)
	     Date (optional):	 TDateTime, if data was a file
	     Data:		 TStream, the data to put into that archive


Normally, you would use other interfaces, when you know what kind of data you have:

Strings:	WriteString(Name, Value);
Switches:	WriteBool(Name, true/false);
Numbers:	WriteInteger(Name, Number);
TStrings:	PutLines(Name, lines (e.g. RichEdit contents));
 or:		WriteStrings(Name, stringlist);
TBitmap:	PutBitmap(Name, image);
Files:		PutFromFile(FileName); (ZLibPOD will include file information)

so, if your data is of that type, use one of dis functions, only if it is any other type,
then use the Put function. Of course there are corresponding "Get"-functions to re-
trieve the data.

Cos ZLibPOD has a lot of data to handle, especially when existing entries will be actualized,
it is better not to manipulate each entry step by step. E.g. if you know you want to delete
a bunch of entries, better collect a name list of'em and give them finally to ZLibPOD:

DeleteEntries(Names as TStrings);

Cos ZLibPOD has to reorganize data in an archive file to prevent holes in it (defragmenting),
it would last some amount of time if you would call Delete(Name); in a loop, cos ZLibPOD re-
organizes after each modification. But if you give it a whole batch of names to modify,
ZLibPOD can do it in a single pass internally.
The other way is to set OverwriteMode to zowRetard. This causes ZLibPOD not to delete older
data, it is just remarked as deleted and rests within the pod file. This allows on the one
hand to undelete deleted data, on the other hand this lets the pod file grow. Thus, when final
changes are done, call CleanUp to remove deleted data. 

How to get to know what contents are in an archive???

ZLibPOD provides a record of all contained data: ZEntryRec(Index).
All data entries are indexed by numbers, starting from 0. Property Entries contains the
number of all entries. So you can query each data item by index, e.g.:

for x=0 to Length(ZLibPOD.ZEntryRec)-1 do begin
   with Form1.ListBox1.Items do begin
	Add(ZEntryRec(x).Alias);
	Add(ZEntryRec(x).Name);
	Add(IntToStr(ZEntryRec(x).Attribs));
   end;
end;

If you know the names, you can get data directly, e.g.:

Image1.Picture.Bitmap:=ZLibPOD.GetBitmap(MyPicture);

Otherwise you have to request the names from ZEntryRec, cos most functions are handeled
by names.

There are some more helper functions, so please take a sneak into the .pas file to
get more information, you'll find functions and procedures under public declarations.

The structure ZDeletedEntries (same kind like ZEntryRec) contains information on deleted
or overwritten data. You can restore this data via UndeleteByIndex(x). Before saving
a pod file, it is recommended to call CleanUp to remove old versions of data from a pod
file, this keeps the file small. You can call CleanUp at any time, when a file is opened
and OverwriteMode is set to zowRetard.

POW! That was complicated! If cannot get ZLibPOD to work in your app, do not hasitate
to ask me via: support@neveprise-inc.de .
Additionally, i will soon provide an example application, where you can see, how it works.


5. Disclaimer
================================================================================

This component is freeware, meaning you can freely use and redistribute this code.
If you do so, please do only copy the original .zip file. If you perform any
modifications to code or documentation, please make a clear note into dis document!

Cos TZLibPOD is freeware, the author

a) claims that dis ware is "as is" and that there is NO guarantee that it will
work correctly, as it was intended to work.

b) is NOT responsible for ANY direct or indirect damages dis software may cause.

Notice that Neveprise takes great care with it's products, so any bad malfunction
is very unlikely.

							Blazko, June 11th, 1999

-EOF-