SASWorkspaceManager Interfaces

The figure below shows the relationship of the interfaces provided with the Workspace Manager.

As the figure shows, the principal interfaces of the SASWorkspaceManager are as follows:

• IWorkspaceManager

  The IWorkspaceManager interface is the top level interface. It provides collection methods for ServerDefs, LoginDefs, LogicalNameDefs, SAS Workspaces and WorkspacePools.

• IWorkspaces

  This interface is used to create, enumerate, locate, and remove running SAS Workspace instances. The only SAS Workspaces that can be manipulated through IWorkspaces are those which are created from IWorkspaces.

• ILoginDef

  This interface allows you to create and manipulate login definitions (LoginDefs). A loginDef is only needed for connections using the IOM Bridge for COM. SSPI, the default NT security, is used for COM/DCOM connections.

• ILoginDefs

  ILoginDefs contains the standard collection methods Count, _NewEnum, Add, Item, and Remove where the key is the loginDefName. It also supports one additional method: CheckAccess.

• IServerDef

  The workspace manager uses the server def to determine how to connect to the server. For a local or dcom server, only the Name and Hostname values need be filled out. The IOM Bridge for Com requires Protocol to be set to ProtocolBridge; Port and ServiceName may be used with the IOM Bridge for COM.

• IServerDefs

  IServerDefs contains the standard collection methods Count, _NewEnum, Add, Item, and Remove where the key is the serverDefName. It also supports one additional method: CheckAccess.

• IWorkspacePools

  This interface is used to create, enumerate, locate, and remove WorkspacePool objects.

• IWorkspacePool

  This interface is used to configure parameters for a WorkspacePool.

• IPooledWorkspace

  This interface is used to notify a pool when the associated SAS workspace can be returned to the pool.

Creating a Workspace

The reference documentation for using the SASWorkspaceManager interfaces is shipped with the Workspace Manager as online help in .chm format. The following descriptions provide usage information for two commonly used methods:

• CreateWorkspaceByLogicalName
• CreateWorkspaceByServer

CreateWorkspaceByLogicalName

This method creates a SAS Workspace from a logical name definition. The signature for this method is shown below:

   CreateWorkspaceByLogicalName([in]BSTR name,
      [in] enum Visibility visibility, [in]BSTR logicalName,
      [in]BSTR referenceDN, [out]BSTR *xmlInfo, [out, retval]IWorkspace
      **newWorkspace)

The invocation of this method results in the following sequence of steps to create the new workspace:

1. Create a list of all ServerDefs that define the provided logicalName

2. Select the first serverDef in the list (Note that the first may vary depending on the LDAP server.)

3. Locate a LoginDef that matches both the DomainName (from the ServerDef) and the provided referenceDN

4. Attempt to create a connection, once for each MachineDNSName in the serverDef, adding the results (either success or failure) into the xmlInfo.

5. If a connection to SAS could not be established, the next serverDef is tried and the process is repeated from step 3

6. If no Workspace has been created after going through all the hostnames in each serverDef and all the serverDefs that match the given logicalName, an error is returned (SEE_XML). Also, the table of connectionAttempts is returned in Err.Description (and if IWorkspaces.UseXMLInErrorInfo is true).

7. If a Workspace is created, the IWorkspace is added to an internal list in the WorkspaceManager. In this case, the errorString will still show all failed attempts, if any.

The name that is passed to the method can be used in other IWorkspaces methods to determine which workspace to locate or remove. The name is also set on IWorkspace->Name before this method returns. The SAS Workspace Manager does not ever look at IWorkspace->Name, so a client could change the name after calling Create. The xmlInfo is only defined when this method returns an IWorkspace. See Error Reporting for details.

Note that the WorkspaceManager should be notified when a Workspace is no longer in use, so the workspace can be removed from the internal list, and so the reference the WorkspaceManager holds on the Workspace can be released.

CreateWorkspaceByServer

This method creates a workspace from a ServerDef object instead of a logical name. It also accepts the actual userName and password instead of a reference to a LoginDef. This method is preferred over CreateWorkspaceByLogicalName since it does not require username/password pairs to be written to a file or a network directory.

The signature for this method is shown below:

   CreateWorkspaceByServer([in]BSTR workspaceName, [in] enum
      SASWorkspaceManagerVisibility visibility, [in]IServerDef *serverDef,
      [in]BSTR userName, [in]BSTR password, [out]BSTR *xmlInfo, 
      [out, retval]IWorkspace **newWorkspace)

This method attempts to connect to each of the hosts listed in the provided serverDef, one at a time, until either a successful connection is made or all hosts have failed.  The userName/password is not required for serverDefs that specify ProtocolCom.