Using Workspace Pooling

Overview of Workspace Pooling with the Workspace Manager

Workspace pooling enables you to create a pool of connections to IOM servers that are shared and reused among multiple client applications. This feature can dramatically reduce connection times in environments where one or more client applications make frequent but brief requests for IOM services. This is typically the case, for example, in Active Server Pages (ASP) applications. Pooling reduces the wait that an application incurs when establishing a connection to SAS and is, therefore, most efficient when used in such applications. A pooled workspace does not offer significant advantages in applications that use workspaces for an extended period of time.

The Workspace Manager supports two different pooling mechanisms: COM+ pooling and SAS Integration Technologies pooling. The most noticeable difference between the two mechanisms is the way in which the pools are administered.

In both COM+ pooling and SAS Integration Technologies pooling, the workspace manager represents a pooled workspace with the PooledWorkspace COM object. This object has a single property: workspace. When PooledWorkspace object is obtained, the calling application keeps a reference to the PooledWorkspace object for as long as it needs to use the workspace. Releasing the PooledWorkspace object returns the connection to the pool and causes the workspace to be cleaned up. It is impossible to make new calls to the workspace after the associated PooledWorkspace is released.

COM+ Pooling

Creating a Pooled Object

To obtain a PooledWorkspace object, creates a new PooledWorkspace object by using COM. The COM+ interceptors detect the new object and manage the pooled objects. The PooledWorkspace object has been written to support the COM+ pooling mechanism.

For an example, see Example Code Using COM+ Pooling .

Administering COM+ Pooling

To administer a COM+ pool, use the COM+ Component Services administrative tool, which is a standard Microsoft Management Console (MMC) plug-in that ships with Windows 2000.

You can configure COM+ pools in these two different ways:

library application — each process has its own pool
server application — the pool is shared by all processes on the same machine

To create a new COM+ server application, perform the following steps:

Start the Component Services administrative tool by selecting StartProgramsAdministrative ToolsComponent Services.
Expand Component ServicesComputerCOM+ Applications. Right-click COM+ Applications and select NewApplication. This starts a wizard. Click Next.
Select Create an Empty Application.
Enter a name of your choice, and select Server application as the Activation Type. Click Next.
Specify an identity, and click Next.
Click Finish.

To add the PooledWorkspace component to the application, perform the following steps:

Expand the application that you previously created in order to see Components and Roles.
Right-click Components and select New Component, which brings up a wizard.
Click Next, and then select Import components that are already registered.
Select SASWorkspaceManager.PooledWorkspace.1, and then click Next and Finish.

To administer the pooling properties, perform the following steps:

Right-click SASWorkspaceManager.PooledWorkspace.1 under the Components node of the application that you created, and select Properties from the pop-up menu.
Select the Activation tab.
Select the Enable object pooling check box. Enter the properties.
(Optional) You can also enter a constructor string, which enables you to specify which machine SAS should run on. For more information, see Constructor Strings .

Constructor Strings

The constructor string is a single string that specifies the parameters that are used to initially create the pool. The workspace manager requires that the constructor string contain a set of name and value pairs, with the names separated from the values by an equal sign (=), and the pairs separated by a semicolon (;). If no parameters are specified, then a pool that consists of SAS servers running on the local machine is created. You should never use quotation marks (") in the constructor string. The constructor string contains the only attributes that are specific to SAS.

If errors occur when creating a workspace, then the workspace manager writes entries to the Event Log.

Constructor Parameters

The following parameters are required when you use a constructor string:

logicalName

specifies which sasServer objects to use when creating objects in the pool.

referenceDN

specifies the login to use for authentication. This parameter is necessary only for an IOM Bridge connection. For the

machineDNSName

specifies the name of the machine to connect to.

protocol

can be either com or bridge.

port

specifies the port number of a server to connect to. This parameter should be specified only for an IOM Bridge connection.

serviceName

used to resolve a TCP/IP service to a port number. This should be specified only for an IOM Bridge connection. Only one of the port or serviceName parameters should be specified.

loginName

specifies the user ID to use when connecting to a SAS server. This should be specified only for an IOM Bridge connection.

password

defines the password that authenticates the loginName. This should be specified only for an IOM Bridge connection.

Here is an example of a valid constructor string:

logicalname=pooltest;protocol=com

SAS Integration Technologies Pooling

Choosing SAS Integration Technologies Pooling

You might choose SAS Integration Technologies pooling instead of COM+ pooling if any of the following are true:

COM+ is not available
you want multiple pools on the same machine
you want to use the security mechanism available in SAS Integration Technologies pooling
you want to use the same administration model for Java applications and COM applications
you want to specify the pooling parameters in the source code

Java applications and COM applications cannot share the same pool, but they can share the administration model used for the pools.

A pool is defined by a logical name. When using WorkspacePools.CreatePoolByLogicalName, a single pool can contain Workspaces from multiple Servers and multiple logins. When using WorkspacePools.CreatePoolByServer, a pool will consist of Workspaces from a single Server and a single Login.

The authentication and authorization checking in SAS Integration Technologies pooling enables you to create a pool that contains SAS Workspaces that have been authenticated by using different user IDs. This capability allowing the access to sensitive data to be controlled on the server machine instead of the middle tier. Checking is performed only in pools that were created with CreatePoolByLogicalName where the checkCredentialsOnEachGet parameter is set to true.

Using SAS Integration Technologies Pooling

The Pooling takes advantage of the WorkspaceManager being a COM singleton object (which means that only a single instance of the WorkspaceManager component is created in any given process). In other words, every time a call to CoCreateInstance (which is what Visual Basic's CreateObject and dim x as New object use) is made in the same process, the same WorkspaceManager object is returned. Therefore, the same pools are available to all callers in the same process.

To create and use a pool of workspaces, perform the following steps:

Create the Pool (use CreatePoolByServer or CreatePoolByLogicalName). This step needs to be performed only once, usually when the application is started. You will get an error if you try to create a pool using a logical name that has already been used in a pool.
Get a PooledWorkspace object from the pool (use GetPooledWorkspace). The PooledWorkspace is really just a wrapper around the SAS.Workspace object that is being pooled. This wrapper is necessary to notify the pooling code when you are finished using the pooled workspace. In pooling, you will want to keep a reference to the pooled workspace for as long as you keep a reference to the workspace.
Use the workspace. For example, you might run a stored process and retrieve the output from SAS.
Release the workspace and the PooledWorkspace. In Visual Basic, you can release these objects by either letting them go out of scope or by calling:
```
set obPooledWorkspace = Nothing
```
The pool will continue to run until either your process exits or you call Shutdown() on each pool. Simply releasing your reference to the WorkspaceManager is not enough.

In an ASP application, there are two ways the pool can be created: in the Application_OnStart callback in the global.asa, or in the code that calls to get the PooledWorkspace. The following code is written in Visual Basic; some changes are needed to write it in VBScript.

Once a pool is running, methods and properties are available on the SASWorkspaceManager.WorkspacePool object to look at statistics about the pool to and shut down the pool.

For an example, see Example Code Using SAS Integration Technologies Pooling .

Administration

Pool parameters can be specified in these two places:

in an LDIF-formatted file. You can edit the file in a text editor. The WorkspaceManager.Scope property must be either ScopeLocal or ScopeUser. The location of the file is determined by WorkspaceManager.FilePath.
in source code. Create both a sasServer object and a sasLogin object, and then fill out the relevant properties. Pass those properties to WorkspaceManager.WorkspacePools.CreatePoolByServer. The following line of code specifies the maximum number of workspaces that can be created in a pool:
```
obServer.MaxPerWorkspacePool = 6
```

The following parameters are used to configure SAS Integration Technologies pooling. The parameters are specified in either the serverDef or loginDef object.

ServerDef.MaxPerWorkspacePool

specifies the maximum number of servers that should be created from the provided ServerDef object. A good starting place for this number is the number of CPUs that are available on the machine that is running SAS.

ServerDef.RecycleActivationLimit

specifies the number of times that a workspace is used before the process that it is running in is replaced. You can use this parameter to cap memory leaks or non-scalable resource usage. A value of 0 means to never recycle the processes.

ServerDef.RunForever

specifies whether unallocated server connections remain alive indefinitely. The value must be either true or false. If the value is false, then unallocated live connections will be disconnected after a period of time (specified by the value of ServerDef.ShutdownAfter). If the value is true (the default value), then unallocated live connections remain alive indefinitely. This property is optional.

ServerDef.ServerShutdownAfter

specifies the number of minutes that an unallocated live connection will wait to be allocated to a user before shutting down. This property is optional, and it is ignored if the value of ServerDef.ServerRunForever is true. The value must not be less than 0, and it must not be greater than 1440 (the number of minutes in a day). The default value is 3. If the value is 0, then a connection returned to a pool by a user is disconnected immediately unless another user is waiting for a connection from the pool.

LoginDef.AllowedClientDN

is a variant property that can contain a single string or an array of strings. The DNs can be specific UserDNs or Groups. This is used to specify who is allowed to access a workspace that is created with the associated user name and password.

LoginDef.MinSize

specifies the minimum number of workspaces using this LoginDef that are created when the pool is created.

LoginDef.MinAvail

specifies the minimum number of available workspaces for this LoginDef. Note that MaxPerWorkspacePool is never be exceeded.

LoginDef.LogicalName

determines which set of LoginDefs in LDAP to use in the Pool. This parameter is used only when a pool is created by using CreatePoolByLogicalName.