Contents SAS IOM Data Provider Previous Next

Initializing a Data Source Object

A data source object that is instantiated from the SAS IOM Provider encapsulates a particular IOM server. By default, this server is on the local machine where the provider is registered. However, you can connect to a SAS session on any IOM server after you create a workspace interface pointer to that session. The creation of a workspace interface is outside the scope of this document. See documentation on the SAS Workspace Manager for more information.

To initialize a data source object, follow these steps:

  1. instantiate the data source
  2. set properties on the data source
  3. initialize the data source.

Instantiating a Data Source Object

A data source object can be instantiated using the standard COM CoCreateInstance() service. You can resolve the CLSID for the data source using the provider's ProgID, sas.IOMProvider.1.

This code fragment instantiates a data source object by calling CoCreateInstance with the IOM provider's class ID.

  HRESULT          hr = S_OK;
  CLSID            clsid_provider;
  IUnknown *       pDSO = NULL;
  
  //-- Get the CLSID & create an instance of a DSO

  hr = ::CLSIDFromProgID( "sas.IOMProvider.1", &clsid_provider);

  hr = ::CoCreateInstance( clsid_provider, NULL, CLSCTX_INPROC_SERVER, 
        IID_IUnknown, (void **)&pDSO );

Setting Properties on the Data Source Object

The instantiated data source now needs to be associated with a session on a particular IOM server. You can either connect to an existing IOM workspace or request that the provider create one for you.

You can connect to an existing workspace by setting the property DBPROP_SAS_INIT_WORKSPACEID in the property set DBPROPSET_SAS_DBINIT. The property value is set to a workspace interface pointer for an existing SAS session. The workspace interface pointer is created by the SAS Workspace Manager. If you do not set this property, the IOM provider will automatically start a SAS session on the local system where the provider is registered. The following code associates an instantiated data source, pDSO, with an existing SAS session. Assume that pIWorkspace has been created to point to an existing SAS session. 

  IWorkspace *                    pIWorkspace; 
  IDBProperties *                 pIDBProperties;
  
  IDBInitialize *                 pIDBInitialize;
  
  DBPROPSET             rgPropSet[1];
  DBPROP                rgProp[1];
  hr = pDSO->QueryInterface( IID_IDBProperties, (void **) &pIDBProperties);
  
  hr = pDSO->QueryInterface( IID_IDBInitialize, (void ** &pIDBInitialize);
  
  //-- Set property values and initialize the DSO 
  
   rgProp[0].dwPropertyID           = DBPROP_SAS_INIT_WORKSPACE;
   rgProp[0].dwOptions              = DBPROPOPTIONS_REQUIRED;
   rgProp[0].colid                  = DB_NULLID;
   rgProp[0].vValue.vt              = VT_UNKNOWN;
   rgProp[0].vValue.punkVal         = (IUnknown *) pIWorkspace;

   rgPropSet[0].cProperties = 1;

   rgPropSet[0].guidPropertySet = DBPROPSET_SAS_DBINIT;
   rgPropSet[0].rgProperties = rgProp;
   
  hr = pIDBProperties->SetProperties( 1, rgPropSet );
  
  //-- now that properties are set, initialize the DSO:

  hr = pIDBInitialize->Initialize();

Example: specifying connection information

In this scenario, the IOM provider uses an existing IWorkspace interface when communicating with the server. If you don't have a IWorkspace interface pointer, the provider can spawn an object server and create a workspace for its use. The properties from the following list can be used to specify connection information

If DBPROP_INIT_DATASOURCE is set to _LOCAL_, an object server is brought up on your local machine and the data source connects to a workspace that is in that server.

If DBPROP_SAS_INIT_LOGICALNAME is given, it should be a logical entry in your LDAP server that defines an IOM server. DBPROP_AUTH_USERID can be set to a logical user ID, if one is needed in conjunction with the logical name given. The provider will use this information to resolve the actual server address and create a workspace appropriately. In this scenario you can associate a symbolic name with the workspace by setting the DBPROP_INIT_DATASOURCE property to a value that is meaningful to the scenario.

If DBPROP_SAS_INIT_LOGICALNAME is not given, the data source will try to create a workspace in a server named by DBPROP_SAS_INIT_MACHINEDNSNAME. This property value should be set to a string representation of the machine name that you want to connect to (for example, lambchop.unx.sas.com or 135.28.14.7). When you set this property you must also set DBPROP_SAS_INIT_PORT or DBPROP_SAS_INIT_SERVICENAME. These two properties are functionally equivalent; they indicate the port to use on the machine that hosts the server. DBPROP_SAS_INIT_PORT takes a numeric value that represents the port number; DBPROP_SAS_INIT_SERVICENAME takes a logical reference to the port. DBPROP_SAS_INIT_PROTOCOL defines the IOM protocol to use when communicating with the server. This should be either ProtocolCom or ProtocolBridge. (These symbols are defined in the SAS type library.) If a user ID and password are required to connect to the machine specified by DBPROP_SAS_INIT_MACHINEDNSNAME, DBPROP_AUTH_USERID and DBPROP_AUTH_PASSWORD can be set accordingly. You can associate a symbolic name with the workspace by setting the DBPROP_INIT_DATASOURCE property to a value that is meaningful to the situation.

When IDBInitialize::Initialize is called, the IOM provider establishes the connection with the server. After a data source object has been successfully initialized, the consumer can call methods in IDBProperties to query the capabilities of the IOM provider. These capabilities include the interfaces that are exposed and rowset properties, such as the ability to scroll.

You can unintialize a data source component when all components that were created using the data source have been released. It is important to uninitialize and release data source components when you are no longer using them. This will free up resources that are associated with the data source. If your application initializes many data sources but does not release them, you run the risk of unnecessarily constraining system resources and leaving open but unused server connections.

Initializing a Connection Object Using ADO

Initializing a data source object using C++ is equivalent to initializing a connection object using ADO. In ADO, a connection object is established for a particular IOM server. By default, the server is located on the local system where the provider is registered. Connecting to a SAS session requires that you specify a workspace ID on the open method of the connection object. This section illustrates briefly how the SAS Workspace Manager might be used with a workspace ID. For more information on SAS Workspace Manager methods, see  SAS Workspace Manager.

When you use an IOM server on the local machine, specify the provider for the connection object and invoke the open method:

Dim cn As New ADODB.Connection
cn.Provider = "sas.IOMProvider.1"
cn.Open

When you use an existing workspace that is obtained from either CreateWorkspaceByserver or CreateWorkspaceByLogicalName, take the workspace ID and include it in the ADO connection object's open method. Use "SAS Workspace ID = " in the connection string.

The following example uses a workspace ID with the CreateWorkspaceByServer method, which takes as input a SASWorkspaceManager ServerDef object. It then uses the workspace ID to open a connection object.

Dim obSAS As SAS.Workspace
Dim obWM As New SASWorkspaceManager.workspaceManager
Dim oServerDef As New SASWorkspaceManager.serverDef 
Dim xmlstring as string
Dim obConnection As New ADODB.Connection
oServerDef.Protocol = ProtocolCom
oServerDef.MachineDNSName "ESS1"
Set obSAS =    obWM.workspaces.CreateWorkspaceByServer("a", VisibilityProcess, oServerDef,"",
"", "")
obConnection.Open "Provider=sas.IOMProvider.1; SAS Workspace ID= " &
obSAS.UniqueIdentifier

Contents SAS IOM Data Provider Previous Next