How do you create an object?

This operation is frequently known as "Creating an INSTANCE of an OBJECT." Yes, this is just one more buzz-word -- but you'll hear it frequently.

In order to create an object, you first need an OBJECT VARIABLE. This object variable can be located most anywhere in your program, and have any scope: LOCAL, GLOBAL, THREADED, etc. This object variable is declared by using the name of the interface you wish to access on the object. This is done so that PowerBASIC knows which Methods can be called via this variable. This variable is expected to be a "container" for an OBJECT REFERENCE (that is, a pointer to the actual object). Initially, this variable is automatically set to "NOTHING". If you wish to use the generic DISPATCH interface to access the object, you would use the name IDISPATCH instead.

LOCAL object1 AS MyInterface
LOCAL object2 AS IDISPATCH

There is actually one more special case, that of an IDBIND DISPATCH interface. Since object creation works the same on those interfaces, as well, we'll have more on that special topic in a later section. So, now that you have two empty object variables, what do you do with them? Use the assignment statement (LET) to create an object!

To create an object, you need to specify a CLASS and an INTERFACE. The interface is implied by the object variable you use, so it only remains that you specify the CLASS name. If the requested CLASS is internal to your program, use the word CLASS:

LET object1 = CLASS "MyClass"

The class name ("MyClass") must be specified as a quoted string literal, which is the name of a class implemented within the program. Since the class is internal (the name is known at compile-time), you may not use a string variable or expression. Upon execution, a new object is created, and a reference to that object is assigned to the object variable object1. The interface requested is determined by the original declaration of object1. If the interface name is DISPATCH, you can call the methods with the OBJECT statement -- otherwise, regular Method and Property references are used for direct interfaces.

LET objvar = NEWCOM PROGID$
LET objvar = GETCOM PROGID$
LET objvar = ANYCOM PROGID$

This form of the LET statement is used to obtain an object reference external to the program using the COM facilities of Windows. If the requested object is in a DLL (an in-process server), you will always use the NEWCOM option, as you're asking Windows to supply a new object. If the request is successful, an OBJECT REFERENCE (a pointer to the object) is assigned to the objvar.

If the requested object is in an EXE (out-of-process server), you may use any of the three options. If the director word NEWCOM is specified, a new instance of a COM application is created. With GETCOM, an interface will be opened on an existing, running application, which has been registered as the active automation object for its class. With ANYCOM, the compiler will first try to use an existing, running application if available, or a new instance if not.

Of course, as with any other LET (assignment) statement, you are free to simply omit the word LET entirely.

If an object creation or assignment fails for any reason, the object variable is set to NOTHING. If this statement fails, no errors are generated, nor is an OBJRESULT set. You should test for success of the operation with ISOBJECT(objvar) before trying to use the object or execute its methods.

But what about the rare case when there's no ProgID$ available? There's an answer for that, too.

LET objvar = NEWCOM CLSID ClassID$
LET objvar = GETCOM CLSID ClassID$
LET objvar = ANYCOM CLSID ClassID$

This new form also obtains a COM object reference, just as in the previous example. However, it is only used in the unusual case of a COM Object which has no ProgID. It works exactly as the original form above, except that it describes the requested object by its 16-byte GUID which is the ClassID of the object.

LET objvar = NEWCOM CLSID ClassID$ LIB DLLPath$

PowerBASIC offers the unique ability to create and reference COM objects without any reference to the registry at all. As long as you know the CLSID (Class ID) and the file path/name of the DLL to be accessed, you can do so with no registry access at all. You don't need a special type of COM server. This technique can be used with any server, whether created by PowerBASIC or another compiler. By using this method of object creation, there is simply no need for the server to be registered at all. That allows you to keep local copies of the COM servers you use, with no chance they will be altered or replaced by another application. You use the above form, where the clause "CLSID ClassID$" identifies the 16-byte Class ID, and the clause "LIB DllPath$" identifies the file path and file name of the COM Server. Once you've obtained the COM object reference in objvar, it is used exactly as you would with a traditional object.