Copyright: Copyright ® 1996 Greenleaf Software, Inc.


Contents
   Greenleaf ArchiveLib v2.0

 Documentation Conventions

 Storage Functions

 Compression Functions

 Archiving Functions

 Utility Functions

 Monitoring Functions

 Technical Support


Documentation Conventions

The following conventions are used throughout this online help file:

ArchiveLib was developed as a Windows product that runs under DOS and OS/2, and contains functions for C++, C, Visual Basic, and Delphi programmers.  Icons for Windows, DOS, and OS/2 platforms are placed at the beginning of each function description to show which platform the function supports.

The Windows icon indicates support for all versions of the Microsoft© Windows™ graphical user interface. This includes Windows 3.1, Win32, Windows NT, and Windows 95.

The Console icon represents support for all Text Modes.  This includes DOS, console mode under Windows 3.1, Windows NT, or Windows 95, and OS/2 Console Modes.

The PM icon shows support for the OS/2 Presentation Manager.

Icons for language support (C++, C, Visual Basic, and Delphi) are placed to the left of the appropriate function synopsis, as shown below:

  int ALFileAttributes::ReadOnly()

  int ALStorageReadOnly( hALStorage storage )

  Declare Function ALStorageReadOnly Lib "AL20LW"( ByVal storage& ) As Integer

  function ALStorageReadOnly( storage : hALStorage ) : Integer;

A note always appears whenever there is a warning or particularly important information to relay to users.


ContentsStorageFunctions
   Greenleaf ArchiveLib v2.0

 Documentation Conventions

 Storage Functions

ALStorage class

ALFile class

ALMemoryBase Family

ALMemory class

ALHugeMemory class

ALWinMemory class

 Compression Functions

 Archiving Functions

 Utility Functions

 Monitoring Functions

 Technical Support


ContentsCompressionFunctions
   Greenleaf ArchiveLib v2.0

 Documentation Conventions

 Storage Functions

 Compression Functions

ALCompressor class

ALDecompressor class

ALCopyCompressor class

ALCopyDecompressor class

ALGlCompressor class

ALGlDecompressor class

ALPkCompressor class

ALPkDecompressor class

 Archiving Functions

 Utility Functions

 Monitoring Functions

 Technical Support


ContentsArchivingFunctions
   Greenleaf ArchiveLib v2.0

 Documentation Conventions

 Storage Functions

 Compression Functions

 Archiving Functions

ALArchive class

ALGlArchive class

ALPkArchive class

ALEntry class

ALEntryList class

ALToolKit class

ALCompressedObject class

 Utility Functions

 Monitoring Functions

 Technical Support


ContentsUtilityFunctions
   Greenleaf ArchiveLib v2.0

 Documentation Conventions

 Storage Functions

 Compression Functions

 Archiving Functions

 Utility Functions

Miscellaneous Function ( EditDisplay() )

ALFileAttributes class

ALName class

ALStatus class

ALTag class

ASSERT Debug Macros

ALTimeDate class

ALWildCardExpander class

 Monitoring Functions

 Technical Support


ContentsMonitoringFunctions
   Greenleaf ArchiveLib v2.0

 Documentation Conventions

 Storage Functions

 Compression Functions

 Archiving Functions

 Utility Functions

 Monitoring Functions

ALMonitor class

ALBarGraph class

ALSpinner class

ALWindowsMessage class

ALOs2Message class

Stand-alone OS/2 Functions

 Technical Support


ALStorage class
Storage Functions

ALStorage class

~ALStorage() 	Destructor for ALStorage class

ClearError() 	Reset the error status for a storage object

Close() 	Close storage object

Compare()	Compare contents of two files

Create()	Create new storage object

Delete()	Delete storage object's underlying system object

FlushBuffer()	Flush data blocks from the I/O storage buffer

GetCrc32()	Get CRC value

GetSize()	Get size data of files opened with Open()

InitCrc32()	Begin tracking 32-bit CRC

IsOpen()	Determine whether storage object is open

LoadBuffer()	Load data into the I/O buffer

Open()	Open file for read/write

ReadBuffer()	Read in a data block

ReadChar()	Read data from storage object

ReadGlLong()	Read 32-bit data word in little endian format

ReadGlShort()	Read 16-bit data word in little endian format

ReadPkLong()	Read a long data word using PKWare's format

ReadPkShort()	Read a short data word using PKWare's format

ReadString()	Read data string from storage object

Rename()	Rename storage object

RenameToBackup()	Rename storage object to use as backup copy

Seek()	Reposition input stream to new file position

Tell()	Indicate where next byte to read/write will go

UnRename()	Revert filename to previous name

WriteBuffer()	Write a block to the storage object

WriteChar()	Write character data to storage object

WriteGlLong()	Write 32-bit data word in little endian format

WriteGlShort()	Write 16-bit data word in little endian format

WritePkLong()	Write a long data word using PKWare's format

WritePkShort()	Write a short data word using PKWare's format

WriteString()	Write data string to storage object

YieldTime()	Yield time to operating system

Access Functions

The following functions can be used by C, Visual Basic, and Delphi programmers to access C++ data members in ALStorage.

ALStorageGetStatusCode()	Get status of ALStorage object

ALStorageGetStatusDetail()	Get detailed error information

ALStorageGetStatusString()	Translate error code into string

ALStorageGetType()	Return integer value indicating storage object type

ALStorageSetError()	Manipulate error code for ALStorage


ALFile class
Storage Functions

ALFile class

ALFile()	Constructor for ALFile class

MakeTempName()	Make temporary file name


ALMemoryBase Family
Storage Functions

ALMemoryBase Family

The ALMemoryBase family is made up of ALMemory, ALHugeMemory, and ALWinMemory.  ALMemoryBase is the base class for this family of derived classes.

Access Functions

The following functions can be used by C, Visual Basic, and Delphi programmers to access C++ data members in ALMemoryBase.

ALMemoryBaseGetBufferOwner()	Indicate owner of memory buffer

ALMemoryBaseGetBufferSize()	Get size of storage buffer used by memory object

ALMemoryBaseSetBufferOwner()	Set ownership of memory buffer


ALMemory class
Storage Functions

ALMemory class

ALMemory()	Constructor for heap based ALMemory class

Access Function

The following function can be used by C programmers to access C++ data members in ALMemory.

ALMemoryGetBuffer()	Get access to memory buffer


ALHugeMemory class
Storage Functions

ALHugeMemory class

ALHugeMemory()	Constructs a new ALHugeMemory object

Access Function

The following function can be used by C programmers to access C++ data members in ALHugeMemory.

ALHugeMemoryGetBuffer()	Retrieve the user buffer for an ALHugeMemory object


ALWinMemory class
Storage Functions

ALWinMemory class

ALWinMemory()	Constructs a new ALWinMemory object

Access Functions

The following functions can be used by C, Visual Basic, and Delphi programmers to access C++ data members in ALWinMemory.

ALWinMemoryGetBuffer()	Retrieve the user buffer being used in an ALWinMemory object

ALWinMemoryGetHandle()	Get the handle for an ALWinMemory object's buffer


ALCompressor class
Compression Functions

ALCompressor class

ClearError()	Reset the error status for a compression engine

Compress()	Compress input storage object to output storage object

Access Functions

The following functions can be used by C, Visual Basic, and Delphi programmers to access C++ data members in ALCompressor.

ALCompressorGetStatusCode()	Get status of ALCompressor object

ALCompressorGetStatusDetail()	Get detailed error information

ALCompressorGetStatusString()	Translate error code into string

ALCompressorGetTypeCode()	Return integer value of compression engine in use

ALCompressorGetTypeString()	Return compression engine type

ALCompressorSetError()	Manipulate error code for ALCompressor


ALDecompressor class
Compression Functions

ALDecompressor class

ClearError()	Reset the error status for a decompression engine

Decompress()	Decompress input storage object to output storage object

Access Functions

The following functions can be used by C, Visual Basic, and Delphi programmers to access C++ data members in ALDecompressor.

ALDecompressorGetStatusCode()	Get the status code for a decompression engine

ALDecompressorGetStatusDetail()	Get the detailed status string for an ALDecompressor engine

ALDecompressorGetStatusString()	Get the short status string for an ALDecompressor engine

ALDecompressorGetTypeCode()	Get the type code of an ALDecompressor engine

ALDecompressorGetTypeString()	Get the type description string for an ALDecompressor engine

ALDecompressorSetError()	Set the error code and text for an ALDecompressor engine


ALCopyCompressor class
Compression Functions

ALCopyCompressor class

ALCopyCompressor()	Constructor for copy compression engine


ALCopyDecompressor class
Compression Functions

ALCopyDecompressor class

ALCopyDecompressor()	Constructor for copy decompression engine


ALGlCompressor class
Compression Functions

ALGlCompressor class

ALGlCompressor()	Constructor for Greenleaf compressor engine

CompressionLevel()	Return the compression level for a Greenleaf engine


ALGlDecompressor class
Compression Functions

ALGlDecompressor class

ALGlDecompressor()	Constructor for the Greenleaf decompressor engine

CompressionLevel()	Read the compression level for a Greenleaf engine


ALPkCompressor class
Compression Functions

ALPkCompressor class

ALPkCompressor()	Constructor for the PKWare deflate compressor engine


ALPkDecompressor class
Compression Functions

ALPkDecompressor class

ALPkDecompressor()	Constructor for the PKWare deflate decompressor engine


ALArchive class
Archiving Functions

ALArchive class

~ALArchive()	Destructor for ALArchive class

Append()	Append archive entries to archive

Append()	Append existing archive entries to a new archive

ClearError()	Reset the error status for an entry list

Create()	Create archive from list of storage objects

Create()	Create new archive from list of objects in another archive

Delete()	Delete objects from an archive

Extract()	Extract storage objects from archive

FillListBox()	Insert storage object names into a list box control

GetComment()	Get comment associated with archive

GetStorageObject()	Get a pointer to the storage object being used by the ALArchive

GetVersion()	Get version of archive

ReadDirectory()	Read archive directory

SetComment()	Set comment

WriteDirectory()	Write archive directory

Access Functions

The following functions can be used by C, Visual Basic, and Delphi programmers to access C++ data members in ALArchive.

ALArchiveGetStatusCode()	Get status of ALArchive object

ALArchiveGetStatusDetail()	Get detailed error information

ALArchiveGetStatusString()	Translate error code into string

ALArchiveSetError()	Manipulate error code for ALArchive


ALGlArchive class
Archiving Functions

ALGlArchive class

ALGlArchive()	The Greenleaf archive constructor

ALGlArchive()	A Greenleaf archive constructor that creates a file object


ALPkArchive class
Archiving Functions

ALPkArchive class

ALPkArchive()	The PKWare archive constructor

ALPkArchive()	A PKWare archive constructor that creates its own file object


ALEntry class
Archiving Functions

ALEntry class

ALEntry()	Constructor for ALEntry class

~ALEntry()	Destructor for ALEntry class

ClearMark()	Clear mark from archive entry

CompressionRatio()	Calculate compression ration of an object in an archive

Duplicate()	Check for duplicates in archive entry list

GetComment()	Get comment associated with archive entry

GetCompressedSize()	Get compressed size of archive entry

GetCrc32()	Get 32-bit checksum of archive entry

GetMark()	Get mark state of an archive entry

GetNextEntry()	Iterate through the ALEntryList

SetComment()	Set comment associated with an archive entry

SetMark()	Mark an archive entry

SetMarkState()	Set mark state for archive entry

Access Functions

The following functions can be used by C, Visual Basic, and Delphi programmers to access C++ data members in ALEntry.

ALEntryGetCompressor()	Return a handle (pointer) to the compressor contained in an ALEntry object

ALEntryGetDecompressor()	Return a handle (pointer) to the decompressor contained in an ALEntry object

ALEntryGetStorage()	Get information about storage object

ALEntrySetCompressor()	Set the compressor object in an ALEntry object

ALEntrySetDecompressor()	Set the decompressor object in an ALEntry object

ALEntrySetStorage()	Modify pointer to storage object


ALEntryList class
Archiving Functions

ALEntryList class

ALEntryList()	Constructor for ALEntryList class

~ALEntryList()	Destructor for ALEntryList class

AddWildCardFiles()	Adds file names to an existing entry list

ClearError()	Reset the error status for an entry list

ClearMarks()	Clear marks on specified objects

DeleteUnmarked()	Delete unmarked entries in archive entry list

FillListBox()	Insert storage object names into a list box control

GetFirstEntry()	Proceed to first archive entry

MakeEntriesFromListBox()	Create new entries in a list based on selected items in a list box

SetMarks()	Set archive entries in list as marked

SetMarksFromListBox()	Set marks from list box selections

ToggleMarks()	Invert marks set in list

UnmarkDuplicates()	Unmark all duplicates in an archive entry list

Access Functions

The following functions can be used by C, Visual Basic, and Delphi programmers to access C++ data members in ALEntryList.

ALEntryListGetStatusCode()	Get status of ALEntryList object

ALEntryListGetStatusDetail()	Get detailed error information

ALEntryListGetStatusString()	Translate error into code string


ALToolKit class
Archiving Functions

ALToolKit class

CopyTools()	Create a toolkit with just the Copy engine and standard storage objects

FullTools()	Create a toolkit with everything in it

GLCompressFileTools()	Create a toolkit that supports Greenleaf compressors and ALFile objects

GLCompressTools()	Create a toolkit that supports Greenleaf compressors

GLDecompressFileTools()	Create a toolkit that supports Greenleaf decompressors and ALFile objects

GLDecompressTools()	Create a toolkit that supports Greenleaf decompressors

GLTools()	Create a toolkit with everything but PK compression/decompression

PkCompressFileTools()	Create a toolkit that supports PKWare compressors and ALFile objects

PkCompressTools()	Create a toolkit that supports PKWare compressors

PkDecompressFileTools()	Create a toolkit that supports PKWare decompressors and ALFile objects

PkDecompressTools()	Create a toolkit that supports PKWare decompressors

PkTools()	Create a toolkit with everything but Greenleaf compression/decompression

Access Functions

The following functions can be used by C, Visual Basic, and Delphi programmers to access the C++ ToolKit functions.

newALListCopyTools()	Create an entry list that uses the copy engine toolkit

newALListFullTools()	Create an entry list that uses the fully loaded toolkit

newALListGlCompressFileTools()	Create an entry list that uses the Greenleaf and ALFile toolkit

newALListGlCompressTools()	Create an entry list that uses the Greenleaf compressor toolkit

newALListGlDecompressFileTools()	Create an entry list that uses the Greenleaf and ALFile toolkit

newALListGlDecompressTools()	Create an entry list that uses the Greenleaf decompressor toolkit

newALListGlTools()	Create an entry list that uses the Greenleaf toolkit

newALListPkCompressFileTools()	Create an entry list that uses the PKWare and ALFile toolkit

newALListPkCompressTools()	Create an entry list that uses the PKWare compressor toolkit

newALListPkDecompressFileTools()	Create an entry list that uses the PKWare and ALFile toolkit

newALListPkDecompressTools()	Create an entry list that uses the PKWare decompressor toolkit

newALListPkTools()	Create an entry list that uses the full PKWare toolkit


ALCompressedObject class
Archiving Functions

ALCompressedObject class

ALCompressedObject()	Constructor for ALCompressedObject class

~ALCompressedObject()	Destructor for ALCompressedObject class

ClearError()	Reset the error status for a compressed object

Extract()	Extract compressed data from compressed object

Insert()	Insert storage object into compressed object

ReadHeaderData()	Read private header data

WriteHeaderData()	Write private header data

Access Functions

The following functions can be used by C, Visual Basic, and Delphi programmers to access C++ data members in ALCompressedObject.

ALCompressedGetStatusCode()	Get status of ALCompressedObject

ALCompressedGetStatusDetail()	Get detailed error information

ALCompressedGetStatusString()	Translate error into code string

ALCompressedSetError()	Manipulate error code for ALCompressedObject


Miscellaneous Function ( EditDisplay() )
Utility Functions

Miscellaneous Function ( EditDisplay() )

A single miscellaneous function, EditDisplay(), is provided for directing output to an edit control in Windows or Presentation Manager.

EditDisplay()	Direct output to multiline edit control


ALFileAttributes class
Utility Functions

ALFileAttributes class

Archive()	Get the Archive (or backup) file protection bit for a storage object

Directory()	Get the Directory attribute bit for a storage object

Hidden()	Get the Hidden file protection bit for a storage object

PackedAttributes()	Get the file attributes packed into a short integer

ReadOnly()	Get ReadOnly file protection bit for a storage object

SetFromPackedAttributes()	Set data members from a packed attribute integer

System()	Get System file protection bit for a storage object


ALName class
Utility Functions

ALName class

ALName()	Constructor for ALName class

ALName()	Copy constructor for ALName class

~ALName()	Destructor for ALName class

ChangeExtension()	Change file extension

ChangeTrailingChar()	Change last character in a file name

GetName()	Return pointer to object name

GetOldName()	Return pointer to old object name

GetSafeName()	Return non-Null pointer to object name

GetSafeOldName()	Return non-Null pointer to old object name

StripFileName()	Remove filename from file specification

StripPath()	Remove path from file specification

WildCardMatch()	Match text string with wildcard specifications


ALStatus class
Utility Functions

ALStatus class

GetStatusCode()	Get integer value of error

GetStatusDetail()	Return pointer to detail string

GetStatusString()	Translate error code into ASCII string

operator=()	Assignment operator for ALStatus class

operator int()	Casting operator for ALStatus

SetError()	Manipulate error code


ALTag class
Utility Functions

ALTag class

ALTag##x()	Constructor for a member of the ALTag class family

~ALTag##x()	Destructor for a member of the ALTag class family

GoodTag()	Test ALTag class family data member for proper construction


ASSERT debug macros
Utility Functions

ASSERT Debug Macros

AL_ASSERT()	Check code for detailed objects, bad pointers

AL_ASSERT_OBJECT()	Debug objects being passed as arguments


ALTimeDate class
Utility Functions

ALTimeDate class

FromJulian()	Set day/month/year from Julian day number

GetDosDate()	Convert the date portion of an ALTimeDate object to 16-bit DOS format

GetDosTime()	Convert the time portion of an ALTimeDate object to 16-bit DOS format

GetTimeDate()	Get time/date from C RTL format

GetUnixTime()	Extract the time/date of an object into UNIX format

SetTimeDate()	Convert time/date from C RTL format to ArchiveLib internal format

SetTimeDate()	Convert 32-bit time/date format to ArchiveLib internal format

ToJulian()	Convert month/day/year to the Julian day

Valid()	Checks to see if the time/date stamp is valid


ALWildCardExpander class
Utility Functions

ALWildCardExpander class

ALWildCardExpander()	Constructor for ALWildCardExpander class

ALWildCardExpander()	Create an ALWildCardExpander object with specific file name delimiters

~ALWildCardExpander()	Destructor for ALWildCardExpander class

GetNextFile()	Return pointer to internal name of next storage object


ALMonitor class
Monitoring Functions

ALMonitor class

ALMonitor()	Constructor for ALMonitor class

~ALMonitor()	Destructor for ALMonitor class

ArchiveOperation()	Monitor archive operation

Progress()	Determine progress of archive operation

Access Functions

The following functions can be used by C, Visual Basic, and Delphi programmers to access C++ data members in ALMonitor.

ALMonitorSetJobSize()	Indicate initial size of a monitored job

ALMonitorSetJobSoFar()	Calculate job size before completion

ALMonitorSetObjectSize()	Indicate the size of an object being monitored

ALMonitorSetObjectStart()	Indicate initial size of a monitored object before completion

ALStorageSetMonitor()	Assign monitor to storage object


ALBarGraph class
Monitoring Functions

ALBarGraph class

ALBarGraph()	Constructor for ALBarGraph class

~ALBarGraph()	Destructor for ALBarGraph class


ALSpinner class
Monitoring Functions

ALSpinner class

ALSpinner()	Constructor for ALSpinner class

~ALSpinner()	Destructor for ALSpinner class


ALWindowsMessage class
Monitoring Functions

ALWindowsMessage class

ALWindowsMessage()	Constructor for ALWindowsMessage class

~ALWindowsMessage()	Destructor for ALWindowsMessage class


ALOs2Message class
Monitoring Functions

ALOs2Message class

ALOs2Message()	Constructor for OS/2 PM monitor object

~ALOs2Message()	The PM monitor object destructor


Stand-alone OS/2 Functions
Monitoring Functions

Stand-alone OS/2 Functions

The following functions can be used with window controls in the IBM OS/2 graphical user interface:

CenterWindow()	Center a window on the screen

SetupSlider()	Setup a control to work with a monitor

TrimSystemMenu()	Trim most of the options from the system menu


~ALStorage
ALStorage::~ALStorage()

see also	example

Destructor for ALStorage class

Synopsis

#include "arclib.h"

 virtual ~ALStorage()

 void deleteALStorage( hALStorage this_object )

 Declare Sub deleteALStorage Lib "AL20LW"  ByVal this_object& )

 procedure deleteALStorage( this_object : hALStorage );

Arguments

this_object

Handle to the ALStorage object

Function

This function will call the destructor for the derived class (e.g. ALFile).  C, Visual Basic, and Delphi programmers don't have access to the destructors for the derived classes, since they can always call this base class destructor.

A sample piece of code including ~ALStorage(), is shown below.

delete object;

Returns

N/A


~ALStorage() see also
See Also

ALFile::ALFile(), ALMemory::ALMemory()


~ALStorage() example
See example programs EX04PM.CPP, EX04WIN.CPP, EX04WIN.C, EX11CON.C, and EX18VB.FRM.


ClearError() - ALStorage class
ALStorage::ClearError()

see also	example

Reset the error status for a storage object

Synopsis

#include "arclib.h"

 void ALStorage::ClearError()

 void ALStorageClearError( hALStorage this_object )

 Declare Sub ALStorageClearError Lib "AL20LW" ( ByVal this_object& )

 procedure ALStorageClearError( this_object : hALStorage );

Arguments

this_object

A reference or pointer to the ALStorage object that is going to have its status reset.  Note that the C++ version of this call doesn't have an explicit argument here, since it has access to 'this' implicitly.

Function

An ALStorage object carries around a status object in its mStatus member.  This member might get set to an error condition.  Because error conditions are not cleared automatically by the library, you will have to manually clear them with a call to this function.

A sample piece of code including ClearError() is shown below.

if ( file.mstatus < AL_SUCCESS ){ cout << "Error on file"; file.ClearError();

Returns

None.


ClearError() see also - ALStorage class
See Also

ALStatus::SetError()


ClearError() example - ALStorage class
See example program EX00MFC.CPP.


Close() - ALStorage class
ALStorage::Close()

see also	example

Close storage object

Synopsis

#include "arclib.h"

 virtual int Close()

 int ALStorageClose( hALStorage this_object )

 Declare Function ALStorageClose Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALStorageClose( this_object : hALStorage ) : Integer;

Arguments

this_object

Handle to the ALStorage object

Function

ALStorage::Close() deletes the I/O buffer if it is still present.  Derived classes can call this version of Close() to save a few bytes of code; however, most derived classes will need to override this virtual function for class-specific reasons.  For example, ALFile::Close() flushes the I/O buffer and then calls the operating system function to physically close the file.

Files or other storage objects that are left open are automatically closed when their destructor is called.  However, storage objects that are left open use up memory for their internal buffers; for this reason we recommend that you routinely use this function to close storage objects.

A sample code piece including Close() is shown below.

 	ALFile output( "output02.dat" );

 	output.Create();

 	for ( short i = 0 ; i < 100 ; i++ )

     output.WritePortableShort( i );

  	output.Close();

Returns

ALStorage::Close() returns AL_SUCCESS (or 0) if the function was successful.  If the function was not successful, an error code is returned.


Close() see also - ALStorage class
See Also

ALStorage::Open(), ALStorage::Create()


Close() example - ALStorage class
See example programs EX09CON.CPP, EX12WIN.CPP, EX10WIN.C, EX14CON.C, EX10VB.FRM, and EX10UNIT.PAS.


Compare() - ALStorage class
ALStorage::Compare()

see also	example

Compare contents of two files

Synopsis

#include "arclib.h"

 int Compare( ALStorage &test_object )

 int ALStorageCompare( hALStorage this_object, hALStorage test_object )

 Declare Function ALStorageCompare Lib "AL20LW" ( ByVal this_object&, ByVal test_object &) As Integer

 function ALStorageCompare( this_object : hALStorage; test_object : hALStorage ) : Integer;

Arguments

this_object

Handle to the ALStorage object

test_object

The storage object that will be compared to this_object

Function

ALStorage::Compare() compares the contents of two storage objects.  The function opens the files (if necessary) and compares each byte.  Any errors that occur will result in an error code being returned.

A sample code piece including Compare() is shown below.

ALFile original( "CONFIG.SYS" );

ALFile backup( "CONFIG.BAK" );

cout << "Comparison returns "  << original.Compare( backup );

Returns

ALStorage::Compare() returns one of the following values:

Return Value	Meaning

AL_SUCCESS	storage objects are identical

AL_COMPARE_ERROR	storage objects are different


Compare() see also - ALStorage class
See Also

ALStorage::GetCrc32()


Compare() example - ALStorage class
See example programs EX04PM.CPP, EX04WIN.CPP, EX12CON.CPP ,EX04WIN.C, EX18CON.C, EX04VB.FRM, and EX04UNIT.PAS.


Create() - ALStorage class
ALStorage::Create()

see also	example

Create new storage object

Synopsis

#include "arclib.h"

 virtual int Create()

 int ALStorageCreate( hALStorage this_object, long desired_size )

 Declare Function ALStorageCreate Lib "AL20LW" ( ByVal this_object&, ByVal desired_size& ) As Integer

 function ALStorageCreate( this_object : hALStorage; desired_size : Long  ) : Integer;

Arguments

this_object

Handle to the ALStorage object

desired_size

If you know in advance how much space a storage object is going to occupy, you can pass that number as the desired_size argument.  If you don't know how many bytes the storage object is going to need, pass -1L as the argument.

Function

   ALStorage::Create() allocates the object's I/O buffer and initializes all of the pointers.  When you use this function to create a file, any previous copy of the file with the same name is erased.

A sample code piece including Create() is  shown below.

    ALStorage *output = new ALMemory( "data" );

    output->Create();

Returns

ALStorage::Create() returns AL_SUCCESS if the function was successful.  An error code is returned if the function was not successful.


Create() see also - ALStorage class
See Also

ALStorage::Delete(), ALStorage::Open()


Create() example - ALStorage class
See example programs EX08CON.CPP, EX10WIN.C, EX11CON.C, EX10VB.FRM, and EX10UNIT.PAS.


Delete() - ALStorage class
ALStorage::Delete()

see also	example

Delete storage object's underlying system object

This is a pure virtual function, a version of which does not exist for ALStorage.  This function is defined by the derived class ALFile or the derived ALMemoryBase family.

Synopsis

#include "arclib.h"

 virtual int Delete()

 int ALStorageDelete( hALStorage this_object )

 Declare Function ALStorageDelete Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALStorageDelete( this_object : hALStorage ) : Integer;

Arguments

this_object

Handle to the ALStorage object

Function

ALStorage::Delete() deletes a storage object's underlying file or storage object.  It is one of a handful of functions that manipulate the underlying operating system physical objects represented by the base class, ALStorage (other such functions include Close(), Create(), and Rename()).

A sample piece of code including Delete() is shown below.

file.Delete();

Returns

ALStorage::Delete() returns AL_SUCCESS if the function was successful.  An error code is returned if the function was not successful.


Delete() see also - ALStorage class
See Also

ALStorage::Open(), ALStorage::Create()


Delete() example - ALStorage class
See example programs EX04WIN.CPP, EX18CON.CPP, EX04WIN.C, EX18CON.C, and EX18VB.FRM.


FlushBuffer() - ALStorage class
ALStorage::FlushBuffer()

see also	example

Flush data blocks from the I/O storage buffer

This is a pure function, a version of which does not exist for ALStorage.  This function is defined by derived class ALFile or the derived ALMemoryBase family.

Synopsis

#include "arclib.h"

 virtual int FlushBuffer()

 int ALStorageFlushBuffer( hALStorage this_object )

 Declare Function ALStorageFlushBuffer Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALStorageFlushBuffer( this_object : hALStorage ) : Integer;

Arguments

this_object

Handle to the ALStorage object

Function

ALStorage::FlushBuffer() flushes output data from the object's I/O buffer.  This is one of a handful of core functions that any derived class must implement (another is ALStorage::LoadBuffer() described in this chapter).  FlushBuffer() is internally called when the ALStorage::WriteChar() or ALStorage::WriteBuffer() functions write past the end of the I/O buffer, but it can be called anytime.  In particular, a programmer must flush the buffer when switching from write mode to read mode.  The ALFile implementation of this function calls the C RTL write() function.  The ALMemoryBase family calls memcpy() to flush the buffer.  The protected function, GrowBuffer(), may need to be called first.

A sample piece of code including FlushBuffer() is shown below.

file.WriteChar( data );

file.FlushBuffer();

file.ReadPkLong( width );

Returns

ALStorage::FlushBuffer() returns AL_SUCCESS if the function was successful.  An error code is returned if the function was not successful.


FlushBuffer() see also - ALStorage class
See Also

ALStorage::LoadBuffer()


FlushBuffer() example - ALStorage class
See example programs EX14CON.C and EX11VB.FRM.


GetCrc32() - ALStorage class
ALStorage::GetCrc32()

see also	example

Get CRC value

Synopsis

#include "arclib.h"

 long GetCrc32()

 long ALStorageGetCrc32( hALStorage this_object )

 Declare Function ALStorageGetCrc32 Lib "AL20LW" ( ByVal this_object& ) As Long

 function ALStorageGetCrc32( this_object : hALStorage ) : Integer;

Arguments

this_object

Handle to the ALStorage object

Function

ALStorage::GetCrc32() returns the 32-bit CRC for a storage object.  This number is only meaningful if the CRC calculation was enabled with a call to ALStorage::InitCrc32(), all the data in the file has been read or written, and the file has been closed.

There is an exception to this.  Storage objects that were created by reading directory information from an archive will have their mlCrc32 data member set to the correct value.

A sample code piece including GetCrc32() is shown below.

    input.InitCrc32();

    while ( ( c = input.ReadChar() ) >= 0 )

        ;

    input.Close();

    cout << "The file's CRC is: "

             << hex

             << input.GetCrc32()

             << endl;

Returns

ALStorage::GetCrc32() returns the 32-bit CRC and stops updating CRC values.  No errors are returned.


GetCrc32() see also - ALStorage class
See Also

ALStorage::InitCrc32()


GetCrc32() example - ALStorage class
See example program EX08CON.CPP.


GetSize() - ALStorage class
ALStorage::GetSize()

see also	example

Get size data of files opened with Open()

Synopsis

#include "arclib.h"

 long GetSize()

 long ALStorageGetSize( hALStorage this_object )

 Declare Function ALStorageGetSize Lib "AL20LW" ( ByVal this_object& ) As Long

 function ALStorageGetSize( this_object : hALStorage ) : LongInt;

Arguments

this_object

Handle to the ALStorage object

Function

ALStorage::GetSize() retrieves the file size data of files opened with the ALStorage::Open() function.  All files also have their sizes updated when they are closed.  This means that after creating, writing, and closing a file, you can determine its size and CRC.

A sample code piece including GetSize() is shown below.

    ALFile input( "INPUT01.DAT" );

    cout << "File size before opening: "

             << input.GetSize()

             << "\n";

    input.Open();

    cout << "After opening: "

             << input.GetSize()

             << "\n";

Returns

ALStorage::GetSize() returns -1L if the file length has not been determined (i.e. if the file has not been opened or if the file was opened with ALStorage::Create()).  Any other value indicates the current size of the file.  No errors are returned.


GetSize() see also - ALStorage class
See Also

ALStorage::GetCrc32()


GetSize() example - ALStorage class
See example programs EX05CON.CPP, EX05CON.C, EX14WIN.C, EX21VB.FRM, and EX21UNIT.PAS.


InitCrc32() - ALStorage class
ALStorage::InitCrc32()

see also	example

Begin tracking 32-bit CRC

Synopsis

#include "arclib.h"

 void InitCrc32( unsigned long seed = 0xffffffffL )

 void ALStorageInitCrc32(  hALStorage this_object, unsigned long seed )

 Declare Sub ALStorageInitCrc32 Lib "AL20LW" ( ByVal this_object&, ByVal seed& )

 procedure ALStorageInitCrc32( this_object : hALStorage; seed : LongInt );

Arguments

this_object

Handle to the ALStorage object

seed

Initial CRC value.  For C++, the default value is 0xffffffffL, and is used by most 32-bit CRC calculations.

There are no default parameter values for C, Visual Basic, and Delphi.

Function

ALStorage::InitCrc32() is used to track the CRC and, by decompression functions, to verify correct file expansion.  ALStorage uses the same 32-bit CRC used by programs like ARJ and PKZIP.  To obtain the proper CRC values, the initial seed for the 32-bit CRC should be set to all 1's.  If you are a C++ user, this function's default parameter takes care of this for you.

To obtain the same CRC as ARJ or PKZIP (after the entire file has been read or closed), you can call ALStorage::GetCrc32() and invert all of the bits, as shown below:

long my_crc = ~object.GetCrc32();

A sample code piece including InitCrc32() is shown below.

    ALFile test( "input02.dat" );

    test.Open();

    while ( test.ReadChar() >>= 0 )

        ;

    cout << "CRC is: " << hex << test.GetCrc32() << "\n";

Returns

None


InitCrc32() see also - ALStorage class
See Also

ALStorage::GetCrc32()


InitCrc32() example - ALStorage class
See example program EX08CON.CPP.


IsOpen() - ALStorage class
ALStorage::IsOpen()

see also	example

Determine whether storage object is open

Synopsis

#include "arclib.h"

 int IsOpen()

 int ALStorageIsOpen( hALStorage this_object )

 Declare Function ALStorageIsOpen Lib "AL20LW" (  ByVal this_object& ) As Integer

 function ALStorageIsOpen( this_object : hALStorage ) : Integer;

Arguments

this_object

Handle to the ALStorage object

Function

ALStorage::IsOpen() determines whether or not the storage object is presently open.  This is done by checking to see if the internal buffer has been allocated; if it has, the object is open.

A sample code piece including IsOpen() is shown below.

   if ( file.IsOpen() )

        file.Close();

   file.Delete();

Returns

ALStorage::IsOpen() returns one of the following values:

Return Value	Meaning

0	storage object is closed

1	storage object is open


IsOpen() see also - ALStorage class
See Also

ALStorage::Open(), ALStorage::Close()


IsOpen() example - ALStorage class
See example programs EX11CON.CPP and EX11CON.C.


LoadBuffer() - ALStorage class
ALStorage::LoadBuffer()

see also	example

Load data into the I/O buffer

Synopsis

#include "arclib.h"

 virtual int LoadBuffer( long address )

 int ALStorageLoadBuffer( hALStorage this_object, long address )

 Declare Function AlStorageLoadBuffer Lib "AL20LW" ( ByVal this_object&, ByVal address& ) As Integer

 function ALStorageLoadBuffer( this_object : hALStorage; address : String ) : Integer;

Arguments

this_object

Handle to the ALStorage object

address

Data block address

Function

ALStorage::LoadBuffer() loads data blocks from the physical underlying storage object into the I/O buffer used by the base class.  LoadBuffer() is normally called when a ALStorage::ReadChar() or ALStorage::ReadBuffer() function runs out of data.  It can also be used to position the file pointer.

This is one of a handful of core functions that any derived class must implement.  The ALFile implementation of this function calls the C RTL read() function.  The ALMemoryBase family calls memcpy() to load the buffer.

A sample code piece for including LoadBuffer() is shown below.

 void read_record( int record_number )

 {

   database->LoadBuffer(record_number * sizeof(RECORD) );

   database->ReadBuffer(record, sizeof(RECORD) );

 }

Returns

ALStorage::LoadBuffer() returns AL_SUCCESS (or 0) if the function was successful.  If the function was not successful, an error code is returned.


LoadBuffer() see also - ALStorage class
See Also

ALStorage::FlushBuffer()


LoadBuffer() example - ALStorage class
See example program EX11VB.FRM.


Open() - ALStorage class
ALStorage::Open()

see also	example

Open file for read/write

Synopsis

#include "arclib.h"

 virtual int Open()

 int ALStorageOpen( hALStorage this_object )

 Declare Function ALStorageOpen Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALStorageOpen( this_object : hALStorage ) : Integer;

Arguments

this_object

Handle to the ALStorage object

Function

ALStorage::Open() allows a storage object to be opened for read-write operations.  Derived class versions of Open() can call the base version to allocate the I/O buffer, initialize indices and other such activities.  The derived class is responsible for establishing some sort of connection to the underlying object, such as opening a file and getting a file handle.

Files that are left open are automatically closed when their destructor is called.  However, storage objects that are left open use up memory for their internal buffers.  We recommend that you use the ALStorage::Close() function routinely to close files.

A sample code piece including Open() is shown below.

     void erase_file( char *name )

     {

         ALFile file( name );

         file.Open();

         long length = file.GetSize();

         while ( length-- > 0 )

             file.WriteChar( '0' );

         file.Close();

     }

Returns

ALStorage::Open() returns AL_SUCCESS (or 0) if the function was successful.  If the function was not successful, an error code is returned.


Open() see also - ALStorage class
See Also

ALStorage::Create()


Open() example - ALStorage class
See example programs EX08CON.CPP, EX12WIN.CPP, EX10WIN.C, EX11CON.C, EX10VB.FRM, and EX10UNIT.PAS.


ReadBuffer() - ALStorage class
ALStorage::ReadBuffer()

see also	example

Read in a data block

Synopsis

#include "arclib.h"

 size_t ReadBuffer( unsigned char *buffer, size_t length )

 size_t ALStorageReadBuffer( hALStorage this_object, unsigned char *buffer, size_t length )

 Declare Function ALStorageReadBuffer Lib "AL20LW" ( ByVal this_object&, ByVal buffer$, ByVal length% ) As Integer

 function ALStorageReadBuffer( this_object : hALStorage; buffer : PChar; length : Integer ) : Integer;

Arguments

this_object

Handle to the ALStorage object

buffer

Pointer to destination data buffer

length

Number of characters desired

Function

ALStorage::ReadBuffer() reads the specified number of characters or fewer into a data block from a storage object.  This function works by reading from or writing to the I/O buffer whenever possible.  If necessary, calls are made to ALStorage::LoadBuffer() to refill the buffer.

This function is not a virtual function.  Derived classes should not attempt to override it.

A sample code piece including ReadBuffer() is shown below.

    for ( ; ; ) {

        length = input_file.ReadBuffer( buf, 1024 );

        if ( length <= 0 )

            break;

        output_file.WriteBuffer( buf, length );

    }

Returns

ALStorage::ReadBuffer() returns the number of bytes read in.


ReadBuffer() see also - ALStorage class
See Also

ALStorage::ReadChar(), ALStorage::WriteChar()


ReadBuffer() example - ALStorage class
See example programs EX11CON.CPP, EX12WIN.CPP, EX11CON.C, EX12WIN.C, EX11VB.FRM, and EX11UNIT.PAS.


ReadChar() - ALStorage class
ALStorage::ReadChar()

see also	example

Read data from storage object

Synopsis

#include "arclib.h"

 int ReadChar()

 int ALStorageReadChar( hALStorage this_object )

 Declare Function ALStorageReadChar Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALStorageReadChar( this_object : hALStorage ) : Integer;

Arguments

this_object

Handle to the ALStorage object

Function

ALStorage::ReadChar() reads a byte of data from a storage object.  This function works by reading from or writing to a memory buffer whenever possible.  If the buffer is empty, it will be reloaded using ALStorage::LoadBuffer().

ReadChar() is defined as inline, meaning that it can execute very quickly.  The debug version of ArchiveLib may not compile this function as inline.  This generally results in this function running much slower, with the advantage of error checking through assertion statements.  C, Visual Basic, and Delphi users never get inline code.

This function is not a virtual function.  Derived classes should not attempt to override it.

A sample piece of code including ReadChar() is shown below.

ALFile f( "input.dat" );

f.Open();

int c;

for( c = f.ReadChar();

       c >= 0;

       c = f.ReadChar() )

     cout << c;

Returns

ALStorage::ReadChar() returns one of the following values:

Return Value	Meaning

AL_EOF	no more data

> = 0	character read

< 0	error occurred.  See mStatus for a detailed list of errors.


ReadChar() see also - ALStorage class
See Also

ALStorage::ReadBuffer(), ALStorage::WriteChar()


ReadChar() example - ALStorage class
See example programs EX09CON.CPP, EX11CON.C, and EX21WIN.C.


ReadGlLong() - ALStorage class
ALStorage::ReadGlLong()

see also	example

Read 32-bit data word in little endian format

Synopsis

#include "arclib.h"

 int ReadGlLong( long &long_data )

 int ALStorageReadGlLong( hALStorage this_object, long *long_data )

 Declare Function ALStorageReadGlLong Lib "AL20LW" ( ByVal this_object&, long_data& ) As Integer

 function ALStorageReadGlLong( this_object : hALStorage; var long_data : LongInt ) : Integer;

Arguments

this_object

Handle to the ALStorage object

long_data

A long integer that will receive the data read from the storage object

Function

ALStorage::ReadGlLong() reads a 32-bit data word stored in little endian format; this facilitates storing storage objects and archiving data in a portable format.  The data is returned to the calling program through a single reference argument.  This function is heavily used in the implementation of the ALGlArchive class.

End users of ArchiveLib may not find this function particularly useful.

A sample code piece including ReadGlLong(), is shown below.

    file->ReadGlLong( buffer_size );

    cout << "Buffer size stored in archive"

             << buffer_size;

Returns

ALStorage::ReadGlLong() returns AL_SUCCESS (or 0) if the function was successful.  If the function was not successful, an error code is returned.


ReadGlLong() see also - ALStorage
See Also

ALStorage::WriteGlLong()


ReadGlLong() example - ALStorage class
See example programs EX11CON.CPP and EX11CON.C.


ReadGlShort() - ALStorage class
ALStorage::ReadGlShort()

see also	example

Read 16-bit data word in little endian format

Synopsis

#include "arclib.h"

 int ReadGlShort( short int &short_data )

 int ALStorageReadGlShort( hALStorage this_object, short int *short_data )

 Declare Function ALStorageReadGlShort Lib  "AL20LW" ( ByVal this_object&, short_data% ) As Integer

 function ALStorageReadGlShort( this_object : hALStorage; var short_data : Integer ) : Integer;

Arguments

this_object

Handle to the ALStorage object

short_data

A short integer that will receive the data read from the storage object

Function

ALStorage::ReadGlShort() reads a 16-bit data word in little endian format; this facilitates storing storage objects and archiving data in a portable format.  The data is returned to the calling program through a single reference argument.  The primary use for this function is to store a storage object and archive data in a portable format.  This function is heavily used in the implementation of the ALGlArchive class.

End users of ArchiveLib may not find this function particularly useful.

A sample code piece for including ReadGlShort() is shown below.

    file->ReadGlShort( count );

    cout << count << " records stored in file" << "\n";

Returns

ALStorage::ReadGlShort() returns AL_SUCCESS (or 0) if the function was successful.  If the function was not successful, an error code is returned.


ReadGlShort() see also - ALStorage class
See Also

ALStorage::WriteGlShort()


ReadGlShort() example - ALStorage class
See example programs EX11CON.CPP and EX11CON.C.


ReadPkLong() - ALStorage class
ALStorage::ReadPkLong()

see also	example

Read a long data word using PKWare's format

Synopsis

#include "arclib.h"

 int ALStorage::ReadPkLong( long &long_data )

 int ALStorageReadPkLong( hALStorage this_object, long *data )

 Declare Function ALStorageReadPkLong Lib "AL20LW" ( ByVal this_object&, long_data& ) As Integer

 function ALStorageReadPkLong( this_object : hALStorage; var long_data : LongInt ) : Integer;

Arguments

this_object

A reference or pointer to the ALStorage object that contains the long word to be read

long_data

A pointer to the long data element that is going to receive the word read in from the storage object

Function

This function reads long integers in native PKWare format.  It is complementary to ReadGlLong(), which reads data in Greenleaf format.  Unfortunately, Greenleaf format and PKWare format are not identical.

End users of ArchiveLib may not find this function particularly useful.

A sample piece of code including ReadPkLong() is shown below.

    file->ReadPkLong( buffer_size );

    cout << "Buffer size stored in archive"

             << buffer_size;

Returns

ALStorage::ReadPkLong() returns AL_SUCCESS (or 0) if the function was successful.  If the function was not successful, an error code is returned.


ReadPkLong() see also - ALStorage class
See Also

ALStorage::WritePkLong()


ReadPkLong() example - ALStorage class
See example programs EX11CON.CPP and EX11CON.C.


ReadPkShort() - ALStorage class
ALStorage::ReadPkShort()

see also	example

Read a short data word using PKWare's format

Synopsis

#include "arclib.h"

 int ALStorage::ReadPkShort( short &short_data )

 int ALStorageReadPkShort( hALStorage this_object, short *short_data )

 Declare Function ALStorageReadPkShort Lib "AL20LW" ( ByVal this_object&, short_data% ) As Integer

 function ALStorageReadPkShort( this_object : hALStorage; var short_data : Integer ) : Integer;

Arguments

this_object

A reference or pointer to the ALStorage object that contains the short word to be read

short_data

A pointer to the short data element that is going to receive the word read in from the storage object

Function

This function reads short integers in native PKWare format.  It is complementary to ReadGlShort(), which reads data in Greenleaf format.  Unfortunately, Greenleaf format and PKWare format are not identical.

End users of ArchiveLib may not find this function particularly useful.

A sample code piece for including ReadPkShort() is shown below.

    file->ReadPkShort( count );

    cout << count << " records stored in file" << "\n";

Returns

ALStorage::ReadPkShort() returns AL_SUCCESS (or 0) if the function was successful.  If the function was not successful, an error code is returned.


ReadPkShort() see also - ALStorage class
See Also

ALStorage::WritePkShort()


ReadPkShort() example - ALStorage class
See example programs EX11CON.CPP and EX11CON.C.


ReadString() - ALStorage class
ALStorage::ReadString()

see also	example

Read data string from storage object

Synopsis

#include "arclib.h"

 int ReadString( ALName &name, short int length = -1 )

Arguments

name

Storage object which will be loaded with the string

length

Length of string to be read; if unknown, pass -1

Function

ALStorage::ReadString() reads a string of data from a storage object stored in an ArchiveLib directory.  These variable length strings are always stored using a short integer header followed by a string of bytes.  The integer header indicates how many bytes will follow.

End users of ArchiveLib may not find this function particularly useful.

A sample piece of code including ReadString() is shown below.

file.ReadString( comment );

Returns

ALStorage::ReadString() returns AL_SUCCESS (or 0) if the function was successful.  If the function was not successful, an error code is returned.


ReadString() see also - ALStorage class
See Also

ALStorage::WriteString(), ALStorage::WriteGlLong()


ReadString() example - ALStorage class
N/A


Rename() - ALStorage class
ALStorage::Rename()

see also	example

Rename storage object

This is a pure virtual function, a version of which does not exist for ALStorage.  This function is defined by the derived class ALFile or the derived ALMemoryBase family.

Synopsis

#include "arclib.h"

 virtual int Rename( const char *new_name = 0, int delete_on_clash = 1 )

 int ALStorageRename( hALStorage this_object, char *new_name,  int delete_on_clash )

 Declare Function ALStorageRename Lib "AL20LW" ( ByVal this_object&, ByVal new_name$, ByVal delete_on_clash% ) As Integer

 function ALStorageRename( this_object : hALStorage; new_name : String; delete_on_clash : Integer ) : Integer;

Arguments

this_object

Handle to the ALStorage object

new_name

New name of storage object.  For C++, 0 is the default value and is used to indicate that the intended new object name has already been stored in the mName data member.  When zero, this function will try to rename the old name with the current name.  For example:

object.mName = "NEW.DAT";

object.Rename();

This is the same as object.Rename( "NEW.DAT" );

delete_on_clash

Flag to determine disposition (delete, retain) of an existing storage object with the same name as the new storage object.  For C++, the default is 1 (TRUE) which means delete.

There are no default parameter values for C, Visual Basic, and Delphi.

Function

ALStorage::Rename() copies a new storage object name to the internal name buffer of the object.  Like ALStorage::Delete(), it manipulates the underlying operating system storage objects represented by the base class ALStorage.

If no new name is specified, the file will be renamed using the values in the mName member, changing from mName.mszOldName to mName.mszName.  This means you can change mName and then call Rename() to make the change effective.

A sample code piece including Rename() is shown below.

    ALFile original( "AUTOEXEC.BAT" );

    original.mName.ChangeExtension( ".BAK" );

    original.Rename();

Returns

ALStorage::Rename() returns AL_SUCCESS (or 0) if the function was successful.  An error code is returned if the function was not successful.


Rename() see also - ALStorage class
See Also

ALStorage::UnRename()


Rename() example - ALStorage class
See example programs EX12WIN.CPP and EX12WIN.C.


RenameToBackup() - ALStorage class
ALStorage::RenameToBackup()

see also	example

Rename storage object to use as backup copy

This is a pure virtual function, a version of which does not exist for ALStorage.  This function is defined by derived class ALFile or the derived ALMemoryBase family.

Synopsis

#include "arclib.h"

 virtual int RenameToBackup(  int delete_on_clash = 1 )

 int ALStorageRenameToBackup(  hALStorage this_object, int delete_on_clash )

 Declare Function ALStorageRenameToBackup Lib "AL20LW" ( ByVal this_object&, ByVal delete_on_clash% ) As Integer

 function ALStorageRenameToBackup( this_object : hALStorage; delete_on_clash : Integer ) : Integer;

Arguments

this_object

Handle to the ALStorage object

delete_on_clash

Flag to determine disposition (delete, retain) of an existing storage object with the same name as the new storage object.  For C++, the default is 1 (TRUE) which means  delete.

There are no default parameter values for C, Visual Basic, and Delphi.

Function

ALStorage::RenameToBackup() renames an existing storage object to a new name, designating it as a backup object.

A sample piece of code including RenameToBackup() is shown below.

file.RenameToBackup();

Returns

ALStorage::RenameToBackup() returns AL_SUCCESS (or 0) if the function was successful.  An error code is returned if the function was not successful.


RenameToBackup() see also - ALStorage class
See Also

ALStorage::Rename()


RenameToBackup() example - ALStorage class
See example programs EX12WIN.CPP and EX12WIN.C.


Seek() - ALStorage class
ALStorage::Seek()

see also	example

Reposition input stream to new file position

This is a pure virtual function, a version of which does not exist for ALStorage.  This function is defined by derived class ALFile or the derived ALMemoryBase family.

Synopsis

#include "arclib.h"

 int Seek( long address )

 int ALStorageSeek( hALStorage this_object, long address )

 Declare Function ALStorageSeek Lib "AL20LW" ( ByVal this_object, ByVal address ) As Integer

 function ALStorageSeek( this_object : hALStorage; address : LongInt ) : Integer;

Arguments

this_object

Handle to the ALStorage object

address

Data block address where the file pointer will be positioned

Function

ALStorage::Seek() lets you reposition your input stream to a new I/O position.  This function takes care of switching a storage object out of the write mode by flushing the output buffer.  The object will then be safe for a call to ALStorage::ReadChar().

A sample code piece including Seek() is shown below.

  file.Seek( 0L );

  if ( file.ReadChar() == 'M' && file.ReadChar() == 'Z' )

      cout << "This file is an executable\n";

Returns

ALStorage::Seek() returns AL_SUCCESS (or 0) if the function was successful.  An error code is returned if the function was not successful.


Seek() see also - ALStorage class
See Also

ALStorage::LoadBuffer()


Seek() example - ALStorage class
See example programs EX12CON.CPP, EX12WIN.CPP, EX12WIN.C, EX18CON.C, EX11VB.FRM, and EX11UNIT.PAS.


Tell() - ALStorage class
ALStorage::Tell()

see also	example

Indicate where next byte to read/write will go

Synopsis

#include "arclib.h"

 long Tell()

 long ALStorageTell( hALStorage this_object )

 Declare Function ALStorageTell Lib "AL20LW" (  ByVal this_object& ) As Long

 function ALStorageTell( this_object : hALStorage ) : LongInt;

Arguments

this_object

Handle to the ALStorage object

Function

ALStorage::Tell() returns a long value indicating where the next byte to be read or written will go.  This is determined using the read and write pointers within the I/O buffer.

A sample code piece including Tell() is shown below.

    printf( "File is currently at %ld\n", input.Tell() );

Returns

ALStorage::Tell() returns the current position of the object I/O pointer.


Tell() see also - ALStorage class
See Also

ALStorage::Seek(), ALStorage::WriteBuffer()


Tell() example - ALStorage class
See example programs EX11CON.CPP and EX11CON.C.


UnRename() - ALStorage class
ALStorage::UnRename()

see also	example

Revert filename to previous name

This is a pure virtual function, a version of which does not exist for ALStorage.  This function is defined by derived class ALFile or the derived ALMemoryBase family.

Synopsis

#include "arclib.h"

 virtual int UnRename( int delete_on_clash = 1 )

 int ALStorageUnRename( hALStorage this_object, int delete_on_clash )

 Declare Function ALStorageUnRename Lib "AL20LW" ( ByVal this_object&, ByVal delete_on_clash% ) As Integer

 function ALStorageUnRename( this_object : hALStorage; delete_on_clash : Integer ) : Integer;

Arguments

this_object

Handle to the ALStorage object

delete_on_clash

Flag to determine disposition (delete, retain) of an existing storage object with the same name as the new storage object.  For C++, the default is 1 (TRUE) which means delete.

Function

ALStorage::UnRename() reverts a filename to its previous name.  For example, you rename an original file AL.DAT to the new backup file name AL.BAK, only to detect an error in the file after processing the input.  You can then opt to delete the new file, AL.DAT, and restore the old name.

This function is only successful if the mName data member has an old name stored in it.  It will always have an old name if you modified it via assignment.

A sample code piece including UnRename() is shown below.

    if ( new_file.mStatus < 0 )

        file.UnRename();

    else

        file.Delete();

Returns

ALStorage::UnRename() returns AL_SUCCESS (or 0) if the function was successful.  An error code is returned if the function was not successful.


UnRename() see also - ALStorage class
See Also

ALStorage::Rename(), ALStorage::Delete()


UnRename() example - ALStorage class
See example programs EX12WIN.CPP and EX12WIN.C.


WriteBuffer() - ALStorage class
ALStorage::WriteBuffer()

see also	example

Write a block to the storage object

Synopsis

#include "arclib.h"

 size_t WriteBuffer( const unsigned char *buffer, size_t length )

 size_t ALStorageWriteBuffer( hALStorage this_object, unsigned char *buffer, size_t length )

 Declare Function ALStorageWriteBuffer Lib "AL20LW" ( ByVal this_object&, ByVal buffer$, ByVal length% ) As Integer

 function ALStorageWriteBuffer( this_object : hALStorage; buffer : PChar; length : Integer ) : Integer;

Arguments

this_object

Handle to the ALStorage object

buffer

Data block containing data to be written to the storage object

length

Number of characters to be written

Function

ALStorage::WriteBuffer() writes the specified number of characters in a data block to a storage object.  This function works by writing to an I/O buffer whenever possible.  When the I/O buffer is filled, a call is made to ALStorage::FlushBuffer().

This function is not a virtual function.  Derived classes should not attempt to override it.

A sample code piece including WriteBuffer() is shown below.

    char *s = "Test data";

    output_file.WriteBuffer( s, strlen( s ) + 1 );

Returns

ALStorage::WriteBuffer() returns the number of bytes written.  This number can indicate the following:

Return Value	Meaning

= length	all bytes successfully written

¹ length parameter	error occurred or EOF (end-of-file).  Check the status of the associated file object by testing mStatus < 0 to determine which of these occurred.


WriteBuffer() see also - ALStorage class
See Also

ALStorage::WriteChar()


WriteBuffer() example - ALStorage class
See example programs EX16CON.CPP, EX16CON.C, EX11VB.FRM, and EX11UNIT.PAS.


WriteChar() - ALStorage class
ALStorage::WriteChar()

see also	example

Write character data to storage object

Synopsis

#include "arclib.h"

 int WriteChar( int c )

 int ALStorageWriteChar( hALStorage this_object, int c )

 Declare Function ALStorageWriteChar Lib "AL20LW" ( ByVal this_object&, ByVal c% ) As Integer

 function ALStorageWriteChar( this_object : hALStorage; c : Integer ) : Integer;

Arguments

this_object

Handle to the ALStorage object

c

character to be written to storage object

Function

ALStorage::WriteChar() writes a byte of data to a storage object, writing to the I/O buffer whenever possible.  If the buffer is full, it will be flushed using FlushBuffer().

ALStorage::WriteChar() is defined as inline, meaning that it can execute very quickly.  The debug version of ArchiveLib may not compile this function as inline; this generally results in this function running much slower.

This function is not a virtual function.  Derived classes should not attempt to override it.

A sample code piece including WriteChar() is shown below.

    for ( int i = 0 ; i < strlen( s ) ) ; i++ )

        WriteChar( s[ i ] );

Returns

ALStorage::WriteChar() returns  AL_SUCCESS (or 0) if the function was successful.  If the function was not successful, an error code is returned.


WriteChar() see also - ALStorage class
See Also

ALStorage::ReadChar()


WriteChar() example - ALStorage class
See example programs EX11CON.CPP, EX10WIN.C, EX11CON.C, and EX14VB.FRM.


WriteGlLong() - ALStorage class
ALStorage::WriteGlLong()

see also	example

Write 32-bit data word in little endian format

Synopsis

#include "arclib.h"

 int WriteGlLong( long long_data)

 int ALStorageWriteGlLong( hALStorage this_object, long long_data )

 Declare Function ALStorageWriteGlLong Lib "AL20LW" (ByVal this_object&, ByVal long_data&) As Integer

 function ALStorageWriteGlLong( this_object : hALStorage; long_data : LongInt ) : Integer;

Arguments

this_object

Handle to the ALStorage object

long_data

Data to be written to the storage object

Function

ALStorage::WriteGlLong() writes a 32-bit data word in little endian format; this facilitates storing storage objects and archiving data in a portable format.  Data is written to the current position in the storage object.  This function is used in the implementation of the ALGlArchive class.

End users of ArchiveLib may not find this function particularly useful.

A sample code piece for including WriteGlLong() is shown below.

    crc32 = input.GetCrc32();

    output.WriteGlLong( crc32 );

Returns

ALStorage::WriteGlLong() returns  AL_SUCCESS (or 0) if the function was successful.  If the function was not successful, an error code is returned.


WriteGlLong() see also - ALStorage class
See Also

ALStorage::ReadGlLong()


WriteGlLong() example - ALStorage class
See example programs EX11CON.CPP and EX11CON.C.


WriteGlShort() - ALStorage class
ALStorage::WriteGlShort()

see also	example

Write 16-bit data word in little endian format

Synopsis

#include "arclib.h"

 int WriteGlShort( short int short_data )

 int ALStorageWriteGlShort( hALStorage this_object, short int short_data )

 Declare Function ALStorageWriteGlShort Lib "AL20LW" ( ByVal this_object&, ByVal short_data% ) As Integer

 function ALStorageWriteGlShort( this_object : hALStorage; short_data : Integer ) : Integer

Arguments

this_object

Handle to the ALStorage object

short_data

Data to be written to the storage object

Function

ALStorage::WriteGlShort() writes a 16-bit data word in little endian format; this facilitates storing storage objects and archiving data in a portable format.  Data is written to the current position in the storage object.  This function is used in the implementation of the ALGlArchive class.

End users of ArchiveLib may not find this function particularly useful.

A sample code piece including WriteGlShort() is shown below.

    int result = file.WriteGlShort( length );

    if ( result < AL_SUCCESS )

       cout << "error: " << file.mStatus;

Returns

ALStorage::WriteGlShort() returns  AL_SUCCESS (or 0) if the function was successful.  If the function was not successful, an error code is returned.


WriteGlShort() see also - ALStorage class
See Also

ALStorage::ReadGlShort()


WriteGlShort() example - ALStorage class
See example programs EX11CON.CPP and EX11CON.C.


WritePkLong() - ALStorage class
ALStorage::WritePkLong()

see also	example

Write a long data word using PKWare's format

Synopsis

#include "arclib.h"

 int ALStorage::WritePkLong( long long_data )

 int ALStorageWritePkLong( hALStorage this_object, long long_data )

 Declare Function ALStorageWritePkLong Lib "AL20LW" ( ByVal this_object&, ByVal long_data& ) As Integer

 function ALStorageWritePkLong( this_object : hALStorage; long_data : LongInt ) : Integer;

Arguments

this_object

A reference or pointer to the ALStorage object that will receive the long word

long_data

The long data element that is going to be written to the storage object in PKWare format

Function

This function writes long integers in native PKWare format.  It is complementary to WriteGlLong() which writes data in Greenleaf format.  Unfortunately, Greenleaf format and PKWare format are not identical.

A sample code piece for including WritePkLong() is shown below.

    crc32 = input.GetCrc32();

    output.WritePkLong( crc32 );

Returns

ALStorage::WritePkLong() returns  AL_SUCCESS (or 0) if the function was successful.  If the function was not successful, an error code is returned.


WritePkLong() see also - ALStorage class
See Also

ALStorage::ReadPkLong()


WritePkLong() example - ALStorage class
See example programs EX11CON.CPP and EX11CON.C.


WritePkShort() - ALStorage class
ALStorage::WritePkShort()

see also	example

Write a short data word using PKWare's format

Synopsis

#include "arclib.h"

 int ALStorage::WritePkShort( short short_data )

 int ALStorageWritePkShort( hALStorage this_object, short short_data )

 Declare Function ALStorageWritePkShort Lib "AL20LW" ( ByVal this_object&, ByVal short_data& ) As Integer

 function ALStorageWritePkShort( this_object : hALStorage; var short_data : Integer ) : Integer;

Arguments

this_object

A reference or pointer to the ALStorage object that will receive the short word

short_data

The short data element that is going to be written to the storage object in PKWare format

Function

This function writes short integers in native PKWare format.  It is complementary to WriteGlShort() which writes data in Greenleaf format.  Unfortunately, Greenleaf format and PKWare format are not identical.

A sample code piece including WritePkShort() is shown below.

    int result = file.WritePkShort( length );

    if ( result < AL_SUCCESS )

       cout << "error: " << file.mStatus;

Returns

ALStorage::WritePkShort() returns  AL_SUCCESS (or 0) if the function was successful.  If the function was not successful, an error code is returned.


WritePkShort() see also - ALStorage class
See Also

ALStorage::ReadPkShort()


WritePkShort() example - ALStorage class
See example programs EX11CON.CPP and EX11CON.C.


WriteString() - ALStorage class
ALStorage::WriteString()

see also	example

Write data string to storage object

Synopsis

#include "arclib.h"

 int WriteString( const char *string_data )

 int ALStorageWriteString( hALStorage this_object, char *string_data )

 Declare Function ALStorageWriteString Lib "AL20LW" (ByVal this_object&, ByVal string_data$) As Integer

 function ALStorageWriteString( this_object : hALStorage; string_data : String ) : Integer

Arguments

this_object

Handle to the ALStorage object

string_data

In C++ and C, this is a null-terminated string.  Visual Basic and Delphi use their own native string types.

Function

ALStorage::WriteString() writes a string of data to a storage object.

End users of ArchiveLib may not find this function particularly useful.

A sample code piece including WriteString() is shown below.

    string name;

    cout << "What is your name? ";

    cin >> name;

    data_file.WriteString( name.c_str() );

Returns

ALStorage::WriteString() returns  AL_SUCCESS (or 0) if the function was successful.  If the function was not successful, an error code is returned.


WriteString() see also - ALStorage class
See Also

ALStorage::ReadString()


WriteString() example - ALStorage class
See example programs EX11CON.CPP and EX11CON.C.


YieldTime() - ALStorage class
ALStorage::YieldTime()

see also	example

Yield time to operating system

Synopsis

#include "arclib.h"

 virtual void YieldTime()

Arguments

None

Function

ALStorage::YieldTime() yields time to the operating system, when called by the storage object after loading or flushing a buffer.  Even if a class implements its own version of YieldTime(), it should call this base class version of the function because it takes care of handing time over to Windows or OS/2 and a monitor function.  In addition, this version of YieldTime() will also call a Progress() monitor function for any monitor object attached to the storage object.

A sample code piece including YieldTime() is shown below.

void MyStorageObject::YieldTime()

{

   cout << "." << flush;

   ALStorage::YieldTime();

}

Returns

None.


YieldTime() see also - ALStorage class
See Also

ALStorage::LoadBuffer(), ALStorage::FlushBuffer()


YieldTime() example - ALStorage class
See example programs EX13CON.CPP and EX23WIN.CPP.


ALStorageGetStatusCode()

see also	example

Get status of ALStorage object

Synopsis

#include "arclib.h"

 int ALStorageGetStatusCode( hALStorage this_object )

 Declare Function ALStorageGetStatusCode Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALStorageGetStatusCode( this_object : hALStorage ) : Integer

C, Visual Basic, and Delphi programmers can access the ALStorage data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALStorage object

Function

ALStorageGetStatusCode() returns an integer status value of an ALStorage object.  ArchiveLib does this for objects that have mStatus members, including ALStorage and ALEntryList.  Status members contain an integer indicating the current status of an object.  ALStorageGetStatusCode() retrieves that status value.

A sample code piece including ALStorageGetStatusCode() is shown below.

    if ( ALStorageGetStatusCode( object ) < AL_SUCCESS )

        printf( "Error, prepare to reboot..." );

Returns

ALStorageGetStatusCode() returns the following values:

Return Value	Meaning

AL_SUCCESS	function successful

<  0	The status member of this object was set to an error state at some time in the past.  To clear the error condintion,, call ALStorage::ClearError().


ALStorageGetStatusCode() see also
See Also

ALStorageGetStatusString(), ALStorageGetStatusDetail()


ALStorageGetStatusCode() example
See example program EX04WIN.C.


ALStorageGetStatusDetail()

see also	example

Get detailed error information

Synopsis

#include "arclib.h"

 char *ALStorageGetStatusDetail( hALStorage this_object )

 Declare Function ALStorageGetStatusDetail Lib "AL20LW" (ByVal this_object&) As String

 function ALStorageGetStatusDetail( this_object : hALStorage ) : String;

C, Visual Basic, and Delphi programmers can access the ALStorage data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALStorage object

Function

ALStorageGetStatusDetail() returns detailed information about a specific error message associated with ALStorage.  ArchiveLib does this for objects that have mStatus members, including ALStorage, ALCompressor, ALDecompressor, and ALEntryList.  The detailed message produced by this function includes various data items that might help track down the source of the problem.  These messages are fairly technical, and are intended for use by developers instead of end-users.

A sample piece of code including ALStorageGetStatusDetail() is shown below.

printf( "current status: %s\n",

           ALStorageGetStatusDetail( file ) );

Returns

ALStorageGetStatusDetail() always returns a pointer to the detailed status string.


ALStorageGetStatusDetail() see also
See Also

ALStorageGetStatusString()


ALStorageGetStatusDetail() example
See example programs EX10WIN.C, EX18CON.C, EX10VB.FRM, and EX10UNIT.PAS.


ALStorageGetStatusString()

see also	example

Translate error code into string

Synopsis

#include "arclib.h"

 char *ALStorageGetStatusString( hALStorage this_object )

 Declare Function ALStorageGetStatusString Lib "AL20LW" ( ByVal this_object& ) As String

 function ALStorageGetStatusString( this_object : hALStorage ) : String;

C, Visual Basic, and Delphi programmers can access the ALStorage data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALStorage object

Function

ALStorageGetStatusString() translates the error code in an ALStorage object to a short text string.  ArchiveLib does this for objects that have mStatus members, including ALStorage, ALCompressor, ALDecompressor, and ALEntryList.  When displaying error values to users, the string returned by this function will be much more intelligible than displaying the integer value of the error.

A few sample error code translations include the following:

 	AL_SUCCESS	"Success"

 	AL_END_OF_FILE	"End of file"

 	AL_CANT_OPEN_BUFFER	"Can't allocate buffer"

Returns

ALStorageGetStatusString() always returns a pointer to a short string translation of the current error code.


ALStorageGetStatusString() see also
See Also

ALStorageGetStatusCode(), ALStorageGetStatusDetail()


ALStorageGetStatusString() example
See example programs EX10WIN.C, EX10VB.FRM, and EX10UNIT.PAS.


ALStorageGetType()

see also	example

Return integer value indicating storage object type

Synopsis

#include "arclib.h"

 int ALStorageGetType( hALStorage this_object )

 Declare Function ALStorageGetType Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALStorageGetType( this_object : hALStorage ) : Integer;

C, Visual Basic, and Delphi programmers can access the ALStorage data member miStorageObjectType using this function.  C++ programmers don't need to call this function since they can access the data member directly.

Arguments

this_object

Handle to the ALStorage object

Function

ALStorageGetType() is an access function that returns an integer value indicating the type of storage object the archive is using.  The integers are defined in an enumerated type in the ArchiveLib ALDEFS.H file.  The currently defined values include:

  AL_FILE

  AL_MEMORY

Returns

ALStorageGetType() returns an integer indicating the type of storage object being used.


ALStorageGetType() see also
See Also

ALFile::ALFile(), ALMemory::ALMemory()


ALStorageGetType() example
See example programs EX10WIN.C, EX10VB.FRM, and EX10UNIT.PAS.


ALStorageSetError()

see also	example

Manipulate error code for ALStorage

Synopsis

#include "arclib.h"

 int ALStorageSetError( hALStorage this_object, int error_code, char *text )

 Declare Function ALStorageSetError Lib "AL20LW" ( ByVal this_object&, ByVal error_code%, ByVal text$ ) As Integer

 function ALStorageSetError( this_object : hALStorage; error_code : Integer; text : String ) : Integer;

C, Visual Basic, and Delphi programmers can access the ALStorage data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALStorage object

error_code

Numeric (integer) error code

text

The formatted error message to be stored in the object's mStatus data member.

Function

ALStorageSetError() lets you set the state of an ALStorage object to an error.  This is a useful way to abort an ArchiveLib operation.  To do this, ALStorageSetError() performs two actions:

1.  It sets the error code for the object.

2.  It allocates enough space in mStatus to copy and then hold a detailed description of why the error occurred.

A sample piece of code including ALStorageSetError() is shown below.

hALStorage s;

s = ALArchiveGetStorage( Archive );

ALStorageSetError( s, -100, "Fatal Error" );

Returns

ALStorageSetError() always returns error_code.


ALStorageSetError() see also
See Also

ALStatus::GetStatusCode(), ALStatus::GetStatusString()


ALStorageSetError() example
See example programs EX00WIN.C, EX00VB.FRM, and EX00UNIT.PAS.


ALFile()
ALFile::ALFile()

see also	example

Constructor for ALFile class

Synopsis

#include "arclib.h"

#include "filestor.h"

 ALFile( const char *file_name = "", int buffer_size = 4096, ALCase name_case = AL_LOWER )

 hALStorage newALFile( char *file_name )

 Declare Function newALFile Lib "AL20LW" ( ByVal file_name$ ) As Long

 function newALFile( file_name : String ) : hALStorage;

Arguments

file_name

Name of the file as it is represented on disk.  For C++, the default is "" which is the empty string.  Creating a file with an empty string causes a temporary name to be used or created.

buffer_size

(C++ only) Size of the I/O buffer used after ALFile::Open() is executed.  The default is 4,096 bytes.

name_case

(C++ only) Naming convention of ALFile objects.  Possible choices are AL_UPPER, AL_LOWER, and AL_MIXED.  Under Win16 or DOS, these should be forced to upper or lower case because the operating system implementation for this class is case insensitive.  In these instances, it is generally a good idea to force the names to be all upper or all lower case.  Derived classes will ordinarily set this member to their preferred state.

Function

ALFile::ALFile() is the constructor for the ALFile class derived from the base class ALStorage constructor.  This constructor calls ALStorage to do most of the work.  The only thing it does is set the file handle to -1, the convention used internally to indicate that no file is open.

C, Visual Basic, and Delphi programmers cannot set the buffer size and name case for an ALFile object.  The default values are used for these languages.

Returns

There are no returns for C++ constructors.  C, Visual Basic, and Delphi return an hALStorage handle, which is passed as the this_object parameter to all ALFile functions.


ALFile() see also
See Also

ALMemory::ALMemory()


ALFile() example
See example programs EX04PM.CPP, EX08CON.CPP, EX04WIN.C, EX11CON.C, and EX05VB.FRM.


MakeTempName() - ALFile class
ALFile::MakeTempName()

see also	example

Make temporary file name

Synopsis

#include "arclib.h"

#include "filestor.h"

 virtual void MakeTempName( int i )

Arguments

i

A number that can be used to construct a temporary file name.  For example, in the ALFile class, the temporary name is created using sprintf ( buffer, "~a~%03d.tmp" ).   If the temporary name turns out to already be in use, MakeTempName() will be called repeatedly, with i being incremented after each successive call.

Function

ALFile::MakeTempName() is a virtual function called by ALFile::Create() when it is trying to make a temporary file name.  This function may be called repeatedly until a usable file name is found.  The parameter i is initially set to a value of 0, but will be incremented until a usable name is generated.  As defined in ALFile, this function creates a file name with the format ~al~xxx.tmp, where xxx is the integer parameter passed to the function.

If you have a particular need to have temporary files created in a particular place, or want a particular algorithm used, you should derive a new class and override this function.  To do this, use ALFile::MakeTempName() as a template.

Returns

None


MakeTempName() see also - ALFile class
See Also

ALStorage::Create()


MakeTempName() example - ALFile class
N/A


ALMemoryBaseGetBufferOwner()

see also	example

Indicate owner of memory buffer

Synopsis

#include "arclib.h"

#include "memstore.h"

 int ALMemoryBaseGetBufferOwner( hALStorage this_object )

 Declare Function ALMemoryBaseGetBufferOwner Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALMemoryBaseGetBufferOwner( this_object : hALStorage ) : Integer;

C, Visual Basic, and Delphi programmers can access the ALMemoryBase data member mfUserOwnsBuffer using this function.  C++ programmers don't need to call this function since they can access the data member directly.

Arguments

this_object

Handle to a memory based storage object

Function

ALMemoryBaseGetBufferOwner() simply returns the state of the flag.

A sample piece of code including ALMemoryBaseGetBufferOwner() is shown below.

int i = ALMemoryBaseGetBufferOwner( hStorageObject );

Returns

 ALMemoryBaseGetBufferOwner() returns one of the following values (no errors are returned):

Return Value	Meaning

1	user owns

0	archive owns


ALMemoryBaseGetBufferOwner() see also
See Also

ALMemoryBaseSetBufferOwner()


ALMemoryBaseGetBufferOwner() example
See example program EX14CON.C.


ALMemoryBaseGetBufferSize()

see also	example

Get size of storage buffer used by memory object

Synopsis

#include "arclib.h"

#include "memstore.h"

 long ALMemoryBaseGetBufferSize( hALStorage this_object )

 Declare Function ALMemoryBaseGetBufferSize Lib "AL20LW" ( ByVal this_object& ) As Long

 function ALMemoryBaseGetBufferSize( this_object : hALStorage ) : LongInt;

C, Visual Basic, and Delphi programmers can access the ALMemoryBase data member muUserBufferSize using this function.  Since C++ programmers can access the data member directly, they don't need to call this function.

Arguments

this_object

Handle to a memory based storage object

Function

ALMemoryBaseGetBufferSize() returns the current size of the allocated memory buffer.  The size of the allocated buffer has to fit into long int.

A sample piece of code including ALMemoryBaseGetBufferSize() is shown below.

ALCompress( engine, input, mem );

printf( "compressed size = %ld",

           ALMemoryBaseGetBufferSize( mem ) );

Returns

ALMemoryBaseGetBufferSize() returns the size of the buffer.  If no buffer exists, 0 will be returned.


ALMemoryBaseGetBufferSize() see also
See Also

ALMemoryBaseGetBufferOwner(), ALMemoryBaseSetBufferOwner()


ALMemoryBaseGetBufferSize() example
See example program EX14WIN.C and EX14DOS.C.


ALMemoryBaseSetBufferOwner()

see also	example

Set ownership of memory buffer

Synopsis

#include "arclib.h"

#include "memstore.h"

 void ALMemoryBaseSetBufferOwner( hALStorage this_object, int user_owns_buffer )

 Declare Sub ALMemoryBaseSetBufferOwner Lib "AL20LW" ( ByVal this_object&, ByVal user_owns_buffer% )

 procedure ALMemoryBaseSetBufferOwner( this_object : hALStorage; user_owns_buffer : Integer );

C, Visual Basic, and Delphi programmers can access the ALMemoryBase data member mfUserOwnsBuffer using this function.  C++ programmers don't need to call this function since they can access the data member directly.

Arguments

this_object

Handle to a memory based storage object

user_owns_buffer

Flag indicating ownership of buffer.  Passing 1 for this argument indicates that you want to assume ownership; passing 0 means that the archive object will assume ownership.

Functions

ALMemoryBaseSetBufferOwner() lets you take over ownership of a memory buffer.  Passing 1 as the user_owns_buffer argument indicates that the buffer now belongs to the program, not to ArchiveLib.  From that point on, ArchiveLib will not attempt to delete the buffer when the ALMemoryBase object is destroyed, nor will it attempt to grow the object if needed.

Returns

None


ALMemoryBaseSetBufferOwner() see also
See Also

ALMemoryBaseGetBufferOwner()


ALMemoryBaseSetBufferOwner() example
See example program EX14CON.CPP.


ALMemory()
ALMemory::ALMemory()

see also	example

Constructor for heap based ALMemory class

Synopsis

#include "arclib.h"

#include "memstore.h"

 ALMemory( const char *buffer_name = "", char *user_buffer = 0, size_t user_buffer_size = 0, ALCase name_case = AL_MIXED )

 hALStorage newALMemory( char *buffer_name, char *user_buffer, size_t user_buffer_size )

Arguments

buffer_name

An arbitrary name assigned to the buffer.  Buffer names don't have to be unique, because buffers aren't named at the operating system level.  But if you are going to insert the storage object into an archive, the name needs to be unique so that you will be able to extract it properly.  For C++, the default is "" (empty string).

There are no default parameter values for C.

user_buffer

If you want the ALMemory class to automatically allocate a buffer for you, and grow it as necessary, just leave this pointer set to 0.  If you want to use your own buffer, which won't have the ability to grow, pass a pointer to it in this parameter.

There are no default parameter values for C.

user_buffer_size

If you are passing a pointer to your own buffer, you need to indicate how large it is here.  Since we are dealing with standard buffers, this is of type size_t.  For C++, the default is 0 bytes.  For C programmers, a value of 0 indicates that the ALMemory object is expected to create and maintain the buffer.

There are no default parameter values for C.

name_case

This decides whether you want the file name to be case sensitive when making comparisons.  MS-DOS file names are case-insensitive.  You can make memory buffers either AL_MIXED, AL_UPPER, or AL_LOWER.  The default of mixed case means that comparisons will be case sensitive, which is fine.

 C programmers are not able to set the name_case.  This parameter does not exist for newALMemory.  This will be internally set to AL_MIXED.

Function

The ALMemory::ALMemory() constructor initializes a pointer to a memory buffer.  At this point, no memory is actually allocated, and will not be until the object is opened.  If a NULL pointer is supplied for the buffer, ArchiveLib will take care of memory allocation.

Normally, an ALMemory object works according to standard ArchiveLib rules:

•	You can construct an ALMemory object using your own predefined memory buffer, or

•	You can let the ALMemory object create it for you.

If the ALMemory object creates the memory buffer, it will destroy it automatically when the object is destroyed.  If you created the buffer, it will not be deleted in the ALMemory destructor.

However, there may be times when you want to let ALMemory create a buffer, and then take it over for your own use.  In a case such as this, you may not want the ALMemory destructor to delete the object.  To accomplish this, you just have to set the ALMemory class public data member mfUserOwnsBuffer to a non-zero value (> 0).  This tells the destructor that it is not responsible for deleting the buffer.

ALMemory() implements the storage class using malloc() and realloc().

Returns

If memory allocation is being done dynamically, this function returns a pointer/handle to a new ALMemory object.  If it is called as a static or automatic constructor (only possible in C++), it returns nothing.


ALMemory() see also
See Also

ALStorage::~ALStorage()


ALMemory() example
See example programs EX04PM.CPP, EX04WIN.CPP, EX08CON.CPP, EX10WIN.C, and EX14CON.C.


ALMemoryGetBuffer()

see also	example

Get access to memory buffer

Synopsis

#include "arclib.h"

#include "memstore.h"

 char *ALMemoryGetBuffer( hALStorage this_object )

C programmers can access the ALMemory data member mpcUserBuffer using this function.  Since C++ programmers can access the data member directly, they don't need to call this function.

Arguments

this_object

Handle to the ALStorage object

Function

ALMemoryGetBuffer() gets the buffer pointer and returns a simple pointer to a character array.  The array will have been allocated using calls to malloc() and realloc().

A sample piece of code including ALMemoryGetBuffer() is shown below.

char *p;

p = ALMemoryGetBuffer( object );

Returns

ALMemoryGetBuffer() returns a pointer to the memory buffer.  If no buffer exists, 0 is returned.


ALMemoryGetBuffer() see also
See Also

ALWinMemoryGetBuffer(), ALHugeMemoryGetBuffer()


ALMemoryGetBuffer() example
See example program EX14CON.C.


ALHugeMemory()
ALHugeMemory::ALHugeMemory()

see also	example

Constructs a new ALHugeMemory object

Synopsis

#include "arclib.h"

#include "memstore.h"

 ALHugeMemory::ALHugeMemory( const char *buffer_name = "", char _huge *user_buffer = 0 , long user_buffer_size = 0, ALCase name_case = AL_MIXED )

 hALStorage newALHugeMemory( char *buffer_name, char _huge *user_buffer, long user_buffer_size )

Arguments

buffer_name

An arbitrary name assigned to the buffer.  Buffer names don't have to be unique, because buffers aren't named at the operating system level.  But if you are going to insert the storage object into an archive, the name needs to be unique so that you will be able to extract it properly.

user_buffer

If you want the ALHugeMemory class to automatically allocate a buffer for you, and grow it as necessary, just leave this pointer set to 0.  If you want to use your own buffer, which won't have the ability to grow, pass a pointer to it in this parameter.

user_buffer_size

If you are passing a pointer to your own buffer, you need to indicate how large it is here.  Since we are dealing with huge buffers, this is of type long.

name_case

This decides whether you want the file name to be case sensitive when making comparisons.  MS-DOS file names are case-insensitive.  You can make memory buffers either AL_MIXED, AL_UPPER, or AL_LOWER.  The default of mixed case means that comparisons will be case sensitive, which is fine.

Function

This constructor calls the base class constructor in an initializer list.  After that is done, the constructor only has to initialize a few data members.

Returns

If memory allocation is being done dynamically, this function returns a pointer/handle to a new ALHugeMemory object.  If it is called as a static or automatic constructor, it returns nothing.


ALHugeMemory() see also
See Also

ALMemory::ALMemory(), ALWinMemory::ALWinMemory()


ALHugeMemory() example
See example programs EX04WIN.CPP and EX04WIN.C.


ALHugeMemoryGetBuffer()

see also	example

Retrieve the user buffer for an ALHugeMemory object

Synopsis

#include "arclib.h"

#include "memstore.h"

 char _huge * ALHugeMemoryGetBuffer( hALStorage this_object )

Arguments

this_object

A handle for (pointer to) an ALHugeMemory object.

Function

This C translation function provides access to the C++ data member ALHugeMemory::mpcUserBuffer.  Under C++, this is a public data  member that the programmer is free to access or modify.

This function first tests its only argument for correct type (when in debug mode), then casts and accesses the data member.  The value of the data member is then returned unchanged to the calling C procedure.

This function should only be used in conjunction with standard memory objects created with new ALHugeMemory() or newALHugeMemory().  If your memory object was created using ALMemory() or ALWinMemory(), this function will not work.

Returns

A pointer to the memory buffer being used as a storage object.


ALHugeMemoryGetBuffer() see also
See Also

ALMemoryGetBuffer(), ALWinMemoryGetBuffer()


ALHugeMemoryGetBuffer() example
See example program EX19CON.C.


ALWinMemory()
ALWinMemory::ALWinMemory()

see also	example

Constructs a new ALWinMemory object

Synopsis

#include "arclib.h"

#include "memstore.h"

 ALWinMemory::ALWinMemory( const char *buffer_name = "", char _huge *user_buffer = 0 , long user_buffer_size = 0, ALCase name_case = AL_MIXED )

 hALStorage newALWinMemory( char *buffer_name, char _huge *user_buffer, long user_buffer_size )

 Declare Function newALWinMemory Lib "AL20LW" ( ByVal buffer_name$, ByVal user_buffer$, ByVal user_buffer_size& ) As Long

 function newALWinMemory( buffer_name : String; user_buffer : Pchar; user_buffer_size : LongInt ) : hALStorage;

Arguments

buffer_name

An arbitrary name assigned to the buffer.  Buffer names don't have to be unique, because buffers aren't named at the operating system level.  But if you are going to insert the storage object into an archive, the name needs to be unique so that you will be able to extract it properly.

user_buffer

If you want the ALWinMemory class to automatically allocate a buffer for you, and grow it as necessary, just leave this pointer set to 0.  If you want to use your own buffer, which won't have the ability to grow, pass a pointer to it in this parameter.

user_buffer_size

 If you are passing a pointer to your own buffer, you need to indicate how large it is here.  Since we are dealing with huge buffers, this is of type long instead of the typical size_t.

name_case

This decides whether you want the file name to be case sensitive when making comparisons.  MS-DOS file names are case-insensitive.  You can make memory buffers either AL_MIXED, AL_UPPER, or AL_LOWER.  The default of mixed case means that comparisons will be case sensitive, which is fine.

Function

This constructor calls the base class constructor in an initializer list.  After that is done, the constructor only has to initialize a few data members.

Returns

If memory allocation is being done dynamically, this function returns a pointer/handle to a new ALWinMemory object.  If it is called as a static or automatic constructor, it returns nothing.


ALWinMemory() see also
See Also

ALHugeMemory::ALHugeMemory()


ALWinMemory() example
See example programs EX04WIN.CPP, EX04WIN.C, EX04VB.FRM, and EX04UNIT.PAS.


ALWinMemoryGetBuffer()

see also	example

Retrieve the user buffer being used in an ALWinMemory object

Synopsis

#include "arclib.h"

#include "memstore.h"

 char * ALWinMemoryGetBuffer( hALStorage this_object );

 Declare Function ALWinMemoryGetBuffer Lib "AL20LW" ( ByVal this_object& ) As String

 function ALWinMemoryGetBuffer( this_object : hALStorage ) : String;

Arguments

this_object

A handle for (pointer to) an ALWinMemory object.

Function

This C translation function provides access to the C++ data member ALWinMemory::mpcUserBuffer.  Under C++, this is a public data  member that the programmer is free to access or modify.

This function first tests its only argument for correct type (when in debug mode), then casts and accesses the data member.  The value of the data member is then returned unchanged to the calling procedure.

A sample piece of code including ALWinMemoryGetBuffer() is shown below.

ALCompress( engine, file, mem );

p=ALWinMemoryGetBuffer( mem );

ALMemoryBaseSetBufferOwner( mem, 1 );

Returns

ALWinMemoryGetBuffer() returns a pointer to the memory buffer being used as a storage object.


ALWinMemoryGetBuffer() see also
See Also

ALMemoryGetBuffer()


ALWinMemoryGetBuffer() example
See example program EX22VB.FRM.


ALWinMemoryGetHandle()

see also	example

Get the handle for an ALWinMemory object's buffer

Synopsis

#include "arclib.h"

#include "memstore.h"

 UINT ALWinMemoryGetHandle( hALStorage this_object )

 Declare Function ALWinMemoryGetHandle Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALWinMemoryGetHandle( this_object : hALStorage ) : Integer;

Arguments

this_object

A reference or pointer to an ALWinMemory object

Function

ALWinMemoryGetHandle() provides access to the C++ data member ALWinMemory::mhUserMemoryHandle.  This function first tests its only argument for correct type (when in debug mode), then casts and accesses the data member.  The value of the data member is then returned unchanged to the calling procedure.

A sample piece of code including ALWinMemoryGetHandle() is shown below.

ALCompress( engine, file, mem );

handle=ALWinMemoryGetHandle( mem );

ALMemoryBaseSetBufferOwner( mem, 1 );

Returns

ALWinMemoryGetHandle() returns the value of the data member.


ALWinMemoryGetHandle() see also
See Also

ALWinMemoryGetBuffer()


ALWinMemoryGetHandle() example
See example program EX22VB.FRM.


ClearError() - ALCompressor class
ALCompressor::ClearError()

see also	example

Reset the error status for a compression engine

Synopsis

#include "arclib.h"

 void ALCompressor::ClearError()

 void ALCompressorClearError( hALCompressor this_object )

 Declare Sub ALCompressorClearError Lib "AL20LW" ( ByVal this_object& )

 procedure ALCompressorClearError( this_object : hALCompressor );

Arguments

this_object

A reference or pointer to the ALCompressor object that is going to have its status reset.  The C++ version of this call doesn't have an explicit argument here, since it has access to 'this' implicitly.

Function

An ALEngine object carries around a status object in its mStatus member.  Error conditions are not cleared automatically by the library, so you will have to clear it manually with a call to this function after detecting an error.

A sample piece of code including ClearError() is shown below.

ALCompressor *c = new ALGlCompressor;

c->Compress( input, output );

if( c->mStatus < 0 )

  c->ClearError();

Returns

None.


ClearError() see also - ALCompressor class
See Also

ALDecompressor::ClearError()


ClearError() example - ALCompressor class
See example progam EX01MFC.C.


Compress() - ALCompressor class
ALCompressor::Compress()

see also	example

Compress input storage object to output storage object

Since this is a pure virtual function in the base class, you cannot call this function directly.  This function should always be called from a derived class of ALCompressor.

Synopsis

#include "arclib.h"

 int Compress( ALStorage &input_object, ALStorage &output_object )

 int ALCompress( hALCompress this_object, hALStorage input_object, hALStorage output_object )

 Declare Function ALCompress Lib "AL20LW" ( ByVal this_object&, ByVal input_object&, ByVal output_object& ) As Integer

 function ALCompress( this_object : hALCompressor; input : hALStorage; output : hALStorage ) : Integer;

Arguments

this_object

Handle to the ALCompressor object

input_object

Input storage object to be compressed

output_object

Output storage object to receive compressed data

Function

ALCompressor::Compress() is the virtual function that performs compression under ArchiveLib.  Compress() compresses an input storage object and then writes it to the output storage object.  This function takes input and output objects in either the open or closed storage state, and returns them to the same state at completion.  If an object was open when the function was called, read/write positions start at the current file position.

ALCompressor::Compress() can take a long time to run.  Under MS Windows, it is considered impolite to monopolize the CPU for long periods of time.  A PeekMessage() loop must then be executed so that other tasks can process their messages.  In ArchiveLib, the compression functions don't have to worry about this; the ALStorage::YieldTime() function runs PeekMessage() each time a buffer is flushed or loaded.

To check for abort conditions or to update the status indicators for compression activities, you can derive a new class of ALStorage and create a new virtual version of YieldTime().  Your virtual function can, at the same time, do other periodic tasks while "inside" the compression routine.

A sample code piece including ALCompressor::Compress() is shown below.

  int foo( ALCompressor *engine )

  {

      ALFile file( "input.dat" );

      ALMemory output( "output" );

      engine->Compress( file, output );

Returns

ALCompressor::Compress() returns AL_SUCCESS if the function was successful.  An error code is returned if the function was not successful.


Compress() see also - ALCompressor class
See Also

ALDecompressor::Decompress()


Compress() example - ALCompressor class
See example programs EX14PM.CPP, EX14WIN.CPP, EX23CON.CPP, EX14WIN.C, EX14VB.FRM, and EX14UNIT.PAS.


ALCompressorGetStatusCode()

see also	example

Get status of ALCompressor object

Synopsis

#include "arclib.h"

 int ALCompressorGetStatusCode( hALCompressor this_object )

 Declare Function ALCompressorGetStatusCode Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALCompressorGetStatusCode( this_object : hALCompressor ) : Integer;

C, Visual Basic, and Delphi programmers can access the ALCompressor data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALCompressor object

Function

This is the C, Visual Basic, and Delphi wrapper function for the C++ function ALName::GetStatusCode() as implemented for objects of type ALCompressor.

A sample code piece including ALCompressorGetStatusCode() is shown below:

    if ( ALCompressorGetStatusCode( engine ) < AL_SUCCESS )

        printf( "Error, prepare to reboot..." );

Returns

ALCompressorGetStatusCode() returns the current integer status of the ALCompressor object.


ALCompressorGetStatusCode() see also
See Also

ALCompressorGetStatusDetail(), mStatus data member in ALEngine


ALCompressorGetStatusCode() example
See example programs EX14WIN.C and EX14VB.FRM.


ALCompressorGetStatusDetail()

see also	example

Get detailed error information

Synopsis

#include "arclib.h"

 char *ALCompressorGetStatusDetail( hALCompressor this_object )

 Declare Function ALCompressorGetStatusDetail Lib a	"AL20LW" ( ByVal this_object& ) As String

 function ALCompressorGetStatusDetail( this_object : hALCompressor ) : String;

C, Visual Basic, and Delphi programmers can access the ALCompressor data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALCompressor object

Function

This is the C wrapper function for the C++ function ALName::GetStatusDetail(), as implemented for class ALCompressor.

Returns

ALCompressorGetStatusDetail() always returns a pointer to a detailed status string.


ALCompressorGetStatusDetail() see also
See Also

mStatus data member in ALEngine


ALCompressorGetStatusDetail() example
See example programs EX14WIN.C, EX14VB.FRM, and EX14UNIT.PAS.


ALCompressorGetStatusString()

see also	example

Translate error code into string

Synopsis

#include "arclib.h"

 char *ALCompressorGetStatusString( hALCompressor this_object )

 Declare Function ALCompressorGetStatusString Lib "AL20LW" ( ByVal this_object& ) As String

 function ALCompressorGetStatusString( this_object : hALCompressor ) : String;

C, Visual Basic, and Delphi programmers can access the ALCompressor data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALCompressor object

Function

This is the C wrapper function for the C++ function ALName::GetStatusString(), as implemented for class ALCompressor.

A few sample error code translations include the following:

     AL_SUCCESS	"Success"

     AL_END_OF_FILE	"End of file"

     AL_CANT_OPEN_BUFFER	"Can't allocate buffer"

Returns

ALCompressorGetStatusString() always returns a pointer to a short string translation of the current error code.


ALCompressorGetStatusString() see also
See Also

ALCompressorGetStatusDetail(), mStatus data member in  ALCompressor


ALCompressorGetStatusString() example
See example programs EX00WIN.C, EX16CON.C, EX00VB.FRM, and EX00UNIT.PAS.


ALCompressorGetTypeCode()

see also	example

Return integer value of compression engine in use

Synopsis

#include "arclib.h"

 int ALCompressorGetTypeCode( hALCompressor this_object )

 Declare Function ALCompressorGetTypeCode Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALCompressorGetTypeCode( this_object : hALCompressor ) : Integer;

C, Visual Basic, and Delphi programmers can access the ALCompresor data member miCompressionType using this function.  C++ programmers don't need to call this function since they can access the data member directly.

Arguments

this_object

Handle to the ALCompressor object

Function

This function is the C, Visual Basic, and Delphi translation function that provides access to the C++ data member ALCompressor::miCompressionType.  Since C, Visual Basic, and Delphi  cannot access the class object directly, they must go through this function as an intermediary.

A sample code piece including ALCompressorGetTypeCode() is shown below.

    if ( ALCompressorGetTypeCode( engine ) ==

AL_COMPRESSION_COPY )

       copy_data();

Returns

ALCompressorGetTypeCode() returns one of the following values:

Return	Value

AL_COMPRESSION_DEFAULT	-1

AL_COMPRESSION_COPY	0

AL_COMPRESSION_GREENLEAF	1

AL_COMPRESSION_DEFLATE_COPY	100

AL_COMPRESSION_DEFLATE	108


ALCompressorGetTypeCode() see also
See Also

miCompressionType data member in  ALCompressor


ALCompressorGetTypeCode() example
See example programs EX14WIN.C, EX16CON.C, EX14VB.FRM, and EX14UNIT.PAS.


ALCompressorGetTypeString()

see also	example

Return compression engine type

Synopsis

#include "arclib.h"

 char *ALCompressorGetTypeString( hALCompressor this_object )

 Declare Function ALCompressorGetTypeString Lib "AL20LW" (ByVal this_object& ) As String

 function ALCompressorGetTypeString( this_object : hALCompressor ) : String;

C, Visual Basic, and Delphi programmers can access the ALCompressor data member mszCompressionType using this function.  C++ programmers don't need to call this function since they can access the data member directly.

Arguments

this_object

Handle to the ALCompressor object

Function

This function is the C, Visual Basic, Delphi  translation function that provides access to the C++ data member ALCompressor::mszCompressionType.  Since C, Visual Basic, and Delphi  cannot access the class object directly, they must go through this function as an intermediary.

A sample piece of code including ALCompressorGetTypeString() is shown below.

printf( "Compression engine:%s",

           ALCompressorGetTypeString( hCompressor ) );

Returns

ALCompressorGetTypeString() returns the compression engine description string, which is usually defined as part of the compression class code.


ALCompressorGetTypeString() see also
See Also

ALCompressorGetTypeCode(), miCompressionType data member in ALCompressor


ALCompressorGetTypeString() example
See example programs EX14WIN.C, EX14VB.FRM, and EX14UNIT.PAS.


ALCompressorSetError()

see also	example

Manipulate error code for ALCompressor

Synopsis

#include "arclib.h"

 int ALCompressorSetError( hALCompressor this_object, int error_code, char *text )

 Declare Function ALCompressorSetError Lib "AL20LW"( ByVal this_object&, ByVal error_code%, ByVal text$ ) As Integer

 function ALCompressorSetError( this_object : hALCompressor; error_code : Integer; text : String ) : Integer;

C, Visual Basic, and Delphi programmers can access the ALCompressor data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALCompressor object

error_code

Numeric (integer) error code

text

Pointer to the formatted error message that will be stored in the object's mStatus data member

Function

This is the C, Visual Basic, and Delphi wrapper function for the C++ member function ALName::SetError(), as applied to an ALCompressor object.

A sample piece of code including ALCompressorSetError() is shown below.

case IDC_ABORT:

 ALCompressorSetError( engine,

  AL_USER_ABORT,

 	  "Abort key pressed" );

Returns

ALCompressorSetError() returns the integer value for the error code that was just set.


ALCompressorSetError() see also
See Also

ALStatus::GetStatusCode(), ALStatus::GetStatusString(), mStatus data member of ALCompressor


ALCompressorSetError() example
See example programs EX14WIN.C, EX14VB.FRM, and EX14UNIT.PAS.


ClearError() - ALDecompressor class
ALDecompressor::ClearError()

see also	example

Reset the error status for a decompression engine

Synopsis

#include "arclib.h"

 void ALDecompressor::ClearError()

 void ALDecompressorClearError( hALDecompressor this_object )

 Declare Sub ALDecompressorClearError Lib "AL20LW" ( ByVal this_object& )

 procedure ALDecompressorClearError( this_object : hALDecompressor );

Arguments

this_object

A reference or pointer to the ALDecompressor object that is going to have its status reset.  The C++ version of this call doesn't have an explicit argument here, since it has access to 'this' implicitly.

Function

An ALEngine object carries around a status object in its mStatus member.  Error conditions are not cleared automatically by the library, so you will have to clear it manually with a call to this function after detecting an error.

A sample piece of code including ClearError() is shown below.

engine->Decompress( in, out );

if ( engine->mStatus < 0 ){

  cout << "Error" << engine->mStatus;

  engine->ClearError();

Returns

None.


ClearError() see also - ALDecompressor class
See Also

ALCompressor::ClearError()


ClearError() example - ALDecompressor class
See example progam EX01MFC.CPP


Decompress() - ALDecompressor class
ALDecompressor::Decompress()

see also	example

Decompress input storage object to output storage object

Since this is a pure virtual function in the base class, you cannot call this function directly.  This function should always be called from a derived class of ALEngine.

Synopsis

#include "arclib.h"

 int Decompress( ALStorage &input_object, ALStorage &output_object, long compressed_length = -1 )

 int ALDecompress( hALDecompressor this_object, hALStorage input_object, hALStorage output_object, long compressed_length )

 Declare Function ALDecompress Lib "AL20LW" ( ByVal this_object&, ByVal input_object&, ByVal output_object&, ByVal compressed_length& ) As Integer

 function ALDecompress( this_object : hALDecompressor; input : hALStorage; output : hALStorage; compressed_length : LongInt ) : Integer;

Arguments

this_object

Handle to the ALDecompressor object

input_object

Input storage object to be decompressed

output_object

Output storage object to receive decompressed data

compressed_length

Number of bytes in a compressed object.  This lets the engine know how many bytes to read before it runs out of input.  For C++, the default is -1 (compressed size is unknown) and is assigned if a value is not supplied.

There are no default parameter values for C, Visual Basic, and Delphi.

Function

ALDecompressor::Decompress() operates much the same way as ALCompressor::Compress(), described above.  Like Compress(), the Decompress() function decompresses an input storage object and then writes it to the output storage object.  This function takes input and output objects in either the open or closed storage state, and returns them to this state at completion.

Also like ALCompressor::Compress(), this function can take a long time to run.  Under Windows, it is considered impolite to monopolize the CPU for long periods of time.  A PeekMessage() loop must then be executed so that other tasks can process their messages.  In ArchiveLib, the compression functions don't have to worry about this; the ALStorage::YieldTime() function runs PeekMessage() each time a buffer is flushed or loaded.

To check for abort conditions or to update the status indicators for compression activities, you can derive a new class of ALStorage and create a new virtual version of YieldTime().  Your virtual function can, at the same time, do other periodic tasks while "inside" the compression routine.

A sample code piece including Decompress() is shown below.

    ALGlDecompressor decompressor;

    decompressor.Decompress( decompressed, output );

Returns

ALDecompressor::Decompress() returns AL_SUCCESS (or 0) if the function was successful.  An error code is returned if the function was not successful.


Decompress() see also - ALDecompressor class
See Also

ALCompressor::Compress()


Decompress() example - ALDecompressor class
See example programs EX14PM.CPP, EX14WIN.CPP, EX23CON.CPP, EX14WIN.C, EX14VB.FRM, and EX14UNIT.PAS.


ALDecompressorGetStatusCode()

see also	example

Get the status code for a decompression engine

Synopsis

#include "arclib.h"

 int ALDecompressorGetStatusCode( hALDecompressor this_object )

 Declare Function ALDecompressorGetStatusCode Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALDecompressorGetStatusCode( this_object : hALDecompressor ) : Integer;

Arguments

this_object

A reference or pointer to the ALDecompressor object that we want the status code for

Function

This is the C, Visual Basic, and Delphi wrapper function for the C++ function ALName::GetStatusCode() as implemented for objects of type ALDecompressor.

A sample piece of code including ALDecompressorGetStatusCode() is shown below.

if( ALDecompressorGetStatusCode( engine ) < 0 )

  printf( "Error!" );

Returns

An integer that contains the current status code for the object.  Note that values of < 0 always indicate an error condition.


ALDecompressorGetStatusCode() see also
See Also

ALCompressorGetStatusCode()


ALDecompressorGetStatusCode() example
See example programs EX00CON.C, EX04WIN.C, EX15VB.FRM, and EX15UNIT.PAS.


ALDecompressorGetStatusDetail()

see also	example

Get the detailed status string for an ALDecompressor

Synopsis

#include "arclib.h"

 char *ALDecompressorGetStatusDetail( hALDecompressor this_object )

 Declare Function ALDecompressorGetStatusDetail Lib "AL20LW" (ByVal this_object&) As String

 function ALDecompressorGetStatusDetail( this_object : hALDecompressor ) : String;

Arguments

this_object

A handle for (pointer to) an ALDecompressor object

Function

This is the wrapper function for the C++ function ALName::GetStatusDetail(), as implemented for class ALDecompressor.

A sample piece of code including ALDecompressorGetStatusDetail() is shown below.

printf( "Decompressor error: %s",

           ALDecompressorGetStatusDetail( engine ) );

Returns

Always returns a pointer to a detailed status string.


ALDecompressorGetStatusDetail() see also
See Also

ALCompressorGetStatusDetail()


ALDecompressorGetStatusDetail() example
See example programs EX00CON.C, EX15WIN.C,  EX15VB.FRM, and  EX01UNIT.PAS.


ALDecompressorGetStatusString()

see also	example

Get the short status string for an ALDecompressor

Synopsis

#include "arclib.h"

 char *ALDecompressorGetStatusString( hALDecompressor this_object )

 Declare Function ALDecompressorGetStatusString Lib "AL20LW" (ByVal this_object&) As String

 function ALDecompressorGetStatusString( this_object : hALDecompressor ) : String;

Arguments

this_object

A handle for (pointer to) an ALDecompressor object

Function

This is the wrapper function for the C++ function ALName::GetStatusString(), as implemented for class ALDecompressor.

A sample piece of code including ALDecompressorGetStatusString() is shown below.

if ( error < 0 )

     SetDlgItemText( hwnd, ID_STATUS,

      ALDecompressorGetStatusString( dc ) );

Returns

Always returns a pointer to a short string translation of the current error code.


ALDecompressorGetStatusString() see also
See Also

ALCompressorGetStatusString()


ALDecompressorGetStatusString() example
See example programs EX00WIN.C, EX16CON.C, EX00VB.FRM, and EX00UNIT.PAS.


ALDecompressorGetTypeCode()

see also	example

Get the type code of an ALDecompressor engine

Synopsis

#include "arclib.h"

 int ALDecompressorGetTypeCode( hALDecompressor this_object )

 Declare Function ALDecompressorGetTypeCode Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALDecompressorGetTypeCode( this_object : hALDecompressor ) : Integer;

Arguments

this_object

A handle for (pointer to) an object of type ALDecompressor

Function

This function is the C, Visual Basic, and Delphi translation function that provides access to the C++ data member ALDecompressor::miCompressionType.  Since C, Visual Basic, and Delphi cannot access the class object directly, they must go through this function as an intermediary.

A sample piece of code including ALDecompressorGetTypeCode() is shown below.

ALDecompressorGetTypeCode( hEngine );

Returns

ALDecompressorGetTypeCode() returns one of the following values:

Return	Value

AL_COMPRESSION_DEFAULT	-1

AL_COMPRESSION_COPY	0

AL_COMPRESSION_GREENLEAF	1

AL_COMPRESSION_DEFLATE_COPY	100

AL_COMPRESSION_DEFLATE	108


ALDecompressorGetTypeCode() see also
See Also

ALCompressorGetTypeCode()


ALDecompressorGetTypeCode() example
See example programs EX14WIN.C, EX16CON.C, EX14VB.FRM, and EX14UNIT.PAS.


ALDecompressorGetTypeString()

see also	example

Get the type description string for an ALDecompressor engine

Synopsis

#include "arclib.h"

 char *ALDecompressorGetTypeString( hALDecompressor this_object )

 Declare Function ALDecompressorGetTypeString Lib "AL20LW" ( ByVal this_object& ) As String

 function ALDecompressorGetTypeString( this_object : hALDecompressor ) : String;

Arguments

this_object

A handle for (pointer to) an object of type ALDecompressor

Function

This function is the C, Visual Basic, and Delphi translation function that provides access to the C++ data member ALDecompressor::mszCompressionType.  Since C, Visual Basic, and Delphi cannot access the class object directly, they must go through this function as an intermediary.

A sample piece of code including ALDecompressorGetTypeString() is shown below.

printf( "Engine is of type: %s",

           ALDecompressorGetTypeString( d ) );

Returns

ALDecompressorGetTypeString() returns the decompressor engine description string, which is usually defined as part of the compression class code.


ALDecompressorGetTypeString() see also
See Also

ALCompressorGetTypeString()


ALDecompressorGetTypeString() example
See example programs EX14WIN.C, EX14VB.FRM, and EX14UNIT.PAS.


ALDecompressorSetError()

see also	example

Set the error code and text for a Decompressor engine

Synopsis

#include "arclib.h"

 int ALDecompressorSetError( hALDecompressor this_object, int error_code, char *text )

 Declare Function ALDecompressorSetError Lib "AL20LW" ( ByVal this_object&, ByVal error_code%, ByVal text$ ) As Integer

 function ALDecompressorSetError( this_object : hALDecompressor; error_code : Integer; text : String ) : Integer;

Arguments

this_object

A handle for (pointer to) an ALDecompressor object

error_code

The error code to apply to the object

text

The text of the error message you want to associate with this error

Function

This is the C, Visual Basic, and Delphi wrapper function for the C++ member function ALName::SetError(), as applied to an ALDecompressor object.

A sample piece of code including ALDecompressorSetError() is shown below.

case IDC_ABORT:

     ALDecompressorSetError( engine, AL_USER_ABORT,

     "Abort key pressed" );

Returns

ALDecompressorSetError() returns the integer value for the error code that was just set.


ALDecompressorSetError() see also
See Also

ALStatus::SetError()


ALDecompressorSetError() example
See example programs EX15WIN.C and EX15VB.FRM.


ALCopyCompressor()
ALCopyCompressor::ALCopyCompressor()

see also	example

Constructor for copy compression engine

Synopsis

#include "arclib.h"

#include "copyengn.h"

 ALCopyCompressor::ALCopyCompressor()

 hALCompressor newALCopyCompressor()

 Declare Function newALCopyCompressor Lib "AL20LW" () As Long

 function newALCopyCompressor : hALCompressor;

Arguments

None

Function

This function creates a new copy compression engine.  The copy engine is used to do simple binary copies of an uncompressed object into an archive or other compressed object.  Since no compression is taking place, the copy compressor is fast and efficient.

Under Delphi, Visual Basic, or C, it is up to the user to destroy this engine by calling deleteALCompressor().  C++ users only need to call the destructor explicitly when they have created the object dynamically using the new operator.

Returns

For C, Visual Basic, and Delphi, a pointer to an ALCompressor object is returned.


ALCopyCompressor() see also
See Also

ALCopyDeompressor::ALCopyDecompressor()


ALCopyCompressor() example
See example programs EX08CON.CPP, EX14PM.CPP, EX14WIN.CPP, EX14WIN.C, EX14VB.FRM, and EX14UNIT.PAS.


ALCopyDecompressor()
ALCopyDecompressor::ALCopyDecompressor()

see also	example

Constructor for copy decompression engine

Synopsis

#include "arclib.h"

#include "copyengn.h"

 ALCopyDecompressor::ALCopyDecompressor()

 hALDecompressor newALCopyDecompressor()

 Declare Function newALCopyDecompressor Lib "AL20LW" () As Long

 function newALCopyDecompressor : hALDecompressor;

Arguments

None

Function

This function creates a new copy decompression engine.  The copy engine is used to do simple binary copies of a compressed object from an archive or other compressed object.  Since no decompression is actually taking place, the copy decompressor is fast and efficient.

Under Delphi, Visual Basic, or C, it is up to the user to destroy this engine by calling deleteALDecompressor().  C++ users only need to call the destructor explicitly when they have created the object dynamically using the new operator.

Returns

For C, Visual Basic, and Delphi, a handle to an ALDecompressor object is returned.


ALCopyDecompressor() see also
See Also

ALCopyCompressor::ALCopyCompressor()


ALCopyDecompressor() example
See example programs EX14PM.CPP, EX14WIN.CPP, EX14WIN.C, EX14VB.FRM, and EX14UNIT.PAS.


ALGlCompressor()
ALGlCompressor::ALGlCompressor()

see also	example

Constructor for Greenleaf compressor engine

Synopsis

#include "arclib.h"

#include "glengn.h"

 ALGlCompressor::ALGlCompressor( short int compression_level = AL_GREENLEAF_LEVEL_2, short int fail_uncompressible = 0 )

 hALCompressor newALGlCompressor( short int compression_level, short int fail_uncompressible )

 Declare Function newALGlCompressor Lib "AL20LW" ( ByVal compression_level%, ByVal fail_uncompressible% ) As Long

 function newALGlCompressor( compression_level : Integer; fail_uncompressible : Integer ) : hALCompressor;

Arguments

compression_level

This is one of the enumerated types found in ALDEFS.H, namely AL_GREENLEAF_LEVEL_0 through AL_GREENLEAF_LEVEL_4.  Level 4 gives the most compression, but takes up the most memory as well.  You can also use AL_GREENLEAF_COPY, which does no compression.

16-bit programs default to level 2, 32-bit programs default to level 4.

fail_uncompressible

This flag is used to indicate the disposition of an incompressible file.  If this flag is set, the compression of an incompressible file will be interrupted, and the file will be recompressed using a binary straight copy.

Function

The Greenleaf Compressor has a very simple constructor.  It simply initializes a couple of data members, then passes some additional data up to the base class constructor.

Under Delphi, Visual Basic, or C, it is up to the user to destroy this engine by calling deleteALCompressor().

A sample code piece including the ALGlCompressor() constructor is shown below.

    ALGlCompressor engine( COMPRESSION_LEVEL_4 );

    engine.Compress( input, output );

Returns

For C, Visual Basic, and Delphi, a pointer to an ALCompressor object is returned.


ALGlCompressor() see also
See Also

ALCopyCompressor::ALCopyCompressor()


ALGlCompressor() example
See example programs EX09CON.CPP, EX14PM.CPP, EX14WIN.CPP, EX14WIN.C, EX16CON.C, EX14VB.FRM, and EX14UNIT.PAS.


CompressionLevel() - ALGlCompressor class
ALGlCompressor::CompressionLevel()

see also	example

Return the compression level for a Greenleaf engine

Synopsis

#include "arclib.h"

#include "glengn.h"

 short int ALGlCompressor::CompressionLevel()

 short int ALGlCompressorLevel( hALCompressor this_object )

 Declare Function ALGlCompressorLevel "AL20LW" ( ByVal this_object& ) As Integer

 function ALGlCompressorLevel( this_object : hALCompressor ) : Integer;

Arguments

this_object

A reference or pointer to the ALGlCompressor object whose compression level will be returned.  In C++, this call does not have an explicit argument referencing this_object, since it has access to 'this' implicitly.

Function

The Greenleaf compressor has a compression level member that dictates how much memory the compressor will devote to its job. The more memory devoted, the better compression you get.

This function will normally be implemented as an inline function.

Returns

ALGlCompressor::CompressionLevel() returns a short integer that contains the current compression level for the Greenleaf Engine.  If a compression pass fails because a file is incompressible, this function will return AL_GREENLEAF_COPY.  Otherwise, the number returned here will normally be between AL_GREENLEAF_LEVEL_0 and AL_GREENLEAF_LEVEL_4.


CompressionLevel() see also - ALGlCompressor class
See Also

ALGlCompressor::ALGlCompressor()


CompressionLevel() example - ALGlCompressor class
See example program EX06UNIT.PAS.


ALGlDecompressor()
ALGlDecompressor::ALGlDecompressor()

see also	example

Constructor for the Greenleaf decompressor engine

Synopsis

#include "arclib.h"

#include "glengn.h"

 ALGlDecompressor::ALGlDecompressor( short int compression_level = AL_GREENLEAF_LEVEL_2 )

 hALDecompressor newALGlDecompressor( short int compression_level )

 Declare Function newALGlDecompressor Lib "AL20LW" (ByVal compression_level% ) As Long

 function newALGlDecompressor( compression_level : Integer ) : hALDecompressor;

Arguments

compression_level

This is one of the enumerated types found in ALDEFS.H, namely AL_GREENLEAF_LEVEL_0 through AL_GREENLEAF_LEVEL_4.  Level 4 gives the most compression, but takes up the most memory as well.

16-bit programs default to level 2, 32-bit programs default to level 4.

Function

The Greenleaf decompressor has a very simple constructor.  All it has to do is initialize a data member, then pass some additional data up to the base class constructor.

Under Delphi, Visual Basic, or C, it is up to the user to destroy this engine by calling deleteALDecompressor().

Returns

For C, Visual Basic, and Delphi, a pointer to an ALDecompressor object is returned.


ALGlDecompressor() see also
See Also

ALGlCompressor::ALGlCompressor()


ALGlDecompressor() example
See example programs EX09CON.CPP, EX14PM.CPP, EX14WIN.CPP, EX14WIN.C, EX18CON.C, EX14VB.FRM, and EX14UNIT.PAS.


CompressionLevel() - ALGlDecompressor class
ALGlDecompressor::CompressionLevel()

see also	example

Read the compression level for a Greenleaf engine

Synopsis

#include "arclib.h"

#include "glengn.h"

 short int ALGlDecompressor::CompressionLevel()

 short int ALGlDecompressorLevel( hALDecompressor this_object )

 Declare Function ALGlDecompressorLevel "AL20LW" ( ByVal this_object& ) As Integer

 function ALGlDecompressorLevel( this_object : hALDecompressor ) : Integer;

Arguments

this_object

A reference or pointer to the ALGlDecompressor object whose compression level will be returned.  In C++, this call does not have an explicit argument referencing this_object, since it has access to 'this' implicitly.

Function

The Greenleaf compressor has a compression level member that dictates how much memory the compressor will devote to its job. The more memory devoted, the better compression you get.

When you create a decompressor, you need to match up the compression level in the decompressor with the same level that the compressor used to create the data.  In ArchiveLib, this is done automatically for all Archiving functions, as well as the compressed object.

If you are performing raw compression on blocks of data, you will need to ensure manually that the two levels are the same when creating the engine.

This function will normally be implemented as an inline function.

Returns

ALGlDecompressor::CompressionLevel() returns a short integer that contains the current compression level for the Greenleaf Engine.  If a compression pass fails because a file is incompressible, this function will return AL_GREENLEAF_COPY.  Otherwise, the number returned here will normally be between AL_GREENLEAF_LEVEL_0 and AL_GREENLEAF_LEVEL_4.


CompressionLevel() see also - ALGlDecompressor class
See Also

ALGlCompressor::CompressionLevel()


CompressionLevel() example - ALGlDecompressor class
See example program EX06UNIT.PAS


ALPkCompressor()
ALPkCompressor::ALPkCompressor()

see also	example

Constructor for the PkWare deflate compressor engine

Synopsis

#include "arclib.h"

#include "pkengn.h"

 ALPkCompressor::ALPkCompressor( int level = 6, int window_bits = 13, int mem_level = 6 )

 hALCompressor newALPkCompressor( int level, int window_bits, int mem_level )

 Declare Function newALPkCompressor Lib "AL20LW" ( ByVal level%, ByVal window_bits%, ByVal mem_level% ) As Long

 function newALPkCompressor( level : Integer; window_bits : Integer; mem_level : Integer ) : hALCompressor;

Arguments

level

A number between 1 and 9.  1 gives the best speed, 9 gives the best compression.  The default is 6 for all programs.

window_bits

The base 2 logarithm of the number of bytes in the history buffer.  Values between 8 and 15 are legal.  The more bits,the more memory.  For 16-bit programs, the default is 13.  For 32-bit programs, the default is 15.

mem_level

How much memory should be allocated for the internal compression state.  mem_level=1 uses minimum memory but is slow and reduces compression ratio; mem_level=9 uses maximum memory for optimal speed.  For 16-bit programs, the default is 6.  For 32-bit programs, the default is 8.

The C, Visual Basic, and Delphi version of the ctor can use default parameter values by simply passing AL_DEFAULT for each of the different numeric parameters.

Function

This constructor creates a new ALPkCompressor.  This compressor by itself is a low cost object with just a couple of data members that help it remember what parameters to use when it comes time to compress.  The compressor becomes a resource user when you call the Compress() member function.

Create compressor objects when you are initializing a toolkit, or when compressing files by hand, or when using an ALCompressedObject.

Returns

The C++ constructor returns nothing.  C, Visual Basic, and Delphi programmers get a handle that points to the newly created object.


ALPkCompressor() see also
See Also

ALGlCompressor::ALGlCompressor()


ALPkCompressor() example
See example programs EX09CON.CPP, EX14PM.CPP, EX14WIN.CPP, EX14WIN.C, EX18CON.C, EX14VB.FRM, and EX14UNIT.PAS.


ALPkDecompressor()
ALPkDecompressor::ALPkDecompressor()

see also	example

Constructor for the PkWare deflate decompressor engine

Synopsis

#include "arclib.h"

#include "pkengn.h"

 ALPkDecompressor::ALPkDecompressor()

 hALDecompressor newALPkDecompressor( void )

 Declare Function newALPkDecompressor Lib "AL20LW" As Long

 function newALPkDecompressor : hALDecompressor;

Arguments

None

Function

This constructor creates a new ALPkDecompressor.  This decompressor by itself is almost a no-cost object with no derived class data members that need to be initialized.  The decompressor becomes a resource user when you call the Decompress() member function.

Create decompressor objects when you are initializing a toolkit, when decompressing files by hand, or when using an ALCompressedObject.

Returns

The C++ constructor returns nothing.  C, Visual Basic, and Delphi programmers get a handle that points to the newly created object.


ALPkDecompressor() see also
See Also

ALPkCompressor::ALPkCompressor()


ALPkDecompressor() example
See example programs EX09CON.CPP, EX14PM.CPP, EX14WIN.CPP, EX14WIN.C, EX16CON.C, EX14VB.FRM, and EX14UNIT.PAS.


~ALArchive()
ALArchive::~ALArchive()

see also	example

Destructor for ALArchive class

Synopsis

#include "arclib.h"

 ALArchive::~ALArchive()

 void deleteALArchive( hALArchive this_object )

 Declare Sub deleteALArchive Lib "AL20LW" ( ByVal this_object& )

 procedure deleteALArchive( this_object : hALArchive );

Arguments

this_object

Handle to the ALArchive object

Function

ALArchive::~ALArchive() is the destructor called during the destruction of an object derived from ALArchive.  This destructor may destroy the ALStorage object as well.

Returns

N/A


~ALArchive() see also
See Also

ALGlArchive::ALGlArchive(), ALPkArchive::ALPkArchive()


~ALArchive() example
See example programs EX00PM.CPP, EX00WIN.CPP, EX00WIN.C, EX16CON.C, EX00VB.FRM, and EX00UNIT.PAS.


Append() 1- ALArchive class
ALArchive::Append()

see also	example

Append archive entries to archive

Synopsis

#include "arclib.h"

 int ALArchive::Append( ALEntryList &list )

 int ALArchiveAppend( hALArchive this_object, hALEntryList list )

 Declare Function ALArchiveAppend Lib "AL20LW" ( ByVal this_object&, ByVal list&) As Integer

 function ALArchiveAppend( this_object : hALArchive; list : hALEntryList ) : Integer;

Arguments

this_object

Handle to the ALArchive object

list

Archive entry list describing which object entries will be appended

Function

ALArchive::Append() appends storage objects to the end of an archive.  This function opens an archive, appends the entries in the archive entry list, and then closes it.  If you want to then get an updated directory of what is in the archive after this operation, you must call ALArchive::ReadDirectory().

Objects in the list that are not marked will be ignored.

This function doesn't need any decompression engines.  You can save on .EXE space by selecting a "compress-only" toolkit when constructing your ALEntryList object.

A sample piece of code including Append() is shown below.

    ALEntryList list( &monitor );

    list.MakeEntriesFromListBox( hDlg, AL_INPUT_FILES );

    pArchive = new ALPkArchive( input_name );

    pArchive->Append( list );

Returns

ALArchive::Append() returns one of the following values:

Return Value	Meaning

> = 0	number of object entries appended to the archive entry list

< 0	error occurred


Append() 1 see also - ALArchive class
See Also

ALArchive::Create()


Append() 1 example - ALArchive class
See example programs EX01WIN.C, EX02CON.C, EX01VB.FRM, and EX01UNIT.PAS.


Append() 2 - ALArchive class
ALArchive::Append()

see also	example

Append existing archive entries to a new archive

Synopsis

#include "arclib.h"

 int ALArchive::Append( ALArchive &source_archive, ALEntryList &source_list )

 int ALArchiveAppendFromArchive( hALArchive this_object, hALArchive source_archive, hALEntryList source_list )

 Declare Function ALArchiveAppendFromArchive Lib "AL20LW" ( ByVal this_object&, ByVal source_archive&, ByVal source_list& ) As Integer

 function ALArchiveAppendFromArchive( this_object : hALArchive; source_archive : hALArchive; source_list : hALEntryList ) : Integer;

Arguments

this_object

Handle to the ALArchive object

source_archive

Archive containing the compressed objects to be appended

source_list

Archive entry list describing the object entries to be appended

Function

ALArchive::Append() appends existing archive entries to the end of an archive.  This function is a lot like the previously described version of Append() except that this function adds a list of objects that are already compressed and in another archive.  This is why this function passes a reference to another archive, in addition to the list of object entries to be appended.

This function doesn't need any decompression engines.  You can save on .EXE space by selecting a "compress-only" toolkit when constructing your ALEntryList object.

A sample code piece including this Append() function is shown below.

        char archive_name[ 128 ];

        GetDlgItemText( hDlg, AL_OUTPUT, archive_name, 128 );

        ALGlArchive archive( archive_name );

        archive.Append( *pArchive, list );

Returns

ALArchive::Append() returns one of the following values:

Return Value	Meaning

> = 0	number of object entries appended to the archive entry list

< 0	error occurred


Append() 2 see also - ALArchive class
See Also

ALArchive::Create()


Append() 2 example - ALArchive class
See example programs EX02WIN.C, EX02VB.FRM, and EX02UNIT.PAS.


ClearError() - ALArchive class
ALArchive::ClearError()

see also	example

Reset the error status for an entry list

Synopsis

#include "arclib.h"

 void ALArchive::ClearError()

 void ALArchiveClearError( hALArchive this_object )

 Declare Sub ALArchiveClearError Lib "AL20LW" ( ByVal this_object& )

 procedure ALArchiveClearError( this_object : hALArchive );

Arguments

this_object

A reference or pointer to the ALArchive object that is going to have its status reset.  The C++ version of this call does not have an explicit argument here, since it has access to 'this' implicitly.

Function

An ALArchive object carries around an ALStatus object in its mStatus member.  Error conditions are not cleared automatically by the library, so the user will have to clear it manually with a call to this function.

In C++, this function will be implemented as an inline function.

A sample piece of code including ClearError() is shown below.

archive.Extract( list );

if ( archive.mStatus < 0 ){

     cerr << "Error \n";

     archive.ClearError();

Returns

None


ClearError() see also - ALArchive class
See also

ALStorage::ClearError()


ClearError() example - ALArchive class
See example program EX03MFC.CPP.


Create() 1 - ALArchive class
ALArchive::Create()

see also	example

Create archive from list of storage objects

Synopsis

#include "arclib.h"

 int ALArchive::Create( ALEntryList &list )

 int ALArchiveCreate( hALArchive this_object, hALEntryList list )

 Declare Function ALArchiveCreate Lib "AL20LW" ( ByVal this_object&, ByVal list& ) As Integer

 function ALArchiveCreate( this_object : hALArchive; list : hALEntryList ) : Integer;

Arguments

this_object

Handle to the ALArchive object

list

Reference to the list of object entries to be inserted into the new archive

Function

ALArchive::Create() creates a new archive object from a list of storage objects.  This function calls ALStorage::Create() to create a storage object in which to hold the archive; this is often referred to as an archive object.  ALArchive::Create() then works its way through the list of job entries compressing the data and storing it in the archive.   After the entire list has been processed, the list of objects is written to the archive in directory format.  The archive is then closed using ALStorage::Close().  The job list and storage objects in the list will have been updated with information pertaining to storage locations, CRCs, file sizes, etc.

This function doesn't need any decompression engines.  You can save on .EXE space by selecting a "compress-only" toolkit when constructing your ALEntryList object.

A sample code piece including Create() is shown below.

    ALGlArchive archive( "DOS00.GAL" );

    ALEntryList list( 0, GlTools() );

    list.AddWildCardFiles( "input*.dat, *.bak" );

    archive.Create( list );

Returns

ALArchive::Create() returns one of the following values:

Return Value	Meaning

> = 0	number of objects inserted into the archive

< 0	error occurred


Create() 1 see also - ALArchive class
See Also

ALArchive::Append()


Create() 1 example - ALArchive class
See example programs EX00PM.CPP, EX00WIN.CPP, EX02PM.CPP, EX06CON.CPP, EX00CON.C, EX00WIN.C, EX00VB.FRM, and EX00UNIT.PAS.


Create() 2 - ALArchive class
ALArchive::Create()

see also	example

Create new archive from list of objects in another archive

Synopsis

#include "arclib.h"

 int Create( ALArchive &source_archive, ALEntryList &source_list )

 int ALArchiveCreateFromArchive( hALArchive this_object, hALArchive source_archive, hALEntryList source_list )

 Declare Function ALArchiveCreateFromArchive Lib "AL20LW" ( ByVal this_object&, ByVal source_archive&, ByVal source_list& ) As Integer

 function ALArchiveCreateFromArchive( this_object : hALArchive; source_archive : hALArchive; source_list : hALEntryList ) : Integer;

Arguments

this_object

Handle to the ALArchive object

source_archive

Archive containing the source objects to be copied

source_list

Archive entry list describing the objects to be copied

Function

This second ALArchive::Create() function does the same thing as the previous Create() function.  The difference is that the objects are already compressed, and reside in another archive.  As the jobs in the list are processed, they are updated with their current positions within the new archive.

This function doesn't need any decompression engines.  You can save on .EXE space by selecting a "compress-only" toolkit when constructing your ALEntryList object.

A sample code piece including Create() is shown below.

void add( ALPkArchive *pArchive ){

        char archive_name[ 128 ];

        GetDlgItemText( hDlg, AL_OUTPUT, archive_name, 128 );

        ALPkArchive archive( archive_name );

        archive.Create( *pArchive, list );

Returns

ALArchiveCreate() returns one of the following values:

Return Value	Meaning

> = 0	number of objects copied

< 0	error occurred


Create() 2 see also - ALArchive class
See Also

ALArchive::Append()


Create() 2 example - ALArchive class
See example programs EX02WIN.CPP, EX14PM.CPP, EX00CON.C, EX00WIN.C, EX00VB.FRM, and EX00UNIT.PAS.


Delete() - ALArchive class
ALArchive::Delete()

see also	example

Delete objects from an archive

Synopsis

#include "arclib.h"

 int ALArchive::Delete( ALEntryList &list, ALArchive &output_archive )

 int ALArchiveDelete( hALArchive this_object, hALEntryList list, hALArchive output_archive )

 Declare Function ALArchiveDelete Lib "AL20LW" ( ByVal this_object&, ByVal list&, ByVal output_archive& ) As Integer

 function ALArchiveDelete( this_object : hALArchive; list : hALEntryList; output_archive : hALArchive ) : Integer;

Arguments

this_object

Handle to the ALArchive object

list

Archive entry list from which object entries are to be deleted

output_archive

Archive created when marked objects are deleted.  If the name of this object is an empty string (""), this function assumes that you want to make the original archive into a backup.

Function

ALArchive::Delete() deletes marked object files in an archive; all entries are marked by default but can be cleared by several ALEntryList commands (described later in this chapter).  When it deletes files, ALArchive::Delete() is actually performing work on two archives.  A set of objects is deleted from the original archive, resulting in a newly created archive, minus the deleted objects.  The original archive is considered a backup archive.  That is why this function contains a "destination" (output_archive) argument. You must pass it the name of the archive object that will become the new archive.

If you pass an archive with an empty string ("") as its name to the output_archive argument, this function assumes that you want to make the original archive into a backup.  To do this, ALArchive::Delete() first creates the new archive, using a temporary name.  It then renames the original archive to a backup name.  Finally, it uses the original archive name for the newly created archive.

This function doesn't need any compression engines.  You can save on .EXE space by selecting a "decompress-only" toolkit when constructing your ALEntryList object.

A sample code piece including Delete() is shown below.

    ALGlArchive archive( "DOS00.GAL" );

    ALEntryList list;

    archive.ReadDirectory( list );

    ALEntry *entry = list.GetFirstEntry();

    list.ClearMarks();

    list.SetMarks( "*.BAK" );

    archive.Delete( list, ALGlArchive( "" ) );

Returns

ALArchive::Delete() returns one of the following values:

Return Value	Meaning

> = 0	number of objects deleted from archive

< 0	error occurred


Delete() see also - ALArchive class
See Also

ALArchive::Extract()


Delete() example - ALArchive class
See example programs EX03CON.CPP, EX03PM.CPP, EX03WIN.CPP, EX03CON.C, EX03WIN.C, EX03VB.FRM, and EX03UNIT.PAS.


Extract() - ALArchive class
ALArchive::Extract()

see also	example

Extract storage objects from archive

Synopsis

#include "arclib.h"

 int Extract( ALEntryList &list )

 int ALArchiveExtract( hALArchive this_object, hALEntryList list )

 Declare Function ALArchiveExtract Lib "AL20LW" ( ByVal this_object&, ByVal list& ) As Integer

 function ALArchiveExtract( this_object : hALArchive; list : hALEntryList ) : Integer;

Arguments

this_object

Handle to the ALArchive object

list

 List containing object entries to be extracted

Function

ALArchive::Extract() extracts all of the marked objects in an archive entry list.  It takes the decompression engine and storage object from the archive entry list, and uses them to extract the marked objects.

This function doesn't need any compression engines.  You can save on .EXE space by selecting a "decompress-only" toolkit when constructing your ALEntryList object.

A sample code piece including Extract() is shown below.

    ALEntryList list( &monitor);

    list.MakeEntriesFromListBox( hDlg, list_box );

    archive.Extract( list );

Returns

ALArchive::Extract() returns one of the following values:

Return Value	Meaning

> = 0	number of objects extracted from archive.

< 0	error occurred


Extract() see also - ALArchive class
See Also

ALArchive::Create()


Extract() example - ALArchive class
See example programs EX04PM.CPP, EX07CON.CPP, EX04WIN.C, EX07CON.C, EX04VB.FRM, and EX04UNIT.PAS.


FillListBox() - ALArchive class
ALArchive::FillListBox()

see also	example

Insert storage object names into a list box control

Synopsis

#include "arclib.h"

 int FillListBox( HWND hWnd, int list_box_id = -1 )

 int ALArchiveFillListBox( hALArchive this_object, HWND hWnd, int list_box_id )

 Declare Function ALArchiveFillListBox Lib "AL20LW" ( ByVal this_object&, ByVal hWnd%,  ByVal list_box_id% ) As Integer

 function ALArchiveFillListBox( this_object : hALArchive; hDlg : HWnd; list_box_id : Integer ) : Integer;

Arguments

this_object

Handle to the ALArchive object

hWnd

This argument can represent one of two things.  If the value of list_box_id is set to -1, it means that hWnd refers to an actual list box itself.  If the value of list_box_id is not -1, it means that hWnd refers to a dialog box, and list_box_id refers to the id of a list box control within that dialog box.

list_box_id

See the description of hWnd for a full detail of what this argument does.

Function

ALArchive::FillListBox() resets the list box so its existing contents are deleted.  It then inserts the names of all of the objects into a Windows or Presentation Manager list box, ignoring unmarked entries.  This makes it a good shortcut function.

Using this function will cause the copy compressor and decompressor to be linked to your application.

A sample code piece including FillListBox() is shown below.

    GetDlgItemText( hDlg, AL_ARCHIVE_NAME, input_name, 128 );

    ALPkArchive archive( input_name );

    archive.FillListBox( hWnd );

Returns

ALArchive::FillListBox() returns one of the following values:

Return Value	Meaning

>= 0	number of entries inserted into list box

< 0	error occurred


FillListBox() see also - ALArchive class
See Also

ALEntryList::FillListBox()


FillListBox() example - ALArchive class
See example programs EX01PM.CPP, EX01WIN.CPP, EX01WIN.C, EX01VB.FRM, and EX01UNIT.PAS.


GetComment() - ALArchive class
ALArchive::GetComment()

see also	example

Get comment associated with archive

Synopsis

#include "arclib.h"

 const char *GetComment()

 char *ALArchiveGetComment( hALArchive this_object )

 Declare Function ALArchiveGetComment Lib "AL20LW"( ByVal this_object& ) As String

 function ALArchiveGetComment( this_object : hALArchive ) : String;

Arguments

this_object

Handle to the ALArchive object

Function

ALArchive::GetComment() retrieves a comment associated with an archive.  You must first read in the archive directory.

A sample code piece including GetComment(), is shown below.

    cout << "Comment: " << Archive.GetComment() << "\n";

Returns

GetComment() returns a pointer to the comment in C++ and C.  The comment string is returned in Visual Basic and Delphi.


GetComment() see also - ALArchive class
See Also

ALArchive::SetComment()


GetComment() example - ALArchive class
See example programs EX05CON.CPP and EX05CON.C.


GetStorageObject() - ALArchive class
ALArchive::GetStorageObject()

see also	example

Get a pointer to the storage object being used by the ALArchive

Synopsis

#include "arclib.h"

 ALStorage * ALArchive::GetStorageObject()

 hALStorage ALArchiveGetStorage( hALArchive this_object )

 Declare Function ALArchiveGetStorage Lib "AL20LW" ( ByVal archive& ) As Long

 function ALArchiveGetStorage( this_object : hALArchive ) : hALStorage;

Arguments

this_object

A reference or pointer to the ALArchive object in question.  The C++ version of this function does not have an explicit argument for this_object,  since it has access to this implicitly.

Function

An ALArchive object always has a storage object underlying it.  The storage object is where the archived objects are actually stored.  At times, you may want to get this storage object.  You can access it with this function.

This function will normally be implemented as an inline function.

A sample piece of code including GetStorageObject() is shown below.

void process( ALArchive * arc ){

 ALStorage *s=arc->GetStorageObject();

cout << s->mName;

Returns

A reference or pointer to the storage object underlying the archive.


GetStorageObject() see also - ALArchive class
See Also

ALFile::ALFile(), ALMemory::ALMemory()


GetStorageObject() example - ALArchive class
See example program EX00WIN.CPP, EX01PM.CPP, EX02CON.CPP, EX00WIN.C, EX00CON.C, EX00VB.FRM, and EX00UNIT.PAS.


GetVersion() - ALArchive class
ALArchive::GetVersion()

see also	example

Get version of archive

Synopsis

#include "arclib.h"

 short GetVersion()

 int ALArchiveGetVersion( hALArchive this_object )

 Declare Function ALArchiveGetVersion Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALArchiveGetVersion( this_object : hALArchive ) : Integer;

Arguments

this_object

Handle to the ALArchive object

Function

ALArchive::GetVersion() retrieves the version level of the archive.  This number will only change when the format of the archive (not just the library version) changes.  The version is stored in the archive directory when it is written to the archive storage object.  This value will be invalid (-1) until the archive directory has been read.  Greenleaf archives should return 0x100.  PKWare archives should return 0x20.

A sample code piece including GetVersion() is shown below.

    archive.ReadDirectory( list );

    cout << "Version: "

             << hex

             << archive.GetVersion()

             << end;

Returns

ALArchive::GetVersion() returns one of the following values:

Return Value	Meaning

0x100	valid ALGlArchive

0x20	valid ALPkArchive

-1	Directory not read


GetVersion() see also - ALArchive class
See Also

ALArchive::ReadDirectory()


GetVersion() example - ALArchive class
See example programs EX15PM.CPP, EX15WIN.CPP, EX15WIN.C, EX15VB.FRM, and EX15UNIT.PAS.


ReadDirectory() - ALArchive class
ALArchive::ReadDirectory()

see also	example

Read archive directory

Synopsis

#include "arclib.h"

 virtual int ReadDirectory( ALEntryList &list )

 int ALArchiveReadDirectory( hALArchive this_object, hALEntryList list )

 Declare Function ALArchiveReadDirectory Lib "AL20LW" ( ByVal this_object, ByVal list& )

 function ALArchiveReadDirectory( this_object : hALEntryList; list : hALEntryList ) : Integer;

Arguments

this_object

Handle to the ALArchive object

list

Reference to the archive entry list to which directory entries will be added

Function

ALArchive::ReadDirectory() reads the entire directory out of an archive, and places all of the archive entries in the supplied list.  Normally, the list will have just been constructed, and will contain no previous entries.

Once you have made the list, you can go through it, unmarking entries (or deleting them) until you have a list of files that you want to extract or copy.

A sample code piece including ReadDirectory() is shown below.

    ALEntryList list;

    archive.ReadDirectory( list );

Returns

ALArchive::ReadDirectory() returns one of the following values:

Return Value	Meaning

> = 0	number of entries added to archive entry list

< 0	error occurred


ReadDirectory() see also - ALArchive class
See Also

ALArchive::WriteDirectory()


ReadDirectory() example - ALArchive class
See example programs EX02CON.CPP, EX02PM.CPP, EX03WIN.CPP, EX02WIN.C, EX03CON.C, EX02VB.FRM, and EX02UNIT.PAS.


SetComment() - ALArchive class
ALArchive::SetComment()

see also	example

Set comment

Synopsis

#include "arclib.h"

 int SetComment( char *comment )

 int ALArchiveSetComment( hALEntry this_object, char *comment)

 Declare Function ALArchiveSetComment Lib "AL20LW" ( ByVal this_object&, ByVal comment$ ) As Integer

 function ALArchiveSetComment( this_object : hALEntry; comment : String ) : Integer;

Arguments

this_object

Handle to the ALArchive object

comment

Comment to be set (for C++ and C , this is a pointer to a comment to be set).

Function

ALArchive::SetComment() sets a comment to be associated with the archive itself (as opposed to a comment associated with an entry in the archive).  This function allocates its own storage space in the ALArchive object, while making a copy of the comment passed to it.  Any activity that causes the directory to be written will also write the comment out to disk.

A sample code piece including SetComment() is shown below.

    archive.ReadDirectory( list );

    archive.SetComment( "My new archive." );

    archive.WriteDirectory( list );

Returns

ALArchive::SetComment() returns AL_SUCCESS if the function was successful.  An error code is returned if the function was not successful.


SetComment() see also - ALArchive class
See Also

ALArchive::GetComment()


SetComment() example - ALArchive class
See example programs EX04CON.CPP, and EX04CON.C.


WriteDirectory() - ALArchive class
ALArchive::WriteDirectory()

see also	example

Write archive directory

Synopsis

#include "arclib.h"

 int WriteDirectory( ALEntryList &list )

 int ALArchiveWriteDirectory( hALArchive this_object, hALEntryList list )

 Declare Function ALArchiveWriteDirectory Lib "AL20LW" ( ByVal this_object&, ByVal list& ) As Integer

 function ALArchiveWriteDirectory( this_object : hALArchive; list : hALEntryList ) : Integer;

Arguments

this_object

Handle to the ALArchive object

list

List of archive entries to be written to the archive directory

Function

ALArchive::WriteDirectory() writes a list of archive entries to the archive directory, which wipes out the existing directory.  This function should be used with caution; you should write a directory out to an archive after reading in the same directory using ALArchive::ReadDirectory().  This should be done after modifying the archive, comments, object names, or object types.

You do not need to write the directory after performing a Create(), Append(), or Delete() operation.  It is done automatically.

You can use this function to change the attributes (i.e. name, time/date, protection bits) of objects that have already been stored in the archive.

A sample code piece including WriteDirectory() is shown below.

    archive.WriteDirectory( list );

Returns

ALArchive::WriteDirectory() returns one of the following values:

Return Value	Meaning

>= 0	number of directory entries written

< 0	error occurred


WriteDirectory() see also - ALArchive class
See Also

ALArchive::ReadDirectory()


WriteDirectory() example - ALArchive class
See example programs EX04CON.CPP and EX04CON.C.


ALArchiveGetStatusCode()

see also	example

Get status of ALArchive object

Synopsis

#include "arclib.h"

 int ALArchiveGetStatusCode( hALArchive this_object )

 Declare Function ALArchiveGetStatusCode Lib "AL20LW" (ByVal this_object&) As Integer

 function ALArchiveGetStatusCode( this_object : hALArchive ) : Integer;

C, Visual Basic, and Delphi programmers can access the ALArchive data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALArchive object

Function

ALArchiveGetStatusCode() returns a status value of an ALArchive object.  ArchiveLib has similar access functions for all objects that have mStatus members, including ALStorage, ALCompressor, ALDecompressor, and ALEntryList.  Status members contain an integer indicating the current status of an object.  ALArchiveGetStatusCode() retrieves that value.

A sample code piece including ALArchiveGetStatusCode() is shown below:

    if ( ALArchiveGetStatusCode( object ) < AL_SUCCESS )

        printf( "Error, prepare to reboot..." );

Returns

ALArchiveGetStatusCode() returns AL_SUCCESS if the function was successful.  An error code is returned if the function was not successful.


ALArchiveGetStatusCode() see also
See Also

ALArchiveGetStatusDetail(), ALArchiveGetStatusString()


ALArchiveGetStatusCode() example
See example programs EX00CON.C, EX04WIN.C, EX15VB.FRM, and EX15UNIT.PAS.


ALArchiveGetStatusDetail()

see also	example

Get detailed error information

Synopsis

#include "arclib.h"

 char *ALArchiveGetStatusDetail( hALArchive this_object )

 Declare Function ALArchiveGetStatusDetail Lib "AL20LW" ( ByVal this_object& ) As String

 function ALArchiveGetStatusDetail( this_object : hALArchive ) : String;

C, Visual Basic, and Delphi programmers can access the ALArchive data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALArchive object

Function

ALArchiveGetStatusDetail() returns detailed information about a specific error message associated with ALArchive.  ArchiveLib has similar access functions for all objects that have mStatus members, including ALStorage, ALCompressor, ALDecompressor, and ALEntryList.  The detailed message produced by this function includes various data items that might help track down the source of the problem.  These messages are fairly technical, and are intended for use by developers only instead of end-users.

Returns

ALArchiveGetStatusDetail() returns a brief description of the error message.  If no error is found,  0 (C only) or an empty string is returned.


ALArchiveGetStatusDetail() see also
See Also

ALArchiveGetStatusCode(), ALArchiveGetStatusString()


ALArchiveGetStatusDetail() example
See example programs EX00CON.C, EX15WIN.C,  EX15VB.FRM, and EX01UNIT.PAS.


ALArchiveGetStatusString()

see also	example

Translate error code into string

Synopsis

#include "arclib.h"

 char *ALArchiveGetStatusString( hALArchive this_object )

 Declare Function ALArchiveGetStatusString Lib "AL20LW" (ByVal this_object&) As String

 function ALArchiveGetStatusString( this_object : hALArchive ) : String;

C, Visual Basic, and Delphi programmers can access the ALArchive data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALArchive object

Function

ALArchiveGetStatusString() translates an error code in an ALArchive object to a short text string.  ArchiveLib has similar access functions for all objects that have mStatus members, including ALStorage, ALCompressor, ALDecompressor, and ALEntryList.  When displaying error values to users, the string returned by this function will be much more intelligible than displaying the integer value of the error.

A few sample error code translations include the following:

     AL_SUCCESS	"Success"

     AL_END_OF_FILE	"End of file"

     AL_CANT_OPEN_BUFFER	"Can't allocate buffer"

Returns

ALArchiveGetStatusString() returns a brief description of the error message.  If no error is found, 0 (C only) or an empty string is returned.


ALArchiveGetStatusString() see also
See Also

ALArchiveGetStatusDetail()


ALArchiveGetStatusString() example
See example programs EX00WIN.C, EX16CON.C, EX00VB.FRM, and EX00UNIT.PAS.


ALArchiveSetError()

see also	example

Manipulate error code for ALArchive

Synopsis

#include "arclib.h"

 int ALArchiveSetError( hALArchive this_object, int error_code, char *text )

 Declare Function ALArchiveSetError Lib "AL20LW" ( ByVal this_object&, ByVal error_code%, ByVal text& ) As Integer

 function ALArchiveSetError( this_object : hALArchive; error_code : Integer; text : String ) : Integer;

C, Visual Basic, and Delphi programmers can access the ALArchive data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALArchive object

error_code

Numeric (integer) error code

text

Pointer to the formatted error message to store in the object's mStatus data member

Function

ALArchiveSetError() is called  to force an ALArchive object into an error state.  This is a useful way to abort an ArchiveLib operation.  To do this, ALArchiveSetError() performs two actions:

•	It sets the error code for the object.

•	It allocates enough space in mStatus to copy and then hold a detailed description of why the error occurred.

Returns

ALArchiveSetError() returns AL_SUCCESS if the function was successful.  An error code is returned if the function was not successful.


ALArchiveSetError() see also
See Also

ALArchiveGetStatusCode(), ALArchiveGetStatusString()


ALArchiveSetError() example
See example programs EX15WIN.C and EX15VB.FRM.


ALGlArchive() 1
ALGlArchive::ALGlArchive()

see also	example

The Greenleaf archive constructor

Synopsis

#include "arclib.h"

#include "glarc.h"

 ALGlArchive::ALGlArchive( ALStorage &storage_object )

 hALArchive newALGlArchiveFromStorage( hALStorage storage_object )

 Declare Function newALGlArchiveFromStorage Lib "AL20LW" ( ByVal storage_object& ) As Long

 function newALGlArchiveFromStorage( storage_object : hALStorage ) : hALArchive;

Arguments

storage_object

A pointer to the storage object that holds the archive.

Function

This function creates a new ALGlArchive object, using a storage object as the underlying physical container.  ALGlArchive is a sibling to ALPkArchive.  While they both use the same base class, and support many functions in common, they are essentially incompatible.

You call this constructor to manipulate any Greenleaf format archive, including ones that haven't been created yet.

The base class, ALArchive, has a single argument to its own constructor that determines whether or not it destroys the underlying storage object in its destructor.  Since we are using user-specified storage in this case, we pass 0, indicating that we don't want the destructor to destroy the underlying storage object.

Returns

When called from C, Visual Basic, or Delphi, the translation function returns a handle to a newly created archive object.


ALGlArchive() 1 see also
See Also

ALPkArchive::AlPkArchive()


ALGlArchive() 1 example
See example programs EX04WIN.CPP, EX13CON.CPP, EX04WIN.C, EX04VB.FRM, and EX04UNIT.PAS.


ALGlArchive() 2
ALGlArchive::ALGlArchive()

see also	example

A Greenleaf archive constructor that creates a file object

Synopsis

#include "arclib.h"

#include "glarc.h"

 ALGlArchive::ALGlArchive( const char *file_name )

 hALArchive newALGlArchive( char *name )

 Declare Function newALGlArchive Lib "AL20LW" ( ByVal name$ ) As Long

 function newALGlArchive( name : String ) : hALArchive;

Arguments

name

A character string that gives the name of the file that you want to use for this Greenleaf archive.  The file name should be a legal one for your operating system  or environment.

Function

There are two versions of the ALGlArchive constructor.  The first creates an archive in a storage object.  The second, this function, creates a new ALFile object using the name you specify as an argument.  This is strictly a convenience; it lets you bypass the extra step required to build the file yourself.

Since the constructor has created the ALFile object, we ask the ALArchive constructor to set the delete_in_dtor flag.  This means that when the archive is destroyed, the ALStorage object destructor will be called as well.

Returns

When called by C, Visual Basic, or Delphi, this constructor returns a pointer to a newly created ALGlArchive object.


ALGlArchive() 2 see also
See Also

ALPkArchive::ALPkArchive()


ALGlArchive() 2 example
See example programs EX00CON.CPP, EX00PM.CPP, EX00CON.C, EX00WIN.C, EX00VB.FRM, and EX00UNIT.PAS.


ALPkArchive() 1
ALPkArchive::ALPkArchive()

see also	example

The PKWare archive constructor

Synopsis

#include "arclib.h"

#include "pkarc.h"

 ALPkArchive::ALPkArchive( ALStorage &storage_object )

 hALArchive newALPkArchiveFromStorage( hALStorage storage_object )

 Declare Function newALPkArchiveFromStorage Lib "AL20LW" (ByVal storage_object&) As Long

 function newALPkArchiveFromStorage( storage_object : hALStorage ) : hALArchive;

Arguments

storage_object

A pointer to the storage object that holds the archive.

Function

This function creates a new ALPkArchive object, using a storage object as the underlying physical container.  ALPkArchive is a sibling to ALGlArchive.  While they both use the same base class, and support many functions in common, they are essentially incompatible.

You call this constructor to manipulate any PKWare format archive, including ones that haven't been created yet.

Recall that the base class, ALArchive, has a single argument to its own constructor that determines whether or not it destroys the underlying storage object in its destructor.  Since we are using user-specified storage in this case, we pass 0, indicating that we don't want the destructor to destroy the underlying storage object.

Returns

When called from C, Visual Basic, or Delphi, the translation function returns a handle to a newly created archive object.


ALPkArchive() 1 see also
See Also

ALGlArchive::ALGlArchive()


ALPkArchive() 1 example
See example programs EX04WIN.CPP, EX13CON.CPP, EX04WIN.C, EX04VB.FRM, and EX04UNIT.PAS.


ALPkArchive() 2
ALPkArchive::ALPkArchive()

see also	example

A PKWare archive constructor that creates its own file object

Synopsis

#include "arclib.h"

#include "pkarc.h"

 ALPkArchive::ALPkArchive( const char *file_name )

 hALArchive newALPkArchive( char *name )

 Declare Function newALPkArchive Lib "AL20LW" ( ByVal name$ ) As Long

 function newALPkArchive( name : String ) : hALArchive;

Arguments

name

A character string that gives the name of the file that you want to use for this PkArchive.  The file name should be a legal one for your operating system or environment.

Function

There are two versions of the ALPkArchive constructor.  The first creates an archive in a storage object.  The second, this function, creates a new ALFile object using the name you specify as an argument.  This is strictly a convenience; it lets you bypass the extra step required to build the  file yourself.

Since the constructor has created the ALFile object, we ask the ALArchive constructor to set the delete_in_dtor flag.  This means that when the archive is destroyed, the ALStorageObject destructor will be called as well.

Returns

When called by C, Visual Basic, or Delphi, this constructor returns a pointer to a newly created ALPkArchive object.


ALPkArchive() 2 see also
See Also

ALGlArchive::ALGlArchive()


ALPkArchive() 2 example
See example programs EX00CON.CPP, EX00PM.CPP, EX00WIN.CPP, EX00CON.C, EX00WIN.C, EX00VB.FRM, and EX00UNIT.PAS.


ALEntry()
ALEntry::ALEntry()

see also	example

Constructor for ALEntry class

Synopsis

#include "arclib.h"

 ALEntry( ALEntryList &list, ALStorage *object, ALCompressor *compressor, ALDecompressor *decompressor )

 newALEntry( hALEntryList list, hALStorage storage, hALCompressor compressor, hALDecompressor decompressor )

 Declare Function newALEntry Lib "AL20LW"( ByVal list&, ByVal storage&, ByVal compressor&, ByVal decompressor& ) As Long

 function newALEntry( list : hALEntryList; storage : hALStorage; compressor : hALCompressor; decompressor : hALDecompressor ) : hALEntry;

Arguments

list

Archive entry list (for C++, this is a reference to an archive entry list).

object

A pointer to the storage object that is attached to this entry.  Remember, this is an unopened storage object, so it does not consume very much space. The ALEntry destructor will destroy this engine for you.

compressor

A pointer to the compression engine that is going to be used to create or insert the storage object into the archive.  This engine will be destroyed in the ALEntry destructor, so be sure to give up any claim you might have on it.  If you aren't going to be compressing the object, a value of 0 is perfectly acceptable here.

decompressor

A pointer to the decompression engine that is going to be used to extract the storage object from the archive.  This engine will be destroyed in the ALEntry destructor, so be sure to give up any claim you might have on it.  If you aren't going to be decompressing the object, a value of 0 is perfectly acceptable here.

Function

ALEntry() is the constructor for the ALEntry class, and can be used to create and add certain information to archive entry lists (although some higher-level functions such as ALEntryList::AddWildCardFiles() do this for you).  This constructor provides four pieces of information that must be supplied if archive entries are created manually by a programmer:

•	A reference to an object of ALEntryList

•	A pointer to a storage object

•	A pointer to a compression engine

•	A pointer to a decompression engine

This means that you must create ALEntry objects dynamically using the new operator.  When you create an ALEntry object, you pass it a pointer to a storage object, a compression engine, and a decompression engine.  Even though you may have created these yourself, the ALEntry object is going to delete them in its destructor.  You should never attempt to delete them.

If you need to keep using a storage object beyond the scope of the ALEntry object, you should make a copy of the pointer to the storage object, and set the mpStorageObject data member of the ALEntry class to 0.

ALEntry objects themselves are also automatically deleted by ArchiveLib. Every ALEntry object is part of a linked list of ALEntry objects that belong to an ALEntryList object.  When the ALEntryList object destructor is called, it goes through the list and destroys all of the ALEntry objects in the linked list.

It is important to remember that the archive entry "owns" the storage object, compression engine, and decompression engine.  Do not attempt to destroy these objects yourself.

A sample code piece including the ALEntry constructor, is shown below.

    ALEntryList list( monitor);

    for ( i = 0 ; i  10 ; i++ ) {

        sprintf( name, "INPUT%03d.DAT" );

        new ALEntry( list,

                     	  new ALFileObject( name ),

                    	  new ALGlCompressor(),

                  	  0 );

    }

    pArchive->Append( list );

Returns

There are no returns for C++ constructors.  C, Visual Basic, and Delphi return an hALEntry handle, which is passed as the this_object parameter to all ALEntry functions.


ALEntry() see also
See Also

ALArchive::Append(), ALArchive::Create(), ALArchive::Delete(), ALArchive::Extract()


ALEntry() example
See example program EX14WIN.CPP, EX16CON.CPP, EX14WIN.C, EX16CON.C, EX14VB.FRM, and EX14UNIT.PAS.


~ALEntry()
ALEntry::~ALEntry()

see also	example

Destructor for ALEntry class

Synopsis

#include "arclib.h"

 ALEntry::~ALEntry()

 void deleteALEntry( hALEntry this_object )

 Declare Sub deleteALEntry Lib "AL20LW" ( ByVal this_object& )

 procedure deleteALEntry( this_object : hALEntry );

Arguments

this_object

Handle to the ALEntry object

Function

ALEntry::~ALEntry() is the destructor for the ALEntry class.  It removes an entry from the archive entry list, also destroying the associated storage and compression objects.  When the archive list is destroyed, it will destroy all of the entries for you, so you never have to call this destructor yourself.  However, it can be used to delete an entry and remove it from the list in a single operation.

It is important to remember that the archive list entry "owns" the storage object, compression engine, and decompression engine.  Do not attempt to destroy these objects yourself.

A sample code piece including ~ALEntry(), is shown below.

    ALEntry *entry = list.GetFirstEntry();

    while ( entry ) {

        if ( stricmp( entry->mpStorageObject->mName,

              "TEST.BAK")==0 )

        {

            delete entry;

            return 1;

        }

        entry = entry->GetNextEntry();

    }

    return 0;

Returns

N/A


~ALEntry() see also
See Also

ALEntry::ALEntry(), ALEntry::ClearMark()


~ALEntry() example
See example program EX16CON.CPP.


ClearMark() - ALEntry class
ALEntry::ClearMark()

see also	example

Clear mark from archive entry

Synopsis

#include "arclib.h"

 void ClearMark()

 void ALEntryClearMark( hALEntry this_object )

 Declare Sub ALEntryClearMark Lib "AL20LW" ( ByVal this_object& )

 procedure ALEntryClearMark( this_object : hALEntry );

Arguments

this_object

Handle to the ALEntry object

Function

ALEntry::ClearMark() clears a mark from an archive entry.  Once you clear the mark, all of the archive functions that use a list argument will ignore this entry so that it will not get added to or deleted from an archive.

A sample code piece including ClearMark(), is shown below.

    list.ClearMark();

    ALEntry *entry = list.GetFirstEntry();

    while ( entry ) {

        if ( entry->mpStorageObject->mName.WildCardMatch( "*.BAK" ) )

            entry->ClearMark();

        entry = entry->>GetNextEntry();

    }

Returns

None


ClearMark() see also - ALEntry class
See Also

ALEntry::SetMark()


ClearMark() example - ALEntry class
See example programs EX16CON.CPP and EX16CON.C.


CompressionRatio() - ALEntry class
ALEntry::CompressionRatio()

see also	example

Calculate compression ratio of an object in an archive

Synopsis

#include arclib.h

 int ALEntry::CompressionRatio()

 int ALEntryCompressionRatio( hALEntry this_object )

 Declare Function ALEntryCompressionRatio Lib "AL20LW" (ByVal this_object& ) As Integer

 function ALEntryCompressionRatio( this_object : hALEntry ) : Integer;

Arguments

this_object

Handle to the ALEntry object

Function

ALEntry::CompressionRatio() calculates the compression ratio of a storage object that has already been placed into an archive.  The ratio is the compressed size of an object compared to the uncompressed size of an object.

A sample code piece including CompressionRatio(), is shown below.

    ALEntry *entry = list.GetFirstEntry();

    while ( entry ) {

        cout << entry->mpStorageObject->mName

                 << " "

                 << entry->miGetCompressionRatio()

                 << "%\n";

        entry = entry->>GetNextEntry();

    }

Returns

ALEntry::CompressionRatio() returns one of the following values:

Return Value	Meaning

> 0 	compression ratio (normally a number between 0 and 100)

-1	problem calculating ratio.  Problem occurs if the size or compressed size is unknown.  This can happen if storage objects have not yet been inserted into an archive.


CompressionRatio() see also - ALEntry class
See Also

ALEntry::GetCompressedSize()


CompressionRatio() example - ALEntry class
See example program EX16DOS.C.


Duplicate() - ALEntry class
ALEntry::Duplicate()

see also	example

Check for duplicates in archive entry list

Synopsis

#include "arclib.h"

 int ALEntry::Duplicate( ALEntryList &list )

 int ALEntryDuplicate( hALEntry this_object, hALEntryList list )

 Declare Function ALEntryDuplicate Lib "AL20LW" ( ByVal this_object&, ByVal list& ) As Integer

 function ALEntryDuplicate( this_object : hALEntry; list : hALEntryList ) : Integer;

Arguments

this_object

Handle to the ALEntryList object

list

Name of list in which to check for duplicates

Function

ALEntry::Duplicate() checks to see if an entry is duplicated anywhere in a list.  The archive functions use this to make sure the same object is not inserted twice in an archive.  The this_object entry is checked to see if the storage object in it has the same name as any other storage object in the archive entry list.

Returns

ALEntry::Duplicate() returns one of the following values:

Return Value	Meaning

1	storage object name is duplicated within the archive entry list

0	storage object name is not duplicated within the archive entry list


Duplicate() see also - ALEntry class
See Also

ALEntryList::UnMarkDuplicates()


Duplicate() example - ALEntry class
See example programs EX15WIN.CPP, EX15WIN.C, and EX15VB.FRM.


GetComment() - ALEntry class
ALEntry::GetComment()

see also	example

Get comment associated with archive entry

Synopsis

#include "arclib.h"

 const char *GetComment()

 char *ALEntryGetComment( hALEntry this_object )

 Declare Function ALEntryGetComment Lib "AL20LW" ( ByVal this_object& ) As String

 function ALEntryGetComment( this_object : hALEntry ) : String;

Arguments

this_object

Handle to the ALEntry object

Function

ALEntry::GetComment() retrieves a comment associated with an archive entry.  The comment that is stored with the entry is read in when the archive directory is read using the ALArchive::ReadDirectory() function.

A sample code piece including GetComment() is shown below.

    cout << "Comment: "

             << ( entry->GetComment() ?

entry->GetComment() : "none" )

             << "\n";

Returns

ALEntry::GetComment() returns a pointer to the comment in C++ and C.  The comment string is returned in Visual Basic and Delphi.

Do not use the pointer to change the comment; the archive object owns the comment; it should be modified only with the ALEntry::SetComment() function.


GetComment() see also - ALEntry class
See Also

ALEntry::SetComment()


GetComment() example - ALEntry class
See example programs EX05CON.CPP and EX05CON.C.


GetCompressedSize() - ALEntry class
ALEntry::GetCompressedSize()

see also	example

Get compressed size of archive entry

Synopsis

#include "arclib.h"

 long GetCompressedSize()

 long ALEntryGetCompressedSize( hALEntry this_object )

 Declare Function ALEntryGetCompressedSize Lib "AL20LW" ( ByVal this_object& ) As Long

 function ALEntryGetCompressedSize( this_object : hALEntry ) : LongInt;

Arguments

this_object

Handle to the ALEntry object

Function

After the archive directory has been read from an archive object, the directory will contain valid data, including the compressed size of an archive entry and the CRC.  You can access this information using the ALEntry::GetCompressedSize() function.

If the storage object has not been compressed, you will not get good information from this function.  The valid size will be found after calling ALArchive::Create(), or another compression function.

A sample code piece including GetCompressedSize() is shown below.

    cout << "Size does matter: \n";

    ALEntry *entry = list.GetFirstEntry();

    while ( entry ) {

        cout << "         "

                 << entry->>GetCompressedSize()

                 << "\n";

        entry = entry->GetNextEntry();

    }

Returns

ALEntry::GetCompressedSize() returns one of the following values:

Return Value	Meaning

long value > 0	value indicating the compressed size  NOTE:  The maximum is determined by your operating system.  Check your operating system manual for details on this.

-1L	cannot determine compressed size


GetCompressedSize() see also - ALEntry class
See Also

ALEntry::GetCrc32()


GetCompressedSize() example - ALEntry class
See example programs EX05CON.CPP and EX05CON.C.


GetCrc32() - ALEntry class
ALEntry::GetCrc32()

see also	example

Get 32-bit checksum of archive entry

Synopsis

#include "arclib.h"

 long GetCrc32()

 long ALEntryGetCrc32( hALEntry this_object )

 Declare Function ALEntryGetCrc32 Lib "AL20LW" ( ByVal this_object& ) As Long

 function ALEntryGetCrc32( this_object : hALEntry ) : LongInt;

Arguments

this_object

Handle to the ALEntry object

Function

ALEntry::GetCrc32() retrieves CRC data for an archive entry or object.  Since CRC data is generated by archiving, an object must have been archived at one point or another for CRC data to exist for it.

This function works much the same way ALEntry::GetCompressedSize() works.  After the archive directory has been read from the archive object, it will contain valid data including the CRC data of an archive entry.  This information can be accessed using the GetCrc32() function.  If the archive list is created prior to compression, you will not get good information from this function until you call ALArchive::Create(), or another compression function.  However, if you get the entry via a call to ReadDirectory() you will have access to the information immediately.

A sample code piece including GetCrc32() is shown below.

    cout << "CRC: " << hex << entry->GetCrc32();

Returns

ALEntry::GetCrc32() returns one of the following values:

Return Value	Meaning

long value >= 0	CRC is returned

-1L	The CRC hasn't been calculated.


GetCrc32() see also - ALEntry class
See Also

ALEntry::GetCompressedSize()


GetCrc32() example - ALEntry class
See example programs EX16CON.CPP and EX16CON.C.


GetMark() - ALEntry class
ALEntry::GetMark()

see also	example

Get mark state of an archive entry

Synopsis

#include "arclib.h"

 int GetMark()

 int ALEntryGetMark( hALEntry this_object )

 Declare Function ALEntryGetMark Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALEntryGetMark( this_object : hALEntry; );

Arguments

this_object

Handle to the ALEntry object

Function

ALEntry::GetMark() finds out if an archive entry is marked.  If not, the entry will not be used when any of the archive commands are called such as ALArchive::Create() or ALArchive::Append().

A sample code piece including ALEntry:GetMark() is shown below.

    while ( entry ) {

        if ( entry->GetMark() )

            cout << entry->mpStorageObject.mName;

        entry = entry->GetNextEntry();

    }

Returns

ALEntry::GetMark() returns 0 if the job is not marked.


GetMark() see also - ALEntry class
See Also

ALEntryList::SetMarks()


GetMark() example - ALEntry class
See example programs EX05CON.CPP and EX05CON.C.


GetNextEntry() - ALEntry class
ALEntry::GetNextEntry()

see also	example

Iterate through the ALEntryList

Synopsis

#include "arclib.h"

 ALEntry * ALEntry::GetNextEntry()

 hALEntry ALEntryGetNextEntry( hALEntry this_object )

 Declare Function ALEntryGetNextEntry "AL20LW" ( ByVal this_object& ) As Long

 function ALEntryGetNextEntry( this_object : hALEntry ) : hALEntry;

Arguments

this_object

Handle to the ALEntry object

Function

ALEntry::GetNextEntry() is used in conjunction with the ALEntryList::GetFirstEntry() to iterate through a list of entries in an archive.  This is useful  for performing tasks such as inserting each entry's storage object name into a list box.

Navigation of an archive list requires a "get first/get next" loop; this function is the "get next" portion of that loop.

A sample code piece including GetNextEntry() is shown below.

    while ( entry ) {

        if ( entry->GetMark() )

            cout << entry->mpStorageObject->mName;

        entry = entry->GetNextEntry();

    }

Returns

ALEntry::GetNextEntry() returns one of the following values:

Return Value	Meaning

0	you have reached the end of the list

pointer/handle	next entry in list


GetNextEntry() see also - ALEntry class
See Also

ALEntryList::GetFirstEntry()


GetNextEntry() example - ALEntry class
See example programs EX03CON.CPP, EX04PM.CPP, EX04WIN.CPP, EX03CON.C, EX04WIN.C, and EX04VB.FRM.


SetComment() - ALEntry class
ALEntry::SetComment()

see also	example

Set comment associated with an archive entry

Synopsis

#include "arclib.h"

 int ALEntry::SetComment( const char *comment )

 int ALEntrySetComment( hALEntry this_object, char *comment )

 Declare Function ALEntrySetComment Lib "AL20LW" ( ByVal this_object&, ByVal comment$ ) As Integer

 function ALEntrySetComment( this_object : hALEntry; comment : String ) : Integer;

Arguments

this_object

Handle to the ALEntry object

comment

Comment to associate with an archive entry (for C++ and C, this is a pointer to a null-terminated string).

The archive entry makes its own private copy of a comment, and will delete the storage object when the ALEntry object is destroyed.  This means that the following is okay:

foo( ALEntry *gob )

{

 string s;

 cin >> s;

 gob->SetComment( s.c_str() );

}

Function

A new archive entry usually has no comment associated with it; that's what ALEntry::SetComment() does.  If an archive entry is being read out of an existing archive, the comment stored in its directory entry will be associated with it.  SetComment() deletes the string associated with an old comment, then allocates new space for the new comment.  It then copies the comment into the new space, where the comment has its own private storage.

A sample code piece including SetComment() is shown below.

     ALEntry *entry;

     entry = new ALEntry( list, file, compressor, decompressor );

     entry.SetComment( "Object created by Inspector 7" );

Returns

ALEntry::SetComment() returns AL_SUCCESS if the function was successful.  An error code is returnd if the function was not successful.


SetComment() see also - ALEntry class
See Also

ALEntry::GetComment()


SetComment() example - ALEntry class
See example programs EX04CON.CPP and EX04CON.C.


SetMark() - ALEntry class
ALEntry::SetMark()

see also	example

Mark an archive entry

Synopsis

#include "arclib.h"

 void SetMark()

 void ALEntrySetMark( hALEntry this_object )

 Declare Sub ALEntrySetMark Lib "AL20LW" ( ByVal this_object& )

 procedure ALEntrySetMark( this_object : hALEntry );

Arguments

this_object

Handle to the ALEntry object

Function

ALEntry::SetMark() sets an archive entry as marked.  If it is not marked, the entry will not be used when any of the archive commands such as ALArchive::Create() or ALArchive::Append() are called.

A sample code piece including SetMark() is shown below.

    if ( entry->>mpStorageObject->mName.WildCardMatch( "*.BAK" ) )

        entry.SetMark();

Returns

None


SetMark() see also - ALEntry class
See Also

ALEntry::SetMarkState(), ALEntry::ClearMark()


SetMark() example - ALEntry class
See example programs EX03CON.CPP and EX03CON.C.


SetMarkState() - ALEntry class
ALEntry::SetMarkState()

see also	example

Set mark state for archive entry

Synopsis

#include "arclib.h"

 void SetMarkState( short int new_state )

 void ALEntrySetMarkState( hALEntry this_object, short int new_state )

 Declare Sub ALEntrySetMarkState Lib "AL20LW"( ByVal this_object&, ByVal new_state% )

 procedure ALEntrySetMarkState( this_object : hALEntry; new_state : Integer );

Arguments

this_object

Handle to the ALEntry object

new_state

Indicator for whether the mark is TRUE or FALSE

Function

ALEntry::SetMarkState() sets the mark state of an archive entry as TRUE or FALSE.  If it is FALSE, the entry will not be used when any of the archive commands are called like ALArchive::Create() or ALArchive::Append().

A sample code piece including SetMarkState() is shown below.

    while ( entry ) {

        entry->SetMarkState( rand() & 1 );

        entry = entry->GetNextEntry();

    }

Returns

None


SetMarkState() see also - ALEntry class
See Also

ALEntry::ClearMark(), ALEntry::SetMark()


SetMarkState() example - ALEntry class
See example programs EX16CON.CPP and EX16CON.C.


ALEntryGetCompressor()

see also	example

Return a handle (pointer) to the compressor contained in an ALEntry object

Synopsis

#include "arclib.h"

 hALCompressor ALEntryGetCompressor( hALEntry this_object )

 Declare Function ALEntryGetCompressor Lib "AL20LW" ( ByVal this_object& ) As Long

 function ALEntryGetCompressor( this_object : hALEntry ) : hALCompressor;

C, Visual Basic, and Delphi programmers can access the ALEntry data member mpCompressor using this function.  C++ programmers don't need to call this function since they can access the data member directly.

Arguments

this_object

Handle to the ALEntry object

Functions

ALEntryGetCompressor() returns an hALCompressor handle, which you can use to extract information about a compression engine.  Remember, each ALEntry object contains a pointer to a compression engine; C, Visual Basic, and Delphi programmers must use this function to retrieve that information.

A sample code piece including ALEntryGetCompressor() is shown below.

    hALCompressor engine;

    engine = ALEntryGetCompressor( entry );

Returns

ALEntryGetCompressor() returns one of the following values:

Return Value	Meaning

hALCompressor handle	valid compression engine handle

0 or nil (Delphi)	no engine attached.  If you aren't going to be compressing any objects,, this is a valid state.


ALEntryGetCompressor() see also
See Also

ALEntryGetStorage()


ALEntryGetCompressor() example
See example program EX16DOS.C.


ALEntryGetDecompressor()

see also	example

Return a handle (pointer) to the decompressor contained in an ALEntry object

Synopsis

#include "arclib.h"

 hALDecompressor ALEntryGetDecompressor( hALEntry this_object )

 Declare Function ALEntryGetDecompressor Lib "AL20LW" ( ByVal this_object& ) As Long

 function ALEntryGetDecompressor( this_object : hALEntry ) : hALDecompressor;

Arguments

this_object

A handle for (pointer to) an ALEntry object

Function

This function provides a translation layer for C, Visual Basic, and Delphi to access the C++ data member ALEntry::mpDecompressor.

Like most of the translation functions, this routine checks the arguments for correct type (in debug mode), then casts this_object to the desired class, and gets the data member.  The data member is passed right back to the calling routine after being cast to the appropriate C, Visual Basic, or Delphi type.

Returns

A valid handle for (pointer to) an ALDecompressor object. It is possible to get a return value of 0, since an ALEntry is not required to have a valid ALDecompressor object attached to it.


ALEntryGetDecompressor() see also
See Also

ALEntryGetCompressor()


ALEntryGetDecompressor() example
See example program EX16CON.C.


ALEntryGetStorage()

see also	example

Get information about storage object

Synopsis

#include "arclib.h"

 hALStorage ALEntryGetStorage( hALEntry this_object )

 Declare Function ALEntryGetStorage Lib "AL20LW" ( ByVal this_object& ) As Long

 function ALEntryGetStorage( this_object : hALEntry ) : hALStorage;

C, Visual Basic, and Delphi programmers can access the ALEntry data member mpStorageObject using this function.  C++ programmers don't need to call this function since they can access the data member directly.

Arguments

this_object

Handle to the ALEntry object

Functions

ALEntryGetStorage() returns an hALStorage handle, which you can use to extract information about a storage object, such as the object name.  Remember, each ALEntry object contains a pointer to a storage object; C, Visual Basic, and Delphi programmers must use this function to retrieve that information.

A sample code piece including ALEntryGetStorage() is shown below.

    hALStorage storage;

    char *name;

     storage = ALEntryGetStorage( entry );

     name = ALStorageGetName( storage );

Returns

ALEntryGetStorage() returns one of the following values:

Return Value	Meaning

hALStorage handle	valid storage object handle

0 or nil (Delphi)	cannot locate storage object.  This is due to an error of some kind when initially creating the storage object.


ALEntryGetStorage() see also
See Also

ALEntryGetCompressor(), ALEntryGetDecompressor()


ALEntryGetStorage() example
See example programs EX04CON.C, EX04WIN.C, EX04VB.FRM, and EX04UNIT.PAS.


ALEntrySetCompressor()

see also	example

Set the compressor object in an ALEntry object

Synopsis

#include "arclib.h"

 void ALEntrySetCompressor( hALEntry this_object, hALCompressor compressor )

 Declare Sub ALEntrySetCompressor Lib "AL20LW" ( ByVal this_object&, ByVal compressor& )

 procedure ALEntrySetCompressor( this_object : hALEntry; compressor : hALCompressor );

C, Visual Basic, and Delphi programmers can access the ALEntry data member mpCompressor using this function.  C++ programmers don't need to call this function since they can access the data member directly.

Arguments

this_object

Handle to the ALEntry object

compressor

A handle for (pointer to) an ALCompressor that will now be attached to the ALEntry object.   A value of 0 is acceptable.

Functions

ALEntrySetCompressor() modifies or reassigns a compression engine to an archive entry.  Remember, each ALEntry object contains a pointer to a compression engine; C, Visual Basic, and Delphi programmers must use this function to change that information.

When you assign a new engine object to a given archive entry, you must destroy the old object, since the ALEntryList destructor will no longer find a copy of that pointer.  Additionally, you should understand that the object you are assigning as the new storage object will be destroyed by the ALEntryList destructor when it is called.

A sample piece of code including ALEntrySetCompressor() is shown below.

if( stricmp( ext, "ZIP" )==0 ){

   hComp=newALCopyCompressor();

   ALEntrySetCompressor( entry, hComp );

}

Returns

None


ALEntrySetCompressor() see also
See Also

ALEntryGetCompressor(), ALEntrySetStorage()


ALEntrySetCompressor() example
See example programs EX14WIN.C, EX16CON.C, EX14VB.FRM, and EX14UNIT.PAS.


ALEntrySetDecompressor()

see also	example

Set the decompressor object in an ALEntry object

Synopsis

#include "arclib.h"

 void ALEntrySetDecompressor( hALEntry this_object, hALDecompressor decompressor )

 Declare Sub ALEntrySetDecompressor Lib "AL20LW" ( ByVal this_object&, ByVal decompressor& )

 procedure ALEntrySetDecompressor( this_object : hALEntry; decompressor : hALDecompressor );

Arguments

this_object

A handle for (pointer to) an ALEntry object

decompressor

A handle for (pointer to) an ALDecompressor that will now be attached to the ALEntry object.  A value of 0 (or nil for Delphi) is acceptable.

Function

This function provides a translation layer for C, Visual Basic, and Delphi to set the C++ data member ALEntry::mpDecompressor to the desired decompression engine.

Like most of the translation functions, this routine checks the arguments for correct type (in debug mode), then casts this_object to the desired class, and changes the data member.

A sample piece of code including ALEntrySetDecompressor() is shown below.

if( my_engine ){

   hEngine=ALEntryGetDecompressor( entry )

   ALEntrySetDecompressor( entry, 0 );

}

Returns

None


ALEntrySetDecompressor() see also
See Also

ALEntrySetCompressor()


ALEntrySetDecompressor() example
See example program EX14VB.FRM.


ALEntrySetStorage()

see also	example

Modify pointer to storage object

Synopsis

#include "arclib.h"

 void ALEntrySetStorage( hALEntry this_object, hALStorage storage )

 Declare Sub ALEntrySetStorage Lib "AL20LW" ( ByVal this_object&, ByVal storage& )

 procedure ALEntrySetStorage( this_object : hALEntry; storage : hALStorage );

C, Visual Basic, and Delphi programmers can access the ALEntry data member mpStorageObject using this function.  C++ programmers don't need to call this function since they can access the data member directly.

Arguments

this_object

Handle to the ALEntry object

storage

Storage object

Functions

ALEntrySetStorage() reassigns a storage object to an archive entry.  Remember, each ALEntry object contains a pointer to a storage object; C, Visual Basic, and Delphi programmers must use this function to change that information.

When you assign a new storage object to a given archive entry, you must destroy the old object, since the ALEntryList destructor will no longer find a copy of that pointer.  Additionally, you should understand that the object you are assigning as the new storage object will be destroyed by the ALEntryList destructor when it is called.

A sample code piece including ALEntrySetStorage(), is shown below.

    char file_name[ 128 ];

    hALStorage file;

    file = ALEntryGetStorage( job );

    strcpy( file_name, ALStorageGetName( file ) );

    deleteALStorage( file );

    ALEntrySetStorage( job, newALMemory(file_name, 0, 0) );

Returns

None


ALEntrySetStorage() see also
See Also

ALEntryGetStorage(), ALEntrySetCompressor(), ALEntrySetDecompressor()


ALEntrySetStorage() example
See example programs EX04WIN.C, EX04VB.FRM, and EX04UNIT.PAS.


ALEntryList()
ALEntryList::ALEntryList()

see also	example

Constructor for ALEntryList class

Synopsis

#include "arclib.h"

 ALEntryList::ALEntryList( ALMonitor * monitor = 0, ALToolKit toolkit = FullTools() )

Arguments

monitor

ALMonitor object.  For C++, the default is a "do-nothing" monitor assigned by this constructor.

toolkit

The toolkit is a collection of storage objects, compressors, and decompressors.  This toolkit is used whenever the archiving software needs to create one of the three types of objects.  The components you put in your toolkit will determine what sort of compression and storage your archives will use.  For more information, see the section about ALToolKits discussed in the ArchiveLib Reference Manual.

Function

This is the only constructor defined for the ALEntryList class.  This constructor simply creates the list head and initializes mStatus.  If a monitor is not passed as an argument, the default is a "do-nothing" monitor assigned by this constructor.

A sample code piece including the ALEntryList() constructor, is shown below.

    ALBarGraphMonitor monitor( AL_MONITOR_OBJECTS, cout );

    ALEntryList list( &monitor );

Returns

N/A


ALEntryList() see also
See Also

ALEntry::ALEntry(), ALEntryList::~ALEntryList()


ALEntryList() example
See example programs EX00CON.CPP, EX00WIN.CPP, and EX02PM.CPP.


~ALEntryList()
ALEntryList::~ALEntryList()

see also	example

Destructor for ALEntryList class

Synopsis

#include "arclib.h"

 ALEntryList::~ALEntryList()

 void deleteALEntryList( hALEntryList this_object )

 Declare Sub deleteALEntryList Lib "AL20LW" ( ByVal this_object& )

 procedure deleteALEntryList( this_object : hALEntryList );

Arguments

this_object

Handle to the ALEntryList object

Function

ALEntryList::~ALEntryList() is the destructor for the ALEntryList class.  This destructor is very powerful because it works through the entire list, deleting every list entry, before exiting.  The ALEntry destructor in turn calls the destructors for the associated storage objects and compression engines.

A sample code piece including ~ALEntryList(), is shown below.

    ALEntryList *list = new ALEntryList( monitor );

    archive.AddWildCardFiles( *list, "*.*", 1 );

    archive.Append( *list );

    delete list;

Returns

N/A


~ALEntryList() see also
See Also

ALEntry::~ALEntry(), ALEntryList::ALEntryList()


~ALEntryList() example
See example programs EX09CON.CPP, EX17PM.CPP, EX17WIN.CPP, EX00WIN.C, EX16CON.C, EX00VB.FRM, and EX00UNIT.PAS.


AddWildCardFiles() - ALEntryList class
ALEntryList::AddWildCardFiles()

see also	example

Adds file names to an existing entry list

Synopsis

#include "arclib.h"

 int ALEntryList::AddWildCardFiles( const char *pattern = "*.*", int traverse_flag = 0  );

 int ALEntryListAddWildCardFiles( hALEntryList this_object, char *pattern, int traverse_flag );

 Declare Function ALEntryListAddWildCardFiles Lib "AL20LW" ( ByVal this_object&, ByVal pattern$, ByVal traverse_flag% ) As Integer

 function ALEntryListAddWildCardFiles( this_object : hALEntryList; pattern : String; traverse_flag : Integer ) : Integer;

Arguments

this_object

This identifies the list which will have a list of new wild card items added to it.  C++ doesn't have this parameter, since AddWildCardFiles is a member function of ALEntryList, and therefore gets an implicit pointer to the object in question.

pattern

A pointer to a C-style null terminated string.  This string contains a wild card pattern that will be expanded into a list of file names.  Note that the wild card expansion is done by the host operating system, so specific wild card characters and expansion rules will vary.  Under C++, this argument defaults to "*.*".

traverse_flag

This integer should be set to 0 if you don't want to search all subdirectories under the current one.  Set it to a non-zero value and the wild card expansion will expand the wild card pattern in every directory it can find under the current directory.  Under C++, this argument has a default value of 0.

Function

This function expands a wild card file specification into a batch of new entries for the list.  The expansion part uses the ALWildCardExpander class to do all the work.  The expander class expands the file spec as requested, and repeatedly returns names.

This function then takes those names and turns them into list entries.  This is accomplished by asking the toolkit to create the storage object, compression engine, and decompression engine.  Since the toolkit is supplied by the user when the entry list is created, this puts the type of entries added to the list under programmer control, not library control.

This function will also add duplicate objects to a list.  If you perform multiple updates on a list, it is probably a good idea to scan for and delete duplicates afterwards.

A sample piece of code including AddWildCardFiles() is shown below.

list.AddWildCardFiles( "*,*" );

list.UnMarkDuplicates();

list.ClearError();

archive.Append();

Returns

unconditionally returns an integer indicating how many entries were added to the list.


AddWildCardFiles() see also - ALEntryList class
See Also

ALEntryList::MakeEntriesFromListBox()


AddWildCardFiles() example - ALEntryList class
See example program EX00PM.CPP, EX00WIN.CPP, EX02CON.CPP, EX00CON.C, EX00WIN.C, EX00VB.FRM, and EX00UNIT.PAS.


ClearError() - ALEntryList class
ALEntryList::ClearError()

see also	example

Reset the error status for an entry list

Synopsis

#include "arclib.h"

 void ALEntryList::ClearError()

 void ALEntryListClearError( hALEntryList this_object )

 Declare Sub ALEntryListClearError Lib "AL20LW" ( ByVal this_object& )

 procedure ALEntryListClearError( this_object : hALEntryList )

Arguments

this_object

A reference or pointer to the ALEntryList object that is going to have its status reset.  Note that the C++ version of this call doesn't have an explicit argument here, since it has access to this implicitly.

Function

An ALEntryList object carries a status object in its mStatus member.  It is possible for this member to be set to an error condition.  Error conditions are not cleared automatically by the library, so the user will have to manually clear it with a call to this function.  This function will normally be implemented as an inline function.

A sample piece of code including ClearError() is shown below.

list.AddWildCardFiles( "*,*" );

list.UnMarkDuplicates();

list.ClearError();

archive.Append();

Returns

None


ClearError() see also - ALEntryList class
See Also

ALEntryListGetStatusCode()


ClearError() example - ALEntryList class
See example program EX03MFC.CPP.


ClearMarks() - ALEntryList class
ALEntryList::ClearMarks()

see also	example

Clear marks on specified objects

Synopsis

#include "arclib.h"

 int ClearMarks( const char *pattern )

 int ALEntryListClearMarks( hALEntryList this_object, char *pattern )

 Declare Function ALEntryListClearMarks Lib "AL20LW" ( ByVal this_object&, ByVal pattern$ ) As Integer

 function ALEntryListClearMarks( this_object : hALEntryList; pattern : String ) : Integer;

Arguments

this_object

Handle to the ALEntryList object

pattern

Name of the storage object(s) whose marks are to be cleared (for C++ and C, this is a pointer to such a storage object).  For C++, 0 is the default (marks should be cleared from all entries).

There are no default parameter values for C, Visual Basic, and Delphi.

Function

ALEntryList::ClearMarks() goes through an archive entry list, checking each entry for a wildcard match against the specified name.  Every entry whose storage object matches the name will have its mark cleared.  If 0 (or no name) is specified, marks will be cleared from all entries.

A sample code piece including ClearMarks() is shown below.

    ALEntryList list( &monitor);

    archive.miAddWildCardFiles( list, "*.*" );

    list.ClearMarks( "*.BAK" );

Returns

ALEntryList::ClearMarks() returns one of the following values:

Return Value	Meaning

>= 0	number of entries cleared

< 0	error occurred.  See mStatus for a detailed list of errors.


ClearMarks() see also - ALEntryList class
See Also

ALEntry::ClearMark()


ClearMarks() example - ALEntryList class
See example programs EX02CON.CPP, EX02PM.CPP, EX02WIN.CPP, EX02WIN.C, EX03CON.C, EX02VB.FRM, and EX02UNIT.PAS.


DeleteUnmarked() - ALEntryList class
ALEntryList::DeleteUnmarked()

see also	example

Delete unmarked entries in archive entry list

Synopsis

#include "arclib.h"

 int ALEntryList::DeleteUnmarked()

 int ALEntryListDeleteUnmarked( hALEntryList this_object )

 Declare Function ALEntryListDeleteUnmarked Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALEntryListDeleteUnmarked( this_object : hALEntryList ) : Integer;

Arguments

this_object

Handle to the ALEntryList object

Function

ALEntryList::DeleteUnmarked() deletes all entries in an archive entry list that do not have their marks set.  This cleans up the archive entry list and frees up some storage space.

This function calls the destructor and the item is removed from the list.  It does not delete a file.

A sample code piece including DeleteUnmarked(), is shown below.

    list.ClearMarks( "*.BAK" );

    list.DeleteUnmarked();

Returns

ALEntryList::DeleteUnmarked() returns one of the following values:

Return Value	Meaning

> = 0	number of entries deleted

< 0	error occurred.  See mStatus for a detailed list of errors.


DeleteUnmarked() see also - ALEntryList class
See Also

ALEntry::ClearMark(), ALEntryList::ClearMarks()


DeleteUnmarked() example - ALEntryList class
See example programs EX09CON.CPP, EX17PM.CPP, EX17WIN.CPP, EX17WIN.C, EX17VB.FRM, and EX17UNIT.PAS.


FillListBox() - ALEntryList class
ALEntryList::FillListBox()

see also	example

Insert storage object names into a list box control

Synopsis

#include "arclib.h"

 int FillListBox( HWND hDlg, int list_box_id = -1 );

 int ALEntryListFillListBox( hALEntryList this_object, HWND hDlg, int list_box_id );

 Declare Function ALEntryListFillListBox Lib "AL20LW" (ByVal this_object&, ByVal hDlg%, ByVal list_box_id% ) as Integer

 function ALEntryListFillListBox( this_object : hALEntryList;  hDlg : HDlg; list_box_id : Integer ) : Integer;

Arguments

this_object

A reference or pointer to the ALEntryList object which will supply all the entry names that are going to be displayed in the list box.

hDlg

This argument is a window handle.  If the next parameter, list_box_id, is set to -1, it means this is the handle of the list box.  If list_box_id is not -1, it means this argument is the window handle of a dialog box that contains the list box.

list_box_id

The ID of the list box.  If set to -1, it means the list box is not in a dialog box, and the hDlg parameter is the actual handle of the list box.

Function

ALEntryList::FillListBox() resets the list box so its existing contents are deleted.  It then inserts the names of all of the objects in the entry list into a Windows or Presentation Manager list box, ignoring unmarked entries.

A sample code piece including FillListBox() is shown below.

ALEntryList list;

ALGlArchive arc( "DOS00.GAL" );

arc.ReadDirectory( list );

list.FillListBox( window, LIST_BOX );

Returns

ALEntryList::FillListBox() returns one of the following values:

Return Value	Meaning

> = 0	number of entries inserted into list box

< 0	error occurred.


FillListBox() see also - ALEntryList class
See Also

ALArchive::FillListBox()


FillListBox() example - ALEntryList class
See example program EX17PM.CPP, EX17WIN.CPP, EX17WIN.C, EX17VB.FRM, and EX17UNIT.PAS.


GetFirstEntry() - ALEntryList class
ALEntryList::GetFirstEntry()

see also	example

Proceed to first archive entry

Synopsis

#include "arclib.h"

 ALEntry * ALEntryList::GetFirstEntry()

 hALEntry ALEntryListGetFirstEntry( hALEntryList this_object )

 Declare Function ALEntryListGetFirstEntry Lib "AL20LW" ( ByVal this_object& ) As Long

 function ALEntryListGetFirstEntry( this_object : hALEntryList ) : hALEntry;

Arguments

this_object

Handle to the ALEntryList object

Function

ALEntryList::GetFirstEntry() is used in conjunction with the ALEntry::GetNextEntry() to iterate through an ALEntryList.

Navigation of an entry list requires a "get first/get next" loop; this function is the "get first" portion of that loop.

A sample code piece including GetFirstEntry() is shown below.

    ALEntry *entry = list.GetFirstEntry();

    while ( entry ) {

        cout << entry->>mpStorageObject->mName << "\n";

        entry = entry->GetNextEntry();

    }

Returns

ALEntryList::GetFirstEntry() returns one of the following values:

Return Value	Meaning

 pointer/handle to ALEntry	first entry found

0	no members found in list


GetFirstEntry() see also - ALEntryList class
See Also

ALEntry::GetNextEntry()


GetFirstEntry() example - ALEntryList class
See example programs EX03CON.CPP, EX04PM.CPP, EX04WIN.CPP, EX03CON.C, EX04WIN.C, and EX04VB.FRM.


MakeEntriesFromListBox() - ALEntryList class
ALEntryList::MakeEntriesFromListBox()

see also	example

Create new entries in a list based on selected items in a list box

Synopsis

#include "arclib.h"

 int ALEntryList::MakeEntriesFromListBox( HWND hDlg, int list_box_id = -1 )

 int ALEntryListMakeEntriesFromListBox( hALEntryList this_object, HWND hDlg, int list_box_id )

 Declare Function ALEntryListMakeEntriesFromListBox Lib "AL20LW" ( ByVal this_object&, ByVal hDlg%, ByVal list_box_id% ) As Integer

 function ALEntryListMakeEntriesFromListBox( this_object : hALEntryList; hDlg : HWnd; list_box_id : Integer );

Arguments

this_object

A reference or pointer to the ALEntryList object which will have new entries added.  The C++ member function version of this call doesn't have an explicit argument here, since it has access to this implicitly.

hDlg

This argument is a window handle.  If the next parameter, list_box_id, is set to -1, it means this is the handle of the list box.  If list_box_id is not -1, it means this argument is the window handle of a dialog box that contains the list box.

list_box_id

The ID of the list box.  If set to -1, it means the list box is not in a dialog box, and the hDlg parameter is the actual handle of the list box.

Function

This function goes through a list box, and picks out all the highlighted entries.  It creates a new ALEntry object for each of the marked entries, using the storage objects and engines that are present in the toolkit owned by this ALEntryList.

A sample piece of code including MakeEntriesFromListBox() is shown below.

case AL_EXPAND:

     list.MakeEntriesFromListBox( hDlg, IDC_FILES );

     break;

Returns

MakeEntriesFromListBox() returns the number of new entries created from the list box.


MakeEntriesFromListBox() see also - ALEntryList class
See Also

ALEntryList::FillListBox()


MakeEntriesFromListBox() example - ALEntryList class
See example programs EX04WIN.CPP, EX01PM.CPP, EX01WIN.C, EX01WIN.CPP, EX01VB.FRM, and EX04UNIT.PAS.


SetMarks() - ALEntryList class
ALEntryList::SetMarks()

see also	example

Set archive entries in list as marked

Synopsis

#include "arclib.h"

 int SetMarks( const char *pattern = 0 )

 int ALEntryListSetMarks( hALEntryList this_object, char *pattern )

 Declare Function ALEntryListSetMarks Lib "AL20LW" ( ByVal this_object&, ByVal pattern$ ) As Integer

 function ALEntryListSetMarks( this_object : hALEntryList; pattern : String ) : Integer;

Arguments

this_object

Handle to the ALEntryList object

pattern

Name of the storage object to be marked (for C++ and C, this is a pointer to the storage object name).  For C++, 0 is the default (marks should be set on all entries).

There are no default parameter values for C, Visual Basic, and Delphi.

Function

ALEntryList::SetMarks() goes through an archive entry list, checking each entry for a wildcard match against the specified name.  Every entry whose object matches the name will have its mark set.  If 0 (or no name) is specified, SetMarks() sets marks on all entries.

A sample code piece including SetMarks() is shown below.

    ALEntryList list( &monitor);

    list.AddWildCardFiles( "*.*" );

    list.SetMarks( "*.CPP" );

Returns

ALEntryList::SetMarks() returns one of the following values:

Return Value	Meaning

> = 0	number of entries marked

< 0	error occurred


SetMarks() see also - ALEntryList class
See Also

ALEntry::SetMark()


SetMarks() example - ALEntryList class
See example program EX09CON.CPP.


SetMarksFromListBox() - ALEntryList class
ALEntryList::SetMarksFromListBox()

see also	example

Set marks from list box selections

Synopsis

#include "arclib.h"

 ALEntryListSetMarksFromListBox( hALEntryList this_object, HWND hDlg, int list_box_id )

 int ALEntryListSetMarksFromListBox( hALEntryList this_object, HWND hDlg, int list_box_id );

 Declare Function ALEntryListSetMarksFromListBox Lib "AL20LW" ( ByVal this_object&, ByVal hDlg%, ByVal list_box_id% ) As Integer

 function ALEntryListSetMarksFromListBox( this_object : hALEntryList; hDlg : HWnd; list_box_id : Integer ) : Integer;

Arguments

this_object

A reference or pointer to the ALEntryList object which will have new entries added.  The C++ member function version of this call doesn't have an explicit argument here, since it has access to this implicitly.

hDlg

This argument is a window handle.  If the next parameter, list_box_id, is set to -1, it means this is the handle of the list box.  If list_box_id is not -1, it means this argument is the window handle of a dialog box that contains the list box.

list_box_id

The ID of the list box.  If set to -1, it means the list box is not in a dialog box, and the hDlg parameter is the actual handle of the list box.

 Function

ALEntryList::SetMarksFromListBox() lets you set marks on entries in an archive entry list from a Windows or OS/2 Presentation Manager list box.  It finds each name in the list box that has been selected, and sets the corresponding mark in the archive entry list.

A sample code piece including SetMarksFromListBox() is shown below.

    ALEntryList list( &monitor );

    pArchive->ReadDirectory( list );

    list.ClearMarks();

    int count = list.SetMarksFromListBox( hWnd );

Returns

ALEntryList::SetMarksFromListBox() returns one of the following values:

Return Value	Meaning

> = 0	number of entries set

< 0	error occurred


SetMarksFromListBox() see also - ALEntryList class
See Also

ALEntryList::SetMarks()


SetMarksFromListBox() example - ALEntryList class
See example programs EX02PM.CPP, EX02WIN.CPP, EX02WIN.C, EX02VB.FRM, and EX02UNIT.PAS.


ToggleMarks() - ALEntryList class
ALEntryList::ToggleMarks()

see also	example

Invert marks set in list

Synopsis

#include "arclib.h"

 int ALEntryList::ToggleMarks()

 int ALEntryListToggleMarks( hALEntryList this_object )

 Declare Function ALEntryListToggleMarks Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALEntryListToggleMarks( this_object : hALEntryList ) : Integer;

Arguments

this_object

Handle to the ALEntryList object

Function

ALEntryList::ToggleMarks() simply inverts marks set in an archive entry list.  All marked entries will be unmarked, and all unmarked entries will be marked.

A sample piece of code including ToggleMarks() is shown below.

list.UnmarkDuplicates();

list.ToggleMarks();

archive.Delete( list, output );

Returns

ALEntryList::ToggleMarks() returns one of the following values:

Return Value	Meaning

> = 0	number of marks removed or set in the list

< 0	error occurred


ToggleMarks() see also - ALEntryList class
See Also

ALEntryList::ClearMarks(), ALEntryList::SetMarks()


ToggleMarks() example - ALEntryList class
See example program EX09CON.CPP.


UnmarkDuplicates() - ALEntryList class
ALEntryList::UnmarkDuplicates()

see also	example

Unmark all duplicates in an archive entry list

Synopsis

#include "archlib.h"

 void UnmarkDuplicates( ALEntryList &list, const char *error_message = 0 )

 void ALEntryListUnmarkDuplicates( hALEntryList this_object, hALEntryList list, char *error_message )

 Declare Sub ALEntryListUnmarkDuplicates Lib"AL20LW" ( ByVal this_object&, ByVal list&, ByVal error_message& )

 procedure ALEntryListUnmarkDuplicates( this_object : hALEntryList; list : hALEntryList; error_message : String );

Arguments

this_object

Handle to the ALEntryList object

list

Name of list in which to unmark duplicates

error_message

Error message to pass to archive

Function

ALEntryList::UnmarkDuplicates() lets you unmark all the duplicates in an archive entry list.  This function is provided mostly for use by the archive functions.  In a given list, every item is checked against itself or an entry in a different list.

UnmarkDuplicates() can work in two different ways:

•	If you don't pass an error message, it just clears the marks of all the duplicates.

•	If you pass an error string, it will not only clear the marks of the duplicates, but it will also set the error status in their associated storage objects.

A sample piece of code including UnmarkDuplicates() is shown below.

list.UnmarkDuplicates();

list.ToggleMarks();

archive.Delete( list, output );

Returns

None


UnmarkDuplicates() see also - ALEntryList class
See Also

ALEntryList::ClearMarks()


UnmarkDuplicates() example - ALEntryList class
See example programs EX17PM.CPP, EX17WIN.CPP, EX20CON.CPP, EX17WIN.C, EX17VB.FRM, and EX17UNIT.PAS.


ALEntryListGetStatusCode()

see also	example

Get status of ALEntryList object

Synopsis

#include "arclib.h"

 int ALEntryListGetStatusCode( hALEntryList this_object )

 Declare Function ALEntryListGetStatusCode Lib"AL20LW" ( ByVal this_object& ) As Integer

 function ALEntryListGetStatusCode( this_object : hALEntryList ) : Integer;

C, Visual Basic, and Delphi programmers can access the ALEntryList data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALEntryList object

Functions

ALEntryListGetStatusCode() returns a status value of an ALEntryList object.  ArchiveLib provides access functions for objects that have mStatus members, including ALEntryList, ALCompressor, ALDecompressor, and ALStorage.  Status members contain an integer indicating the current status of an object.  ALEntryListGetStatusCode() retrieves that status value.

A sample code piece including ALEntryListGetStatusCode(), is shown below:

    if ( ALEntryListGetStatusCode( object ) < AL_SUCCESS )

        printf( "Error, prepare to reboot..." );

Returns

ALEntryListGetStatusCode() returns the integer value of the error code.


ALEntryListGetStatusCode() see also
See Also

ALEntryListGetStatusDetail(), ALEntryListGetStatusString()


ALEntryListGetStatusCode() example
See example programs EX16CON.C.


ALEntryListGetStatusDetail()

see also	example

Get detailed error information

Synopsis

#include "arclib.h"

 char *ALEntryListGetStatusDetail( hALEntryList this_object )

 Declare Function ALEntryListGetStatusDetail Lib "AL20LW" ( ByVal this_object& ) As String

 function ALEntryListGetStatusDetail( this_object : hALEntryList ) : String;

C, Visual Basic, and Delphi programmers can access the ALEntryList data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALEntryList object

Function

ALEntryListGetStatusDetail() returns detailed information about a specific error message associated with ALEntryList.  ArchiveLib provides access functions for objects that have mStatus members, including ALStorage, ALCompressor, ALDecompressor, and ALEntryList.  The detailed message produced by this function includes various data items that might help track down the source of the problem.  These messages are fairly technical, and are intended for use by developers only instead of end-users.

A sample piece of code including ALEntryListGetStatusDetail() is shown below.

char*p

p=ALEntryListGetStatusDetail( list );

SetDlgItemText( hDlg, ID_STATUS, p );

Returns

ALEntryListGetStatusDetail() returns a string with a detailed description of the error message.


ALEntryListGetStatusDetail() see also
See Also

ALEntryListGetStatusCode(), ALEntryListGetStatusString()


ALEntryListGetStatusDetail() example
See example programs EX16CON.C.


ALEntryListGetStatusString()

see also	example

Translate error into code string

Synopsis

#include "arclib.h"

 char *ALEntryListGetStatusString( hALEntryList this_object )

 Declare Function ALEntryListGetStatusString Lib "AL20LW" ( ByVal this_object& ) As String

 function ALEntryListGetStatusString( this_object : hALEntryList ) : String;

C, Visual Basic, and Delphi programmers can access the ALEntryList data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALEntryList object

Function

ALEntryListGetStatusString() translates an error code in an ALEntryList object to a short text string.  ArchiveLib provides access functions for objects that have mStatus members, including ALStorage, ALCompressor, ALDecompressor, and ALEntryList.  When displaying error values to users, the string returned by this function will be much more intelligible than displaying the integer value of the error.

A few sample error code translations include the following:

     AL_SUCCESS	"Success"

     AL_END_OF_FILE	"End of file"

     AL_CANT_OPEN_BUFFER	"Can't allocate buffer"

Returns

ALEntryListGetStatusString() returns a string with a brief description of the error message.


ALEntryListGetStatusString() see also
See Also

ALEntryListGetStatusDetail()


ALEntryListGetStatusString() example
See example programs EX16CON.C.


CopyTools()

see also	example

Create a toolkit with just the Copy engine and standard storage objects

Synopsis

#include "arclib.h"

 ALToolKit CopyTools()

Arguments

None

Function

CopyTools() creates a toolkit that can build ALFile and ALMemory objects, but only contains the ALCopyCompressor and ALCopyDecompressor engines.

A sample piece of code including CopyTools() is shown below.

ALToolKit tk=ALGlCompressor() + CopyTools();

ALBarGraph monitor,

ALEntryList list( monitor, tk );

Returns

A new toolkit.

This doesn't return a pointer, but rather a new toolkit.  Usually this is passed to the ALEntryList constructor.


CopyTools() see also
See Also

FullTools(), GlTools(), newALListCopyTools()


CopyTools() example
See example programs EX05CON.C, EX14WIN.C, and EX14VB.FRM.


FullTools()

see also	example

Create a toolkit with everything in it

Synopsis

#include "arclib.h"

 ALToolKit FullTools()

Arguments

None.

Function

FullTools() creates a toolkit that can build Greenleaf compressors, decompressors, copy compressors, or copy decompressors.  It can also build ALFile, ALMemory, or ALWinMemory objects.  If you are going to be extracting from archives, and you aren't sure what toolkit to use, this is a good choice.

This toolkit creates Greenleaf engines by default with functions such as AddWildCardFiles() or MakeEntriesFromListBox().  If you are going to be creating PKZIP compatible archives, use PkTools() instead.

A sample piece of code including FullTools() is shown below.

ALEntryList list( monitor, FullTools() );

list.AddWildCardFiles( "*.C??", 1 );

Returns

A new toolkit.

This doesn't return a pointer, but rather a new toolkit.  Usually this is copied into an existing toolkit.


FullTools() see also
See Also

PkTools(), GlTools()


FullTools() example
See example program EX15PM.CPP.


GlCompressFileTools()

see also	example

Create a toolkit that supports Greenleaf compressors and ALFile objects

Synopsis

#include "arclib.h"

 ALToolKit GlCompressFileTools( short int compression_level = AL_GL_DEFAULT_LEVEL )

Arguments

compression_level

An integer value somewhere between AL_GREENLEAF_COPY and AL_GREENLEAF_LEVEL_4.  AL_GREENLEAF_LEVEL_0 through AL_GREENLEAF_LEVEL_4 all perform compression at varying levels, using varying amounts of memory.

Function

GlCompressFileTools() creates a toolkit that can build Greenleaf compressors and file objects.  If your application is only going to be compressing files, you can use this toolkit to initialize your ALEntryList, and avoid linking in support for ALMemory objects, decompressors, etc.

A sample piece of code including GlCompressFileTools() is shown below.

ALEntryList( monitor, GlCompressFileTools() );

list.MakeEntriesFromListBox( hDlg, ID_FILES );

archive.Create( list );

Returns

A new toolkit.

This is not a reference or a pointer, so you should use this as part of an assignment statement, or as an argument to a constructor.


GlCompressFileTools() see also
See Also

GlDecompressFileTools(), GlTools()


GlCompressFileTools() example
See example program EX02CON.C.


GlCompressTools()

see also	example

Create a toolkit that supports Greenleaf compressors

Synopsis

#include "arclib.h"

 ALToolKit GlCompressTools( short int compression_level = AL_GL_DEFAULT_LEVEL )

Arguments

compression_level

An integer value somewhere between AL_GREENLEAF_COPY and AL_GREENLEAF_LEVEL_4.  AL_GREENLEAF_LEVEL_0 through AL_GREENLEAF_LEVEL_4 all perform compression at varying levels, using varying amounts of memory.

Function

GlCompressTools() creates a toolkit that can build Greenleaf compressors.  If your application is only going to be compressing objects (and not decompressing), you can use the toolkit returned by this function in your ALEntryList, and avoid linking in support for all decompressors.

This toolkit will clone ALFile and either ALMemory or ALWinMemory objects.  If you only want to use ALFile objects, use GLCompressFileTools().

A sample piece of code including GlCompressTools() is shown below.

ALEntryList list( monitor, GLCompressTools() );

list.AddWildCardFiles( "*.*" );

Returns

A new toolkit.


GlCompressTools() see also
See Also

GlCompressFileTools(), GlTools()


GlCompressTools() example
See example programs EX00PM.CPP and EX22CON.CPP.


GlDecompressFileTools()

see also	example

Create a toolkit that supports Greenleaf decompressors and ALFile objects

Synopsis

#include "arclib.h"

 ALToolKit GlDecompressFileTools()

Arguments

None

Function

GlDecompressFileTools() creates a toolkit that can build Greenleaf decompressors and file objects.  If your application is only going to be decompressing files, you can use this toolkit to initialize your ALEntryList, and avoid linking in support for ALMemory objects, compressors, etc.

A sample piece of code including GlDecompressFileTools() is shown below.

ALEntryList( monitor, GLDecompressFileTools() );

ALGlArchive arc( "DOS00.GAL" );

arc.ReadDirectory( list );

arc.Extract( list );

Returns

A new toolkit.


GlDecompressFileTools() see also
See Also

GlTools(), GlCompressTools()


GlDecompressFileTools() example
See example program EX07CON.C.


GlDecompressTools()

see also	example

Create a toolkit that supports Greenleaf decompressors

Synopsis

#include "arclib.h"

 ALToolKit GlDecompressTools()

Arguments

None.

Function

GlDecompressTools() creates a toolkit that can build Greenleaf decompressors, ALFile objects, and either ALMemory or ALWinMemory objects.  If your application is only going to be decompressing some type of objects, you can use the toolkit returned by this function in your ALEntryList, and avoid linking in support for compression objects.

This toolkit will clone ALFile and either ALMemory or ALWinMemory objects.  If you don't want to support memory based objects, use GlDecompressFileTools().

A sample piece of code including GlDecompressTools() is shown below.

ALEntryList list( monitor, GlDecompressTools() );

archive.ReadDirectory( list );

archive.Extract( list );

Returns

A new toolkit.


GlDecompressTools() see also
See Also

GlTools(), GlDecompressFileTools()


GlDecompressTools() example
See example program EX03CON.CPP.


GlTools()

see also	example

Create a toolkit with everything but PK compression/decompression

Synopsis

#include "arclib.h"

 ALToolKit GlTools( short int compression_level = AL_GL_DEFAULT_LEVEL )

Arguments

compression_level

An integer value somewhere between AL_GREENLEAF_COPY and AL_GREENLEAF_LEVEL_4.  AL_GREENLEAF_LEVEL_0 through AL_GREENLEAF_LEVEL_4 all perform compression at varying levels, using varying amounts of memory.  16-bit libraries have a default value of AL_GREENLEAF_LEVEL_2.  32-bit libraries use AL_GREENLEAF_LEVEL_4 as the default level.

Function

GlTools() creates a toolkit that can build the Greenleaf compressors and decompressors, as well as ALFile and either ALMemory or ALWinMemory storage objects.

A sample piece of code including GlTools() is shown below.

ALEntryList list( monitor, GlTools() );

list.AddWildCardFiles( "*.*" );

Returns

A new toolkit.


GlTools() see also
See Also

FullTools()


GlTools() example
See example programs EX00WIN.CPP and EX01PM.CPP.


PkCompressFileTools()

see also	example

Create a toolkit that supports PKWare compressors

Synopsis

#include "arclib.h"

 ALToolKit PkCompressFileTools( int level = 6, int window_bits = 13, int mem_level = 6 )

Arguments

level

A number between 1 and 9.  1 gives the best speed, 9 gives the best compression.  The default 6 for all programs.

window_bits

The base 2 logarithm of the number of bytes in the history buffer.  Values between 8 and 15 are legal.  The more bits, the more memory.  For 16-bit programs, the default is 13.  For 32-bit programs, the default is 15.

mem_level

How much memory should be allocated for the internal compression state.  mem_level=1 uses minimum memory but has the worst compression ratio; mem_level=9 uses maximum memory for optimal speed.  For 16-bit programs, the default is 6.  For 32-bit programs, the default is 8.

Function

PkCompressFileTools() creates a toolkit that can build PKWare objects.  If your application is only going to be compressing ALFiles using PKWare, you can use this function to initialize your ALEntryList, and avoid linking in support for PKWare decompressors, Greenleaf compressors, Greenleaf decompressors, and either ALMemory or ALWinMemory  objects.

A sample piece of code including PkCompressFileTools() is shown below.

ALEntryList list( monitor, PkCompressFileTools() );

ALPkArchive arc( "DOUG.ZIP" );

list.MakeEntriesFromListBox( hWin );

arc.Create( list );

Returns

A new toolkit.


PkCompressFileTools() see also
See Also

PkTools()


PkCompressFileTools() example
See example programs EX00PM.CPP, EX00WIN.CPP, and EX20CON.CPP.


PkCompressTools()

see also	example

Create a toolkit that supports PKWare compressors

Synopsis

#include "arclib.h"

 ALToolKit PkCompressTools( int level = 6, int window_bits = 13, int mem_level = 6 )

Arguments

level

A number between 1 and 9.  1 gives the best speed, 9 gives the best compression.  The default 6 for all programs.

window_bits

The base 2 logarithm of the number of bytes in the history buffer.  Values between 8 and 15 are legal.  The more bits, the more memory.  For 16-bit programs, the default is 13.  For 32-bit programs, the default is 15.

mem_level

How much memory should be allocated for the internal compression state.  mem_level=1 uses minimum memory but has the worst compression ratio; mem_level=9 uses maximum memory for optimal speed.  For 16-bit programs, the default is 6.  For 32-bit programs, the default is 8.

Function

PkCompressTools() creates a toolkit that can build PKWare compressors.  If your application is only going to be compressing something using PKWare, you can use this function to initialize your ALEntryList, and avoid linking in support for PKWare decompressors, Greenleaf compressors, and Greenleaf decompressors.

This toolkit will clone ALFile and either ALMemory or ALWinMemory objects.  If you only want to use ALFile objects, use PkCompressFileTools().

A sample piece of code including PkCompressTools() is shown below.

ALEntryList list( monitor, PkCompressTools() );

ALPkArchive arc( "DOUG.ZIP" );

list.MakeEntriesFromListBox( hWin );

arc.Create( list );

Returns

A new toolkit.


PkCompressTools() see also
See Also

PkTools(), PkCompressFileTools()


PkCompressTools() example
See example programs EX00PM.CPP, EX00WIN.CPP, and EX20CON.CPP.


PkDecompressFileTools()

see also	example

Create a toolkit that supports PKWare decompressors

Synopsis

#include "arclib.h"

 ALToolKit PkDecompressFileTools()

Arguments

None.

Function

PkDecompressFileTools() creates a toolkit that can build PKWare decompressors.  If your application is only going to be decompressing ALFile objects, you can use the toolkit returned by this function in your ALEntryList, and avoid linking in support for compression objects, Greenleaf compressors and decompressors, and memory based objects.

A sample piece of code including PkDecompressFileTools() is shown below.

ALEntryList list( m, PkDecompressFileTools() );

arc.ReadDirectory( list );

arc.Extract( list );

Returns

A new toolkit.


PkDecompressFileTools() see also
See Also

PkDecompressTools()


PkDecompressFileTools() example
See example program EX07CON.C.


PkDecompressTools()

see also	example

Create a toolkit that supports PKWare decompressors

Synopsis

#include "arclib.h"

 ALToolKit PkDecompressTools()

Arguments

None.

Function

PkDecompressTools() creates a toolkit that can build PKWare decompressors.  If your application is only going to be decompressing objects (and not compressing), you can use the toolkit returned by this function in your ALEntryList, and avoid linking in support for compression objects.

This toolkit will clone ALFile and either ALMemory or ALWinMemory objects.  If you don't want to support ALMemory objects, use PkDecompressFileTools().

A sample piece of code including PkDecompressTools() is shown below.

ALEntryList list( monitor, PkDecompressTools() );

archive.ReadDirectory( list );

for( ALEntry * entry = list.GetFirstEntry();

       entry !=0;

       entry = entry->GetNextEntry() )

    cout << entry->mpStorageObject->mName;

Returns

A new toolkit.

This function doesn't return a pointer, but rather a new toolkit.  Usually this is copied into an existing toolkit.


PkDecompressTools() see also
See Also

PkTools(), PkDecompressFileTools()


PkDecompressTools() example
See example program EX03CON.CPP.


PkTools()

see also	example

Create a toolkit with everything but Greenleaf compression/decompression

Synopsis

#include "arclib.h"

 ALToolKit PkTools( int level = 6, int window_bits = 13, int mem_level = 6 )

Arguments

level

A number between 1 and 9.  1 gives the best speed, 9 gives the best compression.  The default 6 for all programs.

window_bits

The base 2 logarithm of the number of bytes in the history buffer.  Values between 8 and 15 are legal.  The more bits, the more memory.  For 16-bit programs, the default is 13.  For 32-bit programs, the default is 15.

mem_level

How much memory should be allocated for the internal compression state.  mem_level=1 uses minimum memory but has the worst compression ratio; mem_level=9 uses maximum memory for optimal speed.  For 16-bit programs, the default is 6.  For 32-bit programs, the default is 8.

Function

PkTools() creates a toolkit that can build the PKWare compressors and decompressors, as well as both ALFile and ALMemory storage objects.

A sample piece of code including PkTools() is shown below.

ALEntryList list( monitor, PkTools() );

list.AddWildCardFiles( "*.*" );

list.FillListBox( hWin );

Returns

A new toolkit.


PkTools() see also
See Also

GlTools()


PkTools() example
See example programs EX01CON.CPP, EX01PM.CPP, and EX01WIN.CPP.


newALListCopyTools()

see also	example

Create an entry list that uses the copy engine toolkit

Synopsis

#include "arclib.h"

 hALEntryList newALListCopyTools( hALMonitor monitor )

 Declare Function newALListCopyTools Lib "AL20LW" ( ByVal monitor& ) As Long

 function newALListCopyTools( monitor : hALMonitor ) : hALEntryList;

Arguments

monitor

A pointer to a monitor that will be used whenever we are processing objects in the list.

Function

This function creates an ALEntryList with the copy engine toolkit.

A sample piece of code including newALListCopyTools() is shown below.

hALEntryList list=newALListCopyTools();

Returns

A handle to the newly created ALEntryList object.


newALListCopyTools() see also
See Also

CopyTools(), newALListFullTools()


newALListCopyTools() example
See example programs EX05CON.C, EX14WIN.C, and EX14VB.FRM.


newALListFullTools()

see also	example

Create an entry list that uses the fully loaded toolkit

Synopsis

#include "arclib.h"

 hALEntryList newALListFullTools( hALMonitor monitor )

 Declare Function newALListFullTools Lib "AL20LW" ( ByVal monitor& ) As Long

 function newALListFullTools( monitor : hALMonitor ) : hALEntryList;

Arguments

monitor

A pointer to a monitor that will be used whenever we are processing objects in the list.

Function

This function creates an ALEntryList with the fully loaded toolkit.

A sample piece of code including newALListFullTools() is shown below.

hALEntryList list=newALListFullTools();

ALEntryListAddWildCardFiles( list, "*.c" );

ALArchiveCreate( archive, list );

Returns

A handle to the newly created ALEntryList object.


newALListFullTools() see also
See Also

FullTools(), newALListPkTools(), newALListGlTools()


newALListFullTools() example
See example programs EX01WIN.C and EX04CON.C.


newALListGlCompressFileTools()

see also	example

Create an entry list that uses the Greenleaf and ALFile toolkit

Synopsis

#include "arclib.h"

 hALEntryList newALListGlCompressFileTools( hALMonitor monitor, short int compression_level )

 Declare Function newALListGlCompressFileTools Lib "AL20LW" ( ByVal monitor&, ByVal compression_level% ) As Long

 function newALListGlCompressFileTools( monitor : hALMonitor; compression_level : Integer ) : hALEntryList;

Arguments

monitor

A pointer to a monitor that will be used whenever we are processing objects in the list.

compression_level

An integer value somewhere between AL_GREENLEAF_COPY and AL_GREENLEAF_LEVEL_4.  AL_GREENLEAF_LEVEL_0 through AL_GREENLEAF_LEVEL_4 all perform compression at varying levels, using varying amounts of memory.

You can use the C++ default parameter values by simply passing AL_DEFAULT for compression_level.

Function

This function creates an ALEntryList with the Greenleaf and ALFile toolkit.

A sample piece of code including newALListGlCompressFileTools() is shown below.

hALEntryList=newALListGlCompressFileTools( monitor, AL_GREENLEAF_LEVEL_4 );

ALEntryListMakeEntriesFromListBox( list, hDlg, -1 );

ALArchiveAppend( list );

Returns

A handle to the newly created ALEntryList object.


newALListGlCompressFileTools() see also
See Also

newALListGlTools()


newALListGlCompressFileTools() example
See example program EX02CON.C.


newALListGlCompressTools()

see also	example

Create an entry list that uses the Greenleaf compressor toolkit

Synopsis

#include "arclib.h"

 hALEntryList newALListGlCompressTools( hALMonitor monitor, short int compression_level )

 Declare Function newALListGlCompressTools Lib "AL20LW" ( ByVal monitor&, ByVal compression_level% ) As Long

 function newALListGlCompressTools( monitor : hALMonitor; compression_level : Integer ) : hALEntryList;

Arguments

monitor

A pointer to a monitor that will be used whenever we are processing objects in the list.

compression_level

An integer value somewhere between AL_GREENLEAF_COPY and AL_GREENLEAF_LEVEL_4.  AL_GREENLEAF_LEVEL_0 through AL_GREENLEAF_LEVEL_4 all perform compression at varying levels, using varying amounts of memory.

You can use the C++ default parameter values by simply passing AL_DEFAULT for compression_level.

Function

This function creates an ALEntryList with the Greenleaf compressor toolkit.

A sample piece of code including newALListGlCompressTools() is shown below.

list=newALListGlCompressTools( 0, AL_DEFAULT );

ALArchiveReadDirectory( arcl, list );

ALArchiveAppendFromArchive( arc2, arc1, list );

Returns

A handle to the newly created ALEntryList object.


newALListGlCompressTools() see also
See Also

newALListGlTools()


newALListGlCompressTools() example
See example programs EX00CON.C and EX00WIN.C.


newALListGlDecompressFileTools()

see also	example

Create an entry list that uses the Greenleaf and ALFile toolkit

Synopsis

#include "arclib.h"

 hALEntryList newALListGlDecompressFileTools( hALMonitor monitor )

 Declare Function newALListGlDecompressFileTools Lib "AL20LW" ( ByVal monitor& ) As Long

 function newALListGlDecompressFileTools( monitor : hALMonitor ) : hALEntryList;

Arguments

monitor

A pointer to a monitor that will be used whenever we are processing objects in the list.

Function

This function creates an ALEntryList with the Greenleaf and ALFile toolkit.

A sample piece of code including newALListGlDecompressFileTools() is shown below.

archive=newALGlArchive( "DOS00.GAL" );

list=newALListGlDecompressFileTools( monitor );

ALArchiveReadDirectory( archive, list );

Returns

A handle to the newly created ALEntryList object.


newALListGlDecompressFileTools() see also
See Also

newALListGlTools()


newALListGlDecompressFileTools() example
See example program EX07CON.C.


newALListGlDecompressTools()

see also	example

Create an entry list that uses the Greenleaf decompressor toolkit

Synopsis

#include "arclib.h"

 hALEntryList newALListGlDecompressTools( hALMonitor monitor )

 Declare Function newALListGlDecompressTools Lib "AL20LW" ( ByVal monitor& ) As Long

 function newALListGlDecompressTools( monitor : hALMonitor ) : hALEntryList;

Arguments

monitor

A pointer to a monitor that will be used whenever we are processing objects in the list.

Function

This function creates an ALEntryList with the Greenleaf decompressor toolkit.

A sample piece of code including newALListGlDecompressTools() is shown below.

ALArchiveFillListBox( archive, hDlg, ID_FILE_DIR );

list=newALListGlDecompressTools( monitor );

ALEntryListMakeEntriesFromListBox( list, hDlg, ID_FILE_DIR );

ALArchiveExtract( archive, list );

Returns

A handle to the newly created ALEntryList object.


newALListGlDecompressTools() see also
See Also

newALListGlTools()


newALListGlDecompressTools() example
See example program EX03CON.CPP.


newALListGlTools()

see also	example

Create an entry list that uses the Greenleaf toolkit

Synopsis

#include "arclib.h"

 hALEntryList newALListGlTools ( hALMonitor monitor, short int compression_level )

 Declare Function newALListGlTools Lib "AL20LW" ( ByVal monitor&, ByVal compression_level% ) As Long

 function newALListGlTools( monitor : hALMonitor; compression_level : Integer ) : hALEntryList;

Arguments

monitor

A pointer to a monitor that will be used whenever we are processing objects in the list.

compression_level

An integer value somewhere between AL_GREENLEAF_COPY and AL_GREENLEAF_LEVEL_4.  AL_GREENLEAF_LEVEL_0 through AL_GREENLEAF_LEVEL_4 all perform compression at varying levels, using varying amounts of memory.

You can use the C++ default parameter values by simply passing AL_DEFAULT for compression_level.

Function

This function creates an ALEntryList with the full Greenleaf toolkit.

A sample piece of code including newALListGlTools() is shown below.

monitor=newALBarGraph( AL_MONITOR_OBJECT );

archive=newALPkArchive( "DOS00.ZIP" );

list=newALListGlCompressTools( monitor, AL_GREENLEAF_LEVEL_4 );

Returns

A handle to the newly created ALEntryList object.


newALListGlTools() see also
See Also

newALListFullTools()


newALListGlTools() example
See example programs EX00CON.C, EX02WIN.C, EX00VB.FRM, and EX00UNIT.PAS.


newALListPkCompressFileTools()

see also	example

Create an entry list that uses the PKWare and ALFile toolkit

Synopsis

#include "arclib.h"

 hALEntryList newALListPkCompressFileTools( hALMonitor monitor, int level, int window_bits, int mem_level )

 Declare Function newALListPkCompressFileTools Lib "AL20LW" ( ByVal monitor&, ByVal level%, ByVal window_bits%, ByVal mem_level% ) As Long

 function newALListPkCompressFileTools( monitor : hALMonitor; level : Integer; window_bits : Integer; mem_level : Integer )  hALEntryList;

Arguments

level

A number between 1 and 9.  1 gives the best speed, 9 gives the best compression.  The default 6 for all programs.

window_bits

The base 2 logarithm of the number of bytes in the history buffer.  Values between 8 and 15 are legal.  The more bits, the more memory.  For 16-bit programs, the default is 13.  For 32-bit programs, the default is 15.

mem_level

How much memory should be allocated for the internal compression state.  mem_level=1 uses minimum memory but has the worst compression ratio; mem_level=9 uses maximum memory for optimal speed.  For 16-bit programs, the default is 6.  For 32-bit programs, the default is 8.

You can use the C++ default parameter values by simply passing AL_DEFAULT for any of the three numeric parameters shown above.

Function

This function creates an ALEntryList with the PKWare and ALFile toolkit.

A sample piece of code including newALListPkCompressFileTools() is shown below.

list=newALListPkCompressFileTools( monitor, 9, 13, 6 );

ALEntryListAddWildCardFiles( list, "*.CPP", 0 );

ALArchiveAppend( archive, list );

Returns

A handle to the newly created ALEntryList object.


newALListPkCompressFileTools() see also
See Also

newALListPkTools()


newALListPkCompressFileTools() example
See example program EX02CON.C.


newALListPkCompressTools()

see also	example

Create an entry list that uses the PKWare compressor toolkit

Synopsis

#include "arclib.h"

 hALEntryList newALListPkCompressTools( hALMonitor monitor, int level, int window_bits, int mem_level )

 Declare Function newALListPkCompressTools Lib "AL20LW" ( ByVal monitor&, ByVal level%, ByVal window_bits%, ByVal mem_level% ) As Long

 function newALListPkCompressTools( monitor : hALMonitor; level : Integer; window_bits : Integer; mem_level : Integer ) : hALEntryList;

Arguments

level

A number between 1 and 9.  1 gives the best speed, 9 gives the best compression.  The default 6 for all programs.

window_bits

The base 2 logarithm of the number of bytes in the history buffer.  Values between 8 and 15 are legal.  The more bits, the more memory.  For 16-bit programs, the default is 13.  For 32-bit programs, the default is 15.

mem_level

How much memory should be allocated for the internal compression state.  mem_level=1 uses minimum memory but has the worst compression ratio; mem_level=9 uses maximum memory for optimal speed.  For 16-bit programs, the default is 6.  For 32-bit programs, the default is 8.

You can use the C++ default parameter values by simply passing AL_DEFAULT for any of the three numeric parameters shown above.

Function

This function creates an ALEntryList with the PKWare compressor toolkit.

A sample piece of code including newALListPkCompressTools() is shown below.

hlist=newALListPkCompressTools( hMonitor, AL_DEFAULT, AL_DEFAUTL, AL_DEFAULT );

ALEntryListAddWildCardFiles( hlist, "*.*", 1 );

ALArchiveCreate( archive, hlist );

Returns

A handle to the newly created ALEntryList object.


newALListPkCompressTools() see also
See Also

newALListPkTools(), newALListPkCompressFileTools()


newALListPkCompressTools() example
See example programs EX00CON.C and EX00WIN.C.


newALListPkDecompressFileTools()

see also	example

Create an entry list that uses the PKWare and ALFile toolkit

Synopsis

#include "arclib.h"

 hALEntryList newALListPkDecompressFileTools( hALMonitor monitor )

 Declare Function newALListPkDecompressFileTools Lib "AL20LW" ( ByVal monitor& ) As Long

 function newALListPkDecompressFileTools( monitor : hALMonitor ) : hALEntryList;

Arguments

monitor

A pointer to a monitor that will be used whenever we are processing objects in the list.

Function

This function creates an ALEntryList with the PKWare and ALFile toolkit.

A sample piece of code including newALListPkDecompressFileTools() is shown below.

list=newALListPkDecompressFileTools( monitor );

Returns

A handle to the newly created ALEntryList object.


newALListPkDecompressFileTools() see also
See Also

newALListPkCompressFileTools()


newALListPkDecompressFileTools() example
See example program EX07CON.C.


newALListPkDecompressTools()

see also	example

Create an entry list that uses the PKWare decompressor toolkit

Synopsis

#include "arclib.h"

 hALEntryList newALListPkDecompressTools( hALMonitor monitor )

 Declare Function newALListPkDecompressTools Lib "AL20LW" ( ByVal monitor& ) As Long

 function newALListPkDecompressTools( monitor : hALMonitor ) : hALEntryList;

Arguments

monitor

A pointer to a monitor that will be used whenever we are processing objects in the list.

Function

This function creates an ALEntryList with the PKWare decompressor toolkit.

A sample piece of code including newALListPkDecompressTools() is shown below.

list=newALListPkDecompressTools( monitor );

Returns

A handle to the newly created ALEntryList object.


newALListPkDecompressTools() see also
See Also

newALListPkTools(), newALListPkDecompressFileTools()


newALListPkDecompressTools() example
See example program EX03CON.CPP.


newALListPkTools()

see also	example

Create an entry list that uses the full PKWare toolkit

Synopsis

#include "arclib.h"

 hALEntryList newALListPkTools( hALMonitor monitor, int level, int window_bits, int mem_level )

 Declare Function newALListPkTools Lib "AL20LW" ( ByVal monitor&, ByVal level%, ByVal window_bits%, ByVal mem_level% ) As Long

 function newALListPkTools( monitor : hALMonitor; level : Integer; window_bits : Integer; mem_level : Integer ) : hALEntryList;

Arguments

monitor

A pointer to a monitor that will be used whenever we are processing objects in the list.  The default 6 for all programs.

level

A number between 1 and 9.  1 gives the best speed, 9 gives the best compression.  For 16-bit programs, the default is 13.  For 32-bit programs, the default is 15.

window_bits

The base 2 logarithm of the number of bytes in the history buffer.  Values between 8 and 15 are legal.  The more bits, the more memory.

mem_level

How much memory should be allocated for the internal compression state.  mem_level=1 uses minimum memory but has the worst compression ratio; mem_level=9 uses maximum memory for optimal speed.  For 16-bit programs, the default is 6.  For 32-bit programs, the default is 8.

You can use the C++ default parameter values by simply passing AL_DEFAULT for any of the three numeric parameters shown above.

Function

This function creates an ALEntryList with the full PKWare toolkit.

A sample piece of code including newALListPkTools() is shown below.

list=newALListPkTools( monitor, AL_DEFAULT, AL_DEFAULT, AL_DEFAULT );

ALEntryListAddWildCardFiles( list, "*.*", 0 );

ALArchiveCreate( archive, list );

Returns

A handle to the newly created ALEntryList object.


newALListPkTools() see also
See Also

newALListGlTools(), newALListFullTools()


newALListPkTools() example
See example programs EX00CON.C, EX02WIN.C, EX00VB.FRM, and EX00UNIT.PAS.


ALCompressedObject()
ALCompressedObject::ALCompressedObject()

see also	example

Constructor for ALCompressedObject class

Synopsis

#include "arclib.h"

#include "cmpobj.h"

 ALCompressedObject::ALCompressedObject( ALStorage &storage, ALCompressor *compressor, ALDecompressor *decompressor );

 hALCompressed newALCompressed( hALStorage storage, hALCompressor compressor, hALDecompressor decompressor )

 Declare Function newALCompressed Lib "AL20LW" ( ByVal storage&, ByVal compressor&, ByVal decompressor& ) As Long

 function newALCompressed( storage : hALStorage; compressor : hALCompressor, decompressor : hALDecompressor ) : hALCompressed;

Arguments

storage

Storage object where compressed data will be stored

compressor

A reference to the compression engine that will be used to insert a storage object into the compressed object.  If you are only going to be extracting, you can use 0 (or nil for Delphi) for this argument.

decompressor

A reference to the decompression engine that will be used to extract a storage object from the compressed object.  If you are only going to be inserting, you can use 0 (or nil for Delphi) for this argument.

Function

  ALCompressedObject::ALCompressedObject() is the constructor for the ALCompressedObject class.  This constructor requires a storage object for storage and retrieval of compressed data.  When ALCompressedObject::Insert() is called, the storage object will be opened with a call to the ALStorage::Create(), unless it is already open.

A sample code piece including the ALCompressedObject() constructor, is shown below.

    ALFileObject compressed_file( "OUTPUT.COB" );

    ALGlCompressor engine;

    ALCompressedObject *object =

             new ALCompressedObject( compressed_file,  engine, 0 );

Returns

There are no returns for C++ constructors.  C, Visual Basic, and Delphi return an hALCompressed handle, which is passed as the this_object parameter to all ALCompressedObject functions.


ALCompressedObject() see also
See Also

ALCompressedObject::~ALCompressedObject()


ALCompressedObject() example
See example programs EX12CON.CPP, EX14PM.CPP, and EX14WIN.CPP.


~ALCompressedObject()
ALCompressedObject::~ALCompressedObject()

see also	example

Destructor for ALCompressedObject class

Synopsis

#include "arclib.h"

#include "cmpobj.h"

 ALCompressedObject::~ALCompressedObject()

 void deleteALCompressed( hALCompressed this_object )

 Declare Sub deleteALCompressed Lib "AL20LW" ( ByVal this_object& )

 procedure deleteALCompressed( this_object : hALCompressed );

Arguments

this_object

Handle to the ALCompressedObject object to be destroyed

Function

ALCompressedObject::~ALCompressedObject() is the destructor for the ALCompressedObject class.

A sample code piece including ~ALCompressedObject(), is shown below.

    .

    .

    .

    object->Insert( ALFileObject( "INPUT.DAT" ) );

    delete object;

Returns

N/A


~ALCompressedObject() see also
See Also

ALCompressedObject::ALCompressedObject()


~ALCompressedObject() example
See example program EX12CON.CPP.


ClearError() - ALCompressedObject class
ALCompressedObject::ClearError()

see also	example

Reset the error status for a compressed object

Synopsis

#include "arclib.h"

#include "cmpobj.h"

 void ALCompressedObject::ClearError()

 void ALCompressedClearError( hALCompressed this_object )

 Declare Sub ALCompressedClearError Lib "AL20LW" ( ByVal this_object& )

 procedure ALCompressedClearError( this_object : hALCompressed );

Arguments

this_object

A reference or pointer to the ALCompressedObject that is going to have its status reset.  The C++ version of this call does not have an explicit argument here, since it has access to 'this' implicitly.

Function

An ALCompressedObject carries around a status object in its mStatus member.  Error conditions are not cleared automatically by the library, so the user will have to clear it manually with a call to this function.

In C++, this function will be implemented as an inline function.

A sample piece of code including ClearError() is shown below

if ( object.mStatus < AL_SUCCESS )

{

   cerr << "Error in compressed obj.";

   object.ClearError();

}

Returns

None


ClearError() see also - ALCompressedObject class
See Also

ALStatus::SetError()


ClearError() example - ALCompressedObject class
See example program EX14WIN.CPP.


Extract() - ALCompressedObject class
ALCompressedObject::Extract()

see also	example

Extract compressed data from compressed object

Synopsis

#include "arclib.h"

#include "cmpobj.h"

 int Extract( ALStorage &output_object )

 int ALCompressedExtract( hALCompressed this_object, hALStorage output_object )

 Declare Function ALCompressedExtract Lib "AL20LW" ( ByVal this_object&, ByVal output_object& ) As Integer

 function ALCompressedExtract( this_object : hALCompressed; output_object : hALStorage ) : Integer;

Arguments

this_object

Handle to the ALCompressedObject object

output_object

Output storage object to receive the compressed data

Function

ALCompressedObject::Extract() extracts compressed data from a compressed object and places it into an output storage object.

A sample code piece including Extract(), is shown below.

    ALCompressedObject cob( input_file, 0, decompressor );

    ALStorage *dest = new ALMemory();

    cob.Extract( *dest );

Returns

ALCompressedObject::Extract() returns AL_SUCCESS if the function was successful.  An error code is returned if the function was not successful.


Extract() see also - ALCompressedObject class
See Also

ALCompressedObject::Insert()


Extract() example - ALCompressedObject class
See example programs EX12CON.CPP, EX18CON.C, EX18VB.FRM, and EX18UNIT.PAS.


Insert() - ALCompressedObject class
ALCompressedObject::Insert()

see also	example

Insert storage object into compressed object

Synopsis

#include "arclib.h"

#include "cmpobj.h"

 int Insert( ALStorage &input_object )

 int ALCompressedInsert( hALCompressed this_object, hALStorage input_object )

 Declare Function ALCompressedInsert Lib "AL20LW" ( ByVal this_object&, ByVal input_object& ) As Integer

 function ALCompressedInsert( this_object : hALCompressed; input_object : hALStorage ) : Integer;

Arguments

this_object

Handle to the ALCompressedObject object

input_object

Reference to the input storage object to be placed in a compressed object

Function

ALCompressedObject::Insert() inserts an input storage object into a compressed object.  The compressed object's storage object is defined in the constructor.

A sample code piece for C++, including Insert(), is shown below.

   ALCompressedObject cob( output_file, engine, 0 );

   cob.Insert( ALFileObject( "COMMAND.COM" ) );

Returns

ACompressedObject::Insert() returns AL_SUCCESS if the function was successful.  An error code is returned if the function was not successful.


Insert() see also - ALCompressedObject class
See Also

ALCompressedObject::Extract()


Insert() example - ALCompressedObject class
See example programs EX12CON.CPP, EX14PM.CPP, EX14WIN.CPP, EX14WIN.C, EX18CON.C, EX14VB.FRM, and EX14UNIT.PAS.


ReadHeaderData() - ALCompressedObject class
ALCompressedObject::ReadHeaderData()

see also	example

Read private header data

This function is protected.  It cannot be called by functions other than member functions of ALCompressedObject.  You may choose to override this in a class you derive from ALCompressedObject.

Synopsis

#include "arclib.h"

#include "cmpobj.h"

 virtual int ALCompressedObject::ReadHeaderData( ALStorage * storage )

Arguments

storage

A pointer to the storage object that is going to receive the object extracted from the ALCompressedObject.  Be sure not to confuse this with mpStorageObject, which is the member that points to the storage object that's holding the compressed data.

Function

ALCompressedObject::ReadHeaderData() reads private header data during compression or decompression.  It is only used if a new derived class implements this function to store additional data.  Derived classes can also use this function to read additional data from the compressed archive prior to extracting data.  The base class doesn't store any additional data with the object.

A sample piece of code including ReadHeaderData() is shown below.

cout << "Calling ReadHeaderData directly:\n";

mpStorageObject->Open();

mpStorageObject->Seek( 12 );

ReadHeaderData( 0 );

mpStorageObject->Close();

Returns

ALCompressedObject::ReadHeaderData() returns AL_SUCCESS if the function was successful.  An error code is returned if the function was not successful.


ReadHeaderData() see also - ALCompressedObject class
See Also

ALCompressedObject::WriteHeaderData()


ReadHeaderData() example - ALCompressedObject class
See example program EX12CON.CPP.


WriteHeaderData() - ALCompressedObject class
ALCompressedObject::WriteHeaderData()

see also	example

Write private header data

This function is protected.  It cannot be called by functions other than member functions of ALCompressedObject.  You may choose to override this in a class you derive from ALCompressedObject().

Synopsis

#include "arclib.h"

#include "cmpobj.h"

 virtual int ALCompressedObject::WriteHeaderData( ALStorage * storage )

Arguments

storage

A pointer to the storage object that is going to be inserted into the ALCompressed object.  Be sure not to confuse this with mpStorageObject, which is the member that points to the storage object that's going to hold the compressed data.

Function

ALCompressedObject::WriteHeaderData() writes private header data during compression or decompression.  It is only used when a derived class needs to write additional data.  Derived classes can use this function to write additional data to the compressed archive prior to extracting data.  The base class doesn't write any additional data to the archive.

A sample piece of code including WriteHeaderData() is shown below.

cout << "Calling WriteHeaderData directly:\n";

mpStorageObject->Open();

mpStorageObject->Seek( 12 );

WriteHeaderData( 0 );

mpStorageObject->Close();

Returns

ALCompressedObject::WriteHeaderData() returns AL_SUCCESS if the function was successful.  An error code is returned if the function was not successful.


WriteHeaderData() see also - ALCompressedObject class
See Also

ALCompressedObject::ReadHeaderData()


WriteHeaderData() example - ALCompressedObject class
See example program EX12CON.CPP.


ALCompressedGetStatusCode()

see also	example

Get status of ALCompressedObject

Synopsis

#include "arclib.h"

#include "cmpobj.h"

 int ALCompressedGetStatusCode( hALCompressed this_object )

 Declare Function ALCompressedGetStatusCode Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALCompressedGetStatusCode( this_object : hALCompressed ) : Integer;

C, Visual Basic, and Delphi programmers can access the ALCompressedObject data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALCompressedObject object

Function

ALCompressedGetStatusCode() returns a status value of an object of ALCompressedObject.   ArchiveLib does this for objects that have mStatus members, including ALEntryList and ALStorage.  This status member contains an integer that indicates the current status of an object.  ALCompressedGetStatusCode() retrieves that status value.

A sample code piece including ALCompressedGetStatusCode(), is shown below:

    if ( ALCompressedGetStatusCode( object ) < AL_SUCCESS )

        printf( "Error, prepare to reboot..." );

Returns

ALCompressedGetStatusCode() returns the integer value of the error code.


ALCompressedGetStatusCode() see also
See Also

ALCompressedGetStatusString()


ALCompressedGetStatusCode() example
See example programs EX18CON.C, EX18VB.FRM, and EX18UNIT.PAS.


ALCompressedGetStatusDetail()

see also	example

Get detailed error information

Synopsis

#include "arclib.h"

#include "cmpobj.h"

 char *ALCompressedGetStatusDetail( hALCompressed this_object )

 Declare Function ALCompressedGetStatusDetail Lib "AL20LW" ( ByVal this_object& ) As String

 function ALCompressedGetStatusDetail( this_object : hALCompressed ) : String;

C, Visual Basic, and Delphi programmers can access the ALCompressedObject data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALCompressedObject object

Function

ALCompressedStatusDetail() returns detailed information about a specific error message associated with ALCompressedObject.  ArchiveLib does this for objects that have mStatus members, including ALStorage and ALEntryList.  The detailed message produced by this function includes various data items that might help track down the source of the problem.  These messages are fairly technical, and are intended for use by developers instead of end-users.

A sample piece of code including ALCompressedGetStatusDetail() is shown below.

char * p=ALCompressedGetStatusDetail( obj );

printf( "%s", p );

Returns

ALCompressedGetStatusDetail() returns a string with a brief description of the error message.  If no error was found, this function returns 0 or an empty string.


ALCompressedGetStatusDetail() see also
See Also

ALCompressedGetStatusCode()


ALCompressedGetStatusDetail() example
See example programs EX18CON.C, EX18VB.FRM, and EX18UNIT.PAS.


ALCompressedGetStatusString()

see also	example

Translate error into code string

Synopsis

#include "arclib.h"

#include "cmpobj.h"

 char * ALCompressedGetStatusString( hALCompressed this_object )

 Declare Function ALCompressedGetStatusString Lib "AL20LW" ( ByVal this_object& ) As String

 function ALCompressedGetStatusString( this_object : hALCompressed ) : String;

C, Visual Basic, and Delphi programmers can access the ALCompressedObject data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALCompressedObject object

Function

ALCompressedGetStatusString() translates an error code in an ALCompressed object to a short text string.  ArchiveLib does this for objects that have mStatus members, including ALStorage, ALCompressor, ALDecompressor, and ALEntryList.  When displaying error values to users, the string returned by this function will be much more intelligible than displaying the integer value of the error.

A few sample error code translations include the following:

     AL_SUCCESS	"Success"

     AL_END_OF_FILE	"End of file"

     AL_CANT_OPEN_BUFFER	"Can't allocate buffer"

Returns

ALCompressedGetStatusString() returns a string with a brief description of the error message.  If no error was found, this function returns 0 or an empty string.


ALCompressedGetStatusString() see also
See Also

ALCompressedGetStatusDetail()


ALCompressedGetStatusString() example
See example programs EX18CON.C, EX18VB.FRM, and EX18UNIT.PAS.


ALCompressedSetError()

see also	example

Manipulate error code for ALCompressedObject

Synopsis

#include "arclib.h"

#include "cmpobj.h"

 int ALCompressedSetError( hALCompressed this_object, int error_code, char *text )

 Declare Function ALCompressedSetError Lib "AL20LW" ( ByVal this_object&, ByVal error_code%, ByVal text& ) As Integer

 function ALCompressedSetError( this_object : hALCompressed; error_code : Integer; text : String ) : Integer;

C, Visual Basic, and Delphi programmers can access the ALCompressedObject data member mStatus using this function.  C++ programmers don't need to call this function since they can access the data member directly.  C++ ALStatus functions are also described in the Utility Functions section of this help file.

Arguments

this_object

Handle to the ALCompressedObject object

error_code

Numeric (integer) error code

text

Pointer to formatted error message that will be copied to the object's mStatus data member

Function

ALCompressedSetError() is called when an object of ALCompressedObject detects an error.  This is a useful way to abort an ArchiveLib operation.  To do this, ALCompressedSetError() performs two actions:

•	It sets the error code for the object.

•	It allocates enough space in mStatus to copy and then hold a detailed description of why the error occurred.

A sample piece of code including ALCompressedSetError() is shown below.

ALCompressedSetError( hobj, AL_USER_ABORT, "Failed to select option" );

Returns

ALCompressedSetError() returns AL_SUCCESS if the function was successful.  An error code is returned if the function was not successful.


ALCompressedSetError() see also
See Also

ALCompressedGetStatusCode(), ALCompressedGetStatusString()


ALCompressedSetError() example
See example programs EX18CON.C, EX18VB.FRM, and EX18UNIT.PAS.


EditDisplay()

see also	example

Direct output to multiline edit control

Synopsis

#include "arclib.h

 void EditDisplay( HWND hDlg, int id, char *fmt, ...)

 void EditDisplay( HWND hDlg, int id, char *fmt, ...)

Synopsis

hDlg

Dialog box or window handle

id

Edit control ID.  If this value is -1, hDlg is assumed to be the Window handle for a multiline edit control

fmt

Format string, as it will be passed to wvsprintf()or vsprintf()

...

Additional arguments

Function

This is the equivalent of the C Runtime Library printf() function, except that it directs its output to a standard multiline edit control.  Output is directed to a control in a dialog box by specifying the dialog handle and control id.  If you are sending to a control that isn't in a dialog box, you can pass the window handle and set id to -1; this indicates that you are not sending to a control in a dialog.

The following are special considerations when using this function:

•	The Windows version of this function uses the Windows API function  wvsprintf() to format the specified items.  The Presentation Manager version uses vsprintf().  In both operating environments, EditDisplay() uses an internal buffer of 128 bytes to format the data, and is vulnerable to overflow.  Do not send a group of data items that will require more space than 128 bytes.

•	Character pointers must be cast to be far pointers when using the DLL version of ArchiveLib and your program is being compiled in small or medium model.  You can take advantage of the AL_DLL_FAR macro to automatically do this so you will not have to modify your code if you change memory models.

A sample code piece including EditDisplay() is shown below:

   EditDisplay( hDlg, DEBUG_CONTROL, "Error code was: %s", (char AL_DLL_FAR *) pszStatus );

Returns

None


EditDisplay() see also
See Also

None


EditDisplay() example
See example program EX01WIN.C, EX01WIN.CPP, and EX02PM.CPP.


Archive() - ALFileAttributes class
ALFileAttributes::Archive()

see also	example

Get the Archive (or backup) file protection bit for a storage object

Synopsis

#include "arclib.h"

 int ALFileAttributes::Archive()

 int ALStorageArchive( hALStorage storage )

 Declare Function ALStorageArchive Lib "AL20LW" ( ByVal storage& ) As Integer

 function ALStorageArchive( storage : hALStorage ) : Integer;

Arguments

storage

The C++ version of this function is a member function that is applied to the mAttribute member of a storage object.  As such, it does not have an explicit parameter, since it uses the mAttribute object as its implicit this.  C, Visual Basic, and Delphi do not apply this function to an mAttribute member.  Instead, they apply it directly to a storage object.

Function

Every storage object has a set of attributes that corresponds to the attributes kept by the file system.  This function is one of a collection used to read those bits.  The contents of this particular bit are not valid until the storage object has been opened, or until it has had its information read in from an archive directory.

A sample piece of code including Archive() is shown below.

cout << storage.mAttributes.Archive();

Returns

Archive() returns an integer set to 0 if the Archive bit of the storage object is clear.  It returns 1 if it is set.


Archive() see also - ALFileAttributes class
See Also

ALFileAttributes::System(), ALFileAttributes::ReadOnly(), ALFileAttributes::Hidden()


Archive() example - ALFileAttributes class
See example program EX00MFC.CPP.


Directory() - ALFileAttributes class
ALFileAttributes::Directory()

see also	example

Get the Directory attribute bit for a storage object

Synopsis

#include "arclib.h"

 int ALFileAttributes::Directory()

 int ALStorageDirectory( hALStorage storage )

 Declare Function ALStorageDirectory Lib "AL20LW" ( ByVal storage& ) As Integer

 function ALStorageDirectory( storage : hALStorage ) : Integer;

Arguments

storage

The C++ version of this function is a member function that is applied to the mAttribute member of a storage object.  As such, it does not have an explicit parameter, since it uses the mAttribute object as its implicit this.  C, Visual Basic, and Delphi do not apply this function to an mAttribute member.  Instead, they apply it directly to a storage object.

Function

Every storage object has a set of attributes that corresponds to the attributes kept by the file system.  This function is one of a collection used to read those bits.  The contents of this particular bit are not valid until the storage object has been opened, or until it has had its information read in from an archive directory.

This attribute bit is a little different than all the other bits in the attribute structure.  If an object has the directory bit set, it is more like a placeholder than anything else.  By definition it will have a length of 0.  The expansion routines take special action when creating a file whose directory bit is set.

Currently, ArchiveLib does not create any entries in an archive with the directory bit set.  However, it will attempt to create directories it finds in PKZIP archives.

A sample piece of code including Directory() is shown below.

int open( ALStorage &s )

{

    if ( s.mAttributes.Directory() )

       return 0;

Returns

Directory() returns an integer set to 0 if the Directory bit of the storage object is clear.  It returns 1 if it is set.


Directory() see also - ALFileAttributes class
See Also

ALFileAttributes::Hidden(), ALFileAttributes::ReadOnly(), ALFileAttributes::Archive(), ALFileAttributes::System()


Directory() example - ALFileAttributes class
See example program EX00MFC.CPP.


Hidden() - ALFileAttributes class
ALFileAttributes::Hidden()

see also	example

Get the Hidden file protection bit for a storage object

Synopsis

#include "arclib.h"

 int ALFileAttributes::Hidden()

 int ALStorageHidden( hALStorage storage )

 Declare Function ALStorageHidden Lib "AL20LW" ( ByVal storage& ) As Integer

 function ALStorageHidden( storage : hALStorage ) : Integer;

Arguments

storage

The C++ version of this function is a member function that is applied to the mAttribute member of a storage object.  As such, it does not have an explicit parameter, since it uses the mAttribute object as its implicit this.  C, Visual Basic, and Delphi do not apply this function to an mAttribute member.  Instead, they apply it directly to a storage object.

Function

Every storage object has a set of attributes that corresponds to the attributes kept by the file system.  This function is one of a collection used to read those bits.  The contents of this particular bit are not valid until the storage object has been opened, or until it has had its information read in from an archive directory.

A sample piece of code including Hidden() is shown below.

if ( !s.mAttributes.Hidden() )

   cout << s.mName;

Returns

Hidden() returns an integer set to 0 if the Hidden bit of the storage object is clear.  It returns 1 if it is set.


Hidden() see also - ALFileAttributes class
See Also

ALFileAttributes::System(), ALFileAttributes::Archive(), ALFileAttributes::Readonly()


Hidden() example - ALFileAttributes class
See example program EX00MFC.CPP.


PackedAttributes() - ALFileAttributes class
ALFileAttributes::PackedAttributes()

see also	example

Get file attributes packed into a short integer

Synopsis

#include "arclib.h"

 unsigned short int PackedAttributes()

 unsigned short int ALStoragePackedAttributes( hALStorage this_object )

 Declare Function ALStoragePackedAttributes Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALStoragePackedAttributes( this_object : hALStorage ) : Integer;

Arguments

this_object

Handle to the ALFileAttributes object

Function

ALFileAttributes::PackedAttributes() packs status bits into an unsigned short.  This packed format is used to store protection bits in an archive.  Status bits are packed into a 16-bit integer, suitable for reading or writing.  Bits are stored as follows:

 _	D	_	_	A	H	S	R

A sample code piece including PackedAttributes() is shown below.

    WriteGlShort( att.PackedAttributes() );

Returns

ALFileAttributes::PackedAttributes() returns a 16-bit unsigned integer with the bit pattern shown above.


PackedAttributes() see also - ALFileAttributes class
See Also

ALFileAttributes::SetFromPackedAttributes()


PackedAttributes() example - ALFileAttributes class
See example program EX18CON.CPP.


ReadOnly() - ALFileAttributes class
ALFileAttributes::ReadOnly()

see also	example

Get ReadOnly file protection bit for a storage object

Synopsis

#include "arclib.h"

 int ALFileAttributes::ReadOnly()

 int ALStorageReadOnly( hALStorage storage )

 Declare Function ALStorageReadOnly Lib "AL20LW" ( ByVal storage& ) As Integer

 function ALStorageReadOnly( storage : hALStorage ) : Integer;

Arguments

storage

The C++ version of this function is a member function applied to the mAttribute member of a storage object.  As such, it does not have an explicit parameter, since it uses the mAttribute object as its implicit this.  C, Visual Basic, and Delphi do not apply this function to an mAttribute member.  Instead, they apply it directly to a storage object.

 Function

Every storage object has a set of attributes that corresponds to the attributes kept by the file system.  This function is one of a collection used to read those bits.  The contents of this particular bit are not valid until the storage object has been opened, or until it has had its information read in from an archive directory.

A sample piece of code including ReadOnly() is shown below.

if ( file.mAttributes.ReadOnly() )

   cout << "File is protected!\n";

Returns

ReadOnly() returns an integer that will be set to 0 if the ReadOnly bit of the storage object is clear.  It returns 1 if it is set.


ReadOnly() see also - ALFileAttributes class
See Also

ALFileAttributes::System(), ALFileAttributes::Hidden(), ALFileAttributes::Archive()


ReadOnly() example - ALFileAttributes class
See example program EX00MFC.CPP.


SetFromPackedAttributes() - ALFileAttributes class
ALFileAttributes::SetFromPackedAttributes()

see also	example

Set data members from a packed attribute integer

Synopsis

#include "arclib.h"

 void SetFromPackedAttributes( short int packed_attributes )

 void ALStorageSetFromPackedAtts( hALStorage this_object, unsigned int packed_attributes )

 Declare Sub ALStorageSetFromPackedAtts Lib AL20LW" ( ByVal this_object&, ByVal packed_attributes% )

 procedure ALStorageSetFromPackedAtts( this_object : hALStorage; packed_attributes : Integer );

Arguments

this_object

Handle to the ALFileAttributes object

packed_attributes

A set of packed status bit attributes

Function

ALFileAttributes::SetFromPackedAttributes() is used when extracting or reading an archive entry.    SetFromPackedAttributes() reads a 16-bit word in ArchiveLib's proprietary format and uses it to set the five data members in the ALFileAttribute object.

_	D	_	_	A	H	S	R

A sample code piece including SetFromPackedAttributes() is shown below.

    atts.SetFromPackedAttributes( 0 );

Returns

None


SetFromPackedAttributes() see also - ALFileAttributes class
See Also

ALFileAttributes::PackedAttributes()


SetFromPackedAttributes() example - ALFileAttributes class
See example program EX18CON.CPP.


System() - ALFileAttributes class
ALFileAttributes::System()

see also	example

Get System file protection bit for a storage object

Synopsis

#include "arclib.h"

#include "fileattr.h"

 int ALFileAttributes::System()

 int ALStorageSystem( hALStorage storage )

 Declare Function ALStorageSystem Lib "AL20LW" ( ByVal storage& ) As Integer

 function ALStorageSystem( storage : hALStorage ) : Integer;

Arguments

storage

The C++ version of this function is a member function applied to the mAttribute member of a storage object.  As such, it does not have an explicit parameter, since it uses the mAttribute object as its implicit this.  C, Visual Basic, and Delphi do not apply this function to an mAttribute member.  Instead, they apply it directly to a storage object.

Function

Every storage object has a set of attributes that corresponds to the attributes kept by the file system.  This function is one of a collection used to read those bits.  The contents of this particular bit are not valid until the storage object has been opened, or until it has had its information read in from an archive directory.

A sample piece of code including System() is shown below.

entry = list.GetFirstEntry();

while ( entry != 0 ) {

      if ( entry->mpStorageObject->mAttributes.System() )

          entry.ClearMark();

      entry = entry->GetNextEntry();

Returns

System() returns an integer set to 0 if the System bit of the storage object is clear.  It returns 1 if it is set.


System() see also - ALFileAttributes class
See Also

ALFileAttributes::Hidden(), ALFileAttributes::ReadOnly(), ALFileAttributes::Archive()


System() example - ALFileAttributes class
See example program EX00MFC.CPP.


ALName() 1
ALName::ALName()

see also	example

Constructor for ALName class

Synopsis

#include "arclib.h"

 ALName( const char *s = "", ALCase name_case = AL_MIXED)

There are no equivalent C, Visual Basic, or Delphi routines.  All name processing needs to be done using the native string processing capabilities of the language you are using.

Arguments

s

Pointer to the initial object name.  For C++, the default is "" (empty).

name_case

Case specified for the object name.  Valid values are AL_UPPER, AL_LOWER, and AL_MIXED (the default for C++).  These are defined in the enumerated types located in ALDEFS.H.

MS-DOS file names should be forced to upper- or lower-case, since the operating system treats them as case-insensitive.

Function

ALName::ALName() is a constructor for the ALName object.  It initializes the object name with an initializing string, such as the following:

ALName input( "FILE.DAT" )

A sample code piece including the ALName constructor is shown below.

ALName *name = new ALName( "Max", AL_LOWER );

cout << *name;

Returns

N/A


ALName() 1 see also
See Also

ALName::~ALName(), ALName::ALName( ALName& )


ALName() 1 example
See example program EX19CON.CPP.


ALName() 2
ALName::ALName()

see also	example

Copy constructor for ALName class

Synopsis

#include "arclib.h"

 ALName( const ALName &rhs )

There are no equivalent C, Visual Basic, or Delphi routines.  All name processing needs to be done using the native string processing capabilities of the language you are using.

Arguments

&rhs

Reference to the object being copied

Function

The ALName::ALName() copy constructor for the ALName class allows the compiler to create a new copy of an old object.  This constructor allocates new storage for a copy of the object name, copying the new data into it.

A sample code piece including the ALName() copy constructor is shown below.

    ALName name( "It's about time" );

    ALName new_name = name;

    name = "backup";

Returns

N/A


ALName() 2 see also
See Also

ALName::~ALName(), ALName::ALName( char * )


ALName() 2 example
See example program EX07CON.CPP.


~ALName()
ALName::~ALName()

see also	example

Destructor for ALName class

Synopsis

#include "arclib.h"

 ALName::~ALName()

ALName objects are constructed automatically by the ALStorage class; it is unnecessary for C, Visual Basic, and Delphi programmers to construct or destroy ALName objects.

Arguments

None

Function

~ALName() is the destructor for the ALName class.  It deletes memory in use by both the current and old object names.

A sample code piece including the ALName() destructor, is shown below.

    ALName *name = newALName;

    *name = "Rico Suave";

    expand_object( name );

    delete name;

Returns

N/A


~ALName() see also
See Also

ALName::ALName()


~ALName() example
See example program EX04WIN.CPP.


ChangeExtension() - ALName class
ALName::ChangeExtension()

see also	example

Change file extension

Synopsis

#include "arclib.h"

 ALName& ALName::ChangeExtension( const char *new_extension = ".bak" )

 char *ALStorageChangeExtension( hALStorage this_object, char *new_extension )

 Declare Function ALStorageChangeExtension Lib "AL20LW" (ByVal this_object&, ByVal new_extension$) As String

 function ALStorageChangeExtension( this_object : hALStorage; new_extension : String ) : String;

Arguments

this_object

A handle for (pointer to) the storage object whose name you want to test

new_extension

New file extension name.  For C++, the default is .bak.

Function

ALName::ChangeExtension() changes an object's file extension.  It is frequently used to rename a file prior to it becoming a backup.  For C++, the default extension is .bak, however, you can specify any three-character extension.  For physical disk files under MS-DOS, the file extension is limited to a maximum of three characters.  ALMemoryBase objects don't have this limitation.

A sample code piece including ChangeExtension() is shown below.

    ALFile *backup( ALFile &object )

    {

        ALFile *new_file = new ALFile(

                  object.mName() );

        object.mName.ChangeExtension( ".000" );

        object.Rename();

        return new_file;

    }

Returns

ALName::ChangeExtension() returns a reference to this (i.e., the object upon which the function is being performed).  In C, a pointer to the new name is returned; in Visual Basic and Delphi, the new name is returned.


ChangeExtension() see also - ALName class
See Also

ALName::ChangeTrailingChar()


ChangeExtension() example - ALName class
See example program EX19CON.CPP.


ChangeTrailingChar() - ALName class
ALName::ChangeTrailingChar()

see also	example

Change last character in a file name

Synopsis

#include "arclib.h"

 ALName& ALName::ChangeTrailingChar( const char new_char = '@' )

 char *ALStorageChangeTrailingChar( hALStorage this_object, char new_char )

 Declare Function ALStorageChangeTrailingChar Lib "AL20LW" ( ByVal this_object&, ByVal new_char% ) As String

 function ALStorageChangeTrailingChar( this_object : hALStorage; new_char : Char ) : String;

Arguments

this_object

A handle for (pointer to) the storage object whose name you want to change

new_char

Name of new trailing characters.  For C++, the default is '@'.

Function

ALName::ChangeTrailingChar() changes the last character in a file name.  For example, using this function, FILE.DAT might be changed to FILE.DA@.  If the file name does not have an extension, ChangeTrailingChar() adds one composed of a single "." and the new trailing character.  For example, INPUT would become INPUT.@.

The previous object name is stored in the mszOldName member.  Once there is a name stored in mszOldName, you can Rename() or UnRename() the file.

A sample code piece including ChangeTrailingChar(), is shown below.

    ALFile file( argv[ 2 ] );

    cout << "New name : "

             << file.mName.ChangeTrailingChar( '@' )

             << "\n";

Returns

ALName::ChangeTrailingChar() returns a reference to this (i.e., the object upon which the function is being performed).  In C, a pointer to the new name is returned; in Visual Basic and Delphi, the new name is returned.


ChangeTrailingChar() see also - ALName class
See Also

ALName::ChangeExtension()


ChangeTrailingChar() example - ALName class
See example program EX19CON.CPP.


GetName() - ALName class
ALName::GetName()

see also	example

Return pointer to object name

Synopsis

#include "arclib.h"

 const char *GetName()

 char *ALStorageGetName( hALStorage this_object )

 Declare Function ALStorageGetName Lib "AL20LW" ( ByVal this_object& ) As String

 function ALStorageGetName( this_object : hALStorage ) : String;

Arguments

this_object

A handle for (pointer to) the storage object whose name you want

Function

ALName::GetName() returns a pointer to the character array holding the name, or a 0 if no name is defined.  This pointer can change any time the name is modified.  The 0 value is returned if the name is presently NULL.

It is generally easier to use the casting operator to access a string from an object name (e.g., char *p = mName).

A sample code piece including GetName() is shown below.

    copy_file( ALStorage *object )

    {

        cout << "Getting ready to copy: "

                 << object->>mName.GetName();

                 << "\n";

Returns

The C++ and C versions of this function return a pointer to an object name.  A zero is returned if no name is defined.  The Visual Basic and Delphi functions return a string containing the object name.  An empty string is returned if no name is defined.


GetName() see also - ALName class
See Also

ALName::GetOldName(), ALName::GetSafeName()


GetName() example - ALName class
See example program EX19CON.CPP.


GetOldName() - ALName class
ALName::GetOldName()

see also	example

Return pointer to old object name

Synopsis

#include "arclib.h"

 const char *GetOldName()

 char *ALStorageGetOldName( hALStorage this_object )

 Declare Function ALStorageGetOldName Lib "AL20LW" ( ByVal this_object& ) As String

 function ALStorageGetOldName( this_object : hALStorage ) : String;

Arguments

this_object

A handle for (pointer to) the storage object whose old name you want

Function

ALName::GetOldName() returns a pointer to the character array holding the old object name, or a 0 value if no old name is defined (when the object is first created, it doesn't have an old name)  The pointer can change any time the name is modified.  If an object name is not defined, this function will return a NULL pointer.

It is generally easier to use the casting operator to access a string from an old object name (e.g., char *p = mName).  See the function description of operator const char* for more information.

A sample code piece for C++, including GetOldName(), is shown below.

    cout << file.mName.GetOldName()

             << " was just renamed to  "

             << file.mName.GetName()

             << "\n";

Returns

The C++ and C versions of this function return a pointer to the old object name.  A zero is returned if no name is defined.  The Visual Basic and Delphi functions return a string containing the old object name.  An empty string is returned if no name is defined.


GetOldName() see also - ALName class
See Also

ALName::GetName(), ALName::GetSafeOldName()


GetOldName() example - ALName class
See example program EX19CON.CPP.


GetSafeName() - ALName class
ALName::GetSafeName()

see also	example

Return non-Null pointer to object name

Synopsis

#include "arclib.h"

 const char * ALName::GetSafeName() const

Arguments

None

Function

ALName::GetSafeName() returns a pointer to the character array holding the name.  GetSafeName() is just like GetName() except that it is guaranteed not to return a NULL pointer.  The pointer can change any time the name is modified.  This function is useful if you want to safely print a string or send a string to a control without first testing the string.

A sample code piece including GetSafeName() is shown below.

    cout << memory_object.mName.GetSafeName();

Returns

ALName::GetSafeName() returns a pointer to an object name.  An empty string is returned if the internal string is NULL.


GetSafeName() see also - ALName class
See Also

ALName::GetName()


GetSafeName() example - ALName class
See example programs EX01CON.CPP, EX03PM.CPP, and EX03WIN.CPP.


GetSafeOldName() - ALName class
ALName::GetSafeOldName()

see also	example

Return non-Null pointer to old object name

Synopsis

#include "arclib.h"

 const char *GetSafeOldName() const

Arguments

None

Function

ALName::GetSafeOldName() returns a pointer to the character array holding the old object name.  The pointer can change any time the name is modified.  This function is useful if you want to safely print an old object's string or send an old object's string to a control without first testing the string.

The old name is the name that was used just before the most recent name change.

A sample code piece including GetSafeOldName() is shown below.

    cout << memory_object.mName.GetSafeOldName();

Returns

ALName::GetSafeOldName() returns a pointer to an old object name.  An empty string is returned if the internal string is NULL.


GetSafeOldName() see also - ALName class
See Also

ALName::GetSafeName()


GetSafeOldName() example - ALName class
See example program EX12WIN.CPP.


StripFileName() - ALName class
ALName::StripFileName()

see also	example

Remove filename from file specification

Synopsi

#include "arclib.h"

 ALName& ALName::StripFileName()

 char *StripFileName( char *file_name )

 Declare Function StripFileName Lib "AL20LW" ( ByVal file_name$ ) As String

 function StripFileName( file_name : String ) : String;

Arguments

file_name

An ordinary string that contains a file name.  This file name may or may not include a drive and path component.

Function

ALName::StripFileName() removes the filename from a file specification, leaving only the drive and path specified.  For example, invoking StripFileName() upon C:\TEST\INPUT.DAT would result in C:\TEST\.

ALName::StripFileName() does not update the mszOldName data member.

A sample code piece including StripFileName() is shown below.

    name.StripFileName();

    name = name + "NEWNAME.DAT";

    ALFile output( name );

Returns

The C++ version of this function returns a reference to this (i.e., the object upon which the function is being performed).  The C, Visual Basic, and Delphi versions of this function return a pointer to the file_name parameter which will have been modified by this function.


StripFileName() see also - ALName class
See Also

ALName::StripPath()


StripFileName() example - ALName class
See example program EX19CON.CPP.


StripPath() - ALName class
ALName::StripPath()

see also	example

Remove path from file specification

Synopsis

#include "arclib.h"

 ALName& ALName::StripPath()

 char *StripPath( char *file_name )

 Declare Function StripPath Lib "AL20LW" ( ByVal file_name$ ) As String

 function StripPath( file_name : String ) : String;

Arguments

file_name

An ordinary string that contains a file name.  This file name may or may not include a drive and path component.

Function

ALName::StripPath() removes the drive and path from a file specification, leaving only the file name.  This function does not update the mszOldName data member.

A sample code piece including StripPath() is shown below.

    copy_file( ALFile &file )

    {

        ALFile dup( file.mName );

        dup.StripPath();

        ALCopyCompressor engine;

        engine.Compress( file, dup );

    }

Returns

The C++ version of this function returns a reference to this (i.e., the object upon which the function is being performed).  The C, Visual Basic, and Delphi versions of this function return a pointer to the file_name parameter which will have been modified by this function.


StripPath() see also - ALName class
See Also

ALName::StripFileName()


StripPath() example - ALName class
See example program EX19DOS.CPP.


WildCardMatch() - ALName class
ALName::WildCardMatch()

see also	example

Match text string with wildcard specifications

Synopsis

#include "arclib.h"

 int ALName::WildCardMatch( const char *pattern )

 int ALStorageWildCardMatch( hALStorage this_object, char *pattern )

 Declare Function ALStorageWildCardMatch Lib "AL20LW" ( ByVal this_object&, ByVal pattern$ ) As Integer

 function ALStorageWildCardMatch( this_object : hALStorage; pattern : String ) : Integer;

Arguments

this_object

A handle for (pointer to) the storage object whose name you want to test

pattern

Wildcard pattern that contains wildcard characters

Function

ALName::WildCardMatch() matches an entire string of text with strings containing specified characteristics.  In the pattern string, the following rules apply:

•	`*' matches any sequence of characters (zero or more)

•	`?' matches any single character

•	[SET] matches any character in the specified set, e.g., [a-z]

•	[!SET] or [^SET] matches any character not in the specified set.

•	\ is allowed within a set to escape a character like ']' or '-'

A set is composed of characters or ranges; a range looks like "character hyphen character" (as in 0-9 or A-Z).  [0-9a-zA-Z_] is the minimal set of characters allowed in the [..] pattern construct.  Other characters are allowed (i.e., 8-bit characters) if your system supports them.

To suppress the special syntactic significance of any of the characters `[]*?!^-\', matching the character(s) exactly, precede it with a `\' character.

Code for this function was written by J. Kercheval who has made it available in the public domain.  Virtually no modification was made to his code.

A sample code piece including WildCardMatch() is shown below.

    ALEntry *entry = list.GetFirstEntry();

    while ( entry ) {

        ALName *name;

        name = entry->mpStorageObject->mName;

        if ( name.WildCardMatch( "*.bak" ) ) {

            entry.ClearMark();

            cout << "Deleting " << name << "\n";

        }

        entry = entry->GetNextEntry;

    }

Returns

ALName::WildCardMatch() returns one of the following values:

Return Value	Meaning

0	no match was made

1	a match was made


WildCardMatch() see also - ALName class
See Also

ALName::ALName()


WildCardMatch() example - ALName class
See example program EX19DOS.CPP.


GetStatusCode() - ALStatus class
ALStatus::GetStatusCode()

see also	example

Get integer value of error

Synopsis

#include "arclib.h"

 int ALStatus::GetStatusCode()

The corresponding C, Visual Basic, and Delphi functions for GetStatusCode() are ALArchiveGetStatusCode(), ALCompressedGetStatusCode(), ALCompressorGetStatusCode(), ALDecompressorGetStatusCode(), ALStorageGetStatusCode(), and ALEntryListGetStatusCode().

Arguments

None

Function

ALStatus::GetStatusCode() returns the integer status of the error code.  The integer is set to AL_SUCCESS (which is equal to 0) when constructed.  If an error occurs, it will set this to an error code integer less than 0 (< 0).  GetStatusCode() is an inline function so it has low overhead.

A sample code piece including GetStatusCode() is shown below.

    if ( object.mStatus.GetStatusCode() == AL_SEEK_ERROR ) {

Returns

ALStatus::GetStatusCode() returns the integer value of the error code.


GetStatusCode() see also - ALStatus class
See Also

ALStatus::GetStatusString()


GetStatusCode() example - ALStatus class
See example programs EX01CON.CPP and EX15PM.CPP.


GetStatusDetail() - ALStatus class
ALStatus::GetStatusDetail()

see also	example

Return pointer to detail string

Synopsis

#include "arclib.h"

 const char* ALStatus::GetStatusDetail()

The corresponding C, Visual Basic, and Delphi functions for GetStatusDetail() are ALArchiveGetStatusDetail(), ALCompressedGetStatusDetail(), ALCompressorGetStatusDetail(), ALDecompressorGetStatusDetail(), ALStorageGetStatusDetail(), and ALEntryListGetStatusDetail().

Arguments

None

Function

ALStatus::GetStatusDetail() returns a pointer to the error detail string (the text description of the most recent error).  If you call this function when no error has occurred, it will simply return a pointer to an empty static string.

A sample code piece including GetStatusDetail() is shown below.

    cout << object.mStatus.GetStatusDetail();

Returns

  returns a detailed message for the last error detected.


GetStatusDetail() see also - ALStatus class
See Also

ALStatus::GetStatusString()


GetStatusDetail() example - ALStatus class
See example programs EX01WIN.CPP, EX02PM.CPP, and EX18CON.CPP.


GetStatusString() - ALStatus class
ALStatus::GetStatusString()

see also	example

Translate error code into ASCII string

Synopsis

#include "arclib.h"

 const char *GetStatusString()

The corresponding C, Visual Basic, and Delphi functions for GetStatusString() are ALArchiveGetStatusString(), ALCompressedGetStatusString(), ALCompressorGetStatusString(), ALDecompressorGetStatusString(), ALStorageGetStatusString(), and ALEntryListGetStatusString().

Arguments

None

Function

ALStatus::GetStatusString() translates an error code into an ASCII string, making it much easier to read.  Instead of returning an error code/number (e.g., -1987), this function returns a text string such as "File Open Error."  This message will usually be more meaningful to end users of your application.

The ASCII string to which the error code is translated should not be confused with the detailed error message.  The ASCII text consists of a two or three-word translation of the error code and provides no specific information about how or where the error occurred.

A sample code piece including GetStatusString() is shown below.

    sprintf( buffer, "Error status: %s", mStatus.GetStatusString() );

    cout << "Buffer status: " << buffer << endl;

Returns

ALStatus::GetStatusString() returns a string translating the error code.


GetStatusString() see also - ALStatus class
See Also

ALStatus::GetStatusDetail()


GetStatusString() example - ALStatus class
See example programs EX00PM.CPP, EX00WIN.CPP, and EX09CON.CPP.


operator=() - ALStatus class
ALStatus::operator=()

see also	example

Assignment operator for ALStatus class

Synopsis

#include "arclib.h"

 ALStatus &operator=( ALStatus &rhs )

Arguments

rhs

Reference to this (i.e., the object upon which the function is being performed)

Function

ALStatus::operator=() copies the object specified by the rhs argument into this (i.e., the object upon which the function is being performed).

A sample code piece including operator=() is shown below.

    ALStatus status;

    status = archive->mStatus;

Returns

ALStatus::operator=() returns a reference to the object upon which the function is being performed.


operator=() see also - ALStatus class
See Also

N/A


operator=() example - ALStatus class
N/A


operator int() - ALStatus class
ALStatus::operator int()

see also	example

Casting operator for ALStatus

Synopsis

#include "arclib.h"

 operator int()

The corresponding C, Visual Basic, and Delphi functions for operator int() are ALStorageGetStatusCode(), ALArchiveGetStatusCode(), ALEntryListGetStatusCode(), ALCompressorGetStatusCode(), ALDecompressorGetStatusCode(), and ALCompressedGetStatusCode().

Arguments

None

Function

ALStatus::operator int(), like GetStatusCode(), returns the integer status of the error code.  The integer is set to AL_SUCCESS when constructed.  If an error occurs, the host class will set this to an error code integer less than 0 (< 0).

A sample code piece including operator int() is shown below.

    if ( object.mStatus < AL_SUCCESS )

       cout << "Fubar\n";

Returns

ALStatus::operator int() returns an mStatus error code defined in the enumerated types located in ALDEFS.H.


operator int() see also - ALStatus class
See Also

ALStatus::GetStatusCode()


operator int() example - ALStatus class
N/A


SetError() - ALStatus class
ALStatus::SetError()

see also	example

Manipulate error code

Synopsis

#include "arclib.h"

 int SetError( int error, const char *fmt, ... )

The corresponding C, Visual Basic, and Delphi functions for SetError() are ALArchiveSetError(), ALCompressedSetError(), ALCompressorSetError(), ALDecompressorSetError(), and ALStorageSetError().

Arguments

int error

Numeric (integer) error code corresponding to one of the the error codes defined in ALDEFS.H

fmt

Pointer to the format specification to be passed to vsprintf() in creating a detailed error message

 ...

Additional arguments that will be passed to vsprintf() by this function

Function

ALStatus::SetError() is called when an error is detected for an object, and appears everywhere throughout ArchiveLib.  SetError() performs two actions:

•	First, it sets the error code for the object.

•	Secondly, it stores a copy of a detailed status message that was generated at the point where the error occurred.

You might use the SetError() function to abort an archiving operation.  See our Windows example programs for tips on how to accomplish this.

A sample code piece including SetError() is shown below.

    object.mStatus.SetError( AL_READ_ERROR, "No puedo leerlo" );

Returns

ALStatus::SetError() returns the numeric value passed in the error parameter.


SetError() see also - ALStatus class
See Also

ALStatus::GetStatusCode(), ALStatus::GetStatusString()


SetError() example - ALStatus class
See example programs EX00PM.CPP, EX00WIN.CPP, EX08CON.CPP, and EX15WIN.CPP.


ALTag##x()
ALTag##x::ALTag##x()

see also	example

Constructor for a member of the ALTag class family

Synopsis

#include "arclib.h"

 ALTag##x::ALTag##x()

Arguments

None

Function

ALTag##x::ALTag##x() is the constructor for one of the members of the ALTag class.  It assigns a non-zero value to the tag member, indicating that it is a legally constructed object.

This is a macro.  The single parameter, 'x', will be replaced by a tag that is unique to a particular class.  For example, using _ALMemoryTag creates a class called ALTag_ALMemoryTag.

Returns

None


ALTag##x() see also
See Also

ALTag##x::~ALTag##x()


ALTag##x() example
N/A


~ALTag##x()
ALTag##x::~ALTag##x()

see also	example

Destructor for a member of the ALTag class family

Synopsis

#include "arclib.h"

 ALTag##x::~ALTag##x()

Arguments

None

Function

ALTag##x::~ALTag##x() is the destructor for one of the members of the  ALTag class family.  It assigns the tag member mucTagVal a value of 0.  If a routine checks the tag member later, it will see that this is no longer a valid object.

Returns

None


~ALTag##x() see also
See Also

ALTag##x::ALTag##x()


~ALTag##x() example
N/A


GoodTag() - ALTag##x class
ALTag##x::GoodTag()

see also	example

Test ALTag class family data member for proper construction

Synopsis

#include "arclib.h"

 int ALTag##x::GoodTag()

Arguments

None

Function

ALTag##x::GoodTag() returns a binary value indicating whether the tag member mucTagVal has the correct value.  The tag value is unique to the parent class; it is assigned during construction and removed by the destructor.

A sample piece of code including GoodTag() is shown below.

int good = name->GoodTag();

wsprintf( buf, "%d", good );

SetDlgItemText( hDlg, AL_GOOD_TAG, buf );

Returns

ALTag##x::GoodTag() returns 1 if the tag member is valid, or 0 if a bad tag is detected.


GoodTag() see also - ALTag##x class
See Also

AL_ASSERT(), AL_ASSERT_OBJECT()


GoodTag() example - ALTag##x class
See example program EX19WIN.CPP.


AL_ASSERT()

see also	example

Check code for deleted objects, bad pointers

Synopsis

#include "_debug.h"

 AL_ASSERT( int condition, char *message )

Arguments

condition

A boolean variable or expression that specifies a condition that should always be true.  If the expression evaluates to false (which it should never do) the program will abort.

message

Character message that displays if the program aborts

Function

Assertions are one the best tools we have to root out bugs in the development process.  AL_ASSERT() runs a check on your code during debugging for various error conditions.  It is widely used inside the debug versions of ArchiveLib, and performs the same function as the C Runtime Library macro assert().  AL_ASSERT() operates by testing the condition in the first argument.  A good example of this might be in a function that is going to send a message to a text box:

int send_message( char *msg )

{

  AL_ASSERT( msg != NULL,

             "send_message called with NULL pointer!" );

This example will abort the program immediately if send_message() is ever called with a NULL pointer as an argument.

Like C's assert() function, AL_ASSERT() also adds the source file name and line number to the message it displays when exiting.  However,  unlike the C RTL assert(),  you can also add a problem-specific message in addition to that supplied by AL_ASSERT().  This makes it relatively easy to find the location where your program is not working properly.  A message for the example shown above would look like this:

Assertion error, ArchiveLib is aborting the application.

Condition = send_message called with NULL pointer!

File = SEND.CPP, line = 115

After displaying the message, the C abort() function is called to quickly exit your program.  The Windows version of AL_ASSERT() displays the same message in a message box.  It then exits by calling the Windows function FatalAppExit().

You may wonder if the proliferation of AL_ASSERT() function calls throughout ArchiveLib code will result in your system being bogged down with a lot of extra baggage.  Fortunately AL_ASSERT() can be told to disappear on command.  While the debug libraries are compiled so that all assertion macros are fully expanded, ArchiveLib's release versions are compiled with the NDEBUG macro defined.  This macro makes both AL_ASSERT(), its cousin, AL_ASSERT_OBJECT(), and the C Runtime Library assert() function disappear from the library.

Returns

None


AL_ASSERT() see also
See Also

AL_ASSERT_OBJECT()


AL_ASSERT() example
N/A


AL_ASSERT_OBJECT()

see also	example

Debug objects being passed as arguments

Synopsis

#include "_debug.h"

 AL_ASSERT_OBJECT( pointer, class, char* message )

Arguments

pointer

A pointer to an object of a class protected by ArchiveLib ObjectGuard

class

The class to which the object is supposed to belong

message

An error message to be displayed if the object turns out to be invalid

Function

Like AL_ASSERT(), AL_ASSERT_OBJECT() runs a check on your code during debugging for deleted objects and bad pointers.  It is used to verify conditions that are always true, and  immediately aborts your program if the condition is false.  AL_ASSERT_OBJECT() is, however, a highly specialized variant of our normal assertion code, designed to perform just one specific function: test the validity of objects passed as arguments to functions.

Most of the classes in ArchiveLib have a special data member that test for object validity; it is created using a macro that looks something like this: AL_CLASS_TAG(_ALclassnameTag) where classname is the name of the class where the data member resides.  This single-byte tag member is initialized with a special value (unique to its class) when the object is constructed, and erased when the object is destroyed.  Objects protected by ObjectGuard can test for the correct value of this object using the ALTag class family's GoodTag() function.

AL_ASSERT_OBJECT() takes advantage of the tag member mechanism to perform a quick validity check on objects passed as arguments to functions.  This usually means that a single call to AL_ASSERT_OBJECT() is made at the entry point to a function:

    int foo( ALArchive *archive )

    {

        AL_ASSERT_OBJECT( archive, ALArchive, "Bad archive pointer in foo()" );

AL_ASSERT_OBJECT() performs two checks on the object.

•	First, it calls the IsBadWritePtr() function provided by Windows.  (This check is skipped under DOS).

•	Second, it calls the GoodTag() member function for the particular object.

A failure of either one of these functions causes an assertion error, aborting the program.

Just like AL_ASSERT(), AL_ASSERT_OBJECT() is present but generates no code in the release versions of ArchiveLib.  You must compile with the NDEBUG macro defined; this changes the macro definition so that no code is generated.

This macro is particularly useful for the C, Visual Basic, and Delphi interface functions. Neither C nor Visual Basic have strong type-checking for object types, since their knowledge about objects is restricted to integer handles.  If a Visual Basic program inadvertently passes a bad pointer as an object handle, AL_ASSERT_OBJECT() will quickly detect the error and cause the program to immediately abort.

Returns

N/A


AL_ASSERT_OBJECT() see also
See Also

AL_ASSERT(), ALTag::GoodTag()


AL_ASSERT_OBJECT() example
N/A


FromJulian() - ALTimeDate class
ALTimeDate::FromJulian()

see also	example

Set day/month/year from Julian day number

Synopsis

#include "arclib.h"

 void ALTimeDate::FromJulian( long jdn )

 void ALStorageFromJulian( hALStorage this_object, long jdn )

 Declare Sub ALStorageFromJulian Lib "AL20LW" ( ByVal this_object&, ByVal jdn& )

 procedure ALStorageFromJulian( this_object : hALStorage; jdn : LongInt );

Arguments

this_object

A handle for (pointer to) an ALStorage object

jdn

Julian day

Function

ALTimeDate::FromJulian() sets the day, month, and year protected data members from Julian day format.

Returns

None


FromJulian() see also - ALTimeDate class
See Also

ALTimeDate::ToJulian()


FromJulian() example - ALTimeDate class
N/A


GetDosDate() - ALTimeDate class
ALTimeDate::GetDosDate()

see also	example

Convert the date portion of an ALTimeDate object to 16-bit DOS format

Synopsis

#include "arclib.h"

 unsigned short int ALTimeDate::GetDosDate()

 unsigned short int ALStorageGetDosDate( hALStorage this_object )

Arguments

this_object

A handle for (pointer to) the storage object for which you want to get the DOS date

Function

When we close a file that needs to have its time and date stamp set, we normally use the _dos_setftime() function to do the work.  It expects to see the date packed into a particular sequence of bits in an unsigned short.  That is what GetDosDate() does.

Returns

This function returns the date stored in this.  The bits of the date are packed into the form that is needed by the _dos_setftime() format.


GetDosDate() see also - ALTimeDate class
See Also

ALTimeDate::GetDosTime()


GetDosDate() example - ALTimeDate class
N/A


GetDosTime() - ALTimeDate class
ALTimeDate::GetDosTime()

see also	example

Convert the time portion of an ALTimeDate object to 16-bit DOS format

Synopsis

#include "arclib.h"

 unsigned short int ALTimeDate::GetDosTime()

 unsigned short int ALStorageGetDosTime( hALStorage this_object )

Arguments

this_object

A handle for (pointer to) the storage object for which you want to get the DOS time

Function

When we close a file that needs to have its time and date stamp set, we normally use the _dos_setftime() function to do the work.  It expects to see the time packed into a particular sequence of bits in an unsigned short.  That is what GetDosTime() does.

Returns

This function returns the time stored in this.  The bits of the time are packed into the form that is needed by the _dos_setftime() format.


GetDosTime() see also - ALTimeDate class
See Also

ALTimeDate::GetTimeDate(), ALTimeDate::SetTimeDate()


GetDosTime() example - ALTimeDate class
N/A


GetTimeDate() - ALTimeDate class
ALTimeDate::GetTimeDate()

see also	 example

Get time/date from C RTL format

Synopsis

#include "arclib.h"

 void ALTimeDate::GetTimeDate( struct tm *tblock )

void ALStorageSetTimeDateFromStruc( hALStorage this_object, struct tm * tblock )

Arguments

this_object

A handle for (pointer to) an ALStorage object

tblock

A structure in the format used by the C Runtime Library for storing time and date stamps

Function

ALTimeDate::GetTimeDate() converts the ArchiveLib format into the C Runtime Library format struct tm.

Returns

None


GetTimeDate() see also - ALTimeDate class
See Also

ALTimeDate::SetTimeDate(), ALTimeDate::GetDosTime(), ALTimeDate::GetDosDate()


GetTimeDate() example - ALTimeDate class
See example programs EX20PM.CPP and EX20WIN.CPP.


GetUnixTime() - ALTimeDate class
ALTimeDate::GetUnixTime()

see also	example

Extract the time/date of an object into UNIX format

Synopsis

#include "arclib.h"

 long ALTimeDate::GetUnixTime()

 long ALStorageGetUnixTime( hALStorage this_object )

 Declare Function ALStorageGetUnixTime Lib "AL20LW" ( ByVal this_object& ) As Long

 function ALStorageGetUnixTime( this_object : hALStorage ) : LongInt;

Arguments

this_object

A handle for (pointer to) an ALStorage object

Function

ALTimeDate::GetUnixTime() converts the internal time and date format used by ALTimeDate to 32-bit UNIX format.  UNIX time format is the number of seconds since "time 0",  defined as January 1, 1970 00:00:00 GMT.  An object's time and date are stored in an archive in UNIX format.

Returns

ALTimeDate::GetUnixTime() returns one of the following values:

Return Value	Meaning

number of seconds in 32-bit format	number of seconds since "time 0"

0	could not convert to UNIX format


GetUnixTime() see also - ALTimeDate class
See Also

ALTimeDate::SetTimeDate()


GetUnixTime() example - ALTimeDate class
See example programs EX20WIN.CPP and EX20PM.CPP.


SetTimeDate() 1 - ALTimeDate class
ALTimeDate::SetTimeDate()

see also	example

Convert time/date from C RTL format to ArchiveLib internal format

Synopsis

#include "arclib.h"

 void ALTimeDate::SetTimeDate( struct tm *tblock )

 void ALStorageSetTimeDateFromStruc( hALStorage this_object, struct tm * tblock )

Arguments

this_object

A handle for (pointer to) an ALStorage object

tblock

Pointer to the structure returned from the DOS function used to get a file's date and time

Function

ALTimeDate::SetTimeDate() converts the results of the C Runtime Library stat() function to ArchiveLib's internal date and time format.  Time and date are determined by stat() when a file is first opened.

A sample piece of code including SetTimeDate() is shown below.

file.mTimeDate.SetTimeDate( t );

Returns

None


SetTimeDate() 1 see also - ALTimeDate class
See Also

ALTimeDate::GetTimeDate()


SetTimeDate() 1 example - ALTimeDate class
See example programs EX18CON.CPP.


SetTimeDate() 2 - ALTimeDate class
ALTimeDate::SetTimeDate()

see also	example

Convert 32-bit time/date format to ArchiveLib internal format

Synopsis

#include "arclib.h"

 void ALTimeDate::SetTimeDate( long unix_time )

 void ALStorageSetTimeDateFromUnix( hALStorage this_object, long unix_time )

 Declare Sub ALStorageSetTimeDateFromUnix Lib "AL20LW" ( ByVal this_object&, ByVal unix_time& )

 procedure ALStorageSetTimeDateFromUnix( this_object : hALStorage; unix_time : LongInt );

Arguments

this_object

A handle for (pointer to) an ALStorage object

unix_time

32-bit UNIX date/time format

Function

ALTimeDate::SetTimeDate() converts a 32-bit UNIX time value to the correct values required by ALTimeDate's data member.  File time stamps are stored in an archive's directory using UNIX format.  SetTimeDate() is called when reading in the archive directory.

A sample piece of code including SetTimeDate() is shown below.

OutputFile.mTimeDate.SetTimeDate( l );

Returns

None


SetTimeDate() 2 see also - ALTimeDate class
See Also

ALTimeDate::SetTimeDate( struct tm *tblock )


SetTimeDate() 2 example - ALTimeDate class
See example programs EX18CON.CPP.


ToJulian() - ALTimeDate class
ALTimeDate::ToJulian()

see also	example

Convert month/day/year to the Julian day

Synopsis

#include "arclib.h"

 long ALTimeDate::ToJulian()

 long ALStorageToJulian( hALStorage this_object )

 Declare Function ALStorageToJulian Lib "AL20LW" ( ByVal this_object& ) As Long

 function ALStorageToJulian( this_object : hALStorage ) : LongInt;

Arguments

this_object

A handle for (pointer to) an ALStorage object

Function

ALTimeDate::ToJulian() converts the month, day, and year contained in the ALTimeDate object to the Julian day.  The Julian day is used to calculate UNIX time.

Returns

ALTimeDate::ToJulian() returns one of the following values:

Return Value	Meaning

long > 0	day, month, and year in Julian format

0	could not convert to Julian format


ToJulian() see also - ALTimeDate class
See Also

ALTimeDate::FromJulian()


ToJulian() example - ALTimeDate class
N/A


Valid() - ALTimeDate class
ALTimeDate::Valid()

see also	example

Checks to see if the time/date stamp is valid

Synopsis

#include "arclib.h"

 inline int ALTimeDate::Valid()

 int ALStorageValidTimeDate( hALStorage this_object )

 Declare Function ALStorageValidTimeDate Lib "AL20LW" ( ByVal this_object& ) As Integer

 function ALStorageValidTimeDate( this_object : hALStorage ) : Integer;

Arguments

this_object

A handle for (pointer to) the storage object that you want to check for validity

Function

ALStorage objects carry around a time/date stamp.  The time/date stamp is not valid until you either read it from the file system or from an archive.  Call ALTimeDate::Valid() to check if the time/date stamp you have is valid.

A sample piece of code including Valid() is shown below.

if ( obj->mTimeDate.Valid() )

   long t=obj->mTimeDate.GetUnixTime();

Returns

ALTimeDate::Valid() returns 1 if the time/date stamp is valid, or 0 if the time/date stamp is invalid.


Valid() see also - ALTimeDate class
See Also

ALTimeDate::GetTimeDate()


Valid() example - ALTimeDate class
See example program EX18CON.CPP.


ALWildCardExpander() 1
ALWildCardExpander::ALWildCardExpander()

see also	example

Constructor for ALWildCardExpander class

ALWildCardExpander functions that involve traversing directories are system-specific functions that run on MS-DOS, OS/2, Windows, or any Win32 system.  They will not port easily to other unsupported file systems.

Synopsis

#include "arclib.h"

#include "wildcard.h"

 ALWildCardExpander( const char *wild_file_list, int traverse_flag = 0, ALCase name_case = AL_LOWER )

 hALExpander newALExpander( char *wild_file_list, int traverse_flag, ALCase name_case )

 Declare Function newALExpander Lib "AL20LW"( ByVal wild_file_list$, ByVal traverse_flag%, ByVal name_case% ) As Long

 function newALExpander( wild_file_list : String; traverse_flag : Integer; name_case : Integer ) : hALExpander;

Arguments

wild_file_list

A list of wildcard file specifications, separated by commas, semicolons, or spaces.  It may look something like this: "*.CPP, BOB.DAT, *.*"

traverse_flag

A flag that indicates whether you want to traverse all subdirectories under the current path.  Under C++, this defaults to 0.  There are no default values for C, Visual Basic, and Delphi.

name_case

An indicator of whether you want all the returned file names forced to a certain case.  Under C++, this defaults to AL_LOWER.   There are no default values for C, Visual Basic, and Delphi.

Function

ALWildCardExpander::ALWildCardExpander() is the constructor for the ALWildCardExpander class.  The constructor for the expander has to set up data members that will be used during the expansion process.

Using the mCase member, all of the objects that are created can be forced to a certain case.

miTraverseFlag is a copy of the input parameter.

The mState variable keeps track of what is being done between function calls.

mInputLine stores a copy of the list of wildcard file specifications that are passed by the calling program.  Each time a new file name is taken out of mInputLine, it is removed from the ALName object.  This makes mInputLine just a little shorter.

The mResultFileName member is the storage for a copy  of the file name created by the expander.  This is a local copy.  When it gets returned to the calling program, you need to make your own copy of it and leave the local copy alone.

Every time the expander object is asked to get a new file, a check is made to see if the mpNextExpander member is pointing to a new expander object.  If it is, a request is made for the next file name.  If there are no file names left to give, it is destroyed and the pointer is set back to 0.

mpcDelimiters is a short string that is used to define all the characters that can be file name delimiters.  They are used to  separate file names in the input line.  By default, the delimiters are set to be spaces, tabs, or commas.  There is a second constructor for this object that lets users specify their own delimiter objects.

Every operating system has different ways to keep track of a wildcard expansion.  Rather than try to deal with that in here, the member function, ConstructOsData(), is called.  Various versions of this function will be linked in depending on which library is being built.

A sample code piece including the ALWildCardExpander constructor is shown below.

    ALWildCardExpander files( "*.DAT" );

Returns

There are no returns for C++ constructors.  C, Visual Basic, and Delphi return an hALExpander handle, which is passed as the this_object parameter to all ALWildCardExpander functions.


ALWildCardExpander() 1 see also
See Also

ALWildCardExpander::~ALWildCardExpander()


ALWildCardExpander() 1 example
See example programs EX01WIN.CPP.


ALWildCardExpander() 2
ALWildCardExpander::ALWildCardExpander()

see also	example

Create an ALWildCardExpander object with specific file name delimiters

Synopsis

#include "arclib.h"

#include "wildcard.h"

 ALWildCardExpander::ALWildCardExpander( const char *wild_file_list, const char *delimiters, int traverse_flag = 0, ALCase name_case = AL_LOWER )

 hALExpander newALExpanderWithDelimiters( char *wild_file_list, char *delimiters, int traverse_flag, ALCase name_case )

 Declare Function newALExpanderWithDelimiters Lib "AL20LW" ( ByVal wild_file_list$, ByVal delimiters$, ByVal traverse_flag%, ByVal name_case%) As Long

 function newALExpanderWithDelimiters( wild_file_list : String; delimiters : String; traverse_flag : Integer; name_case : Integer ) : hALExpander;

Arguments

wild_file_list

A list of wildcard file specifications, separated by commas, semicolons, or spaces.  It may look something like this: "*.CPP, BOB.DAT, *.*"

traverse_flag

A flag that indicates whether you want to traverse all subdirectories under the current path.  Under C++, this defaults to 0.  There are no default values for C, Visual Basic, and Delphi.

name_case

An indicator of whether you want all the returned file names forced to a certain case.  Under C++, this defaults to AL_LOWER.   There are no default values for C, Visual Basic, and Delphi.

delimiters

A character string that contains a list of characters that are used to delimit file names.  Specify this argument to use delimiters other than the defaults.

Function

This constructor is identical to the previous constructor, except for the addition of the delimiters argument.  This argument lets you specify delimiters other than the default for parsing your list of input file names.

A sample code piece including ALWildCardExpander() with delimiters, is shown below.

ALWildCardExpander ex( "Bob's Files\*.DOC", "" );

char *file = ex.GetNextFile();

cout << "Bob's first file: "

         << file

         << "\n";

Returns

There are no returns for the C++ constructor.  C, Visual Basic, and Delphi, return a handle that is synonymous with a pointer to this object.  The handle is passed as the this_object parameter to all ALWildCardExpander functions.


ALWildCardExpander() 2 see also
See Also

ALWildCardExpander::~ALWildCardExpander()


ALWildCardExpander() 2 example
See example program EX02MFC.CPP.


~ALWildCardExpander()
ALWildCardExpander::~ALWildCardExpander()

see also	example

Destructor for ALWildCardExpander class

ALWildCardExpander functions that involve traversing directories are system-specific functions that run on MS-DOS, OS/2, Windows, or any Win32 system.  They will not port easily to other unsupported file systems.

Synopsis

#include "arclib.h"

#include "wildcard.h"

 ALWildCardExpander::~ALWildCardExpander()

 void deleteALExpander( hALExpander this_object )

 Declare Sub deleteALExpander Lib "AL20LW" ( ByVal this_object& )

 procedure deleteALExpander( this_object : hALExpander );

Arguments

this_object

Handle to the ALWildCardExpander object

Function

ALWildCardExpander::~ALWildCardExpander() is the destructor for the ALWildcardExpander class.  It frees up all storage memory.  It also frees up any system resources in use, in order to support the current expansion.

A sample code piece including the ALWildCardExpander destructor, is shown below.

    ALWildCardExpander *expander =

       new ALWildCardExpander( "*.DAT, *.BAK, *.CPP" );

    .

    .

    .

    delete expander;

Returns

N/A


~ALWildCardExpander() see also
See Also

ALWildCardExpander::ALWildCardExpander()


~ALWildCardExpander() example
See example program EX10CON.CPP.


GetNextFile() - ALWildCardExpander class
ALWildCardExpander::GetNextFile()

see also	example

Return pointer to internal name of next storage object

ALWildCardExpander functions that involve expanding file names or traversing directories are system-specific functions that run on MS-DOS, OS/2, Windows, or any Win32 system.  They will not port easily to other unsupported file systems.

Synopsis

#include "arclib.h"

#include "wildcard.h"

 char *ALWildCardExpander::GetNextFile()

 char *ALExpanderGetNextFile( ALExpander this_object )

 Declare Function ALExpanderGetNextFile Lib "AL20LW" ( ByVal this_object& ) As String

 function ALExpanderGetNextFile( this_object : hALExpander ) : String;

Arguments

this_object

Handle to the ALWildCardExpander object

Function

ALWildCardExpander::GetNextFile() is called to expand the wildcard specification to produce a single file name.  It does this by returning a pointer to the internal name of the next storage object.

Returns

ALWildCardExpander::GetNextFile() returns a pointer to a string if it was successful.  A 0 or empty string is returned if no more file names were found.


GetNextFile() see also - ALWildCardExpander class
See Also

ALWildCardExpander::ALWildCardExpander()


GetNextFile() example - ALWildCardExpander class
See example programs EX01WIN.C, EX01VB.FRM, and EX01UNIT.PAS.


ALMonitor()
ALMonitor::ALMonitor()

see also	example

Constructor for ALMonitor class

Synopsis

#include "arclib.h"

 ALMonitor( ALMonitorType monitor_type )

There are no equivalent C, Visual Basic, or Delphi functions, since this constructor does not produce a useful object by itself.  Instead, C, Visual Basic, and Delphi users should call the constructor for the derived monitor classes (ALBarGraph, ALSpinner, ALWindowsMessage, and ALOs2Message) discussed later in this help file.

Arguments

monitor_type

Type of monitor.  Valid values are AL_MONITOR_OBJECT (to monitor an object, such as a file) or AL_MONITOR_JOB (to monitor an entire job).

Function

ALMonitor::ALMonitor() is the constructor for the ALMonitor class.  The base class ALMonitor, in itself, does not do anything useful so you will normally not instantiate an object of ALMonitor.  However, derived classes can call this constructor to initialize the miMonitorType data member.

A sample code piece including the ALMonitor constructor, is shown below.

class ALMyMonitor : public ALMonitor {

    public :

        ALMyMonitor() : ALMonitor( AL_MONITOR_OBJECTS ){ }

Returns

N/A


ALMonitor() see also
See Also

ALMonitor::~ALMonitor()


ALMonitor() example
N/A


~ALMonitor()
ALMonitor::~ALMonitor()

see also	example

Destructor for ALMonitor class

Synopsis

#include "arclib.h"

 ALMonitor::~ALMonitor()

 void deleteALMonitor( hALMonitor this_object )

 Declare Sub deleteALMonitor Lib "AL20LW" ( ByVal this_object& )

 procedure deleteALMonitor( this_object : hALMonitor );

Arguments

this_object

Handle to the ALMonitor object

Function

ALMonitor::~ALMonitor() is the destructor for the ALMonitor class.  Since this destructor is virtual, it will be called after the destructor for the derived class.  Like the base class constructor, it does not do anything.

A sample code piece for including ~ALMonitor() is shown below.

    ALMonitor *monitor = new ALBarGraph( AL_MONITOR_OBJECTS, cout );

    ALEntryList list( monitor );

    .

    .

    .

    archive.Create( list );

    .

    .

    .

    delete monitor;

Returns

N/A


~ALMonitor() see also
See Also

ALBarGraph::ALBarGraph(), ALSpinner::ALSpinner(), ALWindowsMessage::ALWindowsMessage(), ALOs2Message::ALOs2Message()


~ALMonitor() example
N/A


ArchiveOperation() - ALMonitor class
ALMonitor::ArchiveOperation()

see also	example

Monitor archive operation

This function is protected.  It should only be called by member functions of ALArchive, which is a friend class of ALMonitor.  End users won't call it.  We include it here in case you ever want to write your own monitor.  Should you decide to write your own monitor, you will need to create your own version of this function.

Synopsis

#include "arclib.h"

 void ALMonitor::ArchiveOperation( ALArchiveOperation operation, ALArchive *archive, ALEntry *job )

There are no equivalent C, Visual Basic, or Delphi functions for ArchiveOperation().  This is a virtual function that you must define when deriving a new class.

Arguments

operation

An enumerated type in the ALArchive class indicating the action that an ALArchive member function is about to perform.  Possible values are:

•	AL_ARCHIVE_OPEN

•	AL_ARCHIVE_CLOSE

•	AL_EXTRACTION_OPEN

•	AL_EXTRACTION_CLOSE

•	AL_INSERTION_OPEN

•	AL_INSERTION_CLOSE

•	AL_COPY_OPEN

•	AL_COPY_CLOSE

•	AL_START_DIRECTORY_WRITE

•	AL_END_DIRECTORY_WRITE

•	AL_START_DIRECTORY_READ

•	AL_END_DIRECTORY_READ

archive

Pointer to the archive object performing the operation

job

Pointer to a job in ALEntryList.  Note that this will be NULL during directory operation.

Function

ALMonitor::ArchiveOperation() provides a way to print messages such as "Inserting file.dat".  This function is called by ALArchive member functions during an archive operation; it is one of two functions you need to define for a derived monitor class (ALMonitor::Progress() is the other).  For more information, see the SPINNER.CPP or MONITOR.CPP files.

A sample code piece including ArchiveOperation() is shown below.

void MyMonitor::ArchiveOperation(

ALArchiveOperation operation,

ALArchive *archive,

ALArchiveEntry *job )

{

    switch ( operation ) {

        case AL_ARCHIVE_OPEN :

            printf( "Opening %s", ( char* ) archive->mName );

Returns

None


ArchiveOperation() see also - ALMonitor class
See Also

ALMonitor::Progress()


ArchiveOperation() example - ALMonitor class
See example program EX20CON.CPP.


Progress() - ALMonitor class
ALMonitor::Progress()

see also	example

Determine progress of archive operation

This function is protected.  It is typically called only from ALStorage::YieldTime().  The YieldTime() function is called whenever a LoadBuffer() or FlushBuffer() operation takes place.  End users normally will not call it.  We include it here in case you ever want to write your own monitor.  Should you decide to write your own monitor, you will need to create your own version of this function.

Synopsis

#include "arclib.h"

 void ALMonitor::Progress( long object_tell, ALStorage &object )

There are no equivalent C, Visual Basic, or Delphi functions for Progress().  This is a virtual function that you must define when deriving a new class.

Arguments

object_tell

Current offset of the file pointer in the storage object

object

Reference to the storage object being compressed, copied, or extracted

Function

ALMonitor::Progress() is called periodically by ALStorage::YieldTime() as a storage object is being compressed, decompressed, or copied.  Derived classes that implement this function can call ALMonitor::Progress() at the start of their function to calculate new and correct values for the miByteCount and miRatio data members.

A sample code piece including Progress() is shown below.

void MyMonitor::Progress( long,

                          ALStorage&)

{

    putc( '.', stdout );

Returns

None


Progress() see also - ALMonitor class
See Also

ALMonitor::ArchiveOperation()


Progress() example - ALMonitor class
See example program EX20CON.CPP.


ALMonitorSetJobSize()

see also	example

Indicate initial size of a monitored job

Synopsis

#include "arclib.h"

 long ALMonitorSetJobSize( hALMonitor this_job, long job_size )

 Declare Function ALMonitorSetJobSize Lib "AL20LW" ( ByVal this_object&, ByVal job_size& ) As Long

 function ALMonitorSetJobSize( this_object : hALMonitor; job_size : LongInt ) : LongInt;

C, Visual Basic, and Delphi programmers can access the data member mlJobSize using this function.  C++ programmers don't need to call this function since they can access the data member directly.

Arguments

this_object

Handle to the ALMonitor object

job_size

Size of the job being monitored

Function

ALMonitorSetJobSize() is called to initialize the mlJobSize member at the start of an archiving or copy job.  It is set to the total byte count of all of the objects that are going to be processed during the operation.  This object does not have to be initialized if the monitor is in the AL_MONITOR_OBJECT mode.

This initialization is done automatically by member functions in ALArchive.  You only need to do this yourself if you are using a monitor to track an operation of your own design.

ALMonitorSetJobSize() is used to indicate the total size of a job being monitored.  The value is stored in the monitor by whatever ALArchive member function is performing the work (e.g., Create()).  The ALArchive class is responsible for calculating this value so the monitor can use it to calculate the byte count and ratio.

A sample piece of code including ALMonitorSetJobSize() is shown below.

wsprintf( temp, "%ld", JobSize );

SetDlgItemText( hDlg, AL_PROGRESS_TEXT, temp );

JobSoFar = 0;

ALMonitorSetJobSize( hMonitor, JobSize );

ALMonitorSetJobSoFar( hMonitor, JobSoFar );

Returns

ALMonitorSetJobSize() returns the new value of the mlJobSize member.


ALMonitorSetJobSize() see also
See Also

ALMonitorSetObjectSize()


ALMonitorSetJobSize() example
See example programs EX21WIN.C and EX21VB.FRM.


ALMonitorSetJobSoFar()

see also	example

Calculate job size before completion

Synopsis

#include "arclib.h"

long ALMonitorSetJobSoFar( hALMonitor this_object, long job_so_far )

Declare Function ALMonitorSetJobSoFar Lib "AL20LW" ( ByVal this_object&, ByVal job_so_far& ) As Long

function ALMonitorSetJobSoFar( this_object : hALMonitor; job_so_far : LongInt ) : LongInt;

Arguments

this_object

Handle to the ALMonitor object

job_so_far

Total number of bytes processed so far

Function

At the conclusion of processing each object, this function can be called to update the total number of bytes processed so far.  This is done automatically in ArchiveLib by member functions of ALArchive (so you don't have to do it).  However, if you want to use a monitor in one of your own applications you will have to update this manually.

A sample piece of code including ALMonitorSetJobSoFar() is shown below.

wsprintf( temp, "%ld", JobSize );

SetDlgItemText( hDlg, AL_PROGRESS_TEXT, temp );

JobSoFar = 0;

ALMonitorSetJobSize( hMonitor, JobSize );

ALMonitorSetJobSoFar( hMonitor, JobSoFar );

Returns

ALMonitorSetJobSoFar() returns the new value of the mlJobSoFar member.


ALMonitorSetJobSoFar() see also
See Also

ALMonitorSetJobSize()


ALMonitorSetJobSoFar() example
See example programs EX21WIN.C and EX21VB.FRM.


ALMonitorSetObjectSize()

see also	example

Indicate the size of an object being monitored

Synopsis

#include "arclib.h"

 long ALMonitorSetObjectSize( hALMonitor this_object, long size )

 Declare Function ALMonitorSetObjectSize Lib "AL20LW" ( ByVal this_object&, ByVal object_size& ) As Long

 function ALMonitorSetObjectSize( this_object : hALMonitor; object_size : LongInt ) : LongInt;

Arguments

this_object

Handle to the ALMonitor object

object_size

Final size of an object

Function

ALMonitorSetObjectSize() is used to set the mlObjectSize member of a monitor.  ALArchive member functions, such as Create() and Extract(), automatically set this member so that you don't have to.  The ALArchive class is responsible for calculating this value so the monitor can use it to calculate the completion ratio.

You can set this value to the size of the object to be processed when performing an ArchiveLib operation.  If the object size is set to -1, the monitor will update it with the correct value after the storage object is opened.

A sample code piece including ALMonitorSetObjectSize() is shown below.

ALStorageSetMonitor( hFile, monitor );

ALMonitorSetObjectSize( monitor, -1 );

ALMonitorSetObjectStart( monitor, 0 );

result = ALStorageCompare(hFile,

     ALEntryGetStorage( job ) );

Returns

ALMonitorSetObjectSize() returns the value of the mlObjectSize member.


ALMonitorSetObjectSize() see also
See Also

ALMonitor::ALMonitorSetObjectStart()


ALMonitorSetObjectSize() example
See example programs EX04WIN.CPP and EX04VB.FRM.


ALMonitorSetObjectStart()

see also	example

Indicate initial size of a monitored object before completion

Synopsis

#include "arclib.h"

 long ALMonitorSetObjectStart( hALMonitor this_object, long object_start )

 Declare Function ALMonitorSetObjectStart Lib "AL20LW" ( ByVal this_object&, ByVal object_start& ) As Long

 function ALMonitorSetObjectStart( this_object : hALMonitor; object_start : LongInt ) : LongInt;

Arguments

this_object

Handle to the ALMonitor object

object_start

Starting position of a compressed object in an archive

Function

ALMonitorSetObjectStart() sets the value of the mlObjectStart member of a monitor.  Before performing an extraction or copy operation, ALArchive sets the starting position of an object in the mlObjectStart data member.  If you are using a monitor in an operation of your own design, you should call this function before you start processing each individual storage object.

A sample code piece including ALMonitorSetObjectStart() is shown below.

ALStorageSetMonitor( hFile, monitor );

ALMonitorSetObjectSize( monitor, -1 );

ALMonitorSetObjectStart( monitor, 0 );

result = ALStorageCompare( hFile, ALEntryGetStorage( job ) );

Returns

ALMonitorSetObjectStart() returns the new value of the mlObjectStart member.


ALMonitorSetObjectStart() see also
See Also

ALMonitorSetObjectSize()


ALMonitorSetObjectStart() example
See example programs EX04WIN.C and EX04VB.FRM.


ALStorageSetMonitor()

see also	example

Assign monitor to storage object

Synopsis

#include "arclib.h"

 void ALStorageSetMonitor( hALStorage this_object, hALMonitor monitor )

 Declare Sub ALStorageSetMonitor Lib "AL20LW" ( ByVal this_object&, ByVal monitor& )

 procedure ALStorageSetMonitor( this_object : hALStorage; monitor : hALMonitor );

Arguments

this_object

Handle to the ALStorage object

monitor

Monitor to be assigned to storage object

Function

ALStorageSetMonitor() dynamically assigns monitors to storage objects.  ALStorage objects each have a pointer to a monitor object.  This monitor is used to perform user interface functions during compression, extraction,and copying.  Normally you don't have to assign a monitor to a storage object since this is automatically handled by the ALArchive member functions.

This function is most useful when you are performing a manual operation, such as copying files one at a time.  You must also set the four member attributes of the monitor so the progress tracking is properly conducted.  If your monitor is in the AL_MONITOR_OBJECT mode, you only need to initialize two data members: mlObjectSize and mlObjectStart.

Destruction of the monitor is your responsibility-not the responsibility of the storage object.

A sample code piece including ALStorageSetMonitor() is shown below.

 	ALStorageSetMonitor( hFile, monitor );

 	ALMonitorSetObjectSize( monitor, -1 );

 	ALMonitorSetObjectStart( monitor, 0 );

 	result = ALStorageCompare(hFile, ALEntryGetStorage ( job ) );

Returns

None


ALStorageSetMonitor() see also
See Also

ALCompressor::Compress(), ALArchive::Extract()


ALStorageSetMonitor() example
See example programs EX04WIN.C and EX04VB.FRM.


ALBarGraph()
ALBarGraph::ALBarGraph()

see also	example

Constructor for ALBarGraph class

Synopsis

#include "arclib.h"

#include "bargraph.h"

 ALBarGraph( ALMonitorType monitor_type, ostream& stream = cout, int bar_length = 25 )

 hALMonitor newALBarGraph( enum ALMonitorType monitor_type )

Arguments

monitor_type

Type of monitor.  Valid values are AL_MONITOR_OBJECT (to monitor each individual object in a job, such as a file) or AL_MONITOR_JOB (to monitor an entire job).

stream

Reference to the I/O stream that will display the bar graph.  This is frequently cout.  Under C, the output stream will automatically be set to cout, which should be linked to stdout.

bar_length = 25

Number of characters in the progress bar.  For C++, the default is 25 characters.

There are no default parameter values for C.

Function

ALBarGraph::ALBarGraph() is the constructor for the ALBarGraph class.

A sample code piece including the ALBarGraph constructor is shown below.

    ALBarGraph monitor( AL_MONITOR_OBJECTS );

    ALEntryList;

Returns

The C++ constructor returns nothing.  The C version of this function returns a pointer to an ALMonitor object.


ALBarGraph() see also
See Also

ALSpinner::ALSpinner()


ALBarGraph() example
See example programs EX00CON.CPP and EX00CON.C.


~ALBarGraph()
ALBarGraph::~ALBarGraph()

see also	example

Destructor for ALBarGraph class

Synopsis

#include "arclib.h"

#include "bargraph.h"

 ALBarGraph::~ALBarGraph()

C programmers cannot call derived class functions directly.  To delete an ALBarGraph object in C, you must use deleteALMonitor(), described in ALMonitor::~ALMonitor().  That function will then call ALBarGraph::~ALBarGraph() using the C++ virtual function mechanism.

Arguments

None

Function

ALBarGraph::~ALBarGraph() is the destructor for ALBarGraph, destroying the ALBarGraph object.

A sample code piece for including ~ALBarGraph is shown below.

    ALBarGraph *monitor = new ALBarGraph(

AL_MONITOR_JOB );

    .

    .

    .

    delete monitor;

Returns

N/A


~ALBarGraph() see also
See Also

ALSpinner::~ALSpinner()


~ALBarGraph() example
N/A


ALSpinner()
ALSpinner::ALSpinner()

see also	example

Constructor for ALSpinner class

Synopsis

#include "arclib.h"

#include "spinner.h"

 ALSpinner( ALMonitorType monitor_type, ostream& stream = cout )

 hALMonitor newALSpinner( enum ALMonitorType monitor_type )

Arguments

monitor_type

Type of monitor.  Valid values are AL_MONITOR_OBJECT (to monitor an object, such as a file) or AL_MONITOR_JOB  (to monitor an entire job).

stream

Reference to the I/O stream that will display file names and propellers.  This is frequently cout.  Under C, the output stream will automatically be set to cout, which should be linked to stdout.

Function

ALSpinner::ALSpinner() is the constructor for the ALSpinner class, initializing the class's private data members, miSpinIndex and mrStream.

A sample code piece including this ALSpinner constructor, is shown below.

    ALSpinner monitor( AL_MONITOR_OBJECTS );

    ALEntryList list( monitor );

    .

    .

    .

    archive.Extract( list );

Another sample code piece for C++, including this ALSpinner constructor, is shown below.

    void foo( ALArchive *archive ) {

        ALSpinner monitor( AL_MONITOR_OBJECTS, cerr );

        ALEntryList list( monitor );

        archive->ReadDirectory( list );

        archive->Extract( list );

    } //destructor called implicitly here.

Returns

The C++ constructor returns nothing.  The C version of this function returns a pointer to an ALMonitor object.


ALSpinner() see also
See Also

ALSpinner::~ALSpinner()


ALSpinner() example
See example programs EX01CON.CPP and EX00CON.C.


~ALSpinner()
ALSpinner::~ALSpinner()

see also	example

Destructor for ALSpinner class

Synopsis

#include "arclib.h"

#include "spinner.h"

 ALSpinner::~ALSpinner()

C, Visual Basic, and Delphi programmers cannot call derived class functions directly.  To delete an ALSpinner object in C, Visual Basic, or Delphi, you must use deleteALMonitor(), described in ALMonitor::~ALMonitor().    That function will then call ALSpinner::~ALSpinner() using the C++ virtual function mechanism.

Arguments

None

Function

ALSpinner::~ALSpinner() is the destructor for the  ALSpinner class.  It does not do anything since the ALSpinner class does not contain any dynamically-created objects.

Returns

N/A


~ALSpinner() see also
See Also

ALSpinner::ALSpinner()


~ALSpinner() example
N/A


ALWindowsMessage()
ALWindowsMessage::ALWindowsMessage()

see also	example

Constructor for ALWindowsMessage class

Synopsis

#include "arclib.h"

#include "winmon.h"

 ALWindowsMessage( ALMonitorType monitor_type, HWND progress_text_window, ALWindowsMessageType message_type, HWND progress_number_window, UINT windows_message = 0 )

 hALMonitor newALWindowsMessage( enum ALMonitorType monitor_type, HWND progress_text_window, enum ALWindowsMessageType message_type, HWND progress_number_window, UINT windows_message )

 Declare Function newALWindowsMessage Lib "AL20LW" ( ByVal monitor_type%, ByVal progress_text_window%, ByVal message_type%, ByVal progress_number_window%, ByVal windows_message% ) As Long

 function newALWindowsMessage( monitor_type : Integer; progress_text_window : HWnd; message_type : Integer; progress_number_window : HWnd; windows_message : Integer ) : hALMonitor;

Arguments

monitor_type

Type of monitor.  Valid values are AL_MONITOR_OBJECT (to monitor an object, such as a file) or AL_MONITOR_JOB (to monitor an entire job).

progress_text_window

Window that receives text messages generated during processing of ArchiveOperation().

message_type

Message type.  Valid values are SEND_BYTE_COUNT (to send a byte count) or SEND_RATIO (to send a ratio of completion).

progress_number_window

Window to be updated with byte counts and ratios.

windows_message

The integer value of the message to be sent to the number_window along with the byte count and ratio.  For C++, the default is 0 (byte counts and ratios will be sent as text).  If a non-zero value is supplied, byte counts and ratios will be sent in the lParam and wParam fields of a Windows message.  To use a Windows 95 Progress Bar control, set this message to PBM_SETPOS, and set the message type to SEND_RATIO.  To use a Greenleaf ALGuage control, set this message to ALGuageSetPosition.

There are no default parameters for C, Visual Basic, and Delphi.

Function

ALWindowsMessage::ALWindowsMessage() is the constructor for the ALWindowsMessage class.

A sample code piece including the ALWindowsMessage constructor is shown below.

    ALWindowsMessage monitor( AL_MONITOR_JOB, GetDlgItem( hDlg, AL_PROGRESS_TEXT ),

                             	SEND_RATIO,

                              	GetDlgItem( hDlg, AL_PROGRESS_BAR ),

                            	ALGaugeSetPosition );

    ALEntryList list( monitor );

Returns

The C++ constructor returns nothing.  The C version of this function returns a pointer to an ALMonitor object.


ALWindowsMessage() see also
See Also

ALBarGraph::ALBarGraph()


ALWindowsMessage() example
See example programs EX00WIN.CPP, EX00WIN.C, EX00VB.FRM, and EX00UNIT.PAS.


~ALWindowsMessage()
ALWindowsMessage::~ALWindowsMessage()

see also	example

Destructor for ALWindowsMessage class

Synopsis

#include "arclib.h"

#include "winmon.h"

 ALWindowsMessage::~ALWindowsMessage()

C, Visual Basic, and Delphi programmers cannot call derived class functions directly.  To delete an ALWindowsMessage object in C, Visual Basic, or Delphi, you must use deleteALMonitor(), described in ALMonitor::~ALMonitor().  That function will then call ALWindowsMessage::~ALWindowsMessage() using the C++ virtual function mechanism.

Arguments

None

Function

ALWindowsMessage::~ALWindowsMessage() is the destructor for the ALWindowsMessage class.  It does not do anything.

A sample code piece including ~ALWindowsMessage() is shown below.

    ALMonitor *monitor = new ALWindowsMessage(

 	AL_MONITOR_JOB,

 	GetDlgItem( hDlg, AL_PROGRESS_TEXT ),

SEND_RATIO,

GetDlgItem( hDlg, AL_PROGRESS_BAR ),

ALGaugeSetPosition );

    .

    .

    .

    archive.Extract( list );

    delete monitor;

Returns

N/A


~ALWindowsMessage() see also
See Also

ALWindowsMessage::ALWindowsMessage()


~ALWindowsMessage() example
N/A


ALOs2Message()
ALOs2Message::ALOs2Message()

see also	example

Constructor for OS/2 PM monitor object

Synopsis

#include "arclib.h"

#include "pmmon.h"

 ALOs2Message::ALOs2Message( ALMonitorType monitor_type, HWND progress_text_window, ALWindowsMessageType message_type, HWND progress_number_window, UINT pm_message = 0 )

 hALMonitor newALOs2Message( ALMonitorType monitor_type, HWND progress_text_window, ALWindowsMessageType message_type, HWND progress_number_window, UINT pm_message  )

Arguments

monitor_type

AL_MONITOR_OBJECTS or AL_MONITOR_JOBS

progress_text_window

The handle of the window that is going to receive text messages during the archiving process

message_type

AL_SEND_RATIO or AL_SEND_BYTE_COUNT

progress_number_window

The window that is going to receive the number, which will either be the byte count or the percent complete ratio

windows_message

The message that will be sent to the progress number window.  When the message is sent, the number is sent in mp1 and mp2, so you can use whichever you prefer.  If this number is set to 0, the message is sent as text instead, using the set text call.

Function

This constructor accepts five parameters.  Four of them get copied into data members, while the fifth gets passed up to the constructor for the base class.

This type of monitor is used in Presentation Manager programs.  Our examples make use of it frequently.  It sends text messages to edit text controls, and sends numbers to either text controls or custom controls.

This monitor has special handling if the message sent is SLM_SETSLIDERINFO.  When this is the case, we assume the control is a slider.  We then calculate the length of the slider, so it can be updated in an orderly fashion.  Check some of the PM examples to see this in action.

Returns

The C++ constructor returns nothing.  The C version returns a pointer to a newly constructed monitor object.


ALOs2Message() see also
See Also

ALWindowsMessage::ALWindowsMessage()


ALOs2Message() example
See example program EX00PM.CPP.


~ALOs2Message()
ALOs2Message::~ALOs2Message()

see also	example

The PM monitor object destructor

Synopsis

#include "arclib.h"

#include "pmmon.h"

 ALOs2Message::~ALOs2Message()

Arguments

None

Function

The ~ALOs2Message destructor destroys the ALOs2Message objects.

Returns

N/A


~ALOs2Message() see also
See Also

ALWindowsMessage::ALWindowsMessage()


~ALOs2Message() example
N/A


CenterWindow()

see also	example

Center a window on the screen

Synopsis

#include "arclib.h"

#include "pmutil.h"

 extern "C" void CenterWindow( HWND hwnd )

 void CenterWindow( HWND hwnd )

Arguments

hwnd

The handle of the window to be centered

Function

CenterWindow() centers a window on the screen under OS/2.

A sample piece of code including CenterWindow() is shown below.

switch ( msg ) {

      case WM_INITDLG :

TrimSystemMenu( hwndDlg );

CenterWindow( hwndDlg );

break;

Returns

None


CenterWindow() see also
See Also

SetupSlider()


CenterWindow() example
See example program EX17PM.CPP.


SetupSlider()

see also	example

Setup up a control to work with a monitor

Synopsis

#include "arclib.h"

#include "pmutil.h"

 extern "C" int SetupSlider( HWND hDlg, int slider_id, int draw_ticks )

 int SetupSlider( HWND hDlg, int slider_id, int draw_ticks )

Arguments

hDlg

If slider_id is equal to -1, this argument is the window handle for the slider control.  If slider_id is not -1, this argument is a dialog box handle that contains the slider control.

slider_id

The dialog ID of the slider control.  It is -1 if hDlg contains the actual handle of the slider control.

draw_ticks

A boolean flag indicating whether or not this routine should draw tick marks on the slider control

Function

If you are going to use a slider control as a monitor, this routine will do a few things that help make it look better.

First, the slider is modified so it has 10 intervals.  The slider will change size from 0 to 10 until the process is complete.

Next, the shaft of the slider is widened to 20 pixels.

Finally, a set of tick marks is drawn along the slider, if requested.

You should make the slider control wide to accommodate the tick marks.  Use your resource editor to look at the sliders in the OS/2 examples for an idea of the width.  Also, pin the shaft against the bottom or right hand side of the slider so there is room for tick marks in the upper or left hand side.

A sample piece of code including SetupSlider() is shown below.

ReadDir( hwnd );

ReadArchive( hwnd );

SetupSlider( hwnd, AL_PROGRESS_BAR, 1 );

Returns

SetupSlider() returns 1 if successful, or 0 if unsuccessful.


SetupSlider() see also
See Also

CenterWindow(), TrimSystemMenu()


SetupSlider() example
See example program EX01PM.CPP.


TrimSystemMenu()

see also	example

Trim most of the options from the system menu

Synopsis

#include "arclib.h"

#include "pmutil.h"

 extern "C" void TrimSystemMenu( HWND hwnd )

 void TrimSystemMenu( HWND hwnd )

Arguments

hwnd

The handle of the window whose system menu needs to be trimmed

Function

This is a useful function for removing some of the clutter from the system menu.  It removes all of the default entry menu items, except for the Close and Move options.

A sample piece of code including TrimSystemMenu() is shown below.

switch ( msg ) {

       case WM_INITDLG :

TrimSystemMenu( hwndDlg );

CenterWindow( hwndDlg );

break;

Returns

None


TrimSystemMenu() see also
See Also

CenterWindow()


TrimSystemMenu() example
See example program EX01PM.CPP.


Zork

You are [image] a maze of [image] y passages all alike.


French

Bien venue à le secret!  C'est chouette, non?


 Tech Support

With each product purchased, you receive thirty (30) days of technical support FREE.  Your free 30 days begins with  your first call to Tech Support.  During the 30 days, you may call in at 214-248-2561 and receive unlimited technical support.  After the 30 days, you can choose between the following methods of support (or combine Options 1 and 2).

Tech Support Options

1.  Online Support	Technical support is offered FREE throught the BBS, Internet, CompuServe, or FAX.

2.  Professional Support	This level offers you the ability to call in on a toll-free 800 number.  Using a major credit card, the cost for Tech Support will be $2 per minute.

3.  Premier Support	Our new Premier Support option gives you unlimited telephone support on a toll-free line and a toll-free 800 number for the Greenleaf BBS - as many times as you require throughout the year.  The cost for Greenleaf Premier Support is $300 per product per year.

Hours

Monday - Friday

8:00 am - 5:00 pm

Central Standard Time

Important Numbers and Addresses

30-Days Free Support	214-248-2561

Professional Support Toll-Free Line	800-771-2757

Greenleaf Premier Toll-Free Line	800-523-9830

Greenleaf FAX	214-248-7830

Greenleaf BBS	214-250-3778

e-mail Address	support@gleaf.com

Web Page	http://www.gleaf.com/~gleaf

CompuServe	GO GREENLEAF