Retrieving an Array Object

Internet Security and Acceleration Server 2004/2006 SDK

After the root object is obtained by creating an instance of the FPC object, all the array-level configuration settings defined in the hierarchy of administration COM objects for the ISA Server computers associated with an array can be accessed through the applicable FPCArray object, which is an element of the FPCArrays collection. The way in which an FPCArray object is retrieved depends on the edition of ISA Server that is installed on the computer on which the root object was created and on the components of ISA Server that are installed and running on it.

Standard Edition

In ISA Server 2004 Standard Edition, the FPCArray object provides access to the registry-based configuration settings of only a single ISA Server computer. If the ISA Server services are installed on the computer on which the root object was created, the GetContainingArray method can be called on the root object to retrieve the FPCArray object that represents the array associated with this ISA Server computer, as in the following Visual Basic Scripting Edition (VBScript) code.

 ' Create the root object.
Dim root  ' The FPCLib.FPC root object
Set root = CreateObject("FPC.Root")

Dim isaArray  ' An FPCArray object
Set isaArray = root.GetContainingArray()

The root object can also be created for remote management on a computer on which ISA Server Management is installed and the Microsoft Firewall service is not running. Such a computer is called a remote management computer. In ISA Server 2004 Standard Edition, the Arrays property can be accessed from the root object for calling the Connect method to connect to a specified ISA Server computer and retrieve the FPCArray object for it. After this call succeeds, an application or script can access any property or method in the administration COM hierarchy of objects under the FPCArray object retrieved.

Note  Only computers whose IP addresses are included in the Remote Management Computers computer set of the specified ISA Server computer can access it for remote management, and the user must have permissions to access the ISA Server computer specified. If user credentials are not supplied in the call to Connect, the credentials of the logged-on user are used.

This VBScript subprocedure, which can be called in a script that is run on a remote management computer, receives the name of an ISA Server computer in the parameter passed to it, uses the Connect method to connect to the ISA Server computer specified using the credentials of the logged-on user and to retrieve the FPCArray object for it, and uses the Disconnect method to disconnect from the array.

 Sub ConnectToServer(serverName)

    ' Create the root object.
    Dim root  ' The FPCLib.FPC root object
    Set root = CreateObject("FPC.Root")

    ' Declare the other object needed.
    Dim isaArray  ' An FPCArray object

    ' Connect to the array of the remote ISA Server computer 
    ' specified and retrieve the array object for it.
    Set isaArray = root.Arrays.Connect(serverName)

    ' Add steps to retrieve or set properties.

    ' Disconnect from the array.
    root.Arrays.Disconnect isaArray

End Sub

Multiple ISA Server computers can be administered in a single script or application from the same remote management computer by successively connecting to and disconnecting from the array of each ISA Server computer.

Enterprise Edition

When the root object is created on an array member, which may also be a Configuration Storage server for the array, the ISA Server computer automatically attempts to connect to the Configuration Storage server specified in the registry for the array using the credentials of the logged-on user. If the logged-on user is an enterprise administrator or an enterprise auditor, the GetContainingArray method can be called on the root object to retrieve the FPCArray object that represents the array associated with this ISA Server computer, or the array object for any specified array in the enterprise can be retrieved through the Arrays property of the root object. This property provides access to the FPCArrays collection, which contains the FPCArray objects for all the arrays within the root node.

This VBScript subprocedure, which can be called in a script that is run on a Configuration Storage server or on a computer automatically connected to a Configuration Storage server, receives the name of an array in the parameter passed to it and uses the Item method of the FPCArrays collection to retrieve the specified FPCArray object using the credentials of the logged-on user.

 Sub AccessArray(arrayName)

    ' Create the root object.
    Dim root  ' The FPCLib.FPC root object
    Set root = CreateObject("FPC.Root") 

    ' Declare the other object needed.
    Dim isaArray  ' An FPCArray object

    ' Retrieve the specified array object.
    On Error Resume Next
    Set isaArray = root.Arrays.Item(arrayName)
    If Err.Number <> 0 Then
        WScript.Echo "The specified array was not found."
        Exit Sub
    End If
    On Error GoTo 0

    ' Add steps to retrieve or set properties.

End Sub

If the logged-on user does not have the permissions needed to access information stored on the Configuration Storage server, the ConnectToConfigurationStorageServer method must be called with the credentials of an enterprise administrator or an enterprise auditor to connect to a Configuration Storage server before any array object can be retrieved.

When run on an ISA Server computer, this VBScript subprocedure receives the name of a Configuration Storage server and the credentials of an enterprise administrator in the parameters passed to it, connects to the specified Configuration Storage server using the credentials of the enterprise administrator supplied, retrieves the FPCArray object for the local computer, and disconnects from the Configuration Storage server.

 Sub ConnectToCSS(CSSName, userName, domainName, password)

    ' Create the root object.
    Dim root  ' The FPCLib.FPC root object
    Set root = CreateObject("FPC.Root")

    ' Declare the other object needed.
    Dim isaArray      ' An FPCArray object

    ' Connect to the Configuration Storage server.
    root.ConnectToConfigurationStorageServer CSSName, userName, domainName, password

    ' Retrieve a reference to the array object
    ' for the local ISA Server computer.
    Set isaArray = root.GetContainingArray()

    ' Add steps to retrieve or set properties.

   ' Disconnect from the Configuration Storage server.
   root.DisconnectFromConfigurationStorageServer

End Sub

In ISA Server Enterprise Edition, a remote management computer can create a root object, but it cannot access the properties of the root object or any other object in the administration COM object hierarchy until it connects to a Configuration Storage server in a call to the ConnectToConfigurationStorageServer method on the root object. After this call succeeds, your application or script can access any property or method in the administration COM hierarchy of objects. In particular, the array object for any specified array in the enterprise can be retrieved through the Arrays property of the root object. This property provides access to the FPCArrays collection, which contains the FPCArray objects for all the arrays within the root node.

When run on a remote management computer, this VBScript subprocedure receives the name of a Configuration Storage server and the name of an array in the parameters passed to it, connects to the specified Configuration Storage server using the credentials of the logged-on user, who must be an enterprise administrator or an enterprise auditor, retrieves the FPCArray object for the specified array, and disconnects from the Configuration Storage server.

 Sub ConnectToCSSandArray(CSSName, arrayName)

    ' Create the root object.
    Dim root  ' The FPCLib.FPC root object
    Set root = CreateObject("FPC.Root")

    ' Declare the other object needed.
    Dim isaArray      ' An FPCArray object

    ' Connect to the Configuration Storage server.
    root.ConnectToConfigurationStorageServer CSSName

    ' Retrieve the specified array object.
    On Error Resume Next
    Set isaArray = root.Arrays.Item(arrayName)
    If Err.Number <> 0 Then
        WScript.Echo "The specified array was not found."
        Exit Sub
    End If
    On Error GoTo 0

    ' Add steps to retrieve or set properties.

   ' Disconnect from the Configuration Storage server.
   root.DisconnectFromConfigurationStorageServer

End Sub
Show: