The reference documentation for using the SAS Object Manager interfaces is shipped with the SAS Object Manager as online Help in the sasoman.chm file. The following descriptions provide usage information for two commonly used methods:

CreateObjectByLogicalName
CreateObjectByServer

CreateObjectByLogicalName

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 LogicalName associated with it. You can then use the LogicalName to make a connection. This technique allows you to change the machine(s) where SAS is running without modifying your code.

The signature for this method is shown below:

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

CreateObjectByLogicalName takes 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, CreateObjectByLogicalName does not return until a connection is made. If this parameter equals FALSE, the caller must get the created object from the ObjectKeeper.

LogicalName

provides the LogicalName associated with the connection to the server.

LoginReference

provides the user name and password. If you are using a COM/DCOM server connection, the Windows integrated security is used and this parameter is ignored. If you are using an IOM Bridge connection, the LoginReference is looked up on the metadata server in order to find the matching Login object which defines the username and password to use. The lookup is performed based on the domain specified on the server that is defined for the LogicalName. This mechanism allows a given user to have different logins for different security domains.

If you are using the SAS Metadata Server, the LoginReference is an object ID that points to an identity. You associate the identity with one or more Login objects; but a given identity can only have one login for a given domain. If you specify a null value for LoginReference, 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. For information about administering logins on the SAS Metadata Server, see the SAS Integration Technologies: Server Administrator's Guide.

If you are using LDAP, the LoginReference matches the ReferenceDN defined on login objects in LDAP. You can associate the same ReferenceDN with multiple Logins but the combination of a ReferenceDN and domain resolves to a unique object. For information about administering logins in LDAP, see the SAS Integration Technologies: Administrator's Guide (LDAP Version).

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

Create a list of all ServerDefs that define the provided LogicalName.
Select the first ServerDef in the list. (Note that the first definition can vary depending on the metadata server.)
Locate a LoginDef that matches both the DomainName (from the ServerDef) and the provided LoginReference.
Attempt 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, the next ServerDef is tried and the process is repeated from step 3.
If no object 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. Use the GetCreationLog method to check for errors. For more details, see SAS Object Manager Error Reporting.
If an object is created and Synchronous was passed in as FALSE, 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 only defined when this method returns an IObjectKeeper. See SAS Object Manager Error Reporting for details.

Note that 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 (using the AddObject method).

Example: Creating an Object with CreateObjectByLogicalName

The following example creates a Workspace object named TestWorkspace using the logical name Test Server. The null loginReference indicates that the identity 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

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 reference to a LoginReference. This method is preferred over CreateObjectByLogicalName because 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:

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

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 specify a ProtocolCom.

Example: Creating an Object with CreateObjectByServer

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")