WinCat/PRO Open Systems Developers Toolkit

WinCat/PRO is todays most advanced disk and CD-ROM catalog program for Windows.
To enable other (Pascal) programmers to create add-ons and utility-programs for use with 
WinCat/PRO, the author of WinCat/PRO has created the WINCATOS package ; its routines and 
definitions make it easy to access the information in WinCat/PRO catalogs. 

You may use the routines from WINCATOS.TPU, the definitions in DEFS.PAS and the sample 
code in OSTEST.PAS in your own programs under the following conditions :

*  The WINCATOS routines and definitions are supplied 'as is', without any guarantees 
   regarding functionality or compatibility with future WinCat/PRO releases;
*  You may freely distribute your program as either Freeware or Shareware ;
   In your programdocumentation you must add this statement : WINCAT/PRO Disk & CD-Rom 
   Catalog and WINCATOS catalog interface routines (c) 1992-1995 Mart Heubel, Heerlen, The 
   Netherlands;
*  Thou shall not name your program WINCAT or WINCATnn, where nn = 00-99;
*  Using WINCATOS.TPU in commercial products is not allowed without the prior written 
   permisson of the author;
*  Because the author doesn't have all the time in the world : please do not contact the author 
   for additional information or questions regarding the use of WINCATOS. The supplied 
   information is sufficient (with a little figuring out and experimenting) for experienced Pascal 
   programmers to make use of WINCATOS.
*  The routines in WINCATOS.TPU support catalogs created by the current WinCat/PRO 4.0 
   version and all previous versions.  
*  WINCATOS.TPU has been compiled with Borland Turbo Pascal for Windows version 1.5   



Functional description of the routines in WINCATOS.TPU : 


function CreateCIB:CIBPtr
--------------------------
Creates and initializes a Catalog Information Block (CIB) structure and associated tables, and 
returns pointer to the CIB.
You must call CreateCIB before calling any other catalog interface routine. 
Before terminating, your program must delete every created CIB with the PurgeCIB service.
See below for a description of the CIB.


procedure PurgeCIB(CIB:CIBPtr)
------------------------------
Purges the CIB and all associated tables.


procedure ReadCatalog(CIB:CIBPtr)
---------------------------------
Opens, reads and closes a catalog who's name is in CIB^.CatalogName.
Before calling this function, you must create the CIB with CreateCIB, and then specify the 
catalogs name in CIB^.CatalogName.
 
Upon completion, the CIB^.Status field contains the ReadCatalog return code.
If the returncode is 0, the following CIB fields are valid :
Total_Volumes		: number of volumes in catalog
Total_Files		: number of files in catalog
Total_Used		: total used space on volumes
Total_Free		: total free space on volumes
CatalogSize		: catalogsize in bytes
Volume_Table		: - see below -
Total_Groups		: number of Group-ID's in Grp_Table
Total_Locations	: number of Location-ID's in Loc_Table
Total_Owners		: number of Owner-ID's in Own-table
Grp_Table		: pointer to chain of Group identifiers
Loc_Table		: pointer to chain of Location identifiers
Own_Table		: pointer to chain of Owner identifiers


procedure SortVolumeTable(CIB:CIBPtr; SortOrder:word)
-----------------------------------------------------
Sorts the entries in CIB^.Volume_Table in the order selected by SortOrder:
VSO_Volume		by volume-id
VSO_Group		by group-id
VSO_FreeSpaceA	by free space, ascending
VSO_FreeSpaceD	by free space, descending


procedure SelectVolumes(CIB: CIBPtr; Function:word)
---------------------------------------------------
If Function = VSL_Clear, the CIB^.SV_x selection fields are cleared ; the SV_Total_x fields are 
reset to zero, and all Vol^.Sel fields are set to TRUE. 

If Function = VSL_Select, all volumes that match the CIB^.SV_x selection criteria will be 
selected (by setting Vol^.Sel to TRUE). 
You must specify at least one of these selection fields :
CIB^.SV_Group		the Group ID (maximum length 8 characters)
CIB^.SV_Owner		the Owner ID (maximum length 8 characters)
CIB^.SV_Location	the Location ID (maximum length 8 characters)
CIB^.SV_DiskType	the disks mediatype (1 character)
CIB^.SV_FreeSpace	the minimum amount of free space in KB 

Upon completion, the following CIB^.SV_x fields are updated : 
CIB^.SV_Total_Volumes 	: number of volumes selected
CIB^.SV_Total_Files	: number of files on selected volumes
CIB^.SV_Total_Used	: total used space on selected volumes
CIB^.SV_Total_Free	: total free space on selected volumes



procedure SelectFiles(CIB:CIBPtr; Function:word)
------------------------------------------------
If Function = FSL_Clear, the CIB^.SF_x file selection fields are cleared ; SF_Total_Files is reset 
to zero.

If Function = FSL_Select, all files (on selected volumes) that match the CIB^.SF_x selection 
criteria are selected by adding a pointer to them in CIB^.SF_File_Table.
You must specify at least one of these file selection fields :
CIB^.SF_Filename	(partial) filename (maximum length 8 characters)
CIB^.SF_Extension	(partial) extension (maximum length 3 characters)
CIB^.SF_Directory	(partial) directory name (maximum length 36 characters)
CIB^.SF_Comment	string to look for in comment fiels (maximum length 20 characters)
CIB^.SF_Size		minimum size in KB
CIB^.SF_Date		date value ; you must also specify DateFlag when using this field
CIB^.SF_DateFlag	one of : SFD_Before, SFD_On, SFD_After or SFD_Until 
CIB^.SF_Range		date range value ; you must also specify SF_Date and SF_DateFlag = 
			SFD_Until

Upon completion, the CIB^.SF_File_Table contains pointers (with a maximum of 5000) to the 
selected files.
The following CIB^.SF_ x fields are updated :
SF_Total_Files		: number of selected files

You can sequentially access all files in the CIB^._SF_File_Table like this :
For I := 1 to CIB^.SF_Total_Files do
begin
    Fil := CIB^.SF_File_Table^[I];
    { do something with file }
end;


procedure SortFileTable(CIB:CIBPtr; SortOrder:word)
---------------------------------------------------
Sorts the files in CIB^.SF_File_Table in the order selected by SortOrder:
FSO_Filename		by filename
FSO_Extension		by extension
FSO_Volume		by volume-ID
FSO_Directory		by directory
FSO_DateD		by date, descending 
FSO_DateA		by date, ascending
FSO_SizeD		by size, descending
FSO_SizeA		by size, ascending



The CIB^.Volume_Table
---------------------

After completion of the ReadCatalog routine, the Volume_Table contains a pointer to a table, 
which contains Total_Volumes (but with a maximum of 1000) pointers of type VolPtr.

Each VolPtr points to a volume structure ; if Vol is a valid VolPtr, then you can access these 
fields :
Vol^.PPtr		PatPtr pointer to first entry in directory chain
Vol^.FPtr		FilPtr pointer to first entry in file chain	
Vol^.Sel		if true, volume was selected by SelectVolumes service
Vol^.VRec.lbl		volume label
Vol^.VRec.fre		free space on this volume
Vol^.VRec.usd		used space on this volume
Vol^.VRec.fil		number of files on this volume
Vol^.VRec.pat		number of directories on this volume
Vol^.VRec.dat		date volume was cataloged
Vol^.VRec.grp		group-id
Vol^.VRec.own		owner-id
Vol^.VRec.loc		location-id
Vol^.VRec.act		name of corresponding .ACT file
Vol^.VRec.drv		drive-id from which this volume was cataloged
Vol^.VRec.med		media-descriptor (disktype)


The volumes directories are stored in a single-linked chain of entries of type PatPtr.
The volumes Vol^.PPtr field points to the first entry in this chain.

If Pat is a valid PatPtr, you can access these fields :
Pat^.VPtr		VolPtr pointer to corresponding volume
Pat^.Link		PatPtr pointer to next entry in chain, or nil if last entry
Pat^.Trd 		FilPtr pointer to first file in this directory
Pat^.PRec.pat		directory-name
Pat^.PRec.siz		total size of files in this directory
Pat^.PRec.fil		number of files in this directory

The volumes files are stored in a single-linked chain of entries of type FilPtr.
The volumes Vol^.FPtr field points to the first entry in this chain.

If Fil is a valid FilPtr, you can access these fields :
Fil^.VPtr		VolPtr pointer to corresponding volume
Fil^.PPtr		PatPtr pointer to corresponding directory
Fil^.Link		FilPtr pointer to next entry in chain, or nil if last entry
Fil^.Trd		FilPtr pointer to next file in same directory, or nil if last entry
Fil^.Com		PChar pointer to files description, or nil if not present
Fil^.FRec.nam		Filename
Fil^.FRec.siz		File size
Fil^.FRec.dat		Date last modified
Fil^.FRec.tim		Time last modified




General routines

function ConvDate(Date:integer; Format:word): string
----------------------------------------------------
Converts a numeric date to a string dd-mm-yy (if Format = DF_ddmmyy) or mm-dd-yy (if 
Format = DF_mmddyy).

function ConvTime(Time:integer): string
---------------------------------------
Converts a numeric time to a string hh:mm:ss. 

function GetDiskType(Med:char): string
--------------------------------------
Converts a disks mediatype (Vol^.VRec.med) to a string.
This function supports these mediatypes :
(5.25 disks)
chr(254)	GetDiskType :='5.25" 160 KB'
chr(255)	GetDiskType :='5.25" 320 KB'
chr(252)	GetDiskType :='5.25" 180 KB'
chr(253)	GetDiskType :='5.25" 360 KB'
chr(233)	GetDiskType :='5.25" 1.2 MB'
(3.5" disks)
chr(249)	GetDiskType :='3.5" 720 KB'
chr(240)	GetDiskType :='3.5" 1.44 MB'
chr(241)	GetDiskType :='3.5" 2.88 MB'
(others)
chr(248)	GetDiskType :='Stacker'
chr(247)	GetDiskType :='HardDisk'
chr(67)		GetDiskType :='CD-ROM'
chr(63)		GetDiskType :='Floptical'


Notes
-----
All string-fields are null-terminated ; you must include TPU STRINGS in your program.
Be aware of each fields maximum length ; see file DEFS.PAS for field-definitions.    








