sp_OACreate
Creates an instance of the OLE object on an instance of Microsoft® SQL Server™.
Syntax
sp_OACreate progid, | clsid,
objecttoken OUTPUT
[ , context ]
Arguments
progid
Is the programmatic identifier (ProgID) of the OLE object to create. This character string describes the class of the OLE object and has the form:
'OLEComponent.Object'
OLEComponent is the component name of the OLE Automation server, and Object is the name of the OLE object. The specified OLE object must be valid and must support the IDispatch interface.
For example, SQLDMO.SQLServer is the ProgID of the SQL-DMO SQLServer object. SQL-DMO has a component name of SQLDMO, the SQLServer object is valid, and (like all SQL-DMO objects) the SQLServer object supports IDispatch.
clsid
Is the class identifier (CLSID) of the OLE object to create. This character string describes the class of the OLE object and has the form:
'{nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}'
The specified OLE object must be valid and must support the IDispatch interface.
For example, {00026BA1-0000-0000-C000-000000000046} is the CLSID of the SQL-DMO SQLServer object.
objecttoken OUTPUT
Is the returned object token, and must be a local variable of data type int. This object token identifies the created OLE object and is used in calls to the other OLE Automation stored procedures.
context
Specifies the execution context in which the newly created OLE object runs. If specified, this value must be one of the following:
1 = In-process (.dll) OLE server only
4 = Local (.exe) OLE server only
5 = Both in-process and local OLE server allowed
If not specified, the default value is 5. This value is passed as the dwClsContext parameter of the call to CoCreateInstance.
If an in-process OLE server is allowed (by using a context value of 1 or 5 or by not specifying a context value), it has access to memory and other resources owned by SQL Server. An in-process OLE server may damage SQL Server memory or resources and cause unpredictable results, such as a SQL Server access violation.
When you specify a context value of 4, a local OLE server does not have access to any SQL Server resources, and it cannot damage SQL Server memory or resources.
Note The parameters for this stored procedure are specified by position, not by name.
Return Code Values
0 (success) or a nonzero number (failure) that is the integer value of the HRESULT returned by the OLE Automation object.
For more information about HRESULT Return Codes, see OLE Automation Return Codes and Error Information.
Remarks
The created OLE object is automatically destroyed at the end of the Transact-SQL statement batch.
Permissions
Only members of the sysadmin fixed server role can execute sp_OACreate.
Examples
A. Use Prog ID
This example creates a SQL-DMO SQLServer object by using its ProgID.
DECLARE @object int
DECLARE @hr int
DECLARE @src varchar(255), @desc varchar(255)
EXEC @hr = sp_OACreate 'SQLDMO.SQLServer', @object OUT
IF @hr <> 0
BEGIN
EXEC sp_OAGetErrorInfo @object, @src OUT, @desc OUT
SELECT hr=convert(varbinary(4),@hr), Source=@src, Description=@desc
RETURN
END
B. Use CLSID
This example creates a SQL-DMO SQLServer object by using its CLSID.
DECLARE @object int
DECLARE @hr int
DECLARE @src varchar(255), @desc varchar(255)
EXEC @hr = sp_OACreate '{00026BA1-0000-0000-C000-000000000046}',
@object OUT
IF @hr <> 0
BEGIN
EXEC sp_OAGetErrorInfo @object, @src OUT, @desc OUT
SELECT hr=convert(varbinary(4),@hr), Source=@src, Description=@desc
RETURN
END
See Also
Data Type Conversions Using OLE Automation Stored Procedures
How to create an OLE Automation object (Transact-SQL)