Using SAS Integration Technologies Pooling

Overview of SAS Integration Technologies Pooling

SAS Integration Technologies pooling uses the SAS Object Manager's implementation as a COM singleton object so that only a single instance of the ObjectFactory component is created in any given process. This mechanism makes the same pools available to all callers in the same process.

Note: You define a pool by a logical name. When using ObjectPools.CreatePoolByLogicalName, a single pool can contain connections from multiple servers and multiple logins. When using ObjectPools.CreatePoolByServer, a pool consists of objects from a single server and a single login.

To implement pooling in your application, perform the following steps:

Create the pool (use CreatePoolByServer or CreatePoolByLogicalName). You need to create the pool one time only, usually when the application is started. If you try to create a pool by using a logical name that has already been used in a pool, then you will receive an error.
Use GetPooledObject to get a PooledObject object from the pool. The PooledObject is a wrapper around the SASObject that is being pooled. This PooledObject wrapper is necessary to notify the pooling code when you are finished using the pooled workspace. When you use pooling, keep a reference to the PooledObject for as long as you keep a reference to the object.
Use the object for processing, such as running a stored process and receiving output from SAS.
Use ReturnToPool to return the PooledObject object to the pool so it can be used again.
Release the object. In Visual Basic, you can release these objects by either letting them go out of scope or by calling set obPooledObject = Nothing.

The pool continues to run until either your process exits or you call Shutdown() on each pool. Releasing your reference to ObjectManager does not release the pool.

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

In an ASP application, you can create a pool in one of these two ways:

in the Application_OnStart callback in the global.asa
in the code that calls to get the PooledObject

When a pool is running, methods and properties are available on the SASObjectManager.ObjectPool object to look at statistics for the pool and to shut down the pool.

Supplying Pooling Parameters Directly in the Source Code

To specify the pooling parameters in the source code, perform the following steps:

Create both a Server object and a Login object.
Fill out the relevant properties.
Pass the objects to ObjectManager.ObjectPools.CreatePoolByServer.

The following properties are used to configure SAS Integration Technologies pooling. You specify some of the properties on the LoginDef object and some of the properties on the ServerDef object.

ServerDef.MaxPerObjectPool

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 property to cap memory leaks or non-scalable resource usage. A value of 0 means to never recycle the processes.

ServerDef.RunForever

specifies whether unallocated connections are allowed to remain alive indefinitely. The value for this property 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.

ServerDef.ShutdownAfter

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.MinSize

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

LoginDef.MinAvail

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

LoginDef.LogicalName

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

For more information about the client-side coding for pooling, see the online Help shipped with the Object Manager.

Administering Pooling

When using a SAS Metadata Server with the SAS Object Manager, you create a pool by specifying a logical name that matches a logical server name on the SAS Metadata Server.

The administrator can associate puddles with the pooled logical server name and administer pooling and puddle parameters by using SAS Management Console. For more information, see the SAS Intelligence Platform: Application Server Administration Guide.

The authentication and authorization checking in SAS Integration Technologies pooling enables you to create a pool that contains connections that have been authenticated using different user IDs. This capability allows 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.

Authentication is performed by using the user ID and password to authenticate a new connection to a SAS Metadata Server. The pool is searched for a puddle whose access group has the authenticated user as a member.

The GetPooledObject method authenticates the user by performing the following steps:

Binds to the SAS Metadata Server by using the credentials that are provided to GetPooledObject.
If that bind fails, then GetPooledObject returns an error. If that bind is successful, then it is released and is not used. The bind is connected only to authenticate the credentials. Authorization is then performed against the set of identities in the puddle:
- If a match is not found, then ERROR_ACCESS_DENIED is returned (0x80004005).
- Otherwise, a pooled object is returned when one becomes available.

Pooling authentication enables credentials to be used by people who do not have permission to read the credentials directly.