|
Purpose |
Assign a Dispatch Interface reference to an object variable in preparation to use a COM interface. SET has been superceded by the LET statement, although SET remains supported for a limited period. Existing code should be converted to the new syntax as soon as possible. Simply remove the keyword SET from your source code. |
|
Syntax |
SET objvar = [NEW] [DISPATCH | interfacename] IN ProgramID$ SET objvar = objvar SET vrntvar = objvar SET objvar = vrntvar SET objvar = NOTHING |
|
Remarks |
The five forms of the SET statement operate as follows: SET objvar = [NEW] [DISPATCH | interfacename] IN ProgramID$ Creates a reference to a Dispatch Interface of a named COM object, using either early-binding or late-binding. |
|
NEW |
If the NEW keyword is used, SET creates a new instance of the COM server object and assigns the reference to the object variable objvar. Without the NEW keyword, SET creates an Interface to an existing instance (initialized and running) COM server application, and assigns the reference to the object variable objvar. |
|
DISPATCH |
If the DISPATCH keyword is used, the reference is late-bound to the default or primary Dispatch Interface of the object. Object variable objvar must be a DISPATCH variable. Late-binding is less efficient than early-binding. |
|
interfacename |
If the Interface name is provided, the reference will be early-bound to the named Dispatch Interface of the object. objvar must be dimensioned as an object variable of that Interface name (DIM objvar AS interfacename). Early-binding requires a declaration of the Interface with an INTERFACE/END INTERFACE block. |
|
ProgramID$ |
ProgramID$ specifies the registered object name, for example, "Word.Application.8". ProgramID$ is not case-sensitive and may be a string variable, string literal or string equate. In all cases, once the object reference has been established in objvar, the object's Interface can be accessed using the OBJECT statement; however, if the Interface cannot be opened (for example, if the Dispatch Interface is not supported in ProgramID$), the object variable objvar is set to NOTHING. You can test for success or failure with the ISOBJECT or ISNOTHING functions. SET objvar1 = objvar2 Provided both variables have been dimensioned as DISPATCH object variables, an object copy is created. Success or failure of the operation can be confirmed with the ISOBJECT or ISNOTHING functions. SET vrntvar = objvar2 Attempts to open an IDispatch Interface, else an IUnknown Interface, on the object of objvar. If successful, SET assigns the reference to the Variant variable vrntvar. Variant variables cannot contain references to custom interfaces, only IDispatch or IUnknown Interfaces. If the assignment is successful, VARIANTVT(vrntvar) will return either %VT_UNKNOWN or %VT_DISPATCH. If it is unsuccessful, vrntvar is set to %VT_EMPTY. SET objvar = vrntvar Opens an interface of the appropriate class for objvar on the object of vrntvar, and assigns that Interface reference to objvar. vrntvar must contain a reference to an object of type %VT_UNKNOWN or %VT_DISPATCH or the operation is ignored. If the desired interface cannot be opened, the object variable objvar is set to NOTHING. Success or failure of the operation can be confirmed with the ISOBJECT or ISNOTHING functions. SET objvar = NOTHING Destroys an object variable. Once all variables that reference an object are destroyed, the object itself is destroyed automatically. |
|
Restrictions |
Run-time errors during the execution of the SET statement are not reflected in the ERR system variable. Rather, success or failure of the SET statement can be tested with the ISOBJECT or ISNOTHING functions. The VARIANTVT function can be used to test the content of a Variant variable. Other operations on variant variables can be performed with the LET statement. |
|
See also |
DIM, CLSID$, GUID$, GUIDTXT$, INTERFACE/END INTERFACE, ISNOTHING, ISOBJECT, LET, OBJECT, OBJACTIVE, OBJPTR, OBJRESULT, PROGID$, RESET |
|
Example |
' Reference an existing instance of MSWORD. If there is no existing instance, ' we try to create a new instance and reference that. TRY DIM oWordApp AS WordApplication SET oWordApp = WordApplication IN "Word.Application" IF ISFALSE ISOBJECT(oWordApp) THEN ERROR 5 CATCH SET oWordApp = NEW WordApplication IN "Word.Application" IF ISFALSE ISOBJECT(oWordApp) THEN ' MSWORD COM Server not installed? EXIT FUNCTION END IF END TRY
' Obtain an interface from an interface member method, ' and assign it to a new object variable DIM oWordDoc AS WordDocument DIM vVnt AS VARIANT ERRCLEAR vVnt = 0 OBJECT CALL oWordApp.Documents.Add TO vVnt IF OBJRESULT OR ERR THEN EXIT FUNCTION ' failed SET oWordDoc = vVnt ' Assign the interface |