CATraxx can act as an OLE Automation Server accessible from any automation client, such as Delphi, Visual Basic, or Perl. This allows you to programmatically generate HTML and XML documents, explore data in the Explore window, open data entry windows, activating a specific view and selecting a specific record, etc.

The class name is CATraxx.DataServer.

You can choose to either connect to a running instance (of CATraxx), or start a new instance (with no visible UI). Note that you must call the new Quit method when closing the connection to the server if you created a new instance. Also note that if you create a new instance, the last used database is not opened automatically (you must manually set the Database property to open the database).

In Delphi, if you use early binding, use the ConnectKind property to control this (ckNewInstance, ckRunningInstance or ckRunningOrNew). You can set the AutoQuit property to automatically call Quit when you close the connection to the server. If you use late binding, use GetActiveOleObject to connect to the running instance of CATraxx. CreateOleObject will always create a new instance.

Delphi example:

var
C: Variant;
XMLFile: String;
HTMLFile: String;
begin

// Create a new instance of the server
C := CreateOleObject('CATraxx.DataServer');

// Open database
C.Database := 'C:\Program Files\CATraxx\Data\Sample.mdb';
XMLFile := 'C:\My Documents\Data.xml';
// XML file - All artists
C.GenerateXML('Artist', '', XMLFile);
// XML file - All albums by U2
C.GenerateXML('Album', 'Artist=U2', XMLFile);
// XML file - All Live tracks
C.GenerateXML('Track', 'Live=True', XMLFile);
HTMLFile := 'C:\My Documents\Doc.html';
// HTML file - Album ID = 1
C.GenerateHTML('AlbumBrowse.xsl', 'ID=1', False, HTMLFile, '');
// HTML file - Albums by U2
C.GenerateHTML('AlbumList.xsl', 'Artist=U2', False, HTMLFile, '');
// HTML file - All live tracks
C.GenerateHTML('TrackList.xsl', 'Live=True', False, HTMLFile, '');

// Generate m3u playlist based on playlist #1

C.GenerateM3UPlaylist(1, 'C:\My Documents\Playlist.m3u');

// Generate m3u playlist with all U2 albums in chronological order

C.GenerateM3UPlaylistFilter('Album.Artist=U2@orderby=Album.Released,Track.Position', 'C:\My Documents\Playlist.m3u');

// Play album #1 - enqueue

C.PlayAlbum(1, True);

// Play boxset #1 - enqueue

C.PlayBoxSet(1, True);

// Play all U2 albums sorted by release date - do not enqueue

C.PlayFilter('Album.Artist=U2@OrderBy=Track.Released', False);

// Display the index page in the Explorer window

C.Explore('Index.xsl', '');

// Display album 100 in the Explorer window

C.Explore('Album.xsl', 'ID=100');

// Display all U2 albums in the Explorer window

C.Explore('AlbumList.xsl', 'Artist=U2');

// Edit album 100

C.EditRecord('Album', 100);

// Since we created a new instance we need to call Quit

C.Quit;
end;

Properties

Database (String)

The path to the database you want to work with.

EditWindowOpen (Boolean)

Returns True if a data entry window is open.

ExtractImages (Boolean)

When set to True, all images are extracted and saved to the temp folder, and the IMG SRC tag contains the actual file path. When set to False, a special code is added to the IMG SRC tag, and you must use the GetImage method to extract the image.

ImageFileCount (Integer)

The number of image files in the temp folder. Use the ImageFileGet method to access the files.

ImageFileAutoDelete (Boolean)

When set to True, image files saved to the temp folder (when ExtractImages is True) are automatically deleted when a new html page is generated (or the data server shuts down). When set to False, you are responsible for deleting the image files.

TempFolder (String)

The path to the temp folder where all temporary files are created. By default, this is the default Windows Temp folder. You can change this if you like.

TemplateFolder (String)

The path to the template folder as specified under Tools->Explorer Templates. This is a read-only property.

UseExternalImageFilename (Boolean)

When set to True, the path to an external image file is stored directly in the IMG SRC tag. When False, external images are treated the same way as internal images.

Version (String)

The CATraxx version number (for example "8.00").

Methods

ActiveRecord

Returns the record id of the active record in the browse list according to the table you specify. For example, to get the album id of the active album in the Album View, call ActiveRecord('Album'). To get the playlist id of the active playlist in the Playlist View, call ActiveRecord('Playlist'). An exception is raised if the view is not open.

Parameters:

Table (String) - The table name.

Return value (Integer): The id number of the active record. -1 is returned if no record is active.

ChangeSortOrder

Call this method to change the sort order of a recordset (list with multiple records).

Parameters:

RecordsetGUID (String - by reference) - This is the GUID of the recordset. The GUID was originally created when you called the GenerateHTML method to generate the first page of the recordset. Note that a new GUID is created when you call ChangeSortOrder to change the sort order.

OrderBy (String) - The new sort order. For example "Artist, Released" or "Title".

Filename (String - by reference) - The full path to the location where the HTML file is saved. If you pass an empty string, the data server will create a file in the temp folder.

NOTE: You must delete this file when it is no longer needed. The data server will not delete the generated HTML file when it shuts down.

CloseEditWindow

This will close the open data entry window. Any changes are automatically saved.

EditRecord

Call this method to edit a record in the standard data entry window.

Parameters:

Table (String) - The table name.

Record ID (Integer) - The record number.

Return value (Integer): The window handle of the data entry window.

Explore

Call this method to explore data in the Explorer window.

Parameters:

XSLTemplate (String) - The name of the xsl template to use.

Filter (String) - This is the filter that determines what information is displayed. Use the same format as filter parameters in xsl templates. For example "ID=1" or "Artist=U2".

Return value (Integer): The window handle of the explorer window.

GenerateHTML

Call this method to generate a HTML file.

Parameters:

XSLTemplate (String) - The name of the xsl template to use.

Filter (String) - The filter determines what information is included in the HTML file. Use the same format as filter parameters in xsl templates. For example "ID=1" or "Artist=U2".

StipLinks (Boolean) - If True, all hyperlinks are removed.

Filename (String - by reference) - The full path to the location where the HTML file is saved. If you pass an empty string, the data server will create a file in the temp folder.

NOTE: You must delete this file when it is no longer needed. The data server will not delete the generated HTML file when it shuts down.

RecordsetGUID (String - by reference) - When creating a list page based on a recordset (multiple records), this parameter holds the recordset GUID (an unique ID number) after the method has been called. You need to use this ID when creating other pages in the same recordset (see GenerateHTMLListPage) or if you want to change the sort order (see ChangeSortOrder).

Return value (Integer): Total number of pages. This is always 1 if you create a single record page, or is else the total number of pages in a recordset list.

GenerateHTMLListPage

Call this method to generate a new page based on a recordset.

Parameters:

RecordsetGUID (String) - This is the GUID of the recordset. This is created when you call the GenerateHTML method to generate the first page of the recordset.

PageNo (Integer) - The page number.

Filename (String - by reference) - The full path to the location where the HTML file is saved. If you pass an empty string, the data server will create a file in the temp folder.

NOTE: You must delete this file when it is no longer needed. The data server will not delete the generated HTML file when it shuts down.

GenerateM3UPlaylist

Call this method to generate a M3U playlist file based on a playlist.

Parameters:

PlaylistID (Integer) - The playlist ID number.

Filename (String - by reference) - The full path to the location where you want to save the file. If you pass an empty string, the data server will create a file in the temp folder.

GenerateM3UPlaylistFilter 

Call this method to generate a M3U playlist file dynamically based on a filter.

Parameters:

Filter (String) - The filter, and sort order if you want to change the default sort order. Use the same format as filter parameters in xsl templates. For example "Track.Artist=U2@orderby=Track.Title" or "Album.Released=2011@OrderBy=Track.Artist,Track.Title". Make sure you also reference the table name.

Filename (String - by reference) - The full path to the location where you want to save the file. If you pass an empty string, the data server will create a file in the temp folder.

GenerateXML

Call this method to generate a XML data file.

Parameters:

Table (String) - The table the data is taken form (for example "Album" or "Artist").

Filter (String) - The filter determines what information is included in the XML file. Use the same format as filter parameters in xsl templates. For example "Format=LP" or "Artist=U2".

Filename (String - by reference) - The full path to the location the XML file is saved. If you pass an empty string, the data server will create a file in the temp folder.

Return value (Integer): Total number of records in the XML file.

NOTE: You must delete this file when it is no longer needed. The data server will not delete the generated HTML file when it shuts down.

GetImage

When the ExtractImages property is False, you must pass the IMG SRC tag from the generated HTML page to the method to extract the image.

Parameters:

SRC (String) - The IMG SRC tag (for example "*I:Album,1,1,2").

Filename (String - by reference) - The full path to the location where you want to save the image. If you pass an empty string, the data server will create the file in the temp folder.

NOTE: You must delete this file when it is no longer needed. The data server will not delete the saved image file when it shuts down.

GotoRecord

Call this method to select a record in the browse list. The correct view is automatically activated.

Parameteres:

Table (String) - The table name.

Record ID (Integer) - The record number. Pass a record id of -1 to only activate a specific view without changing the active record.

NOTE: You can not call this method if modal window is open (for example a data entry window). An exception is raised if the view has not been opened.

ImageFileGet

Returns the path to the specified image file in the temp folder.

Parameters:

Index (Integer) - The index of the image (this is zero based). Use the ImageFileCount property to access the total number of images.

Filename (String - by reference) - The parameter hold the full path to the image after you have called the method.

PlayAlbum

Plays the audio files linked to the specified album.

Parameters:

AlbumID (Integer) - The ID number of the album.

Enqueue (Boolean) - Whether to enqueue the tracks or not.

PlayBoxSet

Plays the audio files linked to the specified box set.

Parameters:

BoxSetID (Integer) - The ID number of the box set.

Enqueue (Boolean) - Whether to enqueue the tracks or not.

PlayFilter

Will select tracks to play according to the specified filter. The syntax is the same as the "PLAYFILTER" explorer command; The filter string can contain the following instructions: Filter, Sort Order, Max Records, Random and Shuffle.

Some examples:

To play all tracks by U2:

Track.Artist=U2

To play all tracks by U2, sorted by release date:

Track.Artist=U2@OrderBy=Track.Released

To play the 25 oldest U2 songs:

Track.Artist=U2@OrderBy=Track.Released@Max=25

To pick 25 of the songs at random (still sorted by Released):

Track.Artist=U2@OrderBy=Track.Released@Max=25@Random=Yes

To shuffle the playlist:

Track.Artist=U2@Max=25@Random=Yes@Shuffle=Yes

And finally, select one U2 album at random:

Album.Artist=U2@Max=1@Random=Yes

Parameters:

FilterSRC (String) - The filter string.

Enqueue (Boolean) - Whether to enqueue the tracks or not.

PlayPlaylist

Plays the specified playlist.

Parameters:

PlaylistID (Integer) - The ID number of the playlist.

Enqueue (Boolean) - Whether to enqueue the playlist or not.

PlayTrack

Plays the audio file linked to the specified tracak.

Parameters:

TrackID (Integer) - The ID number of the track to play.

Enqueue (Boolean) - Whether to enqueue the track or not.

Quit

If you created a new instance of the server, call this method before you disconnect from the server. If not, the server will not shut down!

RefreshView

Refreshes the specified view (or the Explorer window). An exception is raised if the view is not open.

Parameters:

Table (String) - The table name. Use 'Explorer' to refresh the Explorer View, use 'ExplorerWindow' to refresh the Explorer window.

RefreshRecordset (Boolean) - If True, both the recordset/list and the explorer pane is refreshed. If False, only the explorer pane is refreshed.

SelectedRecords

This method returns the record id numbers of the selected records in the active view. For example "2,632,43,23,12".

TagAlbum

Tags the audio files linked to the specified album.

Parameters:

AlbumID (Integer) - The record id of the album to tag.

DiscNo (Integer) - The disc no to tag. Specify -1 to tag all discs.

TagTrack

Tags the audio file linked to the specified track.

Parameters:

TrackID (Integer) - The record id of the track to tag.

TemplateType

This returnes the type of template.

Parameters:

Template (String) - The name of the template. Do not include the path.

Return value (Integer): 1 - index template (for example Index.xsl), 2 - record template (for example Album.xsl), 3 - recordset list template (for example AlbumList.xsl), or -1 - not a template.