LET statement (with Objects)

Purpose

Assign an object reference to an object variable.

Syntax

[LET] objvar = object expression

Remarks

The LET Statement, and its implied form (without using the word LET), may be used to assign an object reference to an object variable.  After you declare an object variable as a particular interface, you must create an object and or assign an object reference to it before you can use the objects members (methods, properties, etc.).

If an object creation or assignment fails for any reason, the objvar 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.

LET objvar = CLASS ClassName$

The term ClassName 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 objvar.  The interface requested is determined by the original declaration of objvar.  If InterfaceName is DISPATCH, you can reference it with the OBJECT statement -- otherwise, regular Method and Property references are used.

LET objvar = NEWCOM PrgID$
LET objvar = GETCOM PrgID$
LET objvar = ANYCOM PrgID$

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 (in-process server), you will always use the NEWCOM option, as you're asking for a new object.  If the request is successful, the object reference 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.

The string expression ProID$ evaluates to a ProgID name on an external COM server.  If the InterfaceName is DISPATCH, you can reference it with the OBJECT statement -- otherwise, regular Method and Property references are used instead.

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

This form also obtains a COM object, just as the examples in the above section.  There is always a one-to-one relationship between a ProgID and a CLSID (Class ID).  An object can be identified by either of these tokens, as long as they are both available.  In some instances, you may encounter an object which has no ProgID published. You can substitute the clause "CLSID ClassID$" for the PrgID$.  It works exactly as the usual form above, except that it describes the requested object by its 16-byte GUID which is the CLSID (Class ID) 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.

LET objvar1 = objvar2

If both object variables have been declared as the same object type (the same interface name), the source variable (objvar2) is copied to the destination variable (objvar1), and the reference count of the object is incremented.  If the object variables are of different object types, a new interface (of the type implied by objvar1) is opened on objvar2, and a reference to it is assigned to objvar1.

LET objvar = objmethod(params)

It is assumed that the METHOD or GET PROPERTY specified by objmethod returns an object of the type of objvar.  The objmethod is evaluated, and the object reference which it returns is assigned to objvar.

LET objvar = ME

This form may only be used within a METHOD or PROPERTY.  A new interface (of the type implied by objvar) is opened on the current object, and a reference to it is assigned to objvar.

LET objvar = NOTHING

This destroys an object variable, discontinuing its association with a specific object.  This in turn releases all system and memory resources associated with the object when no more object variables refer to it.

LET objvar = vrnt

Attempts to open an interface of the specified class for objvar on the object of vrnt, and assigns a reference to objvar.  It assumes that vrnt contains a reference to an object of type %VT_UNKNOWN or %VT_DISPATCH.  If the desired interface can not be opened, the object variable objvar is set to NOTHING.

LET vrnt = objvar

This may be used to assign an object reference from an object variable to a variant variable.  It attempts to open an IDispatch interface, else an IUnknown interface on the object of objvar, and assigns that reference to vrnt.  Variant variables can not contain references to custom interfaces, only IDispatch or IUnknown.  If the assignment is successful, VARIANTVT(vrnt) will return either %VT_UNKNOWN or %VT_DISPATCH.  If it is unsuccessful, vrnt is set to %VT_EMPTY.

See also

LET, LET (with Variants), LET (with Types), INTERFACE (Direct), INTERFACE (IDBind), ISINTERFACE,ISNOTHING, ISOBJECT, Just what is COM?, ME, OBJECT, What is an object, anyway?