ObjectStore Active Toolkit Reference

Chapter 2

ATK ActiveX Server

Introduction
ATK is an OLE Automation Server. You can create ActiveX objects to open and inspect databases on local and remote hosts. You can also integrate ATK with OSAX to modify a database, and gather information from ATK ActiveX error codes.

In this chapter
This chapter presents the following topics:

What Is the ATK ActiveX Server?

 The ATK ActiveX server is ATK OLE Automation component that exposes the ATK object model to any ActiveX client programming environment. (These include Active Server Pages, Visual Basic, VBscript, Visual C++, Java, Visual J++, and JavaScript.)

Using the ATK Active X server

You can use the ATK ActiveX server to access and customize the tabular data views you define in Inspector. For a detailed description of the ATK object model, refer to Chapter 5, ATK Object Model.

You can also navigate among persistent objects in an ObjectStore database or retrieve information about the database schema. The ATK ActiveX server supports the OLE Multithreaded Apartment (MTA) model architecture. For more information about threading models, refer to the Microsoft Knowledge Base (http://support.microsoft.com/support/).

The ATK ActiveX server is distributed as a DLL (for in-proc use), and as an executable (for simplified out-of-proc use).

Examples
For examples of applications that use the ATK ActiveX server, refer to Chapter 2, Accessing ATK ActiveX Server from ASP Applications, in the ObjectStore Active Toolkit Tutorial.

Accessing the ActiveX Server Using DCOM

The Distributed Component Object Model (DCOM) underlying ATK allows instances of ActiveX objects to be located and accessed remotely from the ActiveX server. Thus, an application can access the ATK ActiveX server running on a remote machine to open and inspect a remote database.

The DCOM protocol is essential for developing ActiveX controls that run on remote workstations and that access one or more ATK ActiveX servers. The grid control that is distributed with ATK can connect to remote ATK servers using DCOM.

To create an object that will run on a remote ATK ActiveX server, use CoCreateInstanceEx instead of CoCreateInstance and specify the host on which the ATK ActiveX server is running.

For more information
For detailed information about DCOM, refer to the Microsoft documentation. For an example of an application that uses DCOM, refer to Chapter 6, Using ATK ActiveX Server from DCOM, in the ObjectStore Active Toolkit Tutorial.

Integrating ATK and OSAX

What is OSAX?
The ObjectStore ActiveX Interface (OSAX) is an interface that complements ATK's access to ObjectStore databases. Using OSAX, you can encapsulate persistent C++ objects inside COM objects and create, read, update, or modify them.

The ATK and OSAX services can function independently of each other, or you can integrate them. When ATK and OSAX are integrated in one application, you can build object representations in OSAX based on ATK objects, and in ATK based on OSAX objects.

From ATK to OSAX
Use the OSAXObjectStore interface to build an OSAX object from an ATKReference object. OSAXObjectstore retrieves the information it needs from the ATK object and builds an IX object representing the persistent instance, in which X is the name of the class.

For example, suppose you have a database whose schema contains the Customer class, and an ATKReference object represents a Customer instance. You have built an OSAX interface on top of your classes, and OSAX provides the CustomerClass and Customer interfaces. Using Visual Basic, you could create a persistent osaxCustomer object:

Dim atkCustomer as IATKReference
Dim ObjectStore as IOSAXObjectStore
...
Dim osaxCustomer as ICustomer
osaxCustomer = ObjectStore.LoadATKReference(CCustomer, 
atkCustomer)
After you created an osaxCustomer object, you could use the methods you exposed in the Customer interface to modify osaxCustomer as necessary.

From OSAX to ATK
Suppose you have a Customer object called osaxCustomer. You could build an ATKReference object representing the osaxCustomer instance by using this Visual Basic code:

Dim atkKernel as IATKKernel
...
Dim atkCustomer as IATKReference
atkCustomer = atkKernel.LoadOSAXObject(osaxCustomer)
Once you create the atkCustomer object, you can use it to access all of the features that ATK offers. For example, you can retrieve the data members in the instance, navigate a relation, build a table based on a collection that the object contains, retrieve information about classes associated with the object, and so on.

Retrieving Error Information

When ATK ActiveX server calls an ATK method and an error occurs, ATK returns an error code. The file \include\atkkernel.h lists all ATK error codes.

You can retrieve extended information about any error. These code samples in Visual Basic, VBScript, and Visual C++ show how to retrieve information about an error that occurs when ATK ActiveX server tries to open a database.

Visual Basic
      On Error GoTo handle_error
      Dim ObjectStore As New ATKKernel
      Dim OSDatabase As ATKDatabase
      Set OSDatabase = ObjectStore.OpenDatabase("mydb.db")
      Exit Sub
handle_error:
      TmpStr = "ATK Error# " & Hex(Err.Number)
      TmpStr = TmpStr & vbCrLf & "Generated by: " & Err.Source
      TmpStr = TmpStr & vbCrLf & "Description: " & Err.Description
      MsgBox TmpStr
VBScript in Active Server Pages
On Error Resume Next
set ATKKernel=Server.CreateObject("ATKKernel.Document")
set ATKDatabase=ATKKernel.OpenDatabase("mydb.db")
if Err.Number <> 0 then
      Response.Write("ATK Error# " & Hex(Err.Number) & "<BR>")
      Response.Write("Generated by: " & Err.Source & "<BR>")
      Response.Write("Description: " & Err.Description & "<BR>")
      Exit Sub
End If
Visual C++
IID_IATKKernel* pATK;

IID_IATKDatabase* pATKdb;
HRESULT hr=pATK->OpenDatabase("mydb.db", &pATKdb);
if(FAILED(hr)) {
      ISupportErrorInfo* pSEI;
      if(SUCCEEDED(
                  pDisp->QueryInterface(IID_ISupportErrorInfo,(LPVOID*)&pSEI) &&
                  pSEI->InterfaceSupportsErrorInfo(IID_IATKKernel)==S_OK))      {
            IErrorInfo* pEI;
            GetErrorInfo(0,&pEI);
            char szBuffer[512];
            BSTR source,description;
            pEI->GetSource(&source);
            pEI->GetDescription(&description);
            wsprintf(szBuffer,"ATK Error# %X\nSource: %S\nDescription: %S",
                  hr,source,description);
            MessageBox(NULL,szBuffer,"Error",MB_OK);
            SysFreeString(source);
            SysFreeString(description);
            pEI->Release();
      }
}



[previous] [next]

Copyright © 1998 Object Design, Inc. All rights reserved.

Updated: 05/11/99 11:35:00