Ole Automation Server

SoftCAT 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.

Class name: SoftCAT.DataServer.

You can choose to either connect to a running instance (of SoftCAT), 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 SoftCAT. CreateOleObject will always create a new instance.

Delphi example:

var
C: Variant;
XMLFile: String;
HTMLFile: String;
begin
C := CreateOleObject(SoftCAT.DataServer');
C.Database := [path to database];
XMLFile := 'C:\My Documents\Data.xml';
// XML file - All apps
C.GenerateXML('Program', '', XMLFile);
HTMLFile := 'C:\My Documents\Doc.html';
// HTML file - Program, ID = 1
C.GenerateHTML('ProgramBrowse.xsl', 'ID=1', False, HTMLFile, '');

// Display the index page in the Explorer window

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

// Display program 100 in the Explorer window

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

// Display all games in the Explorer window

C.Explore('ProgramList.xsl', 'Category=Games');

// Edit program 100

C.EditRecord('Program', 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 SoftCAT version number (for example "4.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 program id of the active program in the Program View, call ActiveRecord('Program'). To get the publisher id of the active publisher in the Publisher Lookup View, call ActiveRecord('Publisher'). 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.

Parameters:

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

OrderBy (String) - The new sort order. For example "Title" or "Publisher,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. You can access this filename after the method has been called.

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 "Category=Games".

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 "Publisher=Microsoft".

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

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: 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.

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.

GenerateXML

Call this method to generate a XML data file.

Parameters:

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

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 "Publisher=Microsoft".

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. You can access this filename after the method has been called.

Return value: 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:Program,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. You can access this filename after the method has been called.

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.

NOTE: You can not call this method if modal window is open (for example a data entry window).

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.

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".

TemplateType

This returnes the type of template.

Parameters:

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

Return value: 1 - index template (for example Index.xsl), 2 - record template (for example Program.xsl) or 3 - recordset list template (for example ProgramList.xsl).