CreateObject Procedure

Creates an instance of a specific class and returns a reference to an COM/ActiveX object.  By providing sHostName the class object can be created on a specific machine. You can also specify the threading model of the apartment the server can run in: either Free or not.

Syntax

[ obObject/sClassName = ] CreateObject ( sClassName [,sHostName] [,bFreeThreadingModel] )

The CreateObject procedure syntax has the following parts:

Where

The sClassName string argument can be one of the following strings:

1. ATEasy Internal Class name, e.g., "AUser"
    

2. After inserting a type library into ATEasy submodule Libraries, its class object in the library can be created with class name or class path of the Type library. For example, insert a MSXML type library:
   
   CreateObject("DOMDocument") - name of a class in the MSXML type library
   CreateObject("System.DOMDocument") - class path - type library loaded in the ATEasy System
   CreateObject("MSXML.DOMDocument") - Type library name following by class name
   CreateObject("System.MSXML.DOMDocument") - path specifying ATEasy module followed by library name
   
   In each case, ATEasy will find the first class object of given search path.
    

3. Program Id(ProgId) that is a registry entry that can be associated with A CLSID.  The format of a ProgId is <Vendor>.<Component>.<Version>, separated by periods and with no spaces, e.g., "Word.Document.6".
   
   Registry Entry:
   HKEY_LOCAL_MACHINE\SOFTWARE\Classes\<ProgID> =
    

   Name	Description
   Vendor	Application name or class name
   Component	Class component/object
   Version	Version of the application or class

4. Version independent program ID that the typically uses the syntax appname.objecttype with these parts:
    

   Name	Description
   appname	The name of the application providing the object.
   objecttype	The type or class of object to create.

The types of return for this procedure are different depending on how you create the object: early bind or late bind. It can be Object data type for late bind and any libraries class name type for early bind.  The following table shows the differences between late bind and early bind:

 

Please refer to COM Objects under Programming Language for further detailed information.

Comments

Every application that supports Automation provides at least one type of object. For example, a word processing application may provide an Application object, a Document object, and a Toolbar object.

To create an ActiveX object, first declare a variable in ATEasy and define its type as Object or as a class name as defined under in a type library classes or controls sub-module. Declaring it as an Object type will cause late binding while declaring the variable's type with a class name will cause ATEasy to use early binding when calling the object's methods or properties.

ob = CreateObject("Excel.Application")

This code starts the application creating the object, in this case, a Microsoft Excel spreadsheet. Once an object is created, you reference it in code using the object variable you defined. In the following example, you access properties and methods of the new object using the object variable, ExcelSheet, and other Microsoft Excel objects, including the Application object and the Cells collection.

' Make Excel visible through the Application object and Add a workbook.

ob.Visible = True

ob.Workbooks.Add()

' Place some text in the first cell of the sheet.

ob.Cells(1, 1).Value = "This is column A, row 1"

' Close Excel with the Quit method on the Application object.

ob.Quit

' Release the object variable.

ob = Nothing

Declaring the variable as an Object data type creates a variable that can contain a reference to any type of object. However, access to the object through that variable is late bound; that is, the binding occurs when your program is run. To create an object variable that results in early binding, that is, binding when the program is compiled, you must insert the object type library below the module libraries submodule, than, declare the object variable with a specific class name as show in the type library controls or classes. For example, after insert the Excel Object library to the module libraries, you can declare as variable xlApp as type Excel.Application, declare the variable xlchart as type Excel.Chart and use them as follows:

xlApp: Excel.Application
xlchart: Excel.Chart

xlapp=CreateObject("Excel.Application")
xlapp.Visible=TRUE
xlapp.Caption="ATEasy Excel Demo"
xlApp.Workbooks.Add()
..
..
xlchart=xlapp.Charts.Add()
..
..
xlapp.Quit()
..
! free objects
xlchart=Nothing
xlapp=Nothing
 

The reference through an early-bound variable can give better performance, and ensure at compile-time that the expression called on the object is valid and the property or method used exist.

You can pass an object returned by the CreateObject function to a function expecting an object as an argument. For example, the following code creates and passes a reference to a Excel.Application object:

MySub(CreateObject("Excel.Application"))

Note: Use CreateObject when there is no current instance of the object. If an instance of the object is already running, a new instance is started, and an object of the specified type is created. To use the current instance, or to start the application and have it load a file, use the GetObject function.

If an object has registered itself as a single-instance object, only one instance of the object is created, no matter how many times CreateObject is executed.

Once the object variable is no longer needed the application must free the object and release it resources as follows:

ob=Nothing

Host Names

all UNC ("\\server" or "server") and DNS names ("domain.com", "example.microsoft.com", or "135.5.33.19") names are allowed.

COM Object Threading Model

The threading model of the apartment the server can run in is specified in the registry under each class id:

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\{CLSID}\ThreadingModel = <threading model>

ATEasy default is Apartment (Single-threaded apartment) and the default should work most of times. However in some rare situation a TRUE must be passed, forcing ATEasy to use MTA (Multithreaded Apartment) thread to create MTA object.

Example

The following statement creates an instance of given class id on a specific machine of given IP Address:

ob=CreateObject("{2154c700-9253-11d1-a3ac-0aa0044eb5f}", "207.46.131.137")

if ob=Nothing

     error -1, "unable to create object …"

endif

ob.Open()

ob.Mode=3

ob.Write("abc")

ob=Nothing

See Also

GetObject, Nothing, Object, Creating Objects, Early Binding and Late Binding