Using the Workspace Manager

Workspace Manager Interfaces

The following figure shows the relationship of the interfaces provided with the workspace manager.

[Diagram of the interfaces for the workspace manager]

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

IWorkspaceManager: provides collection methods for ServerDefs, LoginDefs, LogicalNameDefs, SAS Workspaces, and WorkspacePools. IWorkspaceManager is the top level interface.
IWorkspaces: is used to create, enumerate, locate, and remove running workspace instances. The only workspaces that can be manipulated through IWorkspaces are those which are created from IWorkspaces.
ILoginDef: allows you to create and manipulate login definitions (LoginDefs). A loginDef is needed only for connections that use the IOM Bridge for COM. SSPI, the default NT security, is used for COM and DCOM connections.
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: determines 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 can also be used with the IOM Bridge for COM.
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: creates, enumerates, locates, and removes WorkspacePool objects.
IWorkspacePool: configures parameters for a WorkspacePool.
IPooledWorkspace: notifies a pool when the associated workspace can be returned to the pool.

Creating a Workspace

CreateWorkspaceByLogicalName Method

This method creates a SAS Workspace from a logical name definition. Here is the signature for this method:

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

The CreateWorkspaceByLogicalName method creates a new workspace by performing the following steps:

Creates a list of all ServerDefs that define the provided logicalName.
Selects the first serverDef in the list.
Locates a LoginDef that matches both the DomainName (from the ServerDef) and the provided referenceDN.
Attempts to create a connection, once for each MachineDNSName in the serverDef, adding the results (either success or failure) into the xmlInfo.

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

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

If a Workspace is created, then 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 parameter is defined only when this method returns an IWorkspace. For more information, see Error Reporting.

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

CreateWorkspaceByServer Method

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

Here is the signature for this method:

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 user name and password are not required for serverDefs that specify ProtocolCom.

Top of Page