Creating an Object

Object Factory Classes

The object manager uses the ObjectFactory and ObjectFactoryMulti2 classes to create objects. These classes contain the same components, but ObjectFactory is a singleton object and ObjectFactoryMulti2 is not a singleton object. A process can use only one instance of a singleton object at a time.

If you are using pooling, then the ObjectFactory class is recommended. If you are not using pooling, then the ObjectFactoryMulti2 class is recommended.

The CreateObjectByLogicalName and CreateObjectByServer methods are available from both of the object factory classes.

CreateObjectByLogicalName Method

This method creates a SAS object from a logical name. When you use CreateObjectByLogicalName, you must define metadata for your connections. Each connection should have a logical name associated with it. You can then use the logical name to make a connection. This technique enables you to change the machines where SAS is running without modifying your code.

Here is the signature for this method:

Set obSAS = obObjectFactory.CreateObjectByLogicalName(Name,
Synchronous, LogicalName, LoginReference)

CreateObjectByLogicalName requires the following parameters:

Name

specifies the name that will be associated with the object. The name can be useful when your program is creating several objects and must later distinguish among them.

Synchronous

indicates whether a connection is synchronous or asynchronous. The synchronous connection (TRUE) is most frequently used and is the simplest connection to create. If this parameter equals TRUE, then CreateObjectByLogicalName does not return until a connection is made. If this parameter equals FALSE, then the caller must get the created object from the ObjectKeeper.

LogicalName

provides the logical name that is associated with the server. The logical name that you specify must match the server's logical name that is defined on the metadata server.

LoginReference

specifies a reference to an identity object on the metadata server. If you specify a null value for LoginReference, then a value is retrieved from the metadata server based on your current connection to the metadata server. In most cases, you should use a null value. If you are using a COM or DCOM server connection, then the Windows integrated security is used and this parameter is ignored. If you are using an IOM Bridge connection, then the login reference is looked up on the metadata server in order to find the matching login object, which defines the user name and password to use. The lookup is performed based on the authentication domain of the server. A user can have different logins for different security domains. The login reference is an object ID that points to an identity. You associate the identity with one or more login objects, but each identity can have only one login for each domain.

The CreateObjectByLogicalName method creates a new object by performing the following steps:

Creates a list of all ServerDefs that define the provided logical name.
Selects the first ServerDef in the list. (The first definition can vary depending on the metadata server.)
Locates a LoginDef that matches both the DomainName (from the ServerDef) and the provided LoginReference.
Attempts to create a connection for each MachineDNSName in the ServerDef, until a successful connection is made. The results are recorded in the log.

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 object has been created after going through all the host names in each ServerDef and all the ServerDefs that match the logical name, then an error is returned. Use the GetCreationLog method to check for errors. For more details, see SAS Object Manager Error Reporting .

If an object is created and the value for the Synchronous parameter is FALSE, then the new interface is added to the object keeper.

The name that is passed to the method can be used in other IObjectKeeper methods to determine which object to locate or remove. The name is also set on IObjectKeeper->Name before this method returns. The SAS Object Manager never looks at IObjectKeeper->Name, so a client could change the name after calling Create. The xmlInfo is defined only when this method returns an IObjectKeeper. For more information, see SAS Object Manager Error Reporting .

Note: The object keeper should be notified when an object is no longer in use (using the RemoveObject method) if the object was created with an asynchronous connection or if the object was explicitly added to the object keeper (by using the AddObject method).

The following example creates a workspace object that is named TestWorkspace by using the logical name Test Server. The null loginReference indicates that the identity that is associated with the current metadata server login is used to find a Login object.

Dim obObjectFactory As New SASObjectManager.ObjectFactory
Dim obSAS As SAS.Workspace
' This assumes that either your metadata configuration files are stored in
' the default location, or that the location of your metadata configuration
' files is stored in the registry. If this is not the case, you can specify
' the location of your configuration files by calling
' obObjectFactory.SetMetadataFile(systemFile, userFile, false)
Set obSAS = obObjectFactory.CreateObjectByLogicalName(
"TestWorkspace", True, "Test Server", "")

CreateObjectByServer Method

This method creates an object from a ServerDef object instead of a logical name. It also accepts the actual user ID and password instead of a login reference.

Here is the signature for this method:

Set obSAS = obObjectFactory.CreateObjectByServer("Name", Synchronous,
obServerDef, "Username", "Password")

The CreateObjectByServer method requires the following parameters:

Name

specifies the name that will be associated with the object. The name can be useful when your program is creating several objects and must later distinguish among them.

Synchronous

indicates whether a connection is synchronous or asynchronous. The synchronous connection is most frequently used and is the simplest connection to create. If this parameter equals TRUE, CreateObjectByServer does not return until a connection is made. If this parameter equals FALSE, the function returns a null value immediately. When a connection is made, the object is stored in the ObjectKeeper.

obServerDef

specifies a Server Definition object.

Username

specifies the user name that will be used for authentication on the server.

Password

specifies the password that will be used for authentication on the server.

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 and Password parameters are not required for ServerDefs that use the COM protocol.

The following example creates a new workspace object named TestWorkspace:

Dim obObjectFactory As New SASObjectManager.ObjectFactory
Dim obSAS As SAS.Workspace
Dim obServer As New SASObjectManager.ServerDef
obServer.MachineDNSName = "RemoteMachine.company.com"
obServer.Protocol = ProtocolBridge
obServer.Port = 8591
Set obSAS = obObjectFactory.CreateObjectByServer("TestWorkspace", True,
obServer, "myUserName", "myPassword")